chapter-content-generator

章节内容生成器

版本： 1.11

版本 1.11 功能：

• 精准且以目标为先的 MicroSim 规范——现在，每个规范块都会说明学习者必须学会并证明什么，以及模拟需要包含的完整内容，而不再说明如何构建模拟。新的结构化字段（Bloom Level、Bloom Verb、Learning Objective、Evidence of Mastery、Misconceptions、Instructional Rationale、Content、Provenance、Rules、Learner Activity、Feedback、Starting State、Chapter Anchors）和自检规则已在新的 references/microsim-specification-rules.md 中定义。布局、像素尺寸、颜色、控件位置和库调用均交由 microsim-generator 处理。这些规则源自一次包含 112 个 MicroSim 的批量运行；在运行中，Agent 报告缺少 450 项规范细节，且 49% 的模拟不得不偏离其规范。
• 批处理工具可解析的 Bloom 字段——**Bloom Level:** 和 **Bloom Verb:** 是分开的标题行。此前的内联格式 Learning objective (Bloom level: X; verb: Y): 无法解析，导致工具将 112 个模拟中的 109 个标记为“Create”。
• 修正 content-element-types.md 中不可能或互相冲突的指令——Bloom 列表只列出六个层级中的四个；Mermaid 边被要求可点击（Mermaid 无法实现）；图表示例要求在嵌入式页面内使用鼠标滚轮缩放；示例将 iframe 占位符固定为 500 px；未闭合的代码块吞掉了 MicroSim 示例。

版本 1.10 功能：

• 吉祥物放置规则统一维护——步骤 2.4 的原则 4 不再包含第 1 章自我介绍模式或吉祥物出现频次的副本。两者现在都统一维护在规范文件 $BK_HOME/skills/book-installer/references/mascot-placement-rules.md 中，库中的每项技能都会引用该文件，而不是重复表述。这解决了两个不同放置表中每章数量相互冲突的问题。
• 在 frontmatter 中跟踪版本——版本存储为 metadata.ibook.version，位于 metadata: 下，而不是会被严格打包验证拒绝的独立 version: 键。

版本 1.09 功能：

• 重大变更：由 CIS 驱动的展开预算——每个概念的字数和非文本元素要求不再采用全章统一目标（“3000-5000 字，4-6 个非文本元素”）。现在，每个概念都会根据其概念影响分数（CIS）计算自己的字数范围和非文本元素最低要求；该分数读取自 book-chapter-generator v1.0.0+ 写入每章“Concepts Covered”表格的 CIS Score 列。基础性强、影响大的概念会得到充分展开（示例演算、图表）；范围窄、影响小的概念则采用高效简短的讲解。见下文“展开预算”（步骤 2.3b）。需要使用 book-chapter-generator v1.0.0+（表格格式）生成章节，并需要 learning-graph-generator v1.06+ 生成的 learning-graph.json（包含 node.cis）。

版本 0.09 功能：

• 第 1 章中吉祥物的自我介绍——如果项目的 CONTENT-GENERATION-GUIDE.md 定义了教学吉祥物，那么第 1 章中吉祥物第一次出现时必须进行自我介绍，点名吉祥物，并列举它将在全书中扮演的每种姿势角色。该模式在整个库中统一定义于 mascot-placement-rules.md（见步骤 2.4，原则 4） 版本 0.07 功能：
• 教学脚手架 - 先定义再展示的规则确保先解释术语，再在图表中使用这些术语；先解释代码参数，再提供代码示例；表格用于巩固概念，而不是引入概念（参见第 2.4 步，原则 3）
• 顺序执行 - 一次生成一章内容，以避免过度消耗令牌。用户可以使用短语 "use parallel execution" 覆盖此设置，但技能会提醒用户，这将额外消耗 38% 的令牌
• 边的方向验证 - 强制检查，以防止依赖关系反向错误（参见第 1.3a 步）

何时使用此技能

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

• book-chapter-generator 技能已创建章节目录，其中包含 index.md 文件
• 章节 index.md 包含：标题、摘要和涵盖的概念列表
• 需要生成详细的章节内容
• 内容需要适配特定阅读水平（初中、高中、大学、研究生）
• 需要丰富的非文本元素（图表、MicroSims、信息图）

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

• 尚未创建章节结构（请先使用 book-chapter-generator）
• 内容已存在，只需编辑（直接使用 Edit 工具）
• 生成其他类型的内容（提示词、术语表等）
• 用户的令牌即将用尽（5 小时窗口内已使用超过 95%）

执行模式

顺序模式（所有用例的默认模式）

• 由于并行模式开销较大，始终一次只处理一章
• 等待一章完全完成并记录会话后，再开始下一章
• 每完成一章时，明确告知用户

并行模式（仅在用户请求时使用）

仅当用户明确请求并行执行时，才应使用并行模式。 提醒用户，并行执行会产生显著的令牌开销。

单章模式

适用于：

• 大纲修订后更新单章内容
• 批量生成前测试内容格式

工作流

阶段 1：设置（顺序）

此阶段仅运行一次，在生成任何内容之前读取所有 Agent 都需要的共享上下文。

步骤 1.1：记录日志用的开始时间

date "+%Y-%m-%d %H:%M:%S" >>logs/ch-{NN}-content-generation.md

其中 {NN} 是两位数的章节编号，不足两位时前面补零。

记录会话报告的开始时间。

步骤 1.2：指示技能正在运行

通知用户："Chapter Content Generator Skill v1.11 running in [parallel/sequential] mode."

步骤 1.3：读取共享上下文

为所有 Agent 读取并缓存以下文件：

1. 课程说明（docs/course-description.md）

   • 提取目标受众和阅读水平
   • 在项目的 CONTENT-GENERATION-GUIDE.md 中记录课程目标和语气指南
   • 在项目的 CONTENT-GENERATION-GUIDE.md 中识别吉祥物或叙事元素（例如微积分中的 Delta）

2. 学习图谱（docs/learning-graph/learning-graph.json 和/或 learning-graph.csv）

   • 加载带有依赖关系的概念列表
   • 理解概念关系，以确定教学顺序
   • 计算 cis_max = 本书所有节点中的最大 cis 值（max(n.get('cis', 1) for n in data['nodes'])）。在本次会话的所有章节中都复用这一个数值——展开预算的归一化（步骤 2.3b）始终是全局的（以整本书为基准），而不是针对单个章节；因为概念的重要性是对全书而言的，而非仅针对某个章节。如果所有节点的 cis 都为 1，则说明学习图谱早于 learning-graph-generator v1.06；请向用户报告这一情况，并建议在继续之前重新生成 learning-graph.json，而不是悄悄退回到简单的字数统计。

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

   某些学习管理系统使用**启用图**，边的方向相反（从先决概念指向被启用的概念）。对某些教师来说，这种方向更直观，但不太适合图算法。本项目仅使用依赖方向。
   

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

   - 边 `{from: 5, to: 1}` 表示“生物多样性（5）依赖生态学（1）”
   - 它**不**表示“生态学引出生物多样性”（那是启用方向）
   
   **构建先决条件映射时：**
   ```python
   # 正确：依赖方向——from=依赖概念，to=先决概念
   prereqs[edge['from']].add(edge['to'])
   ```
   
   **绝不要使用：**
   ```python
   # 错误：意外转换为启用方向，反转了所有依赖关系
   prereqs[edge['to']].add(edge['from'])
   ```
   
   如果方向弄错，会产生数百条错误违规，并在无效的章节设计上浪费大量 Token。继续之前务必使用步骤 1.3a 进行验证。
   

