---

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 - 閱讀整個檔案: 使用指令碼解析模板，獲取格式約束：

python scripts/extract_knowledge_graph.py --template template-knowledge-graph.xlsx --dry-run

MANDATORY - 讀取完整檔案: 閱讀 references/output-format.md 瞭解列結構約束。

步驟 2: LLM 語義化知識抽取（核心步驟）

此步驟由 LLM 執行語義理解和知識抽取。

2.1 讀取 Prompt 模板

MANDATORY - 讀取完整檔案: 閱讀 references/extraction-prompt.md 獲取完整 Prompt 模板。

2.2 執行 LLM 抽取

使用 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 (~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 中的"校驗示例"部分。

校驗通過標準

所有校驗項必須全部通過：

校驗項	通過標準
教學目標覆蓋	Level 4-7節點100%有objective
教學目標質量	所有objective包含行為動詞
層級深度	max(level) ≥ 6
層級跳躍	父子層級連續，無斷層
知識分類約束	分類節點category=""
知識點分類覆蓋	知識點節點category在有效值內
節點名稱長度	所有節點名稱≤30字
關聯關係覆蓋	>50%知識點節點有related
節點順序	父節點在子節點之前（深度優先）
列名結構	Excel第二行列名與模板100%一致
知識點子節點約束	知識點節點無children（有children則自動修正為分類）

呼叫指令碼校驗（可選）

如需指令碼輔助校驗，可執行：

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 (~167 lines) 進行關係推理。模板包含前置關係和關聯關係的完整識別規則。

前置關係識別規則：

模式	示例
基礎概念 → 高階應用	電阻 → 歐姆定律
理論原理 → 實踐操作	電路原理 → 電路安裝
工具使用 → 應用場景	萬用表使用 → 電流測量

關聯關係識別規則：

模式	示例
同類並列	電阻 ↔ 電容 ↔ 電感
對比概念	直流電路 ↔ 交流電路
相似原理	歐姆定律 ↔ 基爾霍夫定律

步驟 4: 格式驗證與 Excel 生成

將 LLM 輸出的 JSON 資料傳入指令碼，生成 Excel 檔案：

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 (~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 使用縮寫名稱作為關係引用

7w4.net有更好的技能外掛。

❌ 錯誤: "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	~289行	步驟1（必須）	僅理解概念時
references/extraction-prompt.md	~15KB	步驟2（必須）	不執行抽取時
references/quality-check-prompt.md	~5KB	步驟2.4（可選）	不執行校驗時
references/relation-prompt.md	~4KB	步驟3（可選）	不執行關係推理時

examples 目錄（示例模板與文件）

檔案	大小	載入時機	Do NOT Load 情況
examples/template-knowledge-graph.xlsx	~61KB	步驟1（必須）	已有使用者提供的模板
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條	節點間過度關聯	減少不必要的關係，只保留有實際教學意義的關聯

這個 Skill 質量中上，文件組織清晰規範，抽取邏輯和校驗機制設計合理，能有效指導知識節點的結構化提取。主要優勢在於質量把控嚴格、層級規則明確；不足之處是缺少開箱即用的處理工具，對技術背景有一定要求。總體適合有一定開發能力的團隊使用。