# 教学覆盖层 · 对照卡(机制①)

把"智能体理论 ↔ 平台代码"做成可浏览的三栏对照课件。每张**对照卡**是一个 YAML,
渲染成一页:**教科书概念 │ 平台源码落点 │ 形式化对象**,并可挂一个真实 run 的 trace。

不改平台内核,纯寄生在现有源码与 run workspace 之上。

## 用法

```bash
python3 teaching/gen.py            # 生成静态站点 → teaching/site/
python3 teaching/gen.py --check    # 只校验锚点是否有效(锚点失效则 exit 1,可进 CI)
open teaching/site/index.html      # 浏览
```

**关键性质:源码 span 在生成时实时从仓库读取**(不是抄一份),所以代码一改、行号
一漂,`--check` 立刻报警 —— 对照卡永不与代码脱节。建议把 `gen.py --check` 接进 CI。

## 写一张新对照卡

在 `teaching/cards/` 下加一个 `NN-<slug>.yml`:

```yaml
id: <唯一 slug,同时是页面文件名>
module: A            # A/B/C/D,见 gen.py 的 MODULE_NAMES
week: 2              # 第几周
title: "..."

concept:             # 📖 教科书概念栏
  textbook: |        # 概念正文(可多行)
    ...
  key_point: "..."   # 一句话要点(黄条高亮)

code:                # 💻 源码栏:可多个锚点,生成时实时读取该 span
  - file: lambdagent/src/lambdagent/fromconfig/compiler.py   # 仓库相对路径
    symbol: _compile_react      # 仅作标注,显示用
    lines: "878-933"            # 实际渲染的行范围,格式 a-b
    note: "..."                 # 这段代码在讲什么

formal:              # ∑ 形式化栏
  term: "Loop(ConversationLam ∘ action_parser, cond, max_steps)"
  effect: "IO[tool] ⊕ Partial"
  note: "..."

live_demo:           # 🎞 可选:挂一个真实 run,自动算步数/token/抽工具调用
  run: agentexample/research67/workspace/run_20260520_004928   # 仓库相对 run 目录
  highlight: "..."   # 这个 run 想让学生看到什么;run 留空则只显示这段文字

related: [tool-native-fc, tool-claude-code-native]   # 可选:相关卡 id,生成超链接

takeaway: |          # 学习目标
  ...
```

跑 `python3 teaching/gen.py` 即可。`live_demo.run` 指向不存在的 trace 时页面会显式标注,
不会静默成功。

## 现有卡片(骨架样例)

| 周 | 卡 | 对照点 |
|---|---|---|
| 2 | `tool-react-over-text` | ReAct ↔ `_compile_react`/`ConversationLam` ↔ `action_parser` 部分性 |
| 2 | `tool-native-fc` | function calling ↔ `_run_fc_loop` ↔ 消除 Partial |
| 2 | `tool-claude-code-native` | 外包给运行时 ↔ `run_native` ↔ 能力授权 Cap |
| 8 | `sandbox-effect-cap` | 沙箱 ↔ `check_write_allowed`/`_resolve` ↔ effect 限制 ↾ Cap |

第 2 周三张卡构成旗舰对比(三种工具调用范式);第 8 周这张展示同一套形式化语言
(effect / Cap)如何复用到安全维度。后续按 14 周大纲继续加卡即可。

## 下一步(对接其他机制)

- `live_demo` 目前挂的是仓库里已有的 react-over-text run。范式②③的对照 run
  待「双车道对比台」(机制③,包 `evals/bench_providers.py`)统一录制后回填。
- Trace 解说器(机制②)可在此基础上把 trace 每步标注成概念,作为卡片的深入页。