YippeeXuXu/dsh-collab-mode

让 Agent 协作可批准、可冻结、可复核。

中文 · English

DSH 协作模式 v4.3 r2.1

安装 · 使用 · 原理 · English

这是什么

dsh-collab-mode 是 DSH（DeepSeek Harness）的 Agent preset：把容易失控的 AI 协作，收敛成一条可追踪的轻量状态机。它用双停点批准明确“做什么”和“怎么做”，用不可移动的候选引用冻结交付，再交给全新上下文的 Reviewer 独立审查；任何一步不满足条件，就停止或回到批准边界内返工，而不是凭对话惯性继续推进。

演进历程

这套模式不是一次设计出来的，而是 2026 年 6 月起十次实战迭代的结果——从三个 CLI 窗口之间人工复制粘贴 prompt，到今天 DSH 里的自动化子 Agent 派发：

| 阶段 | 时间 | 形态 | 关键教训 |
|---|---|---|---|
| 纸面规则 | 6 月初–8/4 | v2.1 → v3.1 规则文档迭代：三窗口分责、强制落盘、子 Agent 辩论 | 没有机制约束的规则会被「顺手」打破 |
| CLI 互调 | 8/4–8/8 | 三个 CLI（Claude / Codex / Kimi）互相调用，人工复制粘贴 prompt 传递任务 | 人工传递可靠但费人；自动化编排器始终没接真实 CLI |
| 硬闸实验 | 8/8–8/11 | 自研 planner_gate：1747 行闸门 + 1127 行自测、逐文件批准账本、hash 防篡改 | 机制倒挂：闸门比业务重，真实试跑从未开始，4 天即弃 |
| 回归轻量 | 8/11 | 只留两停点 + 简单/复杂分支，安全边界交还宿主 sandbox | 确认应发生在计划级，而不是文件级 |
| CLI 跨端互派 | 8/13 | cross-terminal-dispatch：三端 CLI 命令互派，审查跨端派给不同模型 | 跨端的价值是异构审查，不让同一模型自圆其说 |
| DSH preset 化 | 8/14 | v4.0 迁入 DSH 用户级 preset：角色书内嵌 persona、16 技能、7 派发实例 | 规则从文档约定变成宿主可调用的真实工具 |
| v4.1–v4.3 硬化 | 8/15–8/17 | 治理状态机、常驻内核、对抗审查、候选冻结与内容寻址 | 状态要有唯一真源，批准要绑定版本与内容摘要 |
| R2 动态路由 | 8 月下旬 | 共享 route catalog：模型路由可注册、可核验 | 写死的路由会过期，注册制才能管住 |
| R2.1 直令路由 | 8 月底 | 直令指定模型 → 精确 route_id → route_bind_once 单次绑定 | 灵活性受控：直令即时生效，但不出注册表 |
| 开源 | 9/1 | r2.1 发布到本仓库 | 这套思想第一次离开本机 |

完整演进考古（含「加过又删」的 11 项机制、每次迭代的方案/执行/审查报告）保留在作者的私有档案库；本仓库是这条主线的现行开源形态。

这套思想不只属于 DSH

协作模式的内核是一套与宿主无关的工程学纪律，DSH 只是当前载体。迁移到任何支持子 Agent 的 harness（Claude Code、Codex、Kimi CLI、opencode……）时，真正要带走的是：

- 双停点：需求和方案各确认一次，确认前不创建交付候选；
- 版本化状态真源：一个工作区一份 CURRENT，批准绑定版本号与内容摘要，沉默和「继续」不算批准；
- 候选冻结：交付物用内容寻址（commit hash / 逐文件 sha256）冻结，任何修改产生新候选；
- Fresh Reviewer：每轮审查都是全新上下文，禁止用执行者自己的结论充当验收；
- 止损纪律：同根因最多两次、同周期最多三轮审查，到线就 BLOCKED 等人裁决，不靠换 Agent 改名重置。

CLI 时代这些纪律靠人工传递 prompt 执行；DSH 时代由 preset 自动派发执行。载体变了，纪律没变。

特性