3. 术语表（docs/glossary.md）

   • 如果存在术语定义，则加载以确保术语一致
   • 在大多数情况下，术语表会在内容生成后创建
   • 记录哪些概念已有术语表条目

4. 项目 CONTENT-GENERATION-GUIDE.md（如果存在）

   • 加载项目专属指南
   • 记录任何阅读水平、吉祥物规范、语气要求或特殊格式要求

5. 章节列表（扫描 docs/chapters/ 目录）

   • 列出所有章节目录
   • 确定哪些章节需要生成内容（有大纲但没有正文）

步骤 1.3a：验证边的方向（MANDATORY）

使用任何依赖数据之前，请先验证边的方向是否正确。此步骤可防止章节生成中最常见、代价最高的错误——依赖关系映射反转，导致章节顺序悄无声息地出错。

验证流程：

1. 找出基础概念——CSV 中 Dependencies 为空，或 JSON 中前置条件数量为零的概念
2. 使用 prereqs[edge['from']].add(edge['to']) 构建前置条件映射
3. 检查基础概念在 prereqs 映射中是否没有条目

import json
from collections import defaultdict

with open('docs/learning-graph/learning-graph.json') as f:
    data = json.load(f)

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

# Find concepts with zero prerequisites (foundational)
all_ids = {n['id'] for n in data['nodes']}
foundational = all_ids - set(prereqs.keys())

print(f"Foundational concepts (no prerequisites): {len(foundational)}")
for fid in sorted(foundational):
    node = next(n for n in data['nodes'] if n['id'] == fid)
    print(f"  {fid}: {node['label']}")

# SANITY CHECK: foundational concepts should be simple/introductory
# If you see advanced concepts here, the edge direction is WRONG

通过标准：

• 基础概念应当是简单的入门术语（例如，“生态学”“能量”“系统”）
• 如果高级概念被列为基础概念（例如，“可持续性”“气候变化”“临界点”），则边的方向已反转——请停止并在继续之前修正
• 基础概念的数量应较少（对于包含 200-400 个概念的图，通常为 3-10 个）
• 如果看到 50 个以上的“基础”概念，方向很可能已反转

**如果验证失败：**请勿继续生成内容。向用户报告问题，并建议使用正确的边方向重新运行。

步骤 1.3b：验证章节依赖顺序（MANDATORY）

验证边的方向后，请确认每章所涉及概念的前置条件都已在较早的章节中涵盖。这可确保内容引用先前材料时不会出现前向引用。

# Build chapter_map: concept_id -> chapter_index
chapter_map = {}
for i, (title, cids) in enumerate(chapters):
    for cid in cids:
        chapter_map[cid] = i

# Check: for every concept, all prerequisites 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]['label']}(ch{i+1}) needs "
                    f"{nodes[dep]['label']}(ch{chapter_map[dep]+1})"
                )

if violations:
    print(f"DEPENDENCY VIOLATIONS: {len(violations)}")
    for v in violations:
        print(v)
    print("\nDo NOT generate content until all violations are resolved.")
else:
    print("All dependencies respected. Safe to generate content.")

**通过标准：**零处违规。如果存在任何违规，必须先修正章节结构，再开始生成内容。

步骤 1.4：确定阅读水平

从课程描述中提取年级阅读水平：

阅读水平指示词：

• “grade-school”、“grade school”、“grades 1-6”、“elementary school” → 小学
• “junior-high”、“junior high”、“grades 7-9”、“middle school” → 初中
• “senior-high”、“senior high”、“grades 10-12”、“high school” → 高中
• “college”、“undergraduate”、“bachelor” → 大学
• “graduate”、“master”、“masters”、“master's”、“PhD”、“doctoral” → 研究生

阅读水平特点：

• **小学（1-6 年级）：**句子很简短（10-14 个词），使用常见词汇、具体示例和频繁的视觉辅助
• **初中（7-9 年级）：**句子简短（12-18 个词），使用常见词汇、具体示例和频繁的视觉辅助
• **高中（10-12 年级）：**句子复杂度适中（15-22 个词），使用技术词汇并加以定义，兼顾具体与抽象内容
• **大学：**学术风格（18-25 个词），使用专业术语、案例研究和研究背景
• **研究生：**行文严谨（20-30 个词以上），使用完整的专业术语，深入探讨理论并引用研究文献

如果未指定，默认设为 10 年级（高中）。

步骤 1.5：规划章节批次（并行模式）

将章节分成多个批次以便并行处理：

批次大小指南：

• 4-8 章：2 个 Agent（每个处理 2-4 章）
• 9-15 章：3-4 个 Agent（每个处理 3-4 章）
• 16-24 章：4-6 个 Agent（每个处理 4-5 章）
• 25 章以上：5-6 个 Agent（每个处理 5-6 章）

23 章示例：

Agent 1: Chapters 1-4 (Foundations)
Agent 2: Chapters 5-8 (Core Concepts Part 1)
Agent 3: Chapters 9-12 (Core Concepts Part 2)
Agent 4: Chapters 13-16 (Applications Part 1)
Agent 5: Chapters 17-20 (Applications Part 2)
Agent 6: Chapters 21-23 (Advanced Topics)

阶段 2：内容生成（并行或顺序）

并行执行

使用 Task 工具同时启动多个 Task Agent。每个 Agent 接收：

1. 共享上下文（课程信息、阅读水平、术语表、语气指南）
2. 指定章节（具体的章节目录）
3. 内容格式模板（本技能的标准格式）
4. 输出说明（将内容写入各章节的 index.md）

Agent 提示词模板：

You are generating educational content for an intelligent textbook. Generate
detailed chapter content for the following chapters.

COURSE CONTEXT:
- Course: [course name]
- Target audience: [audience]
- Reading level: [level] - [characteristics]
- Tone: [tone guidelines from course description or CONTENT-GENERATION-GUIDE.md]

ELABORATION BUDGET (per concept -- computed in Step 2.3b, see below):
[Insert the per-chapter elaboration budget table here: Concept | CIS | Tier | Target Words | Required Elements]

CONTENT GUIDELINES:
- Follow the per-concept word count and required-element targets in the
  Elaboration Budget table above -- do NOT apply a flat word count to every
  concept regardless of importance
- No more than 4 paragraphs of pure text without a non-text element
- Use diverse element types (lists, tables, diagrams, MicroSims)
- Present concepts in pedagogical order (simple to complex)
- Include LaTeX equations where appropriate (backslash delimiters: `\( \)` for inline, `\[ \]` for display)

