回答评审员 bycall/dsh-answer-reviewer

dsh-answer-reviewer

dsh 宿主插件：每当智能体准备结束一轮时，插件会提取助手最终面向用户的文本，交给一个专门的评审模型按 1-100 打分。如果分数低于配置的 threshold（默认 80），插件会把评审模型认为最重要的一条发现作为具体反馈，把智能体拉回同一轮继续。一轮被拉回 maxChallenges 次（默认 5）之后，助手的回复就按原样结束这一轮——这个上限只是防漏，真正的闸门是分数阈值。

调整闸门、开关评审、改最大拉回次数、指定专门的评审模型——全部实时生效，不用重启宿主。入口有：对话视图输入框上方圆环里的 Reviewer 配置 tab、可选的侧边栏 tab、自托管配置界面 http://127.0.0.1:3987，或者用 curl 调同一套 JSON API。之后每条被评审过的回答都会在消息操作栏里显示自己的评分徽标（见评分徽标）。磁盘上的配置放在 ~/.dsh/answer-reviewer.json（可用 REVIEWER_CONFIG_PATH 覆盖）；文件不存在时，宿主各轮按默认值走。

评审模型能看到用户在会话里发出的每一条真实用户提示词（任何 source.kind 不是 'plugin' 的 user/message 事件），标记为 <all_user_prompts>，外加助手最终回复，标记为 <reply>。插件注入的上下文（文件变更通知、AGENTS.md、技能内容、系统提醒）会被过滤掉，这样评审模型打分依据的是用户实际问了什么，而不是 harness 当时恰好带着的上下文。

配置了 reviewProvider / reviewModel 时，评审模型独立于智能体的工作模型；否则插件回退到智能体当前的路由，开箱即用。

分数不只是内部闸门——它会显示在被打分的那条回答上：

⤷ ⧉ ↻ 👍 👎 ● 评分 92 ← in the message's action row

评分徽标（自 0.7.0 起）

每条定稿的助手消息都会带上评审模型给它的分数，显示为消息操作栏里一个小色块徽标，挨着自带的复制/重试和 Like/Dislike 按钮：

| 判定 | 徽标 | 含义 |
| 过闸 | 绿色底 ● 评分 92 | score >= threshold；这一轮第一次看就结束了 |
| 低于闸门 | 琥珀色底 ● 评分 61 · 第2次 | 被拉回重试；徽标里的数字是最终算数的那次尝试 |
| 重试次数用尽 | 琥珀色底 ● 评分 55 · 第4次 | 仍低于闸门且 maxChallenges 已用完，所以没有再推回去（自 0.7.1 起） |

把鼠标悬停在徽标上，可以看到闸门、判定和评审模型自己的理由：

阈值 80 · 通过 · 第 4 轮回答回答了问题，但始终没有点出出错的文件。

设计说明：

- 它绑定到回答，而不是绑定到轮次。 分数记录在同一个持久消息 id 下，shell 交给操作行的就是这个 id（assistant/message → data.message.id），所以标签和门禁永远不会对某个分数属于哪个回答产生分歧。
- 没有分数时它什么都不渲染。 插件被禁用、没有评审路由、回复无法解析，或重试次数用尽，都会让这一行与原生 dsh 逐字节相同——没有占位符，没有加载指示器，没有预留空间。
- 重试可见。 被引导过的轮次会在最终通过的回答上显示 第2次，所以第三次尝试才通过的分数不会读起来像一次就过。失败的中间回答如果有自己的标签，就保留它。
- 最后一个回答总是带标签。 重试上限只让引导沉默，从不让评审沉默——一个 maxChallenges 用尽的轮次仍会发布它的最终分数，标记为 capped。否则用户实际读到的那个回答就会成为唯一没有分数的回答（在 0.7.1 中修复）。
- 颜色由宿主决定。 标签使用 dsh 自己的 --dsw-alias-state-success- / --dsw-alias-state-warn- token，所以它会跟随当前主题，没有本地调色板。

分数源

标签读取宿主在自己的 webserver 上挂载的同源 JSON 源：

GET /api/dsh-answer-reviewer/reviews → { entries: [...], at }

每个条目是 { messageId, score, threshold, decision, attempt, turn, reason, at }，最新的在前，最多保留最近 200 条分数。它通过宿主的 ctx.webServer.register(...) 注册，并受组合的连接围栏（Host/Origin 检查加上登录 token cookie）管控，所以页面无需任何 CORS 放宽就能读取它。127.0.0.1:3987 sidecar 刻意不授予跨源读取——那样做会让用户访问的任何网站都能读取并改写他们的评审器配置——但它确实在 /api/reviews 镜像了同样的负载，供 curl 使用。

为什么要用单独的模型？

