faq-generator

常见问题生成器

版本： 1.0

根据教材内容生成全面、分类整理的常见问题，以及适用于聊天机器人的 JSON 导出文件。将常见问题放入文件 docs/faq.md。将本次会话的结果记录到 logs/faq.md。

目的

此技能通过分析课程内容、学习图谱和术语表，自动为智能教材创建常见问题，生成相关的问题和答案。此技能会按类别和难度整理问题，确保布卢姆分类法各认知层级的问题分布均衡，提供附有源内容链接的答案，并导出可供 RAG 系统集成的结构化 JSON 数据。

何时使用此技能

满足以下条件后使用此技能：

1. 课程描述已定稿，质量评分高于 70
2. 已创建学习图谱
3. 已生成术语表
4. 至少已完成 30% 的章节内容

具备这些前提条件，才能确保常见问题生成器拥有充足的上下文来创建有意义且相关的问题。以下情形可触发此技能：

• 为新教材创建初始常见问题
• 添加大量内容后更新常见问题
• 为聊天机器人或 AI 助手集成准备内容
• 识别现有内容中的知识缺口

Markdown 格式

1. 使用一级 Markdown 标题（#）作为常见问题标题
2. 使用二级 Markdown 标题（##）作为各个类别的标题
3. 使用三级 Markdown 标题（###）作为各个问题的标题
4. 在正文中写出答案

使用技能参考部分中的 faq-template.md 作为模板。

重要规则：不要使用锚点链接

!!! warning "切勿使用锚点链接" 所有链接都必须仅指向文件，不得包含 # 锚点片段。

锚点链接（`file.md#section-name`）经常会失效，原因如下：

- 编辑内容时，章节标题会发生变化
- 锚点区分大小写和空格
- MkDocs 自动生成锚点的规则不可预测
- 失效的锚点会导致构建警告，并使用户困惑

✅ **正确：** `[See Ohm's Law](chapters/02-ohms-law/index.md)`

❌ **错误：** `[See Ohm's Law](chapters/02-ohms-law/index.md#series-circuits)`

工作流

步骤 1：评估内容完整度

按 1-100 分计算内容完整度，以确定生成常见问题的可行性：

必需输入：

1. 阅读 docs/course-description.md

   • 检查是否包含：标题、受众、先修要求、学习成果
   • 确认是否包含布卢姆分类法学习成果
   • 完整时得分：25 分

2. 阅读 docs/learning-graph/03-concept-dependencies.csv

   • 验证 DAG 结构（无环）
   • 统计概念和依赖关系的数量
   • DAG 有效且连接性良好时得分：25 分

3. 阅读 docs/glossary.md

   • 统计术语数量（50 个以上为良好，100 个以上为优秀）
   • 100 个以上得 15 分，50-99 个得 10 分，少于 50 个得 5 分

4. 扫描所有 docs/**/*.md 文件

   • 计算总词数
   • 目标：达到 10,000 词以上，以生成全面的常见问题
   • 达到 10k 以上得 20 分，5k-10k 得 15 分，少于 5k 得 10 分

5. 计算概念覆盖率

   • 学习图谱中的概念有多少百分比在相关章节内容中有所涉及？
   • 达到 80% 以上得 15 分，60-79% 得 10 分，低于 60% 得 5 分

内容完整度评分区间：

• 90-100：所有输入均已提供且质量较高
• 70-89：核心输入均已提供，但存在部分内容缺口
• 50-69：缺少可选输入或词数较少
• 低于 50：缺少关键输入

用户对话触发条件：

• 评分低于 60：询问“可用内容有限，无法充分生成常见问题。要继续生成基础常见问题，还是等待补充更多内容？”
• 没有术语表：询问“未找到术语表。要继续生成常见问题（技术问题会较少），还是先创建术语表？”
• 词数较少：询问“仅找到 [N] 词的内容。常见问题的质量可能有限。要继续吗？”

如果用户同意在评分低于 60 时继续，则生成常见问题，但需在质量报告中加入内容有限的免责声明。

第 2 步：分析内容，寻找可提问的主题

阅读并分析所有内容来源，以识别常见的问题模式：

从课程描述中提取：

• “这门课程讲什么？”（范围）
• “这门课程适合谁？”（受众）
• “我会学到什么？”（学习成果）
• “我需要先掌握哪些知识？”（先修要求）

