知识框架梳理（Knowledge Framework Builder）

面向大学生 / 教师 / 自学者的三档深度 + 核心知识点提炼 + 概念依赖 + 节点级防幻觉溯源的知识脉络图生成 Skill。 支持多种输入格式（Markdown / DOCX / PDF / 图片截图 / URL），多种输出格式（Markdown / Markmap / Mermaid / OPML / PDF）。

---

何时触发

• 用户说："帮我把『大学英语 / 高数 / 机器学习 / 408』梳理成知识框架 / 知识脉络"
• 用户说："这本书的目录给你，帮我画成思维导图 / 重组成知识框架"
• 用户贴了一份 Markdown / DOCX 笔记 + 提了"帮我整理成框架"
• 用户问："这门课先学什么再学什么？/ XX 概念依赖什么？/ 哪些是核心知识点？"
• 用户说："我看书越看越乱 / 知识点太散记不住 / 想要一张清晰的知识框架"

不触发：

• 视频 / 音频内容（不支持，请先转为文字）
• 整本书 RAG 问答（超出范围，建议分章节提交）
• 通用 brainstorm 思维导图（请补充具体课程主题）
• 单次超过 1 门课程（请分课提交）

💡 支持多种输入格式：Markdown / DOCX / 纯文本 / PDF（文本层）/ 图片截图（OCR 识别）/ URL 网页。图像层 PDF / 扫描件质量较低时会提示用户确认，但不强制拒绝。

---

核心原则

1. 三档深度自动切换：用户不选档，Skill 按输入内容自动判断：

   • 仅提供课程主题 → skim（3-5 层知识框架 + AI 推荐 3 个延伸问题）
   • 含重点话题 / 学习目标 / 初学者标记 → skim + guided（追加 5-10 重点节点 200-500 字讲解 + 核心知识点提炼与总结）
   • 含 deep_explain: true → skim + guided + deep（追加叶子节点讲解；单批 ≤ 15，分批生成，超出时询问继续）
   • preferences.depth_hint 可强制覆盖（force_skim / force_guided / force_deep）

2. 节点级防幻觉溯源：含数字 / 专名 / 公式 / 名词的节点，

   • 用户材料模式：必须能 ngram 匹配到原文 → 标注来源文件 + 章节 + 原文片段
   • 纯主题模式：所有节点标注为 AI 推断，顶部强制 ⚠️ banner："本框架完全为 AI 推断，建议核对教材"
   • 推断字段（如"难点提示""易混点""考点分布"）必须单独标注

3. 概念依赖关系必须"克制"挖掘：

   • 限制条数：≤ 总节点数 × 0.3（防止过度连线）
   • 每条必带置信度（高 / 中 / 低），保守策略下只输出高置信度
   • 类型必须是 6 类之一：前置条件 / 归纳关系 / 细化关系 / 对比关系 / 应用关系 / 工具关系
   • 严禁生成 "A 和 B 有关系" 这种空话；每条必须给出具体依赖原因

4. 重点节点选择必须可解释：

   • 频次策略：用户材料中出现次数 ≥ 阈值（仅材料模式有效）
   • 中心度策略：依赖图中入度 / 出度排名前 N（默认，最稳健）
   • 混合策略：两种各取一半

5. 节点讲解 200-500 字：按用户水平调整：

   • 初学者 → 多用比喻 + 例子 + 类比生活
   • 中级（默认）→ 平衡术语和解释
   • 高级 → 直接用术语 + 强调难点和易混点

6. 多格式输出：

   • 默认输出 Markdown + Markmap（最通用，浏览器双击即开）
   • Mermaid 用于 GitHub / Notion / IDE 原生渲染
   • OPML 用于一键导入 XMind / 幕布精修
   • PDF 用于打印 / 分享 / 手机查看（生成完成后询问）
   • CDN 不可达时 markmap.html 自动降级为静态 SVG

7. 中文原生：中国用户为主，反馈全中文；保留 Markmap / Mermaid / OPML 等专有名词英文。

8. 多格式输入支持：支持 Markdown / DOCX / 纯文本 / PDF（文本层优先）/ 图片截图（OCR 识别）/ URL 网页（抓取正文）。图像层 PDF / 扫描件识别质量较低时，提示用户确认是否继续；识别结果标注为 ocr_extracted，提醒用户核对。

9. 单次处理上限 1 门课：超过 1 门课 / 节点数 > 100 → 拒绝并建议分课处理或按一级分支拆分。

