# 项目复盘：让 AI 不只是给答案，而是完成可验证的任务

> From plausible answers to verifiable execution.

## 1. 这是一次什么样的项目

这是一次人机协作实践：我想看看一个 AI Agent 能否不再只是给出看似合理的答案，而是真正成为真实执行流程中的一环。

Agent 的职责是理解任务、检查 terminal 环境、运行命令、产出工件，并做初步调试。我的职责是定义「完成」意味着什么、设计评测边界、复盘失败运行、区分模型失败与环境 / 评测接口失败，并把这些发现转化为工作流改动。

Terminal-Bench 2.0 提供了真实的执行环境，LangChain Deep Agents 提供了 agent 工作流。这个项目不是冲着 leaderboard 排名去的，而是一份作品案例研究——目标是让 AI 的工作变得可观察、可诊断、可验证。

贯穿始终的四个问题是：

1. 执行过程中到底发生了什么？
2. 运行是从哪里第一次偏离任务契约的？
3. 原因是 agent、环境，还是评测接口？
4. 下一步应该测试哪一个工作流改动？

## 2. 背景

基于 terminal 的 benchmark 暴露了 AI 系统的一个实际短板：一个 agent 可能理解了任务、写出了合理的代码、描述了正确的思路，却依然失败——因为工件不完整、存错了名字、或者与验证器不兼容。

我用 Terminal-Bench 2.0 作为真实执行环境，用 LangChain Deep Agents 研究这个短板。这项工作组合了 agent 运行、容器化编排、执行轨迹、验证器结果、人工失败分析，以及一个基于 LLM 的诊断 judge。

## 3. 问题定义

一个 terminal 任务的可观测结果通常是二元的：验证器接受工件，或者不接受。这个信号必要，但不足以改进 agent。

两个失败运行可能有完全不同的含义：

- 一个可能计划正确，只是卡在网络或工具挂起上；
- 另一个可能跑完了所有命令，却写出了语义错误的输出；
- 第三个可能在检查输入前就破坏了它；
- 第四个可能误解了路径、形状或格式契约。

如果把这四种情况都归为「模型失败了」，下一步的 prompt 或工程改动很可能打偏。

## 4. 为什么用 agent，而不是简单的 LLM 问答

简单的「提问 - 回答」交互，无法建模 terminal 任务中真正重要的状态变化。Agent 必须：

- 检查一个陌生的环境；
- 选择和排序命令；
- 创建或修改文件；
- 观察 stdout、stderr、退出码和验证器反馈；
- 在不丢失原始证据的前提下从失败中恢复；
- 判断工件何时算完成；
- 满足外部的输出契约。

因此，terminal 既是工具面，也是真实反馈的来源。agent 最后那段文字，只是结果里很小的一部分。

## 5. 工作流设计

工作流有七个实际阶段：

1. **任务输入：** 保留任务目标和精确的输出契约。
2. **Agent 计划：** 识别依赖、文件、命令和验证步骤。
3. **终端执行：** 在隔离环境里运行命令。
4. **反馈循环：** 捕获工具结果、错误和中间工件。
5. **验证：** 运行 benchmark 的验收检查。
6. **失败诊断：** 抽取最小证据包，打上 L1/L2 标签。
7. **迭代：** 每次改动一个工作流变量，与受控集合对比。

核心设计选择是：把「任务正确性」和「失败诊断」分开。benchmark 验证器决定任务是否通过；诊断层解释失败原因，并支撑优先级判断。

## 6. 人机分工

Agent 的价值在于能快速、稳定地执行大量具体步骤。人的判断在边界处仍然不可或缺：

- 检查 agent 是否理解了真实目标；
- 判断一个错误是推理、工具使用、基础设施还是评测契约造成的；
- 复核模糊的标签；
- 为相近的失败模式定义证据规则；
- 判断一个改动是真策略变化，还是又一次局部微调。

这种分工也改变了「prompt 工程」在这个项目里的含义。重要的不是把一句指令写得更漂亮，而是设计约束、反馈、停止条件和验证点，让指令真正可执行。

## 7. 评测设计

评测分两层。

### 任务结果

benchmark harness 通过 reward 和验证器结果给出通过 / 失败信号。这是任务完成情况的事实来源。

### 失败诊断

诊断分类体系使用：

- **L1：** 顶层结果，如成功、超时、验证失败或基础设施失败；
- **L2：** 主因，如逻辑错误、误解、输出错误、工具挂起、进展过慢或网络失败；
- **evidence：** 相关的验证断言、命令结果、轨迹片段或环境信号；
- **confidence：** 对证据支持标签程度的受限估计。

因此，judge 是一个诊断分类器，不是替代评测器。一个提升 judge 一致率却没有提升真实任务结果的改动，并不自动等于 agent 改进。

## 8. 失败模式

复盘过的案例呈现四类反复出现的模式：

- **契约不匹配：** agent 构建了一个能用的组件，却暴露在验证器不使用的路径或格式上。
- **不可逆的顺序：** agent 在保留恢复所需证据之前，就执行了改变状态的操作。
- **不收敛的迭代：** agent 反复做小参数调整，却没有改变已经失败的策略。
- **语义误解：** agent 把一个技术正确的概念用到了错误的任务理解上。

这些模式比一个笼统的失败总数更有指导意义，因为每一类都指向不同的干预手段。

## 9. 迭代

分类体系本身被当作一个不断演进的工程工件。迭代模式是：

1. 复盘人工标注的轨迹；
2. 为常见类别定义证据规则；
3. 在开发对比集上测试 judge；
4. 冻结一套回归式的对比集；
5. 检查不一致案例，写下 tie-break 规则；
6. 当观测证据支持时，删除冗余标签或调整优先级。

一些有用的边界规则示例：

- 重复相同失败动作且不改变策略，提示陷入循环；
- 工件各不相同、指标在改善但时间不足，提示进展过慢；
- 只有轨迹显示「概念本身没被理解」时，缺失领域概念才支持 knowledge gap；
- 格式正确但语义内容错误，支持 wrong output；
- 运行器或网络异常不应归因于 agent 推理。

## 10. 结果

现有的对比报告显示：

| 数据集 | 案例数 | 严格 L2 主标签一致率 | 主或次标签一致率 |
|---|---:|---:|---:|
| Judge 开发对比 | 25 | 88% | 92% |
| Judge 测试对比 | 20 | 70% | 75% |

开发对比强于独立测试对比，这与「诊断系统在开发样例上校准、再在独立集合上检查」的预期一致。这个差距本身是有用的证据：它指出仍需更清晰证据规则的边界案例，而不是需要更自信的文字。

首轮任务快照也说明为什么必须把基础设施分开看。开发快照报告 117 个有效试验中 41 个成功（排除 11 个基础设施错误）；测试快照报告 29 个有效试验中 17 个成功（排除 6 个限流错误）。这是两个独立的运行快照，不是单一最终 benchmark 分数。

## 11. 反思

核心结论是：可靠的 AI 协作是一个系统工程问题。Agent 需要定义清晰的任务、真实反馈的通道、安全的执行顺序、验证工件的方法，以及能区分不同失败类型的诊断循环。

这个项目也改变了「改进的单位」。比起问「什么 prompt 能让 agent 更聪明」，更有用的问题是：

> 这个工作流应该减少哪一类可观测的失败模式？什么样的受控证据能证明它真的改善了？

这个框架可以迁移到其他 agentic 系统：使用工具的助手、软件 agent、研究工作流、运营 copilot——在这些场景里，「看似合理的答案」不等于「已完成的任务」。