glossary-generator

术语表生成器

版本： 1.0

根据学习图谱的概念列表生成全面的术语表，并提供符合 ISO 11179 标准的定义。

TOKEN 效率警告

此技能会生成大型文件（2,000 行以上）。对于预算有限的教师用户，Token 成本远比实际耗时重要。

默认做法：使用一个串行 Task 代理，直接将所有定义写入临时文件。这是 Token 效率最高的方法，因为：

• 系统提示词／工具描述的开销只需支付一次（约 12K Token）
• 无需协调或汇总开销
• 经验证，可在约 31K Token 内完成包含 350 个术语的术语表（2026-03-14 基准测试）

实测 Token 成本（350 个术语基准，2026-03-14）

组成部分	Token 数	说明
代理开销（系统提示词 + 工具）	约 12K	串行只需支付一次，并行需支付 4 次
定义生成（350 个术语）	约 19K	不可避免的大模型工作量
汇总（Python 脚本）	约 700	简单的编程任务
总计（串行）	约 31K

每个术语的 Token 数：总计约 88，边际约 54（扣除一次性开销后）。

边际成本的计算方式为：（30,788 − 12,000）/ 350 = 每个术语约 54 Token。 可据此估算任意规模术语表的成本：

术语表规模	预估总 Token 数
100 个术语	约 17K（12K 开销 + 5.4K 生成）
200 个术语	约 23K
350 个术语	约 31K（实测）
500 个术语	约 39K

为什么绝不应使用并行执行

每个并行代理都要独立承担完整的约 12K 系统提示词开销。 生成术语表时，各项定义完全独立——并行执行没有任何值得承担成本的提速效果。串行代理会在一次 Write 调用中写入所有术语，并在约 6 分钟内完成，这完全可以接受。

方式	代理开销	生成	汇总	总计	浪费
1 个串行代理（推荐）	约 12K（一次）	约 19K	约 700	约 31K	—
4 个并行代理 + 脚本	约 48K（4 倍）	约 19K	约 700	约 68K	+37K（119%）
4 个并行代理 + 手动 Edit	约 48K（4 倍）	约 19K	约 200K	约 267K	+236K（761%）

并行执行会使 Token 成本翻倍以上，却不会带来任何质量提升。 对于使用 Claude Pro 套餐（五小时预算约 200K Token）的教师，串行方式会消耗约 16% 的预算，而并行方式会消耗 34%，手动汇总则会消耗 100% 以上。

生成术语表时绝不使用并行代理。浪费的 Token 不值得。

始终使用串行方式。不要将并行作为选项提供。

汇总步骤（排序并写入最终文件）必须始终使用 Python 脚本——绝不可通过 Edit/Write 工具调用手动输出术语表内容。 完整复盘请参阅 logs/glossary-generation-very-inefficient.md。

目的

此技能通过将学习图谱中的概念标签转换为格式规范的术语定义，自动为智能教材创建术语表。每条定义均遵循 ISO 11179 元数据注册标准：准确、简洁、明确、非循环定义，并且不包含业务规则。此技能可确保术语的一致性、验证交叉引用，并生成按字母顺序排列且包含相关示例的词条。

简短定义后，可补充讨论该术语对教材的重要性，并举例说明该术语的用法。

何时使用此技能

在 Learning Graph 技能完成且概念列表最终定稿后，使用此技能。也可以扫描 /docs 目录中的所有 Markdown 内容，查找可能不易被普通高中生理解的词语或短语。

术语表依赖于从学习图谱概念枚举阶段获得的完整且经过审核的概念列表。具体来说，在以下情况下触发此技能：

• 概念列表文件已存在（通常为 docs/learning-graph/02-concept-list-v1.md）
• 概念列表已审核并获批
• 课程说明已存在，且包含明确的学习成果
• 已准备好创建或更新教科书的术语表

工作流

步骤 1：验证输入质量

在生成定义之前，评估概念列表的质量：

1. 读取概念列表文件（通常为 docs/learning-graph/02-concept-list-v1.md）
2. 检查是否有重复的概念标签（目标：100% 唯一）
3. 验证标题大小写格式（目标：符合率达到 95% 以上）
4. 验证长度限制（目标：98% 的概念少于 32 个字符）
5. 评估概念是否清晰（不得含有歧义术语）

