Skip to content

第22章 · 毕业设计 Capstone、clean-room 抽测与答辩 ​

前置要求:掌握 第21章 · 严谨评估、红队安全与受控云部署 的全链路质量门禁与生产交付规范。

这是主线的最后一章:把前18章学到的所有零件——TinyGPT、RAG、typed tools/MCP、状态恢复、HITL、评估、trace——组装成一个完整系统:Evidence-driven Safe Agent Harness。然后接受三重检验:产品证据(固定评估集打分)、真实浏览器旅程(headed Chrome 走完交互)、人类答辩(你闭卷解释,人来判断)。三条门线互相独立,任何一条都不能替代另外两条。

产品证据、真实浏览器和学习者人类答辩是三条独立门线。

本章目标 ​

学完后你能做到:

  • 将教学 TinyGPT、RAG、typed tools/MCP、状态恢复、HITL、评估和 trace 串成 Evidence-driven Safe Agent Harness。
  • 从空白接口重建 L3 主链,回答故障题并解释模型与系统的责任边界。
  • 用固定评估集、人工闭卷解释和真实浏览器旅程分别判断产品质量与学习者掌握;两者不能互相推出。

阶段一:Capstone 全景——可观测链路与指标门槛 ​

Capstone 的可观测链路:

text
input
  → planner/executor output
  → RAG / typed tool validation
  → policy / HITL
  → checkpoint / trace
  → terminal output

固定评估报告至少保留这些指标:

指标首版门槛
确定性任务成功率≥ 85%
tool schema/参数合法率100%
citation correctness≥ 90%
unsupported claim rate≤ 5%
ACL/HITL bypass0
定义故障的 recovery rate≥ 95%

模型调用数量、状态步数、消息 token 数和 trace 事件数量都要有明确上限;没有调用或没有引用不能通过把分母变成零。

Trajectory grading:不是只看最终答案,而是对每一步按 rubric 打分,为正确的中间决策给分。本仓库的 eval_harness.py 和 capstone.py 只测量终态指标(task_success、schema_validity、citation_correctness、recovery),不实现 trajectory grading。

Pass@k:对同一任务采样 k 个完成,只要有一个通过即算解决。报告时需明确 k 值;k 越大表面成功率越高,但计算成本也越高。本仓库不实现 pass@k。

Cons@k:对同一任务独立采样 k 条链,取多数投票;在有可验证答案的任务上提高准确率,但在模型以相同方式系统性地自信错误时会退化(所有 k 条链投同一个错票)。这与第12章讨论的 self-consistency(maj@64)是同一家族的方法,详细分析见该章。

Cost-normalised scoring:将成功率除以 token 数或费用,避免"更贵的 agent 自动成为最好的"。本仓库的 capstone harness 记录 side-effect 计数和 trace 长度,但不计算 cost-normalised 成功率。

全链回顾:工程与数学底座的 12 个核心函数都在哪 ​

回头看,整条 LLM 主链的每一环都在调用前置工程与数学底座中练过的基础函数:

核心基础函数对应章节与环节完整链路中的角色
dot_product(a, b)第8章 AttentionQK⊤ 的核心:衡量 token 间的相关度
neg_log_likelihood(p)第5章 概率语言模型单 token 的 loss = −log⁡(pcorrect)
cross_entropy(p_dist, q_dist)第5/7/9/11章训练目标:模型分布 vs 目标分布的 CE
categorical_sample(probs, rng)第5/10/11章temperature 采样:从模型输出分布中抽样
mle_bernoulli(trials)第11/21章eval 指标的概率估计:成功次数 / 总次数
entropy(probs)第6/10/11章BPE 压缩 / 量化信息损失 / 模型不确定性
kl_divergence(p, q)第11章 DPO衡量 policy 和 reference 模型的分布距离
partial_derivative(f, x, x0)第4/7章 反向传播标量链式法则:每个参数的梯度
gradient_descent_step(param, grad, lr)第4/7/9/15章SGD 更新 / checkpoint 恢复 / Agent 状态转移
momentum_update(velocity, grad, lr, beta)第7/9/15章AdamW 动量 / optimizer state / Agent 轨迹
relu(x)第4/7/8/10章FFN 激活 / SwiGLU 门控基础
mlp_layer_forward(x, W, b, activation)第5/8章Bigram MLP → Transformer FFN

