learning-graph-generator

学习图生成器

**版本：**1.07

更新日志

• v1.07 — 现在会在 SKILL.md 的 frontmatter 中将版本记录为 metadata.ibook.version。它位于 metadata: 下，而非单独的 version: 键，因为严格的打包验证会拒绝六个规范字段之外的任何 frontmatter 键。行为没有变化。

• v1.06 — 重大变更：csv-to-json.py（升级至 v1.04）现在会为每个节点计算概念影响分数（CIS），并将其作为 node.cis 写入 learning-graph.json。CIS 是一种类似 PageRank 的递归重要性度量：CIS(x) = 1 + sum(CIS(d) for d in direct dependents of x)，用于衡量整本书的理解有多少会传递性地依赖于某个概念。它不同于简单的入度，后者会低估仅通过间接关系奠定基础的概念（例如典型代数课程中的“常数”或“系数”，它们的直接后续依赖较少，但传递性依赖很多）。由于图是 DAG，CIS 可通过一次拓扑序遍历精确计算，无需阻尼因子或迭代。下游技能（book-installer 的图查看器、book-chapter-generator、chapter-content-generator）现在会直接读取此字段，而不再自行重新计算重要性度量。完整推导请参阅架构中的 nodes[].cis 字段，以及论文“Predicting Concept Content Size”（定义 3、命题 1）。这是对 learning-graph.json 输出格式的重大变更（新增字段，因此旧版读取器不会出错，但下游技能现在要求该字段必须存在）——在运行更新后的 book-chapter-generator 或 chapter-content-generator 之前，请为任何现有书籍重新生成 learning-graph.json。

• v0.06 —（此更新日志格式未记录更早的历史）

你的任务是根据课程描述生成全面、高质量的学习图。 学习图是智能教科书的基础数据结构，可用于推荐学习路径。 学习图就像一张概念路线图，帮助学生实现学习目标。 学习图是一个 DAG 概念图。每个箭头表示一种“学习依赖”关系，用于指示学习顺序。 你生成的 Markdown 必须兼容 mkdocs 版本的 Markdown。确保在所有列表前留出一个空行。

请仔细遵循以下步骤：

Markdown 生成规则

1. 始终在任何 Markdown 列表前留出一个空行。这是 mkdocs Markdown 工具的要求。

Mkdocs 导航规则

添加 Markdown 文件（任何扩展名为 .md 的文件）后，请确保将该文件添加到 mkdocs.yml 文件的导航结构中。 以下是学习图部分的 nav 区段示例：

  - Learning Graph:
    - Introduction: learning-graph/index.md
    - Course Description Assessment: learning-graph/course-description-assessment.md
    - Concept Enumeration: learning-graph/list-concepts.md
    - Graph Quality Analysis: learning-graph/graph-quality-analysis.md
    - Concept Taxonomy: learning-graph/concept-taxonomy.md
    - Taxonomy Distribution Report: learning-graph/taxonomy-distribution-report.md

步骤 0：设置

告知用户，他们正在运行 graph generator，以及上方显示的版本号。

默认情况下，此技能是在从 GitHub 检出的智能教科书主目录中通过 Claude Code 运行的。 Git 主目录中应有一个 docs 目录和标准的 mkdocs.yml 文件。 如果目录 /docs/learning-graph 尚不存在，请创建它。 此路径相对于 Git 主目录。假设 /docs 是相对于启动 Claude 的目录而言的。

mkdir -p docs/learning-graph; cd docs/learning-graph

你将把 Python 程序从此技能包复制到 /docs/learning-graph 目录中。 你将在该目录中运行 Python。

如果没有看到 docs 目录和 mkdocs.yml 文件，建议用户从以下位置克隆示例教科书：

git clone https://github.com/dmccreary/intelligent-book-template cd intelligent-book-template

步骤 1：课程描述质量评估

开始此步骤前，请先确认尚未完成。 为此，请检查 docs/course-description.md 文件中的 yml 元数据。

以下是 yml 元数据示例：

---
title: Course Description
description: A detailed course description 
quality_score: 95
---
# Course Description

