角色智能体编排 wangyuanchuan2022/dsh-agents

dsh-agents

23 个专职角色 × 三档模型路由，装进 DSH 的多智能体工作台。
一次调用就创建一个「带角色人格 + 钉死档位模型 + 完整任务书」的子会话。

dsh-agents 把 DSH 变成按角色路由的多智能体工作台：23 个专职智能体，每个都钉死一档模型（LOW / MEDIUM / HIGH），一次调用就能拉起，带上人格、钉死的模型和完整任务书——外加 23 件工作流技能，端到端把它们串起来。

关键词：DSH 插件 · 多智能体编排 · 角色-模型档位路由 · 任务书合成 · 工作流技能 · agent orchestration

目录

- 为什么
- 特性
- 环境要求
- 安装
- 快速开始
- 三个工具
- 角色与档位
- 任务书
- 工作流技能
- 配置参考
- 设置页
- 机检工具
- 测试
- 目录结构
- 已知限制
- 许可与致谢

为什么

手工开子会话派活，问题往往不在「模型不够强」，而在三件事没人管：用哪个模型、给它什么人设、任务书写到什么程度。本插件把这三件事固化成机制：

1. 按角色复杂度分配模型，而不是拍脑袋。 oh-my-claudecode（OMC）在 19 个 agent 定义里给每个角色钉了一个 model: 字段；MACAE 的 ADR-003 从另一个方向得出同一结论——编排者用推理型模型、参与者用便宜模型。两条独立证据指向同一件事：角色复杂度决定档位，而不是全都上最贵的。
2. 派活是一次调用，不是一段规程。 人格注入、档位解析、任务书合成都发生在 agent_spawn 内部；调用者只需要说清「谁做、做什么」。
3. 任务书是可审计的产物。 派活消息本身就是一份八节任务书（含硬性完成标准与回收契约），可以先审后派（agent_taskbook 只合成不派活），也可以事后据此核对交付。

特性

- 23 个专职角色，3 条泳道——build（构建与分析 10）· review（评审与质量闸门 6）· domain（领域专家 7）；其中 19 个移植自 OMC，4 个为批次3 新建（rag-reviewer / silent-failure-hunter / spec-miner / harness-optimizer）。
- 三档模型路由（LOW / MEDIUM / HIGH ← haiku / sonnet / opus），档位可被用户层覆盖（设置页或 agent_roles set），解析优先级明确、可查来源。
- 只读角色有明确边界——上游标注 disallowedTools: Write, Edit 的 9 个角色（explore · analyst · architect · verifier · code-reviewer · security-reviewer · critic · document-specialist · scientist）在任务书里写成只读顾问条款，任务书同时注明这只是文字约束（见已知限制）。
- 任务书八节结构 + 派活前置三问（副作用关键词 fail-closed 告警）。
- 评审/验证席的上下文隔离（两层机制）——会话层：每席都是全新会话，不继承派活方对话历史；材料层：blind 席（code-reviewer / security-reviewer）不得获得作者自评与其他席位产出，isolated 席（critic / code-simplifier / verifier）不得获得作者自评；任务书自动写入「上下文隔离契约」，并对下发的材料做泄漏机检（命中「我已经实现并验证过」「另一席说没问题」这类文本时 fail-closed 告警并回传 isolationLeaks）。
- 23 件工作流技能：路由入口 1 + 流水线 4 + 协作 5 + 方法论 13。
- 11 份评审清单按扩展名/专项路由（go / ts / python / kotlin / rust / csharp / cpp / sql / pytorch / a11y / performance）。
- 两个确定性机检工具：crgate（评审证据链 freeze/anchor/finalize）与 publish-scan（发布前脱敏六类扫描 + 三值裁定）。
- 配置错就报错——未知档位、未知角色、半个路由、非法 clarifyMode 一律抛错，不静默兜底。

环境要求

- DSH：需要宿主提供 tools 服务（工具经 ctx.tools.register 注册）。settings / llm / workspaceRegistry / agentPresets 为可选服务，按宿主约定动态读取——旧快照缺它们时插件照常加载，只是降级为「不按名解析 provider、不挂工作区分组、不挂预设」。
- Node.js：支持 ESM 的现代版本（本仓开发环境为 Node 24）。
- 新增 bundle 后需要重启 DSH：宿主引导图在启动时生成，运行中新增的插件不会被加载。