完整的 LLM 主链可以抽象为:

Tokenize→第6章Embed→第8章Attend→第9章Train (CE)→第11/21章Align/Eval→第13/15章Agent

通用 Agent 平台企业级系统架构设计 (LL-Agent-3) ​

在毕业设计中,不仅要能在单进程内跑通 Agent Harness,更需要具备工业级 通用 Agent 平台(Universal Agent Platform) 的系统设计视野。大规模企业级平台必须严格实行**控制面(Control Plane)与数据面(Data Plane)**的架构解耦:

五大核心层生产级失败模式与系统防线矩阵 ​

系统分层典型生产级失败模式 (Failure Mode)发生机制与系统危害架构级应对防线与防护机制
1. API Gateway客户端断连引发的“幽灵任务”(Zombie / Orphaned Tasks)用户关闭页面或断网,网关未级联取消,后端 Agent 继续跑完全程消耗巨额 Token。上下文取消透传与心跳反压:网关检测到断开立即广播 CancellationToken,Runtime 立即中断并就地 Checkpoint。
2. Agent Runtime外部工具挂起引发的 Worker 协程池饥饿(Pool Starvation)某些外部工具 HTTP 挂起或沙箱死循环,耗尽 Runtime 协程池,导致正常请求排队超时。沙箱硬隔离与抢占式超时:每个 ToolSpec 绑定异步硬超时;沙箱限额 CPU/内存,超期强制回收。
3. 统一持久化层并发写冲突导致状态丢失(State Drift / Concurrent CAS Race)两个并发分支或重试节点同时写回同一 Session 的 Checkpoint,产生后写覆盖先写。基于版本号的乐观并发控制(OCC / CAS):UPDATE ... WHERE session_id=X AND version=V,冲突触发拉取重试。
4. 模型网关层上游 429 限流诱发的集群重试风暴(Retry Storm & Herd)某模型 Provider 限流,数百个并发 Agent 节点同时无退避重试,造成系统彻底雪崩。自适应指数抖动退避(Jittered Backoff)与多渠道自动 Failover 降级。
5. 观测与审计层长文本与中间思考回传导致日志队列 OOM(Trace Dropping)Agent 高频思考块与大图片全量写入 trace,导致 Kafka 队列堆积溢出,关键告警丢失。分级采样与冷热分离:结构化状态码 100% 写入热存,大 Payload 异步流式压缩入 S3。

延伸:Coding Agent 的工程画像 ​

通用平台的架构与失败模式讲完,值得顺着 harness 这条线看一个最重要的应用域:Coding Agent——在真实仓库里读代码、改代码、跑测试、提交修复的代理。本课不实现 coding agent(本章 capstone 的通用 harness 已覆盖其骨架:typed tools、policy/HITL、checkpoint/trace 全部原样复用),此处给出的是工程画像级理解——工具面、上下文策略、执行循环、评估口径四张切片,每一片都能在前面章节找到对应零件。

1. 工具面收敛:三类原语覆盖绝大多数工作 ​

成熟 coding agent 的工具注册表出奇地小:shell 执行(跑测试、构建、git)、文件编辑(读、写、打补丁)、搜索(文件名匹配、内容检索、符号定位)——三类原语即覆盖绝大多数工程动作。工具面收敛是设计而不是简陋:每多注册一个工具,就多一份 schema 校验、策略判定与系统提示里的 token 开销(第15章的 shape 契约、第17章 Context Engineering 预算模型里 MCP 工具 Schema 占据的槽位),而三类原语的正交组合表达能力已经足够。这个工具面也恰好是第15章 Progent 权限分级的最典型应用场景——四级判定可以逐行落上来:

动作Progent 级别coding agent 语境
读文件、内容检索、看目录结构Level 0 只读直接放行,占绝大多数调用
在工作区写代码、跑测试、构建Level 1 幂等可逆写沙箱内执行,绑定 idempotency_key
删生产文件、改 CI 配置、外网请求Level 2 特权挂起等待 HITL 审批
rm -rf 根目录、提权后门Forbidden确定性内核直接拦截

