weixshaw/dsh-plugin-task-runner

🧩 dsh-plugin-task-runner — 任务拆解模式

DeepSeek Harness 的「任务拆解模式」agent preset：主代理把大任务拆成独立子任务，派给子代理执行并综合结果。每个子代理都在全新短上下文中独立干活，所以即使本地模型只有 64K 上下文（如 48GB Mac 上 omlx 部署的 Qwen3.8-27B），也能处理很大的任务。并发数、worker 模型、超限 fallback 模型均可按机器自定义。

为什么需要它

本地大模型跑长上下文很容易内存溢出或质量崩坏。本模式的架构是：

用户大任务
└─▶ 主代理（云端，负责拆解+综合，上下文只装「计划+结果摘要」）
├─▶ subagent 1（全新短上下文，默认本地模型）
├─▶ subagent 2（全新短上下文，默认本地模型）
└─▶ ... 并发数受 maxConcurrentWorkers 限制
└─▶ 汇总结果，交付最终答案

主代理的上下文只累积「计划 + 每个子代理返回的紧凑小结」，原始材料由各子代理在自己的短上下文里消化——整件事不需要任何单个上下文装下全部细节。

安装

dsh plugin --profile web add dsh-plugin-task-runner

安装后重启 web（或刷新页面），在模式选择器里选 「任务拆解模式」 即可。

安装时会自动把 preset 拷到 ~/.dsh/.agent-presets/task-runner/（已存在则跳过，不会覆盖你的修改；想恢复出厂就删掉该目录再重启一次）。

配置（按机器自定义）

preset 目录下 config.json（或项目根目录放一份 task-runner.config.json 做项目级覆盖）：

{
"maxConcurrentWorkers": 1,
"worker": {
"provider": "omlx",
"model": "root4k/Huihui-Qwen3.8-27B-abliterated-oQ4e-mtp"
},
"fallback": {
"provider": "deepseek-official",
"model": "deepseek-v4-flash"
},
"maxWorkerContextTokens": 40000,
"maxReplanRounds": 2,
"workerTimeoutMinutes": 30,
"maxWorkerResultTokens": 2000
}

| 字段 | 含义 | 建议 |
|---|---|---|
| maxConcurrentWorkers | 同时运行的子代理数上限 | 内存小的机器设 1（严格串行）；内存充裕可设 2–3 |
| worker.provider / worker.model | 默认 worker 模型（本地优先） | 换成你本机可用的任意 pi-ai 路由 |
| fallback.provider / fallback.model | 子任务超出本地能力时改用的云端模型 | 建议留强模型兜底 |
| maxWorkerContextTokens | 本地 worker 上下文预算 | 本地模型 contextWindow 的 ~60–80% |
| maxReplanRounds | 每个子任务返工上限（验收不过→补拆/修复/复核） | 默认 2；0 = 一次通过就综合 |
| workerTimeoutMinutes | worker 超时阈值 | 默认 30；超时走 Replan，绝不自己上手 |
| maxWorkerResultTokens | worker 小结带宽预算：每个 worker 返回给主代理的上限 | 默认 2000，这是主上下文不随 worker 数线性膨胀的防线 |

会话开始时主代理会读取配置并汇报生效值（并发数 / worker / fallback），方便确认当前机器跑的是什么参数。

依赖

- DeepSeek Harness。worker 按模型路由依赖 dsh-plugin-subagent-director 提供的 subagent_role 工具（它支持每次委派显式传 provider/model）。⚠️ 没有它时无法把 worker 路由到本地模型：内置 subagent 工具没有 provider/model 参数，退化后 worker 只会继承主会话路由（云端），本地路由丢失。此时要么装 director，要么改用 workflow 的 agent(provider/model) 显式指定本地模型。
- 本地模型走 OpenAI 兼容端点（如 omlx http://127.0.0.1:8000/v1），在 settings.yaml 的 llm-pi-ai.providers 里配置 provider。

开发

dsh-plugin-task-runner/
├── package.json          # npm 包清单（dsh.bundle.patch 指向 cordis.patch.yml）
├── cordis.patch.yml      # 注入 bootstrap 行
├── lib/index.js          # 启动时把 presets/ 拷进 ~/.dsh/.agent-presets/
└── presets/task-runner/  # 实际的 agent preset（agent.cordis.yml + preset.yml + config.json）