10. 关键决策处人类确认（防自主失控）：以下 4 个高风险节点必须暂停等用户回应，绝不静默继续：

    • CP-A · 模式确认（Step 0 后）：当仅有课程主题（无材料）且属于常见教材类（大学英语 / 高数 / 408 / 考研政治等），提示 "这是高幻觉风险模式，建议补充教材目录；继续 / 补充材料 / 取消" 三选一；用户选「继续」才进入 Step 1。
    • CP-B · 触顶警示（Step 3 后 / Step 5 后）：若节点数 ≥ 90 或依赖条数 ≥ 总节点数 × 0.25，暂停并展示当前规模 + "继续生成 / 拆分课程 / 收紧策略" 三选一。
    • CP-C · 溯源高失配（Step 7 后）：当 >30% 节点无法匹配到材料原文，暂停并展示失配节点列表 + "材料不全请补充 / 接受当前 AI 推断标注 / 重新选材料范围" 三选一；绝不静默把多数节点标为 AI 推断。
    • CP-D · HTML 报告询问（Step 0 完成后立即询问，不等到最后）：主动询问用户是否需要 HTML 报告；默认选「是」（HTML 体验更好）；用户选「否」则仅输出 framework.md，不再追问。
    • 检查点统一原则：① 提供 ≤ 3 个枚举选项；② 用户沉默 / 任何拒绝 → 走默认安全路径（CP-A 默认取消，CP-B 默认拆分，CP-C 默认补充材料，CP-D 默认生成 HTML）；③ 不重复追问。

---

framework.md 内容规范

framework.md 是主资产，内容必须与 HTML 报告对等，不得是只有标题树的空壳。

必须包含以下节（按顺序）：

# 📚 [课程名] 知识框架

> ⚠️ 本框架由 AI 推断生成（纯主题模式时加此 banner）
> 🗓️ 生成时间：YYYY-MM-DD　　📐 深度档位：框架档 / 框架+重点讲解档 / 全节点档

---

## 📊 框架总览

[知识框架树，用 Markdown 标题层级或缩进列表表示]
[重点节点用 ⭐ 标注]

---

## 🔍 重点知识讲解（guided / deep 档时必有）

### ① [重点节点名]
📍 位置：[一级分支] > [二级分支]

[200-500 字讲解，含比喻/例子/类比]

📌 **核心要点**：[该节点的核心知识点提炼，1-3 条]

---

### ② [重点节点名]
（同上格式）

---

## 🔗 知识点关联图

| 关系类型 | 知识点 A | 知识点 B | 关联说明 |
|---------|---------|---------|--------|
| 前置条件 | ... | ... | ... |

---

## 💡 延伸学习建议

1. **[问题/方向]**：[对用户的价值说明]
2. **[问题/方向]**：[对用户的价值说明]
3. **[问题/方向]**：[对用户的价值说明]

禁止：只输出标题树而不含讲解、关联图、延伸建议节；这些节在对应档位下是必出内容，不是可选项。

---

关键反模式（NEVER 列表）

• NEVER 输出 "A 和 B 有关系" 这种空话依赖 — 每条依赖必须给出具体机制，置信度字段缺一不可。

  Bad:   { from: "前馈网络", to: "反向传播", reason: "两者有关系" }
  Good:  { from: "前馈网络", to: "反向传播", type: "前置条件", confidence: "高",
           reason: "反向传播是前馈网络训练算法的具体实现——前向计算输出 → 损失 → 反向链式法则求梯度" }
  

• NEVER 在 force_skim 时偷讲解 — 用户说"只给框架别讲解"时即使有重点话题也不升档；讲解列表必须为空。

  Bad:   框架下每个一级模块附 1-2 行"小科普"
  Good:  纯标题树，node_explanations: []
  

• NEVER 在溯源失配率 > 30% 时静默标 AI 推断 — 必须触发 CP-C 暂停并展示失配节点 Top 10，让用户三选一。

  Bad:   60% 节点匹配失败 → 全部默默改成 AI 推断后输出
  Good:  暂停 + 列出 10 条失配节点 + 请求用户决策
  

• NEVER 对低质量 OCR 结果静默继续 — 乱码率 > 20% 时必须暂停并展示识别样本，让用户确认是否继续。

  Bad:   扫描件 OCR 错误率 40% → 静默生成一份乱码节点的知识框架
  Good:  展示识别样本 + "识别质量较低，建议提供文本层文件。是否仍然继续？"
  