第15章的四层沙箱纵深(进程 / 容器 / MicroVM / Wasm,加资源硬配额与出站白名单)在 coding agent 语境下不是可选项而是前提:模型生成的代码本身就是不可信输入,测试与构建绝不能在宿主机裸跑。

2. repo map 先行:先建结构认知,再动手 ​

动手改代码之前,先花预算建立仓库结构认知:目录树、模块边界、测试位置、构建入口、配置文件。这不是流程礼节,而是上下文预算的必然推论——真实仓库动辄几十万行,不可能整体装进窗口;第17章的预算模型要求每个读进上下文的文件都在动态区预算内值回票价。先读结构、再按需精读文件,等价于把第13/14章 RAG 的「先召回定位、再 rerank 精读」两段式搬到代码仓库:搜索工具就是 coding agent 的 retriever,repo map 就是它的索引。跳过这一步直接全文翻找的代理,要么烧穿预算,要么在无关文件里耗尽步骤。

3. 测试驱动循环:失败测试就是 verifier ​

coding agent 的核心执行循环是测试驱动的:跑测试 → 读失败输出 → 提出根因假说、做最小修改 → 再跑,直到通过且无回归。循环的每一环都是本课已有零件:

  • 读失败:结构化 Execution Feedback(第15章 Naptime 范式)——只回传 error_type、fault_location、截断 stderr,外加强制 wall-clock 熔断防死循环;把 500 行裸 traceback 整段倒进上下文,既烧预算又稀释注意力。
  • 最小修改:改动边界由工作区沙箱圈定,副作用由幂等键记账——本章「幂等 + 可恢复 harness」的直接应用。
  • 再跑:循环状态由 checkpoint/trace 记录,崩溃后从最近一步续跑,而不是从头再来。

更深一层:失败的测试就是 coding agent 的 verifier。「测试通过 / 不通过」是不需要 LLM judge 的可自动判定信号——这与第11章 RLVR 的判卷器思想同源(代码通过单元测试就是可验证 reward),区别只在用途:RLVR 把它用作训练信号,coding agent 把它用作推理期的循环控制。

4. 评估口径:回链 SWE-bench 治理 ​

评估视角直接回链第21章的 SWE-bench(Jimenez 等,2023)叙事,两个要点那章已展开,这里只做画像级收束。pass@k 与 pass@1 的分歧:学术评估用 pass@k 探潜力上限(本章阶段一已给出它的定义与 k 值口径),工业准出锁定 temperature=0 的单次通过率。Verified 子集治理:人工复核剔除近 60% 缺陷用例(2,294 → 500)消除基准方差。收束句与 capstone 的评估哲学同构:verifier(测试套件)必须先于 agent 被审计——评测标尺本身是弯曲的,所有测量精度都毫无意义。


阶段二:组装系统 ​

  1. 先运行所有 focused tests,再从空白骨架手写一条最小模型主链:token → logits → loss → update → generate/cache。空白接口见仓库 clean_room/;pnpm clean-room:contract 只验证合同完整,不把骨架或页面勾选当作掌握。

  2. 用固定 synthetic/public fixture 接入 RAG 和 typed tools;对 read-only、reversible write、HITL write、forbidden action 各跑一次。

  3. 注入 timeout、replay、shape/mask/tokenizer/cache 错误,提交修复前后 trace 和 evidence。

  4. 运行当前已有的组合回归:

    bash
    PYTHONPATH=python python -m pytest \
      python/tests/test_transformer_contract.py \
      python/tests/test_trainable_tinygpt.py \
      python/tests/test_rag_acl.py \
      python/tests/test_agent_recovery.py \
      python/tests/test_tool_policy.py \
      python/tests/test_eval_spec.py -q
    PYTHONPATH=python python -m agent_core.eval \
      --spec eval/eval-spec-v1.yaml --replay eval/fixtures