从学习图谱中提取：

• “[概念]是什么？”（定义类问题）
• “[概念 A]与[概念 B]有什么关系？”（关系类问题）
• “学习[概念]之前，我需要先了解什么？”（先修知识类问题）
• “学完[概念]之后要学什么？”（学习进阶类问题）

从术语表中提取：

• “[术语]是什么意思？”（术语类问题）
• “[术语 A]和[术语 B]有什么区别？”（比较类问题）
• “能举一个[术语]的例子吗？”（应用类问题）

从章节内容中提取：

• 识别反复出现的主题或话题
• 留意学生可能遇到困难的领域（复杂概念）
• 提取提及的常见误解
• 查找实际应用示例

从现有 FAQ 中提取（如果有）：

• 如果 docs/faq.md 存在，请阅读
• 保留人工整理的问题
• 与新生成的问题合并
• 删除重复项；如有冲突，保留人工整理的版本

第 3 步：生成问题类别

创建 6 个符合学习进阶规律的标准类别。有关如何在布鲁姆分类法的各个层级撰写问题（问题开头、答案特征、常见错误）的详细指南，请阅读规范参考资料 $BK_HOME/skills/chapter-content-generator/references/blooms-taxonomy.md。

1. 入门问题（10-15 个问题）

布鲁姆分类法目标层级：60% 记忆，40% 理解

• 课程概览和目标
• 先修要求和准备工作
• 如何使用教材
• 导航和结构
• 所需时间和难度

2. 核心概念问题（20-30 个问题）

布鲁姆分类法目标层级：20% 记忆，40% 理解，30% 应用，10% 分析

• 学习图谱中的关键概念（优先选择中心性高的节点）
• 基本原理
• 概念间的关系和依赖
• 概念之间如何层层递进

3. 技术细节问题（15-25 个问题）

布鲁姆分类法目标层级：30% 记忆，40% 理解，20% 应用，10% 分析

• 术语表中的术语
• 定义和解释
• 技术比较
• 规范细节

4. 常见挑战（10-15 个问题）

布鲁姆分类法目标层级：10% 记忆，30% 理解，40% 应用，20% 分析

• 需要额外解释的难懂概念
• 常见误解
• 故障排除场景
• 错误解决

5. 最佳实践问题（10-15 个问题）

布鲁姆分类法目标层级：10% 理解，40% 应用，30% 分析，15% 评价，5% 创造

• 如何有效应用概念
• 推荐方法
• 何时使用特定技术
• 现实应用

6. 高级主题（5-10 个问题）

布鲁姆分类法目标层级：10% 应用，30% 分析，30% 评价，30% 创造

• 复杂集成
• 边界情况
• 性能优化
• 未来方向

第 4 步：生成问题和答案

针对每个类别，按照以下指南生成问题：

问题格式：

• 使用二级标题（##）
• 写成实际问题（以 ? 结尾）
• 让问题具体且便于搜索
• 使用术语表中的术语
• 问题保持简洁（5-15 个词）

答案格式：

• 每个问题使用三级 Markdown 标题（###）
• 撰写完整、独立的答案
• 40% 的答案中包含示例
• 链接到相关章节（目标：60% 以上的答案包含链接）
• 目标长度：100-300 个词
• 使用清晰、直接的语言
• 完整回答问题

布鲁姆分类法指南：

记忆： 回忆事实、术语和基本概念

• “什么是[概念]？”
• “[术语]是什么意思？”
• “[系统]由哪些组件构成？”

理解： 解释观点或概念

• “[概念]如何运作？”
• “为什么[概念]很重要？”
• “[A] 和 [B] 有什么区别？”

应用： 在新情境中使用信息

• “如何[执行任务]？”
• “什么时候应该使用[技术]？”
• “[概念]在实践中的应用示例是什么？”

分析： 理清观点之间的联系

• “[A] 和 [B] 之间有什么关系？”
• “[概念]与[其他概念]有什么联系？”
• “[问题]的根本原因是什么？”

评价： 论证某个决定或立场

• “对于[场景]，哪种方法最好？”
• “[技术]有哪些权衡？”
• “如何在 [A] 和 [B] 之间做出选择？”

创造： 创作新的或原创的内容

