Better Harness
English · 简体中文
将编码任务委托给 agent，并优化围绕它们的工作循环。
Better Harness 为 Agent 工作循环提供开源洞察。它通过你的 Coding Agent 运行，将项目和会话凭证转化为优先级改进建议和可验证的后续步骤。缺失的凭证将被明确标识。
网站 ·
选择你的宿主 ·
示例报告 ·
文档
## 快速开始
使用以下工具分析并改进你的编码工作流：[Claude Code](#claude-code), [Codex Desktop](#codex-desktop), [Codex CLI](#codex-cli), [Qoder Desktop/CLI](#qoder), [Cursor](#cursor), [Qwen Code](#qwen-code), 或 [GitHub Copilot CLI](#github-copilot)。
选择你正在使用的宿主，以获取其确切的安装、验证、调用和报告输出步骤。Better Harness 并非在所有宿主上使用统一的通用入口点。
标准注册表涵盖八个宿主适配器。Pi 和 WorkBuddy 目前仅作为适配器支持项，不属于六个已验证宿主的快速入门部分；请参阅[公共宿主适配器矩阵](docs/docs/hosts/adapter-matrix.md)以了解它们的明确边界。
Better Harness 将行为声明限定在相关的 Task Episodes 及其周围的项目机制中。Qoder 生成 Canvas 报告；Claude Code、Codex、Cursor、Qwen Code 和 GitHub Copilot 生成包含配对 Markdown 的独立 HTML。缺失或不完整的凭证将被明确标识。请参阅[宿主适配器矩阵](docs/adapters/README.md)以了解当前的覆盖范围和输出差异。
## 实际效果展示
该报告会明确标识缺失的凭证，并将支持的差距转化为带有影响、预期输出、范围明确的修复和验收检查的优先级发现。
打开完整的独立英文 HTML 报告
(源码)。
当你有了随时间推移可供比较的报告后，历史视图将显示 Agent 工作循环的五个维度是如何变化的：
静态的最终帧总结了历史的 Harness 报告。它展示的是记录到的趋势，而不是改进的因果证明。[查看演示是如何录制的](dev/terminal-demo/README.md)。
## 为什么选择 Better Harness？
AI 编码 agent 改变代码的速度很快，但围绕它们的工作流往往是薄弱环节：
- 🎯 **目标模糊** — agent 自信地解决了错误的问题。
- 🧭 **步骤即兴** — 工作发生在无人可复现的路径上。
- ✅ **“能跑通”却无凭证** — 验证不完整或缺失。
- 🚢 **速度高于保障** — 绕过了审查和交付检查。
- 🧠 **教训丢失** — 同样的摩擦会出现在下一个任务中。
仅仅审查最终的 diff 会遗漏这些系统级问题。Better Harness 会分析 diff 周围的工作流：它收集项目凭证（以及支持的会话凭证），评估五个相互关联的维度，并将具体的差距转化为优先级发现——每一项发现都与其凭证、预期结果、修复边界和验证路径相关联，以便团队可以一次改进一个问题。
## Better Harness 的工作原理
Better Harness 使用一个[前馈与反馈](https://martinfowler.com/articles/harness-engineering.html#FeedforwardandFeedback)循环，将工作开始前可用的指导与 agent 行动后可用的信号结合起来：
- **前馈指南** — `AGENTS.md`、规格说明、Skills 和验收标准在 agent 行动前为其提供引导。
- **反馈传感器** — linter、测试、Hooks 和评估 agent 观察结果，并帮助 agent 进行自我纠正。
在这个循环中，它评估交付的五个部分——即 **Agent 工作循环**：
[](models/agent-work-loop.md)
| 维度 | 它回答的问题 | 依据 |
| --- | --- | --- |
| **Task Understanding** | agent 是否清楚目标以及“完成”的定义？ | Rules, `AGENTS.md`, 规格说明, `DESIGN.md` |
| **Controlled Execution** | 工作是否处于受支持且可重复的路径上？ | Skills, 命令, MCP 工具, 沙箱边界 |
| **Change Validation** | 是否有凭证表明更改确实有效？ | 测试, lint, Hooks, 可观察的诊断信息 |
| **Reliable Delivery** | AI 的速度是否绕过了质量检查或验收？ | 人工审查, 批准, CI/CD, 恢复路径 |
| **Learning Capture** | 下一个任务是否能从当前任务中受益？ | Loop Discovery, 可复用的 SDLC Skills, Memory |
运行 `/better-harness` 会建立一个以任务为边界的基线，并根据宿主环境生成可视化报告、Markdown 报告或两者兼有。该报告结合了五个部分的概述、优先级发现、检测到的 agent 资产以及一份凭证简报。每项发现都包含一个修复动作，该动作会起草一份范围明确的修复计划以供审查。
Better Harness 刻意保持诚实：未观察到的行为会被明确标识，而不是变成毫无根据的分数或声明。通过当前的检查只能证明该干预措施被执行过；只有后续可比的结果才能证明循环得到了改进。
## 开源的内容
Better Harness 开放了三个相互关联的层级，而不仅仅是一个斜杠命令提示词：
- **工程实践** — 跨越[Session Evidence, Project Harness, Agent Customize, 和 Loop Engineering](references/README.md)的凭证和判断指导。
- **评估模型** — 以任务为中心的[Agent 工作循环](models/agent-work-loop.md)，包括凭证状态、发现、评分边界和纵向验证。
- **可运行实现** — 标准的 [`/better-harness` 工作流](skills/better-harness/SKILL.md), 凭证收集器、分析器、渲染器和轻量级的[宿主适配器](docs/adapters/README.md)。
这三个层级共享相同的边界：配置的资产只能证明某个机制存在，但只有链接的任务凭证才能证明它被使用过或改善了结果。
## 架构
[](docs/ARCHITECTURE.md)
该架构将三个独立的凭证领域保持独立，直到由主 agent 进行统一分析。每个结果都保留了可见的凭证来源、所有者和验证路径。
## 安装说明
安装方式因编码 agent 而异。需要为每个宿主单独安装 Better Harness，但 Qoder CLI 可以使用 Qoder Desktop 捆绑的版本。
安装或更新插件后，请启动新的会话或任务，以便宿主重新加载其插件清单。
### Claude Code
将此仓库注册为 Claude Code marketplace：
```
/plugin marketplace add QoderAI/better-harness
```
然后安装 Better Harness：
```
/plugin install better-harness@better-harness
```
从 shell 验证是否被发现：
```
claude plugin details better-harness@better-harness
```
详细信息中应包含 `Skills (1) better-harness`。然后，在你要分析的仓库中启动一个新的 Claude 会话，并运行报告提示词：
```
/better-harness analyze this project's AI coding workflow and generate an evidence-backed report
```
Claude Code 默认在仓库的 `.claude/better-harness` 报告根目录下生成一个独立的 `report.html`，以及配对的 `report.md` 和 `findings.json`。请求内联或无文件输出可将结果仅保留在聊天记录中。在可用时，包含与工作区匹配的本地 Claude 会话；缺失的凭证将被明确标识，而不是被推断。
### Codex
#### Codex 桌面版
1. 打开 **Settings > Plugins**。
2. 选择 **+ Add > From Marketplace**。
3. 输入 Git 仓库 URL，设置其 Git 引用，并将 **Sparse paths** 留空（针对此单插件仓库）。
4. 选择 **Add marketplace**，然后从新的 marketplace 安装 **Better Harness**。
5. 在要分析的仓库中启动一个新任务并运行报告提示词：
```
@better-harness analyze this project's AI coding workflow and generate an evidence-backed report
```
使用 `https://github.com/QoderAI/better-harness.git` 以及 Git 引用 `main`。
#### Codex CLI
添加仓库源：
```
codex plugin marketplace add \
'https://github.com/QoderAI/better-harness.git' \
--ref main
```
然后检查并安装 Better Harness：
```
codex plugin list --marketplace better-harness
codex plugin add better-harness@better-harness
```
在要分析的仓库中启动一个新的 Codex 任务，并运行报告提示词：
```
$better-harness:better-harness analyze this project's AI coding workflow and generate an evidence-backed report
```
在 `marketplace add` 时使用仓库 URL，而不是原始的 `marketplace.json` URL。当前的 Codex 版本使用 `plugin add` 和 `--marketplace`；使用 `plugin install` 或 `--source` 的示例针对的是不同的 CLI 契约。
### Qoder
Better Harness 内置于 [Qoder](https://qoder.com/) 桌面应用程序中，因此无需在此处进行 Marketplace 或本地插件安装。选择任一入口点：
1. **从会话中：** 打开要分析的仓库，启动一个新会话，并运行报告提示词：
/better-harness analyze this project's AI coding workflow and generate an evidence-backed report
2. **从 Quest (Qoder 1.18.0+) 中：** 打开 Quest，然后从左侧边栏选择 **Better Harness (Beta)**。
#### Qoder CLI
如果已安装 Qoder Desktop，则 Better Harness 已在 Qoder CLI 中可用。无需进行 marketplace 或插件安装。在要分析的仓库中启动一个新的 Qoder CLI 会话，并运行报告提示词：
```
/better-harness analyze this project's AI coding workflow and generate an evidence-backed report
```
仅在没有 Qoder Desktop 的情况下使用 Qoder CLI 时，需将此仓库添加为 marketplace 并手动安装 Better Harness：
```
qodercli plugin marketplace add \
'https://github.com/QoderAI/better-harness.git'
qodercli plugin install better-harness@better-harness
```
验证手动安装：
```
qodercli plugin list
```
然后在使用 `/better-harness` 之前启动一个新的 Qoder CLI 会话。
### Cursor
Cursor 插件尚未发布到 marketplace。为单个 Cursor Agent 会话加载源本地插件：
```
git clone https://github.com/QoderAI/better-harness.git
cursor-agent --plugin-dir /path/to/better-harness
```
Cursor 会话凭证通过工作区匹配的转录、元数据和审计日志支持。部分或不可用的覆盖范围将被明确标识。
### GitHub Copilot
将此仓库注册为 Copilot 插件 marketplace，然后安装 Better Harness：
```
copilot plugin marketplace add QoderAI/better-harness
copilot plugin install better-harness@better-harness
```
验证 Skill 是否已加载：
```
copilot plugin list
```
推荐使用 marketplace 安装。Copilot CLI 中已弃用直接仓库、URL 和本地路径安装。
Copilot 会话凭证通过 `~/.copilot/session-state/` 下与工作区匹配的 Copilot CLI 转录支持。Copilot 不记录每项响应的 token 使用情况，且 VS Code Copilot Chat 没有受支持的持久转录；这两者都被明确界定为凭证边界。
### Qwen Code
将 Better Harness 作为 Qwen Code 扩展安装：
```
qwen extensions install QoderAI/better-harness
```
在要分析的仓库中启动一个新的 Qwen Code 会话，并运行报告提示词：
```
/better-harness analyze this project's AI coding workflow and generate an evidence-backed report
```
Qwen Code 生成独立的 `report.html`，以及配对的 `report.md` 和 `findings.json`。会话凭证的覆盖范围取决于 Qwen Code 可用的转录路径；缺失或不完整的凭证将被明确标识。
### Pi
将此仓库作为 [pi package](https://pi.dev/docs/latest/packages) 安装：
```
pi install https://github.com/QoderAI/better-harness
```
或者在不更改设置的情况下进行单次运行试用：
```
pi -e git:github.com/QoderAI/better-harness
```
Pi 通过 `package.json` 中的 `pi` 清单发现 `better-harness` Skill 和 `/better-harness` 提示词模板。在要分析的仓库中启动一个新的 Pi 会话，并运行报告提示词：
```
/better-harness analyze this project's AI coding workflow and generate an evidence-backed report
```
Pi 默认在仓库的 `.pi/better-harness` 报告根目录下生成一个独立的 `report.html`，以及配对的 `report.md` 和 `findings.json`。Pi 会话凭证从 `~/.pi/agent/sessions/` 下与工作区匹配的 JSONL 转录中读取；缺失的凭证将被明确标识，而不是被推断。
## 开发与源码打包
开发需要 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`。
从相同的源码检出中，无需读取本地会话即可检查仓库凭证：
从源码检出中，`npm run preview -- --open` 可为内置的 fixture 提供服务。Canvas 预览需要已安装的 Qoder 运行时，或者显式的 `--sdk-media`/`--sdk-root` 路径。它默认监听 `127.0.0.1`，是一个本地检查工具，而不是经过身份验证的共享服务。
## 贡献
你不需要理解整个 runtime 就能做出贡献。从与你想要进行的改进相匹配的最小切入点开始即可：
| 你可以贡献的内容 | 从这里开始 | 贡献示例 |
| --- | --- | --- |
| 工作流指导和工程实践 | [`skills/`](skills/) 或 [`references/`](references/) | 为某种语言、框架、审查模式或经常发生的 agent 工作流添加有来源的指导。 |
| 评估模型和可执行分析 | [`models/`](models/) 或 [`scripts/`](scripts/) | 添加有凭证支持的评估视角、检测器或对 agent 友好的分析命令，并附带 fixtures 和测试。 |
| 交付控制与宿主支持 | [`hooks/`](hooks/) 或 [新 Coding Agent 指南](docs/adapters/contributing-new-coding-agent.md) | 添加一个范围较小的生命周期检查，或者为其他 Coding Agent 宿主记录并验证凭证支持。 |
| 报告与视觉语言 | [`templates/reporting/`](templates/reporting/) 或 [`templates/style/`](templates/style/) | 添加报告模式、可复用的报告契约，或带有验证凭证的仅指令视觉样式。 |
| 示例与运营模型 | [`case-studies/`](case-studies/) | 分享一个经过脱敏处理的、有明确凭证界限的示例，说明团队如何应用 Agent 工作循环分析和交付实践。 |
快速入门：
1. 阅读[社区扩展映射](docs/community.md)以选择规范的所有者并理解其契约。
2. 遵循[贡献指南](CONTRIBUTING.md)以设置项目并界定更改的范围。
3. 对于宿主支持，请遵循[新 Coding Agent 贡献指南](docs/adapters/contributing-new-coding-agent.md)并更新[宿主适配器矩阵](docs/adapters/README.md)。
4. 当贡献更改了运行时行为或渲染输出时，添加测试、fixtures 或预览凭证。
5. 开启一个聚焦于特定主题的 Pull Request，解释更改了什么、为什么更改以及它是如何被验证的。
不确定某个想法属于哪里？在构建新的顶级展现层或更改公开的报告、schema、打包或兼容性契约之前，请先[提出一个 issue](https://github.com/QoderAI/better-harness/issues)。
## 许可证
Better Harness 采用 [MIT 许可证](LICENSE)授权。
如果 Better Harness 帮助你改进了 agent 工作流，请考虑给它一个 ⭐
—— 这有助于其他人发现这个项目。