@wweir/dsh-advisor

dsh plugin --profile web add @wweir/dsh-advisor

@wweir/dsh-advisor

[English](README.md) | 简体中文

DeepSeek Harness 会话的自动第二意见。

按可配置的步节奏，一个受限子 Agent 用只读工具重读 Executor 近期的工作。具体缺陷

被记录并投递进 Executor 的收件箱；没有可指出的问题时审查方保持沉默——沉默是正常结果，

不是失败。

本插件从不运行自己的模型循环：审查是一个真实的子会话，宿主的 turn/step 状态机、

工具管线、流式输出、取消与持久化原样适用于它。

它能帮你什么

• 抓住幻觉。 审查方亲自读文件（只读）：声称改了但没改的、不存在的 API、从未写

入的值。备注在工作还新鲜时指出具体不符；投递是建议性的，只在配置的程度上打断。

• 让会话不走偏。 每 N 个完成的步最多审查一次（默认 8），绝不并发——审查期间

到来的步边界留到下一次节奏，不叠加审查。一步 = 一次模型调用加上它跑的工具，所以

一个计数器同时覆盖长 turn 内的工作与分散在多个短 turn 的工作；everySteps: 0

关闭自动审查。跑偏在运行中的 turn 内被报告；空闲会话可被严重问题唤醒（有预算、

按严重度门控）。沉默被报告为结果，而不是错误。

• 成本有界。 审查方的上下文是编译出来的两区投影，绝不是 Executor 上下文的副本。

提示词上限取「运维配置的 maxContextTokens（默认 64K）」与「审查模型自己的窗口

扣掉宿主 preamble、该模型的输出预留和余量」中较小者；连一次最小审查都装不下的路由

会被带着这些数字拒绝，而不是溢出成宿主压缩。这个检查的准确度取决于路由广告的信息：

不报窗口的路由只按运维上限跑，因为插件手里只有这一个数字。边界之后是「上次得出结论

（沉默或发现问题）的审查之后的工作」，其证据按「审查方能不能自己重新取得」分级：

Executor 的可见声明保留，工具调用保留名字与参数（shell 命令截到 600 字符、改动截到

2,000），审查方自己能重跑的读文件/搜索（read/grep/glob）降为路径与体积，shell 结果

降为状态、少量失败行与尾部，其余结果——edit、工具报错、ls、MCP、子代理、job——保留

正文，每行消息上限 4,000 字符。边界之前是已审工作的轨迹，工具结果正文省略——提示词

会说明这一点，因为「省略」不能被读成「没执行」。

不投递 Executor 的 reasoning，那是意图而不是证据。往次审查的结论作为有界区块一并

发送，避免重复调查已经判过的内容。边界行带每次审查新生成的随机串，正文里引用的同样

措辞冒充不了它。稳定的指令前缀让 provider 的上下文缓存跨次命中（tab 显示命中缓存的

token，按缓存价计费）。输出仅一条建议，最多 2K 字符。

为什么是这个形态

大多数 advisor 插件把 transcript 交给一次额外的 LLM 调用，然后把返回内容直接注入。

本插件把审查方做成一个自带只读工具的真实子会话，这带来四样具体的东西：

• 它靠读来核实，而不是猜。 审查方打开 Executor 实际动过的文件，因此每条备

注指向的是它亲自查看过的缺陷——而不是从 transcript 摘要里推断出的模式，那只会

复读 transcript 里已有的内容。

• 宿主的规则对审查本身生效。 turn/step 记账、工具管线、流式输出、取消、持久化

以及真实的审计轨迹：审查就是一个可以像其它会话一样检查的会话，它的成本是上报的

用量，不是估算。

• 隔离是被强制执行的，不是承诺。 每个进程一份审查者认领、只读工具面、比上游

advisor 有意更严的受保护路径守卫（工作区根的私钥和 .envrc 同样在禁列），且与

Executor 不共享任何上下文。

• 投递是有记账的。 followup 备注只有在宿主证明它被处理过之后（那个 turn 的

模型回复）才计入已投递；未确认的备注会重新入队，绝不悄悄丢弃；交进运行中 turn 的

