dsh-plan-router

August 15, 2026 · View on GitHub

license stars

DeepSeek Harness（DSH）插件：多模型「计划 / 验证 / 编码」分工闭环。

用「计划模型」（贵模型，可识图）产出实施计划 + 可验证的验收标准；
用「读取模型」（便宜模型）先压缩仓库上下文，只把高密度简报喂给计划模型，省 token 省费用；
用「验证模型」（独立评审模型，可识图）对照「验收标准 vs 当前实现」（含截图）输出修改建议；
编码仍由当前会话模型（如 deepseek-v4-pro）执行。

组成

名称	类型	作用
`plan_draft`	模型工具	需求 + 上下文 →（读取模型压缩）→ 计划模型 → Markdown 计划。每个编号步骤带「本步验收」检查点，结尾另有总验收标准；简报不足时返回「计划草稿 + 补料清单」，二次调用（skipCompression）原文直送出最终计划
`context_brief`	模型工具	随时用读取模型压缩任意上下文（计划、编码阶段都可用）
`verify_impl`	模型工具	验收标准 + 实现证据（+ 截图路径）→ 验证模型 → verdict + 逐条修改建议，返回 token 用量
`/plan-route <需求>`	斜杠命令	把「计划 → 分步实现 → 每步验证 → 总体验证」分阶段闭环提交给当前 agent

原理

用户需求
   │  agent 用 read/grep 收集原始上下文（免费）
   ▼
[读取模型（便宜）] ──压缩──▶ 高密度简报        ← 仅当 context 超过 minInputChars
   │
   ▼
[计划模型（贵）] ──plan_draft──▶ 最终计划：每步带「本步验收」+ 总验收标准
   ▲        │ 若简报不足：返回「计划草稿 + context-requests 补料清单」
   │        ▼
   │  agent 按清单取回原文 ──plan_draft(skipCompression=true)──▶ 原文直送计划模型
   ▼
[当前会话模型] 分步实现：每完成一步 ──自测/截图──▶ verify_impl 验证本步
   │        ▲                                    │ changes-needed → 修好本步再走
   │        └─────── issues 反馈（每步 ≤3 轮）────┘
   ▼
全部步骤完成 ──verify_impl 总体验收──▶ verdict=pass 收尾

计划模型只看到压缩后的简报，而不是几十个文件原文 → 输入 token 大幅下降；
补料机制：简报信息不足时，计划模型主动列出需要原文的文件/模块，agent 取回后二次调用（跳过压缩、原文直送），兼顾省钱与保真；
分阶段验证：计划模型在每个步骤写入「本步验收」检查点，agent 每完成一步立即验证——长程任务的问题在当步暴露，而不是堆到最后；
验证模型只看「验收标准 + 实现证据（+截图）」，只评审不改代码 → 独立质量关卡；
模型凭证全部复用 DSH 凭证库（Settings → Models 里配好的 key），插件自身不管 key；
每次调用返回各模型的输入/输出 token 数，方便核算成本。

安装

在 patch 层插入条目（见 cordis.patch.example.yml）：

- insert:
    - id: plan-router
      name: '/绝对路径/dsh-plan-router/src/index.ts'
      config:
        planner:  { provider: <计划模型路由>, model: <计划模型 id> }
        reader:   { provider: <便宜模型路由>, model: <便宜模型 id> }
        verifier: { provider: <验证模型路由>, model: <验证模型 id> }

推荐写进 profile 级 ~/.dsh/profiles/web/cordis.patch.yml（对 web 生效），或启动时 npx @deepseek-ai/dsh web --patch <文件>；
provider 必须是 Settings → Models 里已配置的路由名（llm-pi-ai.providers.* 或 deepseek-official 这类目录路由），配错会在调用时报出可用路由列表。

重启 dsh web（插件在启动时加载，运行中修改配置不会热生效）。

从源码安装（GitHub）

git clone https://github.com/unable-splanck/dsh-plan-router.git
cd dsh-plan-router
npm install          # 安装 @deepseek-ai/dsh-* 与 playwright-core（npm 缓存不可写时加 --cache /tmp/npm-cache）