• NEVER 在节点 ≥ 90 触顶时静默截断或继续生成 — 必须触发 CP-B 让用户三选一。

  Bad:   生成 114 节点然后只保留前 100 输出
  Good:  CP-B 触顶警示 → 用户选 [1] 拆课 → 重做单课
  

• NEVER 在 deep 模式下让单批超 15 叶子 — 上下文溢出会让后半批讲解质量明显下降，必须分批。

  Bad:   在一次回复里硬塞 30 个叶子讲解，后 15 个明显敷衍
  Good:  优先选高价值前 15 → 标注截断 → 询问用户"继续下一批？"
  

---

工作流（9 步）

收到框架梳理请求后，严格按以下步骤执行。详细规则见 references/ 目录：

文档	用于步骤
references/framework-rubric.md	Step 3/4/6 内容质量自评
references/provenance-spec.md	Step 7 节点级溯源数据模型 + ngram 阈值
references/concept-dependency-taxonomy.md	Step 5 6 类依赖关系定义
references/prompt-templates.md	Step 3/4/5/6 Prompt 模板 + 自检 checklist
references/examples-index.md	few-shot 锚点指引
references/outline-parsing-heuristics.md	Step 2 材料解析启发式规则
references/input-schema.md / output-schema.md	完整 JSON Schema