本地调试：dsh plugin --profile web add link:/path/to/dsh-plugin-task-runner

发布到插件市场

1. 建 GitHub 仓库 dsh-plugin-task-runner，把本目录推上去
2. 在仓库 Topics 添加 dsh-plugin（市场扫描器按此 topic 发现并收录）
3. （可选）npm publish 发布到 npm，别人就能 dsh plugin add dsh-plugin-task-runner 直接安装
4. 在仓库 Description 写清用途（评分含 description 质量），加 MIT License

License

MIT

v0.2.0：图形化设置界面
安装/更新后，在 Web 界面的 设置 → 任务拆解模式 页面可以可视化配置：

- 同时运行的子代理数（并发上限，1–8）
- 全本地模式开关：勾选后主代理（拆解器）也使用 worker 模型
- worker / fallback / orchestrator 的 provider + model
- worker 上下文预算（tokens）

保存即写入 ~/.dsh/.agent-presets/task-runner/config.json，下一个任务拆解模式会话生效（无需重启、无需改 JSON）。

全本地模式提示：勾选后仍需把「该会话的模型」在模型选择器里手动切到本地模型，拆解器才会真的跑在本地（persona 会自动检测并进入全本地纪律）。

配置也可继续直接编辑 config.json（或项目根目录放 task-runner.config.json 做项目级覆盖），优先级：项目覆盖 > 本机 config.json。

FAQ / 排查

- 设置页显示「读取配置失败：HTTP 405」：桥接未挂载。升级到 v0.2.2+ 并重启应用即可；若仍出现，检查启动终端有无 [task-runner] 相关报错。
- 改了并发但没生效：配置在下一个任务拆解模式会话开始时读取，当前会话不受影响；也可以直接在 ~/.dsh/.agent-presets/task-runner/config.json 改。
- 本地 worker 又内存溢出了：把「同时运行的子代理数」降到 1（严格串行），或在项目根目录放 task-runner.config.json 里的 maxConcurrentWorkers: 1。
- 全本地模式没生效：除了勾选开关，还要把该会话的模型在模型选择器里手动切到本地模型——persona 检测到后才会进入全本地纪律。

上下文隔离：已实测验证

v0.4.0 起附带实测结论：在父会话上下文放置密钥 THE_SECRET_CODE_IS_739251 后
派 spawn worker，worker 完全无法感知该密钥——子代理是全新会话（只有自己的
prompt + 系统注入），父会话历史不传递。配合两条防线：

- 语义预算 maxWorkerResultTokens：worker 小结 ≤2K token，超限落盘只回路径；
- 硬截断 tool-result-pruner（composition 自带，阈值 8192 字符）：无论 worker
返回多长，主代理实际收到的工具结果都会被 head/tail 截断。

orchestrator 侧自动压缩（compaction-basic）同样由 composition 提供，长任务下
主代理上下文不会线性膨胀。

外部记忆（.task-runner/）

v0.5.0 起 orchestrator 会把长期状态结构化落盘到工作区 .task-runner/：

.task-runner/
state.json    # 当前阶段 / 目标 / 待办 / 已做决策（紧凑）
tasks.json    # 任务清单（id、状态、worker、小结路径）
findings/     # 一主题一文件的关键发现
artifacts/    # worker 完整输出与长内容
summary.md    # 任务结束时留下的交接摘要

会话开始可恢复延续任务；上下文变重时先落盘、再只留紧凑摘要。这就是把
「Agent 边界当 Context 边界」的第三层：L1 orchestrator 工作记忆 →
L2 worker 短上下文 → L3 结构化文件系统 = 外部记忆。

执行层强制（task_worker，v0.6.0）

任务拆解模式会话里多了一个 task_worker 工具（普通 worker 用它派发），把三条
预算从「prompt 纪律」升级为「执行层事实」：

| 预算 | 执行层行为 |
|---|---|
| 并发上限 | 真信号量：超限返回 busy，等待当前 worker 完成再派 |
| worker 上下文 | 派发前 token 估算，超 maxWorkerContextTokens 拒绝并提示拆分/走 fallback |
| worker 结果 | 超 maxWorkerResultTokens 保头截断，全文自动落盘 .task-runner/artifacts/ |

reviewer/architect 等角色任务仍用 subagent_role（需要角色 persona 时）。