安装

本地路径安装（推荐先 git clone 到本地）
dsh plugin --profile <profile-name> add /path/to/dsh-agents

或直接从 git 安装
dsh plugin --profile <profile-name> add https://github.com/wangyuanchuan2022/dsh-agents
宿主契约与既有 DSH 插件一致：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml（往插件花名册 insert 一行 id/name），lib/index.js 导出 name / inject / apply，工具经 ctx.tools.register 注册。

安装后不要再在 profile patch 里重复插入同一 id —— 重复 id 会让 loader 崩。

人格正文位于 personas/；tools/install-personas.mjs 可批量安装到 DSH（默认跳过已有自定义版本的角色，避免把定制版覆盖回通用版）。

快速开始

// 1. 看有哪些角色、各自档位与实际解析到的模型
agent_roles(action="list", lane="review")
agent_roles(action="tiers") // 档位路由表体检：配置的 provider/model 是否真的存在

// 2. 派活前先审任务书（只合成，不创建会话）
agent_taskbook(role="code-reviewer", task="评审 src/ 下这批改动，给出 P0/P1/P2 分级")

// 3. 一步派活：解析档位 → 注入人格与任务书 → 创建标准 DSH 会话并立即开跑
agent_spawn(role="executor", task="实现 X，按 tests/ 现有风格补测试")

角色会话产出的默认落盘路径是 <cwd>/agent-out/<角色id>-<yyyyMMdd-HHmm>.md（可用 evidencePath 覆盖）。会话本身是标准 DSH 会话：出现在左侧会话列表，可随时接管、继续对话或查看转录。派活方用 de_session action=status|list 做角色回收核对。

三个工具

| 工具 | 作用 |
| agent_roles | 角色目录 / 单角色详情 / 档位路由表体检。动作：list（可按泳道、档位过滤）、show、tiers、set（改某档 provider+model，与设置页同源）、reset。 |
| agent_taskbook | 只合成任务书，不派活：角色卡 + 职责边界 + 人格细则 + 任务 + 交付验收 + 澄清模式 + 汇报回收 + Claude→DSH 工具映射，附派活前置三问与本次路由解析结果。 |
| agent_spawn | 一步派活：解析档位 → 注入人格与任务书 → 创建标准 DSH 会话并立即开跑；dryRun=true 只回路由与任务书；tier / provider / model 可越档但会记入返回（可审计，不阻拦）。 |

边界：本插件只创建会话，不负责 wake / status / list / rename——那些归 de_session。

角色与档位

档位语义：LOW 窄而快的检索/文档/批量任务 · MEDIUM 实现/调试/测试/设计等主力工作 · HIGH 需求分析/规划/架构/评审等长链条推理。

| 档位 | build | review | domain |
| HIGH | analyst 🔒 · planner · architect 🔒 | code-reviewer 🔒 · security-reviewer 🔒 · critic 🔒 · code-simplifier | — |
| MEDIUM | debugger · executor · verifier 🔒 · tracer | — | test-engineer · designer · qa-tester · git-master · document-specialist 🔒 · scientist 🔒 |
| LOW | explore 🔒 | — | writer |

🔒 = 只读角色（上游 disallowedTools: Write, Edit），任务书中写成只读顾问条款。
合计：HIGH 11 · MEDIUM 10 · LOW 2 = 23 个角色。

档位映射分两层：

1. 基底：cordis.patch.yml 的 config.tiers（出厂默认，见配置参考）；
2. 用户层覆盖：设置页「Agents 三档模型路由」卡片，或 agent_roles action=set。
解析优先级：调用期显式 tier/provider/model → roleOverrides → settings 用户层 → cordis 基底 → 内置默认表。

⚠️ 档位表是配置不是常量——派活前用 agent_roles action=tiers 查当次生效值与来源（tierSources），不要假设某个档位一定指向某个模型。

任务书

派活的首条消息 = 八节任务书：