如果看到 quality_score 高于 85，可以告知用户你发现了一个高于 85 的分数，并跳过整个步骤。告诉他们这样可以节省 token。

如果质量分数低于 85，请分析 course-description.md 中提供的课程描述，确保内容足够丰富，至少可以生成 300 个高质量概念：

1. 确认课程包含标题、先修条件、目标受众、目标和学习成果（“完成本课程后，学生将能够……”）。如果缺少这些内容，请向用户索取相关信息。
2. 检查所涵盖主题的深度和广度
3. 评估材料是否足够细致，至少能生成 300 个不同的概念
4. 检查主题领域和学习目标是否多样
5. 向用户提供详细反馈，说明：
   • 列出你找到的预期内容
   • 估算可以提炼出的概念数量
   • 将该概念数量与类似课程进行比较
   • 描述课程描述的优势之处
   • 指出任何缺漏或覆盖不足的领域
   • 建议如何运用 2001 年版布鲁姆分类法（记忆、理解、应用、分析、评价、创造）改进学习成果描述
   • 按 1（差）到 100（完美）的尺度，给出客观的总体质量评估
   • 建议用户在质量分数达到 70 或以上之前不要继续

使用以下评分标准计算质量分数：

2.2 课程描述质量评分系统

使用以下 100 分制对课程描述进行评估：

要素	分值	标准
标题	5	存在清晰、描述性强的课程标题
目标受众	5	指明具体受众（例如“大学本科生”）
先修条件	5	列出先修条件，或明确注明“无”
主要涵盖主题	10	主题列表全面（理想情况下为 5 到 10 个主题）
排除的主题	5	明确界定未涵盖的内容
学习成果标题	5	清晰说明：“完成本课程后，学生将能够……”
记忆层级	10	包含多个具体的记忆或回忆类学习成果
理解层级	10	包含多个具体的理解或解释类学习成果
应用层级	10	包含多个具体的应用或使用类学习成果
分析层级	10	包含多个具体的分析或拆分类学习成果
评价层级	10	包含多个具体的评估或判断类学习成果
创造层级	10	包含多个具体的创造或综合类学习成果；包括毕业综合项目构想
描述性背景	5	提供有关课程重要性、相关性或价值的补充背景

评分指南：

• 如果某项内容完整且质量高，给满分
• 如果某项内容存在但不完整或含糊，给部分分数
• 如果缺少某项内容，给 0 分
• 对于布鲁姆分类法各层级，满分要求至少包含 3 个具体、可操作的学习成果

告知用户其得分，并建议他们改进课程描述，直到分数超过 80。

将此报告保存到 course-description-assessment.md

5. 询问用户是否应继续生成学习图谱

步骤 2：生成概念标签

课程描述获批后，根据课程内容生成概念标签：

要求：

• 每个概念标签都必须采用标题式大小写
• 最大长度：32 个字符
• 标签应清晰、具体，并符合教学要求
• 涵盖课程材料的全部内容
• 概念标签是实体名称，而不是问题
• 概念标签中不要使用问题。不要写“What is Git”，只需写“Git”

概念数量：

对于简单的书籍，列出 300 个概念即可。 对于复杂的技术书籍，最多可生成 600 个概念。 除非有充分理由并获得用户批准，否则不要超过 600 个概念。 请记住，概念越多，生成概念依赖关系就越复杂。

!!! note 由于这些概念标签会用于网络图，因此不能太长。 否则图表会难以阅读。

输出：

• 将编号列表保存到 concept-list.md
• 格式：Markdown 文件中的简单编号列表（1-600）
• 确保每个编号都唯一，以便用作 ConceptID
• 告知用户文件已创建
• 告诉用户现在应查看列表，并添加或删除概念
• 告诉用户最好在进行下一步之前检查概念列表

现在请用户花些时间手动检查完整的概念标签列表。 如果有不合适的概念，应立即删除。 如果需要添加其他概念，也应立即添加。 之后再修改内容会需要消耗大量额外 token。 这是确保教材质量的重要检查步骤。 请特别注意概念标签的长度以及缩写的质量。

