dsh-expert-orchestrator
Đã xác minhdsh-expert-orchestrator · v2.9.6 · MIT · Giao diện web
Expert Orchestrator — multi-agent orchestration agent preset for DeepSeek Harness (dsh): triage → PM planning → delegate implementation to domain experts via a merged roster (summon_expert), dependency-DAG taskboard, file message bus, tiered delivery gate
Cài đặt
dsh plugin add dsh-expert-orchestrator Xác nhận layer đã áp bằng dsh --profile default --dump-config — xem hướng dẫn cài plugin.
Mã nguồn
Thẻ
Tác giả
Readme
DSH Expert Orchestrator（专家编排模式）
多智能体编排 · PM 先行规划 · 合并花名册专家委派 · 依赖 DAG 任务板 · 门禁交付 · 经验沉淀
一个 DeepSeek Harness（DSH）agent preset 插件：安装后 DSH 即获得一个「首席编排者」会话模式—— 不亲自写码，而是分诊任务、请项目管理专家规划、把实施委派给最合适的领域专家，并以门禁保证交付质量。
✨ 它做什么
| 场景 | 行为 |
|---|---|
| 收到任务 | 每轮强制重新分诊（三级：大型 / 小型实施 / 只读），杜绝"上一轮在做就直接续"的漂移 |
| 大型任务 | 先召唤 PM 专家（高级项目经理 / 项目推进专员）产出结构化计划，再逐项委派 |
| 实施改动 | 一律委派专家执行（合并花名册优先：bundled-core + 已启用来源；无匹配时回退自带专家库；dsh-agency-agents 为可选共存项而非依赖）；协调官只做只读验证 |
| 并行协作 | 专家产出走文件消息总线落盘，协调官只读摘要不转述全文 |
| 交付前 | 独立评审专家（评审者 ≠ 实现者，回炉 ≤2 轮）+ PM 检查点，双门禁放行 |
| 任务收尾 | 提炼 ≤3 条教训写入经验池，下次同类任务自动注入 |
🧭 工作流
用户请求 → 分诊（每轮重做）
├─ 只读操作 → 协调官亲自做
├─ 小型实施 → 免 PM，直接委派 1 名执行专家 → 验收
└─ 大型任务 → PM 规划召唤（高级项目经理）
→ 任务板建档（依赖 DAG）→ 逐子任务委派专家
→ 并行专家产出落盘消息总线 → 协调官只读摘要整合
→ 独立评审（回炉 ≤2）→ PM 检查点 → 交付
→ 经验沉淀（lessons.md）
每步行动前过五锚自检：回顾｜收敛｜反跑题｜协作｜资源
🧩 五大机制
| 机制 | 说明 |
|---|---|
| 🎯 每轮分诊 + 五锚自检 | 三级分诊 + 五项显式自检（含"连续 2 轮无进展→换策略或召 PM 重排"），跨轮不漂移 |
| 📋 任务板 taskboard.py | 文件任务板：pending→ready→running→done/failed 状态机，--dep 依赖 DAG（done 自动解锁下游），崩溃 recover |
| 💬 消息总线 bus.py | 信箱式落盘消息：send/read/ack/broadcast/stats，并行专家零转述协作，省协调官上下文 |
| 🛡️ 交付门禁 | 独立评审（同意/部分同意/反对+理由，回炉上限 2 轮）→ PM 检查点，commit 前强制 |
| 💾 经验池 | 全局 lessons.md + 项目级 .expert-lessons.md 双层沉淀，委派任务书自动注入相关教训 |
| 🧙 原生专家工具 | list_experts（浏览合并花名册，紧凑/展开双模式）、summon_expert（白纸精召：persona 经 sanitizePersona 注入，解析链 exact→aliases→无歧义 title，shadowed/disabled 拒绝，task 8000 码点上限）、summon_experts（批量 ≤8、并发 4、部分成功语义）。递归防护：spawn 子代理带六项 toolFilter deny（不可再召唤专家、不可嵌套 subagent/fork、不可 workflow），工具 schema default 3 纵深兜底——单层委派，无失控专家树 |
| 📚 每专家经验池 + persona 方法论分层（v2.4.0） | summon 自动尾部注入 expert-lessons/<slug>.md 该专家历史教训（≤2000 字符，按字符截断，2K 上限，无命中零变化）；persona frontmatter method: + <!-- methods-cut --> 瘦身注入+按需深读指针（Top-5 bundled-core 已分层，fail-safe 全量回退，合入经预注册 A/B 实验门禁，档案见 docs/internal/experiments/）；list_experts 显式标注跨源 conflict/shadowed，自定义专家删除支持清理。已知限制：设置面板「清空已删除」按钮 UI 待接线（RPC 契约已就位） |
🆕 v2.8 新特性
| 特性 | 说明 |
|---|---|
| 🛡️ 委派安全门禁（WP-7） | 围绕 summon_expert 的四层可审计执法：origin chain 链路溯源——每次派发在任务书末行追加标记，链上出现重复 (专家, cwd) 对即拒绝且报错含完整链路、深度由链长推导（默认开启，A/B 实验档案见 docs/internal/experiments/）；四小门禁——工件归属登记（taskboard.py own，冲突具名 artifact_owned）、A→B→A 委派振荡告警（非阻断）、effort 能力预检、per-cwd 写锁（DSH_EXPERT_CWD_LOCK=1，同 cwd 第二位写型专家当场拒绝而非排队）；per-专家工具调用硬预算（DSH_EXPERT_TOOL_BUDGET，默认关闭）——事件溯源计数（模型自报不计入）、三档（告警/收尾/中断——交付出口永不拒绝）、budget <id> [--reset]；idle-edge 自动续领（DSH_EXPERT_IDLE_RECLAIM=1，默认关闭）——最后一位在途专家成功收尾时经既有 claim 路径以 owner=编排者 领取 ready 无 owner 任务，领取≠派工、绝不自动召唤专家 |
| 🧩 per-专家档案与 prompt 瘦身（WP-6 余项） | ~/.dsh/expert-profiles.json（全局层）+ <当前目录>/.dsh/expert-profiles.json（项目层覆盖）按专家调 model / toolFilter 白黑名单 / skills / MCP server 白名单 / effort，每次 summon 现场重读（热改文件下次召唤即生效）；toolFilter 收窄与递归防护 deny 求并不放宽、空 allow fail-closed；persona 中 <!-- tools: … -->…<!-- /tools --> 标记段在点名工具对该专家全部不可见时整段剪除 |
| 🧾 评审台账收口 | v2.7 评审后置 14 项台账全部处置：taskboard.py --json 结构化信封、bus 信箱根约定成文、归档同秒碰撞唯一后缀、视图超前/损坏归档板升格 unrecoverable，另四项书面裁定留档 |
| 🔌 兼容性 | engines.dsh / @deepseek-ai/dsh-tools 区间自 2.6.0 起未变（静态 semver 矩阵复验，记录见 docs/internal/verification/）；PROTOCOL 刷新清单维持 14 项 |
#16 硬预算 × #20 idle-edge 自动续领：建议组合开启
两个开关默认均关闭；若要开启，建议同时开启——各自补上对方留下的缺口。
#20 开而 #16 关时。 每次成功的空闲边沿都会把 ready 且无 owner 的任务（每轮扫描 ≤8 条）以 owner=编排者 领取。领取后未及时派工的任务由 watchdog 从时间面接管（nudge→reclaim 回 ready、清 owner）——而下一个空闲边沿会再次领取。该 claim→reclaim→再 claim 的慢循环在此组合下没有计数上限：#16 的预算累计兜底只在 #16 开启时存在，而 watchdog reclaim 本身是编排面命令，不计入任何预算。
为什么它无害——但也仅是有界。 三个事实兜住它：watchdog 时间窗为循环限速（每个时间窗至多一轮回收周期）、循环零 token（领取≠派工——扫描绝不召唤专家）、每一跳都在事件流可见（事件 type=claim，args 携带 {owner, ids} 可辨来源）。它可以空转，但花不掉 token、也藏不住。
建议。 同时设置 DSH_EXPERT_TOOL_BUDGET=1：续领取道既有 claim 路径，per-(task, expert) 计数跨 reclaim 累计；interrupt 档当场拒绝（budget_interrupted），budget <id> --reset 是唯一放行出口。交付出口（done/fail）永不拒绝——中断=强迫交还，绝不阻断交付。
🆕 v2.7 新特性
| 特性 | 说明 |
|---|---|
| 🗂️ 崩溃安全的编排状态（WP-4b） | 任务板改为事件溯源（append-only 事件流为权威、双层完整性哈希、崩溃后确定性重放）；消息总线按派工代际过滤并给出三态裁决，支持增量读取（--since-seq）；watchdog 会在孤儿专家的完成证据已在总线上时将其收养。summon_expert 可在新代宿主上把中断的专家运行恢复为持久续跑（裁决 Q2=2A——旧代宿主保持一次性行为；DSH_EXPERT_RESUME=0 可关闭） |
| 🚦 质量门禁（WP-5） | PM 规划阶段先落 draft、批准后方生效（create --draft / approve）；--kind review 子任务要求显式裁决——含 findings 校验、自动回炉路由与 escalated 终态；多评审任务（--quorum-m，默认 3，裁决 Q3=3A）仅在 ≥m 票同向且零反向票时达成裁决，每条回到 ready 的路径都重置票数 |
| 📄 文件层专家与零 token 手势（WP-6） | 专家 persona 按项目层 > 全局层 > 内置的 .md 文件层解析（裁决 Q4=4A）并支持运行时重读；/expert-<name> 手势以零模型调用注入 11 位核心专家（见下文「零 token 专家手势」小节） |
🆕 v2.6 新特性
| 特性 | 说明 |
|---|---|
| 🔒 任务板并发正确性（WP-1） | 全部写操作携带 expected_revision 乐观锁（旧 revision 返回具名错误且不落盘）；attempt 代际——转派撤销旧代际，旧代际的 done/汇报被拒；板文件损坏返回显式 unrecoverable 错误而非静默空列表；依赖写入前全图环检测 |
| 📮 消息总线 at-least-once（WP-2） | 游标仅在收到成功回执后前进（投递中途崩溃可重投）；携带已撤销 attempt 的消息读取时归档、不进收件箱；收件箱仅剩过期消息时返回显式 skip-round 提示 |
| 🛡️ 门禁执法平面（WP-3，opt-in） | 零依赖 commit-msg hook（消息格式 + 任务存在性 + 文件范围三查），仅在用户显式开启时安装进你的仓库；验证回执绑定逐文件 SHA-256 范围指纹——回执后任一文件变动即失效 |
| ⚡ 派工即回写（WP-4a） | summon_expert 从召唤任务书解析任务 id，专家运行前自动认领（in_progress + owner）；失败放行并显式提示，不阻断派工 |
| ⚙️ 宿主设置页迁移（WP-8a） | 插件用户配置迁至宿主 schemastery 命名空间（插件配置页），全部写操作带 expectedRevision 乐观并发；注册失败时降级放行，绝不阻断插件装载 |
📦 安装
前置：Node.js 22+ 的 DSH 环境；
python3（任务板与消息总线）；可选安装 dsh-agency-agents（Agency 花名册——本插件已解耦对它的依赖：不装时协议完整可用、自动走自带专家库兜底；装了其花名册也只视为额外来源）。内置trim-cli技能的 scripts wrapper 与 bin 二进制不在本包内（files 白名单不含），需按 trim-cli skill 文档另行获取。
方式 A：DSH 插件管理器（推荐）
dsh plugin --profile web add github:mario841859784/dsh-expert-orchestrator
方式 B：让 Agent 帮你安装
把下面这段话直接粘进任意 DSH 会话即可（无需先切到本预设）：
请帮我安装 dsh-expert-orchestrator 插件：执行
`dsh plugin --profile web add github:mario841859784/dsh-expert-orchestrator`，
装完后提醒我重启 DSH，并在会话预设选择器中选择「专家编排模式」。
方式 C：手动安装
git clone https://github.com/mario841859784/dsh-expert-orchestrator.git
# 作为 bundle 安装（v2.5.0+ 预设由 bundle patch 声明行挂载，目录部署不再生效）
dsh plugin --profile web add /绝对路径/dsh-expert-orchestrator
# 重启 DSH Web，在预设选择器里选「专家编排模式」
preset 注册机制（v2.5.0+ 起）
自 DSH 0.1.7-alpha 起，agent preset 是由 bundle patch 携带的声明行：一个 name: '@deepseek-ai/dsh-agent-preset'、Loader 行 id 为 preset-<id> 的插入行，完整 Cordis 组合内联在其 config.plugins 里。旧版目录机制（~/.dsh/.agent-presets/<id>/ 下放 preset.yml + agent.cordis.yml）已无任何读取方——只部署目录的 preset 永远不会出现在会话预设选择器中。本插件因此把组合内联进自身 bundle patch（cordis.patch.yml 的 preset-expert-orchestrator 行），正常安装插件即可，重启 DSH 后预设即可见可选。~/.dsh/.agent-presets/expert-orchestrator/ 目录继续作为 preset 的运行时数据根（技能、专家、经验池、专家来源）；声明行里的 skill-filesystem 用与部署器相同的 DSH_HOME || ~/.dsh 公式解析该目录。
DSH 版本要求（v2.6.0+；v2.9.1 起覆盖三个宿主版本行）：engines.dsh >=0.1.7-alpha.2 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-0 <0.3.0-0——声明行机制已在 DSH 0.1.7-alpha.2 上验证，并适配 DSH 0.2.0-rc.1；0.2.1-alpha 分支为现宿主线新增，因为严格 semver 下预发布版本不会命中比较器元组不同的区间（(0,2,1) ≠ (0,2,0)）。覆盖的宿主版本行：0.1.7-alpha.2（旧世代——one-shot 召唤，续跑探测回退旧轨）、0.2.1-alpha.1（长期运行宿主线）、0.2.1-alpha.2（现宿主——自插件 v2.9.1 起支持：该宿主移除了 SubagentRuntime.start，v2.9.0 及更早版本在其上无法注册专家工具；v2.9.1 切换为探测式 startActivation 新轨）。@deepseek-ai/dsh-tools peer 为 >=0.1.6-alpha.1 <0.1.7-0 || >=0.1.7-alpha.2 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-0 <0.3.0-0，覆盖历史上支持的 0.1.6-alpha 线。验证范围（用户裁决 1B）：0.2.1-alpha.2 宿主行由静态声明校验与两代手势声明实测覆盖（见 docs/internal/verification/ 的 v2.9.1 发布门禁记录）；宿主运行时项（召唤注册/通道可用）待发布重装后用户重启宿主补测。
部署策略（与其他 preset 插件不同）
- 从不删除目标目录里的任何文件（你加的技能、自定义专家都安全）；
- 协议文件（persona/技能/工具脚本）按版本标记刷新，本地手工修改在重启后保留，插件升级时才更新；
lessons.md与expert-sources/（下载的来源包与合并花名册视图）属于运行时用户数据——只增不覆盖。
安装后出厂只含 11 个 bundled core 专家（skills/expert-orchestration/experts/）。四个上游专家来源包不随包分发——在插件设置页的**「专家来源」**面板下载并启用：host 侧经 GitHub 直连或 CDN 镜像双通道拉取，解包前先做 sha256（pinned archive 哈希）验签。安装时安全扫描（凭据泄漏 + 指令注入模式）按来源分两档执行：注册表来源（pinned sha256）扫描命中 → 发出警告，由用户确认后放行，不自动拒收；注册表外自定义/本地路径来源扫描命中 → 硬拒；符号链接一律跳过并记录，不因此拒包。
专家管理支持专家粒度：已安装来源中的任一专家可单独停用（文件保留，可随时恢复）；并可在设置页创建/编辑/软删除最多 200 位自定义专家——custom 来源 rank 仅次于 bundled-core，作为去重代表时优先于来源包重名者；内置与来源包专家为只读引用（修改需复制为自定义副本）；自定义 prompt 为用户自写，不经第三方来源扫描，受长度限额约束。
本地源码自部署（可选）
插件管理器安装（dsh plugin --profile web add github:mario841859784/dsh-expert-orchestrator）会经 bundle patch 自动挂载部署器，无需任何手工 composition 条目。
仅当想从本地源码 checkout 加载插件时，才往宿主层 patch（与 dsh-onebot 同款机制）：在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中插入以下片段：
- insert:
- id: expert-orchestrator-deploy
name: '/绝对路径/dsh-expert-orchestrator/lib/index.js'
升级语义：插件 VERSION 变更时会用安装包内容覆盖 PROTOCOL 文件（agent.cordis.yml、preset.yml、skills/expert-orchestration/SKILL.md、skills/expert-orchestration/routing.md、skills/expert-orchestration/tools/taskboard.py、skills/expert-orchestration/tools/bus.py、skills/trim-cli/SKILL.md、skills/trim-cli/manifest.json、skills/trim-cli/entries、skills/trim-cli/reference、skills/expert-gestures），外加现只含 11 个 bundled core 专家、按 PROTOCOL 随版本刷新的 skills/expert-orchestration/experts/，以及 skills/expert-orchestration/source-registry.json 与 skills/expert-orchestration/roster-aliases.json——共 14 项（PROTOCOL 刷新）。USER_DATA（lessons.md、expert-sources/——下载的来源包与合并花名册）只缺才补、绝不覆盖。升级到本版本后首次运行时，历史上适配过的专家副本会一次性迁移进 expert-sources/legacy-adapted/（冻结本地来源，默认启用）而非被删除。宿主层本地挂载不受该覆盖影响。
存量迁移提示：若此前在 agent.cordis.yml 中手工加过 expert-orchestrator-deploy 条目，升级前应先迁移到宿主层 cordis.patch.yml，否则 VERSION 变更刷新会用出厂版覆盖该条目、静默断掉本地链路。
🚀 使用
- 安装并重启 DSH，会话选择「专家编排模式」预设（或设为默认）。
- 直接交代任务即可：编排者自动分诊、请 PM 规划、委派专家。
- 大型任务可随时插话调整；里程碑与 commit 前会自动过评审 + PM 检查点。
零 token 专家手势（v2.7）：/expert-名称
内置 11 位专家已注册为 modelInvocable:false 宿主技能（skills/expert-gestures/expert-<name>.md，与 preset 声明一并由 scripts/gen-preset-declaration.mjs 从 bundled-core 花名册生成）：在消息里直接输入 /expert-<名称>（如 /expert-backend-engineer、/expert-tech-writer），宿主 pre-step 钩子会确定性注入对应手势技能——不消耗模型调用、无模型自主决策环节（此类技能不进模型技能目录，模型经 skill 工具调用会被宿主拒绝，因此不产生任何 token 目录开销）。
手势注入后，persona 仍按文件层前置链现场解析：项目层 <cwd>/.dsh/experts/<name>.md > 全局层 ~/.dsh/experts/<name>.md > 内置 skills/expert-orchestration/experts/<name>.md（仅按 name 精确匹配，与 summon_expert 语义同源；改文件立即生效）。三层全部未命中时手势显式报加载失败，不会凭记忆模拟专家。
边界与冲突裁决：手势仅覆盖稳定花名册——文件层专家（随建随变）与来源包专家（随来源管理）不注册手势；手势名与既有技能同名冲突由宿主确定性裁决（同层 rank 升序：项目 .dsh/skills=100 < 项目 .agents/skills=200 < 本 preset 手势=300 < 全局 ~/.dsh/skills=400 < ~/.agents/skills=500；跨层就近层整体胜出，败者告警忽略）——用户项目层自建同名技能确定性地优先于手势。两代宿主（0.1.7-alpha.2 与 0.2.x）技能声明行格式与手势机制逐维一致（验证记录见 docs/internal/verification/）；已部署 preset 的手势层随下一次 VERSION 标记刷新生效（需重启级验证的项见该记录「待用户重启后补测」）。
📚 专家来源项目
11 个 bundled core 专家之外的内容来自四个 MIT 许可的上游项目。四者均已登记进 skills/expert-orchestration/source-registry.json，并原样引用、不改名不改内容（文件按上游原样解包，署名见 NOTICE）：
| 项目 | 许可 | 本插件中的采纳关系 | 收录文件 |
|---|---|---|---|
| VoltAgent/awesome-claude-code-subagents | MIT | classic 包内容源——离线 classic 包中历史适配专家副本的内容锚（62 个文件） | 171（categories/**/*.md） |
| wshobson/agents | MIT | classic 包内容源——离线 classic 包中历史适配专家副本的内容锚（4 个文件） | 202（plugins/*/agents/*.md） |
| msitarzewski/agency-agents | MIT | 独立来源包——作为独立来源整包安装 | 274（*/*.md） |
| jnMetaCode/agency-agents-zh | MIT | 独立来源包——作为独立来源整包安装 | 273（*/*.md） |
表中数字为各来源 pinned ref 解包实测数（按注册表 include/exclude 规则筛选后实际落盘的文件数，已对照 pinned archive 的 sha256 核验）。
前两者是 classic 包（离线兜底 release，锚定历史上 67 个适配过的专家副本）的内容源；后两者以独立来源包形式提供。下载走 GitHub 直连或 CDN 镜像双通道并做 sha256 验签与分档安装时安全扫描（分档规则见上文部署策略一节）；装好的来源专家在合并花名册中以「来源名 / 原名」组织，跨源重名专家并存并显式标注来源。以上上游项目均为 MIT 许可证，专家正文版权归各自作者所有，本仓库的分发遵循 MIT 并在此声明致谢。
推荐配置（中文用户）：来源集建议启用 awesome-claude-code-subagents + agency-agents-zh——加上 11 个 bundled core 专家即可覆盖路由表常见条目，且含中文原生专家文本；其余来源按需再加（来源未启用时协议自动降级到 bundled-core，不报错不中断）。解耦声明：本插件不再依赖 dsh-agency-agents——专家选择以合并花名册（bundled-core + 已启用来源）为主供给；未安装 dsh-agency-agents 时协议完整可用，已安装时其花名册仅视为额外来源、本协议不依赖。
🛠️ 自定义
- 专家提示词库：
skills/expert-orchestration/experts/*.md，直接增删改，格式照现有文件（头部「适用任务」供分诊匹配）；合并花名册无匹配领域时自动回退到这里。 - 经验池：全局
skills/expert-orchestration/lessons.md+ 各工作区.expert-lessons.md。 - 编排协议：
agent.cordis.yml（persona 铁律与循环）+skills/expert-orchestration/SKILL.md（完整协议）。
✅ 兼容性说明
本 preset 不硬编码任何特定部署的工具名（搜索/浏览器/外部 API），所有机制基于 DSH 标准工具 + 两个零依赖 Python 脚本，可直接跨环境使用。
宿主代际实测状态（v2.6.0，用户裁决 1B）：本轮发布门禁仅对现宿主 0.2.1-alpha.1 做了实测（npm pack 产物完整性、tarball 独立加载、声明一致性、PROTOCOL 刷新沙箱演练——均通过）；0.1.7-alpha.2 线的 peer/engines 声明保持覆盖但本轮未复测，以静态兼容为准；真实插件装载、summon 端到端、任务板读写、设置页渲染、commit-msg hook 安装执行等需要重启宿主的验证，标注为待用户重启宿主后补测。
🤝 致谢
- DeepSeek Harness — 核心框架
- MichengAI/dsh-agency-agents — Agency 专家花名册（可选共存来源，本插件不依赖）
- Asher-2000/dsh-expert-mode — 五锚自检 / 经验池 / 独立评审 / 任务板 / 消息总线五个机制的灵感来源
- VoltAgent/awesome-claude-code-subagents · wshobson/agents · msitarzewski/agency-agents · jnMetaCode/agency-agents-zh — 专家库引用来源（MIT）
License
MIT © mario841859784