1. 角色卡：角色 id / 泳道 + 档位与钉死的 provider/model + 定档依据 + 权限边界 + 人格文件哈希；
2. 职责与边界；
3. 人格细则（personas/<id>.md；未安装时退化为角色摘要模式并在卡里标注）；
4. 本次任务 + 背景上下文；
5. 交付与验收：产出落盘路径、泳道默认交付要求（评审类强制「文件:行号 + P0/P1/P2 + 【改进点】」）、硬性完成标准双条件（落盘 + de_broadcast 回报，缺一即未完成）；
6. 澄清模式：interactive = 缺参数按 subagent-clarify 协议问组织者、防编造、超时降级；autonomous = 禁提问 + 缺省决策表；
7. 汇报与回收核对：完成广播对象、里程碑进度、de_session list/status 回收；
8. Claude Code → DSH 工具映射：lsp_diagnostics→pwsh 跑检查、TodoWrite→todo_write、Task(...)→de_session spawn、tmux→pwsh 后台任务等。
另有派活前置三问（方向与「失败也照常执行」相反，这里不派才是安全默认）：① 这事哪个会话能做？② 目标会话有没有对应工具与数据？③ 是否在要求对方做它做不到的副作用（写库/删数据/发消息/装依赖）？任务文本命中副作用关键词时自动告警（fail-closed）。

评审/验证类角色的任务书还会在角色卡之后自动插入 1.1 上下文隔离契约（见特性与已知限制）——先立约束再给材料，并声明故意未提供的项（作者自评、其他席位结论）。

模板正本：docs/task-brief-v3.md——本节是结构概览，条款以正本为准。

工作流技能

skills/ 共 23 件，分四组。技能的 description 一律触发词前置（触发：<中文提法>｜English: <triggers>｜<职责>），因为 DSH 技能目录只显示 description 前若干百字符，触发词写在末尾会被截断而无法被发现。

入口（1）

| 技能 | 作用 |
| agent-workflow-router | 总入口：按用户意图路由到下面 22 件之一，固化五条硬协议（派活前置三问 / 档位现场确认禁越档 / 任务书四条必含 / 点对点消息纪律 / 工作区纪律），附前置门与六条组合串联链。 |

流水线（4）——编排本插件的 23 角色

| 技能 | 链路 |
| agent-autopilot | 旗舰：想法 → 验证过的代码，六阶段（扩写/规划/执行/QA/验证/收尾）带相位门与 fail-closed 席位判定 |
| agent-feature | analyst → planner → executor → test-engineer → code-reviewer → verifier |
| agent-bugfix | explore → debugger（→ tracer）→ test-engineer → verifier |
| agent-review-squad | code-reviewer + security-reviewer 并行盲评 → critic 裁决（→ code-simplifier） |

协作（5）——工作流的外围协议

| 技能 | 作用 |
| subagent-clarify | 子会话澄清协议：缺信息不瞎猜，结构化提问 → 广播问组织者 → 超时降级 |
| requirement-interview | 需求访谈：苏格拉底式提问 + 含糊度门控，≤阈值才准动代码 |
| consensus-plan | 共识规划：规划与执行分离，planner 快照 → architect/critic 串行盲评 → ≤5 轮至 APPROVE |
| ai-slop-cleaner | 先锁行为再清理，五类 slop 分类 + 单味道单批次 + writer/reviewer 分离 |
| visual-verdict | 视觉判定：截图 vs 参考图输出结构化 JSON verdict，达标才准收工 |

方法论（13）——实现/评审/发布环节的作战手册

agent-loop（长任务循环：启动三查 / 停止条件落盘 / 心跳纪律 / 熔断）、tdd-workflow、verification-loop、parallel-execution-optimizer、error-handling、git-workflow、operator-approval-loop、agent-harness-construction、skill-eval、skill-stocktake、session-handoff、dsh-troubleshooting、opensource-sanitize。

安装：把需要的技能目录复制到 DSH 技能库（~/.agents/skills 或 ~/.dsh/skills）即可被会话按 description 触发。

配置参考

全部可配项在 cordis.patch.yml：

- insert:
- id: dsh-agents
name: dsh-agents
config:
档位 → provider + model（出厂基底；按你环境里真实存在的 provider 改） tiers:
LOW: { provider: deepseek, model: deepseek-flash }
MEDIUM: { provider: glm-pro, model: glm-5.3-flash }
HIGH: { provider: deepseek, model: deepseek-v4-pro }

