课程大纲：Python 读码实战课

核对日期 2026-10-06。适用 Python 3.12–3.14（本项目固定 3.12，网站浏览器内运行时为 Pyodide 314.0.7 / Python 3.14）。

1. 定位

项	说明
学习者	有工程经验的开发者（熟悉 JS/TS、React、Java 类工具链），Python 零基础或碎片化
终点	能独立、逐行读懂 minimal_agent.py 这类真实脚本：说清每行做什么、数据怎么流动、出错时定位到哪一行
范围	读懂代码所需的语言核心 + 高频标准库 + 读第三方 SDK 的方法；不含 Web 框架、数据分析、并发、打包发布
原则	专业、简洁、单一职责：每课只解决一个主题；每个概念配可运行示例；每课有自动判题练习
内容源	docs/课程/ 下的 Markdown 是唯一事实来源；网站（site/）直接渲染这些文件

2. 与官方教程及常见教学站的差异

官方 Python 教程 权威、完整，但按“语言特性”组织，面向通用读者。本课程以它为事实基准，在以下方面补强：

维度	官方教程	本课程
目标	全面介绍语言	以“读懂一份真实脚本”为终点倒推内容，每课标注它在 minimal_agent.py 中的用处
动手	示例需自行复制到解释器	示例在浏览器内直接运行、可编辑、可重置（Pyodide）
练习	无	每课 1–4 道练习，隐藏断言自动判题，可看参考答案与检查代码
读代码	少量片段	每课“读代码”一节：真实风格代码片段 + minimal_agent.py 对应行
易错点	分散在正文	每课集中列出，附报错示例（可运行演示）
对开发者	不假设其他语言背景	每课给出 JS / Java 简短对照，复用已有心智模型
进度	无	本地进度跟踪：标记完成、练习通过记录、总体进度
正确性	—	全部示例与参考答案由 tests/check_course.py 用真实 CPython 执行验证；网站运行时与校验器共用同一执行脚本

3. 课程结构

与 学习路线 的 11 个阶段一一对应；阶段 10 在原“读代码技巧”基础上补入迭代器/生成器/装饰器（读码层面）与“读第三方 SDK”。

