第二意见审查 wweir/dsh-advisor

@wweir/dsh-advisor

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 与输出预留后的余量——由宿主带全部数字拒绝，因为只有宿主知道该路由的窗口。
- 编译后的审查上下文——审查模型读的不是 Executor 自己的上下文，而是两区投影，默认以 64K tokens 为界（并受该路由窗口再压低）。因此「会话」区块报四件事：这份提示词有多大、被限到多少预算、预算在新工作与已审轨迹之间怎么分，以及预算不够时被裁掉的是哪一个区。页面不再提供提示词查看器——原先那段分段预览对这个很少翻看的诊断面来说只是交互噪音——但 GET /api/advisor/context?sessionId=… 仍按需返回完整提示词。
- 状态面——/advisor [status] 报告调用者自己会话的状态：生效的路由、当前 turn、是否有审查在进行、最近审查过的 turn 以及它为什么没有产出备注（沉默、被抑制为 muted 或已投递、失败或取消）、待投递队列及其严重度和队首挂起原因、等待 followup 确认的备注、已交入收件箱但尚未被 step 承接的备注数、followup 预算、失败记账。沉默被报告为结果而非错误，否则「审查方找不到能指出的东西」和「插件没在跑」这两种情况无法区分。这里只有 status 一个问题；从旧版本带过来的 on/off/model/config 动词会被明确拒绝而不是应答，以免旧习惯被误读为成功。

投递备注的呈现

审查备注以一条归属 advisor 的聊天通知投递。Executor 运行中投递时，它渲染为已带一行摘要（关注 · 仍适用 · …）的折叠上下文行。Executor 空闲时投递会唤醒一个 turn，于是聊天画出它的 turn-trigger 卡片——而上游这张卡片没有 advisor 分支：它会退化为通用的 "Execution requested" 标题且不显示摘要，备注在被点开前不可见。

本地客户端补丁 ~/.wweir/bin/dsh-patch-advisor-note（由 ~/.wweir/bin/dsh-install 重新应用）给 vendored 的聊天 bundle 补上缺失的分支：卡片显示「二审提醒」/ "Advisor review"，折叠行显示记录的严重度与摘要，展开时渲染备注正文本身。它是对 vendored 文件的修改，因此 DSH 升级会将其丢掉，直到再次运行 dsh-install。

验证

pnpm run verify # typecheck（src + tests）、client 语法、测试套件、宿主构建
pnpm run build # tsc: src/ -> lib/，被 link 的 profile 加载的就是它

本包遵循 DSH 插件形态：宿主入口是 lib/index.js（从 src/index.ts 构建），web 半部是 client/index.js 的手写 bundle，dsh.bundle.patch 指向 cordis.patch.yml。link 的 checkout 如何部署（含免重启热重载与验证标记）见 docs/OPERATIONS.md。

测试覆盖纯 policy 层，以及通过 fake port 驱动的运行时（17 个文件）；完整链路需要一个 长驻 app——部署方式与这一约束见 docs/OPERATIONS.md。

已知限制

- token 数字是审查子会话聚合 step 的 provider 上报用量。建议记录即被中止的那个 step 可能不会上报用量，因此一次审查的成本可能被略微低估。

- 受保护路径守卫判定的是读工具寻址的路径。以子目录为根的搜索工具仍可能返回该子目录内受保护文件的内容（例如仓库里的 .env）；搜索根禁令覆盖工作目录本身，结果脱敏是第二道防线。
- 页面把它的配置持久化为页面自有的完整投影，因此重启后 tab 显示的内容可复现。该集合之外的字段（队列容量、受保护路径）仍归配置行所有，无法从页面修改。

- 日志重写/compaction 时的延迟建议失效未实现；已得出结论的审查所推进的边界只存在进程内存里，因此重载后下一次审查会把整份 transcript 视为新工作（多读一些，绝不漏读）。
- 审查方通过 Executor 自己的 agent-preset 组合读文件，因此远程资产文件工具不在它的能力面上：经由远程命名空间完成的工作无法通过读文件来核实，这类审查保持沉默，而不是对一个不同的文件系统下判断。受保护路径守卫经由文件系统工具所用的同一宿主服务解析路径。
- 宿主接受但没有变成 turn 的 followup（例如 agent 已在关闭中）会让备注保持等待确认 的可见状态，而不是谎报已投递；下一次插件加载时它会重新入队。
- 交进运行中 turn 的备注在交接时即记为已投递；页面的「在途」行只是进程内展示状态（插件重载会忘掉它），它证明消息已进入收件箱，承接由同 id 的 user/message 事件证实。若 agent 在承接前被归档（清空 inbox），备注会记为已投递却从未被读；进程退出则不同——持久化 inbox 会在恢复后的下一个 turn 投递它。
- 审查子会话是真实会话（审查内容审计轨迹），但 web 会话列表会隐藏以子代理身份创建的会话，因此审查永远不会以游离行的形式出现在那里。

运行与部署见 docs/OPERATIONS.md · 关键决策见 docs/DECISIONS.md。