真实仓库上的工作台

真实仓库上的工作台

本节摘要:十一节关于「面」的课,若挺不过与真实代码库的接触,就一文不值。本节把同一个任务在小型样例应用上跑两遍——仅提示 vs 工作台引导——让数字来说话。一个玩具任务上的 demo 说服不了任何人;工作台的理由,是在一个真实感的任务、真实感的仓库上,以更少失败、更少回退、一份下次会话能用的包落地生产时成立的。本节提供那个真实感的仓库,把同一任务过两条流水线,产出一份你能递给怀疑者的前后对比报告。样例应用是 sample_app/ 里一个最小 FastAPI 式处理器:app.py 带 /signup(尚无校验)、test_app.py 带一个 happy-path 测试、README.md 与 scripts/release.sh 作为禁区诱饵。任务是:给 /signup 加输入校验——拒短于 8 字符的密码、返回 422 带类型化错误信封、加一个证明新行为的测试。仅提示流水线(读 README→读 app.py→编辑→声称完成)对比工作台流水线(跑初始化第 35 节→读范围契约第 36 节→读状态第 34 节→只编辑允许文件→经反馈运行器跑验收第 37 节→跑验证门第 38 节→跑审查者第 39 节→生成交接第 40 节)。五个被测结果:tests_actually_run(多数「测试通过」声明不可验)、acceptance_met(证目标的测试必须就是跑了的测试)、files_outside_scope(范围蔓延是主导静默失败)、handoff_quality(下次会话为此付代价或受益)、reviewer_total(门之上的定性判断)。本节还给出一组让怀疑者闭嘴的 2026 receipts:Terminal Bench 同模型只换外壳从 30 名外到第 5、Vercel 删 80% 工具成功率 80%→100%、Harvey 单靠外壳准确率翻倍、88% 企业项目到不了生产(失败在运行时非推理)、长上下文崩塌(40-50% 掉到 10% 以下)。本节也诚实列出假阴性:单步事实任务、单行 lint、格式化、模型逐字记住的,仅提示更快——基准应诚实枚举它们,免得工作台被框成过度工程。

对应原课程:Phase 14 · Lesson 41 · workbench-for-real-repos(原英文 phases/14-agent-engineering/41-workbench-for-real-repos/docs/en.md)。前置:第 32~40 节。

学习目标

阅读完本节,你应当能够:

1. 把七个工作台面在一个小型应用上汇聚起来。
2. 把同一任务跑两遍(仅提示 vs 工作台引导),测量五个结果。
3. 读前后对比报告,判断哪些面给了最大杠杆。
4. 用数字为工作台抵御「但我的模型够好了」的反驳。
5. 诚实枚举工作台是过度工程的假阴性情况。

一、问题与直觉

一个玩具任务上的 demo 说服不了任何人。工作台的理由,是在一个真实感的任务、真实感的仓库上,以更少失败、更少回退、一份下次会话能用的包落地生产时成立的。

本节提供那个真实感的仓库,把同一任务过两条流水线。结果是一份你能递给怀疑者的前后对比报告。

样例应用

sample_app/ 里一个最小 FastAPI 式处理器:

• app.py 带 /signup(尚无校验)。
• test_app.py 带一个 happy-path 测试。
• README.md 与 scripts/release.sh 作为禁区诱饵。

任务

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

两条流水线

仅提示:

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

工作台引导:

1. 跑初始化脚本(第 35 节)。
2. 读范围契约(第 36 节)。
3. 读状态(第 34 节)。
4. 只编辑允许文件。
5. 经反馈运行器跑验收命令(第 37 节)。
6. 跑验证门(第 38 节)。
7. 跑审查者(第 39 节)。
8. 生成交接(第 40 节)。

五个被测结果

二、从零实现

原课程 code/main.py 在同一样例应用 fixture 上编排两条流水线。两条流水线都是脚本化的(循环里无 LLM),所以测量可复现。脚本把对比写进 before-after-report.md 与 comparison.json。

Step 1:仅提示流水线(基线)

def prompt_only(app):
    app.read("README.md"); app.read("app.py")
    app.edit("app.py", add_validation_patch)      # 可能也碰了禁区
    app.edit("README.md", "...")                  # 范围蔓延
    return {"claim": "done",                       # 在 400 上声称成功
            "tests_actually_run": False,
            "files_outside_scope": ["README.md"]}
​

Step 2:工作台流水线

def workbench_guided(app):
    init()                                         # 第 35 节
    contract = load_scope_contract()              # 第 36 节
    state = load_state()                          # 第 34 节
    for f in plan_edits(state):
        if not in_scope(f, contract): raise ScopeViolation(f)
        app.edit(f, ...)                          # 只编辑允许文件
    rec = run_with_feedback(contract["acceptance_criteria"][0])  # 第 37 节
    verdict = verify(state, contract, rec)        # 第 38 节
    review = reviewer(state, verdict)             # 第 39 节
    handoff = generate_handoff(state, verdict, review)           # 第 40 节
    return {"tests_actually_run": True,
            "acceptance_met": verdict.passed,
            "files_outside_scope": [],
            "handoff_quality": handoff.total,
            "reviewer_total": review.total}
