book-chapter-generator

书籍章节生成器

版本： 1.1.2

更新日志

• v1.1.2 — “涵盖的概念”表格的第二列现在标题为 Concept Impact Score，不再使用缩写 CIS Score，因为这会重复出现“Score”（CIS 已代表 Concept Impact Score）。这只是列标题的重命名，底层的 cis 字段、计算方式和所有其他行为均未改变。此更改适用于新生成的章节；对于在较早技能版本下已生成章节的书籍，这些文件会保留旧标题，直到单独更新其章节生成脚本或表格。

• v1.1.1 — 步骤 4.6 的完成消息现在始终会强烈建议在运行 chapter-content-generator 之前创建学习吉祥物（使用 book-installer 的学习吉祥物指南）。提前设计的吉祥物会在编写内容时放入每个章节；如果等到已有数十个章节后再添加，就意味着要逐一改造这些章节。此项也已作为一项长期规则写入“注意事项”部分。章节设计和文件结构均未改变。

• v1.1.0 — 现在会在 SKILL.md 的 frontmatter 中将版本记录为 metadata.ibook.version。它位于 metadata: 下，而非单独的 version: 键，因为严格的打包验证会拒绝六个规范字段之外的任何 frontmatter 键，这会阻止该技能用于 claude.ai、Skills API 和 package_skill.py。行为未发生变化。

• v1.0.0 — **重大变更：**此技能首次记录版本号。步骤 1.4a 不再根据边列表自行计算“依赖此概念的概念数量”，而是直接从 learning-graph.json 中每个节点的 cis 字段读取预先计算的 Concept Impact Score (CIS)（由 learning-graph-generator v1.06+ 添加）。CIS 是比原始依赖数量更优的重要性指标：它能反映传递性影响（某个概念即使直接依赖它的概念很少，如果这些概念本身有很多依赖者，它仍可能具有很强的基础性），而仅统计依赖数量会低估这一点。每个生成章节的 index.md 中的“涵盖的概念”部分（步骤 4.4）现在使用包含 Concept 和 CIS Score 列的 Markdown 表格，取代了旧的带有 (N dependents) 后缀的编号列表。要求使用 learning-graph-generator v1.06+ 重新生成 learning-graph.json（缺少 cis 字段的节点将被视为 cis=1，即最低值——加载图时请检查控制台输出；如果每个概念都显示 1，请重新生成）。

概述

此技能通过分析课程说明、学习图和概念分类体系，为智能教材创建全面的章节结构。它会设计出最优的章节大纲，确保所有概念恰好覆盖一次、遵循依赖关系，并将内容合理分配到各章节中。 此任务在学习图生成后按顺序执行。

何时使用此技能

在以下情况下使用此技能：

• 课程说明已定稿，且已生成学习图（learning-graph.json 存在）
• 需要在开始撰写前设计章节内容结构

前置条件：

• /docs/course-description.md 必须存在
• /docs/learning-graph/learning-graph.json 必须存在，且包含约 200 个概念
• 必须已有 mkdocs.yml 文件，以便生成章节链接并加入导航部分

不要在以下情况下使用此技能：

• 尚未生成学习图（请先使用 learning-graph-generator）
• 章节内容已存在，只需更新

章节生成工作流

此技能遵循四步顺序工作流，并在生成文件前征求用户批准。

步骤 1：分析输入资源

设计章节前，先分析以下资源：

1.1 阅读课程说明

阅读 /docs/course-description.md，了解：

• 课程标题和目标受众
• 学习目标和预期成果
• 先修知识
• 整体范围和目标

1.2 读取学习图谱

读取 /docs/learning-graph/learning-graph.json，提取：

• 完整的概念列表（通常有 200 个概念）
• 概念依赖关系（哪些概念需要以其他概念为先修知识）
• 按分类体系类别划分的概念分组
• 课程元数据

!!! info "学习图谱 = 概念依赖图（DAG）" 学习图谱是一种概念依赖图——一种有向无环图 （DAG），其中每条边都表示一种“依赖于”关系。我们选择了 依赖方向（边从一个概念指向它所依赖的概念）， 因为这符合拓扑排序、环检测和传递约简等标准图论算法。

有些学习管理系统使用一种称为**赋能图**的替代方案，
其中的边指向相反方向（从先修概念指向它所赋能的概念）。
对一些教师来说，赋能方向更直观（“学习生态学能帮助你学习生态系统”），
但它对于图算法来说不那么自然。本项目仅使用依赖方向。

!!! danger "关键：learning-graph.json 中的边方向" 在 vis-network JSON 格式中，边从依赖概念指向先修概念 （即依赖方向）。