SCAFFOLDING (CRITICAL):
- Define every technical term in prose BEFORE it appears in a diagram, code block, or table
- Before code examples, explain what the code does and what key parameters mean in plain language
- Tables must summarize concepts already explained — never introduce new concepts via tables
- Add bridging sentences before complex elements ("Before we examine this diagram, let's define...")

MASCOT (if a mascot is defined in CONTENT-GENERATION-GUIDE.md):
- The pose-by-pose rules, per-chapter counts, and hard limits are defined in the
  project's CONTENT-GENERATION-GUIDE.md (rendered from the canonical
  $BK_HOME/skills/book-installer/references/mascot-placement-rules.md). Read that
  section before placing any mascot admonition and follow it exactly.
- If you are processing CHAPTER 1, the FIRST mascot admonition must be the
  one-time self-introduction described in those rules. See Step 2.4 principle 4.
- For chapters 2 and beyond, open with a normal mascot-welcome admonition that gets straight into chapter-specific content. Do NOT repeat the self-introduction.

NON-TEXT ELEMENTS:
- Markdown lists and tables: embed directly (blank line before)
- Diagrams, MicroSims, infographics: use <details markdown="1"> blocks with #### Diagram: header

SPECIFICATIONS (read references/microsim-specification-rules.md first):
- Use the block template exactly: sim-id, Library, Status, Bloom Level, Bloom Verb and
  Learning Objective as separate bold header lines
- State WHAT the learner must learn and prove: Evidence of Mastery, Misconceptions,
  Instructional Rationale, complete Content (every item written out), Provenance, Rules, Learner Activity,
  Feedback, Starting State, Chapter Anchors
- Do NOT specify HOW to build it: no pixel sizes, layout, control placement, colors,
  breakpoints, library calls or "Implementation:" lines
- Run the self-check in that file on every specification before writing the chapter

CHAPTERS TO PROCESS:
[List specific chapter directories with full paths]

FOR EACH CHAPTER:
1. Read the chapter index.md file to get title, summary, and the "Concepts
   Covered" table (Concept | CIS Score)
2. Compute the Elaboration Budget for this chapter's concepts (Step 2.3b) --
   the chapter's total word count is the SUM of each concept's target, not
   a flat chapter-wide number. Chapters with more high-CIS concepts will
   naturally run longer than chapters of mostly narrow, low-CIS concepts --
   this is expected and correct, not an error to normalize away.
3. Generate content following each concept's individual word-count range
   and required-element targets from the budget table
4. Verify all concepts from "Concepts Covered" are addressed AND that each
   one's actual word count and element mix roughly matches its budget tier
5. Write the content to docs/chapters/[chapter-dir]/index.md

METADATA FORMAT (add to top of each file). Put double quotes around every value that contains a
colon, and always around title, description and date. An unquoted value with a colon is invalid YAML:
mkdocs then prints the frontmatter at the top of the page and drops its metadata, without failing
`mkdocs build --strict`. Escape any inner double quote as \".
---
title: "[Chapter Title]"
description: "[Short description]"
generated_by: claude skill chapter-content-generator
date: "[YYYY-MM-DD HH:MM:SS]"
version: 1.11
---