步骤 3：生成依赖关系图

创建一个 CSV 文件，用于映射概念之间的依赖关系：

格式：

• 文件名：learning-graph.csv
• 列：ConceptID,ConceptLabel,Dependencies
• ConceptID：整数（1-600）
• ConceptLabel：与步骤 2 中的标签完全一致
• Dependencies：以竖线分隔的 ConceptID 列表（例如："1|3|7"）

依赖关系规则：

• 基础/先修概念没有依赖项（Dependencies 字段留空）
• 所有其他概念都必须至少有一个依赖项
• 概念不能依赖自身
• 图必须是有向无环图（DAG），不能有循环
• 创建有意义的学习路径，而不只是线性链条
• 仔细考虑先修关系

注意： JSON 文件将在后续步骤（步骤 7-8）中创建，届时分类体系已添加到 CSV 文件中。完整的 JSON 将包含 metadata、groups、nodes 和 edges 部分，并符合 learning-graph-schema.json。

第 4 步：学习图质量验证

使用此技能中的 Python 程序 analyze-graph.py，对依赖关系图进行全面的质量检查。 该程序将执行以下检查：

1. 验证 DAG 结构：确保不存在循环
2. 检查自依赖：任何概念都不应依赖自身
3. 基础概念：识别没有依赖项的概念
4. 终端节点：识别没有其他概念依赖的概念（叶节点）。这些节点有效且符合预期——不要与没有任何连接的孤立节点混淆
5. 不连通的子图：检查所有概念是否都与主图相连
6. 线性链：如果有过多概念只依赖紧邻的前一个概念，则将其标记出来
7. 入度分析：计算入度（依赖于各概念的概念数量）

Shell 命令 python analyze-graph.py learning-graph.csv quality-metrics.md

确认报告已写入 quality-metrics.md

生成学习图质量指标报告：

• 没有依赖项的概念总数——出边（基础先修概念）
• 有 1 个或更多依赖项的概念总数
• 每个概念的平均依赖项数量
• 最大依赖链长度
• 没有其他概念依赖的终端（叶）节点数量
• 不连通子图的数量
• 入度最高的前 10 个概念（被依赖最多的概念）

按 1（差）到 100（完美）的范围，为用户提供总体质量评分。 如果学习图的评分未超过 70，建议用户迭代改进流程

第 5 步：创建概念分类体系

制定分类体系，对概念进行归类：

要求：

• 目标：约 12 个类别（如果自然形成的分组有所不同，可上下浮动 2–3 个）
• 各类别应均匀分配概念
• 避免任何单个类别包含超过概念总数 30% 的概念
• 使用清晰、描述性且以标题格式书写的类别名称，并以空格分隔单词
• 为每个类别创建 3–5 个字母的缩写（TaxonomyID）
• 请注意，系统将创建该分类体系的 JSON 表示，用于构成学习图的 groups 部分

输出：

• 将分类体系保存到 concept-taxonomy.md
• 使用 Markdown 格式，包含：
  • 类别名称
  • TaxonomyID 缩写（3–5 个大写字母）
  • 简要说明该类别包含哪些概念

第 5b 步：创建分类名称 JSON

关键步骤——这可以避免图表查看器图例和报告中显示分类 ID，而非易读名称这一常见问题。

从 concept-taxonomy.md 中提取分类 ID 到易读名称的映射，并将其保存为 JSON 文件：

创建文件： taxonomy-names.json

格式：

{
  "FOUND": "Foundation Concepts",
  "EDA1": "Exploratory Data Analysis I",
  "EDA2": "Exploratory Data Analysis II",
  "REG": "Regression & Correlation",
  ...
}

规则：

• 键为 TaxonomyID 缩写（大写，3–5 个字母）
• 值为易读的类别名称，使用标题格式并以空格分隔单词
• CSV 中使用的每个分类 ID 都必须有对应的名称
• 名称应具有描述性，便于学生理解