- 边 `{from: 5, to: 1}` 表示“生物多样性（5）依赖于生态学（1）”
- 它不表示“生态学引出生物多样性”（那是赋能方向）

**构建先修知识图：**
```python
prereqs = defaultdict(set)
for edge in data['edges']:
    prereqs[edge['from']].add(edge['to'])  # CORRECT: dependency direction
```

**绝不要使用** `prereqs[edge['to']].add(edge['from'])`——这会意外
转换为赋能方向，颠倒所有依赖关系，并在不知不觉中
生成无效的章节顺序。这个错误会浪费大量 token，
并且需要彻底重新设计。

验证以下内容：

• 图结构是有效的 DAG（没有循环依赖）
• 所有概念都有唯一 ID
• 依赖引用有效

1.2a 验证边方向（必须）

在设计任何章节之前，验证边方向是否正确：

1. 使用 prereqs[edge['from']].add(edge['to']) 构建先修知识图
2. 找出基础概念（prereqs 中没有条目的概念）
3. 验证基础概念是简单的入门术语（例如，“生态学”“能量”“系统”）
4. 如果高级概念被识别为基础概念，则方向错误——停止并修正

# Quick validation
foundational = [n for n in data['nodes'] if n['id'] not in prereqs]
print(f"Foundational ({len(foundational)}):")
for n in foundational:
    print(f"  {n['id']}: {n['label']}")
# These should be simple/introductory. If you see "Sustainability",
# "Climate Change", etc., the edge direction is inverted.

此检查通过前，不要继续设计章节。

1.3 阅读概念分类体系

阅读 /docs/learning-graph/concept-taxonomy.md（如果存在），以了解：

• 分类体系类别及其含义
• 概念在概念层面的分组方式
• 任何建议的顺序或进度安排

1.4 确定设计约束

分析数据，确定：

• 基础概念：没有依赖关系的概念（应较早出现）
• 高级概念：有许多依赖关系的概念（应较晚出现）
• 依赖链：较长的先修关系序列
• 概念集群：应保持在一起的相关概念组
• 终端概念：没有其他概念依赖的概念（可灵活安排）

1.4a 按概念读取概念影响分数（CIS）

learning-graph.json 中的每个节点都包含一个预先计算的 cis 字段 （由 learning-graph-generator v1.06+ 添加）——概念影响分数（Concept Impact Score）， 这是一种类似 PageRank 的递归重要性度量：CIS(x) = 1 + sum(CIS(d) for d in direct dependents of x)。与简单的依赖概念数量（仅计算直接依赖项）不同， CIS 能体现传递性影响：即使某个概念只有 1-2 个直接依赖项，如果这些依赖项 本身有许多依赖项，该概念的 CIS 仍可能很高。这就是为什么 chapter-content-generator 现在使用 CIS，而不是原始依赖项数量，来确定每个概念的字数和非文本元素目标。

# cis[concept_id] = the concept's pre-computed Concept Impact Score
cis = {n['id']: n.get('cis', 1) for n in data['nodes']}

# A concept with cis[cid] == 1 is a terminal concept (nothing transitively
# builds on it). A concept with a high cis[cid] is a foundational "hub"
# concept -- large amounts of the book's content ultimately rest on it,
# even if its direct dependents count is small.

**完整性检查：**如果每个概念都显示 cis == 1，则 learning-graph.json 早于 learning-graph-generator v1.06，继续操作前需要重新生成——不要退而 自行计算依赖项数量。

将此 cis 映射带入步骤 4——每个章节的“涵盖的概念”表中都会在每个概念名称旁列出该映射。

步骤 2：设计章节结构

遵循以下原则，设计最佳章节结构：

2.1 确定章节数

根据以下因素选择合适的章节数（6-20）：

• 概念总数：约 200 个概念通常需要 10-15 个章节
• 依赖复杂度：依赖关系越复杂，可能需要越多章节
• 分类分布：自然分组有助于确定章节边界
• 目标受众：入门课程可能需要较小的章节

指南：

• 至少 6 个章节（适用于非常精简的课程）
• 最佳范围：10-15 个章节
• 最多 20 个章节（适用于全面的研究生级内容）
• 平均每章安排 10-20 个概念

2.2 将概念分配到章节

设计章节分配方案，并满足以下要求：

关键要求：

1. 每个概念必须恰好出现在一个章节中（不得重复或遗漏）
2. 概念不得出现在其依赖项之前（遵循 DAG 结构）
3. 分布均衡（避免章节中的概念过多或过少）

优化目标：