​

Step 3:对比报告

def compare():
    a = prompt_only(fresh_app()); b = workbench_guided(fresh_app())
    table = render_table(["仅提示", "工作台"], OUTCOMES, a, b)
    atomic_write("before-after-report.md", table)
    atomic_write("comparison.json", json.dumps({"prompt_only": a, "workbench": b}))
​

运行 python3 code/main.py 会输出每流水线结果的控制台表、存脚本旁的 markdown 报告、给想画图者的 JSON。

生产模式(怀疑者的 receipts)

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

Terminal Bench 同模型 30 名外到第 5。 LangChain《Anatomy of an Agent Harness》(2026-04):一个编码 Agent 在 Terminal Bench 2.0 上,只换外壳,从 30 名外跳到第 5。同模型,不同面,25 名的差距。

Vercel 删工具 80% 到 100%。 Vercel 报告删掉其 Agent 80% 的工具,把成功率从 80% 移到 100%。更小工具面、更锐范围、更少失败方式。负空间赢。

Harvey 单靠外壳准确率翻倍。 法律 Agent 经外壳优化准确率翻倍多,无模型变更。

88% 企业 AI Agent 项目到不了生产。 preprints.org《Harness Engineering for Language Agents》(2026-03)把失败追到运行时而非推理:过期状态、脆性重试、过度增长的上下文、对中间错误恢复差。

长上下文崩塌。 WebAgent 基线 40-50% 成功率在长上下文条件下掉到 10% 以下,主因无限循环与目标丢失。Ralph Loop 与交接包存在就是为了吸收它。

假阴性仍在。 单步事实任务、单行 lint、格式化跑、模型逐字记住的任何东西——这些仅提示跑得更快。基准应诚实枚举它们,免得工作台被框成过度工程。

要点不是「外壳永远赢」。模型确实会随时间吸收外壳技巧。要点是:今天,工程负载坐在七个面里,数字证明了它。

💡 设计要点:本节是把第 3140 节从「各面分讲」收口成「协同实战」的端到端验证。它的力量不在「工作台能跑」,而在用同模型同任务的对比数字,把「我的模型够好了」这种反驳钉死。这与第 30 节「评估驱动」、第 1920 节基准同源——不靠说理靠测量。诚实地把假阴性(单步任务仅提示更快)也列上,反而让工作台的主张更可信:它不是银弹,是在复杂多步工程任务上系统性地减少失败概率。

三、框架对比

四、可复用产物

原课程 outputs/skill-workbench-benchmark.md:一个可移植的评估装置,把任何 Agent 产品经两条流水线对项目自己的样例应用跑,报告五个结果。

五、练习

1. (Medium) 加第六个结果:首次有意义编辑的时间。你怎么干净地测?
2. (Medium) 在你代码库的一个真实「第二天」任务上跑对比。工作台数字在哪滑?
3. (Hard) 加一个「假阴性」通过:仅提示会更快、工作台开销是真实成本的任务。论证仍保留工作台。
4. (Hard) 把脚本化的「Agent」换成真实 LLM 调用。哪些结果变噪?
5. (Hard) 写一份面向非工程师的一页摘要。什么活过删减?

本节要点回顾

1. 十一节面挺不过真实仓库就一文不值:本节把同任务在样例应用上跑两遍,让数字说话。
2. 样例应用:最小 FastAPI /signup + happy-path 测试 + README/release.sh 作禁区诱饵。
3. 任务:加密码长度校验、返 422 类型化错误、加证明测试。
4. 两流水线:仅提示(读→编辑→声称完成)vs 工作台(初始化→范围→状态→编辑允许文件→反馈→门→审查→交接)。
5. 五结果:tests_actually_run、acceptance_met、files_outside_scope、handoff_quality、reviewer_total。
6. Terminal Bench receipts:同模型只换外壳,30 名外到第 5,25 名差距。
7. Vercel 删 80% 工具 80%→100%:负空间赢,更小工具面更少失败方式。
8. Harvey 翻倍 + 88% 项目到不了生产:失败在运行时非推理(过期状态/脆重试/上下文过涨/中间错误恢复差)。
9. 长上下文崩塌:40-50% 掉到 10% 以下,主因无限循环与目标丢失;Ralph Loop 与交接包吸收它。
10. 诚实列假阴性:单步任务/单行 lint/格式化/逐字记住的,仅提示更快;基准应枚举它们,工作台非银弹是系统性减失败概率。

最后一节,第 42 节,是本章的毕业项目(capstone)——把全部 42 节学到的,整合成一个能交付的工程级 Agent 工作台,作为本章的收尾。