章节产出规范（所有子 Agent 必读）

本文件是 Python 教程「14 章 × 4 件套」的产出契约。第 1 章已完成，作为风格标杆。后续 13 章（第 2-14 章）由多个子 Agent 并行产出，必须严格按本规范保持风格统一。

0. 共同任务背景

我们在为零基础到大厂面试者编写一套 Python 学习教程，存放在 /data/workspace/learnNote/backend/language/python/。

每章必须产出 4 件套：

学习文档 XX_主题.md（400-700 行）
演示页面 XX_主题/demo.html（单文件，无依赖，3-5 个交互演示，500-900 行）
SVG 图表 XX_主题/img/*.svg（至少 2 张）
实战代码 XX_主题/code/*.py（至少 1 个可运行）

1. 必读参考（动手前先读完）

1) /data/workspace/learnNote/backend/language/python/task.md        ← 教程产出规范
2) /data/workspace/learnNote/backend/language/python/01_intro.md    ← 第1章作为风格标杆
3) /data/workspace/learnNote/backend/language/python/01_intro/demo.html  ← demo.html 风格参考
4) /data/workspace/learnNote/backend/language/python/0_learn_plan.md     ← 大纲中你那一章的位置和知识点边界

2. 关键陷阱（必须规避）

2.1 ⚠️ SVG 必须用 Python 脚本写入

经实测，Write 工具直接写 SVG 文件会损坏中文字符（变成乱码）。SVG 必须这样产出：

python

# 1) 写一个临时脚本，例如 /tmp/gen_ch04_svg.py
from pathlib import Path

OUT_DIR = Path("/data/workspace/learnNote/backend/language/python/04_oop/img")
OUT_DIR.mkdir(parents=True, exist_ok=True)

SVG1 = """<svg xmlns="http://www.w3.org/2000/svg" ...>
  ...（完整 SVG 内容）...
</svg>
"""

(OUT_DIR / "class-instance.svg").write_text(SVG1, encoding="utf-8")

bash

# 2) 运行
python3 /tmp/gen_ch04_svg.py

# 3) 校验 XML 合法性
python3 -c "import xml.etree.ElementTree as ET; ET.parse('/data/workspace/learnNote/backend/language/python/04_oop/img/class-instance.svg'); print('XML OK')"

# 4) 校验 UTF-8
iconv -f UTF-8 -t UTF-8 /data/workspace/learnNote/backend/language/python/04_oop/img/class-instance.svg > /dev/null && echo "UTF-8 OK"

2.2 ⚠️ Markdown 大文件分段写入

如果一次 Write 写入超过 ~10K 字符可能失败。建议：

先 Write 写入文档前半部分（含 1-3 节）
再用 StrReplace 在末尾追加后半部分
或者分多次 cat >> 追加

2.3 ⚠️ Demo.html 里写 Python 代码不要用三引号

避免在 JS 字符串里嵌套 Python 三引号字符串，会破坏脚本结构。如果必须，用 \``` 反引号或 escape。

3. .md 文档结构（5 段式 + 面试题）

参考 01_intro.md 的章节排版。每章必须包含：

markdown

# 第 N 章 章节标题

> **学习目标**：（1-2 句话，描述完成本章后能做什么）

---

## N.1 概念引入 / 生活类比

### N.1.1 一个生活类比：xxxx
（用快递柜、奶茶店、图书馆等生活场景类比晦涩概念）
（必须配 ASCII 图）

### N.1.2 技术定义
（这里才是真正的技术解释）

---

## N.2 核心知识点 1
（含 SVG 图、代码示例、REPL 实操记录）

## N.3 核心知识点 2
...

## N.X 底层原理
（必须深挖一层：字节码、内存布局、CPython 源码思想）

---

## N.末-1 本章小结

### 知识点速记
（5-8 条 ✓ 列表）

### 下一步
- ✅ 跑一遍 [code/xxx.py](./XX_主题/code/xxx.py)
- ✅ 打开 [demo.html](./XX_主题/demo.html) 体验交互
- ➡️ 进入 [第 N+1 章: ...](./XX_next.md)

---

## N.末 面试高频题

### Q1. 题目？⭐⭐⭐
**考察点**：xxx
**标准答案**：（分点作答，至少 3 点）
**加分项**：（2-3 条）
**易错点**：（1-2 条）

（共 6 道题，难度 ⭐~⭐⭐⭐⭐ 分布合理）

---

## 📚 延伸阅读

- 官方文档链接
- 经典书籍 1-2 本

字数要求：400-700 行，避免太短没料、太长冗余。

4. SVG 风格规范（svg-draw 标准）

完整规范见 /root/.cursor/skills/svg-draw/SKILL.md。核心要点：

画布尺寸：900-1100 宽，根据内容动态调整高度
主色：#1890FF（蓝），强调用 #E6F7FF 浅蓝填充
中性色：背景 #FAFAFA，边框 #D9D9D9 / #8C8C8C，文字 #262626 / #595959
字体：PingFang SC, Microsoft YaHei, Arial, sans-serif
节点圆角：rx="4" ry="4"
整体外框：虚线 stroke-dasharray="4,4"，距画布 15px
标题：22px font-weight=bold fill=#1890FF，text-anchor=middle
箭头：必须用 <marker> 定义，stroke-width="0.5"~"0.8"
箭头贴边：终点精确贴到目标节点边框（不悬空、不穿模）
节点不重叠：节点间距 ≥ 10px
XML 转义：& → &，< → <，避免标签内出现裸 <>

5. demo.html 风格规范

参考 01_intro/demo.html 的整体风格：

单文件，零依赖（不引 CDN）
暗色主题：bg=#0f1419, card=#1a2027, accent=#1890FF or 章节主色
Tab 切换式布局：顶部 Tab 切换 3-5 个演示面板
每个演示面板包含：
- 概念解释（短）
- 控制按钮（"下一步"/"重置"/"开始"）
- 可视化区域（动画、卡片、栈图等）
- "💡 关键洞察" 提示框（hint 类）
行数：500-900 行
使用原生 JS，不要 jQuery / React 等框架

6. 实战代码规范

code/*.py 必须：

单文件可运行：python3 xxx.py 直接出结果
仅依赖标准库（除非章节本身就是讲第三方库，如第 13 章）
包含 if __name__ == "__main__": 入口
多个演示函数，每个函数演示一个知识点
打印格式美观：用 print("=" * 60) 分隔块
必须能跑通：完成后用 python3 xxx.py 实测

7. 各章节具体大纲

第 2 章基础语法与数据类型 (`02_basic_types.md`)

核心知识点：

数字类型（int 任意精度、float IEEE-754、bool 是 int 子类、Decimal）
字符串：不可变、str vs bytes、f-string、切片三参数
列表 list：动态数组、append/pop O(1)、切片陷阱、* 复制陷阱
元组 tuple：不可变 + 可哈希、namedtuple
字典 dict：哈希表、3.7+ 插入有序、底层紧凑布局
集合 set / frozenset：去重、哈希、交并差
可变 vs 不可变；浅拷贝 vs 深拷贝；is vs == 与小整数缓存

SVG 推荐（至少 2 张）：

data-types-overview.svg：6 大数据类型分类图（可变 / 不可变 / 序列 / 映射 / 集合）
dict-hash-table.svg：dict 底层哈希表 + 紧凑数组结构（3.7+ 设计）
list-vs-tuple.svg：list 与 tuple 内存布局对比（动态数组 vs 固定数组）
copy-deep-vs-shallow.svg：浅拷贝 vs 深拷贝的对象引用图

demo.html 推荐演示：

演示 1：6 种数据类型实操（输入值，显示 type/id/可变/可哈希）
演示 2：is vs == 互动（小整数缓存陷阱、字符串驻留）
演示 3：dict 哈希表插入动画
演示 4：浅拷贝 vs 深拷贝可视化（嵌套列表）
演示 5：字符串切片三参数（[start:stop:step]）

code/types_demo.py 场景：综合演示 6 种类型的常见操作和性能测试

面试题方向：is vs ==、dict 实现、3.7 后有序、字符串拼接性能、浅深拷贝、列表切片

第 3 章控制流与函数 (`03_flow_function.md`)

核心知识点：

if/elif/else、match/case 模式匹配（3.10+）
for/while/break/continue/else 子句（独特特性！）
推导式：list / dict / set / generator expression
函数定义、*args/**kwargs、关键字参数、默认参数的可变陷阱
作用域 LEGB 规则（Local → Enclosing → Global → Builtin）
闭包（Closure）：函数 + 引用环境
lambda、map/filter/reduce、Pythonic 偏好

SVG 推荐：

legb-scope.svg：LEGB 作用域查找顺序图
closure-mechanism.svg：闭包工作原理（函数对象 + cell + free variable）
function-call-stack.svg：函数调用栈帧示意

demo.html 推荐演示：

演示 1：LEGB 查找过程动画（输入变量名，显示在哪一层找到）
演示 2：闭包计数器（多个 counter 互不干扰）
演示 3：默认参数陷阱（可变默认值跨调用累积）
演示 4：列表推导 vs map/filter 性能对比
演示 5：match/case 模式匹配可视化

code/closure_demo.py 场景：实现一个支持配置的计数器工厂

面试题方向：默认参数陷阱、闭包是什么、LEGB、global/nonlocal、lambda 限制、推导式 vs map

第 4 章面向对象编程 (`04_oop.md`)

核心知识点：

类与实例、__init__ vs __new__
类属性 vs 实例属性、__dict__ 与 __slots__
继承、MRO（C3 线性化）、super()
魔术方法：__str__/__repr__/__len__/__getitem__/__call__/__eq__/__hash__
@property / @classmethod / @staticmethod
抽象基类 ABC / 协议 Protocol
元类 type（类也是对象）
dataclass / namedtuple / TypedDict 选型

SVG 推荐：

class-instance-relation.svg：类与实例的关系（类是模板、实例有自己的 __dict__）
mro-c3-linearization.svg：钻石继承的 MRO 计算图
metaclass-hierarchy.svg：type → 元类 → 类 → 实例的四层关系

demo.html 推荐演示：

演示 1：实例化过程（__new__ 创建 → __init__ 初始化）
演示 2：MRO 钻石继承可视化（D 继承 B,C，B,C 继承 A）
演示 3：__slots__ 内存对比
演示 4：魔术方法触发（用户操作 → 触发哪个 dunder）
演示 5：元类创建类（type('Foo', (), {})）

code/oop_demo.py 场景：实现一个简化的 ORM 模型类（含元类）

面试题方向：init vs new、MRO、classmethod 区别、slots、@property 原理、元类

第 5 章模块、包与依赖管理 (`05_module_package.md`)

核心知识点：

import 机制：sys.modules 缓存、sys.path 查找
__init__.py 的作用、命名空间包（PEP 420）
相对导入 vs 绝对导入
虚拟环境：venv / virtualenv / conda
包管理：pip / requirements.txt / pyproject.toml
现代工具链：uv / poetry / pdm
发布到 PyPI

SVG 推荐：

import-mechanism.svg：import 时的查找顺序流程图
venv-isolation.svg：虚拟环境隔离原理（每个 venv 独立的 site-packages）
pip-vs-uv.svg：传统 pip vs 现代 uv 的对比

demo.html 推荐演示：

演示 1：import 查找顺序模拟器（输入模块名，显示按 sys.path 查找过程）
演示 2：相对 vs 绝对导入对比
演示 3：依赖锁文件演化（requirements.txt → poetry.lock → uv.lock）
演示 4：虚拟环境创建步骤
演示 5：包结构可视化（含 vs 不含 init.py）

code/package_demo/ 场景：一个微型示例包，演示 __init__.py 的几种典型用法

面试题方向：import 查找顺序、init.py 作用、相对 vs 绝对导入、虚拟环境必要性、pip 选型

第 6 章异常处理与文件 IO (`06_exception_io.md`)

核心知识点：

异常体系：BaseException → Exception 树
try/except/else/finally 完整语义
自定义异常、异常链 raise from
上下文管理器：with 语句、__enter__/__exit__、@contextmanager
文件 IO：open 模式、编码、文本 vs 二进制
pathlib 现代写法 vs 老 os.path
标准输入输出 sys.stdin/stdout/stderr

SVG 推荐：

exception-hierarchy.svg：Python 异常类继承树
try-except-flow.svg：try/except/else/finally 的完整执行流程
context-manager-flow.svg：with 语句生命周期

demo.html 推荐演示：

演示 1：异常捕获优先级（多个 except，从上往下匹配）
演示 2：try/except/else/finally 执行顺序动画
演示 3：with 语句的 enter/exit 调用顺序
演示 4：异常链可视化（raise from）
演示 5：pathlib vs os.path 对比

code/io_demo.py 场景：安全的文件处理工具（带异常处理 + 上下文管理）

面试题方向：try/except/else/finally、捕获 Exception 的坑、上下文管理器原理、@contextmanager、open 不用 with 的问题

第 7 章迭代器、生成器、装饰器 (`07_iter_gen_decorator.md`)

核心知识点：

迭代器协议：__iter__ / __next__ / StopIteration
可迭代对象 vs 迭代器
生成器函数：yield / yield from
生成器 vs 列表的内存对比（处理 1 亿数据）
装饰器原理：函数也是对象
带参装饰器、类装饰器、functools.wraps
实战装饰器：日志、缓存、性能计时、重试

SVG 推荐：

iterator-protocol.svg：迭代器协议的方法和状态切换
generator-state.svg：生成器函数的状态机（CREATED / RUNNING / SUSPENDED / CLOSED）
decorator-stack.svg：多层装饰器的调用栈和包装顺序

demo.html 推荐演示：

演示 1：迭代器单步执行（next() 一次次推进）
演示 2：生成器 vs 列表内存可视化（处理百万数据）
演示 3：装饰器包装过程动画（@A @B @C 的顺序）
演示 4：带参装饰器三层闭包
演示 5：functools.lru_cache 命中率

code/decorator_toolkit.py 场景：4 个实用装饰器（计时、重试、缓存、日志）

面试题方向：iterable vs iterator、生成器节省内存原因、yield from 优势、装饰器原理、functools.wraps、带参装饰器

第 8 章并发：多线程 / 多进程 / GIL (`08_concurrency.md`)

核心知识点：

进程 vs 线程 vs 协程的本质区别
GIL 是什么？为什么 Python 有 GIL？
threading：Lock / RLock / Semaphore / Event / Condition
multiprocessing：Process / Pool / Queue / Pipe
concurrent.futures 高层抽象
CPU 密集 vs IO 密集：用谁不用谁
Python 3.13 的 No-GIL（PEP 703）

SVG 推荐：

process-thread-coroutine.svg：进程 / 线程 / 协程的资源占用和调度对比
gil-mechanism.svg：GIL 的工作机制（一个时刻只有一个线程持有锁）
cpu-vs-io-bound.svg：CPU 密集与 IO 密集任务在多线程下的性能差异

demo.html 推荐演示：

演示 1：GIL 抢占可视化（4 个线程争抢 GIL）
演示 2：CPU 密集 vs IO 密集任务在多线程下的速度对比
演示 3：Lock vs RLock 区别（重入测试）
演示 4：生产者消费者模型动画
演示 5：进程池 vs 线程池

code/concurrency_demo.py 场景：CPU 密集任务对比（单线程 / 多线程 / 多进程）

面试题方向：GIL 是什么、GIL 让多线程没用吗、多线程多进程协程怎么选、Lock vs RLock、multiprocessing 慢在哪

第 9 章异步编程 asyncio (`09_asyncio.md`)

核心知识点：

协程是什么？从 yield 到 async/await 的演进
事件循环（Event Loop）的工作原理
async def / await / asyncio.run
gather / wait / as_completed / Task / Future
同步代码混入异步：run_in_executor
aiohttp 实战：并发抓取 N 个 URL
常见踩坑：阻塞事件循环、忘记 await

SVG 推荐：

event-loop.svg：事件循环的核心循环图（pending → running → callback）
coroutine-vs-thread.svg：协程切换 vs 线程切换的对比
asyncio-task-flow.svg：asyncio.gather 多任务调度流程

demo.html 推荐演示：

演示 1：事件循环可视化（协程在循环中切换）
演示 2：sync vs async 抓 5 个 URL 的时间对比动画
演示 3：await 关键字的"暂停-恢复"机制
演示 4：gather vs wait vs as_completed 行为差异
演示 5：误用同步代码导致事件循环阻塞的演示

code/async_demo.py 场景：异步并发请求 + 信号量限速

面试题方向：协程和线程区别、async def 直接调用、事件循环原理、await 非 awaitable、同步代码混入 asyncio、gather vs wait

第 10 章标准库精华 (`10_stdlib.md`)

核心知识点：

datetime / time / zoneinfo
collections：Counter / defaultdict / OrderedDict / deque / namedtuple
itertools：chain / groupby / product / combinations / permutations
functools：lru_cache / partial / reduce / singledispatch / cached_property
json / csv / re / logging
os / pathlib / shutil / subprocess

SVG 推荐：

stdlib-map.svg：Python 标准库分类地图（IO / 数据 / 网络 / 系统等）
lru-cache-internals.svg：lru_cache 双向链表 + dict 实现
re-engine.svg：正则引擎的 NFA / DFA 状态机示意

demo.html 推荐演示：

演示 1：Counter / defaultdict 等容器对比
演示 2：itertools 常用函数演示
演示 3：lru_cache 命中率

examples

04 · internal

examples

章节产出规范（所有子 Agent 必读） ​

0. 共同任务背景 ​

1. 必读参考（动手前先读完） ​

2. 关键陷阱（必须规避） ​

2.1 ⚠️ SVG 必须用 Python 脚本写入 ​

2.2 ⚠️ Markdown 大文件分段写入 ​

2.3 ⚠️ Demo.html 里写 Python 代码不要用三引号 ​

3. .md 文档结构（5 段式 + 面试题） ​

4. SVG 风格规范（svg-draw 标准） ​

5. demo.html 风格规范 ​

6. 实战代码规范 ​

7. 各章节具体大纲 ​

第 2 章 基础语法与数据类型 (02_basic_types.md) ​

第 3 章 控制流与函数 (03_flow_function.md) ​

第 4 章 面向对象编程 (04_oop.md) ​

第 5 章 模块、包与依赖管理 (05_module_package.md) ​

第 6 章 异常处理与文件 IO (06_exception_io.md) ​

第 7 章 迭代器、生成器、装饰器 (07_iter_gen_decorator.md) ​

第 8 章 并发：多线程 / 多进程 / GIL (08_concurrency.md) ​

第 9 章 异步编程 asyncio (09_asyncio.md) ​

第 10 章 标准库精华 (10_stdlib.md) ​

章节产出规范（所有子 Agent 必读）

0. 共同任务背景

1. 必读参考（动手前先读完）

2. 关键陷阱（必须规避）

2.1 ⚠️ SVG 必须用 Python 脚本写入

2.2 ⚠️ Markdown 大文件分段写入

2.3 ⚠️ Demo.html 里写 Python 代码不要用三引号

3. .md 文档结构（5 段式 + 面试题）

4. SVG 风格规范（svg-draw 标准）

5. demo.html 风格规范

6. 实战代码规范

7. 各章节具体大纲

第 2 章基础语法与数据类型 (`02_basic_types.md`)

第 3 章控制流与函数 (`03_flow_function.md`)

第 4 章面向对象编程 (`04_oop.md`)

第 5 章模块、包与依赖管理 (`05_module_package.md`)

第 6 章异常处理与文件 IO (`06_exception_io.md`)

第 7 章迭代器、生成器、装饰器 (`07_iter_gen_decorator.md`)

第 8 章并发：多线程 / 多进程 / GIL (`08_concurrency.md`)

第 9 章异步编程 asyncio (`09_asyncio.md`)

第 10 章标准库精华 (`10_stdlib.md`)