计算质量得分（1–100 分）：

• 90–100：所有概念都唯一、格式正确且长度适当
• 70–89：大多数概念符合标准，只有少量格式问题
• 50–69：存在一些重复概念或格式不一致
• 低于 50：存在需要人工审核的严重问题

用户对话触发条件：

• 如果得分低于 70：询问“概念列表存在质量问题。生成术语表之前，您是否希望先审核并清理列表？”
• 如果发现重复项：询问“发现 [N] 个重复概念。是否要自动删除重复项，还是由您审核？”
• 如果发现格式问题：询问“发现 [N] 个概念存在格式问题。是否自动修复？”

步骤 2：阅读课程背景

阅读课程说明文件（docs/course-description.md）以及 /docs/**/*.md 中的其他 Markdown 文件，以了解：

• 目标受众（用于确定示例的复杂程度）
• 课程目标（用于确保术语一致）
• 先修要求（用于确定背景知识的假设）
• 学习成果（用于了解概念的使用背景）

步骤 3：使用单个串行 Agent 生成定义

默认方法（最节省 token）： 启动一个 Task Agent，生成所有定义并将其直接写入一个临时文件。

Task agent prompt:
"Generate ISO 11179-compliant glossary definitions for the following [N] terms.
Write ALL entries as markdown (#### headers with definitions, examples, and
discussion) to the file /tmp/glossary-raw.md using the Write tool.
Each entry uses #### for the term header. Do not return the content in your
response — just confirm the file was written and report the term count.

[Paste the full term list here]

[Paste course description context here for audience level]"

单个 Agent 会将所有定义写入一个文件。这样只需支付一次系统提示词开销（约 12K 个 token），并避免所有协调成本。经验证，生成 350 个术语的术语表约需 31K 个 token（总计约 88 个 token/术语，边际成本约 54 个 token/术语）。

不要使用并行 Agent 生成术语表。 有关为何绝不应使用并行执行的原因，请参阅上文的 TOKEN EFFICIENCY WARNING（Token 效率警告）部分——并行执行会使 token 成本增加一倍以上，却不会带来任何质量提升。

针对列表中的每个概念，按照 ISO 11179 标准创建定义：

精确性（25 分）： 准确表达概念的含义

• 在课程的具体语境中定义概念
• 使用适合目标受众的术语
• 确保定义符合概念在课程中的用法

简洁性（25 分）： 保持定义简短（目标：20–50 个词）

• 避免不必要的词语或解释
• 尽快说明核心含义
• 使用清晰、直接的语言

独特性（25 分）： 确保每个定义各有特点，彼此可区分

• 避免照搬其他来源的定义
• 确保没有两个定义过于相似
• 突出此概念与相关概念的区别

非循环性（25 分）： 避免循环依赖

• 定义中不要引用尚未定义的术语
• 不要形成循环链（A 依赖 B，B 依赖 A）
• 在定义中使用更简单、更基础的术语

格式示例：

对于概念“Learning Graph”：

#### Learning Graph

A directed graph of concepts that reflects the order that concepts should be learned to master a new concept.

Learning graphs are the foundational data structure use for intelligent textbooks.  They are used to guide
intelligent agents and recommend learning paths for students.

**Example:** In a programming course, the learning graph shows that "Variables" must be understood before "Functions," which must be understood before "Recursion."

步骤 4：添加示例（覆盖 60-80% 的术语）

对于大多数概念（目标：60-80%），请添加相关示例：

• 以“示例：”开头（冒号后不换行）
• 提供一个来自课程领域的具体示例
• 示例应简短（1-2 句话）
• 确保示例能阐明概念，而不会造成混淆

步骤 5：添加交叉引用

适当时，请引用相关术语：

• 使用“另请参阅：”引用相关概念
• 使用“对比：”引用相反概念
• 确保所有交叉引用的术语都存在于术语表中
• 每个术语的交叉引用保持在 1-3 个

步骤 6：使用 Python 脚本组装术语表文件

重要：绝不要手动通过 Edit/Write 工具调用来组装术语表。 按字母顺序排序并合并文件是简单的编程任务。通过手动生成文本来完成会浪费 100,000+ 个 token，并产生实际费用。

