核心知识：沿一次教材任务读代码

学习目标是能解释数据流、修改一条约束、观察结果并定位故障。先建立整体图景，再沿生成、检索、评审和交付逐层深入；不要先背全部框架接口。

顺序	章节	源码入口	验收重点
1	模型与上下文	providers.py::run_model	解释一次节点为何可能多次调用模型
2	结构化输出	schemas.py	区分格式、契约和业务错误
3	工具调用	tools.py::ToolSession	演示服务端拒绝越权请求
4	Agent 与流程	graph.py::context	说明模型与程序各决定什么
5	LangGraph	graph.py::build_graph	解释分支、暂停与恢复
6	Embeddings 与切分	retrieval.py::embeddings	验证维度、片段边界与模式区别
7	pgvector	retrieval.py::retrieve	验证范围过滤和来源返回
8	RAG	retrieval.py::import_document	追踪资料更新与证据快照
9	评审与修订	content.py::apply_patch	证明未授权块不被修改
10	本地化与一致性	content.py::business_review	识别结构化规则的能力边界
11	素材制作	media.py	核对依赖、文件与内容版本
12	可靠执行	worker.py	区分重试、结果不明与旧任务
13	观测与评估	db.py::event	把错误关联到版本和实验条件
14	权限与注入	tools.py、api.py	解释提示词与程序权限的边界

前十二章为核心必学；观测和安全同样是资深岗位必答内容，可在第二遍结合故障实验学习。每章按问题、原理、流程、混淆、示例、实现、源码、取舍、实验、排障、面试和官方资料组织。完整设计见系统架构，概念辨析见对比目录。

实验约定

文档网站可独立阅读。运行实验才需要下载交付包并启动 Docker 系统；不要在 Cloudflare Pages 构建环境运行教材服务。

1. 按交付包说明准备 system/.env，从项目根目录进入 system 后启动 Compose。
2. 本组命令默认 MODE=demo，API 地址为 http://127.0.0.1:8000。真实模式需要独立配置服务凭据，并使用 scenario=normal。
3. 如果配置了 API_KEY，在当前终端将同值放入 LAB_API_KEY；命令通过请求头发送它，不能写进 VitePress 文档或公开提交。
4. 文中的 $JOB_ID 和 $VERSION 必须取自实际任务详情，不要照填示例编号。任务状态由后台进程推进，创建请求返回不等于已经完成。
5. Python 代码块使用项目已安装依赖。可在 docker compose exec -T api python - 中粘贴运行；命令示例已明确需要数据库的前提。

cd system
docker compose up --build -d
docker compose exec api python -m app.cli schemas

实验写明预期行为，不表示本次交付已经执行过该命令。实际通过、失败或未验证项以最终验收报告为准。核心页的 STAR 应用采用假设实验场景；R 列是需要收集的证据，不能改写成历史工作成果。

读代码的方法

先在请求模型上找到字段，再追踪调用者、数据库写入点与对应事件。每次只改一个因素，例如修订上限、地区或某块文本，并比较前后版本。遇到失败先确定层次：HTTP、Schema、检索、业务规则、图状态、任务队列或外部媒体服务。

完成一轮后，用五分钟讲清：模型看到什么、程序禁止什么、状态存在哪里、任务中断后怎样恢复、交付前验证什么。讲不清的节点就是下一轮实验入口。