leeyoung1/dsh-advisor-plugin

DeepSeek Harness 的 advisor 策略模式插件：让便宜快速的执行模型继续跑主线，在关键节点把整段会话交给更强的审查模型，拿回 plan / correction / stop signal 后继续执行。

dsh-advisor-plugin 解决的是一个结构性问题：同一个模型既写代码又验代码，很容易“证明自己是对的”。长链路 Coding Agent 常见的三类失效——自验证盲区、长程漂移、过早宣告完成——都可以用“独立第二意见”来缓解。

它提供两条互补通道：

• 显式咨询：执行模型零参数调用 advisor()，整段会话与工具清单自动转发给审查模型；
• 自动巡逻：每 N 步把会话快照发给审查模型，跑偏时在下一个请求注入纠偏，STOP 时要求执行模型停下向用户报告。

所有审查配置都在 DSH 设置页完成，不需要手改配置文件。

---

特性

• 总开关：设置页一键启用/关闭；关闭时不注册 advisor 工具与升级守则，已保存的模型配置保留。
• 可折叠配置：模型与推理档位、巡逻模式两个区块可分别收起/展开。
• 零参数 advisor() 工具：调用即自动转发整段会话，模型不需要组织上下文。
• plan / correction / stop 契约：审查模型只做判断，不碰代码、不直接改状态。
• compaction 感知：转发的是 session.deriveMessages() 的真实模型可见面，而不是过期原始历史。
• 稳定的工具清单前缀：按 agent scope 序列化，目标是命中 DeepSeek 前缀缓存。
• 巡逻模式：步数 + 90 秒墙钟节流 + patrolImmuneTurns 冷却 + emission-guard 去重，防止过度打扰。
• 只读调查工具：审查模型可先在工作区内 search_files / read_file 核实事实，再给建议。
• 失败隔离：审查调用失败、超时、空正文、上下文溢出都不会炸掉执行模型的 turn。
• 双降级：推理档位不支持时走模型默认档；上下文溢出时做配对安全截断后重试。
• 执行模型黑名单：disabledForModels 支持 model、provider/model、provider/model@effort 三种语法。
• 未武装零成本：没有配置审查模型时，工具和提示段都不注册。
• 可视化：设置页卡片、advisor() 咨询卡片、巡逻裁决灰/琥珀/红三形态卡片。

---

架构

src/                      # host 半（Node / Cordis 插件）
├── index.ts              # apply：组装工具/提示段/门控/巡逻/命令/设置
├── advisor-prompt.ts     # 咨询/巡逻两套系统提示 + 干预文本
├── config.ts             # schemastery schema + 武装解析 + 黑名单语法
├── tool.ts               # 零参 advisor 工具 + 专属卡片 + 结果信封
├── history.ts            # 工具清单 + deriveMessages + 尾部规则
├── llm-call.ts           # 审查调用 / sessionId 透传 / 降级 / 调查循环 / 回显剥离
├── patrol.ts             # 巡逻调度 / 裁决解析 / agent.inject 干预
├── patrol-event.ts       # 巡逻裁决写入会话事件
├── emission-guard.ts     # 归一化 / 空话过滤 / FIFO 去重
├── settings.ts           # settings 命名空间接入与活编辑
├── gating.ts             # 按 agent 隐藏 advisor 工具
├── prompt-section.ts     # 升级守则提示段
├── command.ts            # /advisor 命令
└── client/               # 浏览器半
    ├── index.ts          # 注册设置卡片 / 工具行 / 巡逻卡片
    ├── controller.ts     # 设置暂存编辑 + 模型目录
    ├── AdvisorCard.tsx   # 设置页卡片
    ├── AdvisorToolRow.tsx
    ├── PatrolNodeView.tsx
    ├── patrol-chat.ts
    ├── locales.ts
    └── store.ts

docs/                     # 技术文章与架构图
scripts/                  # 本地开发辅助脚本

完整模块说明见 docs/。

---

安装

1. npm 安装（推荐）

dsh plugin --profile web add dsh-advisor-plugin

安装后重启 dsh web。

2. 本地开发安装

git clone https://github.com/leeyoung1/dsh-advisor-plugin.git
cd dsh-advisor-plugin
npm install
./scripts/link-deps.sh
./scripts/mount.sh

link-deps.sh 会把本机 DSH 携带的官方包链接进 node_modules，供类型检查和测试使用；mount.sh 会构建并挂载到本地 web profile。

