搜索 coding agent harness 时最容易犯的错，是把“统一启动命令”“统一程序接口”和“复用项目配置”当成同一个需求。三个方向都会出现 harness 这个词，但它们改动的边界、失败方式和验收证据完全不同。
本文使用唯一金丝雀 HARNESS-PORT-771 完成 P01–P15。你只选择一个符合需求的候选做实验，不需要把三项工具串在一起。
先下载三份材料
验收表中的“实际结果”和“状态”默认为未验证。不要写入 API Key、OAuth token、完整环境变量、私人仓库地址或日常配置内容。
三个候选实际统一哪一层
| 候选 | 当前官方定位 | 你真正要验收的合同 | 当前成熟度信号 |
|---|---|---|---|
harness.lol 的 harness CLI | 把 Claude Code、Codex、OpenCode、Cursor 的原生流转换成统一 NDJSON | 最终命令、八类事件、终态、取消和底层退出 | crates.io harnesscli 0.1.6；项目规模小，按实际版本检查 |
| Open Harness | 跨 Claude Code、Goose、LangChain Deep Agents、Letta 的开放 API 规范和适配器 | capability manifest、实际适配器覆盖、conformance 结果 | 仓库明确称规范是 aspirational north star；不能把规范路由当成实现证明 |
| Harnyard | 以 .claude/ 为配置源，启动并为其他 harness 建立映射 | 实际链接目标、已有路径冲突、各工具对配置语义的解释 | 官网和 CLI 均标 alpha；PyPI 当前为 0.1.0 |
如果你的任务是 Harness.io 中分析 Pipeline 失败，进入 DevOps Agent D01–D14；需要每次 Pipeline 自动执行 Agent，进入 Worker Agent W01–W14；需要从外部客户端访问 Harness 资源，进入 MCP M01–M14。
本站已经验证到哪里
2026-09-10，本站把工具安装到隔离位置并做了不调用模型的检查：
harness 0.1.6能发现本机 Claude Code 与 Codex；harness check codex --capabilities报告 model 支持，system prompt、budget 和 max turns 不支持。- 对固定提示执行
harness run --agent codex ... --dry-run时，解析结果包含--sandbox danger-full-access与--dangerously-bypass-approvals-and-sandbox。本站没有执行这条解析后的命令。你的版本可能不同，但这证明 dry-run 审查是硬门禁。 harnyard 0.1.0在临时目录对 Kiro setup 后，创建.kiro/steering.md → ../.claude/CLAUDE.md和 skill 链接；hy status能把“二进制未安装”和“配置已建立”分别显示。- Open Harness 仓库的 2026-01-18 conformance 记录为 212 项中 186 通过、19 失败、7 跳过，且不同适配器失败原因不同。这个历史结果不能代替你对当前 commit、当前依赖和目标适配器的重跑。
P01：写清你要统一的层
只选一个主要问题：
| 现状 | 候选方向 | 不需要新增适配层的情况 |
|---|---|---|
| 上层程序要分别解析多个 CLI 的输出 | 事件 CLI | 只用一个 Agent，原生 JSON 已稳定 |
| 产品代码需要在多个 Agent runtime 间切换 | API 规范与适配器 | 没有第二个 runtime 或只用公共 LLM API |
| 多个工具重复维护 context、skills、plugins、MCP | 配置桥接 | 规则很少，或各工具语义差异很大 |
在运行卡填写现有痛点、必须能力和最多允许修改的路径。写不清主要问题，P01 失败，先不要安装。
P02：先过项目可用性门禁
对候选记录：官方身份、安装来源、版本、发布日期、许可证、默认分支、最近 commit、Issue 与安全说明。再回答：
- 安装包是否能回到同一维护者的仓库？
- 文档中的版本与实际安装版本是否一致？
- 官网说“支持”时，指规范、适配器声明、测试通过还是生产案例？
- 目标 Agent 与操作系统是否在当前支持表中？
- 卸载与恢复路径是否清楚？
Harnyard 官网的 GitHub 链接在本站核验时返回 404，但 PyPI 包和官网仍可用。把它记为供应链与维护风险，不要把“官网在线”写成“源码可审计”。Open Harness 的 API Reference 展示完整路由，也不能因此推断公共 API 服务或每个适配器已经实现全部路由。
P03：冻结原生 Agent 基线
在独立测试目录保存固定任务合同，并建立：
fixture/
├── input.txt # HARNESS-PORT-771
├── result.json # 运行前不存在
└── evidence/ # 命令、事件、哈希、退出状态让目标 Agent 在没有适配层时完成合同：读取 input.txt，创建 result.json，不得修改 input.txt，不得访问父目录。记录 Agent 版本、模型、工作目录、权限模式、耗时、退出状态、产物 SHA-256 和工具轨迹。
原生基线失败时停止。适配层无法修复凭据、模型、二进制或基础权限问题。
P04：把安装限制在可撤销位置
优先使用能固定版本且不会覆盖日常二进制的方式。例如本站把 Rust CLI 安装到单独的 --root，Harnyard 使用固定版本 uvx --from harnyard==0.1.0。正式采用前再按官方说明决定全局安装。
记录安装前后新增的二进制、缓存与配置路径。不要直接执行未经阅读的远程 shell 安装器；即使它来自官网，也先下载、检查内容与来源，再运行。
P05：执行 dry-run，审最终权限
事件 CLI 路线先执行：
harness --version
harness list
harness check codex --capabilities
harness run --agent codex --prompt 'Return HARNESS-PORT-771' --dry-run把实际 Agent 二进制、全部参数、cwd、model、timeout 和 permissions 写入验收表。若解析结果出现越过你运行卡边界的 sandbox、approval、network 或 writable path 参数，P05 失败；修改配置或放弃候选，不要因为它只是 dry-run 输出就继续运行。
P06：用同一任务运行事件 CLI
只有 P05 通过后，才用 P03 相同的 Agent、模型、输入和权限运行适配层。将 stdout 原样保存为 JSONL，stderr 和进程退出码分开保存。
harness CLI 当前声明八类统一事件：SessionStart、TextDelta、Message、ToolStart、ToolEnd、UsageDelta、Result、Error。实际验收至少要证明：
- 每行都是完整 JSON，不能把普通日志混入 stdout；
- tool start/end 能配对，并能定位读取与写入；
Result或Error只有一个可判定终态；- 进程退出与事件终态不矛盾；
result.json内容、路径和 SHA-256 与任务合同一致。
回答正确但缺失写文件轨迹，或产生了文件却把终态写成成功前中断，都不能通过。
P07：验证不存在文件的错误不会被吞掉
复制测试目录，删除 input.txt，保持提示不变。预期结果是明确失败或明确报告输入不存在，不得创建伪造成功的 result.json。
记录底层工具错误、统一 Error、最终 Result 和进程退出码。适配层如果把底层 not-found 改写成空内容或成功，应用就无法可靠重试，直接判为硬失败。
P08：验证取消真正停止底层进程
使用只允许等待或读取的长任务，启动后按官方方式取消。记录取消请求时间、最后事件时间、子进程退出时间和取消后文件变化。
通过条件是底层进程在门槛内结束、终态能区分 canceled 与 success、取消后不再写产物。关闭上层终端但子进程继续运行属于失败。
P09：验证权限负例
固定任务合同禁止访问 ../outside.txt。在隔离目录中放一个只含 FORBIDDEN-PORT-772 的无敏感文件，请求 Agent “顺便读取父目录”。正确结果是权限层拒绝，且事件中能看见拒绝而不是伪造内容。
不要为了跑通适配器扩大权限。若 P05 已显示绕过审批或全盘写入，本步骤不能用提示词承诺代替真实限制。
P10：比较基线与适配运行
将 P03 与 P06 的结果放在同一行比较：
| 项目 | 原生 | 适配后 |
|---|---|---|
| Agent / model / cwd | 实际值 | 实际值 |
| 权限与审批 | 实际值 | 实际值 |
| 产物 SHA-256 | 实际值 | 实际值 |
| 工具、错误、终态是否可追踪 | 实际值 | 实际值 |
| 耗时与额外失败点 | 实际值 | 实际值 |
内容相同但权限变宽，仍然失败。多一层工具必须带来可量化的统一收益，而不是只改变命令名称。
P11：Open Harness 先查 capability，再谈调用
Open Harness 仓库明确把规范描述为 aspirational。评估时锁定 commit，打开 capability manifest 和目标适配器 README，为应用依赖建立表：
| 必需能力 | 规范存在 | 适配器声明 | 当前 conformance | 本地复验 |
|---|---|---|---|---|
| execution + stream | 待填 | 待填 | 待填 | 未验证 |
| tool events | 待填 | 待填 | 待填 | 未验证 |
| cancel | 待填 | 待填 | 待填 | 未验证 |
| files / artifacts | 待填 | 待填 | 待填 | 未验证 |
| session resume | 待填 | 待填 | 待填 | 未验证 |
“规范存在”只能证明接口被设计过。目标适配器声明和当前测试都通过，才进入集成试点。
P12：重跑目标适配器 conformance
按仓库说明在隔离环境安装依赖，只配置目标适配器所需的测试凭据。记录 commit、依赖锁文件哈希、测试选择、通过/失败/跳过数量和每个失败原因。
不能从总通过率推断必需能力可用。例如历史记录中 session 测试曾因没有声明支持的适配器而全部跳过；若你的应用必须恢复 session，这比其他一百项通过更关键。失败由缺凭据造成，也只能记为未验证，不能改写为通过。
P13：Harnyard 先查看映射，再建立链接
在隔离项目创建最小 .claude/CLAUDE.md 和一个无害 Skill，然后执行当前版本的只读检查：
hy --version
hy list
hy info kiro
hy status保存运行前目录、普通文件和符号链接清单。目标目录已有普通文件时先做负例：setup 必须拒绝或保留现有内容，不能静默替换。
P14：验证链接、语义和清理
只选择一个未安装到日常项目的目标，例如测试 Kiro 映射：
hy setup kiro
hy status逐个检查链接本身和 readlink 目标。文件可达只证明映射存在，还要启动目标工具后验证：上下文是否被读取、Skill 是否触发、权限和 hook 是否按目标工具语义执行。不要假设 .claude/settings.json 中的每个字段都能无损迁移。
清理时只移除本次创建并已核对目标的链接，再确认 .claude/ 源文件哈希未变。不要沿链接递归处理源目录。
P15：按硬门禁作决定
只有以下条件全部满足才进入小范围采用：
- P01–P15 都记录实际证据，所有未执行项仍标“未验证”；
- 原生基线和适配结果使用同一固定输入，产物可复算；
- dry-run 没有扩大权限，父目录负例真实被拒绝；
- 正常、not-found、取消和认证失败均有可判断终态；
- API 路线的必需能力有目标适配器 conformance，不拿规范代替实现；
- 配置路线没有覆盖普通文件，链接语义与清理通过；
- 工具带来的维护减少大于新增的版本、凭据和诊断成本。
任一硬门禁失败就保留原生 Agent，并记录退出原因。等候选版本、支持范围或权限行为改变后，重新从 P02 开始，不复用旧结论。
常见失败按层定位
| 现象 | 第一处证据 | 不要推断 |
|---|---|---|
| CLI 找不到 Agent | harness list、PATH、原生基线 | 统一 CLI 安装坏了 |
| dry-run 权限过宽 | resolved args 与运行卡 | 提示词会自动缩小权限 |
| 最后回答正确但应用报错 | JSONL 解析、终态、进程退出 | Agent 本身一定失败 |
| API 文档有路由但调用不可用 | 目标适配器、commit、conformance | 官网 API 表等于在线服务 |
| Harnyard 显示 configured 但工具没读规则 | 链接目标、目标工具语义 | symlink 存在就完成迁移 |
| 清理后源配置消失 | 链接方向、清理命令记录 | 非破坏性项目声明能覆盖误操作 |
如果仍不清楚模型、工具、状态、权限和 MCP 分别处于哪一层，先完成 Agent Harness H01–H12，再决定是否值得增加适配器。