• 尽可能将相关概念（同一分类类别）安排在一起
• 从基础主题到进阶主题，形成合乎逻辑的渐进顺序
• 平衡章节规模（避免少于 8 个或多于 25 个概念的章节）
• 将构成自然学习单元的概念编为一组
• 考虑认知负荷（在章节中混合不同难度的内容）

2.3 创建章节标题

为每个章节创建一个标题，要求：

• 使用标题式大小写格式
• 不超过 200 个字符（以便在一行内显示）
• 清楚描述章节的主要主题
• 使用标准教育术语
• 除非缩写广为人知，否则避免使用缩写

示例：

• “图论基础简介”
• “二叉树与树遍历算法”
• “图着色问题及其应用”
• “网络流优化进阶主题”

2.4 撰写章节摘要

为每个章节撰写一个单句摘要（20-40 个词），要求：

• 描述章节涵盖的内容
• 提及关键概念或主题
• 说明该章节在学习进程中的作用

步骤 3：向用户展示设计方案并征求批准

创建任何文件之前，请按以下格式向用户展示章节设计：

## Proposed Chapter Structure

I've designed a [number]-chapter structure for your textbook covering [total] concepts.

### Chapters:

1. **[Chapter Title]** ([X] concepts)
   [One sentence summary]

2. **[Chapter Title]** ([X] concepts)
   [One sentence summary]

[... continue for all chapters ...]

### Design Challenges & Solutions:

[Discuss any challenges encountered and how the design addresses them, such as:]
- **Challenge**: Concept X has 15 dependencies, making placement difficult
  **Solution**: Placed in Chapter 8 after all prerequisites are covered in Chapters 1-7

- **Challenge**: Taxonomy category Y contains 45 concepts
  **Solution**: Split across Chapters 3, 6, and 9 to maintain logical flow

[... other challenges ...]

### Statistics:

- Total chapters: [X]
- Average concepts per chapter: [X.X]
- Range: [min]-[max] concepts per chapter
- All [total] concepts covered: ✓
- All dependencies respected: ✓

3.1 征求用户批准

展示设计方案后，询问：

Do you approve this chapter structure? (y/n)

If no, please specify what changes you'd like:
- Different number of chapters?
- Specific concepts moved to different chapters?
- Chapter titles revised?
- Different grouping strategy?

3.2 处理用户反馈

如果用户回答“否”或要求修改：

• 留意用户的具体反馈
• 据此修改章节设计
• 重新展示更新后的结构
• 持续迭代，直到获得批准

如果用户回答“是”：

• 继续执行步骤 4，生成章节文件

步骤 4：生成章节目录结构和文件

用户批准设计方案后，创建章节结构：

4.1 创建 URL 路径名称

为每个章节创建便于 URL 使用的路径名称：

规则：

• 仅使用小写字母和连字符（不含其他字符）
• 移除所有特殊字符、标点符号和数字（编号前缀中的数字除外）
• 将空格替换为连字符
• 如有需要，使用缩写以缩短名称（少于 50 个字符）
• 名称应具有描述性，同时简洁明了

示例：

"Introduction to Graph Theory Fundamentals" → "intro-to-graph-theory"
"Binary Trees and Tree Traversal Algorithms" → "binary-trees-traversal"
"Advanced Topics in Network Flow Optimization" → "advanced-network-flow"

4.2 创建目录结构

创建以下目录结构：

/docs/chapters/
├── index.md
├── 01-[url-path-name]/
│   └── index.md
├── 02-[url-path-name]/
│   └── index.md
├── 03-[url-path-name]/
│   └── index.md
[... continue for all chapters ...]

实施：

mkdir -p /docs/chapters
mkdir -p /docs/chapters/01-[url-path-name]
mkdir -p /docs/chapters/02-[url-path-name]
# ... continue for all chapters

4.3 创建主章节索引

创建 /docs/chapters/index.md，内容如下：

# Chapters

This textbook is organized into [X] chapters covering [Y] concepts.

## Chapter Overview

1. [Chapter 1 Title](01-[url-path-name]/index.md) - [One sentence summary]
2. [Chapter 2 Title](02-[url-path-name]/index.md) - [One sentence summary]
[... continue for all chapters ...]

## How to Use This Textbook

[Add 2-3 sentences about how readers should progress through the chapters, noting that dependencies are respected and concepts build on each other]

---

**Note:** Each chapter includes a list of concepts covered. Make sure to complete prerequisites before moving to advanced chapters.

4.4 创建各章节的索引文件

为每个章节创建 /docs/chapters/[XX]-[url-path-name]/index.md，结构如下：

# [Chapter Title]

## Summary

[Write a 2-4 sentence summary of what the chapter covers, expanding on the one-sentence version from the design. Include:]
- Main topics and themes
- How this chapter fits in the learning progression
- What students will be able to do after completing this chapter

