dsh-plan-runner
为 DeepSeek Harness 打造的逐步计划运行器，适用于小型本地模型：每个步骤都在全新的子对话中运行，并使用独立的模型和访问权限；通过机械检查和可选的只读审查器进行验证；失败后重试一次，然后向用户提议进一步拆分。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:MathieuPortmann/dsh-plan-runner#2bb098a0ab8a433f7eef893c30424c8086c3d2cdPlan Runner 以 dsh-plan-runner 发布，当前版本为 0.1.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Step-by-step plan runner for DeepSeek Harness (DSH), built for small local models that lose the thread on long tasks. A Plan agent writes the steps; the runner then executes each step in a fresh child conversation that only sees the objective, its own instructions, short summaries of earlier steps and the files it needs, and verifies the result with checks the harness runs itself.
Maintenance: best-effort. Issues may go unanswered; forks are welcome.
plan_begin, plan_add_step (one call per step) and plan_show. A step that would exceed 60 %
of its model's context window is refused, so it has to be split. The plan is also saved as
PLAN-<name>.md.read, read-shell (read-only shell commands only), write
(files, limited to the step's declared outputs) or full,Summary / Files / Decisions / Open questions).exists: <path>,
contains: <path> :: <text>, words: <path> >= <n>, count: <glob> >= <n>,
command: <shell command> (exit 0 = ok). Important steps also get a read-only reviewer that
ends with VERDICT: OK or VERDICT: PROBLEMS - ....for_each steps run once per file or item, each in a short conversation, and write one result
file per item. Steps marked stop pause the run so you can check the result.State is kept in <working folder>/.plan-<name>/state.json (readable by humans) and an index of
plans per conversation in <DSH_HOME>/plan-runner/index.json. Files a step overwrites are backed up
under .plan-<name>/backups/.
Steps cannot ask for approval (DSH rejects approval requests in a subagent): an action the conversation's permission mode does not allow without asking is refused and the step fails. For steps that write, put the conversation in an auto or workspace-write mode.
dsh plugin --profile web add dsh-plan-runner
# or straight from GitHub:
dsh plugin --profile web add github:MathieuPortmann/dsh-plan-runner
Restart the profile afterwards. The bundle adds its own
Plan preset (id plan); do not combine it with another bundle that defines a preset with the
same id.
Row plan-runner in your profile's cordis.patch.yml; every key is optional.
- id: plan-runner
config:
models: # models a step may use; empty = the plan conversation's own model
my-local-model:
provider: ollama
window: 32768 # context window in tokens
description: good reasoning, slow # shown to the Plan agent
defaultModel: my-local-model
splitModel: my-local-model # proposes the finer split after two failures
auditModel: '' # reviewer of important steps ('' = the step's own model)
pauseOnBattery: false # pause the run on battery power
ollamaUrl: http://127.0.0.1:11434
commandTimeoutMs: 120000 # timeout of `command:` checks
loopRepeats: 3 # identical tool calls in a step that count as a loop
When a model's provider is ollama, the run pauses if ollamaUrl stops answering. Token budgets
use basePromptTokens, outputReserve, unknownFileTokens, itemOutputTokens and
summaryTokens (defaults tuned for 32k windows).
| Component | Supported |
|---|---|
| Node.js | ^22.19.0 || >=24.0.0 (engines.node) |
| DSH | >=0.2.0-rc.2 <0.3.0; declared as optional peerDependencies on @deepseek-ai/dsh-llm and @deepseek-ai/dsh-tools, the only DSH packages the plugin imports |
| Platform | Linux (tested); pure JavaScript, no native addon. command: checks need a POSIX sh |
Tested with DSH 0.2.0-rc.2 on Node 22.23 (see Verification).
Everything the plugin can touch, and what happens when it fails:
| Capability | Where | Used for | If it fails |
|---|---|---|---|
| Files (read) | lib/checks.js, index.js | exists / contains / words / count checks, file sizes for the token budget, /sys/class/power_supply (only with pauseOnBattery); every path is resolved inside the working folder | the check fails or the file counts as missing |
| Files (write) | lib/store.js, lib/plan-file.js, index.js | <cwd>/.plan-<slug>/state.json and backups/, <DSH_HOME>/plan-runner/index.json, PLAN-<name>.md in the working folder; a step's own result files are written by the step's child conversation, restricted to its declared outputs | the plan stays in its previous state |
| Commands | lib/checks.js (spawn('sh', ['-c', …])) | command: checks, written by you or by the Plan agent, run in the working folder with a timeout (commandTimeoutMs); the Plan agent is told to keep them read-only | a timeout kills the command and its children; the check fails |
| Network | index.js (fetch) | only GET <ollamaUrl>/api/tags when a step uses an ollama model | an unreachable server pauses the run |
| Dynamic module loading | index.js, lib/plan-tools.js | loads @deepseek-ai/dsh-llm and @deepseek-ai/dsh-tools from the DSH installation that runs the plugin (a synchronous require of an ES module fails on Node 22); nothing is downloaded and no code is evaluated from text | both are required: the plugin fails to load without them |
| Subagents | index.js (ctx.subagents) | one child conversation per step, with a tool filter per access level (read, read-shell, write, full) | the step fails and follows the retry rule |
The plan state is plain JSON under .plan-<slug>/; delete the folder to forget a plan.
Checked on a disposable profile (DSH_HOME pointing at a temporary folder, profile cloned with
dsh <name> --from-default-profile web, so the real profile is never touched):
npm pack
dsh plugin --profile t add file:$PWD/dsh-plan-runner-0.1.1.tgz # install
dsh --profile t --no-open --port 3095 # start: plugin loads, no error
npm test runs 42 standalone tests (state, parsing, checks, store, runner, scope guard,
read-only shell, config) with no DSH installation needed. A real run with a 9B local model created
a plan with plan_begin / plan_add_step, ran its step in a child conversation and verified the
result with a words: check.
npm test
MIT