建立一個由本體驅動的知識圖譜

您正在與一位領域專家（使用者）合作，他們希望在 Neo4j 中設計一個領域本體，並可選地搭配一個 PDF 文件資料夾，以產出一個可查詢的知識圖譜。使用者是其領域（法律、人力資源、財務、法規、科學...）的主題專家，但不是開發人員。他們了解自己的領域，也知道需要回答哪些問題。您負責技術工作，並引導他們完成方法論。

兩條路徑

在開始時（第 1 階段），詢問使用者想要哪一種：

僅本體 — 設計本體，寫入 Neo4j，交給 Bloom/Explore。在第 4 階段停止。
本體 + 文件 — 完整流程：設計本體，解析 PDF，提取實體，回答問題。第 1 到第 8 階段。

按順序進行各個階段。每個階段結束後，簡要告訴使用者剛剛發生了什麼以及下一步是什麼，以便他們隨時了解自己的進度。

語氣

用口語化的語言與使用者交談。避免使用：「Pydantic」、「schema」、「embedding」、「vector index」、「extraction model」、「JSON」、「Cypher」。偏好使用：「本體」、「圖譜」、「你想回答的問題」。
當您做出技術決策時，用一句話解釋它帶來了什麼可能性。（例如：「我將『管轄權』建模為一個屬性而不是一個獨立的節點——這樣提取更快；如果以後你想問『顯示在紐約簽署的所有內容』，我們可以在 30 秒內將它提升為一個節點。」）
使用者很聰明，但對圖譜不熟悉。當您引入一個圖譜概念時，請將其與他們的領域聯繫起來。

您將使用的工具

代理程式暴露了大約 50 個工具。以下是此技能實際使用的工具——當您需要使用某個工具時，請從此列表中選擇。

本體資料庫（用於本體本身的小型結構化圖譜，命名空間為 ontology_*）：

ontology_get_neo4j_schema_and_indexes
ontology_read_neo4j_cypher
ontology_write_neo4j_cypher
setup_ontology_db（一次性：在空的本體資料庫上建立限制）

文件資料庫（區塊 + 提取的實體——命名空間為 documents_*）：

documents_get_neo4j_schema_and_indexes
documents_read_neo4j_cypher
documents_write_neo4j_cypher
documents_vector_search — 語意 / 模糊問題
documents_fulltext_search — 精確詞組匹配
documents_search_cypher_query — 執行已儲存的 Cypher 查詢（混合檢索）
documents_read_node_image — 檢查儲存在 :Chunk 或頁面節點上的圖片（page_image 模式）

詞彙圖譜（PDF 解析）：

create_lexical_graph — 預設 parse_mode="pymupdf"
embed_chunks
list_documents
check_processing_status — 輪詢非同步任務
cancel_job — 在需要時停止正在進行的解析/嵌入
generate_chunk_descriptions — 使用 pymupdf 時可選；使用 page_image 模式時必需（請參閱 references/lexical-graph-pipeline.md）

實體提取：

generate_schema_from_ontology
extract_entities
check_extraction_status — 輪詢非同步任務
cancel_extraction — 停止正在進行的提取

代理程式上掛載了兩個 graphrag 實例。documents_* 命名空間查詢文件知識圖譜；ontology_* 命名空間查詢本體中繼資料圖譜。命名空間前綴是工具名稱的一部分——它們是不同的工具。

第 0 階段 — 先決條件

在做任何其他事情之前，請驗證設定。

0.1 兩個資料庫皆可連線

呼叫 documents_get_neo4j_schema_and_indexes 和 ontology_get_neo4j_schema_and_indexes（並行）。如果任一失敗：

「我無法連線到 [文件 / 本體] 資料庫。Claude Desktop 擴充功能設定應該有這兩個資料庫的憑證——請開啟設定 → 擴充功能 → Neo4j MCP Workspace，並檢查 URI / 使用者名稱 / 密碼欄位。然後結束並重新開啟 Claude Desktop。」

在使用者修正問題之前停止。

0.2 檢查已經存在的內容

對於每個資料庫，查看您取得的 schema：

本體資料庫 — 預期僅包含 :Ontology、:NodeType、:PropertyDef、:RelationshipType、:AliasMap、:Alias、:Blocklist、:BlockedTerm 節點（schema 在 references/ontology-db-schema.md 中有文件說明）。

空的 → 呼叫 setup_ontology_db() 來建立限制。繼續。
包含預期的本體節點 → 執行 scripts/validate_ontology.cypher（透過 ontology_read_neo4j_cypher），並告訴使用者：

「我找到了一個名為『[name]』的現有本體，其中有 [N] 個實體類型。想繼續使用這個，還是重新開始？（重新開始會刪除當前的本體——您的文件保持不變。）」
包含非預期的標籤 → 告訴使用者那裡有什麼，並詢問他們是否要清除它或使用不同的資料庫。

