知識圖譜批次產生器
📌 版本歷史
| 版本 | 日期 | 變更內容 |
|---|---|---|
| 2.2.0 | 2026-09-02 | 沉澱大規模專案全量升級實戰：① 骨架卡升級策略——使用者反饋「待補充太多/規則過簡」時觸發全量升級，按領域並行派子代理 + 主代理監控產出（grep 剩餘待補充數），代理停滯即接管補齊；② mermaid 節點 label 禁巢狀圓括號（渲染失敗頭號原因）與批次正則修復腳本；③ 子代理跨模組相對路徑易錯（../.. 層級），終檢必須跑雙鏈校驗；④ 更新升級後的統計回寫與 README |
| 2.1.0 | 2026-09-01 | 修復 Obsidian wiki 連結路徑規範（重要）：Obsidian 的 [[...]] wiki 連結不支援 ../ 相對路徑（../ 會被當作筆記名導致無法點擊），全部改為從知識庫根出發的完整路徑（[[領域/模組/功能.md|別名]]）；同步修正 templates.md 中的連結規範表與 mermaid 節點語法（mermaid 內禁止 [[...]]，用純文字節點）；補充實戰經驗：L2 領域索引引用跨領域模組連結深度、子代理 429 限流降級、質檢腳本跳過程式碼塊、L3 功能數差異由第五批回寫 |
| 2.0.0 | 2026-08-24 | 修復 Obsidian 雙鏈相容性：第五批質檢新增「無點號語法 + 逐連結相對路徑解析校驗」，生成的知識庫在 Obsidian 中可正常跳轉 |
| 1.0.0 | 初始版本 | 5 批批次生成策略（L1+L2 骨架 → L3 模組索引 → 核心功能卡片 → 其餘功能骨架 → 全域質檢）基礎能力 |
Overview
面向大規模專案的知識工程。當專案已有完整程式碼/文件、功能節點超過 50 個、需要一次性生成數百個節點的完整知識庫時，按批次策略高效生成，避免單次輸出過載。所有檔案內容必須遵循 business-knowledge-graph-generator skill 中定義的模板規範（references/templates.md）。
何時使用
- 功能數量超過 50 個的大規模專案
- 已有完整的專案程式碼目錄結構 + 核心程式碼檔案內容（可分批提供）
- 需要一次性生成數百個節點的完整知識庫
輸入要求：提供完整的專案程式碼目錄結構 + 核心程式碼檔案內容（可分批提供）。
批次處理策略
當功能數量超過 50 個時，按以下順序分 5 批處理：
第一批：L1 + L2 骨架（全域結構）—— 預計輸出 6~20 個檔案
- 生成
knowledge/_index.md（L1 全景圖） - 為每個領域生成
<領域>/_index.md（L2 領域圖） - 品質檢查：確認所有領域和模組已覆蓋，無遺漏
第二批：L3 模組索引（功能清單）—— 預計輸出 20~50 個檔案
- 為每個模組生成
<領域>/<模組>/_index.md（L3 模組圖） - 品質檢查：確認每個模組的功能清單完整，所有功能已命名
第三批：高優先級功能卡片（核心流程）—— 預計輸出 20~30 個檔案
- 識別系統的核心功能（使用者最常用的 20% 功能，如登入、下單、支付）
- 為這些功能生成完整的 L4 卡片（含流程、規則、事件、依賴、程式碼位置）
- 品質檢查：核心流程包含異常分支，程式碼位置精確到行號
第四批：其餘功能骨架卡片 —— 預計輸出 50~200+ 個檔案
- 為剩餘功能生成最小化卡片（至少包含 Frontmatter + 功能描述 + 基礎規則）
- 標註
狀態: 待補充，供後續人工完善 - 品質檢查：所有功能都有對應的 .md 檔案，無功能遺漏
第五批：全域品質檢查與索引更新
- 驗證所有雙鏈均為 Obsidian 相容相對路徑（
[[../模組/功能.md\|別名]]），無[[領域.模組.功能]]點號語法 - 遍歷校驗：每個連結相對當前檔案解析後，目標 .md 檔案必須存在
- 標註所有懸空連結，生成待修復清單
- 更新各層級
_index.md中的統計數字（模組數量、功能數量） - 生成
knowledge/README.md使用說明
優先級判定規則
| 優先級 | 判定標準 | 範例功能 |
|---|---|---|
| 核心 | 使用者日常使用 > 80% 的場景、資金安全相關 | 登入、下單、支付、退款 |
| 重要 | 使用者日常使用 30%~80% 的場景、資料管理相關 | 訂單查詢、物流追蹤、修改資訊 |
| 一般 | 管理後台功能、低頻操作、配置類 | 商品分類管理、日誌查詢、報表生成 |
輸出要求
- 按批次輸出，每批完成後報告進度，並等待使用者確認後再繼續下一批
- 每批輸出時，列出本批生成的檔案清單
- 第三批（核心功能）生成完成後，暫停，等待使用者指定下一批重點領域
- 所有檔案內容必須遵循
business-knowledge-graph-generator中references/templates.md定義的模板規範
批次回報格式
## 第 X 批完成 ✅
**生成檔案數**：XX 個
**涉及領域**：領域A、領域B
**檔案清單**：
- knowledge/領域A/_index.md
- knowledge/領域A/模組A/_index.md
- ...
**下一批計劃**：生成 XXX 領域的核心功能卡片
請確認是否繼續？
注意事項
- 分批交付：如果專案超過 100 個功能，先完成 L1 和 L2 骨架，再逐步下鑽到 L3，最後批次生成 L4
- 程式碼讀取限制：如果程式碼檔案太多，讓使用者先提供核心模組的 5~10 個關鍵檔案，其他按目錄結構描述即可
- 人工補充：Skill 生成 80% 的內容（結構、流程、規則框架），但具體的歷史踩坑記錄和負責人資訊需提示使用者手動補充
實戰經驗（2026-09-01 jetlinks 專案沉澱）
- Obsidian 連結必須用庫根路徑 + 不帶
.md後綴（最關鍵）：Obsidian 的 wiki 連結 不支援../相對路徑（../會被當作筆記名），也 不支援.md後綴（[[Note.md]]會被當作名為 "Note.md" 的筆記而非 "Note"，導致無法點擊）。所有連結統一寫[[領域/模組/功能\|別名]]（從 knowledge/ 根出發，不寫 .md），mermaid 圖中用純文字節點（A[功能] --> B[功能]），禁止[[...]]語法。 - 子代理 429 限流降級：大規模探索/生成時子代理可能觸發頻率限制（429），此時降級為主會話直接生成：先用 Glob/Grep 定位所有 Controller 的
@RequestMapping與 HTTP 方法註解（可精確到行號），再逐檔案寫入。 - 質檢腳本須跳過程式碼塊：L4 卡片內「連結規範」範例常寫在反引號程式碼塊中，質檢正則需先剔除
`...`與mermaid塊內容，否則會把範例誤報為懸空連結。 - 功能數回寫機制：L2 索引中的模組功能數是預估的，L3 生成後以實際為準，第五批用腳本自動回寫 L2 統計列與 L1 規模統計。
- 批次生成用腳本：第四批骨架卡片（100+ 檔案）用 Python 腳本從 L3 索引表格正則提取功能名/類型/描述並批次寫入，保證命名與連結一致，比逐檔案手寫高效且不易出錯。
實戰經驗（2026-09-02 大規模專案全量升級沉澱）
- 骨架卡升級全量觸發，不等點名：使用者對「待補充/規則過簡」不滿即觸發全量升級，按領域分批，全部升級到完整卡詳細度（見 business skill 的「L4 卡片詳細度標準」）。
- 並行子代理按領域分派 + 主代理監控：每個領域派一個子代理（prompt 內置模板範例 + mermaid 鐵律 + 程式碼勘察要求）；主代理用
grep -rl "狀態: 待補充" <領域> | wc -l定期檢查剩餘量，代理停滯（一段時間無新檔案產出）時直接接管補齊，不乾等。 - mermaid 節點 label 禁巢狀圓括號（渲染失敗頭號原因）：flowchart 節點
[..]/{..}內出現()（如A[Foo(x)]）會報 "Expecting SQE, DOUBLECIRCLEEND..." 解析錯誤；函式簽名參數刪除或空格分隔。批次修復：正則僅掃 mermaid 塊，把[label(args)]替換為[label args]（去括號、逗號變空格）。 - 子代理跨模組相對路徑易錯：子代理寫跨模組連結時
../..層級算錯是高頻失誤（例如交易管理/交易日誌/指向行情資料/自選股管理/應為../../行情資料/自選股管理/_index.md而非../自選股管理/）；終檢必須跑雙鏈校驗腳本，列出斷鏈清單逐一修復。 - 終檢三合一：升級完成後跑 ① 雙鏈完整性腳本（遍歷全部 md 解析
[[...]]相對路徑並校驗目標存在）② mermaid 括號掃描 ③ 待補充殘留計數（grep -rl "狀態: 待補充" | wc -l應為 0）；更新 README 統計後交付。
批次升級骨架卡操作指南
當 knowledge/ 已存在大量骨架卡需升級時：
1. 統計剩餘：grep -rl "狀態: 待補充" knowledge/*/ | wc -l （按領域細分）
2. 按領域並行派子代理（每個 prompt 需包含：模板範例絕對路徑、mermaid 鐵律、
程式碼勘察要求「至少 1-2 個真實函式名+行號，找不到標待定位不編造」、輸出報告格式）
3. 主代理定期檢查：find 最近 mtime 檔案 / grep 剩餘待補充數；停滯即接管
4. 終檢：雙鏈校驗腳本 + mermaid 括號掃描 + 待補充計數歸零
5. 更新 README 統計與各層 _index 統計數字
Resources
business-knowledge-graph-generator/references/templates.md：L1~L4 模板規範（必須遵循）