Vai al contenuto principale
L

dsh-commander

leleou209/dsh-commander

A resident commander agent for DSH sessions that gates goal completion, goal edits and user questions, then drives the next turn in full mode. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.

Installazione

dsh plugin --profile web add github:leleou209/dsh-commander

README

决策托管(dsh-commander)

npm License DSH

决策托管:把「下一步做什么、做到什么算完成」的判断权,按你选的挡位托付给一个长期在线、可续接的指挥实体。即指挥员。

在 DSH 中建立一位稳定处于指挥位的子 agent,并以不同挡位下不同的身份参与你的项目、逐级代行指挥,实现项目的自动化推行。

包名@leleou209/dsh-commander
版本3.1.6
npmhttps://www.npmjs.com/package/@leleou209/dsh-commander
许可证MIT
DSH≥ 0.2.2

主 agent 负责执行,指挥员负责方向与验收。双方分工协作,节奏合拍。

安装

# 一条命令,装完重启 DSH 即可
dsh plugin --profile desktop add @leleou209/dsh-commander

也可以在插件市场里装:

  1. DSH 左侧栏 → 插件 → 发现 → 添加索引源
  2. 粘贴:https://aaamechanic.github.io/dsh-plugin-market/index.json
  3. 搜 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的专家模型模式
partialgoal 的变更与放行归指挥员,问用户自由常规长线开发,此时goal被接管,指挥员会自主决定演化方向
full指挥员驱动每一轮,主 agent 自动被唤醒,且主会话的结果会被指挥员看到并循环驱动指挥员会完整代理你的相当量行为
  • 前两档(off/observe)为弱参与,此时指挥员一般不直接干预会话,除非主会话保留了极强的询问惯性,那么用户应当及时干预。
  • 后两档(partial/full) 为强参与,此时指挥员会代替你决断并掌控goal以控制演化方向——开启前请确认它已经真正理解你的需求。

挡位跨进程保存(按根会话),重启后恢复;放行 / 批准 / 已咨询是本轮语义,重启即清。

它怎么工作

  1. 建立并绑定本会话的指挥员(delivery: 'caller'——宿主的完成推送被关掉,所以建完不会把主会话叫醒);
  2. 让它预热(读四份协作文档)然后待命;
  3. 按挡位管住三个判断点,同时收紧指挥员自己的工具面;
  4. 全接管时自动交接:本轮结束 → 汇报 → 等指令 → 唤醒新一轮。

初始化不会让主会话自动开工、不会建 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 / recordToolNamecommander / commander_record暴露给模型的工具名
commanderNamecommander指挥员在 Agent Teams 里的名字(也用于查重)
providerfork子会话建立方式;失败自动退 spawn
routePath/commander/takeover图标读写挡位的 HTTP 路由
statePath~/.dsh/commander/state.json挡位与预热代价的落盘位置
docDirdoc四份协作文档所在目录
enforceApprovaltrue是否启用 goal 审批门禁
waitMs / pollMs20 min / 30 swait 的最长等待与轮询间隔
initTimeoutMs90 s建立超时(超时图标显示失败,可点击重试)
shellToolspwsh / 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.js261composer 图标(React,子会话首帧就不渲染)
driver.js259全接管交接驱动 + 看门狗
tools.js173commander / commander_record 的工具面
routes.js154图标用的 HTTP 路由(读路径全 async)
store.js144状态落盘(临时文件 + rename,跨进程加锁)
gate.js129门禁真值表(纯函数)
commander.js119建立 / 查找 / 收紧工具面
consult.js113咨询握手(工具与驱动共用一份)
goal-link.js106goal 联动
preheat.js99从会话事件算预热代价
handoff.js86交接守卫与决议解析
modes.js69挡位定义与强弱分类
prompt.js61指挥员提示词与文档清单
protocol.js60回复契约(请求号 / 决议 / 批准 / 放行)
docs.js55四份文档的骨架与倒序追加

三条结构性决定(也是三条静态不变量):

  1. 成员不缓存(每次按需向宿主查)→ 没有冷缓存,也就没有"重启后不认指挥员"这类问题;
  2. 挡位一个缓存两种访问器(async 为主,同步只给 tools.guard)→ 不让 store 反向持有 Map;
  3. 相位由事实推导(在飞 / 失败 / 有指挥员)→ 不需要第三套状态机。

测试

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

Plugin correlati