可选：按角色覆盖档位 roleOverrides:
executor: { provider: deepseek, model: deepseek-v4-pro }

可选：角色会话使用的 Agent 预设（不填 = DSH 默认预设） defaultPreset: standard

clarifyMode: interactive # interactive | autonomous
agentOutSubdir: agent-out # 未显式给 evidencePath 时的产出目录（相对 cwd） allowSpawn: true # false = 紧急刹车，禁用 agent_spawn（另两个工具仍可用）

| 键 | 类型 | 说明 |
| tiers | {LOW,MEDIUM,HIGH} → {provider,model} | 档位路由基底。别名 haiku/sonnet/opus 同义。 |
| roleOverrides | {<角色id>: {provider,model}} | 按角色覆盖档位（优先级低于调用期显式传参）。 |
| defaultPreset | string | 角色会话的 Agent 预设 id；不填走 DSH 默认。 |
| clarifyMode | interactive \| autonomous | 任务书澄清模式缺省值。 |
| agentOutSubdir | string | 产出目录名（相对 cwd）。 |
| allowSpawn | boolean | 紧急刹车开关。 |
fail-loud 约定：未知档位、未知角色 id、半个路由（只给 provider 或只给 model）、非法 clarifyMode 一律直接抛错——静默兜底会把「改了没生效」变成黑盒。

设置页

DSH 设置 → 插件 → 「Agents 三档模型路由」卡片，三档各配 provider + model，支持逐档「保存 / 放弃修改 / 恢复基底」与「全部重置」。改完即时生效，无需重启：设置卡与 agent_spawn 共用同一份解析值。

接线方式与 DSH 生态既有插件的「服务端命名空间 × 浏览器端卡片」双半结构同构：服务端（lib/settings.js + lib/http-config.js）注册 settings 命名空间 dsh-agents 并挂 GET/PATCH /plugins/dsh-agents/config（回环 + Origin 同源防护）；浏览器端（lib/client.js）在 settings.plugin.item 槽位注册 key=dsh-agents 的卡片。两半缺一，设置页不会渲染（package.json 的 dsh.client 字段就是这半边存在的前提）。

机检工具

| 工具 | 作用 | 自测 |
| tools/crgate.mjs | 评审的确定性证据链：freeze（选择器）/ anchor（三级定位，--strict 为交付前强制门）/ finalize（覆盖状态机） | node tools/crgate.test.mjs（65 断言） |
| tools/publish-scan.mjs | 发布前脱敏机检：六类扫描（secrets / PII / 内部路径 / 危险文件 / 配置完整性 / git 历史）+ 三值裁定（PASS / PASS-WITH-WARNINGS / FAIL，单条 CRITICAL 即 FAIL）；--strict-tracked --git-history 为单仓放行门 | node tools/publish-scan.test.mjs（47 断言） |
| tools/install-personas.mjs | 人格批量安装（默认跳过已有自定义版本的角色） | — |
| tools/assemble-review.mjs | 评审材料装配（tools/approved.json 记录批准来源与时间） | — |

测试

node tests/run.mjs # 主测试（65 passed / 0 failed）：纯逻辑 + 假宿主全链路 + 端点 + 浏览器半/manifest 门
node tools/crgate.test.mjs # 65 断言
node tools/publish-scan.test.mjs # 47 断言
node tests/boot-schema-check.mjs # 宿主真实校验器验收门（装前必过）
node tests/installed-smoke.mjs # 安装副本烟测：工具 + settings + 端点三方同源

不要用 node --test：在受限沙箱（如 DSH 自身的 Windows 沙箱）里 node 的 pipe 子进程捕获会 EPERM，逐文件直跑是可靠方式。
重启后可用 tests/probe-boot.mjs / probe-catalog.mjs / probe-client.mjs 探针确认宿主引导图已含本插件、工具目录与 client.js 均可分发。

效果评测

针对「多角色编排是否真的优于单 agent」做过一次受控对照（DeepSWE v1.1 官方任务、官方 grader 复用判分、防应试隔离）：同任务同模型下，三席编排与全路由（5 席）均通过全部 held-out 测试（43/43），单 agent 为 38/43——差距集中在需求歧义点的裁决质量。完整对照表、差异归因与边界声明见 ARCHITECTURE.md 第 10 节。