- 🛑 双停点批准：先确认版本化需求，再确认方案、路由、范围与风险。
- 🔗 版本绑定：task_id、需求版本、方案版本与 approval_cycle 共同锁定当前执行。
- 🧊 候选冻结：用内容寻址的 base_ref 与 candidate_ref 描述可重建对象，避免“当前工作区”漂移。
- 🧪 Fresh Reviewer 独立审查：审查者从独立上下文读取候选，不接受执行者的推理辩护替代证据。
- 🔐 SHA 链校验：把规范、运行内核和 YAML 投影的关系固定下来，冲突时停止发布。
- 🧭 绝对路径参数化：DSH_HOME 缺省为 ~/.dsh，catalog 路径在加载时解析为绝对路径。
- ♻️ 可复跑部署：提供零依赖的 Node 校验脚本与 POSIX bootstrap 脚本，初始化目录并验证既有 catalog。

安装

前置条件

- 已安装支持 v4.3 preset composition 的 DSH。
- Node.js 18 或更高版本。
- Git。

快速开始

1. 获取仓库：

git clone https://github.com/a1270425803-bit/dsh-collab-mode.git
cd dsh-collab-mode

2. 设置 DSH_HOME 并准备 preset 目录（不设置时使用 ~/.dsh）：

export DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
mkdir -p "$DSH_HOME/.agent-presets/collab-v43-r2-1"

3. 复制 preset 文件：

cp -R agent.cordis.yml preset.yml governance plugins scripts skills dsh-route-catalog \
"$DSH_HOME/.agent-presets/collab-v43-r2-1/"

4. 初始化共享路由目录：先用 dry-run 查看动作，再执行初始化。脚本会创建 route-catalog/shared/、bindings/、snapshots/ 私有目录，并在缺失时创建受保护的 catalog.json；已有 catalog 只校验、不覆盖。

sh scripts/bootstrap-catalog.sh --dry-run
sh scripts/bootstrap-catalog.sh

5. 校验三处投影：从已复制的 preset 根目录执行；命令只读检查 spec.md、planner-kernel.md 与 agent.cordis.yml 的 SHA 链和嵌入内容。

cd "$DSH_HOME/.agent-presets/collab-v43-r2-1"
node scripts/release-sync.mjs --verify

6. 在 DSH 中选择 preset：选择 协作模式 v4.3 r2.1，然后按 DSH 的正常会话流程使用。

DSH_HOME 可以指向自定义目录；preset 中的 catalogDir 会通过 node:path.resolve 将它解析为绝对路径。若校验失败，请停止部署，确认复制的是同一版本的文件，并从 preset 根目录重新运行 node scripts/release-sync.mjs --verify；不要绕过校验继续选择 preset。

使用

一次协作按以下顺序推进：

1. 停点一：需求批准。Planner 把目标、交付、范围、禁止项和验收写成版本化需求；未获明确批准，不创建交付候选。
2. 停点二：方案批准。Planner 固定实现路线、模型路由、权限、风险、并行关系和停止条件；未获第二次明确批准，不进入执行。
3. 执行与冻结。Executor 按任务书生产候选，记录命令和证据；Planner 冻结可重建的候选引用。
4. 独立审查。Fresh Reviewer 对同一候选重跑验收并做风险相称的反例检查：PASS 才能进入完成路径，FAIL 在批准边界内返工，BLOCKED 则停止并返回 Planner 处理。

stateDiagram-v2
[] --> RequirementPending: 提出任务
RequirementPending --> PlanPending: 停点一批准
PlanPending --> Executing: 停点二批准
Executing --> CandidateFrozen: Executor 生成候选
CandidateFrozen --> IndependentReview: Fresh Reviewer 独立审查
IndependentReview --> Done: PASS
IndependentReview --> Executing: FAIL / 按批准边界返工
IndependentReview --> Blocked: BLOCKED / 停止
Done --> []

执行者只提交候选与证据，不自行宣布最终通过；最终状态由独立审查和 Planner 的状态记录共同决定。

原理

三处投影与一条 SHA 链

