亲手造属于你自己的教材（Craft Your Textbook）

铁律（不可违反）

先出设计再写正文；先写金标准再并行；交付前必拆脚手架；触发后必问路线，不替用户默认。 违反本条的字面 = 违反本条的精神。

这是什么

造书 = 为学习者制备一份教材。有两种形态（触发后必选，见下"第一步：定路线"）：

pure-blueprint：给 AI 苏格拉底老师读的教学蓝本（pedagogical spec），结构化、含元指令
human-readable：给人读的流畅教材，AI 拿到也能直接教

三方分工决定所有下游规则：

| 角色 | 做什么 | 看到什么 | |---|---|---| | 用户（学习者） | 跟 AI 老师对话学习 | 只看到对话（blueprint）或读教材+对话（human-readable） | | AI 老师 | 读书，用引导式提问教学 | 读完整本书作为输入 | | 书（造物） | 教学素材 | 是 AI 老师的输入，或人读的教材 |

最常见的根本错误：把书写成"给读者感受的文学作品"——开篇钩子写给谁看？"你"指谁？写每一块前先问："AI 老师/人读到这块会怎么用它？"

书对 AI 老师的四个功能：①内容锚定（防跑题/幻觉）②知识结构（推理主线）③弹药库（案例随取随用）④提问路线图（引导学生抵达知识点的问题方向）。

何时用

用户要把教材/领域知识做成 AI 能教的书或人读的教材
用户说"造一本书""做一本教材""按这套方法写 XX"
需要从 PDF 教材加工出结构化教学素材

第一步：定路线（触发后必须问，不替用户默认）：

"这本书是喂给 AI 苏格拉底老师教学用的教学蓝本（推荐——AI 教学精度最高），还是一本给人读的流畅教材（AI 也能直接拿它教，但教学约束更少）？"

决策启发式：

用户原话含"我自己读/出版/给别人看/当书出/通读/给真人教师/我想先通读" → human-readable
书要喂给已成型的苏格拉底 AI 软件（Socratopia 等） → pure-blueprint
用户不确定 → 推荐 pure-blueprint 并等拍板

digraph route {
    rankdir=TB;
    "用户要造书" [shape=box];
    "原话含'我自己读/出版/当书出/给真人教师/通读'?" [shape=diamond];
    "喂给已成型的苏格拉底 AI 软件?" [shape=diamond];
    "human-readable" [shape=box];
    "pure-blueprint" [shape=box];
    "呈现两路线 + 推荐 pure-blueprint，等用户拍板" [shape=box];

    "用户要造书" -> "原话含'我自己读/出版/当书出/给真人教师/通读'?";
    "原话含'我自己读/出版/当书出/给真人教师/通读'?" -> "human-readable" [label="是"];
    "原话含'我自己读/出版/当书出/给真人教师/通读'?" -> "喂给已成型的苏格拉底 AI 软件?" [label="否"];
    "喂给已成型的苏格拉底 AI 软件?" -> "pure-blueprint" [label="是"];
    "喂给已成型的苏格拉底 AI 软件?" -> "呈现两路线 + 推荐 pure-blueprint，等用户拍板" [label="否/不确定"];
}

路线差异和细节见 references/two-routes.md。

全流程导航（6 阶段）

先出设计，再写正文；先写一章金标准审到满意，再并行铺开。平均每本书 5-7 轮审校。

| 阶段 | 名称 | 做什么 | 产出 | |---|---|---|---| | Phase 1 | 源材料准备 | PDF→MD（MinerU API）+ 复制脚本进项目 + 装依赖 | sources-md/、scripts/ | | Phase 2 | 源探查 | 所有有源书必走：摸源结构、角色标签、简码表、权威层级 | 源材料索引.md 第一层 | | Phase 3 | 教学设计 | 核心阶段：五步设计（见下）+ 三个用户确认关卡 | META/OUTLINE/style-spec/源材料索引 | | Phase 4 | 金标准验证 | 选一章按设计的语法写 → 四层审计 + 试教（条件触发）→ 通过后回填 style-spec | 金标准章 md | | Phase 5 | 全量写作+收网 | 5.1 sub-agent 并行铺章（分批写，写一批即跑章级独立审计）→ 5.2 附录汇编 → 5.3 跨章全书审计（查映射表/事实一致性/时间线/术语）→ 5.4 合并 BOOK.md（human-readable 注入 loader 指令） | chapters/、appendix/、BOOK.md | | Phase 6 | 终检与交付 | 修订复审（核实 5.3 的修复到位且没引入新问题）→ 终检 → 拆脚手架 → 质量门 → 交付 | 纯净 BOOK.md |

Mode A（无源从零造）差异：Phase 2 跳过、幻觉 gate 更严，仅适合 AI 知识密度高领域（见 references/source-material.md 知识密度自评）。Mode B（有源造书）：Phase 2 必走，按源数量选择探查深度（轻量/中量/完整版）。

Phase 5.1 并行铺章的落盘纪律：

进度 ledger：每批/每章写完，在 <项目根>/chapters/progress.md 记一行状态（章号 → 完成 → 审计结论）。上下文压缩后靠它恢复进度，别靠记忆。
模型分级：章节写作 = 标准档模型（prose 生成非机械任务）；机械任务（合并/批量替换/脚本）= 廉价档；全书审计/收尾终审 = 最强档。审计顽固问题升一档重试。

核心：Phase 3 教学设计五步

这是本 skill 的核心——Agent 不套模板，自己设计书的形状。