评审模型使用严格的仅 JSON 评分提示词（{score, reason}），智能体从不直接看到它。评审结果会作为 user/message 注入回去，带有 source: { kind: 'plugin', plugin: 'dsh-answer-reviewer' }，所以智能体会把它们当作用户输入——但智能体被明确告知不要向用户提及评审。使用不同的服务商/模型能降低自评检查给自己工作盖橡皮图章的概率，而显式的数值门禁意味着一个调校良好的模型返回 80+ 就不会触发任何重新尝试。

实时配置（自 0.4.0 起）

插件启动一个微小的 node:http 服务器，绑定到 127.0.0.1:3987（无外部访问）。在浏览器中打开它，就能看到表单、磁盘上的配置路径，以及最近 15 次评审结果的滚动列表。同样的 JSON API 也能从 shell 访问：

Read current effective config + overrides + file path
curl -s http://127.0.0.1:3987/api/config

Tweak the threshold (only the fields you POST are written)

curl -s -X POST http://127.0.0.1:3987/api/config \
-H 'content-type: application/json' \
-d '{"threshold": 90}'

Disable the reviewer

curl -s -X POST http://127.0.0.1:3987/api/config \
-H 'content-type: application/json' \
-d '{"enabled": false}'

Wipe overrides back to defaults (also removes the on-disk file)

curl -s -X DELETE http://127.0.0.1:3987/api/config

See the last 20 review outcomes

curl -s http://127.0.0.1:3987/api/recent

See the score of every recent assistant answer, by message id

curl -s http://127.0.0.1:3987/api/reviews

用 REVIEWER_HTTP=0 关掉服务端。用 REVIEWER_HTTP_PORT=<n> 改端口。用 REVIEWER_CONFIG_PATH=<abs path> 挪动磁盘上的文件。下一轮对话就会读到新值，宿主不用重启。

配置标签页（自 0.7.6 起）

插件往 shell 的 conversation.view 槽位注册了一个一等标签页——就是输入框上方那条承载 dsh 自带 对话 / 轨迹 / 记忆系统 标签的环：

对话 │ 轨迹 │ 记忆系统 │ Reviewer 配置 ╰──────────── active → the main area is the page

点一下标签，配置页就接管对话区域，跟其他任何对话视图一模一样：

┌────────────────────────────────────────────────────────┐
│ dsh-answer-reviewer · 实时配置 新标签打开 127.0.0.1:3987 │ ├────────────────────────────────────────────────────────┤ │ │
│ (the config form, iframed) │
│ │
└────────────────────────────────────────────────────────┘

三个刻意的设计点：

- 它是真正的视图，不是输入框上方的一条横条。 标签以 order: 40 注册，所以排在所有自带视图之后（chat 0、trajectory 10、mnemon 30）。dsh 只在标签处于激活状态时渲染注册的视图，所以切走就会卸载 iframe，它的轮询定时器自己就停了——不需要 visible prop，也不需要持久化开合状态。
- 没有折叠控件，也没有浮层。 标签没有「开」和「关」；视图区域就是页面。这就从根上消掉了旧 dock 那一整套几何难题（浮在固定高度的输入框列之上，而不是把它顶开）。
- 配置服务端挂了会给出提示，而不是一片空白。 视图挂载时探测一次 /api/health；如果 sidecar 没起来（比如 REVIEWER_HTTP=0），它就用一条可操作的提示替换掉 iframe，指明端口和宿主日志。

这是主要界面：它除了核心 slots 客户端服务什么都不需要，所以每个安装都能用——不需要 dsh-better-sidebar。

标签页、侧边栏标签页、独立页面三者嵌入的是同一个 URL。从任意一处保存，其他两处在下一次 GET 时就能看到，因为三者读的都是宿主里那一个 ConfigStore 处理。

侧边卡片（自 0.5.0 起）

如果宿主配置档还安装了 dsh-better-sidebar，插件还会注册一个右侧边栏标签页，标题是 「Reviewer 配置」。
从侧边栏的 + 菜单打开它（就在 Files / Terminal / Browser 旁边）。
标签页的内容和独立服务器是同一份表单，装在 iframe 里加载——通过标签页保存的值，独立服务器在下一次 GET 时就能看到（反过来也一样）。标签页不活跃时 iframe 会卸载，这样后台标签页不会一直轮询。

如果没装 dsh-better-sidebar，侧边卡片就直接隐藏——配置标签页和独立的 127.0.0.1:3987 页面照样够用。每个入口都是可选的，一个都不装插件也能正常工作。

better-sidebar 依赖是有意做成软依赖的：标签页用惰性等待
（ctx.inject(["betterSidebar"], …)），而不是在 exports.inject 里声明。
硬注入会让客户端入口在任何没装 dsh-better-sidebar 的宿主上停在
pending (waiting for service: betterSidebar)，web 启动审计会报成
web boot: 1 entry did not activate，shell 则会在整个主页面上渲染出「Failed to load plugins」横幅。参见 0.5.3 更新日志条目。

安装

