团队把同一个模型接进两套系统。第一套只把仓库说明和用户问题拼进 Prompt，再提供一个通用 Shell； 第二套会先定位相关文件，按项目规则构造上下文，把读取、修改、执行和验证拆成不同工具，并在测试失败后 把结构化结果送回循环。前者常常给出一段看似合理的建议，后者更可能完成一次可以检查的修改。
这并不自动证明第二套“模型更强”。模型名称相同，但它们实际看到的事实、能够采取的动作、收到的反馈 和被要求满足的出口条件都不同。反过来，如果两套系统给出同样的信息与动作空间，模型仍持续误解核心 问题，也不能继续把责任推给 Harness。
所以，讨论 Agent 表现时最先需要的不是排行榜，而是一条归因纪律：模型、Harness、执行环境与人工批准 分别负责什么；失败发生后，应该修哪一层。
一、一次失败，可能来自四个完全不同的位置
假设任务是“修复登录过期后无法刷新 Token 的问题，并运行相关测试”。最终没有修好，表面结果只有一个： Agent 失败。实际至少存在四种原因。
第一种是模型判断错误。它已经看到刷新逻辑、错误堆栈和测试，但把并发竞争误判成 Token 格式问题。
第二种是 Harness 构造了错误问题。它只发送了 Controller，没有发送真正持有刷新状态的 Client；或者工具 输出被截断，关键异常恰好消失。模型并不是在完整证据上做判断。
第三种是执行环境没有兑现动作。模型正确提出修改，也正确调用测试，但容器缺少依赖、工作目录错误、网络 受限，或者写入发生在临时副本。此时继续调 Prompt 不会让测试突然可用。
第四种是出口条件失真。系统把“命令已启动”记成“测试通过”，把一次上传 ACK 记成公网可访问，或者在 正文变化后继续沿用旧审核结论。模型甚至可能已经完成它被要求的部分，错误出在状态晋级。
这四种失败需要四种不同动作：换模型、修 Harness、修环境、修 Gate。把它们都归为“AI 不稳定”，既无法 复现，也无法改善。
二、Pi 的分层为什么适合观察这条边界
Pi v0.82.1 / b4f2936 把相关职责拆在不同 Package 中。pi-ai 处理多 Provider 模型接口；
pi-agent-core 承担 Tool Calling、状态与 Agent Runtime；pi-coding-agent 组装代码工具、Session 和 CLI；
pi-tui 处理终端交互。Coding Agent 的包描述还明确列出 read、bash、edit、write 与 Session 管理。
这些事实只证明 Pi 的固定版本如何分层，不证明 Pi 在所有任务上优于其他 Coding Agent。但分层提供了一个 很有用的观察框架：模型 API、运行循环、产品工作流和用户界面不是同一个对象，不能用一个“Agent 效果” 指标把责任全部混在一起。
可以把一次 Coding Agent 任务压缩成下面的闭环：
任务与项目状态
→ Harness 选择观察内容
→ 模型生成文本或动作意图
→ Harness 校验并执行动作
→ 环境产生结果和副作用
→ Harness 更新状态并决定继续或停止
→ 人工批准高风险结果模型处在闭环中，但不是整个闭环。所谓 Harness，是包围模型、负责组织上下文、工具、执行反馈、状态和 停止条件的工程系统。它不是一个更长的 System Prompt，也不是把多个脚本依次调用起来的别名。
三、模型与 Harness 责任矩阵
真正有用的分工不是“模型负责智能，系统负责其他”，而是把每一步可检查的责任写清楚。
| 阶段 | 模型主要责任 | Harness 主要责任 | 环境或人工责任 |
|---|---|---|---|
| 观察 | 从给定证据中识别问题、冲突和缺口 | 选择相关文件、规则、历史和工具结果；控制截断与优先级 | 人工确认高风险来源与任务范围 |
| 决策 | 提出方案，选择下一动作，解释不确定性 | 暴露可用动作、Schema、预算和权限边界 | 环境真实提供文件、进程、网络和凭据能力 |
| 执行 | 生成参数或修改内容 | 校验参数、调用工具、隔离副作用、绑定 Attempt | 操作系统或外部服务执行真实动作 |
| 反馈 | 解读成功、失败和反例，决定是否修正 | 忠实返回 stdout、stderr、状态码、结构化错误和被截断范围 | 外部系统提供可核验响应 |
| 状态 | 在当前上下文内维持计划和假设 | 保存 Session、Artifact、任务版本、幂等键和取消状态 | 人工处理冲突与不可逆决策 |
| 验证 | 解释证据是否支持结论 | 运行确定性检查，绑定产物 SHA，阻止旧结论继承 | 独立审核者和 Owner 做最终判断 |
矩阵里最容易被忽略的是“反馈”。模型调用工具之后，下一步判断完全依赖 Harness 怎样描述结果。如果工具
只返回 failed，模型不知道是权限、参数、超时还是断言错误；如果 Harness 把数千行日志原样塞回上下文，
关键行又可能淹没在噪声里。有效反馈不是越多越好，而是既忠实又能定位。
另一个容易混淆的是“验证”。模型可以建议运行哪些测试，也可以解释测试结果，但它不应该自行宣布自己 的产物已经独立审核通过。确定性脚本、独立审核与 Owner 决策解决的是不同风险，不能由同一次生成调用 同时代替。
四、同一个模型，为什么实际面对的不是同一个问题
说“两套 Agent 使用同一个模型”只控制了一个变量。只要下面四项不同，模型收到的实际任务就已经改变。
1. 观察空间不同
一个系统发送整个仓库摘要，另一个只发送与调用链相关的文件；一个系统加载项目规则，另一个没有；一个 系统保留最近 Tool Result，另一个在 Compaction 后丢掉了未完成事项。模型名称相同，输入状态并不相同。
观察空间不是越大越好。无关文件会争夺注意力，过期状态会制造冲突，缺少来源标识会让模型把作者推导 当成官方事实。Harness 的责任是让模型看到完成当前判断所需、且能够追溯版本的证据集合。
2. 动作空间不同
只有通用 Shell 的系统理论上能完成很多事，但模型必须自己拼命令、解析输出并维护路径。提供类型明确的
read、edit、bash 等动作，可以缩短从意图到执行的距离，也能在调用前做参数校验。
动作越多同样不一定越好。数百个工具一次性进入上下文，会增加选择冲突和 Schema 成本。关键不是工具 数量，而是当前阶段是否给出了足够且边界清楚的动作。
3. 反馈语义不同
同一条测试命令，一套系统可能只返回退出码，另一套同时返回失败用例、截断说明、执行目录和耗时。后者 并没有替模型完成推理，但减少了模型对环境状态的猜测。
如果 Tool Result 与真实副作用不一致，模型再强也会在错误世界模型上继续行动。例如，上传接口返回成功 只证明服务接收请求，不证明对象可公网访问；Harness 若把两者混为一谈，后续发布判断必然失真。
4. 状态与出口不同
一次回答可以靠当前 Context 维持状态，长任务却需要跨轮次、跨失败和跨执行器保存 Task、Attempt、Artifact 与批准关系。没有持久化状态时，模型只能根据对话文本猜“做到哪一步了”。
出口条件同样塑造行为。“修改文件后结束”与“修改文件、通过指定测试、记录未验证项后结束”会让模型 选择不同动作。Harness 不是事后统计器，它通过停止条件直接影响任务路径。
五、遇到坏结果时，按五个问题定位
读者最终需要的不是再背一套架构名词，而是一套换模型之前可以执行的诊断顺序。
问题一：模型是否看到了完成判断所需的事实
检查实际送入模型的文件、规则、历史与 Tool Result，而不是检查仓库里“本来存在什么”。若关键证据没有 进入观察空间，先修检索、加载或截断策略。
问题二：模型是否拥有正确且可用的动作
检查工具是否适合当前阶段、Schema 是否能表达目标、权限是否真实开放。若模型只能提出建议却无法读取、 修改或验证，问题在动作空间，不在语言质量。
问题三：反馈是否忠实描述了真实执行
检查退出码、错误类型、工作目录、截断范围、远端状态和副作用。若反馈含糊或失真，先修 Tool Result 契约。
问题四：状态是否绑定当前任务版本与产物
检查 Attempt、输入版本、Artifact SHA、取消状态和旧批准是否仍然有效。若旧状态泄漏到新产物，继续调用 更强模型只会在错误状态上产生更昂贵的结果。
问题五：在前四项相同后，模型是否仍反复做错核心判断
只有到了这里，换模型、提高推理强度或调整专门后训练才成为主要路线。可比较同一冻结任务集上的关键 错误率、升级率、返工量和成功成本，而不是拿两个不同 Harness 的主观体验直接归因给模型。
这套顺序并不要求每次都完整审计系统。它要求团队保留足够的运行记录，使失败能够落到具体层，而不是 只留下“这次 AI 写得不行”。
六、Harness 能改善什么，不能改善什么
Harness 可以减少信息缺失、动作歧义、反馈失真、状态漂移和虚假完成。它还能把一次偶然成功变成可回放、 可比较的执行记录。这些能力会影响模型能力被利用的程度。
但 Harness 不能凭空创造模型没有的推理能力。面对陌生算法、复杂跨域综合或高度含糊的目标，模型可能在 完整证据与正确工具下仍然给出错误判断。此时更强模型、领域专家或拆小任务是合理选择。
还有一些简单任务根本不需要复杂 Harness。确定的字段迁移、格式规范化和可逆链接回填，用脚本比 Agent 更便宜、更可靠。把所有工序都交给模型，不是重视智能，而是在放弃确定性。
本文也没有完成跨 Harness 受控实验，因此不能给出“某种 Harness 能提升多少成功率或节省多少 Token”的 数字。Pi 的固定源码分层支撑的是责任边界，不是性能排行榜。
七、把 Agent 评价从品牌问题改成系统问题
当一个 Agent 表现不好时，直接问“是不是模型不行”太早，直接说“都是 Harness”也同样武断。更准确的 问题是：模型实际看到了什么、能做什么、收到了什么反馈、系统保存了什么状态、完成由谁证明。
Pi 值得研究的原因正在这里。它不是因为默认功能最多，而是因为模型接口、Agent Runtime、Coding Agent 和终端交互能够分别观察。开发者可以看到，一次看似自然的 Coding Agent 行为，背后由多层责任共同完成。
最终可以保留一句归因原则：
模型决定在给定观察和动作空间中的判断质量；Harness 决定这个空间、反馈和状态是否可靠；环境兑现动作；人工为不可逆结果负责。
先按这条边界定位，再决定修上下文、工具、运行时、环境、门禁还是模型。这样得到的不是一句对 AI 的印象， 而是一条可以复现和改进的工程结论。
参考资料
- Pi
v0.82.1固定源码树：https://github.com/earendil-works/pi/tree/v0.82.1 - Pi Coding Agent README（固定 Tag）：https://github.com/earendil-works/pi/blob/v0.82.1/packages/coding-agent/README.md
- Pi Coding Agent package.json（固定 Tag）：https://github.com/earendil-works/pi/blob/v0.82.1/packages/coding-agent/package.json
- Pi Agent Core package.json（固定 Tag）：https://github.com/earendil-works/pi/blob/v0.82.1/packages/agent/package.json
- Pi AI package.json（固定 Tag）：https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/package.json
- Pi TUI package.json（固定 Tag）：https://github.com/earendil-works/pi/blob/v0.82.1/packages/tui/package.json
证据与推导边界
- Pi 包职责与 Coding Agent 表面能力：固定版本第一方来源。
- 模型/Harness/环境/人工责任矩阵与五问诊断：作者工程综合。
- 跨 Harness 性能提升、Token 节省和成功率幅度：未运行、未知，不作结论。