Phase 3.1 分析源+推导目标（不读模式库，免先入为主）：
- 源材料形态是什么？
- 这本书让学习者最终能做到什么？（通过考试/理解概念/掌握技能/通读建体系）
- 学习者最大的坑是什么？
- 用户确认关卡 ①：目标和坑是否准确
Phase 3.2 路线决策（见"第一步：定路线"）
Phase 3.3 模式选型+板块语法设计：
- 读 references/patterns/README.md，理解模式库
- 带 Phase 3.1 的教学问题翻卡（每张卡判断"这个问题本书有没有"）
- 回答两个强制问题写进 style-spec： ① 考虑过哪些模式、拒绝了哪些、为什么拒绝？ ② 所选每个模式对应本书哪个具体教学问题？
- 可选：从预装配包（认证/叙事/K-12）出发再定制
- 设计章内板块语法（必含/循环/可选板块、叙事约定、章末教学区）
- 用户确认关卡 ②：模式选型和板块语法是否合理
Phase 3.4 整书教学架构设计：
- 知识链主线、卷/部划分、逐章骨架
- 特殊功能章（地基章/收网章）
- 跨章引用机制、附录汇编策略
- 贯穿案例/主角约定
- 回填源材料索引第二层（章级映射）
- 用户确认关卡 ③：全书架构和逐章骨架
Phase 3.5 META+源索引完稿：
- META 完成（必答 10 个问题见 references/file-contracts.md）
- 源材料索引完成

不变量底线见 references/invariants.md——任何设计都不能违反。

关键工程原则

金标准先行：没有金标准就并行 = agent 必然漂移
一个 agent 只写一章，避免长上下文漂移
断言可追溯：每写一条定义/公式/偏好判断，都能回源或回判断根
深度承诺：Phase 3 在 style-spec 声明四维深度目标（默认"中"底线），金标准兑现，未兑现回炉
防螺旋：Phase 3 定稿后不允许加章/附录/机制板块，新需求先问"能不能塞进现有结构"
交付前必拆脚手架

参考文件按需加载

**REQUIRED:** = Phase 3 开跑前必须读（不变量是底线、模式库是菜单、契约强制回答设计问题）。其余按需。

| 场景 | 参考文件 | |---|---| | REQUIRED Phase 3 不变量底线 | references/invariants.md | | REQUIRED Phase 3 模式选型 | references/patterns/README.md | | REQUIRED Phase 3 四文件契约 | references/file-contracts.md | | Phase 1 PDF 转换 | 见下方"Phase 1 前置"段落 + scripts/01_pdf_to_md.py docstring | | Phase 2 源探查 | references/source-material.md | | Phase 3 板块语法起点 | references/chapter-grammar-starter.md | | Phase 3.3 深度设计 / Phase 4 深度审计 | references/depth.md | | Phase 3 路线差异 | references/two-routes.md | | Phase 4-5 审计 | references/audit-and-testing.md | | Phase 5 写作 subagent prompt | references/subagent-prompts/writing-agent-prompt.md | | Phase 5 审计 subagent prompt | references/subagent-prompts/audit-agent-prompt.md | | Phase 6 交付 | references/delivery-checklist.md | | 避坑 | references/anti-patterns.md |

Quick Reference 速查表

| 常见操作 | 命令 / 判据 | |---|---| | Phase 1 PDF→MD | python <项目>/scripts/01_pdf_to_md.py <PDF> sources-md/（理科 ENABLE_FORMULA=True） | | 定路线 | 见上方流程；两路线差异见 two-routes.md | | 审计何时跑 | 章写完 L1/L2/L3；全书 L4；试教条件触发（见 audit-and-testing.md） | | Phase 6 禁用词终检 | grep -rn "AI\|伴读\|指挥官\|prompt\|批量指挥\|对话框\|Socratopia\|让学生" chapters/ appendix/ \| grep -v 'AI 老师'（先 export LC_ALL=C.UTF-8） | | Phase 6 拆脚手架 | python scripts/strip_meta_sections.py chapters/ appendix/ + 逐类 grep 清理 | | Phase 6 合并 | python scripts/merge_book.py（human-readable 加 --strip-frontmatter） | | 质量门判据⑥ baseline | wc -c < BOOK.md \| tr -d ' ' > .book-baseline；重跑时 ±10% 内 |

⚠️ Phase 1 前置：MinerU API Token

PDF→Markdown 默认走 MinerU 在线 API（mineru.net）。开跑前让用户完成：

定位 skill 脚本目录 + 装依赖：

# 依次在用户级、项目级目录查找 skill 位置，取第一个命中
SKILL_DIR=$(dirname "$({ find ~/.claude -name SKILL.md -path '*craft-your-textbook*' 2>/dev/null; find . -name SKILL.md -path '*craft-your-textbook*' 2>/dev/null; } | head -1)")
if [ -z "$SKILL_DIR" ]; then
  echo "错误：找不到 craft-your-textbook skill 目录。请确认已正确安装（见 README 安装节）。"
  return 1 2>/dev/null || exit 1
fi
pip install -r "$SKILL_DIR/scripts/requirements.txt"

复制脚本：cp "$SKILL_DIR/scripts/"*.py <项目根>/scripts/

打开 https://mineru.net 注册申请 API Token
设环境变量：export MINERU_TOKEN="你的token"
运行 python <项目根>/scripts/01_pdf_to_md.py <PDF路径> sources-md/

理科改 ENABLE_FORMULA = True。已有 MD 跳过 Phase 1。

一句话核心

书是给 AI 老师或人读的教学素材，学生主要跟 AI 老师对话。触发后先定路线；不套模板，Phase 3 自己设计书的形状——不变量是底线、模式库是菜单、四文件契约强制回答设计问题。先出设计再写正文，先写金标准再并行，交付前必拆脚手架。