当前已有 python/agent_core/、eval-spec-v1 和相关测试;本地 Capstone 对真实产生的 schema/citation 计数,对没有生成主张的场景明确记录 unsupported_claim_rate=not-measured,而不是写入 0。完整 clean-room 抽测、人工答辩和真实浏览器验收不是这些测试自动完成的事项,必须明确保持 gate。

阶段三:Clean-room 抽测(Learner submission contract) ​

clean_room/contracts.json 保留 7 个 blank interface 作为起点,并为每个模块冻结接口签名、可见语义对拍和一个故障题。学习者的私有 submission.json 必须逐模块列出独立 implementation_path/interface_signature、可复现的 test_evidence、包含"失败前 → 修复后"的 failure_records,以及含 prompt、主题、回答摘要、局限和审核备注的 oral_records。实现和测试不得导入 clean_room、llm_core、python.llm_core、llm_train 或 python.llm_train;校验器也会拒绝实现/evidence 符号链接,避免借链接绕过 clean-room 边界。

bash
pnpm clean-room:contract
node scripts/validate_clean_room.mjs --submission /path/to/private-submission
PYTHONPATH=python python scripts/run_clean_room.py \
  --submission /path/to/private-submission \
  --output /path/to/private-submission/runtime-result.json
# 在仓库外临时副本上,对 8 个 L3 模块做显式故障前后 smoke(不修改源文件):
python3 scripts/run_clean_room_faults.py \
  --submission /tmp/learn-llm-clean-room-practice \
  --output /tmp/learn-llm-clean-room-practice/faults-result.json

run_clean_room_faults.py 默认只寻找仓库外固定临时目录 /tmp/learn-llm-clean-room-practice,也可用 --submission 明确指定学习者 submission;它只在临时副本中为 autograd、language-model、BPE、attention、transformer-block、TinyGPT training、RoPE/KV-cache、advanced weight quantization 各注入一个确定性故障,然后要求"注入前失败、原版修复后通过"。输出仅保留模块、故障类型、状态、异常类型和 SHA-256,不回显代码、路径或隐私;它不是安全沙箱,human_review_required=true 且 mastery_claim=false,退出成功也只表示这 8 个 bounded worker 故障证据满足,不表示学习者掌握或毕业。

结构校验器只检查提交结构、接口签名、参考实现导入黑名单和已保存测试证据;行为 runner 才会在学习者明确选择后,逐模块执行固定 shape/共享梯度/激活和 MLP 更新/采样/UTF-8 特殊 token/因果性/更新/checkpoint 恢复/完整 token-to-loss/generation 主链/RoPE-KV full-cache 等价 smoke。transformer-block 的 rebuild_model_chain 必须证明 loss 下降、参数更新、checkpoint 落盘和生成结果。runner 具有子进程超时和静态网络导入门,输出只保留指标、输出哈希和脱敏 provenance 哈希(runner/合同/manifest/每个实现文件),不写入原始路径或代码,也不写入 learner_graduation_approved。任何缺字段、缺 artifact、测试失败、故障未修复、行为 smoke 失败或口述未审核的提交都明确停在 gate;即使结构与行为均成功,结果仍是 human-review-required,不能替代 clean-room provenance、故障定位、口述或最终人类判定。

阶段四:动手实验 ​

把全链路五个阶段串成一条可审计的 artifact chain:训练产出 checkpoint;检索拉取证据;Agent 完成任务;评估冻结打分;报告聚合指标、成本与失败记录,并支持从 config_hash 一路回溯到最终结果。

环境准备 ​

bash
cd <仓库根>
export PYTHONPATH="$PWD/python"

命令与预期输出 ​

bash
python -m agent_core.capstone \
  --output .artifacts/capstone-report.json \
  --checkpoint-root .artifacts/capstone-checkpoints
# 或
pnpm capstone:local

python -m pytest python/tests/test_capstone.py \
  python/tests/test_framework_comparison.py \
  python/tests/test_clean_room_contract.py -q
text
........................                                                 [100%]
24 passed in 18.62s

判定信号:
  指标稳定可复现、多 seed 波动在可接受范围
  报告含成本估算、失败记录与可归因链路
  artifact chain 可由 config_hash 追溯到 checkpoint、eval 与 report

