帮手调度台 Napstablooky233/dsh-agent-dispatch

dsh-agent-dispatch · 帮手调度台

一块设置面板：决定主 agent 要不要别的 agent 帮忙、准哪几个帮手上场——而且真的生效。策略以 systemPrompt 段的形式注入，保存即生效。

- 看得见：一个设置分区，显示状态、通道与帮手名册（含实测首字延迟）。
- 点得动：总开关 / 四态模式 / 通道勾选 / 帮手勾选 / 并发上限 / 附加要求，改完点保存。
- 真的生效：策略文本是函数，每步重新求值；关闭时注入「本轮不派活」的明确指令。
- 自己会开口：默认姿态是每轮先自查这份活能不能拆——不等人点名，也不把「要不要派帮手」原样问回去。
- 会自检：每次动工前先估一句话——这活能不能拆成几块互不依赖的？帮手卡住就换人，换不动就交给兜底。

它解决什么 · 为什么省 token

主 agent 每推进一步都要重发完整上下文（系统提示 + 历史），按 cacheMiss 计费，是 token 账单的大头。独立的帮手各有独立上下文，且免费车道输入输出零成本。所以省钱的关键不是「少说话」，而是把自包含的活挪出去。这个插件管的就是「挪哪些、挪给谁、挪几个」。

分工原则（写死在注入文本里）：简单、机械、自包含、不依赖主会话上下文的活（批量检索、逐项审计、抄改重排、列清单、翻译、格式化、初稿）派给免费车道的帮手；最难、最需要判断、后果在意的部分（架构与关键设计、跨模块推理、正确性与安全判断、分歧裁决、最终交付）留在主 agent。

安装

插件目录：本仓库在本机的克隆（<repo-path>）。两条路：

A. 自动改 profile 清单（推荐）

node scripts/install-into-profile.mjs # 预演，打印将改的两行
node scripts/install-into-profile.mjs --apply # 真的改（自动备份 package.json）
node scripts/install-into-profile.mjs --revert # 撤回到备份

脚本只动一处文件：<DSH_HOME>/profiles/<profile>/package.json 的两处——dependencies 里的 link: 依赖，和 dsh.profile.bundles 里的包名。改完在该 profile 目录跑 pnpm install（让 link: 变成 node_modules 里的 junction）并重启 dsh（patchReload: "live" 管得了热更，管不了新增 bundle，重启会结束当前 GUI 会话）。

注意：pnpm install 会把 node_modules 对齐到 package.json 的声明版本——如果某个插件此前被插件管理器更新到更高版本，这一步会把它降回声明值。想保持新版：pnpm add <包>@<版本> 后再重启。

B. 手动

等价于手动改 <DSH_HOME>/profiles/<profile>/package.json 两处：

1. dependencies 里加： "dsh-agent-dispatch": "link:<repo-path>"

2. dsh.profile.bundles 数组里加包名："dsh-agent-dispatch"

然后 pnpm install + 重启 dsh。

装好后：设置 → 帮手调度。

面板速览

八个区块，从上到下：

| 区块 | 内容 |
| 总开关与四态模式 | 开启 / 关闭；模式四种：关闭 / 先问我 / 主动派 / 直接派 |
| 帮手通道 | workflow 扇出 / 子代理单派 / Agency 专家 / Agent Teams；没勾的通道写进禁止清单 |
| 帮手名册 | 三层来源合并（宿主已注册 / 车道实测 / 手填 + 内置参考），每行标来源；★ 是默认主力 |
| 派活规模 | 同时最多几个帮手（1–8）、任务超过多少步才值得派、短任务是否禁止派活 |
| 动工前预估 | 是否每次动工先估一句话；拆出几块才算值得建队；预估通过能不能当场建 Agent Teams 队 |
| 卡住改派 | 多少步没产出算卡住、同一个活最多改派几次、之后交给谁收尾（主 agent 或某个已勾选的帮手） |
| 附加要求 | 原样写进注入文本 |
| 查看注入文本 | 展开就是真正发给 agent 的策略，不是示意图 |

