back
loading skill details...
从PDF/Word文档提取6级以上层次化知识节点，标注节点类型与语义关系，输出可导入超星在线课程的CSV/Excel文件（支持最高7级）。触发场景：用户需要从文档抽取知识点、构建知识图谱、生成结构化教学数据、导出知识点层级关系。关键词：知识图谱、知识节点、知识树、教学大纲、课程标准、知识点抽取、层次化知识
---
name: knowledge-graph-extractor
description: 从PDF/Word文档提取6级以上层次化知识节点，标注节点类型与语义关系，输出可导入超星在线课程的CSV/Excel文件（支持最高7级）。触发场景：用户需要从文档抽取知识点、构建知识图谱、生成结构化教学数据、导出知识点层级关系。关键词：知识图谱、知识节点、知识树、教学大纲、课程标准、知识点抽取、层次化知识
---
# 文档知识图谱结构化抽取
## 功能概述
从 docx/pdf 文档中抽取层次化知识节点，标注节点类型和语义关系，输出可直接导入知识图谱系统的结构化文件。
**核心能力：**
- 抽出至少 6 级层次化知识节点（支持最高7级）
- 标注节点类型（分类/知识点）
- 识别语义关系（前置/后置/关联）
- 输出 CSV 和 Excel 格式文件
**技术架构：**
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 文档解析 │───→│ LLM 语义抽取 │───→│ 格式验证 │───→│ Excel 生成 │
│ (脚本) │ │ (LLM) │ │ (脚本) │ │ (脚本) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
│ │ │ │
▼ ▼ ▼ ▼
提取纯文本 语义理解+推理 验证格式约束 生成标准输出
解析模板 生成节点+关系 修复格式错误
```
## 输入参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| source_document | file | 是 | 待抽取的源文档，支持 docx/pdf 格式 |
| template_xlsx | file | 是 | 字段格式模板 xlsx 文件，需读取 A1 单元格的格式要求 |
---
## 使用步骤
### 步骤 1: 解析模板规则
**MANDATORY - 阅读整个文件**: 使用脚本解析模板，获取格式约束：
```bash
python scripts/extract_knowledge_graph.py --template template-knowledge-graph.xlsx --dry-run
```
**MANDATORY - 读取完整文件**: 阅读 [references/output-format.md](references/output-format.md) 了解列结构约束。
### 步骤 2: LLM 语义化知识抽取（核心步骤）
**此步骤由 LLM 执行语义理解和知识抽取。**
#### 2.1 读取 Prompt 模板
**MANDATORY - 读取完整文件**: 阅读 [references/extraction-prompt.md](references/extraction-prompt.md) 获取完整 Prompt 模板。
#### 2.2 执行 LLM 抽取
使用 [references/extraction-prompt.md](references/extraction-prompt.md) (~391 lines) 中的完整 Prompt 模板进行知识抽取。该模板包含所有抽取规则、字段说明和示例。
#### 2.3 LLM 抽取检查清单
抽取完成后，LLM 应自检：
- [ ] **节点顺序**：父节点在子节点之前，按深度优先顺序
- [ ] **节点类型正确**：Level 1-3="分类"，Level 4-7="知识点"
- [ ] **知识分类约束**：分类节点category为空，知识点节点填写分类值
- [ ] **教学目标完整性**：知识点的教学目标描述具体可衡量
- [ ] **排除教学管理信息**：未抽取课程性质、教学学时、评价标准等
- [ ] 每个知识点名称简洁准确（不超过30字）
- [ ] 层级正确反映知识的从属关系
- [ ] 前置关系符合学习逻辑
- [ ] 已过滤非知识内容
### 步骤 2.4: 质量校验与修正（重要）
**MANDATORY - Agent自检并自动修正**
**MANDATORY - READ ENTIRE FILE**: 阅读 [references/quality-check-prompt.md](references/quality-check-prompt.md) (~146 lines) 获取校验方法与修正指导。
抽取完成后，Agent必须执行质量校验。发现问题后，Agent直接修正JSON文件，无需用户干预。
#### 校验清单与修正规则
| # | 校验项 | 检查方法 | 问题判定 | 修正方法 |
|---|--------|----------|----------|----------|
| 1 | **教学目标覆盖** | Level 4-7节点是否都有objective | level≥4但objective为空或"无" | 根据节点内容生成教学目标，使用行为动词："能够..." |
| 2 | **教学目标质量** | 是否使用行为动词、是否具体可衡量 | "学会这个"、"了解"等模糊描述 | 改为具体目标："能够说出..."/"能够操作..."/"能够分析..." |
| 3 | **层级深度** | 最高层级是否达到≥6级 | max(level) < 6 | 在末级知识点下添加细分节点（6-7级） |
| 4 | **层级跳跃** | 是否存在断层（父→孙跳过子） | level从1直接到3，无level 2 | 补充缺失的中间层级节点 |
| 5 | **知识分类约束** | 分类节点category是否为空 | node_type="分类"但category有值 | 清空category字段 |
| 6 | **知识点分类覆盖** | Level 4-7节点是否有category | node_type="知识点"但category为空 | 根据内容填写：事实性/概念性/程序性/元认知 |
| 7 | **节点名称长度** | 是否超过30字 | len(name) > 30 | 缩短名称，保持核心含义 |
| 8 | **关联关系覆盖** | 知识点节点related是否为空数组 | 知识点无任何关联关系 | 补充同类/对比/相似原理的关联节点 |
| 9 | **节点顺序** | 是否按深度优先输出 | 子节点在父节点之前出现 | 调整JSON数组顺序：父→子→兄弟 |
| 10 | **列名结构** | Excel第二行是否与模板列名一致 | 任意列名与模板不符 | 警告提示，不自动修正（脚本硬编码） |
| 11 | **知识点子节点约束** | 知识点节点是否有下级节点 | 知识点有children | 自动修正为分类 |
#### 执行流程
```
1. Read 工具读取生成的 JSON 文件
2. 遍历所有节点，逐一检查上述11项
3. 发现问题 → 立即使用 Edit 工具修正
4. 修正完成后重新校验（循环直到全部通过）
5. 输出校验报告，确认所有项✅
```
如需查看校验示例，阅读 [references/quality-check-prompt.md](references/quality-check-prompt.md) 中的"校验示例"部分。
#### 校验通过标准
所有校验项必须全部通过：
| 校验项 | 通过标准 |
|--------|----------|
| 教学目标覆盖 | Level 4-7节点100%有objective |
| 教学目标质量 | 所有objective包含行为动词 |
| 层级深度 | max(level) ≥ 6 |
| 层级跳跃 | 父子层级连续，无断层 |
| 知识分类约束 | 分类节点category="" |
| 知识点分类覆盖 | 知识点节点category在有效值内 |
| 节点名称长度 | 所有节点名称≤30字 |
| 关联关系覆盖 | >50%知识点节点有related |
| 节点顺序 | 父节点在子节点之前（深度优先） |
| 列名结构 | Excel第二行列名与模板100%一致 |
| 知识点子节点约束 | 知识点节点无children（有children则自动修正为分类） |
#### 调用脚本校验（可选）
如需脚本辅助校验，可运行：
```bash
python scripts/extract_knowledge_graph.py \
--json knowledge_nodes.json \
--template template-knowledge-graph.xlsx \
--output output.xlsx \
--validate-only
```
脚本输出详细问题清单，Agent据此逐一修正。
### 步骤 3: 关系推理（可选增强）
**MANDATORY - READ ENTIRE FILE**: 阅读 [references/relation-prompt.md](references/relation-prompt.md) (~167 lines) 进行关系推理。模板包含前置关系和关联关系的完整识别规则。
**前置关系识别规则：**
| 模式 | 示例 |
|------|------|
| 基础概念 → 高级应用 | 电阻 → 欧姆定律 |
| 理论原理 → 实践操作 | 电路原理 → 电路安装 |
| 工具使用 → 应用场景 | 万用表使用 → 电流测量 |
**关联关系识别规则：**
| 模式 | 示例 |
|------|------|
| 同类并列 | 电阻 ↔ 电容 ↔ 电感 |
| 对比概念 | 直流电路 ↔ 交流电路 |
| 相似原理 | 欧姆定律 ↔ 基尔霍夫定律 |
### 步骤 4: 格式验证与 Excel 生成
将 LLM 输出的 JSON 数据传入脚本，生成 Excel 文件：
```bash
python scripts/extract_knowledge_graph.py \
--json knowledge_nodes.json \
--template template-knowledge-graph.xlsx \
--output output.xlsx
```
脚本自动验证：
- 节点类型正确（A列为"分类"或"知识点"）
- 每行只有一个节点名称 (B-H列)
- 分类节点M列为空
- 分隔符为英文分号
- 树状结构完整性
### 步骤 5: 输出结果
1. **output.xlsx** - 结构化抽取结果的 Excel 文件
2. **output.csv** - CSV 格式备份（可直接导入知识图谱工具）
3. **抽取统计** - 节点数量、层级分布、节点类型分布、关系类型等
---
### 列名固定约束
Excel 第二行的列名是固定不变的，由脚本生成时硬编码写入。列名对应关系如下：
| 列 | 固定列名 | 说明 |
|----|----------|------|
| A | 节点类型 | 分类 或 知识点 |
| B | 节点名称 | level1（模块/项目级） |
| C | 节点名称 | level2（章/单元/任务级） |
| D | 节点名称 | level3（节/知识主题/工序级） |
| E | 节点名称 | level4（知识点级） |
| F | 节点名称 | level5（细分级） |
| G | 节点名称 | level6（原子级） |
| H | 节点名称 | level7（精细级） |
| I | 前置节点 | 学习依赖的前置知识点 |
| J | 后置节点 | 前置关系的反向（自动生成） |
| K | 关联节点 | 相关但不构成依赖的知识点 |
| L | 标签 | 重点/难点/考点/课程思政 |
| M | 知识点分类 | 事实性/概念性/程序性/元认知 |
| N | 节点说明 | 知识点简要描述 |
| O | 教学目标 | 学习后应达成的能力 |
**重要**：请勿修改任何列名。下游系统（超星泛雅等）依赖这些列名进行数据导入。列名不匹配会导致导入失败。
---
## 输出格式核心约束
**核心原则（必须遵守）**：
- **每行只能填写一个节点名称**（树状结构，仅一个单元格有值）
- **分类节点 M列必须留空**（知识点分类仅适用于知识点节点）
- **任意两节点之间只能存在一种关系**（前置、后置或关联）
- **分隔符使用英文分号 `;`**（不使用中文分号 `；`）
**详细格式规则**：开始填充前，**MANDATORY - READ ENTIRE FILE**：
[`references/output-format.md`](references/output-format.md) (~289 lines)
**Do NOT load**：如果只是理解流程概念，不需要加载详细格式规则。只有实际生成输出时才需要加载。
---
## 关键 Anti-Patterns（重要）
**绝对禁止做这些 — 会导致导入失败：**
### 1. NEVER 分类节点填写知识分类
```
❌ 错误: A列="分类", M列="概念性"
✅ 正确: A列="分类", M列="" # 分类节点M列必须留空
```
**Why**: 模板规则明确：分类节点不支持填写知识点分类。
### 2. NEVER 一行填写多个节点名称
```
❌ 错误: ['一级节点', '二级节点', '三级节点', '', '', '', '', '']
✅ 正确: ['一级节点', '', '', '', '', '', '', ''] # 每行只有一个节点名称
```
**Why**: 导入系统使用树结构。每行表示 ONE 节点。位置表示层级。
### 3. NEVER 使用中文分号分隔关系
```
❌ 错误: 知识节点A；知识节点B；知识节点C
✅ 正确: 知识节点A;知识节点B;知识节点C
```
**Why**: 解析器期待 ASCII 分号 (`;`, U+003B)，不是中文分号 (`；`, U+FF1B)。
### 4. NEVER 填写多个知识分类
```
❌ 错误: M列 = "事实性;概念性"
✅ 正确: M列 = "事实性" # 单选值
```
**Why**: 知识分类字段是单选。多个值会导致导入失败。
### 5. NEVER 不完整的层级路径
```
❌ 错误:
行1: [B列: 模块]
行2: [D列: 章节] # 跳过了C列
✅ 正确:
行1: [B列: 模块]
行2: [C列: 单元]
行3: [D列: 主题]
```
**Why**: 每个知识节点必须有完整的父链。跳跃层级会破坏树结构。
### 6. NEVER 遗漏关联关系
```
❌ 错误: K列全部为空
✅ 正确: K列包含语义相关的知识点（同类、对比、相似原理）
```
**Why**: 关联关系是知识图谱的重要组成部分，缺失会降低图谱质量。
### 7. NEVER 修改Excel列名
```
❌ 错误: 修改Excel输出的第二行列名
✅ 正确: 保持脚本生成的标准列名不变
```
**Why**: 列名是硬编码的，用于下游系统导入。列名不匹配会导致导入失败。
### 8. NEVER 使用缩写名称作为关系引用
```
❌ 错误: "pre_requisites": ["半身裙结构图的绘制"] # 实际节点名缺少"与工业样板的制作"
✅ 正确: "pre_requisites": ["半身裙结构图的绘制与工业样板的制作"] # 与name完全一致
```
**Why**: 关系引用（I列前置节点、K列关联节点）按节点 name 字段精确匹配。名称不一致会被视为引用不存在的节点，导致关系丢失。
---
## 抽取决策框架
### LLM 抽取时应遵循的决策逻辑：
#### 1. 边界判断
**问题**: 这个节点能独立存在吗？
| 情况 | 判断 | 行动 |
|------|------|------|
| 概念过大 ("电路基础") | 太宽 | 拆分为多个子节点 |
| 细节过碎 ("电阻的单位") | 太窄 | 合并到上级节点 |
| 可独立理解 | 合适 | 保留为独立节点 |
#### 2. 层级定位
**问自己三个问题：**
```
Q1: 上级 - 这个节点属于哪个模块/章节？
Q2: 下级 - 这个节点包含哪些具体内容？
Q3: 平级 - 还有哪些同类节点？
```
#### 3. 节点类型判断
**根据层级自动判断节点类型**：
| 层级 | node_type | M列处理 |
|------|-----------|---------|
| Level 1-3 | "分类" | 留空 |
| Level 4-7 | "知识点" | 填写分类值 |
#### 4. 关系识别
**前置关系 (I列)**：
- 基础概念 → 高级概念 (电阻 → 欧姆定律)
- 工具使用 → 应用操作 (万用表 → 测量电流)
- 理论知识 → 实践技能 (电路原理 → 电路安装)
**关联关系 (K列)**：
- 同一主题下的并列节点 (电阻 ↔ 电容 ↔ 电感)
- 相似或对比概念 (直流电路 ↔ 交流电路)
- 不同章节但逻辑相关的节点
---
## 参考文件加载指引
### references 目录（工作流程参考）
| 文件 | 大小 | 加载时机 | Do NOT Load 情况 |
|------|------|----------|-----------------|
| [references/output-format.md](references/output-format.md) | ~289行 | 步骤1（必须） | 仅理解概念时 |
| [references/extraction-prompt.md](references/extraction-prompt.md) | ~15KB | 步骤2（必须） | 不执行抽取时 |
| [references/quality-check-prompt.md](references/quality-check-prompt.md) | ~5KB | 步骤2.4（可选） | 不执行校验时 |
| [references/relation-prompt.md](references/relation-prompt.md) | ~4KB | 步骤3（可选） | 不执行关系推理时 |
### examples 目录（示例模板与文档）
| 文件 | 大小 | 加载时机 | Do NOT Load 情况 |
|------|------|----------|-----------------|
| [examples/template-knowledge-graph.xlsx](examples/template-knowledge-graph.xlsx) | ~61KB | 步骤1（必须） | 已有用户提供的模板 |
| [examples/example-curriculum-office-software.pdf](examples/example-curriculum-office-software.pdf) | ~464KB | 演示/测试时 | 实际抽取任务时 |
**⚠️ 注意**：
- references 文件是 Agent workflow 的组成部分，Agent 需要读取它们来了解如何执行对应任务
- examples 文件仅用于演示和测试，实际抽取任务时应使用用户提供的文档
---
## 兼容性
- 可导入平台：超星泛雅和学银在线平台
- 源文档格式：docx、pdf
- 模版格式：xlsx
## 验证规则与提示信息
脚本在处理过程中会输出以下验证提示：
| 提示类型 | 说明 | 处理方式 |
|----------|------|----------|
| FILE_FORMAT_ERROR | 上传的文档格式不支持（仅接受 docx/pdf） | 检查文件格式 |
| JSON_PARSE_ERROR | LLM 输出的 JSON 格式无效或根元素不是数组 | 修正 JSON 格式 |
| HIERARCHY_WARNING | 层级深度不足：最高层级低于6级（⚠️ 警告，非硬性要求） | 建议在末级知识点下添加细分节点 |
| NODE_TYPE_INVALID | 节点类型无效："XX"，应为"分类"或"知识点" | 修正 A 列值 |
| CATEGORY_FOR_CLASSIFICATION | 分类节点的知识点分类(M列)必须为空 | 清空分类节点的 M 列 |
| RELATION_LOW_COVERAGE | 关联关系覆盖率低于50%（建议补充同类/对比关联节点） | 补充 K 列关联关系 |
| CHINESE_SEPARATOR | 使用中文分号"；"，应使用英文分号";" | 替换为英文分号 |
| MULTIPLE_NAMES_PER_ROW | 每行应只有1个节点名称，实际N个 | 每行只填写一个层级节点 |
---
## 故障排除
### 脚本执行失败
| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| `openpyxl` 未安装 | 缺少 Python 依赖 | `pip install openpyxl python-docx pdfplumber` |
| JSON 解析错误 | LLM 输出格式不符合要求 | 检查 JSON 是否为有效数组格式，确保根元素是 `[]` |
| 模板文件未找到 | `--template` 路径错误 | 确认模板文件路径，使用 `--dry-run` 测试 |
| Excel 生成失败 | 数据格式异常 | 检查 JSON 中是否有特殊字符 |
### LLM 抽取质量问题
| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| 层级深度不足（<6级） | 文档内容不够细 | 在末级节点下添加细分，或提供更详细的文档 |
| 节点类型判断错误 | level与node_type不匹配 | 检查 Level 1-3 是否设为"分类"，Level 4-7 设为"知识点" |
| 关系引用不匹配 | 名称不完全一致 | 确保 pre_requisites/related 与节点 name 完全一致 |
| 教学管理信息被抽取 | 未遵守排除规则 | 参照"排除内容"清单重新过滤 |
### 输出文件问题
| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| 导入超星平台失败 | 列名被修改 | 重新运行脚本生成，确保第二行列名与标准一致 |
| CSV 乱码 | 编码问题 | 脚本已使用 UTF-8 BOM 编码，检查导入平台编码设置 |
| 关系数超过2000条 | 节点间过度关联 | 减少不必要的关系，只保留有实际教学意义的关联 |
don't have the plugin yet? install it then click "run inline in claude" again.