- governance/spec.md：v4.3 的唯一规范真源。
- governance/planner-kernel.md：从规范中抽取的常驻运行投影，保留状态、批准、路由、证据与完成规则。
- agent.cordis.yml：把同一份 kernel 原文嵌入 persona 的哨兵区间，并在头部保存 norm_sha256 与 runtime_projection_sha256。

scripts/release-sync.mjs 会按 NFC、LF、去行尾空白和单一结尾换行规范化文本，再计算 UTF-8 SHA-256。默认模式负责同步；--verify 逐项比较规范哈希、kernel 哈希和 YAML 哨兵区间的逐字节内容，任一不一致都会以非零退出码停止。

flowchart LR
S["governance/spec.md唯一规范真源"]
K["governance/planner-kernel.md常驻运行投影"]
Y["agent.cordis.ymlpersona 嵌入区间"]
V["node scripts/release-sync.mjs --verify"]
C["可重建候选"]
S -->|规范化并写入 norm_sha256| Y
S -->|抽取并校对规则| K
K -->|逐字节嵌入并写入 runtime_projection_sha256| Y
Y --> V
K --> V
V -->|一致| C

路由目录
bootstrap-catalog.sh 使用 DSH_HOME（缺省 ~/.dsh）初始化共享路由目录。目录和绑定/快照子目录为 0700，初始 catalog.json 为 0600，并带有自校验 digest；已有 catalog 不会被覆盖。

版本命名说明

对外发布名是 r2.1；内核中的 norm_version 是 collab-v4.3-r2.2。这是历史命名差异：发布标签用于识别仓库交付，norm_version 用于识别内核规范版本，二者不代表两套不同的功能逻辑。

FAQ

Q：为什么发布名是 r2.1，内核却写 r2.2？
A：这是已知的历史命名差异。部署完整性以 node scripts/release-sync.mjs --verify 的实际 SHA 校验为准，不要手工改写 norm_version。

Q：可以把 DSH_HOME 放到别处吗？
A：可以。在复制 preset 和运行 sh scripts/bootstrap-catalog.sh 前导出自定义 DSH_HOME；它会被解析为绝对路径，缺省值仍是 ~/.dsh。

Q：catalog 已经存在时，bootstrap 会覆盖它吗？
A：不会。脚本会检查真实文件、权限、JSON 字段和 digest；校验不通过就停止，避免静默覆盖已有路由数据。

License

本项目采用 MIT License。版权声明见 LICENSE。

致谢

感谢 DSH 及其协作模式的使用者与贡献者；本 preset 的目标是让 Agent 协作更容易理解、复现和审查。

English

中文 · Install · Usage · How it works

What is this?

dsh-collab-mode is the DSH (DeepSeek Harness) Agent preset for turning failure-prone AI collaboration into a traceable, lightweight state machine. Two approval gates clarify what to do and how to do it; immutable candidate references freeze the deliverable; a fresh Reviewer independently checks the same candidate. When a condition is not met, the process stops or returns for bounded rework instead of continuing on conversational momentum.

Evolution

This preset was not designed in one sitting. It is the result of ten iterations since June 2026 — evolving from manually copy-pasting prompts between three CLI windows to automated subagent dispatch in DSH:

| Stage | Period | Form | Lesson |
|---|---|---|---|
| Paper rules | early Jun–Aug 4 | Rule-doc iterations v2.1 → v3.1: three-window split of duties, mandatory persistence, subagent debates | Rules without enforcement get broken "casually" |
| CLI relay | Aug 4–8 | Three CLIs (Claude / Codex / Kimi) calling each other, prompts relayed by hand | Manual relay works but costs human time; the orchestrator never touched a real CLI |
| Hard gate | Aug 8–11 | Self-built planner_gate: a 1,747-line gate with 1,127 lines of self-tests, per-file approval ledger, hash anti-tamper | Mechanism inversion: the gate outweighed the work; abandoned in 4 days |
| Back to lightweight | Aug 11 | Two approval gates + simple/complex branch; safety returned to the host sandbox | Approve at plan level, not file level |
| Cross-CLI dispatch | Aug 13 | cross-terminal-dispatch: three CLIs dispatch to each other; reviews sent to a different model | The value of crossing terminals is heterogeneous review |
| DSH preset | Aug 14 | v4.0 migrated into a DSH user-level preset: embedded personas, 16 skills, 7 dispatch instances | Rules became real host-callable tools |
| v4.1–v4.3 hardening | Aug 15–17 | Governance state machine, resident kernel, adversarial review, content-addressed freeze | One state source of truth; approvals bind version and digest |
| R2 动态路由 | 8 月下旬 | 共享路由目录：路由可注册、可验证 | 硬编码路由会腐化；注册机制让它们保持诚实 |
| R2.1 直接订单路由 | 8 月下旬 | 直接订单 → 精确 route_id → 一次性 route_bind_once 绑定 | 灵活性保留在注册表内部 |
| 开源 | 9 月 1 日 | r2.1 发布在本仓库中 | 想法离开作者的机器 |