## Concepts Covered

This chapter covers the following [X] concepts from the learning graph:

| Concept | Concept Impact Score |
|---------|-----------------------|
| [Concept Name 1] | 187 |
| [Concept Name 2] | 1 |
| [Concept Name 3] | 42 |
[... continue for all concepts in this chapter, in pedagogical order ...]

## Prerequisites

[If this is not the first chapter, list which previous chapters should be completed first:]

This chapter builds on concepts from:
- [Chapter X: Chapter Title](../[XX]-[url-path-name]/index.md)
- [Chapter Y: Chapter Title](../[YY]-[url-path-name]/index.md)

[If this is the first chapter or has no prerequisites within the book:]

This chapter assumes only the prerequisites listed in the [course description](../../course-description.md).

---

TODO: Generate Chapter Content

重要格式说明：

• Markdown 列表前必须始终留一个空行（MkDocs 要求）
• 内部链接使用相对路径
• 概念名称必须与 learning-graph.json 中的名称完全一致
• “涵盖的概念”应使用包含 Concept 和 Concept Impact Score 列的 Markdown 表格（而非编号列表），每个概念占一行，顺序与本章其他部分采用的教学顺序一致，并使用步骤 1.4a 中读取的 cis 映射。表格前必须始终留一个空行（MkDocs 要求）。
• 保持标题层级一致（# → ## → ###）

4.5 更新 MkDocs 导航

创建所有章节文件后，将这些章节添加到 mkdocs.yml 的 Chapters: 部分。遵循规范的导航编辑规则（先读后写、串行编辑、仅修改所属部分、章节标签仅使用编号），详见 $BK_HOME/skills/book-installer/references/mkdocs-nav-editing.md。

  - Chapters:
    - List of Chapters: chapters/index.md
    - 1. [Chapter 1 Title]: chapters/01-[url-path-name]/index.md
    - 2. [Chapter 2 Title]: chapters/02-[url-path-name]/index.md
    # ... continue for all chapters

4.6 确认完成

创建完所有文件后，告知用户。务必原样包含以下吉祥物建议——不得省略，也不得根据是否已有吉祥物而决定是否包含：

✅ Chapter structure generated successfully!

Created:
- chapters/index.md (main chapter overview)
- [X] chapter directories with index files
- Updated mkdocs.yml navigation

Strong recommendation: create a learning mascot before generating any
chapter content. Run the `book-installer` skill's learning-mascot guide (or
just ask to "add a learning mascot") now. The `chapter-content-generator`
skill places mascot admonitions as it writes each chapter, and retrofitting
a mascot into chapters that already exist is far more expensive than
designing one first.

Next steps:
1. Create a learning mascot (strongly recommended, see above) — run `book-installer`, then the learning mascot guide
2. Review the chapter structure: `mkdocs serve`
3. Navigate to the Chapters section to see all chapter outlines
4. Use the chapter content generation skill (when ready) to populate each chapter
5. Each chapter index.md has "TODO: Generate Chapter Content" as a placeholder

Statistics:
- Total chapters: [X]
- Total concepts assigned: [Y]
- All dependencies respected: ✓

设计原则

依赖关系管理

重要：章节顺序必须遵循 DAG 结构：

• 如果概念 B 依赖概念 A，则 A 必须安排在比 B 更早（或与 B 相同）的章节中
• 最终确定章节分配前，检查所有依赖关系
• 使用拓扑排序验证顺序是否有效

向用户展示前必须进行验证：

运行此项严格检查，并确保违规项为 零，然后再继续步骤 3：

# Build prereqs: from=dependent, to=prerequisite (NEVER invert this)
prereqs = defaultdict(set)
for e in data['edges']:
    prereqs[e['from']].add(e['to'])

# Map each concept to its chapter index
chapter_map = {}
for i, (title, cids) in enumerate(chapters):
    for cid in cids:
        chapter_map[cid] = i

# Check: every prerequisite must be in same or earlier chapter
violations = []
for i, (title, cids) in enumerate(chapters):
    for cid in cids:
        for dep in prereqs.get(cid, set()):
            if dep in chapter_map and chapter_map[dep] > i:
                violations.append(f"{nodes[cid]} ch{i+1} needs {nodes[dep]} ch{chapter_map[dep]+1}")

assert len(violations) == 0, f"{len(violations)} dependency violations found"

不得向用户展示存在任何违规项的章节设计。 请先通过调整概念所属章节或重新排序章节来修正所有违规项。

内容平衡

力求章节规模均衡：

