dsh-orchestrate

One prompt. A team of agents. ｜ 一句话，一支 Agent 队伍。

English ｜ 中文

让 DeepSeek Harness（dsh）的主 Agent 在合适时候主动、积极地调用子 Agent 完成并行任务： orchestrate_delegate 并行拆分、orchestrate_review 对抗审查、orchestrate_explore 多样性探索， orchestrate_status / orchestrate_stop / orchestrate_converge 跟踪、中止与收敛； 附 orchestration:policy 决策注入（仅根 Agent 可见），教模型判断"何时该派、何时不该派"。

⚠️ 第三方插件，非官方出品。构建于官方 subagent 能力族（ctx.subagents）之上，只做 决策层 + 编排模式层 + 收敛层。

为什么

• 官方已有完整的 subagent 底层（spawn/continuable/toolFilter/structured output），但模型只有 "可以派"的能力，没有"何时主动派、怎么拆、怎么等、怎么收"的编排层。
• 一个 Agent 的能力有上限：长任务串行、方案没有第二视角、多方向只能拍脑袋。
• 本插件把 Proma agent-collaboration 的协作方法论（并行拆分/对抗审查/多样性探索）工程化。

真实 API 验证（Spike C，2026-08-16）：10 个应编排任务 100% 主动触发编排， 10 个对照任务 0% 误触发（deepseek-v4-flash）。触发率依赖任务书自包含——与插件设计一致。

安装

# 需要官方 subagent 能力族（dsh-subagent + dsh-subagent-spawn-in-process）
dsh plugin --profile demo add ./dsh-orchestrate

插件默认使用 spawn provider；可通过配置 provider 切换（如 fork/acp）。

使用

在 dsh Web UI 里对 Agent 说：

并行调研这三个方向：① SQLite vs DuckDB 存储，② RAG chunk 策略，③ 索引方案。

Agent 会主动调用 orchestrate_delegate，返回：

🧩 编排完成（run run-8ca117bf，3/3 成功）
  [0] ✅ SQLite 更适合小规模…
  [1] ✅ 512-token 重叠 10%…
  [2] ✅ HNSW 优于 IVF…

长任务可后台化：run_in_background: true 立即返回 runId，稍后用 orchestrate_converge 收敛。

工具

| 工具 | 作用 | | --- | --- | | orchestrate_delegate | 并行拆分：tasks（任务书数组）/ task（单任务）/ template（模板引用：delegations/<id>.yml + templateArgs 占位符填充）；并发默认 4、超时默认 10 分钟；支持 run_in_background（后台化）、converge.mode: all/any、retryFailed、role、model（per-run 模型）、maxTokens（软预算）；返回结构化汇总（每个结论标注来源子会话） | | orchestrate_review | 对抗式审查：spawn 多个只读审查者子 Agent 挑毛病，返回风险/假设挑战/边界/建议的机械汇总；父 Agent 逐条评估；支持 aspects/reviewers（1-5）/model/maxTokens | | orchestrate_explore | 多样性探索：spawn 多个只读调研者子 Agent 沿独立方向探索，返回带置信度的发现报告；支持 directions（上限 6，超限截断提示）/model/maxTokens | | orchestrate_converge | 收敛后台编排：按 runId 阻塞等待全部子会话完成并返回完整汇总（可重复读） | | orchestrate_status | 查询编排任务与子会话状态（含后台 run 的完成比例） | | orchestrate_stop | 中止进行中的编排任务（子会话以 aborted 收尾） |

后台模式（run_in_background: true）忽略 converge.mode=any 与 retryFailed（语义不适用，调用时在 note 提示）。

角色（persona）

子 Agent 可指定 role（orchestrate_delegate 参数；review/explore 内定角色）：

| role | 视角 | 结构化输出 | | --- | --- | --- | | executor（默认） | 独立完成子任务并汇报 | { summary, findings[], open_questions[] } | | reviewer | 对抗式审查：风险/假设/边界/建议 | { verdict, risks[], assumptions_challenged[], edge_cases[], suggestions[] } | | researcher | 方向探索，标注置信度 | { summary, findings[], confidence, evidence[] } | | devil | 刁难压力测试：反面论点与推演 | { challenge, counterpoints[], what_if[] } |

