复用 docs_dir: Article 不动原目录结构。nav 覆盖 codeSpec、python0-16
和闭包/装饰器全部章节。首页 Article/index.md 仿原 README 开场风格做
简单引导,链接到几个核心章节。
已知 2 处 broken local image(python8/Preface.md、python9/2.md)
来自仓库历史问题,留待 Stage 1 处理 python8/python9 章节时统一识别。

example_runner 扫描 Article/**/*.md 中的 ```python 代码块逐块跑一遍,
支持 <!-- skip-ci --> 前置注释跳过单块。默认匹配大小写两种 [Pp]ython
fenced 标记,兼容现有大写写法。
GH Actions 在 3.10/3.11/3.12/3.13 矩阵上跑。当前基线 235 块、72 失败,
Stage 1 完成后预期失败数大幅下降。

参考原 SUMMARY.md 的层级,一级目录可折叠展开二级子页面。

原图是 Python 代码规范的章节目录树(非代码截图),按 spec §3 决策
转为可点击、可搜索的 markdown 嵌套列表,三大节加上跳转链接。

防御 1:download_legacy_images.py
- 下载完用 magic bytes 校验(PNG/JPEG/GIF/WebP)
- 单 URL 失败重试 1 次
- 已存在且校验通过的跳过(断点续传)
- 失败列表写到 _legacy_images/_failed.txt
- 加 --validate 模式只校验不下载
- 加 --redo 模式无视已有重新下载
防御 2:tools/SUBAGENT_PROMPT_TEMPLATE.md
- 标准化 Stage 1 单文件截图替换流程
- 硬规则:Read 图前先用 file 命令验证是合法图片
- API 错误 fallback:遇到 'Could not process image' 不重试不阻塞,按上下文重写
- 单文件原子化 commit + example_runner 验证
背景:之前 5-6 次卡死的根因是 1 张 PNG 文件实际是 xxd 文本,
subagent 触发 API 400 后无 fallback 直接停止响应,主控制器看到的是
'in progress 永不退出'。这两个防御从源头和反应两层避免再发生。

实测发现 Anthropic vision API 对大尺寸 + 8-bit colormap PNG(如
2019年07月06日-091204.png 1540x1354 indexed PNG)会返回 400 'Could not
process image'。用 macOS sips 把 _legacy_images/ 下所有图统一转成
长边 ≤1024 的 RGB JPEG,输出到 _legacy_images_safe/,让后续视觉
识别 100% 不再触发 API 拒绝。
_legacy_images_safe/ 也加进 .gitignore(本地参考,不入库)。

- 第 1 张 TIOBE 走势图 → 折线图无法转代码块,按图列出 Top 10 关键
 趋势的文字小结 + 数据来源链接。
- 第 2 张北上广深 Python 薪资表 → markdown 表格。
- 第 3 张澎湃新闻'Python 进入山东小学课本'报道截图 → markdown 引用块
 保留原报道关键摘录(标题/作者/日期/正文核心两段)。
原文段落 100% 保留,仅替换 3 处 ![](http*) 引用。

...hon20 dataclass+Pydantic / python21 上下文管理器 / python22 async+httpx)

...st / python26 logging / python27 打包+typer / python28 出路指南)

之前 Plan 1 一刀切把所有图转 markdown,把流程图/活动图也错转了。
本次 audit 出 19 张候选 + If.md 还原 UML 活动图(替换 mermaid),共 20 张:
- 14 张章节心智图(python1-14 Preface + codeSpec),统一命名 mindmap.png
- 5 张示意图(TIOBE 趋势、变量指向、tuple 结构、类创建过程、Condition)
- 1 张 if 条件 UML 活动图(python5/If.md,替换 mermaid 渲染)
附带清理 python2/3/6 Preface 内的 readwithu/公众号过期引用(同文件改动并入)。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- python2/Grammar:readwithu 链接改站内相对路径
- python8/Preface:去除 JetBrains 激活/CSDN 破解链接,改用站内 IDE 引用
- python8/8、python14/6:删除 TwoWater 旧 GitHub 链接 + Gitbook 同步说明
- python10/6、python14/6:删除「闭眼说真话」/「两点水」公众号引导
- index.md:删除「面向零基础读者...」多余说明,保留原项目风格 quote
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- python9/2.md:替换缺失的 from···import 对比图为代码块(mkdocs build 死链)
- mkdocs.yml:补 codeSpec/序、枚举类/序 入 nav(其他章节都有「序」)
- advanced/advanced.md:绝对路径 /Article/... 改相对(mkdocs 不重写绝对链接会死链)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

516 处替换,覆盖 Article 下 39 个章节 + mkdocs.yml copyright。
统一作者称谓为更亲切的「水哥」。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

上一次全文替换把代码示例里的字符串字面量也改了(pyproject 字段、
argparse default、typer.prompt、命令行输入输出等),这些字面量
后续被章节文字引用,改了会导致代码-讲解不一致。
本次只回滚 fenced code block 内的「水哥」为「两点水」,正文称谓保留「水哥」。
共 34 个文件,428 处回滚。另手工修正 python27/1.md 一处嵌套 \`\`\`markdown
fence 导致的误识别(line 566 是作者正文,应保留水哥)。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- 一去不返还 → 一去不复返
- 带奈何 → 但奈何
- 「我这个课程是不是还有人看,但我都劝说」整理为「我以为这个课程不会再有人看了,所以都劝大家」
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

setup-python 的 cache: pip 默认查找 requirements.txt / pyproject.toml,
我们用的是 requirements-docs.txt,需要显式指定 cache-dependency-path,
否则会报 "No file matched to [**/requirements.txt or **/pyproject.toml]"
导致 build 失败。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

补 images/ 目录放两张站点截图,同时清理已过时的"知识点补漏"和"Python 进阶"段。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- A 类(GitBook 时代遗留):book.json、TwoWater-Python.json、SUMMARY.md
- B 类(README 与 mkdocs nav 均不引用的孤儿章节):Article/{advanced,Linux,supplement}/
- C 类(孤立资源 + 政策敏感内容):Res/
- D 类(一次性图片迁移脚本,主流程已结束):tools/{download,sanitize,find}_*.py、SUBAGENT_PROMPT_TEMPLATE.md、__init__.py
- 保留 tools/example_runner.py,后续可接入 CI 校验代码块
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

教程内容(markdown / 代码示例 / 图片)以 CC BY 4.0 协议授权,
允许任何人自由分享与改编,仅需署名。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

之前的 attribution preamble 导致 GitHub 把 license 检测为
NOASSERTION(fuzzy match 阈值不到 95%)。改为纯 SPDX 标准
文本,attribution 信息后续放到 README。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

互动版(learn-py.org)面向零基础动手学,文档版(GitHub Pages)面向系统通读与速查,避免新访客只看到旧文档站。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>