顶部另有首次引导（四步，看过一次不再出现）与宿主适配自检（解释每个功能为什么在或不在）。首次打开时，侧栏设置区还会出现一张引导小卡片（自带排版，不占用设置页布局）：「打开设置去配」直达本页，「暂时不用」即只看这一次。

主动分工与四态模式

注入文本的第一句就是姿态，不是等人开口：每轮动工先自己扫一遍这份活能不能拆。不派也要一句话说清为什么自己干；「要不要派帮手」这种问题不许原样问回去。

四个模式只差在「谁点头」：

| 模式 | 行为 |
| 关闭 | 整轮不派活：不扇出、不召唤、不建队 |
| 先问我 | 主 agent 自己扫、自己给出具体分法（哪几块、几个帮手、谁做什么），然后等你一句同意 |
| 主动派（出厂默认） | 低风险的机械块直接派出去，只留一行告知；高成本动作先问 |
| 直接派 | 满足条件就派，不再问 |

低风险的机械块指：只读检索、多来源调研、逐项审计、抄改重排、翻译、格式化、初稿。高成本动作指：建 Agent Teams 队、召唤 Agency 专家、走非免费车道、写盘 / 删除 / 提交 / 发布、一次开的帮手超过并发上限——「主动派」下这些仍然先问一句。

注入文本还带一份顺手就该派的信号清单：一个大目标下面挂着几块子活、「分别 / 各 / 逐一 / 批量 / 对比 N 个」这类说法、要读多个文件或来源、重复的格式化与翻译、能切成自包含小块的一份活。逐块判断：找到一个自包含、有明确验收口径的独立块就值得派，剩余设计与裁决留给主 agent；不用等所有子件都适合派活。

派活规则里也写进了反面清单：等用户开口才派、把「要不要派帮手」问回去、为了并行硬拆、同一块重复派、把拍板的活也派出去——这五条都不算派活。

动工前预估与卡住改派

配置 v3 新增的两个行为。两者都写进注入文本（agent 每步都会读到），都能在面板上开关。

动工前预估（plan）。动工之前逐块判断：能否独立交付、能否写成自包含 prompt、能否用明确验收口径核对？找到一个合格块就值得派，剩余设计与裁决留给主 agent。低风险块优先走已勾选的 workflow / subagent；只有确实需要共享任务板、且至少有 plan.minBlocks 块时才考虑建 Agent Teams 队，建队确认不阻塞其他可独立派出的块。先问我 与 主动派 模式下建队前仍先问一次（建队算高成本动作）；直接派 模式下不再问；关闭 autoTeam 时永远要用户明确要求。minSteps 只按动工前预估，不按已经执行的步数累计。

卡住改派（failover）。帮手连续 failover.waitSteps 步没有任何产出就算卡住：主 agent 先发一条消息问一句（长调研可能只是安静），确认没动静就把这块活先改派给另一个模型、另一条上游（同一个模型换个成员修不好它——实证卡住的根因是上游过载和模型被弃用），最多改派 failover.maxRetry 次，之后交给 failover.fallback。勾了 Agent Teams 时，观察与改派用 agent_teams_status / agent_teams_reassign_task；否则用 list_agents，子代理通道开着时用 interrupt_agent + subagent。改派时把已确认的约束和已有的部分产出一并转交；已经派出去的活绝不重复派，等待期间也不许整轮空转。

任一开关关掉都不是删掉文本，而是换成一句明确的「本轮不做」指令，agent 不会自己发挥一套预估或改派。

配置键表

落盘于 $DSH_HOME/agent-dispatch/config.json，原子写（tmp + rename）。面板每次打开重新读取，手改此文件与面板改等价。

