一键把批注回传智能体,会不会把评审养成“盲签”

原创2026-11-14 13:27:391,189 阅读
文章标签:开发者工具代码评审AI 应用前端后端CLIAI 插件AI 技能MCP 服务dsh-plugin

一键把批注回传智能体,会不会把评审养成“盲签”

Plannotator 的产品描述里有一句话非常直白:shape, decide, plan, annotate, review code, share with team, and send all feedback to agents with one click。它把“人看东西”和“智能体改东西”之间的最后一段手工活,也就是把评审意见复制粘贴回对话,压缩成了一次点击。

社区里对这套闭环的反应基本是正面的:从 Claude Code 的 ExitPlanMode hook、--hook 把人工闸门嵌进 Agent 生命周期,到 Guided Review 把大 diff 切成章节、结构化 JSON 响应让评审结果变成机器可读的闸门,讨论重点都是“怎么接得更顺”。但顺滑本身值得警惕。评审闸门的价值不在于它存在,而在于它真的拦住过东西。当回传成本降到一次点击,人的行为会向“点一下就走”偏移——我把这种偏移叫“盲签”:签署动作发生,判断没有发生。

这篇文章不讨论要不要一键回传,而是拆三件事:这个闭环在代码里到底怎么实现的、盲签在系统里留下哪些可观测信号,以及仓库里已经存在哪些保留人工否决权的设计。

闭环的工程实现:一次点击背后发生了什么

先看清“一键”到底封装了多少东西。Plannotator 的决策按钮不是散落在各个应用里的组件,而是由一个纯函数统一生成规格,再由各应用翻译成 HTTP 请求。核心在 decisionSpec.ts:

export type DecisionActionId =
  | 'primary'              // the left segment
  | 'note-with-approval'   // "Approve with a note…"
  | 'request-changes'      // "Request changes…"
  | 'note-with-feedback'   // "Send with a note…"
  | 'approve-with-notes'   // review + gate-annotate; capability-gated
  | 'discard-and-finish';  // "Done/Approve, discard n annotations…"

注意这个枚举的形状:六个决策里,有三个是“带着内容通过”,一个是“丢掉内容通过”,只有两个是“驳回或要求修改”。也就是说,从可选动作的数量上看,系统对“放行”的表达力远强于对“拦截”的表达力。这不是实现缺陷,这是产品取向——文件头注释写得很清楚,这个模块的存在是为了让“两个应用、两种状态都是数据,而不是分叉的组件”。

规格生成之后,路由是另一层纯函数。计划评审在 planDecision.ts:

export function resolvePlanDecisionAction(id: DecisionActionId): PlanDecisionRoute {
  switch (id) {
    case "primary":
      return { kind: "primary" };
    case "note-with-approval":
      return { kind: "note", route: "approve" };
    case "request-changes":
    case "note-with-feedback":
      return { kind: "note", route: "deny" };
    case "approve-with-notes":
      return { kind: "approve", discardFeedback: false };
    case "discard-and-finish":
      return { kind: "approve", discardFeedback: true };
  }
}

代码评审的对应实现是 reviewDecision.ts,注释点明了它的拓扑:“Review is single-transport:每个决策都 POST 到 /api/feedback,唯一的岔路是 approved”。也就是说,评审、批注、通过、放弃批注,最终都汇聚到同一个 HTTP 端点,只是请求体不同。这种收敛带来一个后果:判断“这次放行有没有依据”必须靠请求体里的字段,不能靠 URL 的语义。

再看落盘。决定一旦作出,会被写入两个地方。计划的历史在 storage.ts,saveFinalSnapshot 用文件名后缀记录结论:

export function saveFinalSnapshot(
  slug: string,
  status: "approved" | "denied",
  plan: string,
  annotations: string,
  customPath?: string | null
): string {
  const planDir = getPlanDir(customPath);
  const filePath = join(planDir, `${slug}-${status}.md`);
  // Combine plan with annotations appended
  let content = plan;
  if (annotations && annotations !== "No changes detected.") {
    content += "\n\n---\n\n" + annotations;
  }
  writeFileSync(filePath, content, "utf-8");
  return filePath;
}

评审的结论则进入反馈归档,格式是追加写的 JSONL,见 feedback-archive.ts:

{DATA_DIR}/feedback/{project}/index.jsonl      append-only, authoritative
{DATA_DIR}/feedback/{project}/records/…​.md      human-readable sidecar