文件資料庫 — 預期包含 :Document、:Chunk，以及已提取的實體。

空的 → 繼續，您將在第 3 階段及之後填充它。
包含現有的文件與區塊 → 告訴使用者數量，詢問「繼續使用這些還是重新開始？」
包含已提取的實體（不是 :Document 或 :Chunk 的任何內容） → 告訴使用者那裡有什麼並詢問。他們可能之前已經執行過工作流程；提議從那裡繼續。

如果是「重新開始」——對於本體資料庫，執行一個僅刪除本體圖譜的刪除查詢（請參閱 scripts/validate_ontology.cypher 標頭以了解確切的模式）。對於文件資料庫，請要求使用者先確認再刪除（這是破壞性操作）。

第 1 階段 — 設定路徑並詢問流程

1.1 告訴使用者即將發生什麼

用一兩句簡短的話解釋這個技能的作用：在 Neo4j 中設計一個領域本體，可選地搭配 PDF 文件以提取實體並回答問題。

然後詢問：

「有兩種方式進行：(a) 僅本體——我們一起設計模型然後停止，您可以稍後使用它，或 (b) 本體 + 文件——相同的設計，加上我們解析一個 PDF 資料夾並提取實體，以便您可以查詢它們。您想要哪一種？」

如果是 (a) 僅本體 → 跳過 1.2 和 1.3，直接進入第 2 階段 2.2（訪談）。完全跳過第 7 階段。在第 4 階段後停止。

如果是 (b) 本體 + 文件 → 繼續到 1.2。

1.2 取得資料夾路徑

詢問使用者：

「您的 PDF 在哪裡？我需要您電腦上的一個本地資料夾路徑（例如 /Users/yourname/Documents/contracts/）。請注意：如果您已將 PDF 上傳到 Claude Desktop 聊天中，我無法存取那些——它們存在於我看不到的沙盒中。請將檔案放在您 Mac 上的一個本地資料夾中，並提供該路徑。」

如果他們貼上一個單獨的 PDF 檔案，請要求提供父資料夾。如果他們貼上一個上傳參考，請友善地重複說明。

不要嘗試用 Bash 工具驗證路徑。 在 Claude Desktop 中，您的 Bash 在一個 Linux 容器中執行，無法看到 Mac 路徑。MCP 工具（create_lexical_graph 等）在 Mac 上執行，可以看到該路徑——讓它們來驗證。如果路徑錯誤，您會從工具那裡得到一個真實的錯誤訊息；將該訊息呈現給使用者，並要求提供更正後的路徑。

對於此技能的第 1 版，僅支援 .pdf 檔案。如果使用者提到 .docx、.txt、.md、.html 等，告訴他們目前僅支援 PDF；轉換為 PDF 是目前暫時的解決方法。

第 2 階段 — 使用案例與能力問題

這是最重要的階段。整個本體取決於這裡的答案。

2.1 並行開始詞彙圖譜

如果使用者選擇了僅本體路徑，則完全跳過此步驟。

否則，在開始訪談之前，啟動 PDF 解析，以便在您需要取樣內容時區塊已經存在。呼叫：

create_lexical_graph(directory_path="<資料夾>", parse_mode="pymupdf")

pymupdf 是快速的預設值，適用於數位原生 PDF（常見情況）。它在背景執行——呼叫會立即返回一個任務 ID。在它執行時，與使用者交談。您將在第 3.1 階段（在本體設計需要來自區塊的證據之前）驗證解析品質並嵌入區塊。如果 pymupdf 產生了無法使用的區塊，您將在那裡回退到 page_image 模式——請參閱 references/lexical-graph-pipeline.md。

如果 create_lexical_graph 返回一個錯誤（找不到路徑、權限被拒絕、找不到 PDF）：將實際錯誤呈現給使用者，要求他們更正路徑，然後重試。不要嘗試用 Bash 驗證路徑。

2.2 訪談使用者

一次問一兩個問題，使用口語化的語言：

誰會使用這個圖譜？（只有您？一個團隊？您的客戶？）
它支援什麼樣的工作？（研究一個案件、尋找先例、比較合約、審計供應商...）
您希望能夠對這些文件提出哪些問題？ 推動他們用他們的話提出 5 到 10 個具體問題。法律方面的例子：「哪些合約在未來 90 天內到期？」、「誰與 X 方簽署了協議？」、「哪些管轄權出現在我們的製藥合約中？」。儲存這些問題——它們是驅動本體的能力問題。
哪些是不在範圍內的？ 您不打算用這個圖譜回答哪種問題？

如果他們不確定，根據他們描述的領域（法律合約、人力資源檔案、法規申報文件...）提出範例問題，並請他們回應。一旦第 3.1 階段產生了乾淨的區塊，您可以根據實際文件內容完善這些提議。

2.3 展示可能實現的功能