必须采用以下方法： 通过 Bash 工具编写并执行 Python 脚本，该脚本需：

1. 读取 Agent 输出文件 — /tmp/glossary-raw.md（串行）或 /tmp/glossary-part-*.md（并行）
2. 通过按 #### 标题拆分来解析条目
3. 使用 sorted() 按字母顺序排序条目（不区分大小写）
4. 一次性写入最终的 docs/glossary.md

参考脚本（可按需调整路径）：

#!/usr/bin/env python3
"""Merge glossary parts into a single sorted glossary."""
import glob, os, re

entries = {}

# Support both serial (single file) and parallel (multiple files)
if os.path.exists('/tmp/glossary-raw.md'):
    sources = ['/tmp/glossary-raw.md']
else:
    sources = sorted(glob.glob('/tmp/glossary-part-*.md'))

for path in sources:
    with open(path) as f:
        content = f.read()
    for block in re.split(r'\n(?=#### )', content):
        block = block.strip()
        m = re.match(r'#### (.+)', block)
        if m:
            entries[m.group(1).strip()] = block

sorted_terms = sorted(entries.keys(), key=lambda t: t.lower())

with open('docs/glossary.md', 'w') as out:
    out.write('# Glossary of Terms\n\n')
    for term in sorted_terms:
        out.write(entries[term] + '\n\n')

print(f"Wrote {len(sorted_terms)} terms to docs/glossary.md")

通过 Bash 工具运行此脚本：python3 /tmp/assemble_glossary.py。 总成本：脚本约 500 个 token + 输出约 200 个 token = 约 700 个 token （而通过 Edit 调用手动完成则需 200,000+ 个 token）。

绝不要执行以下操作：

• 通过 Write 或 Edit 工具直接编写术语表条目
• 将子 Agent 的输出复制粘贴到 Edit 工具的 old_string/new_string 参数中
• 通过按字母顺序输出术语来手动排序
• 通过 Edit 调用逐个向术语表文件追加章节

组装后文件的格式规则：

• 术语表条目只能使用四级标题（####）。 不要在术语表中使用 ## 章节标题、### 子标题或任何其他级别的标题。文件中唯一的 # 标题是页面标题（# Glossary of Terms）。其余内容均使用 ####。
• 术语只能按字母顺序排序（不区分大小写）。绝不要按类别、领域或主题对术语分组。 术语表是扁平的字母顺序列表——不要使用分隔线、类别标题或主题分组。字母顺序是唯一的组织原则。
• 术语表中不要出现任何 --- 字符串。无需使用它们。
• 示例使用“示例：”（加粗并带冒号）
• 保持条目间距一致（条目之间空一行）

步骤 7：生成质量报告

创建 docs/learning-graph/glossary-quality-report.md，其中包含：

ISO 11179 元数据注册表合规性指标：

对每条定义按 5 项标准评分（每项 25 分）：

1. 精确性：是否准确表达了含义？
2. 简洁性：是否简短（20-50 个词）？
3. 差异性：是否独特且易于区分？
4. 非循环性：是否不存在循环依赖？
5. 不受业务规则限制：是否不包含特定政策或规则？

总体质量指标：

• 定义平均长度：[X] 个词
• 满足全部 4 项标准的定义：[X]%
• 发现的循环定义：[X]
• 示例覆盖率：[X]%
• 交叉引用：[X] 个，其中 [X] 个无效

可读性：

• Flesch-Kincaid 年级水平：[X]
• 是否适合目标受众：是/否

建议：

• 列出得分低于 70/100 的定义
• 指出需要修复的循环依赖
• 建议需要添加示例的概念
• 说明任何无效的交叉引用

步骤 8：验证输出

执行最终验证：

1. 验证是否按字母顺序排列（必须 100% 符合要求）
2. 检查所有交叉引用是否指向现有术语
3. 确保包含输入列表中的所有概念
4. 验证 Markdown 语法能否正确渲染
5. 确认不存在循环定义

成功标准：

• 总体质量评分 > 85/100
• 不存在循环定义
• 100% 按字母顺序排列
• 包含概念列表中的所有术语
• Markdown 能在 mkdocs 中正确渲染

步骤 9：更新导航（可选）

