dsh-commander
leleou209/dsh-commander
给 DSH 会话配一位常驻指挥员:托管「算不算完成、能不能改目标、该不该问用户」三个判断点,全接管时按轮次驱动下一轮。它的 HTTP 路由没有 DSH 的访问检查,浏览器里打开的网页可以调用它们。
安装
dsh plugin --profile web add github:leleou209/dsh-commanderREADME
决策托管(dsh-commander)
决策托管:把「下一步做什么、做到什么算完成」的判断权,按你选的挡位托付给一个长期在线、可续接的指挥实体。即指挥员。
在 DSH 中建立一位稳定处于指挥位的子 agent,并以不同挡位下不同的身份参与你的项目、逐级代行指挥,实现项目的自动化推行。
| 包名 | @leleou209/dsh-commander |
| 版本 | 3.1.6 |
| npm | https://www.npmjs.com/package/@leleou209/dsh-commander |
| 许可证 | MIT |
| DSH | ≥ 0.2.2 |
主 agent 负责执行,指挥员负责方向与验收。双方分工协作,节奏合拍。
安装
# 一条命令,装完重启 DSH 即可
dsh plugin --profile desktop add @leleou209/dsh-commander
也可以在插件市场里装:
- DSH 左侧栏 → 插件 → 发现 → 添加索引源
- 粘贴:
https://aaamechanic.github.io/dsh-plugin-market/index.json - 搜
commander,点安装
或直接 npm install @leleou209/dsh-commander 后手动加进 profile 的 dsh.profile.bundles
(包里声明了 dsh.bundle,装进 profile 后会被自动识别并启用)。
# 升级
dsh plugin --profile desktop add @leleou209/dsh-commander@latest
# 卸载
dsh plugin --profile desktop remove @leleou209/dsh-commander
装好后:composer 右侧出现图标即就绪;客户端半改动刷新页面,Host 半改版本需重启。
它解决什么问题
- 自循环迭代开发:主 agent 每轮停下 → 插件把「本轮输出 + 工具摘要」交给指挥员 → 指挥员给下一步 → 自动开下一轮。你给一个明确目标,剩下的是"跑—验—纠"的循环,不用一直按回车。
- 把强模型的判断力借给弱模型:指挥员可以是比主 agent 更强、或来自不同厂商的模型。指挥员负责判断与验收,主 agent 负责动手——弱模型也能产出被强模型把关过的结果并显著提升效能。
代价是真实的:它放大你表达的清晰度。需求明确、边界清楚,它就是加速器;需求含糊,它会用更多轮次和更多 token 把含糊放大成返工。
什么时候值得用
适合:长线、多批次、有可验收标准的工程任务;需要有人持续盯质量与一致性的重复迭代;想把一段明确的需求交给能自己推进的系统;或者只是想以小模型的消耗获取大模型的项目能力。
不适合:一句话就能做完的事(直接问主 agent 更快,或改用"不接管但陪听"的顾问挡位);需求本身模糊到无法验收(先想清楚再开启)。
模型怎么选(最重要的一条)
- 不要用同类 / 同源模型当指挥员。 dsh默认选择同模型作为subagent,结果是两个同水平模型相互无法突破反而相互攒合,浪费时间和token。
- 至少满足其一:比主 agent 强一个量级;或来自不同厂商 / 不同训练路线,让它拿到的视野与主 agent 不同、甚至更全。
- 尽可能用擅长架构设计的模型当指挥,这会减少迭代次数与跨步,并兼容工作模型的能力,变相减少 token 消耗与
history.md的堆积。
指挥员参与的四个挡位
挡位决定着代管的程度:
| 挡位 | 谁做决定 | 具体成效 |
|---|---|---|
off | 只你。指挥员休息,所有门禁失效 | 指挥员此时会拒绝向主会话提供帮助 |
observe | 你和主 agent 拍板,指挥员只给意见(建立后的默认值) | 类似顾问式处理,类比trae的专家模型模式 |
partial | goal 的变更与放行归指挥员,问用户自由 | 常规长线开发,此时goal被接管,指挥员会自主决定演化方向 |
full | 指挥员驱动每一轮,主 agent 自动被唤醒,且主会话的结果会被指挥员看到并循环驱动 | 指挥员会完整代理你的相当量行为 |
- 前两档(off/observe)为弱参与,此时指挥员一般不直接干预会话,除非主会话保留了极强的询问惯性,那么用户应当及时干预。
- 后两档(partial/full) 为强参与,此时指挥员会代替你决断并掌控goal以控制演化方向——开启前请确认它已经真正理解你的需求。
挡位跨进程保存(按根会话),重启后恢复;放行 / 批准 / 已咨询是本轮语义,重启即清。
它怎么工作
- 建立并绑定本会话的指挥员(
delivery: 'caller'——宿主的完成推送被关掉,所以建完不会把主会话叫醒); - 让它预热(读四份协作文档)然后待命;
- 按挡位管住三个判断点,同时收紧指挥员自己的工具面;
- 全接管时自动交接:本轮结束 → 汇报 → 等指令 → 唤醒新一轮。
初始化不会让主会话自动开工、不会建 goal、不会投递任何消息。 它不影响 agent team:主会话该拆并行就拆并行,不因为在场而收敛成"凡事先问它"。 代价是可见的:tooltip 会写明预热花了多久、几步、几次工具、多少 token,这份实测数字重启后仍在。
建立后第一次调用要预填充整份工具表,通常 60–90 秒才出首字;此后走缓存。这段时间主会话不受影响,可以继续干活。
三个判断点
指挥员只盯这三处,不干预你写代码:
| 判断点 | 没有指挥员 | 有指挥员(partial / full) |
|---|---|---|
| 目标算不算完成 | 主 agent 自己宣布完成 | goal complete 要指挥员的「允许结束」才放行 |
| 目标能不能改 | 可以悄悄暂停 / 改写你在跑的目标 | edit / pause / blocked 要「批准:goal <动作>」 |
| 该不该问你 | 一遇模糊就停下来弹确认 | full 下问用户也收归指挥员,由它决定是否打扰你 |
paused 的 goal 只能由你在界面恢复——模型无权 resume。
这三道门卡在工具层,对宿主原生的 create_goal / update_goal 同样生效,不只管 commander(action="goal") 那条自家通道——否则主 agent 直接调原生工具就能绕开指挥员。off 挡位连"直连指挥员"也拦:send_message 发给指挥员同样会被拒绝,避免绕过 say/wait 的禁令。
权限边界
指挥员是只读的全知观察者 + 受控的作者:
| 能力 | 说明 |
|---|---|
| 读 | 全部项目文件(read / glob / grep) |
| 跑 | 只读 shell(pwsh / bash;写操作、重定向、未知命令一律拦下) |
| 写 | 只有两个通道:commander_record → doc/history.md;commander(action="plan") → doc/plan.md。都是倒序追加,保留旧版 |
| 联网 | web_search / web_fetch |
| 对话 | commander / commander_record / list_agents / send_message |
| 不做 | 改源码、装插件、动 profile;也没有 write/edit,碰不到 doc/ 以外的文件 |
工具面是白名单(13 项),默认不动手;要它真的改点什么,是你在对话里明确要求。
四份协作文档
| 文件 | 作用 |
|---|---|
doc/suggest.md | 用户偏好与硬口径 |
doc/history.md | 已发生的实质行为(最新在上) |
doc/plan.md | 当前计划与历史轮次 |
doc/agent.md | 设计导向与编辑行为分化 |
plan.md 由指挥员自己维护:目标足够清楚时,它用 commander(action="plan") 写一版计划,最新一条就是当前计划,旧版保留可回溯。
全接管时每次交接都会提示它「计划有变就先更新 plan.md 再下指令」。
它们支持模糊迭代与意图溯源,但也会增加上下文,利弊兼存:文档越厚,预热越贵,指挥员越容易读到过期结论。建议只写"会影响下一次判断"的东西。
手动配置(一般用不到)
包内自带 cordis.patch.yml,装进 profile 后自动生效。需要改默认值时,在你的 profile patch 里加同名条目覆盖:
- insert:
- id: commander
name: '@leleou209/dsh-commander'
config:
provider: fork # fork 复用父会话前缀以命中 KV cache;不可用时自动退 spawn
commanderName: commander
docDir: doc
enforceApproval: true
配置项
全部有默认值,通常不用写:
| 键 | 默认 | 说明 |
|---|---|---|
toolName / recordToolName | commander / commander_record | 暴露给模型的工具名 |
commanderName | commander | 指挥员在 Agent Teams 里的名字(也用于查重) |
provider | fork | 子会话建立方式;失败自动退 spawn |
routePath | /commander/takeover | 图标读写挡位的 HTTP 路由 |
statePath | ~/.dsh/commander/state.json | 挡位与预热代价的落盘位置 |
docDir | doc | 四份协作文档所在目录 |
enforceApproval | true | 是否启用 goal 审批门禁 |
waitMs / pollMs | 20 min / 30 s | wait 的最长等待与轮询间隔 |
initTimeoutMs | 90 s | 建立超时(超时图标显示失败,可点击重试) |
shellTools | pwsh / bash / shell | 需要按只读规则审查的 shell 工具名 |
writeScopes | ['doc'] | 允许写的目录 |
allow | 见上方权限边界 | 指挥员的工具白名单 |
版本与依赖
| 项 | 要求 |
|---|---|
| DSH | ≥ 0.2.2(本版在 0.2.2-rc.3 上验证) |
| Host 服务 | DSH 内置 base 提供的 tools / subagents / webServer / workingDirectory;缺 subagents 时插件会给出明确报错而不是静默失效 |
| 客户端 | @deepseek-ai/dsh-client-ui-conversation 提供的 composer 槽位 conversation.input.right |
fork 后端 | provider: fork 需要 DSH 挂载 fork 后端;未挂载、或父会话还没有已完成轮次时,自动退 spawn(功能一致,只是首次请求要冷预填充) |
| 可选 | goals 服务——没有它时 goal 门禁自动跳过,其余功能不受影响 |
代码结构
index.js 307 行 只做装配:配置归一、服务取用、五个 effect 接线
lib/ ~1,890 行 15 个模块,每个只管一件事
test/ 9 个测试文件,零依赖
| 模块 | 行数 | 职责 |
|---|---|---|
client.js | 261 | composer 图标(React,子会话首帧就不渲染) |
driver.js | 259 | 全接管交接驱动 + 看门狗 |
tools.js | 173 | commander / commander_record 的工具面 |
routes.js | 154 | 图标用的 HTTP 路由(读路径全 async) |
store.js | 144 | 状态落盘(临时文件 + rename,跨进程加锁) |
gate.js | 129 | 门禁真值表(纯函数) |
commander.js | 119 | 建立 / 查找 / 收紧工具面 |
consult.js | 113 | 咨询握手(工具与驱动共用一份) |
goal-link.js | 106 | goal 联动 |
preheat.js | 99 | 从会话事件算预热代价 |
handoff.js | 86 | 交接守卫与决议解析 |
modes.js | 69 | 挡位定义与强弱分类 |
prompt.js | 61 | 指挥员提示词与文档清单 |
protocol.js | 60 | 回复契约(请求号 / 决议 / 批准 / 放行) |
docs.js | 55 | 四份文档的骨架与倒序追加 |
三条结构性决定(也是三条静态不变量):
- 成员不缓存(每次按需向宿主查)→ 没有冷缓存,也就没有"重启后不认指挥员"这类问题;
- 挡位一个缓存两种访问器(async 为主,同步只给
tools.guard)→ 不让 store 反向持有 Map; - 相位由事实推导(在飞 / 失败 / 有指挥员)→ 不需要第三套状态机。
测试
node test/modes.mjs # 9 挡位真值表
node test/gate.mjs # 15 门禁:每道门该拦 2 条 + 不该拦 2 条
node test/handoff.mjs # 10 交接守卫 + 协议解析
node test/store.mjs # 8 落盘 / 恢复 / 损坏隔离 / 磁盘失败降级
node test/docs.mjs # 4 doc/ 写入:骨架不覆盖、倒序追加不嵌套、plan 格式
node test/preheat.mjs # 6 预热代价 + goal 决策
node test/goal-link.mjs # 5 goal 联动
node test/client-render.mjs # 10 React stub 真跑组件(hooks 顺序 / 首帧)
node test/load.mjs # 18 假宿主真跑 apply():接线 / 路由 / init / 挡位 / 门禁 / cwd / plan
node test/invariants.mjs # 15 架构不变量(防止简化被悄悄改回去)
100 项全绿,npm pack 产物内重跑同样全绿(证明没有漏文件)。零外部依赖,只用 node。
已知限制
- 只读 shell 是 best-effort 启发式(命令白名单 + 重定向检查),不是沙箱。
- 指挥员异常崩溃靠看门狗发现(默认 20 分钟上限),没有宿主的即时推送。
- 未实现"切到全接管立刻补一次交接":要等下一次
turn end。 - 子会话的服务端 canControl 在"会话未打开且非已知指挥员"时 fail-open,第一道防线是客户端首帧判定。
- 门禁判断用内存里的指挥员 id 集合,重启后到第一次解析到指挥员之前是 fail-open(不拦);这是刻意选的失败方向——漏拦一次比误拦一整天安全。
License
MIT