🧩 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 时）。