概念图 ​

图:Capstone 五层 artifact chain — 从 clean-room 抽测(7 个 blank interface 手写 + 故障注入 + 闭卷解释审核)到训练产出(checkpoint + config_hash),经 RAG 检索 → Agent 执行 → 冻结 eval 的系统链路,到审计报告(可回溯的 artifact chain),最终通过产品 gate + 人类 gate 双门控判定毕业。每个环节的产物 hash 绑定到 config_hash,任何一个断裂,整条链失效。

故障注入与预期信号 ​

注入预期失败信号修复后证据
让教学 TinyGPT 直接承担工具规划工具参数/状态指标混入教学模型结论教学链与 Agent harness 分离
删除 checkpoint 后重跑副作用事件重复或终态不一致从最近合法 checkpoint 恢复
让工具输出覆盖 policy未批准动作或越权 evidence 出现policy 是不可绕过的系统边界
用页面 marker 代替旅程构建绿但交互/刷新/键盘失败headed Chrome 步骤、console/network 证据
只记录成功样本评估存在幸存者偏差、失败案例被掩盖报告必须同时聚合成功与失败两种轨迹并按维度切片
checkpoint 与 eval 用不同 config_hash结果无法归因到具体配置、复现成本极高同一 run 内 config_hash 必须贯穿训练、检索、eval、报告四阶段
只跑一个 seed波动被当作提升、指标虚高至少三个 seed 取中位数并报告方差,差异过大需复跑
把课程产品状态当学习者毕业状态自动化通过率高估人类能力、误判达成必须分离两个独立信号并分别记录

本章验收 ​

不看资料,用 5–10 分钟回答:

  • 从用户输入走到终态,闭卷解释 TinyGPT 教学链、planner/executor、RAG、typed tools、policy/HITL、checkpoint/trace 与 Judge 的责任边界;指出 TinyGPT 为什么不能计入 Agent 任务成功率。
  • 任选一个 mask、tokenizer、cache、训练或 Agent recovery 故障,先描述可观察失败,再说明修复证据和仍未能推出的结论;最后解释为什么产品 gate 不能替代人类毕业判定。
  • 从练习文件 python/labs/w0p_exercises.py 出发,任选 5 个函数分别说明它们在完整 LLM 主链中的位置(Tokenize → Embed → Attend → Train → Align → Agent)。该文件头写明共 37 道练习,第2章引入这批练习,第3章讲解其中的数学函数。不需要写出完整公式,但必须说明"输入是什么、输出是什么、下一步去哪里"。
  • 用第3章的 cross_entropy(p_dist, q_dist) 解释"训练 loss 下降 ≠ 生成质量提升":CE 只衡量模型分布和训练标签的差距,不等于人类偏好、事实性或安全性。
  • 用 coding agent 的工程画像回答:工具面为什么收敛到 shell / 文件编辑 / 搜索三类原语?为什么说「失败的测试就是 verifier」——它与第11章 RLVR 的判卷器思想哪里同源、用途有何不同?

论文与延伸 ​

实验与参考 ​

前端/Agent 迁移 ​

Capstone 把前端工程师熟悉的状态机、协议、重试、可观测性和 UI journey 与模型概率输出连接起来:模型负责提出候选,系统负责验证、批准、恢复和审计。

  • Capstone ≈ E2E test suite:从用户输入到终态的完整旅程被录制和重放;capstone report 就是测试报告,含通过/失败/错误的分项统计。
  • Clean-room ≈ 算法面试:从空白接口手写 TinyGPT 组件,就像从零实现 reduce 或 Promise——不能用库函数,必须展示对底层机制的理解。
  • 产品 gate ≠ 毕业判定:course_product_w12_passed 是产品层面的"所有测试通过",learner_graduation_approved 是人类层面的"学习者真正掌握"——CI 全绿不等于代码没有 bug,人类 review 永远不可替代。

资源 / 成本 / 隐私 ​

本地 preview、合成 eval fixture 和本地 Python 测试即可完成产品演练,预计 gross cost 为 0;生产站点、云训练、DNS 和公网发布均是独立授权门。只提交脱敏 evidence,真实答辩记录保存在本地。

