
Verifair:让人类审阅编码代理的证据而非代码差异
来源标题:Verifair – review what your coding agent proves, not its diff
Verifair 是一个自托管 Web 服务,编码代理可推送 Markdown 格式的变更审查报告,人类通过选中文本评论并给出结论,以判断变更意图与证据是否成立,而非逐行阅读 diff。每个变更生成一份报告,包含意图、前后对比与图示、边界情况、验证命令与结果、未验证项、回滚方案、安全影响及代理审查摘要等内容。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
审视证据,而非 diff。一个自托管平台,coding agent 在这里发布变更报告,由人来评判。
如何称呼:verifier(/ˈvɛrɪfaɪər/,与单词本身读音相同)或 veri-fair(/ˈvɛrifɛər/,“very fair”)。两者皆可。
Docs · Quickstart · How it works · Screenshots · API · Configuration · Deployment
如今大部分代码由 agent 编写。人无法读完它们做出的每一处 diff,而读 diff 从来就不是判断一项变更是否正确的最佳方式。
verifair 是一个小型 Web 服务,agent 在这里推送 markdown 格式的变更审查报告,人阅读报告、通过选中文本发表评论,并给出裁决。agent 已经承担了代码审查。人应当评判意图与证据:这是不是正确的变更,证据是否站得住脚?verifair 为每项变更提供一个页面来完成这件事。
每项变更一份报告。包含意图、用前后对比和示意图展示的设计、边界情况、验证(命令、结果和链接)、未验证的内容、回滚方案、安全影响、agent 审查摘要、只有人能回答的问题,以及每个 merge request 一行。查看报告。
由人先签署。提出变更的人阅读 agent 的报告并签署。只有在这之后,团队才会被请来审查。签署人或管理员可以在无人给出裁决时撤销签署。
对任意文本发表评论。选中一句话即可开启一个讨论串。讨论串默认阻塞;审查人可以将其标记为建议。Conventional Comments 标签按钮(issue:、nitpick:、question: 等)用于设置标签以及该讨论串是否阻塞。
带规则的裁决。批准或请求修改。存在未关闭的阻塞讨论串时,批准会被拒绝,且签署人不能批准自己所在的版本。改变主意时可以取消批准或撤回裁决。
版本。agent 在收到反馈后推送新版本。签署和裁决按版本分别保存;评论会显示它们是在哪个旧版本上发表的。
需要时先做计划。在实施之前审查并批准一份 Markdown 计划,然后在同一 URL 上附加变更报告。计划与实施有各自的签署、评论和裁决。直接提交报告仍然可用。
示意图与截图。报告中的 Mermaid 代码块会被绘制成示意图,源码一键可看。agent 通过 API 上传截图并在报告中展示;来自其他站点的图片仍以链接形式呈现。
可选的执行证据。为实施版本附加本地录屏或带标注的重建。只读的 Execution 标签页提供额外上下文;人仍然要签署和评判实施本身。参见 trace 格式和版本固定的捕获方法。
为 agent 而构建。一个小型 JSON API,用于推送报告、读取和回复评论、长轮询获取反馈,以及归档或恢复审查。随附一个 agent skill,用一条 npx skills 命令即可安装,并在 /docs 提供 API 浏览器。
面向人的收件箱。按轮到谁分组:需要你审查、需要你签署、退回给你、需要实施、等待他人。分配给我、由我创建和全部审查列出其余内容,并带有状态标签页。
归档与删除。归档一个已完成或测试用的审查(或整个项目)以将其从列表中移除;它仍可阅读,并可恢复。管理员可以将其永久删除。
两种模式。本地模式面向一个人或一个小型可信团队。共享模式面向团队,内置登录(Google 或任意 OpenID Connect 提供方)、成员、管理员、按成员分配的 agent token、可选的面向自有域名的开放注册,以及首次运行引导,帮助每位成员连接各自的 agent。
小巧而朴素。FastAPI、Jinja 和 htmx,无需 JavaScript 构建步骤,严格 CSP。状态存储在 Postgres 中,因此可以运行多个副本。提供系统、浅色和深色主题,可在手机上使用。
开放也安全。报告中来自其他站点的图片以链接形式展示,不会被加载。本地模式拒绝未知主机名,从而阻断 DNS rebinding。
可选的 Slack 消息,用于草稿、待审查、评论、裁决和撤回的裁决。agent 撰写的文本在 Slack 和邮件中会标注为 agent 所写。
在审查页面上向任意成员请求审查,可选在变更为其准备就绪时发送邮件,以及为新成员发送欢迎邮件(共享模式)。
工作原理 verifair 本身不运行任何 AI。coding agent 在它们一贯运行的地方(你的机器、CI)运行,并使用 agent token 在此发布报告。只做审查的人不需要 token。
对于需要先做计划审查的工作,提交 workflow: "plan_first" 并附带计划、不附带实施正文。作者签署计划,另一个人批准它。随后变更等待实施。用同一 ID 附加报告,并将 expected_version 设为最新快照;然后分别签署和审查实施。未改动的计划在实施版本之间保留其批准。编辑过的计划需要重新批准,未解决的阻塞计划讨论串会暂停工作流。参见计划审查和 API。
sequenceDiagram autonumber participant Agent participant Author participant verifair participant Reviewer Agent->>verifair: POST /api/reports (v1) Note over verifair: unsigned Author->>verifair: read and sign v1 Note over verifair: awaiting review Reviewer->>verifair: comment on text, request changes Agent->>verifair: GET /api/reports/{id}/wait verifair-->>Agent: new comment or verdict Agent->>verifair: answer threads, push v2 Author->>verifair: sign v2 Reviewer->>verifair: approve v2 Note over verifair: approved Loading
快速开始 你需要 Docker 与 Compose。 git clone https://github.com/romanzdk/verifair.git cd verifair docker compose up --build 打开 http://localhost:8000。agent token 是 change-me。在启动前设置 VERIFAIR_API_TOKEN 以使用其他 token。用户设置显示名称(保存在 cookie 中)。作者签署一个版本,审查人选中文本发表评论,然后批准或请求修改。 在第二个终端中,加载演示审查(只需要 Python 3):
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。