目录结构

dsh-agents/
package.json 插件清单（dsh.bundle.patch + dsh.client 浏览器半声明） cordis.patch.yml 宿主插件行 + 全部可配项 lib/ index.js 插件入口 + 三个工具定义 roles.js 23 角色注册表（元数据；人格正文不在此） routing.js 档位路由解析 + 按模型名反查 provider + 目录体检 persona.js 人格加载（缺文件退化 + 哈希留档） taskbook.js 任务书合成 + 派活前置三问 spawn.js 会话创建（对齐 de_session 的踩坑修复时序） settings.js 三档配置：settings 命名空间注册 + tiersApi settings-compat.js 宿主 settings 服务版本差异的兼容层 http-config.js 设置卡数据端点 client.js 浏览器半：设置卡 personas/ 23 份人格正文（19 OMC + 4 ECC 系） personas/checklists/ 11 份评审清单（语言 7 + 专项 4，按扩展名/专项路由） skills/ 23 件工作流技能（源副本） docs/task-brief-v3.md 任务书模板正本 tools/ crgate / publish-scan / install-personas / assemble-review tests/ run.mjs + 宿主校验、烟测与探针 LICENSE MIT THIRD-PARTY-NOTICES.md 第三方许可与版权声明

已知限制

1. 只读角色是文字约束，不是硬隔离：DSH 无法按会话禁用工具，只读是任务书条款；要硬隔离，得给该角色配一个禁写工具的 Agent 预设（defaultPreset / agentPreset 可指定）。
2. 人格文件缺失时退化为摘要模式：personas/<id>.md 不在位时角色仍可用，但行为约束全部来自任务书条款，且任务书里会明确标注。
3. 只创建，不管理：wake / status / list / rename 归 de_session。
4. 预设只作用于创建时刻：会话运行中不可切换 Agent 预设（宿主 agent-preset-locked）。
5. 档位是默认值不是强制：可以越档派活，越档会记入返回并在任务书里留理由位（便于事后审计，不阻拦）。
6. agent_spawn 依赖宿主 agents 服务；workspaceRegistry 缺失时不影响创建，只是不挂左侧工作区分组。
7. 档位表随配置变化：README 里给的是出厂基底，真实生效值以 agent_roles action=tiers 的当次回显为准。
8. 上下文隔离是「硬会话层 + 软材料层」：会话层由 agent_spawn 硬保证（每次派活全新会话）；材料层靠机检告警而非阻断——组织者坚持把作者自评塞进任务书时，工具会点名命中原文但不会拒绝派活。此时该席结论不应作为独立评审采信（评审席自身仍须按隔离契约标注污染并只采信可核验证据）。

许可与致谢

- 本仓库自身代码：MIT，见 LICENSE。
- 角色体系：18 个基础角色逐字对照翻译移植自 oh-my-claudecode（OMC，MIT，Copyright © 2025 Yeachan Heo）——中文译文逐字对应定义与人格原文；code-reviewer 在 OMC 底本上深度改造升级为 v2.3 反编报形态（不再逐字）；4 个专项角色（rag-reviewer / silent-failure-hunter / spec-miner / harness-optimizer）的方法论移植自 Everything Claude Code（ECC，MIT，Copyright © 2026 Affaan Mustafa）v2.2.2。各上游版权与许可全文见 THIRD-PARTY-NOTICES.md。
- 任务书模板：源自 MACAE（Multi-Agent-Custom-Automation-Engine-Solution-Accelerator，Microsoft，MIT）的可移植机制清单；skills/subagent-clarify 的工具级 HITL 机制同出 MACAE（与 OMC AskUserQuestion guard 混合来源）。
- 部分协作与方法论技能、11 份专项/语言评审清单、tools/publish-scan.mjs：源自 ECC v2.2.2 的分析移植（全量保真；移植时的适配决策记录在提交历史）。
- 会话创建时序：来自 dsh-memory-evolve 的 de_session 实机踩坑记录（预设挂载、provider 解析、种子序号、工作区挂接）。

欢迎 issue 与 PR。若你的角色/档位配置有普适价值，也欢迎回灌成基底默认。