多智能体编排 TimYuann/orchestra-dsh

orchestra — DSH 多智能体编排

把 DSH 实例变成一支乐队：角色默认使用平级完整会话，适合的任务也可显式选择原生 continuable 子代理。
Turn your DSH instance into an orchestra: roles use first-class sessions by default, with native continuable subagents available for compatible tasks.

orchestra-dsh 是 DeepSeek Harness（DSH）的多智能体编排插件。一个 driver 会话带着团队朝目标推进，角色各自拥有独立上下文（默认是平级会话，显式选择时用原生子代理），整轮运行——从 onboarding 到 review 再到 archiving——都靠对话协调。它分两层交付：一层是 A2A transport，负责任意会话之间的点对点消息传递；另一层是编排层，负责项目范围内的团队、角色与拓扑。

Why — the idea（设计理念）

编排 = 协作宪章（orchestration is a collaboration charter），不是固定流水线。创建任何团队之前，宪章必须先回答七个问题：

1. 谁做什么；
2. 每个决策归谁（每个决策只有一个最终负责人）；
3. 工作完成后交到哪里；
4. 交接必须带上什么；
5. 争议去哪里解决；
6. 循环何时结束；
7. 谁宣布团队完工。

driver 针对你的目标提出一份宪章，你批准之后，角色才会创建。插件只校验它能证明的部分（角色存在、归属引用能解析、每个目录只有一个团队），其余交给角色自律——不做脆弱的文本解析，也不上工作流引擎。

传统智能体用 plan mode：在同一个上下文里切换模式——计划和执行搅在一起，上下文越滚越大。Orchestra 用 A2A 取而代之：

- 讨论即计划（Discussion is the plan）——和一个思考型角色（比如 oracle）在交互式 a2a 对话里把难题聊透。每条消息都可观察、可回放。
- 计划即任务（The plan is the task）——讨论收敛后，结论原样作为自包含任务发给执行者。
- 计划与执行彻底分离（Plan and execution contexts stay separate）。

Quick start（快速开始）

环境要求：DSH（DeepSeek Harness），Node ≥ 22。v0.6.1 支持 DSH >=0.1.7-alpha.1 <0.3.0（这是声明的 peer 范围；已在 0.1.7-alpha.1 和 0.2.0-rc.2 上做过端到端验证）。精确锁定版本会被宿主的 bundle 兼容性检查拒掉，所以这里故意用范围——见 0.6.1 发布说明。可选的宿主投递层目前仍是一份 v2 实现计划，尚未交付。
检查点（2026-09-30，v0.6.1）： 类型检查干净，295/295 项维护测试通过，npm pack 各道关卡全绿，A2A 路径已在 DSH 0.2.0-rc.2 上实测跑通（在隔离的无头配置档里完成 a2a_create → a2a_read 往返；web 配置档 4602 能带着插件启动，其客户端 bundle 也在启动模块图里）。本轮尚未验证的部分：团队/交付层（本轮明确不在范围内）、重启后仍存活的角色身份，以及在没有预设注册表的无头配置档下执行 a2a_create(execution="session")。交付层 v2 文档仍是草稿，记录了九个阻塞项；图循环/关卡仍是声明。

1. 从 npm 安装，在你的 DSH 配置档目录里操作（先 cd ~/.dsh/profiles/<your-profile>）：

| 包管理器 | 命令 | 说明 |
| npm（推荐） | npm install orchestra-dsh | npm ≥7 会自动安装 peer 依赖 —— 改用 npm install --legacy-peer-deps orchestra-dsh；不要指望 pnpm 的 auto-install-peers 设置来配置 npm。 |
| pnpm | pnpm add orchestra-dsh | 如果紧跟发版之后安装（24 小时 minimumReleaseAge 策略），把 orchestra-dsh@<version> 加进 pnpm-workspace.yaml → minimumReleaseAgeExclude。 |
| yarn | yarn add orchestra-dsh | Yarn 会自动安装 peer 依赖 —— 安装后跑一遍下面的安全检查。 |
| bun | bun add orchestra-dsh | Bun 会自动安装 peer 依赖 —— 安装后跑一遍下面的安全检查。 |