┌─────────────────────────────────────────────────────────────────┐
│ Step 0  输入解析与模式判定                                        │
│   课程主题 必有 OR 材料文件 必有（≥ 1 个）                        │
│   都没提供 → 报错并给 3 个示例                                    │
│   无材料文件 → 纯主题模式（高幻觉风险，加 banner）                │
│   有材料文件 → 材料优先模式                                       │
│   两者都有 → 混合模式（材料优先 + 主题作为补全提示）              │
├─────────────────────────────────────────────────────────────────┤
│ ⏸ CP-A 模式确认（仅纯主题模式 + 常见教材类时）                    │
│   提示："检测到纯主题模式（高幻觉风险）。继续 / 补充材料 / 取消？"│
│   沉默 / 拒绝 → 默认取消；选「继续」才进 Step 1                   │
├─────────────────────────────────────────────────────────────────┤
│ ⏸ CP-D 输出格式询问（Step 0 完成后立即询问，不等到最后）           │
│   "📋 好的！开始梳理知识框架。需要同时生成 HTML 报告吗？           │
│    HTML 报告含折叠节点 + 重点讲解 + 知识点关联图，浏览器直接查看。 │
│    □ 是，生成 HTML 报告                                            │
│    □ 否，仅生成 Markdown 文档"                                     │
│   未选 / 沉默 → 默认「是」（主动生成 HTML，体验更好）              │
│   用户选「否」→ 仅输出 framework.md，不追问                        │
├─────────────────────────────────────────────────────────────────┤
│ Step 1  深度档位确认│   depth_hint != auto → 按 hint 强制                              │
│   depth_hint == auto → 按输入内容自动判断                         │
│   永远含 skim；guided / deep 按规则叠加                            │
├─────────────────────────────────────────────────────────────────┤
│ Step 2  材料解析（仅当有材料文件时）                               │
│   run: python scripts/parse_outline.py {input}                   │
│   markdown → ATX `#` + Setext `===`（零外部依赖）                │
│   docx → 标准库 zipfile + xml.etree + Heading 1-5 样式（降级）   │
│   txt / pasted_text → 7 套启发式回退（章节/数字/§/中文序号/字母）│
│   pdf（文本层）→ 提取文本后解析                                   │
│   image / 截图 → 调用 OCR 工具识别后解析（低质量时提示确认）      │
│   webpage / URL → 抓取正文后解析                                  │
│   video / audio → 拒绝，提示用户先转为文字                        │
│   见 references/outline-parsing-heuristics.md                    │
├─────────────────────────────────────────────────────────────────┤
│ Step 3  框架生成（skim，必出）                                     │
│   读 references/framework-rubric.md                               │
│   读 references/prompt-templates.md §1（skim 框架模板）           │
│   纯主题模式：LLM 生成 3-5 层框架                                 │
│   材料优先模式：以材料大纲为准 + AI 补全缺失子节点                │
│   混合模式：以材料为准 + 主题作为"是否漏了什么"的反向核对         │
│   生成延伸学习建议（默认 3 条）                                    │
│   每条延伸建议附说明（回答这个问题对用户的价值）                   │
├─────────────────────────────────────────────────────────────────┤
│ ⏸ CP-B 触顶警示（节点数 ≥ 90 时）                                  │
│   "框架已含 N 节点，逼近 100 上限。继续生成 / 拆分课程 /           │
│   收紧到 3 层？" 沉默 → 默认拆分课程并提示重提交                   │
├─────────────────────────────────────────────────────────────────┤
│ Step 4  重点节点选择与讲解（若深度含 guided）                      │
│   按重要度策略挑 5-10 个重点节点（默认中心度策略）                 │
│   用户指定重点话题时 → 优先在这些主题分支选                        │
│   每个重点节点写 200-500 字讲解，按用户水平调整语气                │
│   必含【核心要点】：该节点的核心知识点提炼与总结（必须具体）       │
│   严禁产出无具体内容的空泛节点                                     │
│   ⚠️ 报告输出规范（HTML 面向用户，不得暴露内部术语）：            │
│     · 讲解节点标题用 ①②③ 序号，不暴露内部字段名                 │
│     · 路径用 📍 前缀 + 自然语言描述                               │
│     · 章节标题用「重点知识讲解」                                   │
│     · 每条讲解末尾必须有绿色「📌 核心要点：」总结块               │
├─────────────────────────────────────────────────────────────────┤
│ Step 5  概念依赖关系挖掘（若策略 != off）                          │
│   读 references/concept-dependency-taxonomy.md                    │
│   读 references/prompt-templates.md §3（依赖挖掘模板）            │
│   LLM 跨分支挖掘 6 类依赖；限制 ≤ 总节点数 × 0.3                  │
│   保守策略：只输出高置信度；激进策略：输出中置信度及以上           │
│   每条必带具体依赖原因 + 来源标注 + 置信度                         │
│   材料模式：优先挖掘材料里相邻段落 / 章节的关系                    │
│   ⚠️ 报告输出规范（HTML 面向用户）：                              │
│     · 章节标题用「知识点关联图」                                   │
│     · 依赖类型在表格/图中用中文标签：                             │
│       前置条件 / 对比关系 / 细化关系 / 应用关系 / 归纳关系 / 工具关系│
│     · 表头用「关系类型/知识点A/知识点B/关联说明」                  │
├─────────────────────────────────────────────────────────────────┤
│ Step 6  deep 全节点讲解（若深度含 deep）                           │
│   目标：所有叶子节点都生成 200-500 字讲解                          │
│   分批约束：单批 ≤ 15 叶子；超过时按重要度优先选高价值节点         │
│     其余批次标注截断 + 提示用户"继续下一批？"                      │
│   可选结构化字段：                                                 │
│     · cross_ref：与其他节点的关联指针（易混点的客观化表达）        │
│     · drill：结构化练习题（含题目 + 参考答案）                     │
├─────────────────────────────────────────────────────────────────┤
│ Step 7  溯源审计（防幻觉闭环，内部执行，不输出给用户）             │
│   run: python scripts/verify_provenance.py                        │
│   规则见 references/provenance-spec.md                            │
│   材料优先 / 混合模式：每节点对材料做 ngram 校验                   │
│     · 匹配成功 → 标注来源文件 + 章节 + 原文片段                    │
│     · 匹配失败 → 标注 AI 推断 + 标记 ⚠️                           │
│   纯主题模式：所有节点标注为 AI 推断                               │
│     · 顶部加 banner："本框架完全为 AI 推断，建议核对教材"          │
│   推断字段（"难点提示""易混点"等）必须单独标注                    │
│   输出 provenance-audit.json（仅内部存档，不在 HTML 报告中展示）   │
│   ⚠️ HTML 报告中不得出现"溯源审计""ngram""失配率"等内部术语      │
│      纯主题模式的 AI 推断 banner 用用户语言：                      │
│      「⚠️ 本框架由 AI 根据课程主题推断生成，建议核对教材后使用」   │
├─────────────────────────────────────────────────────────────────┤
│ ⏸ CP-C 溯源高失配（失配率 > 30% 时）                               │
│   暂停并展示失配节点 Top 10 + "材料不全请补充 / 接受当前 AI 推断  │
│   标注 / 重新选材料范围？" 沉默 → 默认请用户补充材料               │
│   绝不静默把多数节点标 AI 推断后继续                               │
├─────────────────────────────────────────────────────────────────┤
│ Step 8  多格式渲染（按输出格式偏好）                               │
│   run: python scripts/render_outputs.py                           │
│   markdown   → framework.md（主资产）                             │
│   markmap    → framework.markmap.html（CDN + 离线降级）            │
│   mermaid    → framework.mermaid.md（mindmap + flowchart）         │
│   opml       → framework.opml（导入 XMind / 幕布）                │
│   默认输出 markdown + markmap                                      │
│   注：PDF 输出在 Step 9 CP-D 询问时提供选项                        │
├─────────────────────────────────────────────────────────────────┤
│ Step 9  HTML 报告渲染（若 CP-D 用户选「是」）                       │
│   模板：assets/report-template.html（占位符替换式渲染）             │
│   产物：./reports/framework-reports/<ts>-<slug>.html                │
│   若用户同时需要 PDF，在 HTML 生成后追加询问一次                    │
│   ⚠️ HTML 报告结构规范（面向用户，不含内部术语）：                 │
│     · Hero pills 用用户语言：「基于大纲原文生成」「框架+重点讲解」 │
│     · 目录 4 节：知识框架总览/重点知识讲解/知识点关联图/延伸学习   │
│     · 延伸学习（原延伸建议）放最后一节                              │
│     · 框架树中只用 ⭐ 重点 徽章，不用内部字段名标签                │
│     · 不含「溯源审计」「输入与配置摘要」两节                        │
└─────────────────────────────────────────────────────────────────┘

