前言¶
在 DeepSeek Harness（DSH）里用本地小模型做长任务时，常见问题是上下文一拉长就「丢线」：前面定的步骤、中间改过的文件、尚未完成的子目标，很容易在同一条长对话里被冲淡。单靠「一条会话跑到底」往往要靠人不断提醒模型「你现在在第几步」。
下面介绍社区插件 dsh-plan-runner（维护者 MathieuPortmann，GitHub 仓库 MathieuPortmann/dsh-plan-runner）。它把任务拆成 Plan 写出的步骤，每一步在新的子会话里执行，Harness 用机械检查（以及可选的只读 reviewer）验收结果，面向「小本地模型 + 可验证的多步工作流」这一组合。目录页见 SkillHub 上的 dsh-plan-runner（社区目录，与 DeepSeek / 幻方无官方从属关系）。
这是什么¶
dsh-plan-runner 是 DSH 的工作流类插件：Plan 智能体先只读探索，再用 plan_begin、plan_add_step（每步一次调用）和 plan_show 记录步骤；你批准后点 Run step by step，Runner 按步执行。每一步使用 DSH 原生 subagent，子会话里只看到本步目标、指令、前面步骤的短摘要、所需文件，以及固定的收尾报告格式（Summary / Files / Decisions / Open questions）。
插件自述维护为 best-effort，Issue 可能无人回复，欢迎 fork。当前 package 版本为 0.1.1，许可证 MIT。
核心功能¶
Plan 与步骤约束¶
- 选用 bundle 自带的 Plan preset（id 为
plan；勿与另一个同样 id 的 preset bundle 混装）。 - Plan 写步骤时，若某步会超过该模型上下文窗口的 60%，会被拒绝，必须拆小。
- 计划会保存为工作目录下的
PLAN-<name>.md。
逐步执行与权限¶
每一步在独立子会话中运行，可配置：
- model：见下文 Configuration；
- access level：
read、read-shell（只读 shell）、write（仅限本步声明的 outputs 写文件）、full； - 子会话内不能发起 approval 请求（DSH 会拒绝）；超出当前权限模式、需要人工批准的操作会被拒绝并导致该步失败。涉及写文件的步骤，应把会话放在 auto 或 workspace-write 模式。
机械检查（checks）¶
每步结束后 Harness 运行本步定义的 checks，语法包括：
exists: <path>contains: <path> :: <text>words: <path> >= <n>count: <glob> >= <n>command: <shell command>（退出码 0 为通过）
重要步骤还可启用只读 reviewer，必须以 VERDICT: OK 或 VERDICT: PROBLEMS - ... 结尾。
失败、重试与拆分¶
- 某步失败：重试一次，并带上原因与 lesson；
- 第二次仍失败：提议更细的拆分，在你接受前不会改动物理状态。
- 同一步内重复相同 tool call 视为 loop，达到配置阈值会中止该步（默认见
loopRepeats）。 - 计划因重启中断：暂停后可从当前步继续。
for_each 与 stop¶
for_each步骤：对每个文件或条目各开短会话，每项写一份结果文件。- 标记
stop的步骤：执行后暂停，便于你人工检查结果。
状态与备份¶
- 运行状态：
<工作目录>/.plan-<name>/state.json（人类可读 JSON）。 - 计划索引：
<DSH_HOME>/plan-runner/index.json。 - 步骤覆盖的文件会备份到
.plan-<name>/backups/。删除.plan-<slug>/目录即可丢弃该计划状态。
安装与启用¶
安装命令以 README 为准：
dsh plugin --profile web add dsh-plan-runner
# or straight from GitHub:
dsh plugin --profile web add github:MathieuPortmann/dsh-plan-runner
安装后重启对应 profile。bundle 会加入 id 为 plan 的 Plan preset。
配置（可选）¶
在 profile 的 cordis.patch.yml 中增加 id 为 plan-runner 的行；各键均可省略：
- id: plan-runner
config:
models:
my-local-model:
provider: ollama
window: 32768
description: good reasoning, slow
defaultModel: my-local-model
splitModel: my-local-model
auditModel: ''
pauseOnBattery: false
ollamaUrl: http://127.0.0.1:11434
commandTimeoutMs: 120000
loopRepeats: 3
说明要点：
models为空时，各步使用 Plan 会话自身的模型。- provider 为
ollama时，若ollamaUrl无响应，运行会暂停；插件仅对该地址做GET .../api/tags探测。 command:类 check 在工作目录下用sh -c执行，超时由commandTimeoutMs控制。
环境兼容性¶
| 组件 | 要求 |
|---|---|
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| DSH | >=0.2.0-rc.2 <0.3.0（peer：@deepseek-ai/dsh-llm、@deepseek-ai/dsh-tools） |
| 平台 | Linux 上测试；纯 JavaScript。command: check 需要 POSIX sh |
README 记载在 DSH 0.2.0-rc.2、Node 22.23 上做过验证。
典型用法¶
先做 Plan，再逐步跑：
- 在 DSH 中选择 Plan preset，让智能体只读探索后调用
plan_begin→ 逐步plan_add_step→plan_show。 - 在 plan review 卡片或 composer 上方条带中批准计划，点击 Run step by step。
- 每步结束后查看 checks 与（若启用）reviewer 的 VERDICT；遇到
stop步骤时人工确认后再继续。
Plan 与 Runner 会为步骤设计 checks（例如 README 验证记录里曾用 words: 检查输出）。你也可在步骤里加入 command:，Plan 侧被提示尽量保持只读；实际命令仍以你审查计划内容为准。
开发插件本身时，仓库内可运行：
npm test
（42 个独立测试，无需安装 DSH。）
适用场景与注意¶
更适合：本地小参数量模型、步骤可声明输出文件、能用 exists / contains / words / count / command 客观验收的多步任务（重构一批文件、按清单生成文档、分目录批处理等）。
权限与安全：插件以当前 DSH 进程的权限读写工作目录与 DSH_HOME 下索引，并可在工作目录执行 command: check。安装前请阅读源码与 MIT 许可证，确认 checks 与 Plan 生成的 shell 命令符合你的信任边界。子 agent 的 tool 集合按 access level 过滤；需要写盘时务必使用合适的会话写权限模式。
生态：DSH 理念是「一切皆插件」；SkillHub 目录是社区站点，不是官方应用商店。
结尾¶
dsh-plan-runner 把「写计划」和「按步执行」拆开：Plan 负责拆步与保存 PLAN-<name>.md，Runner 用 fresh child conversation、机械 checks 和可选 reviewer 把小模型长任务的可靠性押在可验证的短步上，而不是单会话记忆。
- 目录页：https://www.skillhub.cn/plugins/MathieuPortmann/dsh-plan-runner
- 源码与完整说明：https://github.com/MathieuPortmann/dsh-plan-runner
