@wweir/dsh-advisor

English | 简体中文

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  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。