csv-to-json.py 需要此文件，才能在 learning-graph.json 中生成正确的 classifierName 值。没有该文件，图表查看器图例将显示诸如“EDA1”之类难以理解的 ID，而非“Exploratory Data Analysis I”。

---

第 6 步：向 CSV 添加分类信息

更新依赖关系 CSV 文件：

1. 如果现有 CSV 文件中没有 TaxonomyID 列，则添加该列
2. 为每个概念分配最匹配的 TaxonomyID
3. 对于没有明确匹配类别的概念，使用“MISC”
4. 将更新后的文件保存到 learning-graph.csv

你可以参考 Python 程序 add-taxonomy.py， 它会执行替换操作。

最终 CSV 列： ConceptID,ConceptLabel,Dependencies,TaxonomyID

步骤 7：创建 learning-graph.json 文件的 metadata 部分

metadata 部分包含受都柏林核心启发的字段，适用于从 course-description.md 文件中提取的教科书。学习图谱的 JSON 架构位于此技能中的 learning-graph-schema.json 文件内。

必填字段：

• title：从课程描述标题中提取
• description：从课程描述中提取或概述

可选但建议填写的字段：

• creator：作者或组织名称
• date：当前日期，格式为 YYYY-MM-DD
• version：版本号（例如，“1.0”）
• format：“Learning Graph JSON v1.0”
• schema：JSON 架构的 URL
• license：许可证信息（例如，“CC BY-NC-SA 4.0 DEED”）

以下是 metadata 部分的示例：

"metadata": {
    "title": "Title Text From Course Description",
    "description": "A description of the course in a few sentences.",
    "creator": "Your Name",
    "date": "2025-11-01",
    "version": "1.0",
    "format": "Learning Graph JSON v1.0",
    "schema": "https://raw.githubusercontent.com/dmccreary/learning-graphs/refs/heads/main/src/schema/learning-graph-schema.json",
    "license": "CC BY-NC-SA 4.0 DEED"
  }

你可以使用这些字段创建 metadata.json 文件，并在步骤 9 中传递给 csv-to-json.py 程序。

步骤 8：创建 JSON 文件的 groups 部分

将分类体系类别转换为 JSON 格式，用作 learning-graph.json 文件的 groups 部分。学习图谱的 JSON 架构位于此技能中的 learning-graph-schema.json 文件内。

groups 部分用于创建概念类型图例，并为可视化设置不同颜色。

重要事项：

• groups 部分使用分类体系 ID（例如，“FOUND”“DEF”）作为键
• 每个组都必须包含 classifierName 字段，其中填写描述性、易于理解的名称（例如，“基础概念”，而不仅仅是“FOUND”）
• 每个组都必须包含 color 字段，并使用CSS 颜色名称（不得使用“#E74C3C”之类的十六进制代码）
• 每个组都应包含一个带有 color 字段的 font 对象——深色背景使用 white，浅色背景使用 black。csv-to-json.py v1.04+ 会根据背景自动选择合适的字体颜色。

关键结构：

• 组键：使用 CSV 中的 TaxonomyID（大写，不含空格，例如，“FOUND”）
• classifierName：使用标题式大小写并以空格分隔的描述性显示名称（例如，“基础概念”）。切勿只重复 TaxonomyID 缩写。
• color：使用下方推荐的不同 CSS 颜色名称。避免使用 AliceBlue（页面背景色）。
• font.color：深色背景使用 white，浅色背景使用 black。由 csv-to-json.py 自动分配。

推荐的 24 色独特调色板

csv-to-json.py v1.04+ 中的默认调色板经过精心调整，确保相邻图例行不会冲突，并通过明度区分同色系。它可以轻松支持最多 24 个不同类别。使用此调色板（或按此顺序选取其子集，并通过 color-config.json 配置），即使分类体系很多，也能保持视觉清晰：