行为细节

• 子 Agent 结构化输出：按角色强制对应 schema（官方 structured_output 机制）。
• 防递归：每个子 Agent 自动隐藏 orchestrate_* 工具（Spike B 验证 one visibility）， 且子请求显式传 maxDepth=1；toolFilter 降级时深度上限仍生效。
• 决策注入方案 C：orchestration:policy 段按 delegationDepth 过滤——仅根 Agent 可见， 子 Agent 的 prompt 里完全没有该段（2026-08-16 落地）。
• 只读：依赖官方部署 sandbox 默认 read-only（若部署改为 workspace-write，子 Agent 将继承写权限）。
• 失败语义：子会话失败（error/refusal/max-tokens）标记为 failed，partial output 保留； retryFailed 只重试非中止类失败。
• 成本控制：converge.timeoutMs 超时中止在途子会话；maxTokens 软预算（按输出长度 估算 token，超限中止余下子会话，估算值返回在 costTokens）；任务数上限 20。
• 取消：用户/模型取消当前回合时，在途子会话一并中止（父级信号接入）。

使用限制

• task 路径不自动拆分（等价单任务）；请先自行将父任务拆成任务书数组。
• 编排状态存于进程内，重启后需重新编排（跨重启恢复未实现）。
• costTokens 为估算值（输出长度近似），非官方 token 计数。
• 后台 run 受 timeoutMs 兜底；收敛语义依赖官方 one-shot 子会话（未用 continuable 后台）。

配置

| 键 | 默认 | 含义 | | --- | --- | --- | | provider | spawn | in-process spawn provider 名 | | auto | true | 是否注入 orchestration:policy 决策段（false = 只被动响应） | | denyTools | orchestrate_* | 子 Agent 需隐藏的工具名列表 | | maxDepth | 1 | 子 Agent 递归深度上限 | | templatesDir | 包内 delegations/ | 任务书模板目录（可挂载外部模板库） | | registryCapacity | 100 | registry 保留编排记录上限（超出时淘汰最旧记录） |

模板库

delegations/ 提供 10 个任务书模板（调研对比/代码审查/竞品分析/bug 排查等）， 可通过 orchestrate_delegate 的 template 参数直接引用（模式插件化）：

调用 orchestrate_delegate，template=code-review-multi，templateArgs={ module: ['src/a', 'src/b'] }

模板约定：templateArgs 中值为字符串数组的参数（如 module/items/competitor） 每个元素展开为一条独立任务，其余字符串参数作为公共上下文注入。 欢迎 PR 贡献新模板（对标 dsh-bench 的 datasets/）。

评测（collab 套件）

Collab real 扩展集（2026-08-17）：27 条任务的全量运行与分批复测显示，显式应编排任务 11/12（91.7%），隐式自主编排 1/5（20.0%），应编排合计 12/17（70.6%），对照任务 0/10 误触发。这个结果与 Spike C 的 10/10（100%）应编排触发率分别保留：前者覆盖更宽、含隐式自主场景，后者是精心设计的明确任务基线。详细报告见 dsh-plugin-analysis/07-collab-real-评测报告.md。

Roadmap

• [x] M1：delegate / status / stop + 决策注入 + 模板库（16 测试）
• [x] M2：review / explore / persona / per-run 模型（30 测试）
• [x] M3：模板参数化、后台化（converge）、决策注入方案 C、collab 套件、Spike C（54 + 37 测试）
• [ ] 发布前：npm 发布、UI 卡片

Development

pnpm install
pnpm vitest run packages/orchestrate/dsh-orchestrate/tests/   # 54 tests
pnpm vitest run packages/orchestrate-collab/                   # 37 passed（另 1 个真实 API 用例需 DEEPSEEK_API_KEY）

# 发布构建（产出 lib/，npm 包 main/types 指向 lib）：
#   注意：构建时 tsc 会对 vendor/ 依赖源码报类型噪音，可忽略；产物 lib/ 已正确生成
pnpm build

License

MIT