Craft Your Textbook

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

铁律（不可违反）

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

这是什么

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

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

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

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

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

何时用

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

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

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

决策启发式：

1. 用户原话含"我自己读/出版/给别人看/当书出/通读/给真人教师/我想先通读" → human-readable
2. 书要喂给已成型的苏格拉底 AI 软件（Socratopia 等） → pure-blueprint
3. 用户不确定 → 推荐 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 轮审校。

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 不套模板，自己设计书的形状。

1. Phase 3.1 分析源+推导目标（不读模式库，免先入为主）：

   • 源材料形态是什么？
   • 这本书让学习者最终能做到什么？（通过考试/理解概念/掌握技能/通读建体系）
   • 学习者最大的坑是什么？
   • 用户确认关卡 ①：目标和坑是否准确

2. Phase 3.2 路线决策（见"第一步：定路线"）

3. Phase 3.3 模式选型+板块语法设计：

   • 读 references/patterns/README.md，理解模式库
   • 带 Phase 3.1 的教学问题翻卡（每张卡判断"这个问题本书有没有"）
   • 回答两个强制问题写进 style-spec： ① 考虑过哪些模式、拒绝了哪些、为什么拒绝？ ② 所选每个模式对应本书哪个具体教学问题？
   • 可选：从预装配包（认证/叙事/K-12）出发再定制
   • 设计章内板块语法（必含/循环/可选板块、叙事约定、章末教学区）
   • 用户确认关卡 ②：模式选型和板块语法是否合理

4. Phase 3.4 整书教学架构设计：

   • 知识链主线、卷/部划分、逐章骨架
   • 特殊功能章（地基章/收网章）
   • 跨章引用机制、附录汇编策略
   • 贯穿案例/主角约定
   • 回填源材料索引第二层（章级映射）
   • 用户确认关卡 ③：全书架构和逐章骨架

5. Phase 3.5 META+源索引完稿：

   • META 完成（必答 10 个问题见 references/file-contracts.md）
   • 源材料索引完成

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

关键工程原则

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

参考文件按需加载

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

Quick Reference 速查表

⚠️ Phase 1 前置：MinerU API Token

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

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

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

一句话核心

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