lambdagent/teaching

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

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

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

用法

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:

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 每步标注成概念,作为卡片的深入页。