Better Harness 实操指南，怎么用证据审查 AI 编码智能体

只看 diff 不够，怎么审查 AI 编码智能体的工作流？

AI 编码智能体写代码很快，但围绕它的工作流往往很薄弱。如果只审查最终的代码变更，你会漏掉系统层面的问题。Better Harness 这个开源工具能帮你分析变更背后的工作流，收集项目与会话证据，把具体差距变成按优先级排列的改进项。

它把分析重点放在前馈指引和反馈传感器组成的闭环上。前馈指引包括 AGENTS.md、spec 和验收标准，反馈传感器包括 linter、测试和评估智能体。在这个闭环里，它评估五个维度的表现。

  • 任务理解，判断智能体知不知道目标以及完成的含义，由规则和 spec 支撑。
  • 受控执行，看工作是否沿着受支持且可重复的路径进行，由 Skill 和沙箱边界支撑。
  • 变更验证，确认是否有证据表明变更有效，由测试和 lint 支撑。
  • 可靠交付，检查 AI 的速度是否绕过了质量检查或验收，由人工审查和 CI/CD 支撑。
  • 经验沉淀，决定下一个任务能否从本次任务中受益，由可复用 Skill 支撑。

在你的 Agent 里装 Better Harness (各宿主安装与排坑)

不同编码智能体的安装方式不同，除 Qoder CLI 可使用 Qoder Desktop 内置版本外，都需要单独安装。安装或更新插件后，记得启动新会话让宿主重新加载清单。

Claude Code

把仓库注册为 Marketplace，然后直接安装插件。

/plugin marketplace add QoderAI/better-harness
/plugin install better-harness@better-harness

装完在 shell 里验证一下发现状态。

claude plugin details better-harness@better-harness

详细信息里应该包含 Skills (1) better-harness。接着在目标仓库启动新会话，运行报告提示词 /better-harness 分析此项目的 AI 编码工作流并生成基于证据的报告。

报告默认生成在 .claude/better-harness 目录下，包含 report.html、report.md 和 findings.json。如果不想生成文件，可以直接在对话里要求行内输出。

Codex (Desktop 与 CLI)

Desktop 版需要打开 Settings > Plugins，选择从 Marketplace 添加。Git 仓库 URL 填 https://github.com/QoderAI/better-harness.git，ref 填 main。

Codex 添加插件 Marketplace 的对话框，包含仓库、Git ref 和可选的 sparse paths

CLI 版的坑在于命令格式。添加仓库源时必须传仓库 URL，而不是原始 marketplace.json URL。

codex plugin marketplace add \
  'https://github.com/QoderAI/better-harness.git' \
  --ref main

安装插件用 plugin add 和 --marketplace。不要用 plugin install 或 --source，那些对应的是另一套接口。

codex plugin list --marketplace better-harness
codex plugin add better-harness@better-harness

Cursor

这里有个大坑。Cursor 插件没发布到 Marketplace，而且本机 Cursor help 没有验证历史的 --plugin-dir 合同。所以哪怕你克隆了源码，Better Harness 也会把安装计划标记为不可用，不会输出执行命令。

当前只能克隆源码并尝试生成计划来查看状态。

git clone https://github.com/QoderAI/better-harness.git
better-harness plugin plan install --host cursor --surface agent --scope session

会话证据来自工作区匹配的会话记录和审计日志。你可以跑 better-harness plugin verify --host cursor --surface agent 验证，覆盖范围不完整或不可用时会被明确标注。

Qoder 与 GitHub Copilot

Qoder 桌面版内置了 Better Harness，直接在会话里敲 /better-harness 就行。Qoder CLI 如果装了 Desktop 也能直接用，没装的话需要手动添加 Marketplace 源或 Git 克隆安装。

GitHub Copilot 建议用 Marketplace 安装，因为 Copilot CLI 已经弃用了直接从仓库或 URL 安装的方式。

copilot plugin marketplace add QoderAI/better-harness
copilot plugin install better-harness@better-harness

Copilot 会话证据来自 ~/.copilot/session-state/ 下的记录。注意 Copilot 不记录逐次响应的 token 用量，VS Code Copilot Chat 也没有持久化会话记录，这些都会被明确标为证据缺口。

跑完 /better-harness 后，报告里到底有什么？

