AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

真实仓库上的工作台 ​

十一课的接触面，如果挺不过与真实代码库的交锋，就一文不值。这一课在一个小示例应用上把同一个任务跑两遍：仅 prompt vs 工作台引导。数字来论证。

类型： Build 语言： Python（标准库） 前置要求： 阶段 14 · 32 到 14 · 40 预计时间： ~60 分钟

学习目标 ​

  • 在一个小应用上把七个工作台接触面整合到一起。
  • 把同一个任务跑两遍（仅 prompt 和工作台引导）并度量五个结果。
  • 读 before/after 报告，判断哪些接触面给了最大杠杆。
  • 面对「但我的模型够好了」的反弹为工作台辩护。

问题背景 ​

在一个玩具任务上演示说服不了谁。工作台的论据，是在一个有真实感的任务、一个有真实感的仓库上以更少失败、更少回退、加一个下个会话能用的包落到生产时才立得住。

这一课提供那个有真实感的仓库，并让同一个任务过两条流水线。结果是一份你可以递给怀疑者的 before/after 报告。

核心概念 ​

mermaid
flowchart TD
  Task[任务：校验 /signup 并加测试] --> A[仅 prompt 运行]
  Task --> B[工作台引导运行]
  A --> M[度量：5 个结果]
  B --> M
  M --> Report[before-after-report.md]

示例应用 ​

sample_app/ 里一个极简的 FastAPI 式处理器：

  • app.py，带 /signup（还没校验）。
  • test_app.py，带一个顺利路径测试。
  • README.md 和 scripts/release.sh 作为禁区诱饵。

任务 ​

给 /signup 加输入校验：拒绝短于 8 字符的密码，返回 422 加一个带类型的错误信封。加一个证明新行为的测试。

两条流水线 ​

仅 prompt：

  1. 读 README。
  2. 读 app.py。
  3. 编辑文件。
  4. 声称完成。

工作台引导：

  1. 跑 init 脚本（第 35 课）。
  2. 读范围契约（第 36 课）。
  3. 读状态（第 34 课）。
  4. 只编辑允许的文件。
  5. 通过反馈运行器跑验收命令（第 37 课）。
  6. 跑验证关卡（第 38 课）。
  7. 跑审查者（第 39 课）。
  8. 生成交接（第 40 课）。

度量的五个结果 ​

结果为什么重要
tests_actually_run大多数「测试通过」声称是不可验证的
acceptance_met证明目标的那个测试必须是跑过的那个测试
files_outside_scope范围蔓延是占主导的静默失败
handoff_quality下个会话为它付出代价或从中受益
reviewer_total在关卡之上的定性判断
figure
wb-ab-runs

动手构建 ​

code/main.py 在同一个示例应用 fixture 上编排两条流水线。两条流水线都是脚本化的（循环里没有 LLM），所以度量可复现。脚本把对比写进 before-after-report.md 和 comparison.json。

运行它：

python3 code/main.py

输出：每条流水线结果的控制台表、存在脚本旁边的 markdown 报告，以及给想画图的人用的 JSON。

野外的生产模式 ​

怀疑者的问题是「工作台到底帮多大忙？」2026 年的数字比解释说得多得多。

同一个模型在 Terminal Bench 上从前 30 到前 5。 LangChain 的《Anatomy of an Agent Harness》（2026 年 4 月）：一个编码 agent 仅靠改 harness 就在 Terminal Bench 2.0 上从前 30 名开外跳到第五名。同一个模型。不同的接触面。25 名的差距。

Vercel 靠删工具从 80% 到 100%。 Vercel 报告删掉它 agent 80% 的工具把成功率从 80% 移到 100%。更小的工具接触面、更锐利的范围、更少的失败途径。负空间获胜。

Harvey 仅靠 harness 准确率翻倍。 法律 agent 仅靠 harness 优化就把准确率翻了一倍多，没改模型。

88% 的企业 AI agent 项目无法进入生产。 preprints.org 的《Harness Engineering for Language Agents》论文（2026 年 3 月）把失败追溯到运行时，而非推理：过时状态、脆弱重试、过度生长的上下文、从中间错误中恢复不力。

长上下文崩溃。 WebAgent 基线 40-50% 的成功率在长上下文条件下掉到不足 10%，大多源于死循环和目标丢失。Ralph Loop 和交接包的存在就是为了吸收那个。

假阴性仍然存在。 单步事实任务、一行 lint、格式化器运行、任何模型逐字记住的东西 —— 这些仅 prompt 跑得更快。基准应该诚实地把它们列举出来，免得工作台被框定成大材小用。

要点不是「harness 永远赢」。模型确实会随时间吸收 harness 技巧。要点是今天，工程负载坐在七个接触面里，数字证明了这点。

实际使用 ​

这一课是你引用的案卷，当：

  • 有人问为什么每个 PR 都带一个 agent-rules.md 和一个范围契约。
  • 一个团队想「就这个 sprint」丢掉验证关卡。
  • 一个新 agent 产品上线，你需要一个可移植基准来判断它是否真省时间。

数字比解释传得更远。

拿去用 ​

outputs/skill-workbench-benchmark.md 是一个可移植评估 harness，让任意 agent 产品对着一个项目自己的示例应用过两条流水线，并报告五个结果。

练习 ​

  1. 加一个第六个结果：到第一次有意义编辑的时间。你怎么干净地度量它？
  2. 在你代码库里一个真实的第二天任务上跑这个对比。工作台数字在哪里滑落？
  3. 加一遍「假阴性」：那些仅 prompt 本来更快、工作台开销是真实成本的任务。仍然为保留工作台辩护。
  4. 把脚本化「agent」换成一次真实 LLM 调用。哪些结果变得更嘈杂？
  5. 撰写一份面向非工程师的一页摘要。什么挺过了删减？

关键术语 ​

术语大家怎么说它实际是什么
Sample app「玩具仓库」小但真实到足以演练所有七个接触面
Pipeline「工作流」agent 遵循的、有序的接触面读/写序列
Before/after report「收据」你递给怀疑者的产物
False negative「工作台大材小用」仅 prompt 更快的任务；诚实列举有用
Workbench benchmark「可靠性分数」在你代码库上跑这个对比的可移植 harness

延伸阅读 ​