docs 目录 OKF v0.2 Wiki 教程规范化改造里程碑复盘

docs 目录 OKF v0.2 Wiki 教程规范化改造里程碑复盘#

方法论编排：七概念 R→I→E→C 链路（里程碑复盘场景） 复盘对象：以 projects/awesome-okf-xs 为参考标杆，将 docs/ 目录改造为符合 OKF v0.2 规范的 Wiki 教程文档库 时间范围：2026-08-28（单会话完成） 复盘日期：2026-08-28 session：sc-20260828-okf-wiki-conversion 原子提交：d95a862e（132 files changed, 2246 insertions(+), 307 deletions(-)）

一、改造规模总览#

本次改造以 OKF v0.2 规范成熟参考实现 awesome-okf-xs（11 技术域、30 分组、263 知识包）为标杆，对 SpecWeave 主文档库 docs/（384 个 Markdown 文件）进行规范化改造。核心量化指标如下：

1.1 规模总览#

指标	数值
总 Markdown 文件数	384
index.md 文件数	101
log.md 文件数	33
readme.md 文件数	4
内容文件数（非 index/log/readme）	246
含合规 frontmatter+type 的内容文件	246（100%）
toctree 块总数	101
新增 Python 脚本	4 个（800 行）
tasks/ 包文件	3 个（212 行）
invoke 注册任务数	10 个
原子提交变更规模	132 files, +2246/-307

1.2 改造前后对比#

维度	改造前	改造后
Sphinx 构建警告数	421	0
toctree 导航问题	373（2 断链 + 6 缺失 index + 9 缺失条目 + 356 不可达）	0
子目录 index.md 越权 frontmatter	32 个携带 okf_version	0 个（100% 移除）
frontmatter 合规率	248/249（99.6%，1 个 YAML 错误）	246/246（100%）
质量门检查脚本	0 个	3 个（utf8/toctrees/frontmatter）
任务系统	单文件 tasks.py	tasks/ 包（docs + gates 命名空间）
缺失 index.md 目录	10 个	0 个

1.3 type 字段分布#

type	数量	说明
Reference	46	参考资料
Concept	30	概念说明
Tutorial	15	教程
Report	10	复盘/分析报告
Pattern	4	可复用模式
Example	3	示例
insight	1	洞察
knowledge	2	知识条目

二、R 阶段：事实清单（32 条）#

G1 质量门：✅ 通过（32 条事实均为客观描述，无"因为/所以/导致/错误/失误"等因果推断词）

