ScottDuncanAI/pid-to-kg

P&ID 轉知識圖譜

工作分為確定性腳本與你兩部分：

• 腳本 負責分類頁面（向量 vs 掃描）、將其渲染為可讀取的圖塊、收集 OCR/文字提示，然後建立、檢查、儲存並查詢圖譜。
• 你 負責閱讀圖面，並為每張圖紙撰寫一份結構化的萃取檔案。符號辨識與線條追蹤屬於視覺推理，這是腳本無法做好的部分。

所有腳本皆位於此檔案旁的 scripts/ 目錄中。請使用其完整路徑來呼叫它們（以下指令將其縮寫為 scripts/），並將工作目錄保持在使用者的當前資料夾內，例如 work/<plant>。

設定。 許多使用者是工程師而非程式設計師，因此請自行處理設定事宜。腳本需要 Python 3.10 以上版本。在首次執行前，請使用 pip install -r <skill dir>/scripts/requirements.txt 安裝相依套件（如果使用者的 Python 環境與其他工作共用，請使用虛擬環境）。如果缺少 Python，請告知使用者從 python.org 安裝並停止。

基本規則

• 僅限 P&ID 頁面。 圖面常常位於一份冗長的許可證或設計報告中。如果使用者指定了頁碼，請使用 --pages 參數傳遞。如果沒有，且 PDF 頁數超過少數幾頁，請先探查，查看頁面概覽或詢問使用者，然後使用 --pages 重新執行探查，以便後續步驟跳過報告、圖例和非 P&ID 圖面。
• 一個工廠，一個工作目錄，一個圖譜。 切勿將不同工廠的圖紙放入同一個工作目錄：這樣會導致標籤在不同工廠之間合併。如果使用者提供多個工廠，請為每個工廠分別執行整個工作流程。
• 每個圖譜一個配置。 如果 PDF 包含同一圖面的兩個版本（相同標題或區域，標籤重疊，例如竣工圖和舊版草稿），請勿合併它們。詢問使用者要使用哪個版本，僅萃取該版本，並在報告中記錄被排除的頁面及其原因。QA 會將可能的重複標記為 possible_duplicate_revision。請記錄每張圖紙在標題欄或圖章中的 issue_status。
• 僅記錄圖面上繪製的內容。 切勿為了讓圖譜看起來完整而虛構標籤、連接或迴路。任何不明確的內容，都應以較低的 confidence 填入，或歸入 unreadable。
• QA 循環並非選項。 持續重建直到沒有錯誤，並根據圖面重新檢查每個警告。

工作流程

將此檢查清單複製到你的筆記中並逐項核對：

- [ ] 1. 探查：    python scripts/probe_pdf.py <pdf> --work <work> --plant-name "<name>" [--pages 47-60]
- [ ] 2. 渲染：    python scripts/render_pages.py <work>
- [ ] 3. 定向：    開啟每個 pages/page_NN/overview_grid.png；如果文字不端正則修正旋轉
- [ ] 4. 提示：    python scripts/make_hints.py <work>
- [ ] 5. 萃取：    為每張圖紙撰寫 <work>/extract/page_NN.json（參考 references/extraction_procedure.md）
- [ ] 6. 建立：    python scripts/build_kg.py <work>
- [ ] 7. QA 循環： 修正每個錯誤，重新檢查每個警告，重建（重複）
- [ ] 8. 報告：    將結果總結給使用者，並提出未決問題

1. 探查

probe_pdf.py 為每頁指定一個類別和萃取路徑，並寫入 <work>/manifest.json。使用 --pages 時，後續步驟將僅渲染和讀取那些頁面。

類別	意義	路徑
vector_text	具有文字層的向量圖	從向量渲染；文字層提供精確文字提示
vector_outlined	向量圖，文字繪製為外框（無文字層）	高解析度向量渲染；OCR 提示
raster	掃描影像	原始解析度渲染，放大並增強對比；OCR 提示
raster_with_text	帶有 OCR 文字層的掃描	如同 raster；文字層作為（不可信的）提示
hybrid	向量加上大型圖片	兩種路徑

用一句話向使用者報告探查結果，例如「14 張帶有外框文字的向量圖紙。」

低掃描解析度會在備註中標記。預期在這些圖紙上會有更多項目歸入 unreadable。

2–3. 渲染與檢查方向

render_pages.py 為每頁寫入以下內容：

• overview.png
• overview_grid.png，顯示圖塊名稱
• tiles/ 中的重疊圖塊
• tiles.json，記錄哪些圖塊是空白的

如果已安裝 OCR，方向會透過 OCR 檢測。請務必在 overview_grid.png 上確認。如果主要圖面文字不端正，請使用明確的順時針旋轉重新渲染該頁：render_pages.py <work> --pages N --rotation 90。