完整的考古记录（11 个曾被添加后又移除的机制，以及每次迭代的计划/执行/审查报告）保存在作者的私人档案中；本仓库是该谱系当前的开源形态。

这些理念并非 DSH 专属

从核心来看，这种协作模式是一组与宿主无关的工程纪律；DSH 只是当前的载体。当迁移到任何支持子代理的 harness（Claude Code、Codex、Kimi CLI、opencode……）时，你实际带走的是：

- 两道审批门：分别审批需求和计划；审批之前不存在可交付候选物；
- 版本化状态真相：每个工作区一个 CURRENT；审批绑定到修订版本和内容摘要——沉默或“继续”不是审批；
- 候选物冻结：可交付物通过内容寻址（提交哈希 / 每文件 sha256）冻结；任何更改都会产生新的候选物；
- 全新审查者：每一轮审查都在全新的上下文中运行；执行者自己的结论永远不算作验收；
- 止损纪律：同一根因最多尝试两次，每个审批周期最多三轮审查——然后进入 BLOCKED 并等待人工判断；重命名代理不会重置计数。

在 CLI 时代，这些纪律通过手工转述提示词来执行；在 DSH 时代，预设会自动派发子代理。载体变了；纪律没变。

特性

- 🛑 两道审批门：先审批版本化需求，再审批计划、路由、范围和风险。
- 🔗 版本绑定：将执行锁定到 task_id、需求修订版本、计划修订版本和 approval_cycle。
- 🧊 候选物冻结：使用内容寻址的 base_ref 和 candidate_ref，而不是漂移的工作树。
- 🧪 全新审查者：从独立上下文进行审查；执行侧推理不能替代证据。
- 🔐 SHA 链验证：保持规范、运行时内核和 YAML 投影一致。
- 🧭 绝对路径配置：默认 DSH_HOME 为 ~/.dsh，并在加载时解析目录路径。
- ♻️ 可重复部署：使用无依赖的 Node 验证器和 POSIX 引导脚本初始化并验证目录。

安装与部署

前置条件

- 支持 v4.3 预设组合的 DSH 运行时。
- Node.js 18 或更新版本。
- Git。

快速开始

1. 克隆仓库：

git clone https://github.com/a1270425803-bit/dsh-collab-mode.git
cd dsh-collab-mode
2. 设置 DSH_HOME 并准备预设目录（默认为 ~/.dsh）：

export DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
mkdir -p "$DSH_HOME/.agent-presets/collab-v43-r2-1"

3. 复制预设文件：

cp -R agent.cordis.yml preset.yml governance plugins scripts skills dsh-route-catalog \
"$DSH_HOME/.agent-presets/collab-v43-r2-1/"

4. 初始化共享路由目录：

sh scripts/bootstrap-catalog.sh --dry-run
sh scripts/bootstrap-catalog.sh

该脚本会创建私有的 route-catalog/shared/、bindings/ 和 snapshots/ 目录，并且仅在 catalog.json 不存在时创建受保护的 catalog.json。已存在的目录会被验证，而不会被覆盖。

5. 从复制后的预设根目录验证三个投影：

cd "$DSH_HOME/.agent-presets/collab-v43-r2-1"
node scripts/release-sync.mjs --verify