REPORT when done:
- Chapter name
- Word count (and how it compares to the sum of the concepts' budgeted targets)
- Non-text elements (lists, tables, admonitions, diagrams, MicroSims)
- Concepts covered (X of Y), with any concept whose actual length fell outside its budget's tolerance flagged

顺序执行

对于顺序模式或少于 4 章的情况，请按照下方的逐章步骤一次处理一章。

阶段 2 步骤（逐章——供 Agent 或顺序模式使用）

步骤 2.1：确认章节文件存在

确认章节文件存在且包含必需元素。

预期输入格式：

• 章节名称："01-intro-to-itil-and-config-mgmt" 或 "Chapter 1"
• 完整路径："/docs/chapters/01-intro-to-itil-and-config-mgmt/index.md"
• 相对路径："chapters/01-intro-to-itil-and-config-mgmt/index.md"

章节目录结构：

/docs/chapters/NN-lowercase-name/index.md

其中：

• NN = 两位数章节编号，前面补零（例如："01"、"07"、"12"）
• lowercase-name = 适用于 URL 的小写名称，使用连字符分隔，不含空格

启动并行 Agent： 仅当用户请求并行执行时才执行此操作。

在同一条消息中多次调用 Task 工具，以并行运行 Agent：

[Call Task tool for Agent 1: Chapters 1-4]
[Call Task tool for Agent 2: Chapters 5-8]
[Call Task tool for Agent 3: Chapters 9-12]
[Call Task tool for Agent 4: Chapters 13-16]
[Call Task tool for Agent 5: Chapters 17-20]
[Call Task tool for Agent 6: Chapters 21-23]

重要： 所有 Task 工具调用都必须放在同一条消息中，才能并行执行。如果分开发送，它们将按顺序执行。

步骤 2.2：确认章节大纲

打开章节文件并检查是否包含必需元素。

必需元素：

1. 标题，位于一级标题中（# Title）
2. 摘要，位于二级标题中（## Summary）
3. 涵盖的概念，位于二级标题中（## Concepts Covered），并包含 Concept | CIS Score Markdown 表格（由 book-chapter-generator v1.0.0+ 编写；参见步骤 1.4a）

操作：

1. 解析章节 index.md 文件
2. 提取：
   • 章节标题
   • 摘要文本
   • Concepts Covered 表格：按给定行顺序排列的 (concept_name, cis_score) 对列表（此顺序即教学顺序）
3. 如果缺少任何元素，则跳过该章节或请用户提供内容
4. 如果 "Concepts Covered" 是不含 CIS 分数的编号列表（由 book-chapter-generator v1.0.0 之前版本生成的章节），不要编造 CIS 值——向用户报告此情况，并建议使用当前版本的 book-chapter-generator 重新生成章节脚手架
5. 保存概念/CIS 列表，以用于细化预算（步骤 2.3b）以及步骤 2.5 中的验证

步骤 2.3：添加元数据

将元数据添加到 index 文件顶部：

---
title: "Chapter Title"
description: "Short description of title"
generated_by: claude skill chapter-content-generator
date: "YYYY-MM-DD HH:MM:SS"
version: 1.11
---

Frontmatter 规则： 对包含冒号的每个 frontmatter 值加上双引号，并将内部双引号转义为 \"。始终为 title、description 和 date 加引号：标题和描述中通常包含冒号（"运动学：手在哪里？"），而时间戳总是包含冒号。未加引号的 description: A chapter on X: how Y works 是无效的 YAML。mkdocs 随后会将 frontmatter 打印在页面顶部并丢弃其元数据，而 mkdocs build --strict 不会报错，因此页面会显示异常，却没有任何错误提示。包含冒号的键（og:image）无需加引号；只需为值加引号。写入章节后，检查 frontmatter 是否能正确解析：

python3 -c "import sys,yaml; t=open(sys.argv[1]).read(); d=yaml.safe_load(t.split('---')[1]); print(d['title'], '|', d['date'])" docs/chapters/NN-name/index.md

此时，date 值将是字符串，而非 YAML 时间戳，这正是下游工具所期望的格式。

步骤 2.3b：计算详述预算（由 CIS 驱动）

此步骤取代旧版的固定指令“每章 3000-5000 个词、4-6 个非文本元素”。 内容长度和丰富度不再按章节设定，而是按概念设定，由每个概念的概念影响分数（CIS）驱动。这样一来，许多其他概念会间接依赖的概念能够得到充分详述（包括实例演示、图表），而影响较小的狭窄概念则可以简洁高效地讲解。这与人类领域专家自然会在基础思想上投入更多解释精力，而在边缘词汇上投入较少的方式一致。

1. 计算每个概念的详述分数 E(c)：

import math

# cis_max was computed once in Step 1.3 across the WHOLE book -- reuse it
# here. Normalization is always GLOBAL, never local to this chapter: a
# concept's importance is a book-wide claim. (An earlier, chapter-local
# normalization was tried and rejected -- it produced a degenerate result
# where a chapter's own single most-important concept always looked like
# the book's most important concept, even when it wasn't.)
def elaboration_score(cis, cis_max):
    if cis_max <= 1:
        return 0.0
    return math.log(cis + 1) / math.log(cis_max + 1)

E(c) 的取值范围为 [0, 1]。使用 log(cis+1) 而非原始 CIS 很重要：CIS 呈重尾分布（在典型的约 200 个概念的图中，约一半概念的 CIS 都处于最低值 1），因此线性尺度或总体百分位尺度会让整个较低的一半概念彼此无法区分，而一两个枢纽概念则会主导整个范围。开发过程中发现并修复了这一确切问题——如需了解详情，请参阅论文“Predicting Concept Content Size”（定义 4）。

2. 根据 E(c) 分配层级：

层级	E(c) 范围	目标词数	必需元素
A（完整讲解）	>= 0.5	500-750	>=1 个实例演示 AND >=1 个图示/图表/表格/MicroSim
B（标准）	0.2 <= E(c) < 0.5	250-400	>=1 个实例演示
C（简要）	< 0.2	120-200	清晰的定义；可选短例子，无需强制提供

这些分界点和范围是经过验证的起始值（开发过程中根据 CIS 特征相反的两个真实章节——一个基础性章节和一个专业性章节——进行核验），并非不可更改的常数。如果某一章节的层级分布与其实际内容不符（例如，所有概念都落在同一层级），请在生成内容前检查层级划分是否合理，但不要悄悄恢复为固定的章节词数。

3. 编制本章的详述预算表（每个概念占一行，按“涵盖的概念”中的教学顺序排列）：

概念	CIS	E(c)	层级	目标词数	必需元素
[概念 1]	187	0.83	A	500-750	实例演示 + 图示
[概念 2]	4	0.22	B	250-400	实例演示
[概念 3]	1	0.00	C	120-200	定义

本章的总词数是各概念目标词数之和，而不是单独设定的。包含多个 A 层级概念的章节自然会比大多由 C 层级概念组成的章节更长；这种差异正是预期效果，而不是需要消除的问题（见下文“常见误区”）。

4. 使用此表指导步骤 2.4。 生成正文时，请遵循每个概念对应的预算行，而不是将章节总长度平均分配给所有概念。

步骤 2.4：生成详细的章节内容

根据章节大纲、概念列表和阅读水平，生成全面的教学内容。

内容生成原则：

1. 适配阅读水平：

   • 使用恰当的句子复杂度、词汇和讲解风格
   • 具体指南请参阅 references/reading-levels.md

2. 概念排序：

   • 先介绍简单概念，再介绍复杂概念
   • 遵循自然的教学进度
   • 不必严格遵循“涵盖的概念”列表中的顺序
   • 以先前讲解过的概念为基础

3. 搭建脚手架——先定义，再展示：

   • 先介绍术语，再展示视觉内容： 每个图示、代码示例或表格之前，都必须先用文字定义其中包含的所有技术术语。如果图示中显示了“向量”和“嵌入”，就必须在图示前紧接着的段落中解释这些术语。读者不应在非文本元素中第一次遇到某个术语。
   • 代码前先写衔接句： 每个代码示例之前，都要用通俗易懂的句子说明代码的作用及其关键参数的含义。绝不能先展示代码、把解释留到后面的章节——必须先解释，再展示代码。例如：“temperature 参数控制随机性（0 = 确定性，1 = 富有创造性）。max_tokens 参数设置响应的最大长度。”
   • 先讲解，再用表格强化： 表格用于总结或比较读者已经理解的信息。绝不能用表格引入新概念。正确顺序是：（1）先用文字解释概念，（2）再用表格整理或比较这些概念。如果读者需要从表格单元格中反向推断含义，就说明使用表格的时机还不成熟。
   • 提前说明接下来的内容： 在复杂元素之前添加导航提示，例如：“在查看这张图之前，我们先定义两个关键术语。”或“下表总结了我们刚才讨论的三种方法。”这样的衔接句能将参考文档转变为循序渐进的学习体验。

4. 吉祥物的摆放（定义了吉祥物时）：

   每种姿势承担什么教学任务、每章应使用多少个、具体数量限制，以及仅适用于第 1 章的一次性自我介绍模式，均在本库所有技能共用的单个文件中定义：

   $BK_HOME/skills/book-installer/references/mascot-placement-rules.md
   

   每本书的 CONTENT-GENERATION-GUIDE.md 中都包含这些规则的渲染副本，位于 `` 标记之间。放置任何吉祥物提示框前，请先阅读该部分，并严格遵循其中的要求。

   不要在此重述这些规则，也不要自行发明项目未定义的姿势及其用途。如果需要更改规则，请修改规范文件，以便所有技能同时采用该更改。

   有两点值得重申，因为它们最容易被遗漏：

   • 第 1 章的自我介绍仅在吉祥物首次出现时进行一次。第 2 章及后续章节以常规的 mascot-welcome 开篇，直接进入本章的具体内容。
   • 吉祥物图片必须使用 Markdown 图片语法放在提示框的正文中——![alt](path){ class="mascot-admonition-img" }——绝不能使用原始 HTML <img> 标签。

5. 非文本元素：

   • 对每个概念，请遵循“展开预算”（第 2.3b 步）中的“必需元素”列——A 级概念需要一个完整示例和图示／图表／表格／MicroSim；B 级需要一个完整示例；C 级只需清晰的定义。这些是针对每个概念的最低要求，而不是不考虑概念构成、单独为整章设定的元素数量目标。
   • 目标：纯文本内容不超过 4 段，中间应包含非文本元素。
   • 使用多种元素类型（不要重复使用同一种类型）。
   • 特别重视交互式元素（信息图、MicroSim）。
   • 适用时，使用 LaTeX 并通过反斜杠定界符渲染公式：
     • 行内数学公式：句子中的公式使用 \( equation \)
     • 独立数学公式：单独成行的公式使用 \[ equation \]
   • 不要使用美元符号定界符（$ 或 $$）。
   • 有关公式的正确格式，请参阅 references 中的 math-equations.md 文件。

非文本元素类型：

直接嵌入 Markdown 的元素（无需 <details markdown="1"> 块）：

1. Markdown 列表（项目符号或编号）——列表前始终留空行
2. Markdown 表格——表格前始终留空行

需要图示标题和 <details markdown="1"> 规范块的元素： 3. 图表/绘图 - 系统架构、关系、数据流 4. 交互式信息图 - 可点击的概念图、渐进式信息展示、悬停时在工具提示中显示与术语表一致的定义 5. MicroSim - 带有交互控件的 p5.js 仿真 6. 图表 - 展示定量数据的条形图、折线图、饼图 7. 时间线 - 历史演进、顺序事件 8. 地图 - 地理分布及移动箭头 9. 工作流图 - 带悬停文本的业务流程 10. 图数据模型 - 使用 vis-network 表示实体关系 11. 因果回路图 - 用于系统思维和因果关系解释

MicroSim 复用检查（编写任何新的交互元素规范之前必须完成）：

dmccreary/* 教材中已有数百个 MicroSim，并已编入 search-microsims 目录的索引。在为 MicroSim、工作流图、图表、时间线、地图或信息图编写 SPECIFICATION 块之前，请检查是否已有讲解相同概念的托管 MicroSim；如果有，请通过 iframe 嵌入，而不是指定一个必须从头生成和调试的新 MicroSim。

1. 可用性检查（每个会话检查一次）： 运行 test -x /Users/dan/Documents/ws/search-microsims/.venv-embeddings/bin/python && test -f /Users/dan/Documents/ws/search-microsims/data/microsims-embeddings.json && echo AVAILABLE 如果没有输出 AVAILABLE，则整个会话都跳过此复用步骤，并严格按照下文所述生成规范。优雅降级——绝不要让搜索服务阻塞章节生成。
2. 起草 WHAT 查询，按照嵌入查询格式为该元素编写查询： Title: <working title> | Topic: <concept> | Subjects: <subject areas> | Grade Level: <level> | Learning Objectives: <objective with Bloom verb>
3. 运行复用搜索：

   /Users/dan/Documents/ws/search-microsims/.venv-embeddings/bin/python \
     /Users/dan/Documents/ws/search-microsims/src/find-similar-templates/find-similar-templates.py \
     --mode reuse --query "<WHAT query>" --top 3 --json --quiet
   

   如果命令出错或耗时超过约 60 秒，则本会话剩余部分改为正常生成规范。
4. 根据首个结果的 recommendation 字段作出决定：
   • reuse（WHAT 分数 ≥ 0.75）：输出下文的复用块，而不是规范。首先检查候选项的 grade_level 和 subject 是否适合本书；如果明显不合适（例如，在一本中学教材中使用研究生级别的仿真），则将其视为 template。如果本书中本地已存在 docs/sims/<sim-id>/，则使用相对路径 iframe 嵌入本地 MicroSim。
   • template（0.60 ≤ WHAT 分数 < 0.75）：编写常规规范，并在 details 块中添加一行：**Template:** <github_url of top match><br/>，以便 microsim-generator 可以使用现有 MicroSim 的代码作为起点。
   • generate（WHAT 分数 < 0.60）：照常编写常规规范。
5. 在章节生成摘要中记录复用决策：n 个复用、n 个基于模板、n 个新规范。

复用块结构（复用时用来替代规范）：

#### Diagram: [Title of the existing MicroSim]

<iframe src="[fullscreen_url from the search result]" width="100%" height="500px" scrolling="no"></iframe>

[Run the [Title] MicroSim fullscreen]([fullscreen_url]){ .md-button }

<details markdown="1">
<summary>[Title] (reused MicroSim)</summary>
Type: [element-type]
**sim-id:** [sim directory name from the source repo]<br/>
**Library:** [framework from the search result]<br/>
**Status:** Reused<br/>
**Source:** [live_url from the search result]<br/>
**Source Repo:** [github_url from the search result]<br/>
**Bloom Level:** [Remember | Understand | Apply | Analyze | Evaluate | Create]<br/>
**Bloom Verb:** [one verb from that level's list]<br/>
**Learning Objective:** The learner will [verb] [the objective as used in this chapter].

Reused from the MicroSim catalog (WHAT match score [what_score]).
</details>

**Status:** Reused 字段可防止下游批处理工具尝试搭建或实现该仿真：generate-todo.py 会从 TODO.md 中排除复用规范，而 extract-sim-specs.py 会将其记录为已完成。Reused 是一种终止生命周期状态——复用的仿真不会经历 specified → scaffolded → implemented → validated → deployed；它们已在其源代码库中部署。

对于每个新的 <details markdown="1"> 规范，请先阅读 references/microsim-specification-rules.md，并严格使用其中的代码块：

#### Diagram: [Title Case Name]

<details markdown="1">
<summary>[Title Case Name]</summary>
Type: [microsim | chart | diagram | infographic | timeline | map | workflow | graph-model | causal-loop]
**sim-id:** [kebab-case-directory-name]<br/>
**Library:** [p5.js | Chart.js | Plotly | Mermaid | vis-network | vis-timeline | Leaflet | venn.js | html]<br/>
**Status:** Specified<br/>
**Bloom Level:** [Remember | Understand | Apply | Analyze | Evaluate | Create]<br/>
**Bloom Verb:** [one verb from that level's list in references/blooms-taxonomy.md]<br/>
**Learning Objective:** The learner will [verb] [specific content] [condition or criterion].

**Prerequisites:** [terms the learner needs; each is defined in the prose above this block]

**Evidence of Mastery:** [the learner action that demonstrates the verb, and the rule that decides correct/incorrect]

**Misconceptions:** [wrong ideas the sim should expose and correct, or "none"]

**Instructional Rationale:** [why this kind of activity produces the evidence at this Bloom level]

**Content:** [every item, value, definition and label the learner sees, written out in full]

**Provenance:** [chapter section, file path or URL, synthetic with seed, or illustrative]

**Rules:** [formulas, thresholds with >= or >, ranges as min/max/step/default/unit, tie-breaks, edge cases]

**Learner Activity:** [numbered steps: what the learner does, what changes, what they should notice]

**Feedback:** [items, order, attempts, correctness rule, correct and incorrect messages, when answers are revealed]

**Starting State:** [what the learner sees first, and the question it poses]

**Chapter Anchors:** [every number, name and claim the chapter prose states about this sim, or "none"]
</details>

不要为新规范添加 iframe。MicroSim 构建完成后，microsim-generator 会插入高度正确的 iframe。

批处理工具（extract-sim-specs.py、 create-microsim-todo-json-files.py、generate-sim-scaffold.py）会解析六行标题行：

• sim-id — kebab-case 目录名（例如，angle-type-explorer），用于 docs/sims/<sim-id>/
• Library — 从列表中选择一个值；用于选择生成器路径和 CDN。无法识别“HTML and CSS”等自由文本，并会回退到 p5.js
• Status — 新规范使用 Specified；复用检查匹配到现有 MicroSim 时使用 Reused（这是一个终止状态，批处理工具会跳过）
• Bloom Level 和 Bloom Verb — 分行填写，不带修饰的值（填写 Analyze，而不是 Analyze (L4)）
• Learning Objective — 一句话，后接一个空行

<details markdown="1"> 块内的任何文本都不要缩进。<details markdown="1"> 块内的新行开头不得有空格或制表符。

务必在 details 块前添加带有 #### Diagram: 前缀的四级标题。这是必需的！

规范要求（完整规则、示例和自检请参阅 references/microsim-specification-rules.md）：

• 目标优先。 一个可衡量的目标，使用一个 Bloom 动词。“掌握证据”应指出学习者活动实际支持的操作，以及用于判断操作是否正确的规则。
• 内容完整。 写出学习者会看到的每一项内容。绝不要使用“例如”“诸如”“等等”，也不要说“12 张卡片的一组”却只列出 4 张。对于学习者需要分类或作答的任何内容，都要给出正确答案和一句理由，这将作为反馈。
• 注明内容来源。 每个事实值都要注明来源：章节小节、文件路径或 URL、带有种子的合成数据，或说明性数据。模拟必须标明合成数据和说明性数据。绝不能把真实世界的事实（坐标、日期、统计数据）留给生成器自行编造。
• 写规则，而非描述。 阈值使用 >= 或 >；每个可调参数都要注明最小值、最大值、步长、默认值和单位；默认值必须符合步长网格。
• 与章节内容一致。 正文中提到的所有与模拟有关的数字，都必须与 Chapter Anchors 中的数字完全一致。
• 不写构建说明。 像素尺寸、画布高度、布局、控件位置、断点、颜色、字体、库调用和 Implementation: 行都留给 microsim-generator 处理。例外情况是，视觉属性本身就是教学内容。
• 有关各元素类型的适用场景，请参阅 references/content-element-types.md。

内容结构：

1. 从介绍性段落开始，与章节摘要建立联系
2. 按教学顺序呈现概念（由简单到复杂）
3. 在内容中自然地融入非文本元素
4. 经常使用 Markdown 列表和表格（前面留空行）
5. 对复杂的视觉或交互元素使用 <details markdown="1"> 块
6. 在每个 details 块前添加四级 Markdown 标题 #### Diagram: [Diagram Name]
7. End with summary or key takeaways section

Interactive elements emphasis:

CRITICAL: Every diagram, chart, infographic, MicroSim, timeline, map, workflow, and graph model MUST be interactive. NEVER specify a static image that does not give the learner feedback. At minimum, every visual element must support at least one of: clickable nodes/regions/bars that open an infobox, hoverable elements that reveal tooltips, or controls that change the rendered output. Mermaid diagrams are acceptable ONLY when every node has a click directive that reveals a definition or explanation in an infobox — a plain Mermaid diagram with no click handlers is a static image and is forbidden. If a candidate diagram cannot meet this bar, redesign it as a MicroSim, an interactive infographic, or a clickable Mermaid diagram — or cut it. See references/content-element-types.md "CRITICAL RULE: Every Visual Element Must Be Interactive" for the full specification.

• Prioritize MicroSims and infographics that enable:
  • Student interaction tracking
  • Progress gauging
  • Personalized content recommendations
• Each interactive element has exactly one Learning Objective, with its Bloom Level and Bloom Verb on separate header lines (see the template above)
• Choose the level from the 2001 Bloom Taxonomy:
  • Remembering: Recalling facts, terms, basic concepts, and answers without necessarily understanding their meaning.
  • Understanding: Explaining ideas or concepts, demonstrating comprehension by summarizing or rephrasing information.
  • Applying: Using acquired knowledge to solve problems in new or unfamiliar situations.
  • Analyzing: Breaking down information into parts to understand its structure and relationships, and drawing comparisons.
  • Evaluating: Making judgments about information based on set criteria or standards, requiring critical thinking and justification.
  • Creating: Producing new or original work by combining elements to form a novel whole or solution.
• For the per-level action-verb lists and detailed question-writing guidance, read the canonical reference references/blooms-taxonomy.md (also used by faq-generator and quiz-generator).

Step 2.5: Verify Completeness

After generating chapter content, verify all concepts have been covered.

Verification process:

1. Review the generated content
2. Check that each concept from "Concepts Covered" list appears in the content
3. Create a checklist showing which concepts were covered
4. If any concepts missing:
   • Add content covering those concepts
   • Integrate them naturally into existing structure
5. Update the chapter index.md file with the complete generated content
6. Make Absolutely Sure that the content has been written to the chapter index.md file. Do a word count to make sure that ALL the content is present and that the TODO has been removed.
7. Run the Self-Check in references/microsim-specification-rules.md on every specification block in the chapter and fix each failure. At minimum, confirm for each block:
   • the Bloom Level, Bloom Verb and Learning Objective lines are present and consistent
   • the Evidence of Mastery is possible with the described Learner Activity
   • every count in the spec matches the items listed in Content
   • every number matches the chapter prose
   • the block contains no pixel sizes, layout, colors or Implementation: line

Actions:

• Replace the "TODO: Generate Chapter Content" placeholder with generated content
• Keep the existing title, summary, concepts list, and prerequisites sections
• Add the new detailed content after the prerequisites section

Phase 3: Aggregation (Sequential, after parallel agents complete)

After all parallel agents complete, aggregate results.

Step 3.1: Collect Agent Results

Wait for all Task agents to complete. Collect from each:

• List of chapter files created/updated
• Per-chapter statistics (word count, non-text elements, concepts covered)
• Any errors or issues encountered

Step 3.2: Generate Summary Report

Create a summary of all content generation:

# Chapter Content Generation Report

Generated: YYYY-MM-DD
Execution Mode: Parallel (6 agents)
Wall-clock Time: X minutes Y seconds

## Overall Statistics

- **Total Chapters:** 23
- **Total Words:** ~100,000
- **Avg Words per Chapter:** ~4,350
- **Total Non-text Elements:** ~115

## Execution Summary (Parallel Mode)

| Agent | Chapters | Words | Elements | Time |
|-------|----------|-------|----------|------|
| Agent 1 | 1-4 | 17,200 | 20 | 3m 15s |
| Agent 2 | 5-8 | 18,100 | 22 | 3m 42s |
| Agent 3 | 9-12 | 17,800 | 19 | 3m 28s |
| Agent 4 | 13-16 | 18,500 | 21 | 3m 51s |
| Agent 5 | 17-20 | 17,900 | 18 | 3m 33s |
| Agent 6 | 21-23 | 13,200 | 15 | 2m 45s |

## Per-Chapter Summary

| Chapter | Words | Lists | Tables | Diagrams | MicroSims | Concepts |
|---------|-------|-------|--------|----------|-----------|----------|
| 1. Foundations | 4,200 | 6 | 3 | 2 | 1 | 15/15 ✓ |
| 2. Limits | 4,500 | 5 | 2 | 3 | 2 | 14/14 ✓ |
| ... | ... | ... | ... | ... | ... | ... |

步骤 3.3：记录结束时间并写入会话日志

记录结束时间：

date "+%Y-%m-%d %H:%M:%S"

将会话信息导出到 logs/chapter-content-generator-YYYY-MM-DD.md：

# Chapter Content Generator Session Log

**Skill Version:** 1.11
**Date:** YYYY-MM-DD
**Execution Mode:** Parallel (6 agents)

## Timing

| Metric | Value |
|--------|-------|
| Start Time | YYYY-MM-DD HH:MM:SS |
| End Time | YYYY-MM-DD HH:MM:SS |
| Elapsed Time | X minutes Y seconds |

## Token Usage

| Phase | Estimated Tokens |
|-------|------------------|
| Setup (shared context) | ~20,000 |
| Agent 1 (Ch 1-4) | ~80,000 |
| Agent 2 (Ch 5-8) | ~80,000 |
| ... | ... |
| Aggregation | ~5,000 |
| **Total** | ~500,000 |

## Results

- Total chapters: N
- Total words: ~X
- All chapters written successfully: Yes/No

## Files Created/Updated

[List all chapter index.md files]

步骤 3.4：通知用户

通知用户：

“Chapter Content Generator v1.11 已完成！

• 模式： 并行（6 个 Agent）
• 耗时： X 分钟 Y 秒
• 已处理章节： 23
• 总字数： 约 100,000
• 非文本元素： 约 115

所有章节内容均已写入各自的 index.md 文件。

会话记录已写入 logs/chapter-content-generator-YYYY-MM-DD.md”

资源

此技能包含提供内容生成详细指南的参考文件：

references/content-element-types.md

涵盖所有非文本元素类型（以上第 3–11 项）的完整规范。包括：

• 各元素类型的适用场景
• 规范所需的信息
• 实现方法
• <details markdown="1"> 块格式的规范示例
• 在每个 details 元素前添加四级 Diagram 标题

#### Diagram: [Diagram Name]

生成内容时加载此参考文件，确保正确规范图表、MicroSims、信息图表、图表、时间线、地图、工作流和图模型。

references/microsim-specification-rules.md

编写精确规格说明块的规则。包括：

• 包含 6 行机器可读头部的块模板
• 规则 R1–R14，每个字段对应一条规则，并附有该规则所防止的问题以及错误／正确示例
• 应留给 microsim-generator 处理的内容（布局、尺寸、颜色、库调用）
• Type/Library 表
• 每章结束前对每个规格说明块进行自查的清单
• 完整的示例

编写任何 <details markdown="1"> 规格说明前，请先加载此参考文档。

references/reading-levels.md

针对不同阅读水平调整内容的详细指南。包括：

• 句子结构和长度指南
• 词汇选择
• 讲解风格
• 示例复杂度
• 预设背景知识
• 各个水平的示例文本

确定如何以适当的阅读水平撰写内容时，请加载此参考文档。

最佳实践

1. 始终阅读参考文档： 生成内容前，加载 references/content-element-types.md、references/microsim-specification-rules.md 和 references/reading-levels.md

2. 保留空行： Markdown 列表和表格前始终留一个空行（MkDocs 要求）

3. 教学顺序： 不必受概念列表顺序限制，应按最有效的顺序讲授概念

4. 视觉多样性： 混合使用不同类型的非文本元素，不要反复使用同一种类型

5. 强调互动： 优先使用能追踪学生参与情况的 MicroSim 和信息图

6. 规格说明要精确： 让每个 <details markdown="1"> 块都完整说明学习者必须学习的内容以及用于教学的内容，这样生成器就无需自行编造内容、规则或反馈。至于如何构建，则留给生成器处理。参见 references/microsim-specification-rules.md

7. 整合概念： 自然地交织不同概念，不要把它们当作互不相关的主题

8. 深度适当： 讲解深度应与阅读水平相匹配（初中阶段要提供更多引导，研究生阶段要增加理论内容）

9. 循序引导——阅读体验： 生成的内容应像引导式教程，而非参考文档。每个非文本元素（图表、代码块、表格）都应成为前文自然铺垫后的成果。请思考：“如果学生从上到下顺序阅读，读到每个元素时，是否已掌握理解它所需的词汇和背景？”如果没有，请在该元素前补充过渡说明。

10. 验证： 始终检查“涵盖的概念”列表中的所有概念是否都出现在生成的内容中

11. 风格一致： 整章保持统一的语气、术语和视觉风格

12. 并行执行： 处理 4 章及以上内容时，始终使用并行模式以提高效率

13. 真实时间戳： 始终使用实际系统时间戳，切勿使用合成数据

14. 谨慎使用表情符号： 仅当表情符号用于表现本章所教的隐喻时才使用。装饰性表情符号会与教材吉祥物以及“加粗并定义词汇”的模式争夺注意力——请勿使用。根据 Mayer 的连贯性原则，即使学生觉得装饰性视觉元素亲切，它们也会显著降低记忆留存率。参与度不等于学习。

15. 吉祥物位置： 如果项目的 CONTENT-GENERATION-GUIDE.md 定义了吉祥物，请严格遵守其中关于吉祥物呈现位置的规则——包括姿势选择、每章数量、硬性限制，以及第 1 章中仅一次的自我介绍。如果未定义吉祥物，则完全跳过此项。参见步骤 2.4 原则 4。

应避免的常见陷阱

依赖方向（最高优先级）：

• ❌ 使用 prereqs[edge['to']].add(edge['from']) 构建先决条件映射——这会反转所有依赖关系
• ❌ 跳过边方向验证（步骤 1.3a）——反转的映射会悄无声息地生成无效章节
• ❌ 存在依赖违规时仍继续生成章节（步骤 1.3b）
• ✅ 始终使用 prereqs[edge['from']].add(edge['to'])——from=依赖项，to=先决条件
• ✅ 始终先确认基础概念是否正确，再继续
• ✅ 生成任何内容前，始终确认依赖违规数量为 0

由 CIS 驱动的详述预算（高优先级——v1.09 新增）：

• ❌ 不考虑概念的 CIS 分数，对章节中的每个概念都采用统一字数
• ❌ 用本章概念而不是整本书的 cis_max 来归一化 E(c)（步骤 1.3）——开发期间曾尝试过这种做法，结果退化
• ❌ 将章节之间的字数差异视为需要平滑处理的错误——包含多个 Tier A 概念的章节理应比大多由 Tier C 概念组成的章节更长
• ❌ 仅仅为了让 Tier C 概念“看起来完整”，就添加不必要的图表/MicroSim；或者因为写得很快，就把 Tier A 概念只写成简短定义
• ✅ 每个概念的字数和必备元素都以其详述预算行（步骤 2.3b）为准，而不是以整章平均值为准
• ✅ 在步骤 1.3 中跨整本书计算一次 cis_max，并在每个章节中重复使用
• ✅ 将章节实际字数与其预算目标总和比较并报告，而不是与统一的 3000-5000 字范围比较

循序引导（关键——读者体验）：

• ❌ 图表使用前文尚未定义的术语（例如“向量”“嵌入”）
• ❌ 代码示例包含仅在后续章节中解释的参数（例如 temperature、max_tokens）
• ❌ 表格引入新概念，而不是总结已在正文中解释的概念
• ❌ 复杂元素出现前没有过渡句（“在查看此图表之前……”）
• ✅ 非文本元素中的每个技术术语都在其前面的正文中定义
• ✅ 代码示例前先用通俗语言说明代码的作用以及参数的含义
• ✅ 表格用于强化和整理内容，绝不引入新内容
• ✅ 使用导航提示（“在查看此图表之前，我们先定义两个术语”）引导读者顺畅过渡

吉祥物的使用：

• ❌ 第 1 章吉祥物首次发出的提醒跳过了自我介绍，直接进入章节内容
• ❌ 第 2 章及之后的章节重复吉祥物自我介绍（自我介绍应只在第 1 章出现一次）
• ❌ 臆造项目的 CONTENT-GENERATION-GUIDE.md 未定义的姿势角色
• ❌ 将吉祥物当作装饰，而不是提示信号；或超过渲染版吉祥物摆放规则规定的上限
• ✅ 第 1 章吉祥物首次发出的提醒应是自我介绍，并列出吉祥物扮演的每种姿势角色
• ✅ 第 2 章及之后的章节以普通的吉祥物欢迎语开篇，直接进入内容
• ✅ 吉祥物提醒之间应留有间隔（绝不连续出现），且应有其必要性，而非装饰用途

内容质量：

• ❌ 连续超过 4 段没有非文本元素
• ❌ 反复使用同一种元素类型
• ❌ 遗漏“涵盖的概念”列表中的概念
• ❌ 内容对目标阅读水平而言过于艰深或过于简单 MicroSim 规格（高优先级 — v1.11 新增）：
• ❌ 在目标句中写入 Bloom 层级（Learning objective (Bloom level: X; verb: Y): ...）——批处理工具无法解析，并会将模拟标记为「Create」
• ❌ 目标动词为「understand」「learn」「know」或「explore」，或将两个目标合并为一个的目标
• ❌ 只说明内容类型，却未提供具体内容（「例如，十二张卡片……」「三个数据集」「六个目标」）
• ❌ 活动无法展示的目标（五个配置层级，却只有三个选项；「四种节点形状」，但只定义了三种）
• ❌ 测验或检查未注明题目数量、尝试规则、正确性规则或反馈文本
• ❌ 阈值写成「above 0.95」，而不是 >= 0.95；范围未注明步长或单位；默认值不在步长网格上
• ❌ 规格中的数字与章节正文不一致（规格中为 12 种类型，章节中为 13 种）
• ❌ 指定布局、像素尺寸、画布高度、颜色、控件位置、断点或库调用——这些是导致规格自相矛盾的主要原因
• ❌ 要求在嵌入式模拟中实现 Mermaid 边缘点击、Mermaid <-- 箭头或鼠标滚轮缩放
• ❌ 使用自由文本作为 Library 值（「HTML and CSS」「Mermaid with a click directive on every node」）
• ✅ 分别填写 **Bloom Level:**、**Bloom Verb:** 和 **Learning Objective:**
• ✅ 完整写出内容，并为每个题目提供正确答案和一句话理由
• ✅ 每个事实值都有 Provenance；合成数据和示例数据均已标注
• ✅ 填写 Evidence of Mastery、Feedback 和 Chapter Anchors，并对每个区块运行自检

格式：

• ❌ 列表或表格前缺少空行
• ❌ 缩进 <details> 块中的内容
• ❌ <details> 块前缺少 #### Diagram: 标题
• ❌ 缺少闭合的 </details> 标签
• ❌ 未加引号的 frontmatter 值中包含冒号（description: Kinematics: where is the hand?，或 date: 2026-10-07 08:49:36）
• ✅ 所有包含冒号的 frontmatter 值都加双引号；title、description 和 date 始终加双引号

并行执行：

• ❌ 在不同消息中发送 Task 调用（这会导致顺序运行）
• ❌ 未等所有 Agent 完成就开始汇总
• ❌ 忘记汇总所有 Agent 的统计数据
• ❌ 使用合成时间戳，而非真实时间戳

输出文件摘要

必需（每章）：

1. 章节内容：docs/chapters/[chapter-name]/index.md

建议（汇总）： 2. logs/chapter-content-generator-YYYY-MM-DD.md - 含计时信息的会话日志

可选： 3. 含各章统计数据的摘要报告

会话示例

并行模式（默认）

用户：「为所有章节生成内容」

Agent（使用此技能）：

1. 记录开始时间
2. 通知：「Chapter Content Generator Skill v1.11 正在以并行模式运行。」
3. 读取共享上下文（课程说明、学习图谱、术语表、CONTENT-GENERATION-GUIDE.md）
4. 确定阅读水平（例如，高中）
5. 扫描章节目录，找到 23 个需要生成内容的章节
6. 规划批次：6 个 Agent，每个约 4 章
7. 在单条消息中启动 6 个 Task Agent（并行执行）
8. 等待所有 Agent 完成
9. 汇总所有 Agent 的结果
10. 记录结束时间
11. 写入会话日志
12. 报告：「Chapter Content Generator v1.11 已完成！模式：并行。耗时：18 分 32 秒。章节：23。字数：约 100,000。」

顺序模式

用户：“仅生成第 3 章的内容”

该 Agent（使用此技能）：

1. 阅读共享上下文
2. 确认第 3 章文件存在且包含所需元素
3. 确定阅读难度
4. 根据每个概念的 CIS 分数（步骤 2.3b）计算详述预算——例如，本章包含 4 个 A 级、6 个 B 级和 5 个 C 级概念，总预算约为 4,000 个单词
5. 按照每个概念的单独预算生成内容，并包含各级别所需的元素
6. 确认已涵盖所有概念，且字数大致符合预算范围
7. 将内容写入章节 index.md
8. 报告：“已生成第 3 章的内容。字数：4,050（预算：3,950）。元素：7。概念：15/15。”

报告示例

✅ Chapter content generated successfully!

Chapter: 01-intro-to-itil-and-config-mgmt
Reading level: Graduate
Content length: ~3,500 words

Non-text elements:
- 6 markdown lists
- 3 markdown tables
- 2 diagrams (CMDB architecture, ITIL process flow)
- 1 interactive timeline (ITIL evolution)
- 1 MicroSim (Configuration drift simulator)
- 1 workflow diagram (Change management process)

Interactive elements: 2 (timeline, MicroSim)
Skills required: 2 (microsim-p5 for MicroSim, infographic-generator for timeline)

All 20 concepts covered: ✓

!!! Note 若要使告诫框正常工作，mkdocs.yml 必须启用 admonition 和 pymdownx.details。