每行携带 decision(approved、approved-with-notes、denied、feedback、lgtm、dismissed)、counts 和可选的 feedback / annotations。这个文件是跨客户端共享的:plannotator 和 plannotator-tui 都往同一个 index.jsonl 里追加,靠 client 字段区分。这意味着它天然就是一个可以拿来做评审质量分析的数据集。

闭环的最后一环是把结论变成智能体的下一轮输入。Claude Code 的 mod 在 delivery.ts 里做纯函数式的投递决策:

if (record.noop && !approvalAwaited && !misreadAsPlatformPost(record)) {
  const what = record.decision === 'approved' ? 'approved with no notes' : 'closed with no annotations'
  return { action: 'log', text: `${subject} ${what}. Nothing was sent to Claude.` }
}

这一段值得单独说:“空批准”不会打断智能体。人点了 Approve 但没有任何批注,系统只写一行日志 Nothing was sent to Claude.,不产生新回合。这是有意为之的省 token 设计,也在客观上把“无内容批准”从流程里抹掉了——它不留痕、不占上下文,于是更难被复盘。

代码评审界面:文件树、并排 diff 与行内批注

盲签的早期信号:四个可以从数据里读出来的指标

盲签不是一个能用直觉判断的现象,它在系统里留下的是结构性痕迹。以下信号都能从上面这些数据结构里直接算出来,无需额外的埋点。

信号一:noop 比例与 Nothing was sent 的次数。

host-result.ts 会给每条结论打上 noop 标记:一次代码评审被批准但没有任何反馈时,noop = true,annotationCount: 0。计划评审里的空批准同样走这条路径。这个比例是“评审是否真的产出内容”的最直接度量。当一次会话里连续多轮出现“批准且零批注”,而 diff 行数并不小,盲签的概率就很高——Anthropic 在公开的评审实践里用的是同一类口径:人工批准次数、人工评论数、评审等待时间,三者要一起看,只砍后者成本会从别处冒出来。

信号二:批准时携带的批注数量,以及这些批注的来源。

归档记录里的 counts 有三个维度:

counts: { annotations: number; external: number; images: number };

其中 external 的语义非常关键,字段注释写得很明确:

/** External tool identifier ("eslint", "browser-agent", a review job).
 *  Absent means the human wrote it — that is the "my own comments" filter. */
source?: string;

于是可以定义一个很锋利的指标:一次批准里,人自己写的批注数 ÷ 总批注数。如果这个比值长期趋近 0,而批注总量不小,说明 Reviewer 的行为已经从“我发现问题”退化成“我转发工具发现的问题”。这不一定是坏事,但它意味着人的角色变成了路由器,而不是判断者。把 external 单独计数,正是为了让两者不被混为一谈。

信号三:discard-and-finish 的使用频率。

这是整个决策模型里最需要盯住的动作。它把已经写下的批注全部丢掉,然后照样按“通过”处理。规格里连确认文案都写得很克制:

confirm: approvalFlow
  ? {
      title: `Discard ${count} ${noun} and approve?`,
      message:
        'These annotations are change requests, including any from other tools. Approving without them tells the agent no changes are needed.',
      confirmText: 'Discard & approve',
    }

文案里那句 “including any from other tools” 说明设计者已经预见到一种具体场景:外部工具或 AI 评审往 diff 上灌了一批评论,人嫌吵,一次性丢掉然后通过。一次确认就能完成“丢掉 N 条待办 + 放行”。从效率上看这很合理,从评审质量上看,这是唯一一个把“发现问题”和“忽略问题”压缩进同一个动作的按钮。它的使用率如果随着批注数量上升而上升,就是典型的评审疲劳信号。

信号四:评审轮次是否收敛。

Guided Review 的线程模型里有一个 round 概念(inbox-review.ts):

/** A review's round in its thread: 1, plus every review message before it. */
export function inboxReviewRound(...)

轮次本身不是问题,问题在于轮次和“本轮是否只审新增部分”的搭配。Anthropic 披露过一个很能说明问题的数字:在多轮评审里,评审者反复指出的问题中约 59% 在第一轮就已经存在——也就是它在挖存量,而不是在审新变更。Plannotator 这边的对应提示写在 Inbox 的 agent 指令里:当人已经对不同轮次给过 verdict 或评论,再让 agent 出评审时,要求它“只审自那次评审以来的变化,而不是对 base 分支的全量 diff”。如果轮次上升而“只审增量”的比例没有跟着上升,多轮评审的边际收益就在下降。