位置	颜色（CSS 名称）	建议的类别系列	字体
1	SteelBlue	基础	白色
2	DarkSlateBlue	角色／治理	白色
3	DarkGreen	架构	白色
4	LimeGreen	应用开发	黑色
5	Gold	数据管理	黑色
6	DarkGoldenrod	数据治理	白色
7	Khaki	商业智能	黑色
8	Teal	企业系统	白色
9	DodgerBlue	网络／电信	白色
10	LightSkyBlue	云计算	黑色
11	Crimson	安全	白色
12	DarkRed	隐私／合规	白色
13	MediumPurple	项目管理	白色
14	Indigo	流程管理	白色
15	DarkOrchid	系统分析与设计	白色
16	HotPink	人机交互	黑色
17	OliveDrab	IT 服务管理	白色
18	Orange	AI 能力	黑色
19	Coral	负责任的 AI	黑色
20	Peru	AI 法律／法规	黑色
21	SaddleBrown	AI 安全	白色
22	Tomato	AI 生产力	白色
23	DeepPink	知识图谱／强调色	白色
24	DimGray	新兴／其他	白色

设计依据：

• 按主题系列分组色相——基础与基础设施使用冷蓝色，构建／架构使用绿色，数据领域使用黄色／金色，安全使用红色，项目／流程使用紫色，AI 集群使用橙色／棕色；以强调色（DeepPink）表示作为连接纽带的知识图谱，以中性灰表示新兴主题。
• 在每个色相系列中交替使用明度，避免相邻颜色冲突（Gold → DarkGoldenrod、DodgerBlue → LightSkyBlue、MediumPurple → Indigo 等）。
• 深色背景使用白色文字，浅色背景使用黑色文字——csv-to-json.py v1.04+ 会自动执行此规则。深色集合包括 SteelBlue、DarkSlateBlue、DarkGreen、DarkGoldenrod、Teal、DodgerBlue、Crimson、DarkRed、MediumPurple、Indigo、DarkOrchid、OliveDrab、SaddleBrown、Tomato、DeepPink、DimGray。

color-config.json（推荐）

将选定的调色板保存到 docs/learning-graph/color-config.json，以便之后重新生成时保留每个分类体系 ID 对应的颜色。示例：

{
  "FOUND": "SteelBlue",
  "ROLE": "DarkSlateBlue",
  "ARCH": "DarkGreen",
  "APPDEV": "LimeGreen",
  "DATA": "Gold",
  "SEC": "Crimson",
  "MISC": "DimGray"
}

将其传递给 csv-to-json.py：python csv-to-json.py learning-graph.csv learning-graph.json color-config.json metadata.json taxonomy-names.json

分组部分示例

"groups": {
    "FOUND": {
      "classifierName": "Foundation Concepts",
      "color": "SteelBlue",
      "font": { "color": "white" }
    },
    "DATA": {
      "classifierName": "Data and Information Management",
      "color": "Gold",
      "font": { "color": "black" }
    },
    "SEC": {
      "classifierName": "Security of Information Assets",
      "color": "Crimson",
      "font": { "color": "white" }
    },
    "AIIS": {
      "classifierName": "AI in Information Systems",
      "color": "Orange",
      "font": { "color": "black" }
    },
    "MISC": {
      "classifierName": "Miscellaneous Concepts",
      "color": "DimGray",
      "font": { "color": "white" }
    }
  }

**注意：**csv-to-json.py 程序会根据 CSV 文件中找到的分类体系自动生成分组部分。如果没有 color-config.json，程序会按照图例顺序从默认的 24 色调色板中按位置分配颜色——这些颜色本身已经足够鲜明，但建议保存 color-config.json，以确保重新生成时颜色分配保持稳定。

步骤 9：生成完整的学习图 JSON

创建 metadata.json 文件（步骤 7）、taxonomy-names.json 文件（步骤 5b）并准备好融入分类体系的 CSV 文件（步骤 6）后，运行 csv-to-json.py 程序来生成完整的 learning-graph.json 文件：

python csv-to-json.py learning-graph.csv learning-graph.json color-config.json metadata.json taxonomy-names.json

重要： 强烈建议使用 taxonomy-names.json 文件，以确保图表查看器图例中显示的是易于理解的类别名称。否则，显示名称将使用分类体系 ID（如“EDA1”），而不是规范名称（如“探索性数据分析 I”）。