• “如何设计一个满足[要求]的[系统]？”
• “组合[概念]的最佳方式是什么？”
• “如何将[技术]改用于[新情境]？”

答案质量检查清单：

• 为标题、类别和问题使用正确的 Markdown 标题
• 直接回答问题
• 始终使用术语表中的术语
• 如果概念抽象，则包含示例（目标为 40%）
• 链接到相关章节文件（目标为 60%）——不得包含锚点片段
• 长度适当（100-300 个词）
• 对目标受众而言清晰易懂
• 符合教材内容，准确无误
• 除非已在术语表中定义，否则不使用行话
• 链接中不得包含 # 锚点（硬性要求）

第 5 步：创建 FAQ 文件

生成 docs/faq.md，并使用正确的结构：

# [Course Name] FAQ

## Getting Started Questions

### What is this course about?

[Answer with overview, linking to course description]

### Who is this course for?

[Answer describing target audience]

[Continue with 10-15 Getting Started questions...]

## Core Concepts

### What is a [Key Concept]?

[Answer with definition and example, linking to chapter]

[Continue with 20-30 Core Concepts questions...]

## Technical Detail Questions

[Continue with terminology and technical questions...]

## Common Challenge Questions

[Continue with troubleshooting questions...]

## Best Practice Questions

[Continue with application questions...]

## Advanced Topic Questions

[Continue with advanced questions...]

格式要求：