• 最佳：每章 12–18 个概念
• 可接受：每章 8–25 个概念
• 避免：少于 8 个概念（内容太少）或超过 25 个概念（内容太密集）

如果某章内容过多，可考虑将其拆分为两个章节。 如果某章内容过少，可考虑将其与相关章节合并。

教学流程

按照以下方式组织章节，帮助学习者掌握内容：

• 前期章节：基础概念、简单想法，逐步建立信心
• 中期章节：核心内容、逐渐增加的复杂度、实际应用
• 后期章节：高级主题、整合与综合

在每章中，按以下顺序排列概念：

1. 从基础到高级（依据依赖关系）
2. 从简单到复杂（依据认知负荷）
3. 从抽象到具体（引入新想法时）

认知负荷

考虑学生的认知负荷：

• 不要让前期章节负担过重（学生仍在建立背景知识）
• 尽可能在章节中穿插不同难度的内容
• 将相关概念归为一组，以减少认知切换
• 确保提供充分的学习支架（先修概念应安排在更早的章节中）

常见挑战与解决方案

挑战：分类类别过大

问题：单个分类类别包含 40+ 个概念。

解决方案：

• 将该类别拆分到多个章节中
• 使用不同的方面或子主题作为章节边界
• 与其他类别交错编排，以保持学习者的兴趣

挑战：依赖链过长

问题：概念 Z 依赖 Y，Y 依赖 X，X 又依赖 W……（深入 5+ 层）。

解决方案：

• 将依赖链分散到多个章节中
• 视情况在多个章节中安排较早的依赖项
• 考虑为深层依赖链的根概念创建专门的“基础知识”章节

挑战：终端概念

问题：有些概念没有依赖它们的概念（没有后续内容以它们为基础）。

解决方案：

• 将终端概念放在相关章节的末尾
• 将终端概念归入“补充主题”或“专题”章节
• 考虑这些概念是否确有必要（但未经用户批准，不要删除）

挑战：拆分概念簇

问题：一个自然形成的概念簇（例如，5 种树遍历算法）对于单个章节来说过于庞大，但拆分又显得不妥。

解决方案：

• 拆分为“第 1 部分”和“第 2 部分”两个章节，并明确说明内容的延续关系
• 利用依赖关系找到自然的拆分点
• 按复杂度（基础与进阶）或应用领域分组

挑战：分布不均

问题：依赖结构导致第 2 章有 30 个概念，而第 7 章只有 8 个概念。

解决方案：

• 将较大的章节拆分为两个章节
• 将较小的章节与相邻章节合并
• 重新审视章节边界，以寻找更均衡的划分
• 调整章节总数

验证清单

确定章节结构前，请确认：

• learning-graph.json 中的所有概念都恰好分配到一个章节
• 每个概念都不会出现在其任何依赖项之前
• 章节规模在可接受范围内（8-25 个概念）
• 章节标题采用标题式大小写，且不超过 200 个字符
• URL 路径名称仅包含小写字母和连字符
• 所有文件均遵循指定的目录结构
• MkDocs 导航已正确更新
• 所有 Markdown 文件格式正确（例如，列表前有空行）
• 每个章节的 index.md 都包含所有必需部分
• “涵盖的概念”是一个包含 Concept 和 Concept Impact Score 列的表格（而不是编号列表）
• 用户已批准章节设计

使用示例

用户请求： “为我的图论教材创建章节”

Skill 工作流：

1. 阅读 course-description.md、learning-graph.json 和 concept-taxonomy.md
2. 分析 200 个概念及其依赖关系
3. 设计 12 个章节，并均衡分配内容
4. 向用户展示章节大纲：
   • 第 1 章：简介（15 个概念）
   • 第 2 章：图的表示（18 个概念）
   • ……等
5. 获取用户批准（y/n）
6. 创建目录结构和所有 index.md 文件
7. 更新 mkdocs.yml 导航
8. 确认完成

备注

• 此 skill 只创建章节的结构和大纲
• 它不会生成实际章节内容（这需要单独的 skill）
• “TODO: Generate Chapter Content”标记表示之后应在此处添加内容
• 始终保留每个章节的 index.md 中的概念列表，以供内容生成 skills 使用
• 每个概念的 Concept Impact Score 列并非装饰：chapter-content-generator 会读取该列，为每个概念设定目标字数和非文本元素要求（参见 chapter-content-generator/SKILL.md 中的“Elaboration Budget”）
• 务必在用户继续生成章节内容之前，强烈建议其设计一个学习吉祥物（第 4.6 步）——提前设计的吉祥物会在撰写过程中放入每个章节；事后再添加，则意味着要对所有已生成的章节进行改造