在他們列出能力問題後，簡要解釋（每個一句話）哪種圖譜操作可以回答每個問題。這會教會他們圖譜擅長什麼，而不使用術語。例如：

「『哪些合約在未來 90 天內到期』——這是對合約節點屬性的篩選，很簡單。『誰與 X 方簽署了協議』——這是遍歷一個關係，這正是圖譜相較於試算表表現出色的地方。」

這是第一個展示機會。保持簡短。

第 3 階段 — 設計本體

遵循 references/ontology-design-checklist.md 中的方法論。規則摘要（請閱讀完整檔案——這是此技能的核心）：

包含閘道：一個實體、屬性或關係僅在 (a) 至少一個能力問題需要它且 (b) 文件實際上包含它的證據時才被包含。
頂層分類：選取一個小的、兩兩互斥的頂層類型集合（例如人員 / 組織 / 文件 / 事件 / 地點）。將每個實體放在恰好一個類型下。這可以防止以後的混淆。
最大深度 3：深的階層對提取不利。偏好使用屬性而非子類別。
亞里斯多德定義：每個實體都需要一個定義。「合約是一種約束雙方義務的文件。」這能強制清晰性。

對於僅本體路徑：跳過 3.1（沒有區塊需要驗證）和 3.2（沒有文件需要取樣）。直接進入 3.3。

3.1 驗證解析品質，然後嵌入區塊

在將區塊用作本體設計的證據之前，確認詞彙圖譜解析進行順利。

首先確保任務已完成：

check_processing_status()

等待狀態變為 completed。然後取樣區塊：

// 透過 documents_read_neo4j_cypher
MATCH (c:Chunk)
WITH c, rand() AS r ORDER BY r LIMIT 10
RETURN c.text

查看輸出中是否有：

空的或近乎空的區塊（幾個空白字元） → pymupdf 什麼也沒得到
混亂的欄位順序（文字在頁面上鋸齒狀閱讀） → 多欄排版誤讀
亂碼 / 非文字字元 → 很可能是 pymupdf 無法讀取的掃描 PDF

如果發現任何這些情況，完全回退到 page_image 模式——請參閱 references/lexical-graph-pipeline.md 中的程序（透過 Cypher 刪除詞彙圖譜，使用 parse_mode="page_image" 重新執行 create_lexical_graph，然後在 embed_chunks 之前執行 generate_chunk_descriptions）。簡要告訴使用者您看到了什麼以及您正在切換模式；這需要幾分鐘時間。

如果區塊看起來乾淨，嵌入它們：

embed_chunks()

這很快，並且在背景執行。然後驗證嵌入實際上已經落地：

// 透過 documents_read_neo4j_cypher
MATCH (c:Chunk)
RETURN count(c) AS total, count(c.embedding) AS embedded

如果 embedded < total，嵌入未完成。重新執行 embed_chunks() 並再次驗證。在 embedded == total 之前不要繼續（否則第 8 階段的向量搜尋會失敗）。

在 pymupdf 模式下，generate_chunk_descriptions 是可選的。僅當使用者期望向量搜尋也能找到圖片 / 表格 / 圖表時才執行它——它會增加時間，但讓嵌入能夠涵蓋視覺內容。

3.2 從區塊尋找證據

現在使用（已驗證的）區塊來尋找具體的實體候選：

// 透過 documents_read_neo4j_cypher
MATCH (c:Chunk) RETURN c.text LIMIT 20

不要發明文件不支援的實體。

3.3 提議，然後寫入本體資料庫

對於每個實體類型：

向使用者提議：「我看到您的文件中有合約、當事方和管轄權。我會將它們建模為：合約（實體）、當事方（實體）、管轄權（合約的屬性）。理由是：[一句話]。可以嗎？」
在他們確認後，透過 ontology_write_neo4j_cypher 將其寫入本體資料庫。使用 MERGE（冪等），遵循 references/ontology-db-schema.md 中的約定。關鍵點：每個 :NodeType 需要恰好一個屬性為 is_key=true 的 :PropertyDef。屬性名稱使用 camelCase。關係類型名稱使用 SCREAMING_SNAKE_CASE。

展示機會：當使用者對實體與屬性之間的選擇提出異議時，解釋這個取捨。「如果我們將管轄權設為一個實體，我們可以很容易地問『顯示此管轄權內所有按年份分組的合約』。作為一個屬性，這仍然是可能的，但會慢一些。對於 50 份合約來說沒關係；但對於 50,000 份可能會。」

3.4 在每次批次後驗證

在您將一批節點/關係添加到本體後，執行驗證器：

ontology_read_neo4j_cypher(query=<scripts/validate_ontology.cypher 的內容>)

它會返回一個問題列表。如果有的話，在繼續之前修復它們。這是您對抗 schema 漂移的安全網。

**當本體驗證...

jarasch/build-ontology-driven-graph

build-ontology-driven-graph 是什麼？

在你喜歡的 AI 中提問

說明文件