把包加进配置档的 dependencies 和 dsh.profile.bundles，然后刷新宿主。
jsonc
// ~/.dsh/profiles/web/package.json
{
"dependencies": {
"dsh-answer-reviewer": "file:/Users/bycall/Downloads/workbuddy/Claw/dsh-answer-reviewer"
},
"dsh": {
"profile": {
"bundles": [
"dsh-answer-reviewer"
]
}
}
}

然后执行 dsh plugin --profile web install，重启宿主。

配置

| key | type | default | meaning |
| enabled | boolean | true | 总开关。设为 false 即可禁用，无需卸载。 |
| threshold | number | 80 | 含端点的 1-100 分门槛。低于此值，插件就会介入引导。 |
| maxChallenges | number | 5 | 每个（会话, 轮次）引导次数的硬上限。硬性封顶为 8。 |
| maxReviewTokens | number | 512 | 审查模型的输出上限。 |
| timeoutMs | number | 60000 | 审查调用的墙钟时间上限。 |
| reviewProvider | string | 智能体的 | 专用审查模型的服务商。必须和 model 成对出现。 |
| reviewModel | string | 智能体的 | 专用审查模型的模型 id。必须和 provider 成对出现。 |

threshold 必须是 [1, 100] 范围内的整数；超出范围的值会回退到默认值，而不是被悄悄截断（这样配置写错时，门槛不会从「80」无声无息变成「100」）。
reviewProvider 和 reviewModel 必须同时提供；只给其中一个就是配置错误，插件会拒绝挂载。

行为

- 跳过子代理回合。 插件只审查面向用户的智能体。agent.session.header.origin === 'subagent' 会被过滤掉。
- 跳过空的或中断的助手输出。 没有审查就不干预。
- 审查调用失败时放行。 网络错误、超时、解析失败、模型侧错误都只记一条警告，让回合正常结束。审查器不稳定，绝不能卡住宿主。
- 信号中止时直接短路。 如果用户暂停或取消了回合，审查会在进行中取消，回合保持原样。
- 分数越界时拒绝放行。 审查模型必须返回 [1, 100] 范围内的整数，且 reason 非空。其他任何情况（模型返回 "1.5"、"99.9%"、"I score this ..." 等）都按解析失败处理——放行会让行为异常的审查器靠返回垃圾数据蒙混过关。
- 每回合计数器有上限。 一个回合被干预 maxChallenges 次后，同一回合内后续的回合边界允许不经审查直接关闭。默认值 5 意味着你最多看到五次干预后的重试，之后智能体的回复会原样发给用户，即使审查模型仍给出低于阈值的分数——上限是硬预算，不是软提示。
- 智能体被告知不要提及审查。 干预消息明确指示智能体静默处理发现的问题。

测试

node test/smoke.mjs

冒烟测试用 mock 对象（模拟 BlockAssembler 形状的流式数据块）覆盖每个纯辅助函数，以及 onTurnStopping 的放行、跳过子代理、低于阈值、上限耗尽分支。它不会启动 dsh 宿主。

文件

- lib/index.js — cordis 的 apply，接好监听器并编排审查调用。从 ./internal.js 导入。
- lib/internal.js — 桶文件再导出，让 lib/index.js 和测试从同一处导入。
- lib/review.js — 纯辅助函数：resolveConfig、extractAssistantText、extractUserPrompts、buildReviewPrompt、parseScore、isScoreAcceptable、buildSteerMessage、createChallengeCounter，以及公开的 Config zod schema。
- lib/config-store.js — createConfigStore（持久化、可热重载）、defaultConfigPath、HTTP 服务器的环境变量常量。
- lib/server.js — startServer(store, opts) — 仅监听 127.0.0.1 的 node:http 实例（HTML 表单 + JSON API）。
- lib/client.js — window.__ModuleLoader__.load 客户端包。把分数标签和 Reviewer 配置 标签页注册到 shell 的 conversation.chat.assistant-actions / conversation.view 插槽；当宿主配置档也包含 dsh-better-sidebar 时，还会注册一张「Reviewer 配置」侧边卡片。两处挂载都是可选的，入口在两者都不存在时也能激活。
- cordis.patch.yml — cordis bundle 入口，用来挂载插件。
- test/smoke.mjs — node ESM 冒烟测试（58 个用例）。
- CONFIGURE.md — 详细配置指南（默认评审模型与独立评审模型的区别、阈值调优、fail-closed/fail-open 对照表）。
- CHANGELOG.md — 按版本记录的发布历史。

延伸阅读

- CONFIGURE.md — 回答「怎么配置独立评审模型」「阈值该怎么选」「配置出错时插件会怎样」。调 threshold 或接入第二个服务商之前，先读这份文档。
- CHANGELOG.md — 0.3.0 的破坏性变更是把 threshold 和 maxChallenges 拆开；如果你从 0.2.x 升级，读一下里面的迁移说明。