编号	事实
F01	参考标杆项目 `d:\AI\projects\awesome-okf-xs` 包含 11 个技术域、30 个分组、263 个知识包，具备完整 Sphinx 构建配置、Invoke 任务包和 CI 质量门脚本
F02	改造前 `d:\AI\docs` 包含 200+ Markdown 文件，按 tech/、knowledge/、retrospective/、general/、topics/ 五大板块组织，另含 refactor/ 目录
F03	docs 环境中未安装 invoke 包，通过 `pip install invoke` 安装（invoke-3.0.3）
F04	docs 环境中未安装 invocations 包（参考项目 tasks/docs.py 依赖它）
F05	改造前 32 个子目录 index.md 携带 `okf_version: "0.2"` frontmatter
F06	改造前 249 个非保留 .md 文件中 248 个已有合规 frontmatter（含 type 字段），1 个存在 YAML 转义问题
F07	toctree 初次检查报告 373 个问题：2 个断链、6 个缺失 index.md、9 个缺失条目、356 个不可达文档
F08	Sphinx 首次构建处理 383 个源文件，输出 421 条警告
F09	`article-content.md` 无 H1 标题，Sphinx 对每个 toctree 引用报告 toc.no_title 警告，共 387 条
F10	`torch-dev-mirror-build-retrospective-20260820.md` 第 9 行 source 字段双引号字符串内 `\s` 不符合 YAML 转义规范
F11	为 4 个不在 toctree 中的 README.md 添加 orphan 声明时，脚本拼接输出 `---orphan: true`（分隔符与内容之间缺少换行符）
F12	4 个 README.md frontmatter 格式不符合 YAML 规范，check-frontmatter.py 报告 4 处违规
F13	最终统计：384 个 .md 文件（101 index.md + 33 log.md + 4 readme.md + 246 内容文件）
F14	246 个内容文件全部有可解析 YAML frontmatter 且含非空 type 字段
F15	type 分布：Reference 46、Concept 30、Tutorial 15、Report 10、Pattern 4、Example 3、insight 1、knowledge 2
F16	100 个子目录 index.md 无 frontmatter，0 个携带 frontmatter
F17	根 `docs/index.md` 携带 okf_version 字段
F18	101 个 toctree 块分布在 101 个 index.md 中
F19	4 个文件声明 `orphan: true`（general/references/readme.md、tech/references/readme.md、topics/references/readme.md、knowledge/learning/03-agent-platforms-tools/README.md）
F20	新增 `scripts/check-utf8.py`（106 行）：UTF-8 有效性检查，含 --self-test 自检
F21	新增 `scripts/check-toctrees.py`（297 行）：toctree 完整性检查，含 --self-test 自检
F22	新增 `scripts/check-frontmatter.py`（198 行）：frontmatter 合规检查，含 --self-test 自检
F23	新增 `scripts/fix-toctrees.py`（199 行）：toctree 自动修复工具，需运行两轮收敛
F24	`tasks/` 包含 `__init__.py`（34 行）、`docs.py`（132 行）、`gates.py`（46 行）
F25	tasks/docs.py 自包含实现，不依赖 invocations 包，直接使用 subprocess 调用 sphinx-build -M
F26	invoke 注册 10 个任务：6 个根级构建任务（help/build/html/clean/linkcheck/doctest）+ 4 个 gates 子集合任务
F27	conf.py 新增 source-read 事件钩子（第 132-164 行，共 33 行），自动给 frontmatter 裸日期值加引号
F28	创建了 10 个新 index.md（algorithmic-art、engineering、learning、retrospective/patterns、03-agent-platforms-tools、codewhale/concepts/general、codewhale/concepts/tech、2 个 competitive-analysis 子目录、milestone/retrospective-agency-deep-learning-20260706）
F29	删除 `docs/README.md`（与 index.md 重复）和 `docs/tasks.py`（重构为 tasks/ 包）
F30	统一 14 个 log.md 标题为"# 变更日志"
F31	最终 Sphinx HTML 构建成功，0 警告；三个质量门脚本全部通过（UTF-8: 384 文件、toctree: 全部可达、frontmatter: 383 文件合规）
F32	独立审查 7 项验收标准（AC-1 至 AC-7）全部 PASS，无 FAIL 项

三、I 阶段：核心洞察（3 条）#

G2 质量门：✅ 通过（每条洞察含四元组：陈述/证据/反常识/行动）

洞察 I-1：大规模文档规范化的瓶颈是导航结构而非元数据补全#

维度	内容
陈述	在 384 个文件的文档库中，frontmatter 合规率改造前已达 99.6%（248/249），但 toctree 导航问题达 373 个——导航结构完整性才是大规模文档规范化的主要工作量所在
证据	F05（32 个越权 frontmatter）、F06（99.6% 已合规）、F07（373 个 toctree 问题）、F28（10 个缺失 index.md）、F23（199 行自动修复脚本）
反常识	直觉上"给每个文件加 frontmatter"是文档规范化的最大工作量；实际数据显示元数据补全仅涉及 1 个 YAML 错误修复和 32 个越权字段移除，而导航修复需要创建 10 个新 index.md、更新 90+ 个 toctree 块、编写 297 行检查脚本和 199 行修复脚本
下次行动	规划大规模文档规范化项目时，优先投入 toctree 自动检查和修复工具的开发，将 frontmatter 批量补全视为低优先级任务；先用检查脚本量化两类问题的实际规模再分配资源

洞察 I-2：单一文件缺陷可产生数量级级联警告效应#