备注在交接时即记账。重复按 finding 身份加相似度抑制，支持按 hash mute。

安装

本包是 Cordis 插件（dsh.bundle.patch → cordis.patch.yml），已发布到 npm（每次发布带

provenance 证明），安装方式与任何 profile bundle 相同：

dsh plugin --profile <profile> add @wweir/dsh-advisor

也可以用本地 checkout 的路径 dsh plugin … add /path/to/checkout 以 link: 方式安装；

其部署方式见 docs/OPERATIONS.md。

然后给它一条模型路由。未配置模型前它处于禁用状态，且绝不回退到 Executor 的模型：

- id: advisor
  name: '@wweir/dsh-advisor'
  config:
    enabled: true
    model:
      provider: opencode-go
      model: glm-5.3-flash
      reasoningEffort: low
    instructions: ''            # 追加到审查提示词末尾的额外指令
    review:
      everySteps: 8             # 两次审查之间最少间隔的完成步数（0 = 关闭）
      timeoutMs: 180000         # 单次审查的墙钟上限
      maxContextTokens: 64000   # 送审提示词上限（模型窗口可再压低它）
      maxAdviceChars: 2000      # 单条建议正文上限
      maxPending: 32            # 排队中、尚未投递的备注上限
    delivery:
      activeIdleSeverities: [concern, blocker]   # 允许唤醒空闲 Executor 的严重度
    security:
      additionalProtectedPaths: []      # 审查方永远不许读取的额外路径

patch 条目按行 id 整体替换、不做合并：一个只设了追加指令的 overlay 会丢掉模型

路由，该行因此以禁用状态加载；只有 overlay 同时要求 enabled: true 时，才会以校验

错误响亮报错。

值得了解的行为

• 触发——只有一条节奏：一个完成的步（一次模型调用加上它跑的工具）。步是宿主的

进度单位，同一个计数器既覆盖长 turn 内的工作（几十步都不跨回复边界），也覆盖分散在

多个短 turn 的工作；不存在第二个按回复计数的间隔去和它打架。自上次审查结束以来

累计满 everySteps 步（默认 8）即触发一次审查。游标在审查结束时推进，因此慢审查不会

立刻接力下一次；计数器与游标都是绝对值并持久化，重载会延续节奏而不是把已累积的步

一笔勾销。新会话要攒满一个完整节奏才首审，不再“首轮立即”。turn 的最终回答本身不触发

审查：产生它的那些步已经有过机会，因此在节奏未满时结束的会话，其尾部会由后续步来审。

子 Agent 会话（包括审查子会话本身）永远不会被审查；本插件自己打开的 turn 同样不会

被审查。

• 审查子会话的边界——一次审查就是一次有界尝试：最多 5 次读取/搜索，再多的调用会被

拒绝并附上「用已有证据收敛」的理由；墙钟走到 timeoutMs 的 70% 时注入一次收敛引导

（沉默仍然是合法结论）；到点则取消子会话并记为失败。失败的审查不推进入审边界，材料

由下一次审查重读；游标仍推进，所以坏路由不会每个 step 都重试一次。

• 投递——Executor 运行中时，备注被交进下一个 step 边界；空闲时，备注可以开一个

独占 turn，但只有允许唤醒空闲会话的严重度才可以（默认 concern 与 blocker），每个

会话最多 5 次；其余情况等待后续 flush。交进运行中 turn 的备注在宿主接受后即记为

已投递。开了独占 turn 的备注只在那个 turn 产生模型回复之后才记账：交接本身不

能证明备注被读到，因此一个没有回复就关闭的 turn（重启、打断、空 turn）会把备注放

回队列，标记为已尝试过——它不会再开第二个 follow-up turn，但下一个运行中的 turn

仍可收到它。确认会立即持久化；加载时在 sidecar 里发现未确认的声明，也按同样方式

重新入队。已投递的 finding 按身份抑制，换措辞重复不会被重复投递。

• 失败暂停——连续三次真实失败（模型错误、超时、工具面错误）暂停自动审查。

取消单独计数：有记录但永不触发暂停。暂停是冷却而不是闩锁：先停一分钟，到期后放行

一次探针审查；探针也失败则冷却翻倍，上限三十分钟。瞬态故障因此会自行恢复，坏路由最坏