阶段	课程	学习目标（达成后能……）	在 minimal_agent.py 中的用处
1 环境与工具	1.1 运行 Python 代码 · 1.2 uv 项目与依赖	区分系统解释器与项目环境；用 uv run 运行脚本；读懂 pyproject.toml / uv.lock	运行方式 uv run examples/agent/minimal_agent.py；依赖 anthropic、python-dotenv
2 基础语法与数据类型	2.1 语法骨架与变量 · 2.2 数字、布尔与 None · 2.3 字符串 · 2.4 f-string 与格式化	读懂缩进、名字绑定、真值、or 取默认值、字符串方法与 f-string	文档字符串、os.getenv(...) or "deepseek"、"".join(...)、f"[第 {turn} 轮]..."
3 控制流与函数	3.1 条件与循环 · 3.2 函数定义与调用 · 3.3 参数进阶与解包 · 3.4 作用域、闭包与 lambda	读懂 for…else、range、关键字参数、*args/**kwargs、** 解包、函数是对象	主循环 for turn in range(...)…else、TOOL_FUNCTIONS[block.name](**block.input)
4 容器	4.1 列表、元组与切片 · 4.2 字典 · 4.3 集合 · 4.4 推导式与解包	读懂嵌套 list/dict 结构及访问路径、推导式	PROVIDERS、tools、messages 的结构；[b.text for b in resp.content if ...]
5 模块与包	5.1 模块与 import · 5.2 包与项目结构	判断名字来自内置/标准库/第三方；读懂各种 import 与 __name__	import os、import anthropic、from dotenv import load_dotenv
6 异常	6.1 读懂 Traceback · 6.2 try/except/raise · 6.3 with 与上下文管理器	从 Traceback 定位出错行；读懂错误处理与资源管理代码	PROVIDERS[provider] 的 KeyError；SDK 抛出的 API 错误
7 类与对象	7.1 类与实例 · 7.2 继承与特殊方法 · 7.3 dataclass 与枚举	读懂 class、self、属性链、__repr__ 等特殊方法、数据类	anthropic.Anthropic(...) 创建对象、client.messages.create、block.type
8 常用标准库	8.1 pathlib 与文件 · 8.2 json · 8.3 os、sys 与环境变量 · 8.4 datetime · 8.5 collections 与 itertools · 8.6 logging	认识高频标准库的典型用法与坑	os.getenv、load_dotenv() 背后的环境变量机制；工具参数即 JSON
9 类型注解	9.1 类型注解基础 · 9.2 typing 进阶	读懂注解、X | None、泛型、TypedDict、Literal、Protocol	读 SDK 签名（大量类型注解）的前提
10 读代码技巧	10.1 迭代器与生成器 · 10.2 装饰器 · 10.3 读陌生代码的方法 · 10.4 读第三方 SDK 代码	识别进阶语法；掌握“入口→数据→名字来源→实验验证”的读码流程；能顺着 SDK 源码找到方法定义	读懂 client.messages.create 的参数与返回对象
11 简单项目	11.1 minimal_agent.py 逐行精读 · 11.2 改造与自测	逐行讲清 Agent 循环；在浏览器内用模拟客户端运行完整循环并改造	终点
附录	速查表 · 术语表	随查随用	—

共 11 个阶段、36 课。每个阶段目录下的 index.md 是阶段导读（目标、课程列表、与终点项目的关系）。

前置关系

1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11
            └── 3.4 闭包 是 10.2 装饰器 的前置
                4.4 推导式 是 10.1 生成器表达式 的前置
                7.x 类 是 10.4 读 SDK 的前置

4. 单课结构（固定模板）

章节	内容
目标	2–4 条可检验的学习目标；前置课程；对应官方章节
核心概念	精确定义 + 可运行示例（python run），必要时附预期报错示例
易错点	高频错误与反直觉行为，尽量附可运行演示
对照	与 JS / Java 的简短差异表
读代码	真实风格代码片段；与 minimal_agent.py 的对应行
练习	1–4 道，含起始代码、参考答案、自动检查断言
小结	3–5 条要点
延伸阅读	仅官方来源：docs.python.org、peps.python.org、docs.astral.sh/uv、packaging.python.org

5. 交互与判题机制

• 可运行示例：Markdown 中 ```python run 代码块在网站上渲染为可编辑、可运行组件；raises=异常名 表示演示预期报错。
• 练习：```python exercise id=... 代码块包含 starter（起始代码）、solution（参考答案）、check（隐藏断言）三段。网站先执行学习者代码，再在同一命名空间执行检查断言，全部通过即判定通过并记录进度。
• 运行时：浏览器端为 Pyodide（WebAssembly 版 CPython，在 Web Worker 中执行，10 秒超时自动终止）；本地校验器为真实 CPython。两者共用 site/public/py-runtime.py。
• 进度：保存在浏览器 localStorage（课程完成标记、练习通过记录、未提交的练习草稿），不上传任何数据。

6. 质量保证

检查	工具	规则
示例可运行	tests/check_course.py	每个 python run 块在真实 CPython 中运行，正常结束或抛出声明的异常
练习有效	同上	参考答案必须通过检查；起始代码必须不能通过检查（证明断言有效）
静态代码	同上	普通 python 块必须能通过语法编译
源码副本	同上	课程中嵌入的 minimal_agent.py 必须与仓库文件逐字一致
结构与链接	同上	每课包含全部固定章节；站内链接可解析；外链仅限官方域名；提及版本处须有核对日期
浏览器兼容	site/scripts/verify-pyodide.mjs	在 Node 中用同版本 Pyodide 执行全部示例与练习
网站	npm run build + 冒烟测试	构建成功；页面可访问；代码块可在浏览器中运行

7. 版本与来源政策

• 正文内容对 Python 3.12、3.13、3.14 均成立；仅在某版本新增或变更时标注“3.x 起”。
• 版本相关陈述均标注核对日期 2026-10-06；以 What's New 与对应 PEP 为准。
• 只引用官方来源；非官方资料不作为依据。