维度	内容
陈述	`article-content.md` 缺少一个 H1 标题，在 Sphinx 构建中产生 387 个 toc.no_title 警告，占首次构建总警告数（421）的 91.9%；修复该单一文件后警告数从 421 降至 4
证据	F08（421 条警告）、F09（387 条来自单一文件）、F31（修复后 0 警告）
反常识	421 条警告看起来像是 421 个独立问题，容易让人判断为"问题严重、修复成本高"；实际上 91.9% 的警告来自同一根因，警告数量与问题根因数量不呈线性关系，而呈"一个根因 × N 个引用点"的乘法关系
下次行动	处理构建/linter 警告时，第一步按警告类型分组并提取涉及的唯一文件列表，优先修复唯一文件数最少的警告类型；不要按警告出现顺序逐个修复，否则可能在修复 387 个症状而非 1 个根因

洞察 I-3：自动化修复脚本本身必须纳入质量门保护范围#

维度	内容
陈述	为消除 4 个 toc.not_included 警告而编写的 orphan frontmatter 添加脚本，在文件拼接时产生 `---orphan: true`（缺少换行），引入 4 个 frontmatter 格式缺陷，使 frontmatter 质量门从通过状态退化为失败状态
证据	F11（脚本输出缺少换行）、F12（4 处 frontmatter 违规）、F31（最终修复后通过）
反常识	自动化修复工具本应减少问题数量，但脚本字符串拼接逻辑的一个缺陷引入了与待修复问题数量相同的新问题——"修复脚本"本身也可能成为缺陷来源，且自动化脚本的修改范围广，一个拼接 bug 可同时影响多个文件
下次行动	所有自动修改文件的脚本执行后必须立即运行对应的质量门检查脚本验证输出，形成"修复→验证"闭环；脚本中涉及 frontmatter 分隔符等关键格式时，应使用结构化 YAML 库操作而非字符串拼接

四、E 阶段：可复用模式萃取#

G3 质量门：✅ 通过（模式含触发场景+核心步骤+反模式+迁移验证）

模式 1：导航收敛修复法#

项	内容
模式名称	导航收敛修复法
触发场景	适用于大规模文档库（100+ 文件）的 toctree/导航不完整问题，尤其是增量积累导致的索引缺失和不可达文档；不适用于小型文档集（<20 文件，手动修复效率更高）
核心步骤	1. 量化：编写检查脚本扫描所有 index.md 的 toctree 引用，识别断链、缺失条目、不可达文档三类问题并计数 2. 创建：编写自动修复脚本，为含 .md 文件但无 index.md 的目录生成 index.md 骨架（含标题和空 toctree） 3. 补全：对现有 index.md，计算目录下应列入 toctree 的条目（子目录 index + 直接 .md 文件），替换或追加 toctree 块 4. 迭代：运行两轮修复——第一轮创建新 index.md，第二轮更新父目录 toctree 收录新创建的 index.md 5. 验证：运行检查脚本确认零问题，Sphinx 构建确认无 toc.not_included 警告
反模式	1. ❌ 只运行一轮修复就认为完成：新创建的 index.md 未被父目录 toctree 收录，仍然不可达 2. ❌ 手动逐个编辑 toctree：100+ 文件场景下效率低且易遗漏，90+ toctree 块的手动维护成本不可接受 3. ❌ 修复后不运行检查验证：无法确认是否全部收敛，可能残留静默不可达文档 4. ❌ 用字符串拼接生成 frontmatter：分隔符与内容之间缺少换行等格式问题难以目视发现
检验标准	检查脚本输出"全部通过"；Sphinx 构建无 toc.not_included 警告；所有 .md 文件从根 index.md 出发可沿 toctree 遍历到达
迁移验证	✅ 已验证于本项目（384 文件、101 toctree 块、373→0 问题） ✅ 可迁移到任何 Sphinx+MyST 文档项目；toctree 概念等价于 MkDocs 的 nav 配置、Docusaurus 的 sidebar 配置，核心逻辑（量化→创建→补全→迭代→验证）与框架无关
成熟度	L2（两个案例支撑：本项目 + awesome-okf-xs 参考项目的同类检查脚本）

模式 2：级联缺陷定位法#

