dsh-advisor
English | 中文
 
为 DeepSeek Harness 提供独立模型 advisory 审查。
每个工具执行步之后，由独立的审查模型审计 agent 最近的操作。发现真实问题时（破坏性/不可逆操作、契约/模式违规、偏离用户明确要求、正确性 bug），向下一轮模型调用注入一条简短的 [advisor] 指导消息，让 agent 自我纠正。操作健全时什么都不注入，审查只消耗一次（廉价的）审查调用。
dsh 本身没有内置 advisor；本插件基于标准的 agent/pre-step waterfall 实现（与 dsh-agent-instructions、dsh-compaction-basic 相同的注入通道）。
安装
dsh plugin add @slhssb/dsh-advisor或加入 profile 的 package.json：
"dependencies": { "@slhssb/dsh-advisor": "^0.1.0" },
"dsh": { "profile": { "bundles": ["@slhssb/dsh-advisor"] } }然后在 profile 目录执行 npm install（或 pnpm install）并重启 dsh。
配置
默认目标为 DeepSeek 官方 API（deepseek-official provider）与廉价的 deepseek-v4-flash 模型。API key 不由本插件管理：deepseek-official adapter 按请求从 DEEPSEEK_API_KEY 环境变量或凭据存储解析。
默认值无需覆盖——即 DeepSeek 官方 API（deepseek-official/deepseek-v4-flash）。要换审查 provider，在 profile 的 cordis.patch.yml 中覆盖（后写覆盖先写）。以下示例把审查路由到第三方中转：API key 由该 provider 的 adapter 解析（此处按 settings.yaml 的 apiKeyEnv 取 TOKENRHYTHM_API_KEY 环境变量）——本文件从不存放 key：
- id: advisor
config:
provider: tokenrhythm
model: deepseek-v4-pro
maxTokens: 512
maxHistoryMessages: 40
interval: 1
timeoutMs: 30000| 键 | 默认 | 含义 |
|---|---|---|
provider | deepseek-official | 审查 provider 路由（任意 OpenAI 兼容 adapter 可用）。 |
model | deepseek-v4-flash | 审查模型。 |
maxTokens | 512 | 审查输出上限。 |
maxHistoryMessages | 40 | 发送给审查模型的最新派生消息数。 |
interval | 1 | 每隔 N 个含工具结果的步审查一次（1 = 每步）。 |
timeoutMs | 30000 | 单次审查超时；超时静默降级。 |
行上加 disabled: true 可整体关闭；留空 provider/model 则回退到当前请求路由（agent/session 请求头，再退 agent options）。
规则（确定性检查）
除 LLM 审查外，rules 提供零成本、确定性的检查：用正则匹配最近一次工具调用（工具名 + 参数 JSON）。规则不会失败、不消耗 token；warn 规则向下一步注入 [advisor] Rule check: 消息，block 规则直接拒绝该步（显式开启，默认 warn）。
- id: advisor
config:
provider: deepseek-official
rules:
- id: no-recursive-delete
pattern: 'Remove-Item|rm\s+(-rf|-r\s*-f)|del\s+/[sq]'
message: '检测到破坏性删除命令，请确认目标路径与用户授权。'
action: warn # 或 block
tools: ['pwsh', 'bash'] # 可选：只对这些工具名生效
enabled: true # 可选，默认 true| 键 | 默认 | 含义 |
|---|---|---|
id | — | 规则标识（触发时记录日志）。 |
pattern | — | 大小写不敏感的 JS 正则，匹配 工具名 + 参数。 |
message | — | 注入文本 [advisor] Rule check: …。 |
action | warn | warn 注入提示；block 拒绝该步。 |
tools | 全部 | 可选：规则生效的工具名子串列表。 |
enabled | true | 禁用但不删除规则。 |
非法规则（缺字段、坏正则）会被跳过并记录警告；错误配置的规则永远不会阻塞 agent。多条 warn 命中合并为一条消息。block 在 LLM 审查之前触发——被阻断的步不跑审查。
工作原理
1. 每次模型调用前触发 agent/pre-step（waterfall）。 2. 插件扫描会话日志找最新的 tool/result 事件。没有，或其 seq 已审过，则放行本步。 3. 否则审查模型接收最近的派生历史 + 审查指令，流式返回。 4. 非空响应包装为 user 消息（source: { kind: 'plugin', plugin: 'dsh-advisor' }，文本带 [advisor] 前缀），插入本步 messages 的 claimed 消息之后、system context 之前——与 dsh-agent-instructions 相同的插入点，保证下一轮模型调用一定能看到。 5. 审查失败（LLM 错误、超时、空输出）记录 warning，不注入，并推进已审 seq 标记，同一批不会在下一步重试。agent 主流程永不被阻塞。
注入的 [advisor] 消息是普通 user/message 日志条目；它们永不产生 tool/result 事件，因此审查不会递归自触发。
开发
npm install
npx tsc -p tsconfig.json
node test/smoke.mjs # 手写 fake，无网络lib/ 已提交进 git（git 安装的消费者无需构建即可使用）；gitignore 只排除 node_modules/、test/smoke.mjs、package-lock.json。npm 发布经 files 白名单打 lib。
发布
已发布到 npm：@slhssb/dsh-advisor；仓库带 GitHub dsh-plugin topic 便于发现。发新版：改 package.json 的 version → 发布 → 打 tag：
npm publish --access public
git tag v0.1.0 && git push --tags