• 标题使用一级标题
• 类别名称使用二级标题
• 问题使用三级标题
• 答案使用正文文本
• 使用 Markdown 链接指向章节文件：[text](path.md)——绝不使用锚点链接
• 使用粗体强调重点：**important term**
• 代码使用代码块：` language
• 保持间距一致

重要：不得使用锚点链接

绝不在链接中添加锚点片段（#section-name）。锚点经常失效，原因如下：

• 编辑时章节标题会发生变化
• 锚点区分大小写和空格
• MkDocs 生成锚点的方式不可预测
• 锚点失效会导致构建警告并使用户困惑

✅ 正确： [Ohm's Law](chapters/02-ohms-law/index.md) ❌ 错误： [Ohm's Law](chapters/02-ohms-law/index.md#series-circuits)

只链接到章节文件。用户可以自行在页面内导航。

第 6 步：生成聊天机器人训练 JSON

为 RAG 集成创建 docs/learning-graph/faq-chatbot-training.json：

{
  "faq_version": "1.0",
  "generated_date": "YYYY-MM-DD",
  "source_textbook": "Course Name",
  "total_questions": 87,
  "questions": [
    {
      "id": "faq-001",
      "category": "Getting Started",
      "question": "What is this course about?",
      "answer": "Full answer text here...",
      "bloom_level": "Understand",
      "difficulty": "easy",
      "concepts": ["Course Overview", "Learning Objectives"],
      "keywords": ["course", "overview", "objectives", "goals"],
      "source_links": [
        "docs/course-description.md",
        "docs/index.md"
      ],
      "has_example": false,
      "word_count": 142
    },
    {
      "id": "faq-002",
      "category": "Core Concepts",
      "question": "What is a Learning Graph?",
      "answer": "A Learning Graph is...",
      "bloom_level": "Understand",
      "difficulty": "medium",
      "concepts": ["Learning Graph", "Concept Dependency"],
      "keywords": ["learning graph", "dependencies", "prerequisites"],
      "source_links": [
        "docs/concepts/learning-graph.md",
        "docs/glossary.md"
      ],
      "has_example": true,
      "word_count": 218
    }
  ]
}

JSON 架构要求：

• 每个问题都有唯一 ID（faq-001、faq-002 等）
• 类别必须与 6 个标准类别之一匹配
• 布鲁姆层级来自 6 层分类法
• 难度：简单、中等、困难
• 概念列表来自学习图谱
• 包含用于搜索优化的关键词
• 包含指向原始内容的源链接
• 包含用于标记是否有示例的布尔值
• 包含答案的词数

第 7 步：生成质量报告

创建 docs/learning-graph/faq-quality-report.md：

# FAQ Quality Report

Generated: YYYY-MM-DD

## Overall Statistics

- **Total Questions:** 87
- **Overall Quality Score:** 82/100
- **Content Completeness Score:** 78/100
- **Concept Coverage:** 73% (145/198 concepts)

## Category Breakdown

### Getting Started
- Questions: 12
- Avg Bloom's Level: Remember/Understand
- Avg Word Count: 156

[Continue for all categories...]

## Bloom's Taxonomy Distribution

Actual vs Target:

| Level | Actual | Target | Deviation |
|-------|--------|--------|-----------|
| Remember | 18% | 20% | -2% ✓ |
| Understand | 32% | 30% | +2% ✓ |
| Apply | 24% | 25% | -1% ✓ |
| Analyze | 16% | 15% | +1% ✓ |
| Evaluate | 7% | 7% | 0% ✓ |
| Create | 3% | 3% | 0% ✓ |

Overall Bloom's Score: 25/25 (excellent distribution)

## Answer Quality Analysis

- **Examples:** 38/87 (44%) - Target: 40%+ ✓
- **Links:** 54/87 (62%) - Target: 60%+ ✓
- **Avg Length:** 187 words - Target: 100-300 ✓
- **Complete Answers:** 87/87 (100%) ✓

Answer Quality Score: 24/25

## Concept Coverage

**Covered (145 concepts):** [list]

**Not Covered (53 concepts):**
- [Concept 1] - Priority: High (high centrality in learning graph)
- [Concept 2] - Priority: Medium
- [Concept 3] - Priority: Low

Coverage Score: 22/30 (73% coverage)

## Organization Quality

- Logical categorization: ✓
- Progressive difficulty: ✓
- No duplicates: ✓
- Clear questions: ✓

Organization Score: 20/20

## Overall Quality Score: 82/100

- Coverage: 22/30
- Bloom's Distribution: 25/25
- Answer Quality: 24/25
- Organization: 20/20

## Recommendations

### High Priority
1. Add questions for high-centrality concepts: [list top 10]
2. Slightly increase Remember-level questions (+2%)

### Medium Priority
1. Add examples to 3 more answers (to reach 47%)
2. Link 5 more answers to source content

### Low Priority
1. Consider adding 2-3 more Advanced Topics questions
2. Review question phrasing for searchability

## Suggested Additional Questions

Based on concept gaps, consider adding:

1. "What is [Uncovered Concept 1]?" (Core Concepts)
2. "How does [Uncovered Concept 2] work?" (Technical Details)
[Continue with top 10 suggestions...]

第 8 步：生成覆盖缺口报告

创建 docs/learning-graph/faq-coverage-gaps.md：

# FAQ Coverage Gaps

Concepts from learning graph not covered in FAQ.

## Critical Gaps (High Priority)

High-centrality concepts (many dependencies) without FAQ coverage:

1. **[Concept Name]**
   - Centrality: High (12 dependencies)
   - Category: Core Concepts
   - Suggested Question: "What is [Concept] and why is it important?"

[Continue for all high-priority gaps...]

## Medium Priority Gaps

Moderate-centrality concepts without FAQ coverage:

[Continue...]

## Low Priority Gaps

Leaf nodes or advanced concepts without FAQ coverage:

[Continue...]

## Recommendations

1. Add questions for all critical gaps (15 concepts)
2. Consider adding questions for medium priority (23 concepts)
3. Low priority can be addressed in future updates (15 concepts)

Step 9: 验证输出质量

执行全面验证：

1. 唯一性检查：

• 扫描所有问题，查找重复项
• 检查近似重复项（相似度 >80%）
• 报告发现的任何重复项

2. 链接验证：

• 提取答案中的所有 Markdown 链接
• 拒绝任何包含 # 锚点片段的链接——必须将其移除
• 验证每个链接目标文件是否存在
• 报告失效链接
• 链接只能指向文件（例如，chapters/01-intro/index.md），不能包含锚点

3. Bloom 分类分布：

• 计算所有问题的实际分布
• 与目标分布进行比较
• 根据偏差评分（±10% 可接受）

4. 阅读难度：

• 计算答案的 Flesch-Kincaid 年级水平
• 确认难度适合目标受众
• 标记过于复杂或过于简单的答案

5. 答案完整性：

• 检查每个答案是否回应了问题
• 确认答案没有不完整或只回答一部分的情况
• 确保提供了恰当的上下文

6. 技术准确性：

• 根据术语表交叉核对术语
• 确认内容与章节内容一致
• 标记任何矛盾或不准确之处

成功标准：

• 总体质量得分 > 75/100
• 至少生成 40 个问题
• 概念覆盖率至少达到 60%
• Bloom 分类法分布均衡（偏差不超过 ±15%）
• 所有答案均包含来源引用
• 聊天机器人 JSON 通过架构验证
• 无重复问题
• 所有内部链接有效（文件存在）
• 无锚点链接——任何链接中都不能包含 # 片段

Step 10: 更新 mkdocs.yml 中的导航部分（可选）

如果 - FAQ: faq.md 尚未添加到 nav: 中，请在靠近末尾的位置添加（与 Glossary 相邻），并在 Learning Graph: 下添加任何质量报告 （faq-quality-report.md、faq-coverage-gaps.md）。遵循 $BK_HOME/skills/book-installer/references/mkdocs-nav-editing.md 中的规范 导航编辑规则。

质量评分参考

使用此评分标准计算 FAQ 的总体质量得分（1-100）：

覆盖率（30 分）：

• 概念覆盖率达到 80% 及以上：30 分
• 70-79%：25 分
• 60-69%：20 分
• 50-59%：15 分
• <50%：10 分

Bloom 分类法分布（25 分）：

计算每个层级与目标的偏差，并将绝对偏差相加：

• 总偏差为 0-10%：25 分
• 总偏差为 11-20%：20 分
• 总偏差为 21-30%：15 分
• 总偏差 >30%：10 分

答案质量（25 分）：

• 示例：占比达到 40% 及以上 = 7 分，30-39% = 5 分，<30% = 3 分
• 链接：占比达到 60% 及以上 = 7 分，50-59% = 5 分，<50% = 3 分
• 长度：平均 100-300 个词 = 6 分，可接受范围 = 4 分
• 完整性：100% = 5 分，95-99% = 4 分，<95% = 2 分

组织（20 分）：

• 分类合理：5 分
• 难度逐步递进：5 分
• 无重复项：5 分
• 问题清晰：5 分

应避免的常见问题

重复问题：

• 不要在不同类别中提出相同的问题
• 对相关概念采用不同的表述方式
• 将相似问题合并为一个全面的答案

答案不完整：

• 不要只回答问题的一部分
• 不要只说“详情请参阅第 X 章”，而不提供摘要
• 始终提供可独立理解的上下文

缺少链接：

• 不要忘记将答案链接到源内容
• 仅链接到章节文件——绝不要使用锚点片段（#section-name）
• 定稿前确认所有链接都指向现有文件

失效锚点链接：

• 绝不要使用 file.md#section-name 这样的锚点链接
• 编辑、重命名或重构标题后，锚点会失效
• 只链接到章节或页面文件：file.md
• 这是硬性规则，无一例外

问题表述不佳：

• 避免“How does it work?”这类含糊的问题
• 使用术语表中的具体术语
• 确保问题便于搜索

Bloom 分类失衡：

• 不要过度侧重记忆/理解层级
• 加入高阶思维问题
• 均衡覆盖全部 6 个层级

输出文件摘要

必需：

1. docs/faq.md - 按类别整理的完整常见问题及解答

推荐：

2. docs/learning-graph/faq-quality-report.md - 质量指标和建议
3. docs/learning-graph/faq-chatbot-training.json - 面向 RAG 系统的结构化数据

可选：

4. docs/learning-graph/faq-coverage-gaps.md - 尚未覆盖常见问题的概念
5. 如果导航中缺少常见问题链接，则更新 mkdocs.yml

示例会话

用户：“为我的教科书生成常见问题”

Claude（使用此技能）：

1. 评估内容完整度（得分：78/100）
2. 阅读课程描述、学习图谱、术语表和章节
3. 确定可提出问题的主题
4. 在 6 个类别中生成 87 个问题
5. 编写答案，其中 44% 包含示例，62% 包含链接
6. 导出聊天机器人训练 JSON
7. 生成质量报告（得分：82/100）
8. 生成覆盖缺口报告（53 个未覆盖的概念）
9. 报告：“已创建常见问题，包含 87 个问题，覆盖 73% 的概念。总体质量：82/100。添加了 38 个示例和 54 个链接。建议请参阅质量报告。”