每半小时只浪费一次尝试，而不是每步重试。显式的 /advisor resume（页面横幅上同一个

立即恢复按钮）可以立刻结束冷却；在表单里保存配置或插件重载同样会重新武装。每次

触发暂停都会连同重试延迟写进宿主日志，/advisor status 会报告剩余冷却。

• 状态——每个 Executor 会话一个 JSON sidecar，位于

$DSH_HOME/advisor/（默认 ~/.dsh/advisor/）。其中保存步计数器及其游标、去重表、

待投递队列、mute 列表，以及作为诊断的失败记账。无法解析的文件永不被覆盖，并会在宿

主日志里报告。

• Mutes——向 sidecar 的 mutes 列表添加

{ "hash": "<64-十六进制 finding 的 hash>", "label": "..." }。身份以完整 hash

为准，没有前缀匹配。

• 页面——web 客户端在 Chat/Trajectory/Host 旁显示 Advisor tab。它通过 GUI

自身的认证通道读取与 /advisor status 相同的状态（该边界见

docs/OPERATIONS.md），每

几秒刷新一次，无需输入命令即可看到暂停的 advisor 以及上次沉默的原因。展示层只有一

条注入样式表、基于 DSH 主题 token，因此明暗主题、焦点、悬停与触控尺寸都跟随宿主；

区块是带标签区域里的标题，轮询状态同时镜像到 polite live region 供屏幕阅读器使用。

它的队列区块就是投递面，按「读者要动手的顺序」排：先是投递状态——待投递备注连同队首

备注被挂起的原因（executor 运行中、严重度不允许唤醒空闲会话、followup 预算耗尽、

上一次尝试未被处理、更新的指令到达），followup 交接后等待确认的备注，以及**已交入

收件箱、等下一步边界承接**的备注（连投递正文一起显示；聊天里在承接前看不到它）——然后

是一行弱化的累计量：只显示本会话真正计数过的东西（已投递、已 mute、花掉过的空闲

followup，旁边是宿主上报的预算；从未用过的预算不算值得一画的数字）。队列为空时用一句话说明，而不是画一排 0。它还承载日志里没有的每会话审查记账，同样是一行一

件事：审查方读到的提示词总量及其缓存命中占比、输出量、审查次数与平均耗时、只列真正

发生过的结果，以及有界的、最新在前的审查与投递历史。它也编辑常用配置——开关、模

型路由、审查节奏与各项预算、空闲投递严重度和额外审查指令——保存即应用到运行中的

reviewer。配置行仍是默认值；页面编辑作为 override 层持久化，校验用的是比加载

schema 更严的页面上界（后者只限下界）；受保护路径设置归配置行所有，行里的值若超出

页面上界会拒绝保存，而不是写出一份下次加载会被整体丢弃的 override 层。Provider、模型与推理等级是由宿主实时模型注册表

驱动的联动下拉框（GUI 模型选择器读的是同一来源）：选了 provider 就把模型指向它

的第一项，档位列表是所选模型广告出来的档位——「默认」始终可用，注册表未广告但已

配置的值也保持可表示，使表单可以往返；若某个模型广告的档位本插件一个都提供不了，

就只显示「默认」而不再回退静态列表，而注册表里完全没有档位信息的模型仍回退到它。档位归属路由而非独立存在：未选 provider/

model 时其控件不可用并显示「默认」，因为不带模型路由的配置会丢掉它。模型注册表

无法列出的宿主会让表单退回之前的纯文本 provider/model 输入。无论哪种情况，表单都

拒绝会撒谎的保存：半填的路由，「清空路由」（页面无法表达后者，因为不带模型路由的

配置会保留行的路由），以及在没有路由时启用审查——宿主对合并后的配置校验这条

不变式，否则页面会报告保存成功，而这份配置什么都不审。数字字段在本地按持久化行的

上下界校验，空框或行里存不下的值会报在它自己的字段上，而不是以宿主字段路径的形式回来。

路由装不下的上限则——低于 4K tokens 的证据下限，或大于模型窗口扣掉 preamble 与

输出预留后的余量——由宿主带全部数

…(truncated)