把这四个指标放在一起,能得到一个很实用的判据:批准率上升 + 单次批注数下降 + 人工批注占比下降 + 轮次上升,四者同时出现时,团队不是在提速,而是在失去闸门。

系统里已经存在的“反盲签”设计

Plannotator 的代码里其实散落着不少结构性防线,值得单独拎出来,因为它们是可以直接照抄的流程设计。

其一,批准能不能携带意见,由服务端能力声明决定,而不是由按钮颜色决定。

两套服务端都会在 /api/plan 上广播 approvalNotesSupported。如果宿主不支持“批准时带意见”,客户端就根本不渲染 “Approve with a note…” 这一行:

const positive: DecisionMenuItem | null = approvalFlow && input.approvalNotesSupported
  ? { id: 'note-with-approval', label: 'Approve with a note…', ... }
  : null;

注释给出的理由很硬:“它只在声明支持投递的地方渲染(绝不提供一个静默丢弃内容的选项)”。这是一个通用原则:如果一个动作会产生无法送达的内容,就不要把它做成可点击的样子。直接后果是有些运行时的批准永远只能二选一——要么干净通过,要么走 Send Feedback 走 deny 通道,不存在“通过了但意见丢了”的中间态。

其二,同一份批注,通过时是“非阻断建议”,驳回时才是“要改”。

这是整个设计里最微妙、也最容易被误读的一处。当批准携带批注时,规格里对这批内容的定性是:

subtitle: count > 0
  ? `Approve; your ${count} ${noun} ride along as non-blocking guidance`
  : 'Approve; your edits and attachments ride along as non-blocking guidance',

而在 annotate 的批准通道上,默认提示词写得更赤裸:

The artifact is approved. The notes below are non-blocking guidance,
not a request for another revision.
...
Do not revise or reopen the artifact solely because of these notes
unless the user explicitly requests it.

换句话说:同一条批注,从 Approve 通道走是“顺便提一句”,从 Send Feedback 通道走才是“必须改”。如果一个人习惯用“Approve with notes”表达所有意见,他其实是在持续地降级自己的否决权,而界面上看不出任何异常——按钮是绿的,批注也送到了,只有 agent 收到的语义变了。这是盲签最隐蔽的形态:不是没写意见,而是意见被贴上了“不必执行”的标签。这也是为什么“批准时携带的批注数”必须和“驳回时携带的批注数”分开统计。

其三,不允许批准你已经看不到的文本。

计划在评审期间可能被智能体改写。Plannotator 的处理是给每次修订编号,/api/plan 带上 planRevision,页面在评审期间轮询修订号,而批准与否决的请求体会回显这个编号,服务端发现过期就直接拒绝:

Approve/deny bodies echo `planRevision`, and the server answers
`409 { code: "plan_revised" }` to a stale one, so a reviewer cannot
approve text the agent replaced; the tab then loads the revision and
the reviewer decides again.

进一步,Pi 的计划评审在执行阶段用的是屏幕上的那份文本,而不是磁盘上的文件:批准结论携带 plan,执行时以它为源;如果批准那一刻磁盘文件和屏幕上的不一致,消息里会明确告诉 agent 不要执行未经评审的改动。

这一条对“盲签”的抑制作用比任何 UI 提示都强:它把“签的东西必须是你刚才看的东西”变成了服务端的硬约束。任何异步评审、后台批准、多人共用一个标签页的流程,都应该抄这个机制。

其四,宿主能不能替人做决定,是有明确边界的。

Qwen Code 的例子很典型:因为它不允许 hook 直接批准一个需要人参与的 exit_plan_mode,所以浏览器里点了批准之后,Qwen 终端里还会再弹一次自己的确认框(Proceed once / Proceed always / Cancel)。Plannotator 的文档把这条写得很清楚,并注明“That is Qwen's rule, not a Plannotator bug”。反面例子也有:在无 UI 或构建产物缺失的会话里,计划会自动批准,日志会直接告诉你 “Plans will auto-approve on exit_plan_mode”。

这套边界值得当成检查清单来用:哪些宿主允许自动批准、哪些必须二次确认、哪些场景会静默降级为自动批准。第三条最危险,因为它通常发生在 CI、headless 或者打包出问题的时刻,恰恰是没人盯着的时候。

其五,Agent 也能主动关闭评审,但会明说有多少东西没送出去。

POST /api/host/close 让发起评审的会话自己关闭面板。这时结论被标记为 closedBy: "agent",同时带上 unsentAnnotations:

const unsent = record.unsentAnnotations
const saved = typeof unsent === 'number' && unsent > 0
  ? ` ${unsent} unsent ${unsent === 1 ? 'comment' : 'comments'} kept in the draft.` : ''
return { action: 'log', text: `Claude closed ${subject}.${saved} Nothing was sent to Claude.` }

草稿被保留,评审没有得出结论。这个设计的意义在于:“没人做决定”和“决定是通过”在系统里是两个不同的值。很多流程之所以会退化成盲签,就是因为它们把“超时未处理”折叠成了“默认通过”。这里的 dismissed / closedBy / noop 三个字段把这个区分保留了下来,可以直接拿来做流程质量报表。

其六,把“谁有权批准”写进规格,而不是写进口头约定。

平台侧(PR/MR)的自批准不是被隐藏,而是被“变灰但仍可见”:

/**
 * Platform self-approval (PR6, §3.4): rendered dimmed but NOT disabled.
 * The reason surfaces through the shared Tooltip + aria-describedby …
 * every invocation path (click, Mod+Enter, compact row) is a no-op.
 */
muted?: boolean

理由写得很克制:menu 仍然应该记录这条路径的存在,让任何状态都不成为死路。同理,GitHub 上不允许对自己的 PR 提 REQUEST_CHANGES 时,界面不会把这一行删掉,而是附上原因,并补一条可用的“Comment…”,避免空状态变成死角。

给流程加回人工否决权的四条建议

综合上面的机制,可以给出几条不依赖意志力、依赖结构的建议。

第一,把“批准”拆成两种语义,并且强制区分。

不要把“我看过了”和“可以继续”合成一个按钮。Plannotator 用 approvalNotesSupported 已经在做这件事:有内容要走就 Send Feedback(deny 通道,agent 必须处理),只是附带说明才用 Approve with notes(非阻断)。团队层面应该形成规矩:任何需要 agent 修改的内容,一律不走批准通道。这条规矩比任何“请认真评审”的呼吁都有效。

第二,把“丢弃批注并批准”从常规路径里降级。

discard-and-finish 有确认弹窗,这是必要的下限,但还不够。更稳的做法是让它在流程上不可用于有实质性发现的情况:例如当 counts.external > 0 时,把丢弃动作改成“逐条标记为已知/不适用”,而不是一次性清空。归档里已经有 source 字段,技术上区分“工具灌进来的噪音”和“人自己写的意见”是现成的,只是目前两者共享同一个丢弃入口。

第三,用归档数据做月度体检,而不是用印象。

feedback/{project}/index.jsonl 是追加写、跨客户端共享、带版本号的,天然适合做趋势分析。建议至少有四个面板:批准的 noop 比例、人工批注占比(counts.annotations - counts.external ÷ 总批注)、discard-and-finish 使用率、以及单次评审的批注数中位数。这四个量的组合能区分“评审变快”和“评审变空”。Anthropic 的经验是把回滚率和事故率当护栏指标——你可以再加一条:用了 Plannotator 的变更,回滚率有没有上升。如果效率指标全绿而护栏指标变红,说明时间只是被搬到了下游。

第四,给多轮评审设硬上限,并把“只审增量”变成默认。

Inbox 的线程已经有 round 计数,指令层面也已经写好了“只审自上次评审以来的变化”。缺的是执行纪律:轮次到上限后,不应该再让 agent 出新一轮完整评审,而应该要求人对方案本身做一次判断。这条在代码里没有强制,但可以靠 prompt 定制来做——custom-feedback.md 里的模板机制允许你直接改驳回和批准消息,把“超出 N 轮请升级到人工决策”写进 agent 收到的文本。同一份文档里的 ## Decisions Log(把被否决的方案记录在计划文档里,随每次修订一起传播)也是一个很实用的反重复手段:它让“这个方案已经被拒过”变成文档的一部分,而不是靠人的记忆。

结语

Plannotator 把这个闭环做得很干净:决策是数据、路由是纯函数、结果落盘可审计、能力声明决定 UI 是否存在。正因为每一层都清晰,盲签的痕迹也更容易被看见——noop、external 计数、discard-and-finish、round,这些字段本来就是为“这活是不是真的干了”准备的。

一键回传本身不会让评审变坏,它只是把评审的成本从“操作”移到了“判断”,而判断是没有快捷键的。真正需要守住的不是那个按钮,而是按钮背后那三分支的语义:批准就是放行,带批注的批准是“顺便提一句”,只有驳回才等于“必须改”。把这三件事混为一谈的那天,评审就成了仪式。

登录后查看全文
plannotator