Evidence ​

仓库当前机器证据(只读快照) ​

evidence/module-manifest-v1.json 中 19.evidence 指向 evidence/browser-journey-local-v1.json,19.additional_evidence 指向 evidence/19-capstone-local-v1.json。前者是当前工作树的 headed-Chrome 本地旅程快照,后者是本地 Capstone harness 结果;二者都只覆盖各自 JSON 的范围,不是学习者提交,也不能推出课程产品或学习者已经通过。

浏览器证据合同由 pnpm browser:evidence 校验:每一步必须有 expected、actual、状态、当前 checkout 标识和脱敏的 console/network 范围。它还必须关联 pnpm docs:build 生成的 docs/.vitepress/dist/dist-build-manifest.json 及其 SHA-256,防止浏览器记录与另一份构建产物错配。当前证据明确 base_url 是本地 preview,并关联一个不含敏感请求内容的页面源网络元数据文件;它仍只是 Phase D 本地观察,不关闭生产 HTTPS 或发布门禁。

19.additional_evidence 也包含 evidence/clean-room-runtime-runner-v1.json,它只记录合成测试提交上的 runner 合同测试;没有学习者提交、真实答辩或掌握结论。

本地还保留一份 evidence/clean-room-agent-practice-local-v1.json 的 Agent 独立练习快照:7 个模块通过有界行为 smoke,索引只保存哈希和指标;它明确标记为 human-review-required,不是用户学习者提交,也不证明 clean-room provenance、故障定位、口述或毕业。

历史快照 evidence/clean-room-faults-local-v1.json 只覆盖 autograd/BPE;扩展高级量化前的历史快照 evidence/clean-room-faults-local-v2.json 对当时 7 个 L3 模块观察到 before=failed → after=passed。第 8 个模块的参考实现故障门禁见 evidence/10-advanced-quantization-v1.json;完整 8 模块学习者 fault smoke 尚未运行。以上证据都明确不代表用户提交或学习者掌握,也不是安全沙箱。

clean-room 合同的脱敏索引见 evidence/clean-room-submission-index-v1.json。该索引明确当前没有仓库内学习者提交,状态保持 gate;行为 runner 的存在不等于已经有学习者实现,也不能替代私有实现、失败→修复 trace、口述记录或人类答辩。

学习者提交模板(待填写,不是当前机器证据) ​

复制下面模板并填写自己的真实运行结果。所有 <...> 都是未填写状态;actual 和 artifacts 尤其不能被当作已运行或已通过。artifacts 必须替换为本次提交中真实存在的仓库相对路径。

yaml
schema: learn-llm.evidence.v1
module: 22-capstone
commit: <learner-commit-sha>
verified_at: <iso-date>
environment: <sanitized-os-python-device>
seed: 12
commands:
  - PYTHONPATH=python python -m pytest <learner-focused-capstone-tests> -q
  - PYTHONPATH=python python -m agent_core.eval --spec eval/eval-spec-v1.yaml --replay eval/fixtures
metrics:
  - name: task_success
    expected: '>=0.85'
    actual: <recorded-value>
  - name: schema_validity
    expected: 1.0
    actual: <recorded-value>
  - name: acl_hitl_bypasses
    expected: 0
    actual: <recorded-value>
  - name: recovery_rate
    expected: '>=0.95'
    actual: <recorded-value>
artifacts:
  - <learner-repo-relative-artifact-path>
cost:
  gross_usd: 0
  credit_usd: 0
licenses:
  - source: <source>
    version: <version>
    license: <license>
    attribution: <attribution>
    redistribution: <redistribution>
known_failures:
  - <sanitized-failure-or-none>

没有固定 eval hash、失败/攻击 fixture、clean-room 记录、真实旅程和人类答辩记录时,本章保持 gate,不得写入课程产品或学习者毕业状态。

下一步 ​

恭喜完成 Capstone 工业级工程交付与答辩!接下来,你可以进入进阶前沿专题:

私有学习站 · 原理从零构建 · 勿提交个人隐私或密钥