从0到1实战教程 docx 编写与精修（tutorial-docx-craft）
面向零基础小白的工具/软件入门实战教程：从搭大纲到最终 docx 交付，含一套打磨流水线。核心是席先生确认过的体例铁律 + 八段流水线 + 两条编辑路线选型。参考实例：《ComfyUI 从 0 到 1 实战教程》（15 章 + 附录 A-D，本机 ppt_work/ 下）。
工具层细节（editor_sdk 批量文本修正、doc_find 返回格式三坑）见 docx-batch-text-edit 技能，本技能只讲教程内容与流程，不重复。
A. 写作体例铁律（席先生偏好，任何教程通用）
- 对象 = 完全小白（"没碰过电脑绘画、甚至不太懂电脑的人"）：少术语、多打比方（做菜流程图/厨房/搭积木/传送带/翻译官）。必须出现的术语，先讲"它是干什么的、为什么要这么做"。
- 每个概念块用固定句式："它是干什么的：… / 为什么这样做：…"，先结论后原因。
- 每章末尾放「小结：」框：一句话串起本章主线（如 "X = 节点→连线→去噪，点 Queue 才运行"）。
- 操作类内容一律"完整步骤体例"：
- 结构：目标 → 准备(可选) → 第N步：… → 卡住了？自查N条 → 收尾/下一步
- 每步必须写清"点什么、填什么、为什么"；参数给真实值（seed=42、steps=20、cfg=7、denoise=0.55、512×768…），不同章节的参数示例要自洽不打架。
- 关键步骤配"为什么"解释段（如"为什么 denoise 设 0.55：太低动漫味不足…"）。
- 分场景给对照值（如 denoise 0.3-0.5 / 0.7-0.85 / >0.85 的表格），比单一推荐更能帮读者理解旋钮。 - 交叉引用必须真实存在：正文用"见 4.4 / 附录D / 第7章"串起关联内容；交付前跑脚本审计引用存在性（见 G-2），杜绝死链。
- 事实先核后写，宁删勿编：URL、GitHub 仓库、模型版本号、节点名、快捷键、拼写（JoyCaption 非 Jaycaption）全部 WebSearch/本地源码核实；外部不确定的版本（如 WAN 3.0）要么标"官方未确认"要么不写。
- 配图带图注：统一「图：第X.X节 一句话描述（关键参数）」紧跟讲解段落；示意图（节点框+连线）比真实截图更清晰时可先用示意，用户明确要求且软件可用时再上真实截图。
- 附录三件套：常见报错与排查 / 常用快捷键 / 模型与资源网站清单（完整 URL）；新手教程建议加术语速查表（多张两列表：界面词/端口类型/参数词/功能词，"忘了就回来看一眼"）。
- 读者视角自查：机器扫完再人工从头通读一遍（错别字、语句顺滑、引号全半角统一、知识点表述准确），见 C 流水线 S6。
B. 推荐成书结构（从 ComfyUI 教程提炼，可裁剪）
- 封面 5 行：主标题 + 副标题（"用搭积木的方式学会…"）+ 关键能力标签 + "内部学习资料 · N 章 · 附 GitHub 开源工作流参考"
- 前言：用一页比喻讲清"这工具是干嘛的 / 为什么用这个方式学 / 读完能到什么水平"
- 正文章节节奏：是什么 & 值不值得学 → 环境准备（含硬件门槛+常见坑）→ 核心概念 → 第一个成功案例（尽早让读者出第一个成果） → 参数/提示词 → 进阶功能（每个都有"实操案例"）→ 2~3 个综合实战（完整步骤）→ 进阶方向与资源
- 综合实战章多给"一个目标多方案"实例（整体换风格 / 只改局部 / 多图融合），体现同思路复用
- 附录 A-D：报错 / 快捷键 / 资源站 / 术语速查
C. 八段打磨流水线
| 段 | 目标 | 关键动作 | 出口校验 |
|---|---|---|---|
| S0 规划 | 大纲与章节结构 | 按 B 定章节目录；与用户确认范围/深度/是否有真实素材 | 目录清单获得确认 |
| S1 初稿 | 生成/改写全文 | 见 D 选路线；按 A 体例写"它是干什么的/为什么"块 | 20 h1 / N h2 齐；XML 合法 |
| S2 排版美化 | 观感达标 | tencent-docx beauty_only，或自建模板（封面节+正文节+页码重起）；HTML 关键样式落到标签级（line-height/字体族勿依赖继承） | html-review ≥90；图宽 ≤版心；无苹方等缺失字体 |
| S3 配图 | 讲解可视化 | 示意：matplotlib（CJK 需 SimHei）节点框+连线+参数标注；真实截图：playwright 无头；统一图注格式 | 图数/rels/r:embed 对账一致，无溢出 |
| S4 扩充 | 按需加深度 | 补"用户没问但必然要问"的小节（常见坑/对照表/自查清单） | 新增小节回归比对（源 vs 产物 set 零丢失） |
| S5 逐步走查 | 操作章补步骤 | 给缺步骤的实操案例补"目标+第N步+自查+收尾"；复用 A-4 体例 | 全部实操案例都到"照做能跑通"颗粒度 |
| S6 校对 | 读者向通读 | 机器扫描（占位符/空括号/连标点/叠字/直引号/快捷键空格）→ 人工逐段通读 → 批量就地修正（工具层见 docx-batch-text-edit） | ASCII 引号仅剩代码示例；old 串 0 残留 |
| S7 审计 | 引用/口径一致 | 正则抽 N.M/第N章/附录X 引用比对真实标题集；抽查术语、快捷键、版本号跨章一致 | 0 死链；误报仅小数/版本号 |
| S8 交付 | 落盘 | 备份原文件 → 保存/另存 → md5 校验 → present_files 打开预览；按需复制桌面副本 | 与源 md5 一致 |
流水线可反复进入任意段（本次 ComfyUI 教程实际经历了 2 次扩充、2 次配图、3 轮校对/审计才终稿）。
D. 两条编辑路线（关键选型，按场景权衡）
| 路线 | 适用 | 优点 | 坑 |
|---|---|---|---|
| zipfile 直改 document.xml（重生成 body） | 全文结构级改写/重排、批量新增章节、插图重排 | 样式用真实 styleId（读保存后 styles.xml 为准）、一次成型、可脚本回归 | 手写 XML 转义 &<>；段落 XML 需整段复用保格式 |
| editor_sdk 增量编辑（present_files + doc_*） | 在已打开文档上做局部增删改、用户实时可见 | 实时预览、格式刷 copy_format、撤销/改版记录 | 索引随每次写操作漂移→改前必重新 doc_find/resolve；save_file 会重映射 styleId，不能沿用改前 probe 的 id |
editor_sdk 批量改动铁律：反向降序插入（从大到小 idx）避免坐标漂移；插段落用 doc_insert_paragraph_with_text 后 doc_copy_format 从既有同型段落刷样式（bullet 统一 00002c、正文 Normal）；连续插入用上一次返回的 end_index 链式追加；删"末段"不可行，改样式收尾。批量文本替换见 docx-batch-text-edit。
E. 关键坑速查（都真实踩过）
- styleId 非固定：save_file 后 heading2 可能从 00000a 变 00005f → 一律以保存后 styles.xml 为准。
- 「图+标题」复合段 = 提取陷阱：docx→HTML 必须拆同段文本，否则标题静默丢失；做 h2 集合 round-trip 比对。
- 图片溢出：html-to-docx 不认 max-width 继承，必须预缩放或给固定宽度。
- 中文路径/引号经 bash heredoc 多层转义易走样；脚本入参用文件或 import 传参。
- matplotlib 中文需注册
C:\Windows\Fonts\simhei.ttf并设 font.family。 - 事实类内容（GitHub 仓库、版本号、快捷键）写前核实；版本存疑宁可标"官方未确认"。
F. 交付门禁 checklist
- [ ] zipfile.testzip() OK
- [ ] h1/h2 数量与预期一致（20 章级 h1 / 126+ h2）
- [ ] 图片 r:embed 数与 media 唯一 PNG 数一致，无横向溢出
- [ ] 表格（术语表等）完整
- [ ] 交叉引用审计 0 死链
- [ ] 占位符 0、ASCII 中文引号 0（代码示例除外）
- [ ] 文件已保存 + md5 一致性 + present_files 打开预览
G. 核心脚本 snippet（自包含，勿依赖本机绝对路径）
G-1 zipfile 提取全文（w:t 合并 + 标题分级）
import zipfile, xml.etree.ElementTree as ET
z = zipfile.ZipFile(path); root = ET.fromstring(z.read('word/document.xml'))
W = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
for pel in root.iter(W+'p'):
s = pel.find('.//'+W+'pStyle'); sv = s.get(W+'val') if s is not None else ''
txt = ''.join(t.text or '' for t in pel.iter(W+'t')).strip()
# sv==000008 → 章级 h1；00000a/00005f → h2（以实际 styles.xml 为准）
G-2 章节引用存在性审计
# 抽取全文 h2 文本集 H；正则抽引用 token：r'(?<!\d)(\d{1,2})\.(\d{1,2})(?!\d)'、'第(\d{1,2})章'、'附录[A-D]'
# token 在 H 中找不到 → 死链；剔除小数(1.5)与版本号(2.6/3.0)误报
G-3 editor_sdk 批量文本替换（find 验唯一 → replace）→ 完整实现与三坑见 docx-batch-text-edit 技能。