---

三档深度速查

用户输入	自动档位	输出内容
仅课程主题	框架档	知识框架树 + 延伸学习建议
课程主题 + 重点话题	框架档 + 重点讲解档	+ 5-10 个重点节点讲解（含核心知识点提炼）+ 知识点关联图
课程主题 + 材料文件	框架档 + 重点讲解档*	+ 全节点溯源标注 + 核心重点提炼
任一配置 + deep_explain: true	框架档 + 重点讲解档 + 全节点档	叶子节点讲解（分批 ≤15；可选关联指针 + 练习题）

*：有材料文件时默认升档到重点讲解档，因为材料提供了足够上下文

强制覆盖：

• force_skim → 即使提供了重点话题也只出框架
• force_guided → 即使没有重点话题，AI 自动挑 5 个高价值节点深入
• force_deep → 全叶子节点都讲解（分批 ≤15，超出询问继续）

---

输入规范

完整 schema 见 references/input-schema.md。核心字段：

字段	必填	说明
course_topic	⚠️	课程主题字符串（如 "大学英语"），与 material_files 至少一个
material_files	⚠️	数组；来源类型支持 markdown / docx / txt / pasted_text / pdf / image / url，与 course_topic 至少一个
context.focus_topics	可选	数组（如 ["语法", "听力技巧"]），触发重点讲解档自动升档
context.learning_goal	可选	自然语言（如 "通过 CET-4"），影响讲解侧重
context.user_level	可选	beginner / intermediate（默认）/ advanced，影响讲解语气
preferences.depth_hint	可选	auto（默认）/ force_skim / force_guided / force_deep
preferences.concept_dependency_strategy	可选	off / conservative（默认）/ aggressive
preferences.importance_strategy	可选	frequency / centrality（默认）/ mixed
preferences.output_formats	可选	数组，默认 ["markdown", "markmap"]，可选 mermaid / opml / pdf
preferences.language	可选	zh（默认）/ en / bilingual

---

输出结构

完整 schema 见 references/output-schema.md。

./framework-output/<timestamp>-<slug>/
├── result.json                      # 结构化总结果
├── framework.md                     # Markdown 大纲（主资产）
├── framework.markmap.html           # Markmap 单文件交互式思维导图
├── framework.mermaid.md             # Mermaid mindmap + flowchart 代码
├── framework.opml                   # OPML 2.0（导入 XMind / 幕布）
├── node-explanations/               # 重点讲解档 / 全节点档下的节点讲解
├── concept-dependencies.md          # 知识点关联图（表格 + Mermaid flowchart）
├── provenance-audit.json            # 节点级溯源审计（内部存档）
└── (按需) report.html               # 一体化 HTML 报告（Step 9 主动询问后生成）

result.json 顶层字段：meta / inputs_summary / framework_tree / node_explanations / concept_dependencies / recommended_questions / provenance_summary / warnings / next_step_hint。