6. 在 DSH 中选择预设：选择 协作模式 v4.3 r2.1，然后继续正常的 DSH 会话。

DSH_HOME 可以指向自定义目录。catalogDir 使用 node:path.resolve 将其转换为绝对路径。如果验证失败，请停止部署，确认所有文件均来自同一发布版本，并从预设根目录重新运行 node scripts/release-sync.mjs --verify；不要绕过验证。

用法

1. 需求门禁：Planner 将目标、交付物、范围、禁止事项和验收标准记录为带版本的需求，并等待明确批准。
2. 计划门禁：Planner 确定路线、模型、权限、风险、并行结构和停止条件，并等待第二次明确批准。
3. 执行并冻结：Executor 在任务书下产出候选结果和证据；Planner 冻结可复现的候选引用。
4. 独立审查：由全新的 Reviewer 重新运行验收以及与风险相称的反例检查。PASS 进入完成路径，FAIL 触发有界返工，BLOCKED 停止并由 Planner 处理。

stateDiagram-v2
[] --> RequirementPending: 提交任务
RequirementPending --> PlanPending: 门禁 1 已批准
PlanPending --> Executing: 门禁 2 已批准
Executing --> CandidateFrozen: Executor 产出候选结果
CandidateFrozen --> IndependentReview: 全新 Reviewer
IndependentReview --> Done: PASS
IndependentReview --> Executing: FAIL / 有界返工
IndependentReview --> Blocked: BLOCKED / 停止
Done --> []

Executor 仅提交候选结果和证据；它不宣布最终结果。

工作原理

三个投影，一条 SHA 链

- governance/spec.md 是唯一的 v4.3 规范来源。
- governance/planner-kernel.md 是常驻运行时投影，包含状态、批准、路由、证据和完成规则。
- agent.cordis.yml 将相同的内核文本嵌入到 persona 哨兵范围内，并在其头部存储 norm_sha256 以及 runtime_projection_sha256。

scripts/release-sync.mjs 在计算 UTF-8 SHA-256 值之前，将文本规范化为 NFC、LF、无尾随空白，并且恰好以一个最终换行符结尾。其默认模式为同步；--verify 会比较规范哈希、内核哈希和嵌入的 YAML 字节，并在任何不匹配时以非零状态退出。

flowchart LR
S["governance/spec.mdsole specification source"]
K["governance/planner-kernel.mdresident runtime projection"]
Y["agent.cordis.ymlpersona sentinel range"]
V["node scripts/release-sync.mjs --verify"]
C["reproducible candidate"]
S -->|normalized norm_sha256| Y
S -->|rules projected into| K
K -->|embedded runtime_projection_sha256| Y
Y --> V
K --> V
V -->|consistent| C

路由目录

scripts/bootstrap-catalog.sh 使用 DSH_HOME（默认为 ~/.dsh）来初始化共享路由目录。目录以及绑定/快照子目录的权限为 0700；初始的 catalog.json 权限为 0600，并带有自校验摘要。现有目录永远不会被覆盖。

版本命名

公开发布名称为 r2.1，而内核 norm_version 为 collab-v4.3-r2.2。这是一个已知的历史命名差异：发布标签标识仓库交付版本，而 norm_version 标识内核规范版本。它们并不代表两组不同的功能集。

常见问题

问：为什么发布版本写的是 r2.1，而内核写的是 r2.2？
答：这是历史命名差异。请信任实际的完整性检查 node scripts/release-sync.mjs --verify，而不是手动编辑 norm_version。

问：我可以使用自定义的 DSH_HOME 吗？
答：可以。在复制预设并运行 sh scripts/bootstrap-catalog.sh 之前导出它；它会被解析为绝对路径。默认值仍为 ~/.dsh。

问：bootstrap 会覆盖现有目录吗？
答：不会。它会验证真实文件、权限、JSON 字段和摘要，然后在数据无效时停止，而不是静默覆盖路由数据。

许可证

本项目基于 MIT 许可证 发布。版权和许可声明请参见 LICENSE。

致谢

感谢 DSH 以及协作式 Agent 工作流的用户和贡献者。本预设旨在让 Agent 协作更易于理解、复现和审查。