| 键 | 类型 | 默认 | 作用 |
| version | number | 3 | 配置结构版本；v1 的裸模型键加载时自动补 provider 前缀，v2 文件会补上 plan / failover 两块 |
| enabled | boolean | true | 总开关；关 = 注入「不派活」明确指令 |
| mode | 'off' \| 'ask' \| 'proactive' \| 'auto' | 'proactive' | 派活模式 |
| peer | string | 'our-free-model' | 名册默认 provider 名（只决定参考名册挂在谁名下，不要求这台机器真有它） |
| discover.llm | boolean | true | 是否问宿主 llm 服务枚举 provider/model |
| discover.siblings | boolean | true | 是否扫 $DSH_HOME 下兄弟插件的状态文件 |
| channels.workflow | boolean | true | 允许 workflow 扇出 |
| channels.subagent | boolean | true | 允许子代理单派 |
| channels.experts | boolean | false | 允许 Agency 专家 |
| channels.teams | boolean | false | 允许 Agent Teams |
| helpers.\{provider}:{model\} | object | 见下 | 键为 provider:model，值 { enabled: boolean, label?: string } |
| primary | string | 'our-free-model:nemotron-3-ultra-free' | 默认主力帮手；必须是已勾选的模型，否则退回第一个已勾选 |
| maxHelpers | number | 4 | 同时最多派几个（夹回 1–8） |
| minSteps | number | 3 | 任务超过多少步才值得派（夹回 1–20） |
| longTaskOnly | boolean | true | 打开后一句话能答完的活不许派 |
| plan.enabled | boolean | true | 是否每次动工前先估一句话 |
| plan.minBlocks | number | 2 | 拆出几块互不依赖的活才算值得建队（夹回 2–8） |
| plan.autoTeam | boolean | true | 只在 channels.teams 已勾选时有意义：预估通过可以直接建队、不必等用户当场再提一次；关掉则仍要用户明确要求 |
| failover.enabled | boolean | true | 帮手卡住时是否改派，而不是继续干等 |
| failover.waitSteps | number | 6 | 多少步没产出算卡住（夹回 1–50） |
| failover.maxRetry | number | 1 | 同一个活最多改派几次，用尽即走兜底（夹回 0–3；0 = 一次不重试） |
| failover.fallback | string | 'main' | 兜底谁来做：'main'（主 agent 自己接手）或一个 provider:model 键；其它值一律读作 main |
| onboarding.seen | boolean | false | 看过首次引导后置 true |
| notes | string | '' | 附加要求，原样写进注入文本（截尾 2000 字符） |

出厂默认 helpers 勾选了六个 our-free-model 下的实测可用模型：nemotron-3-ultra-free、nemotron-3.5-lightning-free、space-bunny-free、longcat-2.5-preview-free、ling-3.0-flash-fin-free、mimo-v2.6-flash-free（v1 配置无 provider 前缀的键自动补 our-free-model:）。

通道与名册

通道（CHANNEL_IDS 顺序即面板顺序）

| id | 标签 | 说明 |
| workflow | workflow 扇出 | 一个脚本里并排跑多个独立子任务，可逐项指定 provider/model |
| subagent | 子代理单派 | 把一整块独立任务丢给另一个上下文，只收回结果 |
| experts | Agency 专家 | 按领域召唤专家人格（需在设置里已启用） |
| teams | Agent Teams 团队 | 多成员共享任务板协作（需用户明确要求；动工前预估通过且 plan.autoTeam 打开时可直接建队） |

名册三层来源

每一行都有来源标签，面板显示为「车道实测 / 宿主已注册 / 手填 / 内置参考」：

1. 宿主 llm 服务实枚举（来源 llm，标签「宿主已注册」）——唯一能证明「这个 provider/model 现在真的能调」的来源。
2. 兄弟插件状态文件（来源 peer，标签「车道实测」）——扫 $DSH_HOME/<任意插件目录>/catalog.json + availability.json，不写死名字，拿到实测首字延迟。
3. 面板手填（来源 manual，标签「手填」）——用户可填任意 provider:model，哪怕别的付费车道。
4. 内置参考名册（来源 seed，标签「内置参考」）——11 行 our-free-model 模型快照，保证面板第一次打开不空。不是事实来源，只说明「长什么样」。

合并优先级：llm 枚举 → verified=true；兄弟插件 availability → state / ttftMs；内置参考 → 只补长什么样，不覆盖上面两者的判定。

HTTP API