標題欄有時會與圖面的旋轉方向不同。請根據圖面標籤而非標題欄來定向。

4. 提示

make_hints.py 寫入 hints/page_NN.json。每個檔案包含候選標籤及其頁面位置，這些標籤來自文字層或 OCR。它們只是提示：OCR 可能誤讀，且會遺漏一些東西。你在萃取期間不需要閱讀提示檔案。QA 會使用它們來標記你可能遺漏的標籤。如果未安裝 OCR，則跳過此步驟；請在最終報告中註明。

5. 萃取每張圖紙

這是工作的核心。請嚴格遵循 references/extraction_procedure.md。它涵蓋了：

• 閱讀順序：概覽，然後每個非空白圖塊，最後是放大的裁切區域
• 如何建模管線路徑、三通、支管、訊號和跨頁連接器
• 信心水準校準
• 儲存前要執行的自我檢查清單

需要時可閱讀的參考資料：

• references/isa_5_1.md：儀表字母代碼、泡泡符號、訊號線類型
• references/symbol_guide.md：設備和閥門符號如何對應到 kind 值
• references/ontology.md：圖譜的節點和邊緣類型及其推導方式
• references/schema/extraction.schema.json：頁面檔案的確切 JSON 綱要

撰寫 extract/page_NN.json 並在開始下一張圖紙前儲存，以便長時間的工作最多只在上下文中保留一張圖紙。如果圖紙很多，且你的環境支援子代理，你可以並行萃取圖紙。為每個子代理提供程序檔案及其自己的頁面目錄。

6–7. 建立與 QA 循環

build_kg.py 驗證每個頁面檔案，並在發現綱要錯誤時以精確的訊息停止。然後它會將以下檔案寫入 <work>/kg/：

• graph.json
• graph.duckdb
• summary.md
• qa_report.md

處理 qa_report.md 中的項目：

• 錯誤，例如 unresolved_reference，表示頁面檔案中有錯誤。修正它們並重建。
• 警告 會指出需要重新檢查的圖塊名稱。再次查看那些圖塊，或使用 crop.py 取得放大檢視，如果圖面顯示了不同的內容，請修正萃取項目。常見警告：
  • instrument_not_located：沒有 measures 的感測器
  • equipment_not_connected
  • unmatched_off_page
  • possible_missed_tags：OCR 標籤未在你的萃取項目中
  • tiles_not_reviewed
• 若警告經檢查後確認圖面無誤，則可保留。例如：跨頁連接器的另一張圖紙未被提供，或 OCR 誤讀。請將這些項目列入你的報告。

當沒有錯誤且每個警告都已檢查時停止。

python scripts/crop.py <work> --page 5 --bbox 0.40 0.20 0.55 0.35   # 區域放大檢視

8. 報告

告知使用者：

• 輸出檔案的位置
• 主要計數（設備、儀表、迴路）
• 從 summary.md 中取出的兩到三個範例流程路徑和迴路
• 尚不確定的事項

詳細資訊請參考 qa_report.md。明確說明圖譜是由機器萃取的，在使用於設計、操作或安全用途之前，需要經過工程審查。

使用圖譜

• summary.md 是給 LLM 使用的精簡、token 高效的背景資訊：設備層級的流程、包含位置的儀表表格，以及迴路表格。
• graph.json 是標準圖譜，任何工具皆可讀取。
• graph.duckdb 適用於 SQL。其檢視表為 equipment、equipment_flow、instruments、loops 和 signals，表格巨集為 upstream(id) 和 downstream(id)。

使用 kg_query.py 來回答問題；當其他工具將取用輸出時，請加上 --json：

python scripts/kg_query.py <work>/kg downstream 660-TK-001 --equipment
python scripts/kg_query.py <work>/kg upstream FV-0502
python scripts/kg_query.py <work>/kg path 660-TK-001 660-TK-004
python scripts/kg_query.py <work>/kg instruments --on 660-PP-011
python scripts/kg_query.py <work>/kg loop FIC-0502
python scripts/kg_query.py <work>/kg sql "SELECT * FROM equipment_flow"

若要衡量圖紙上的萃取品質，請將其手動檢查後放入一個小型黃金檔案（格式見 scripts/eval_kg.py），並執行 python scripts/eval_kg.py <work>/kg gold.json：它會報告標籤、流程和迴路的精確率/召回率，以及儀表放置。

若要將圖譜移至其他工具：python scripts/export.py <work>/kg graphml 會產生一個適用於 yEd、Gephi 或 NetworkX 的檔案，而 python scripts/export.py <work>/kg neo4j 會產生 CSV 檔案加上 Cypher 匯入腳本。