安全检查（所有包管理器） —— 本插件的 @deepseek-ai/ 是 peerDependencies，由 DSH 宿主提供。如果你的包管理器自己装了一份副本，插件会重复加载，每次工具调用都会崩：

ls node_modules | grep '^@deepseek-ai' # expect no output (a .dup-bak leftover is fine)

如果出现了核心副本，先停下来查清它们的解析路径，再动手改任何东西；不要删掉整个 scope，里面可能有无关的包。关键检查点是：插件和宿主解析到的 DSH 核心服务必须指向同一份安装。只装 npm 依赖并不会选中 bundle：要通过 DSH 的 bundle/插件管理器启用它，并确认已激活。

2. 重启 DSH，打开新会话。

Use it（用法）

直接说就行 —— 用自然语言，或者 /team 斜杠命令：

/team 在当前工作目录实现一个 TypeScript 工具库 + 单测 + README

driver 会跑引导协议（目标 → 约束 → 上下文 → 拓扑提案 → 你批准 → 执行），给出协作方案，只有你批准之后，它才会创建角色会话并派发自包含任务。这道关卡没有捷径：orchestra_create 需要 frozenRef，而只有你批准草稿才会生成它 —— 只给目标和模板去调用，按设计会返回 approval_required。批准方式就是用大白话回一句（启动 / 可以 / ok）；/team approve <draftId>@<revision> 也行，但从来不是必须的。
先定规模：driver 可以直接干活，也可以委派一个有边界的原生子进程，或者先用彼此独立的会话，等确有需要再引入共享团队。新任务可以变成当前团队的新泳道，复用已有的合适成员。新的角色组合由可发现的 orchestra-preset-authoring 手册指导；在 DSH 0.1.7 上不需要做 preset-root 初始化。

轻量模式：一次性的协作根本不需要团队——A2A 工具（a2a_list / a2a_create / a2a_send / a2a_reply / a2a_read / a2a_stop / a2a_status）可以在主机上任意会话之间独立使用。

Core concepts（核心概念）

四类对象彼此独立；各自拥有自己的事实，其他对象只引用它们：

| 概念 | 是什么 | 存在哪里 |
| Topology（拓扑） | 某一类团队如何协作：角色、归属、路由、完成条件。一个可以实例化的模板。 | .orchestra/topologies/<id>.json（项目） · ~/.dsh/orchestra/topologies/（全局） · 内置 |
| Preset（预设） | 某个角色如何行事：人设、工具、纪律。拓扑通过 preset id 引用它。 | .orchestra/presets/<id>/（项目） · ~/.dsh/orchestra/presets/（全局） · 内置 |
| Mission（任务） | 这个团队要做什么：目标、范围、约束、验收标准。 | 传给 orchestra_create |
| Runtime State（运行时状态） | 这个团队已经做了什么：会话、报告、生命周期。 | orchestra/state/team.json + orchestra/archive/ |

目录约定：项目级 .orchestra/ 优先于全局 ~/.dsh/orchestra/，后者优先于内置。插件首次运行时，会把内置预设和拓扑写入全局根目录（用户改动永远不会被覆盖）。运行时状态位于 <cwd>/orchestra/ 下（state / reports / archive），按工作目录区分。

Built-in topologies（内置模板）

v0.3 legacy templates（继续可读，不静默替换）：

| 模板 | 生成的角色 | 用途 |
| duo | reviewer（只读） | 最小闭环：driver + 有针对性的两轮评审。 |
| trio | implementer + reviewer（只读） | 面向正经开发任务的实现–评审闭环。 |
| oracle | oracle（只读） | 深度讨论伙伴：对话 → 把结论变成任务。 |
| four-role-dev | implementer + reviewer + oracle（reviewer/oracle 只读） | 实现 ⇄ 评审主循环，外加一条按需升级的 oracle 通道。 |