此命令将：

1. 读取 learning-graph.csv 文件（包含 ConceptID、ConceptLabel、Dependencies、TaxonomyID 列）
2. 使用 metadata.json 中的元数据
3. 使用 taxonomy-names.json 中易于理解的名称填充 classifierName 字段
4. 根据 CSV 中的分类体系自动生成 groups 部分
5. 创建具有正确分组引用的节点（使用 TaxonomyID）
6. 根据依赖关系创建边
7. 为每个节点计算概念影响分数（CIS），并将其附加为 node.cis（参见上面的更新日志）
8. 输出符合架构的完整 learning-graph.json 文件
9. 如果某个分类体系 ID 缺少易于理解的名称，则发出警告

确认文件 learning-graph.json 存在且有效。控制台输出将列出 CIS 最高的 10 个概念——请检查这些概念是否确实是课程的基础概念（被广泛依赖的概念），而不是狭窄的末端主题。如果某个狭窄或高级概念的 CIS 排名最高，边的方向很可能反了（如何诊断，请参阅 book-chapter-generator 技能中的边方向验证）。

可选：你可以使用以下命令根据架构验证 JSON：

./validate-learning-graph.sh learning-graph.json

步骤 10：分类体系分布报告

生成分布分析：

1. 统计每个类别中的概念数量
2. 计算百分比
3. 找出占比过高的类别（>30%）
4. 如有需要，建议替代分类方式

使用此技能中的 Python 报告程序 taxonomy-distribution.py

输出：

• 保存为 taxonomy-distribution.md
• 格式为 Markdown 表格，包含以下列：
  • 类别名称
  • TaxonomyID
  • 数量
  • 百分比

步骤 11：根据 index-template.md 创建新的 index.md

在 learning-graph 目录中，根据此技能中的 index-template.md 文件创建新的 index.md 文件。 自定义新的 index.md 文件，使其体现这本智能书的名称。查找所有大写值（TEXTBOOK_NAME）， 并将其替换为相应的值。

步骤 12：编写会话日志

将会话日志导出到 logs/learning-graph-generator-VERSION-DATE.md

其中：

1. VERSION 是此技能的版本。
2. DATE 是今天的日期，格式为 ISO 格式 yyyy-mm-dd。

请注意，会话日志还应列出所使用的任何 Python 程序的版本。 例如，应记录会话中使用的 csv-to-json.py Python 程序的版本。 这对于调试很重要。

步骤 13：完成

告知用户学习图谱生成完毕！向他们表示祝贺，并祝他们的教材或课程材料进展顺利。
告诉用户，如果想查看学习图谱，应运行 /book-installer 技能，并使用安装学习图谱指南；该指南会在 @docs/sims/graph-viewer 中创建一个 microsim。 尽管这一步是可选的，但强烈建议执行。 告诉他们，接下来最合适的步骤是运行 /book-chapter-generator 技能，但在执行这一步之前，务必检查章节概览、 概念列表、概念分类体系和学习图谱。 生成章节内容会消耗大量 tokens，因此最好确保每个 章节概览和概念列表都完整无缺。

已创建的文件：

• course-description-assessment.md - 课程描述的质量评估
• concept-list.md - 最多包含 600 个概念的编号列表
• learning-graph.csv - 包含分类体系的完整依赖关系图
• taxonomy-names.json - 分类体系 ID 到人类可读名称的映射（对图谱查看器至关重要）
• metadata.json - 学习图谱的元数据（标题、描述、创建者等）
• learning-graph.json - 完整的学习图谱，包含元数据、分组、节点和边，采用 vis-network.js JSON 格式
• concept-taxonomy.md - 类别定义
• quality-metrics.md - 质量验证报告
• taxonomy-distribution.md - 类别分布分析
• index.md - 学习图谱部分的介绍页面

重要说明

• 在整个过程中保持教学完整性
• 依赖关系应反映实际的先修知识
• 在细粒度和全面性之间取得平衡
• 确保概念之间的逻辑递进
• 学习图谱应支持多种学习路径，而不只是单一路径