运行报告命令后，Better Harness 会建立一个以任务为边界的基线。报告不会随便打分，它坚持如实呈现。没有观察到的行为会明确标注，不会转化成无依据的断言。当前检查通过只能证明改进措施执行过，后续可比较的结果才能证明闭环确实改进了。

每项发现都包含影响、预期输出、范围明确的修复方案与验收检查。你可以点击查看自包含的 HTML 报告示例。

Better Harness HTML 报告，展示一项由证据支持的发现及其影响、预期输出、范围明确的 AI 修复方案和验收检查

打开完整的自包含英文 HTML 报告
（源文件）。

如果你要追踪交付链路，交互式 Harness Inspector 会在只读工作区里把产品意图、智能体活动、会话和提交串联起来，同时保持证据强度与局限清晰可见。

Harness Inspector 会话视图：提示词、工具调用与提交的同步时间线，配套证据抽屉解释每条关联

打开交互式 Harness Inspector 示例（使用虚构的英文数据，不会读取你的工作区）。

积累多份报告后，历史视图会展示那五个维度的变化。这张图展示的是已记录的趋势，不能证明改进之间存在因果关系。

Better Harness 报告历史的静态最终帧，展示智能体工作闭环五个维度随时间的变化

想改源码或本地打包，需要什么环境

开发环境需要 Node.js >=22.20.0 <25.0.0 和 npm >=10.9.3 <12.0.0，跨平台支持 Windows、macOS 和 Linux。

npm ci
npm test
npm run pack:verify

构建 Codex 本地插件产物用 node scripts/packaging/build-host-plugin.mjs，通过验证的产物会输出到 dist/plugins/better-harness。

如果只想检查仓库证据不读会话，可以用 node scripts/better-harness.mjs report --no-sessions。在源码检出目录中运行 npm run preview -- --open 会提供一个内置测试样例。Canvas 预览需要已安装的 Qoder 运行时，或者显式指定 --sdk-media 或 --sdk-root 路径。服务默认监听 127.0.0.1，它是本地检查工具，不是带身份验证的共享服务。

操作速览

  1. 检查插件状态：better-harness plugin status --host all
  2. 生成安装计划：better-harness plugin plan install --host <host> --surface <surface> --scope <scope>
  3. Claude Code 安装：/plugin marketplace add QoderAI/better-harness 后执行 /plugin install better-harness@better-harness
  4. Codex CLI 安装：codex plugin marketplace add 'https://github.com/QoderAI/better-harness.git' --ref main 后执行 codex plugin add better-harness@better-harness
  5. 生成报告：在目标仓库启动新会话，运行 /better-harness 分析此项目的 AI 编码工作流并生成基于证据的报告
  6. 本地源码验证：npm ci && npm test && npm run pack:verify

FAQ

Q: Better Harness 的报告会给出评分吗？
未观察到的行为会被明确标注，不会转化为缺乏依据的评分或断言。只有与任务关联的证据才能证明该机制被使用过或确实改善了结果。

Q: Cursor 为什么不能直接安装插件？
Cursor 插件尚未发布到 Marketplace，且本机 Cursor help 没有验证历史 --plugin-dir 合同。因此 Better Harness 会把安装计划标记为不可用，不会输出执行命令。

Q: Codex CLI 安装时用 plugin install 报错怎么办？
当前 Codex 版本使用 plugin add 和 --marketplace。使用 plugin install 或 --source 对应的是另一套 CLI 接口。

Q: 报告生成在哪个目录？
Claude Code 默认在仓库的 .claude/better-harness 报告根目录下生成 report.html、report.md 和 findings.json。其他宿主如 Qoder 与 Cursor 会生成原生 Canvas 报告。

Q: GitHub Copilot CLI 能直接从仓库 URL 安装吗？
不建议。Copilot CLI 已弃用直接从仓库、URL 或本地路径安装，请优先使用 Marketplace 安装。

Q: 参与贡献需要理解整个运行时吗？
不需要。你可以从与你希望改进的内容最匹配的最小范围入手，比如从 skills/ 添加工作流指南，或从 templates/reporting/ 添加报告模式。

Q: 本地预览 Canvas 报告需要什么条件？
Canvas 预览需要已安装的 Qoder 运行时，或显式指定 --sdk-media/--sdk-root 路径。