v0.4 task topologies（schemaVersion 1；protocol 里的 typed handoffs / bounded Loop / Human Gate / single Closure owner 在 v0.5 中保留为声明式资产——校验器仍然检查、角色 welcome 仍然携带，但运行时不再用状态机工具去驱动它们）：

| 模板 | 生成的角色 | 用途 |
| feature-development | implementer + verifier + reviewer（verifier/reviewer 只读） | 已批准的任务 → 有边界、经过测试、经过评审的代码交付。Loop implementation-review（最多 2 次尝试），gate feature-closure-approval。 |
| bug-diagnosis-and-fix | investigator + implementer + verifier + reviewer（除 implementer 外均为只读） | 先复现 + 定位根因，再做最小修复并附回归证据。循环 diagnosis-fix-review，门禁 bug-fix-acceptance。 |
| architecture-decision | researcher + architect + reviewer（全部只读） | 给出有证据支撑的决策简报，并让用户直接选择。循环 decision-validation，门禁 architecture-decision-approval（reviewer PASS ≠ 用户批准）。 |
| refactor-and-migration | architect + implementer + verifier + reviewer | 按声明的切片做行为基线迁移，并附回滚证据。循环 migration-validation，门禁 migration-compatibility-approval。 |
| audit-and-hardening | hardening-auditor + investigator + implementer + verifier + reviewer | 有边界的安全审计 → 最小修复 → 复扫证据。循环 hardening-remediation，门禁 security-risk-acceptance（缺少复扫不能 PASS）。 |

每个模板都带一个 protocol 块：ownership（每项决策归谁）、routes（默认消息流向）、completion（谁宣布团队完成），外加 v0.4 的 loops / gates / handoffs / closure 声明。validator 会检查引用，但当前 lazy-dispatch 路径不会带上完整的 protocol 开场消息。这些声明并不能证明运行时真的会约束 payload、尝试次数、门禁或 closure。九个 v0.4 角色预设（orchestra-v04--v1，含 planner 和 oracle）都是完整可挂载的组合（persona + tools + agent-instructions），不是只有 persona 的文本。

编排在设计上就是灵活的：driver 可以挑任意数量的角色（3 个或 10 个）——它必须定义 routes 和 ownership，但阵容取决于任务。角色名与某个模板角色相同时，会继承该模板的 sandbox 和 preset。还可以提议新角色，并通过 orchestra_add_lanes 加入正在运行的团队（plan → 用户同意 → confirm:true）。新增的席位记录在 team.addedLanes，不算对原始 charter 的修订。orchestra_spawn 已不存在。

Tools（工具一览）

A2A transport（独立使用，不需要团队）：a2a_list（先列你的 cwd，按最近活动排序，query 关键词过滤，archived 折叠，role + 相对 lastActivity）· a2a_create（开启一个轻量协作者；execution: "session" | "subagent"）· a2a_send / a2a_reply（投递回执：live_inbox / durable_inbox / resumed_inbox —— accepted ≠ processed）· a2a_read（反向渐进披露：默认只读最近 1–2 轮，按需放宽）· a2a_stop（取消目标正在运行的轮次，并清空它待处理的 inbox —— 相当于 Composer 的 Stop 按钮）· a2a_status（只报告有对应 Session 事件真正证明的生命周期事实）。
Orchestra 泳道： orchestra_draft（只追加的计划草稿；按角色渲染的蓝图预览以 Markdown 表格呈现；inlineTopology 让 driver 从角色预设 COMPOSE 出图，而不是借用现成的一张）· 你的批准（一句简单的 yes —— 启动 / 可以 / ok —— 记录到最近一次展示给你的那个草稿修订版上；只有真正的用户发言才算数，/team approve <draftId>@<revision> 也可以）· orchestra_create（预留已批准的计划；需要批准产出的 frozenRef，且不创建任何会话）· orchestra_dispatch（把任务派发到某条泳道；角色的会话在第一次派发时才实体化，实体化失败会报出角色及其固定模型，并回退到 reserved，让下一次派发重试）· orchestra_add_lanes（把新目标嫁接到 RUNNING 状态的团队上，作为另一条泳道 —— 先出计划，用户同意后再 confirm: true；每个目录一个团队依然成立）· orchestra_report（托管写入通道 —— 只读角色唯一能做的持久写入）· orchestra_send（按 teamId+roleId 派发给受治理的角色）· orchestra_team（目标看板：角色会话、存活状态、报告数量、最近报告路径、批准后新增的泳道）· orchestra_dismiss / orchestra_activate（归档与复活）· orchestra_topologies（项目/全局/内置目录，附带角色库）· orchestra_wait（仅用于无头/脚本循环 —— 交互式 driver 直接结束自己的回合，由角色的回复唤醒）。