全部走同源路由 /api/agent-dispatch/*，与宿主半身在同一进程。只服务本机浏览器，非 loopback 一律 403。

| 方法 | 路径 | 作用 |
| GET | /api/agent-dispatch/summary | 返回当前配置、名册、预览策略、统计、宿主适配状态 |
| GET | /api/agent-dispatch/health | 返回服务连接状态、配置路径、名册来源计数 |
| POST | /api/agent-dispatch/config | body { patch } 合并配置并落盘，返回完整 summary |
| POST | /api/agent-dispatch/rescan | 重新枚举 llm 并重建名册 |
| POST | /api/agent-dispatch/reset | 恢复出厂默认并落盘 |

兼容与降级

inject = [] + 嵌套 fiber 机会式获取 webServer / systemPrompt / llm 三个服务。任一缺席只少对应功能，插件照常可用：

- 无 webServer：面板 API 不可用（浏览器半身不能读写配置），但 systemPrompt 段照常注入。
- 无 systemPrompt：策略不注入（面板改完不生效），但 API 与名册正常。
- 无 llm：名册只剩车道实测 + 内置参考 + 手填；手填一条 provider:model 仍然可用。
- 无任何服务：面板照常可用（纯内存配置 + 内置参考名册）。

写盘失败不致命：配置先改内存并立刻生效，面板提示「写盘失败，重启后回旧值」。

卸载

node scripts/install-into-profile.mjs --revert（恢复备份），然后 pnpm install + 重启 dsh。
$DSH_HOME/agent-dispatch/ 可留可删。

开发与自测

node --check index.js # 语法检查宿主半身
node --check client.js # 语法检查浏览器半身
node scripts/check-i18n.mjs # zh/en 字典同键、且代码里 t() 引用的键都在字典里
node scripts/check-links.mjs # Markdown 相对链接与图片目标是否真实存在
node scripts/selftest.mjs # 纯函数自检（策略渲染 / 配置收敛 / 名册构建），148 项
node scripts/smoke-host.mjs # 假 cordis ctx 下跑真实 apply()，含 403、落盘、即时生效，44 项
node scripts/smoke-client.mjs # 桩 React + 真 /summary 数据，把 Panel 真渲染四遍，37 项

selftest.mjs 在临时目录造假伙伴状态，验证名册优先级、地区受限与暂不可用的降级、配置收敛（0 并发、非法 peer、非法键名都夹回安全值）。smoke-host.mjs 用假 webServer / systemPrompt 服务跑真实 apply()，确认路由挂上、配置落盘、段文本是函数（所以「保存后下一步生效」是结构事实），覆盖非 loopback 403、坏 JSON 500、disposer 可调用，以及 v3 全链路：预估与改派两块出现在注入文本里、预估通过后 teams 禁令解除、两块在 /reset 后回到出厂。smoke-client.mjs 用迷你 hooks 运行时当桩 React，喂给面板的是宿主半身真跑出来的 /summary，断言渲染树里有名册键、有真注入策略的原文、引导卡看过就消失，再勾上 Agent Teams 并调过预估与改派参数重渲染一遍，确认两个新区块（含禁用与锁定态）都真能渲染出来——node --check 抓不到「一开就是空白」这类崩法，这一层专门抓。

npm run check（语法）、npm run i18n（字典一致性）、npm run links（链接检查）、npm run test（自检）、npm run smoke（宿主半身）、npm run smoke:client（浏览器半身）、npm run verify（六项全跑）已配在 package.json 的 scripts 里。

相关文档

| 文件 | 用途 |
| README.md | 英文版（English primary） |
| AGENTS.md | 给 AI 编码 agent 的工作约定：结构、契约、自检 |
| INSTALL.md | 安装、验证与卸载步骤 |
| docs/GLOSSARY.md | 术语表：本仓库所有文档与界面文案的唯一口径 |
| CONTRIBUTING.md | 贡献指南：提交信息规范、分支流程、文档约定 |
| SECURITY.md | 安全策略与漏洞报告方式 |
| CODE_OF_CONDUCT.md | 社区行为准则 |
| CHANGELOG.md | 版本变更记录 |
| docs/market-entry.md | 上架 DSH 插件市场的条目与收录规则 |
| docs/publish.md | 发布流程（含需要人工授权的步骤） |

许可

MIT。仓库：github.com/Napstablooky233/dsh-agent-dispatch。
English version: README.md.