注意：npm install 会清掉手工链接的 @deepseek-ai/* 包，重装依赖后需要重新执行 ./scripts/link-deps.sh。

3. Git 直接安装（开发）

dsh plugin --profile web add github:leeyoung1/dsh-advisor-plugin

---

快速开始

1. 打开 设置 → 插件，找到 Advisor 审查模型 卡片；
2. 选择一个比执行模型更强的审查模型，按需设置推理档位；
3. 按任务类型决定是否开启巡逻模式；
4. 保存后，执行模型在任务开始前、卡住时、宣告完成前会自动调用 advisor()。

也可以在会话里执行 /advisor 查看当前配置和可用 provider/model。

配置示例

~/.dsh/settings.yaml：

advisor:
  enabled: true
  provider: example-provider
  model: reviewer-model
  effort: high
  patrolEnabled: true
  patrolEverySteps: 6
  patrolImmuneTurns: 3
  investigate: true
  disabledForModels:
    - deepseek-v4-pro
    - gpt-5.2@high
  guidelines: []

provider + model 齐备才会武装；未配置时 advisor 工具对模型不可见，零提示词成本。

---

两条通道

显式咨询

执行模型 ──advisor()──▶ 上下文组装 ──▶ 审查模型
   ▲                                      │
   └──── plan / correction / stop ◀───────┘

适用时机：

• 实质性工作开始前；
• 反复卡住、方向不收敛时；
• 证据与建议矛盾时；
• 宣告完成前。

自动巡逻

agent/request ──每 N 步──▶ 快照 ──▶ 审查模型
                                      │
                ON-TRACK / CORRECTION / STOP
                                      ▼
                    会话事件卡片 + agent.inject() 注入下一请求

巡逻不会打断在飞 turn，干预最早落在下一个模型请求。

---

依赖要求

• Node.js ^22.19 或 >=24
• DeepSeek Harness（web profile）
• 已配置至少一个可用的 provider / model 作为审查模型

兼容性

• 目标 DSH：0.1.5-rc.1 / 0.1.5-rc.2；不承诺更早的 rc / alpha 版本。
• Node.js：^22.19 或 >=24。
• 安装方式：请使用 dsh plugin --profile web add dsh-advisor-plugin；裸 npm install 会撞 DSH 官方包的 peer 依赖，这不是插件本身的问题。

两条通道

显式咨询

执行模型 ──advisor()──▶ 上下文组装 ──▶ 审查模型
   ▲                                      │
   └──── plan / correction / stop ◀───────┘

适用时机：

• 实质性工作开始前；
• 反复卡住、方向不收敛时；
• 证据与建议矛盾时；
• 宣告完成前。

自动巡逻

agent/request ──每 N 步──▶ 快照 ──▶ 审查模型
                                      │
                ON-TRACK / CORRECTION / STOP
                                      ▼
                    会话事件卡片 + agent.inject() 注入下一请求

巡逻不会打断在飞 turn，干预最早落在下一个模型请求。

---

依赖要求

• Node.js ^22.19 或 >=24
• DeepSeek Harness（web profile）
• 已配置至少一个可用的 provider / model 作为审查模型

兼容性

• DSH 版本：peer 范围覆盖 0.1.0-rc.6、0.1.1-rc.2、0.1.2-rc.1、0.1.3-alpha.1；已在 0.1.1-rc.2 上实机验证。
• 配置向后兼容：旧配置没有 enabled 字段时默认 true，不影响升级。
• 关闭总开关：enabled: false 时保留已保存的模型配置，但不注册工具与升级守则。
• 安装方式：请使用 dsh plugin --profile web add dsh-advisor-plugin；裸 npm install 会撞 DSH 官方包的 peer 依赖，这不是插件本身的问题。

开发验证：

npm run typecheck
npm test
npm run build

当前测试：7 个测试文件、59 个用例通过。

---

文档

• 文档索引
• 技术文章：DeepSeek Harness 插件实战：我给 Coding Agent 请了个“随车专家”
• 架构图
• 双通道时序图

---

设计取向

• 执行与判断分离：执行模型负责推进，审查模型负责判断。
• 建议权不等于执行权：advisor 只输出建议，不替执行模型做决定。
• 按需升级：强模型只在关键节点出现。
• 防御性工程：降级、截断、重试、防噪、冷却、失败隔离。
• 宿主原生：复用 DSH 的模型路由、凭据、设置页、会话事件与 UI 槽位。

灵感来源

• Anthropic: The advisor strategy
• oh-my-pi advisor/watchdog
• rpiv-advisor

常见问题

DSH Desktop 报 cannot resolve package "dsh-advisor"

这是 0.2.1 的旧 bundle patch 导致的：那个版本的 cordis.patch.yml 仍然引用旧包名 dsh-advisor。0.2.2+ 已经改成 dsh-advisor-plugin。

1. 先从对应 profile 移除旧安装（DSH Desktop 通常是 desktop profile）：

   dsh plugin --profile desktop remove dsh-advisor
   dsh plugin --profile desktop remove dsh-advisor-plugin
   

2. 安装最新版本：

   dsh plugin --profile desktop add dsh-advisor-plugin@latest --registry=https://registry.npmjs.org
   

3. 验证 profile 组合结果：

   dsh --profile desktop --dump-config | grep -A3 dsh-advisor
   

   期望看到：

   # == dsh-advisor-plugin
   - id: dsh-advisor-plugin
     name: dsh-advisor-plugin
   

4. 如果 profile 的 cordis.patch.yml 里还残留 - id: dsh-advisor / name: dsh-advisor 行，删掉那一行再重启。

License

MIT