v0.5 移除 —— 微型状态机接口： orchestra_loop_start、orchestra_attempt_start、orchestra_verdict、orchestra_handoff、orchestra_gate_open、orchestra_gate_fallback、orchestra_graph、orchestra_graph_reconcile、orchestra_reconcile、orchestra_decision、orchestra_document、orchestra_charters、orchestra_close、orchestra_apply_amendment、orchestra_freeze、orchestra_spawn —— 共 16 个工具，外加 orchestra_create 里那次一次性全名单校验，规范那份 17 项瘦身清单也点了它的名。driver 不再是图管理员：节点之间直接通过 A2A 交接硬事实，两轮上限是角色纪律，而不是宿主强制的上限，报告会尝试唤醒 driver，不再要求轮询。orchestra_create 拒绝任何没有批准产出的 frozenRef 的调用，所以控制点没有变化。

设置标签页： DSH 设置面板里的「orchestra」页面展示模板（带协议）和团队实例（带 mission/status/archives）。

Team lifecycle（团队生命周期）

none ─[orchestra_create]→ active ─[orchestra_dismiss]→ archived ─[orchestra_activate]→ active
- dismiss 请求取消/排空，尝试发出退役通知，在 orchestra/archive/ 下写入不可变快照，并用归档标记替换活动状态。持久化的角色会话会保留；这不代表它们的轮次会继续运行。停止失败和成功结果 schema 不匹配仍是已知缺陷。
- activate 从归档 id 恢复团队：活跃会话直接复用，持久化的会话恢复运行，权威缺失的会话被替换（记录到 sessionHistory，并发放恢复包）；部分失败时团队进入 degraded，而不是假装成功。
- 每个工作目录只能有一个活动团队。

Development（开发）

npm run typecheck && npm run build # host tsc + client tsc + tsdown → lib/
scripts/dev-instance.sh # dev instance on :4600

开发实例几秒内即可重启，且绝不碰主实例。端口 4600 和 dev 配置档与另一个项目的设置共用：该配置档除了本插件，还带着那个项目的 bundle，所以同步新构建时绝不要清理它的 bundle 列表或依赖。本地交接文件（AGENTS.md、STATE.md、DSH-INTEGRATION.md）、会话日志和运行时状态按仓库忽略规则留在 Git 之外。docs/ 下部分设计和评审文档纳入版本跟踪；它们不包含在 npm 包里。

Roadmap（路线图）