然后把 patch 条目里的 name 指向克隆后的绝对路径（<clone目录>/src/index.ts）即可。

使用

完整闭环：/plan-route 添加用户登录功能
只出计划：用 plan_draft 给「添加用户登录功能」出个计划，先读一下 src 里相关代码作为 context
补料二轮（agent 自动处理，也可手动）：用 plan_draft 细化：context 填取回的原文，skipCompression 填 true
编码阶段压缩大文件：用 context_brief 总结 docs/api.md 里和认证相关的部分
单独验收：用 verify_impl 验收：expectation 填验收标准，implementation 填改动与测试结果

给验证模型传截图（UI 类任务）

截图脚本（playwright-core + 本机 Chrome，零下载）：
```
node dsh-plan-router/scripts/screenshot.mjs http://localhost:5173 /tmp/home.png 1440 900 2000
```
没有 Chrome 时：npm i -D playwright && npx playwright install chromium，再用 PW_CHANNEL=chromium 运行。
验证模型要能收图：在 ~/.dsh/settings.yaml 里给该模型加 input: [text, image]：
```
- id: <你的验证模型 id>
  name: <显示名>
  input: [text, image]
```
否则 DSH 会在发请求前拒绝图像（手填模型默认 text-only）。
调用时把截图路径放进 screenshots 数组（建议绝对路径；相对路径按会话工作目录解析）。

配置项

键	默认	说明
`planner.provider` / `planner.model`	必填	计划模型路由与模型 id
`planner.systemPrompt`	内置架构师提示词	覆盖计划提示词（含验收标准要求）
`planner.maxTokens`	12000	计划输出上限
`planner.timeoutMs`	300000	超时（ms）
`planner.maxContextChars`	200000	简报/上下文硬上限，超出截断并告知模型
`reader.provider` / `reader.model`	可选	不配 reader 时上下文原文直送计划模型
`reader.minInputChars`	4000	上下文超过该字符数才启用压缩
`reader.maxTokens`	4000	简报输出上限
`reader.timeoutMs`	120000	超时（ms）
`verifier.provider` / `verifier.model`	可选	不配 verifier 时 verify_impl 调用报错并提示配置
`verifier.systemPrompt`	内置评审员提示词	要求输出 JSON：verdict/summary/issues
`verifier.maxTokens`	4000	评审输出上限
`verifier.timeoutMs`	120000	超时（ms）

未知配置键、非法值都会在启动时直接报错（fail loud），不会静默忽略。

验证

# 1. 不启动服务，检查插件是否进配置树（应能看到 plan-router 及你的配置）
dsh --profile web --dump-config --patch cordis.patch.example.yml | grep -i -A 20 plan-router

# 2. 启动后在会话里让模型调一次：
#    “调用 plan_draft，requirement 填‘给 README 加一个徽章’，context 留空”
#    返回里应带 token 用量统计。

排障

工具不存在 / UNKNOWN_TOOL：patch 没生效 → 重启 web；--dump-config 里看不到 plan-router → 检查 name 是不是绝对路径。
报 provider 未注册：Settings → Models 里没有该 provider，按报错里列出的可用路由改配置。
报 UNKNOWN_MODEL：模型 id 与 settings.yaml 里登记的不一致（pi-ai 会校验模型目录）。
启动报 未知配置键：检查 config 键名拼写（planner / reader / verifier / provider / model / …）。
输出到 maxTokens 上限：调大 planner.maxTokens。
传截图报不支持/无法读取：路径、扩展名（png/jpg/webp/gif）、或模型没声明 input: [text, image]。

已知限制

配置修改需重启生效（DSH 插件在启动时加载）；
读取模型的压缩质量 = 简报质量上限：极敏感的细节（精确常量、边界条件）建议由当前 agent 直接读原文确认；
验证模型的评审质量 = 反馈质量上限：expectation 越具体（颜色/数值/行为），反馈越准；
计划、读取、验证模型必须都在 DSH 的模型目录里（Settings → Models）。