项	内容
模式名称	级联缺陷定位法
触发场景	适用于构建/检查工具报告大量警告但怀疑根因集中的场景；不适用于警告类型分散、各警告根因独立的场景
核心步骤	1. 分组：从构建输出中提取所有警告，按警告类型（如 toc.no_title、toc.not_included、undefined）分组统计 2. 去重：对每种警告类型，提取涉及的唯一文件列表，计算"警告数/唯一文件数"比率 3. 定位：优先处理比率最高的警告类型——高比率意味着少量文件产生大量级联警告 4. 修复：修复该类型涉及的唯一文件（通常是 1-3 个根因文件） 5. 验证：重新构建，确认警告数大幅下降后再处理下一类型
反模式	1. ❌ 按警告出现顺序逐个修复：可能在修复 387 个症状而非 1 个根因，效率极低 2. ❌ 看到大量警告就判定问题严重：警告数量不等于问题数量，91.9% 的警告可能来自单一文件 3. ❌ 不区分警告类型直接全部 suppress：掩盖了真正需要修复的根因 4. ❌ 修复后不重新构建验证：无法确认级联效应是否已消除
检验标准	修复单一文件（或少量文件）后警告数下降超过 80%；剩余警告类型分散且各对应独立根因
迁移验证	✅ 已验证于本项目（421→4 警告，单文件修复消除 91.9%） ✅ 可迁移到编译器警告、linter 警告、测试失败、CI 报错等任何"大量症状/少量根因"场景；核心洞察（警告数与根因数呈乘法关系）与具体工具无关
成熟度	L1（单案例验证，待更多项目确认 80% 阈值的普适性）

五、质量门通过记录#

质量门	检查内容	结果	说明
G1	事实无因果词	✅ 通过	32 条事实均为客观描述，无因果推断词
G2	洞察四元组完整	✅ 通过	3 条洞察均含陈述/证据/反常识/下次行动
G3	模式可迁移	✅ 通过	2 个模式，各含 4 个反模式 + 跨领域迁移验证
G4	行动项原子化	✅ 通过	交付物已通过原子提交 d95a862e 完成，质量门全部通过

六、原子行动项交付记录#

行动项	交付物	验证方式	状态
conf.py 日期兼容性钩子	conf.py:132-164	Python import 确认	✅
UTF-8 质量门脚本	scripts/check-utf8.py	–self-test 通过	✅
toctree 质量门脚本	scripts/check-toctrees.py	–self-test + 全量扫描通过	✅
frontmatter 质量门脚本	scripts/check-frontmatter.py	–self-test + 全量扫描通过	✅
toctree 自动修复工具	scripts/fix-toctrees.py	两轮运行收敛	✅
tasks/ 包重构	tasks/init.py + docs.py + gates.py	`invoke --list` 显示 10 任务	✅
frontmatter 层级权限修复	32 个子目录 index.md	check-frontmatter 通过	✅
toctree 完整性修复	10 个新 index.md + 90+ toctree 更新	check-toctrees 通过	✅
Sphinx 构建零警告	article-content.md H1 + orphan 声明	构建成功，0 警告	✅
独立审查	7 项 AC 全部 PASS	只读审查子智能体报告	✅
原子提交	d95a862e	git log 确认	✅

七、经验总结#

做对了什么#

先量化再修复：在动手修复前先编写检查脚本量化问题规模（373 个 toctree 问题 vs 1 个 frontmatter 错误），避免了资源错配
自动化优先：面对 90+ toctree 块需要更新，选择编写自动修复脚本而非手动编辑，两轮运行即收敛
质量门前置：三个检查脚本均带 --self-test 自检，确保检查工具本身可信
独立审查收尾：完成后委派只读子智能体独立验证 7 项验收标准，避免自我确认偏误

待改进项#

自动修复脚本应使用结构化库操作 YAML：orphan frontmatter 添加脚本使用字符串拼接产生格式缺陷，应使用 yaml 库结构化操作
自动修复后应立即运行对应质量门：脚本执行后未第一时间运行 check-frontmatter.py 验证，导致格式问题在后续构建时才发现
自动生成的 index.md 标题为英文：如 "# Algorithmic Art"、"# Engineering" 等，建议后续中文化（不阻塞构建）