第19章 · Capstone、clean-room 抽测与答辩

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

先修：第3–18章的模块、测试、失败题和 evidence。

本章目标

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

公式与 shape

Capstone 的可观测链路：

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 bypass	0
定义故障的 recovery rate	≥ 95%

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

数学桥接：第2章 → 第19章（全链回顾）

本章是 Capstone：把第3–18章的所有环节串成一条可审计的 artifact chain。回顾第2章的每个函数在完整链路中的位置：

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

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

$$\text{Tokenize}\stackrel{\text{第5章}}{\to }\text{Embed}\stackrel{\text{第7章}}{\to }\text{Attend}\stackrel{\text{第8章}}{\to }\text{Train (CE)}\stackrel{\text{第10/18章}}{\to }\text{Align/Eval}\stackrel{\text{第11/13章}}{\to }\text{Agent}$$

每个箭头都至少调用一个第2章函数：Embed 之后做 dot_product（attention），Attend 之后算 cross_entropy（训练），Train 用 gradient_descent_step（更新），Align 用 kl_divergence（DPO），Agent 用 categorical_sample（决策）。

前端类比：全链路 = 前端 build pipeline：Tokenize = webpack loader（raw bytes → modules），Embed = CSS-in-JS（token → vector），Attend = 组件树依赖收集（Q 找相关 K），Train = HMR 热更新（loss 驱动参数更新），Align = A/B 测试（偏好优化），Agent = 用户交互循环（observe → reason → act → observe）。每个环节的输出是下一个环节的输入，任何一个断裂，整条链失效。

从零实践

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. 运行当前已有的组合回归：

   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。

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 边界。

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
# 在仓库外临时副本上，对 7 个 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 各注入一个确定性故障， 然后要求“注入前失败、原版修复后通过”。输出仅保留模块、故障类型、状态、 异常类型和 SHA-256，不回显代码、路径或隐私；它不是安全沙箱， human_review_required=true 且 mastery_claim=false，退出成功也只表示 这 7 个 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、故障定位、口述或最终人类判定。

故障注入与预期信号

注入	预期失败信号	修复后证据
让教学 TinyGPT 直接承担工具规划	工具参数/状态指标混入教学模型结论	教学链与 Agent harness 分离
删除 checkpoint 后重跑副作用	事件重复或终态不一致	从最近合法 checkpoint 恢复
让工具输出覆盖 policy	未批准动作或越权 evidence 出现	policy 是不可绕过的系统边界
用页面 marker 代替旅程	构建绿但交互/刷新/键盘失败	headed Chrome 步骤、console/network 证据

论文与延伸

• 复习 ReAct: Synergizing Reasoning and Acting in Language Models 的“行动与观测交错”思想，但把批准、状态和副作用交给系统。
• 复习 Holistic Evaluation of Language Models 的可比较评估观；Capstone 指标还需固定自己的分母与阈值。
• 口述题不接受只背论文摘要：必须说明问题、公式/接口、证据、局限和工程取舍。

前端/Agent 迁移

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

• Capstone ≈ E2E test suite / Cypress：从用户输入到终态的完整旅程需要被录制和重放——就像 Cypress 录制用户操作后重跑验证；capstone report 就是测试报告，含通过/失败/错误的分项统计。
• Artifact chain ≈ Git commit history：config_hash → checkpoint → eval → report 的完整追溯链，就像 git log --follow 从一个 commit 回溯到所有父 commit——任何一个环节缺失，链断裂。
• Clean-room ≈ Algorithm interview：从空白接口手写 TinyGPT 组件，就像算法面试中从零实现 reduce 或 promise——不能用库函数，必须展示对底层机制的理解。
• 产品 gate ≠ 毕业判定：course_product_w12_passed 是产品层面的"所有测试通过"，learner_graduation_approved 是人类层面的"学习者真正掌握"——就像 GitHub Actions 全绿不等于代码没有 bug，人类 review 永远不可替代。

口述与自测（不看资料，5–10 分钟）

• 从用户输入走到终态，口述 TinyGPT 教学链、planner/executor、RAG、typed tools、policy/HITL、checkpoint/trace 与 Judge 的责任边界；指出 TinyGPT 为什么不能计入 Agent 任务成功率。
• 任选一个 mask、tokenizer、cache、训练或 Agent recovery 故障，先描述可观察失败，再说明修复证据和仍未能推出的结论；最后解释为什么产品 gate 不能替代人类毕业判定。
• 从第2章的 12 个函数出发，任选 5 个分别说明它们在完整 LLM 主链中的位置（Tokenize → Embed → Attend → Train → Align → Agent）；不需要写出完整公式，但必须说明"输入是什么、输出是什么、下一步去哪里"。
• 用第2章的 cross_entropy(p_dist, q_dist) 解释"训练 loss 下降 ≠ 生成质量提升"：CE 只衡量模型分布和训练标签的差距，不等于人类偏好、事实性或安全性。

实验与参考

• 关联概念：术语表 - harness / manifest / artifact chain
• 论文依据：必读论文 - LLM judge 与评测驱动开发
• 毕业要求：毕业口试清单

动手实验

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

环境准备

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

命令与预期输出

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

.........................                                          [ 100% ]
3 passed in 12.31s

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

概念图

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

故障注入清单

故障	表现	修复
只记录成功样本	评估存在幸存者偏差、失败案例被掩盖	报告必须同时聚合成功与失败两种轨迹并按维度切片
checkpoint 与 eval 用不同 config_hash	结果无法归因到具体配置、复现成本极高	同一 run 内 config_hash 必须贯穿训练、检索、eval、报告四阶段
只跑一个 seed	波动被当作提升、指标虚高	至少三个 seed 取中位数并报告方差，差异过大需复跑
把课程产品状态当学习者毕业状态	自动化通过率高估人类能力、误判达成	必须分离两个独立信号并分别记录

资源 / 成本 / 隐私

本地 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。两份证据都明确标记为 human_review_required=true、mastery_claim=false，是 Agent 自己的有界实践，不是用户提交，也不是安全沙箱。

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

学习者提交模板（待填写，不是当前机器证据）

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

schema: learn-llm.evidence.v1
module: 19-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，不得写入课程产品或学习者毕业状态。