- v0.5.0 ✅（2026-09-16） — lean-lane 重构。16 个微状态机工具没了：driver 不再扮演图管理员，节点之间直接交接硬事实，前线循环最多 2 轮，driver 由角色自己的回复唤醒（响应式收件箱），不再轮询 —— orchestra_wait 现在只是无头专用工具，因为为了心跳阻塞 driver 的轮次，正是角色回复排成「待处理消息」的原因。插件记录从 Session 日志迁到 <cwd>/orchestra/ 文件（ADR-0002）—— 自定义 Session 事件类型让整个日志重读时无法阅读，所以这次迁移才让插件接触的每个会话重新可以原生回放。A2A 新增 a2a_stop（真正的 agent.cancel()）、按活动排序并支持关键词搜索的 a2a_list，以及反向窗口的 a2a_read。审批就是普通用户回复（ADR-0006）。222/222 测试全绿；完整生命周期（draft → approval → team → implement → review FAIL → targeted fix → review PASS → dismiss）已在 :4600 的真实开发实例上跑通。
- v0.4.1 ✅（2026-09-12） — 兼容 DSH 0.1.5-rc.2。依赖从 0.1.0-rc.6 升级（20 处宿主类型错误，全是机械性改动），另有一处类型检查器看不出来的运行时回归：DSH 0.1.5 把槽位注册改成了声明式门控，所以客户端插件必须用 ctx.slots.inject("settings.section", () => ctx.slots.register(...)) —— 裸调 register() 会让整个插件加载失败。142/142 测试通过；在真实开发实例上做了端到端验证（设置面板能渲染拓扑目录；实时会话能成功调用 orchestra_topologies）。
- v0.4.0 ✅（2026-08-25 主线闭环） — 活的编排文档（章程草案 → /team approve → 冻结 → 修订）、有界图运行时（循环/尝试/裁决/门控/闭包，带类型的交接，上限耗尽）、事务式供给、七个 v0.4 角色预设、五种任务拓扑、会话标题三段式方案、驱动节点里程碑通知、提案蓝图表格、恢复加固（归档校验、三分支激活、控制器接管）。本地验证：18 个测试文件 / 142 个测试通过。真实全流程端到端没有由开发团队跑过 —— 外部验证清单见 UPDATE-v0.4.0.md。
- v0.5.1 ✅（2026-09-19） — 自适应团队与诚实的失败路径。团队现在是动态的：orchestra_add_lanes 把新目标作为另一条泳道嫁接到运行中的图上（计划 → 一次用户确认 → 应用），于是一个目录始终只有一个团队、一个闭包负责人，同时又不限制它能承载多少工作。对已有活跃团队的目录执行 /team，总会说明现状并给出唯一一个二选一（继续旧目标，或归档旧目标再开新目标）—— force-archive 这条逃生通道按设计已移除。orchestra_create 变成只做预留：角色在首次派发前只是席位，物化失败时会报告角色、失败原因以及章程钉定的模型，然后把角色退回 reserved，下次派发重建它，而不是投递到一个从未存在过的会话里。模型路由不再回退到内置阶梯：偏好文件只在存在时才读取，否则用部署自身的默认模型。两个角色加入库（planner、orchestra-v04-oracle-v1），阶段/泳道引用会做交叉校验。文档和工具描述已与代码重新同步（v0.5.0 评审里「文档教人用一个已经不存在的工具」这类缺陷又出现了）。
- 0.8.0 — 已规划，未发布：批次 2 加入宿主采集的证据、冻结候选、worktree/租约、合并 CAS 和决策记录；批次 3 加入恢复胶囊、治理和可观测性。2026-09-22 评审指出了前置生命周期和设计上的修正。跨 worktree 的仓库级团队身份是目标，不是当前行为。
- UI 候选（不属于当前交付承诺）——侧边栏实时拓扑图与 GUI 操控；当前设置页仅供展示。
- 后续——product-or-ui-design / frontend-designer / documenter 拓扑（目录中标记为 Deferred）。

Coexistence（与官方 Agent Teams 共存）

DSH 提供一个可选启用的实验性 Agent Teams 分组（@deepseek-ai/dsh-experimental-agent-team 及其同组包）。Orchestra 不使用它，也不依赖它（实验性包在该分组之外无法作为依赖安装），并且没有占用该分组的任何工具名——send_message、list_agents、interrupt_agent、spawn_teammate、wait_agent、team_task_。Orchestra 自己的工具都带 orchestra_ / a2a_ 命名空间，所以两者可以同时挂载。

License

MIT © 2026 TimYuann. DeepSeek Harness（DSH）是独立项目；其许可协议请见该项目自身说明。