如果 - Glossary: glossary.md 尚未添加到 mkdocs.yml 的 nav: 中，请按照 $BK_HOME/skills/book-installer/references/mkdocs-nav-editing.md 中的规范导航编辑规则，在接近末尾的位置（License/Contact 之前）添加。

步骤 10：生成交叉引用索引（可选）

创建 docs/learning-graph/glossary-cross-ref.json，用于语义搜索：

{
  "terms": [
    {
      "term": "Learning Graph",
      "related_terms": ["Concept Dependency", "Directed Acyclic Graph"],
      "contrasts_with": ["Linear Curriculum"],
      "category": "Educational Technology"
    }
  ]
}

此 JSON 文件可支持未来的功能，例如：

• 在整个术语表中进行语义搜索
• 概念关系可视化
• 自动推荐相关术语

质量评分参考

使用以下评分标准为每个定义打分（1–100 分）：

85–100：优秀

• 满足全部 4 项 ISO 11179 标准（每项 20 分以上）
• 长度合适（20–50 个词）
• 包含相关示例
• 语言清晰、明确
• 不存在循环依赖

70–84：良好

• 满足 3–4 项 ISO 标准
• 长度可接受（15–60 个词）
• 可能缺少示例
• 总体清晰
• 不存在严重问题

55–69：合格

• 满足 2–3 项 ISO 标准
• 长度存在问题（过短或过长）
• 在有帮助的情况下缺少示例
• 存在一些歧义
• 存在轻微循环引用

低于 55：需要修改

• 未满足多项 ISO 标准
• 长度存在严重问题
• 内容令人困惑或存在循环定义
• 缺少上下文
• 需要彻底重写

常见错误及规避方法

循环定义：

• 错误：“学习图是展示学习的图。”
• 正确：“一种概念有向图，反映概念的学习顺序。”

过于含糊：

• 错误：“教育中使用的一种东西。”
• 正确：“一种反映概念间先决关系的有向图。”

过长：

• 错误：“学习图是一种特殊类型的有向无环图结构，通常用于教育技术和教学设计场景中，以表示学生为实现特定学习成果而需要掌握的不同概念要素之间的层级和顺序关系。”
• 正确：“一种反映概念学习顺序的有向图，可用于掌握新概念。”

业务规则：

• 错误：“学生必须先完成先决概念，才能学习依赖这些概念的内容。”
• 正确：“一种展示概念间先决关系的有向图。”

未定义的术语：

• 错误：“使用 DAG 结构”（如果术语表中未定义 DAG）
• 正确：“使用有向无环图结构”

输出文件摘要

必需：

1. docs/glossary.md - 按字母顺序排列的完整术语表，定义符合 ISO 11179 标准

建议：

2. docs/learning-graph/glossary-quality-report.md - 质量评估和建议

可选：

3. docs/learning-graph/glossary-cross-ref.json - 用于语义搜索的 JSON 映射
4. 如果 mkdocs.yml 中缺少术语表链接，则更新导航

示例会话

用户：“根据我的概念列表生成一份术语表”

Claude（使用此技能）：

1. 读取概念列表文件和 docs/course-description.md（约 5K 个令牌）
2. 验证质量（检查重复项和格式）（约 1K 个令牌）
3. 启动一个串行 Task Agent，将所有定义写入 /tmp/glossary-raw.md（约 19K 个令牌）
4. 编写 Python 组装脚本 /tmp/assemble_glossary.py（约 500 个令牌）
5. 通过 Bash 运行脚本——脚本解析、排序并写入 docs/glossary.md（约 200 个令牌）
6. 使用 grep -c "^####" docs/glossary.md 验证术语数量（约 100 个令牌）
7. 按需更新 mkdocs.yml 导航（约 500 个令牌）
8. 报告：“已创建包含 350 个术语的术语表。为 70% 的术语添加了示例。”

**实测结果（2026-03-14）：**共生成并整理了 350 个术语，总计约 31K 个令牌。 每个术语约 88 个令牌（扣除 Agent 开销后约 54 个令牌），这是 目前可能达到的最高效方式。

**请记住：**子 Agent 负责生成文本（这是不可避免的大模型工作）。组装属于 编程任务——使用 sorted()，不要使用 Edit 工具。切勿使用并行 Agent。