docs(sdd): library-map（藏書地圖）SDD 出稿 draft——#39 立案 11 天催辦補課；含 D6 歸屬裁定（SQL 住基本盤）＋D30 檢索治本連動

2026-07-19 07:54:23 +00:00
parent 65d85eb08f
commit 1ee0dbd2fe
3 changed files with 77 additions and 0 deletions
@@ -0,0 +1,38 @@
+---
+status: draft
+note: 依 D35 單一活性，本 SDD 以 draft 出稿；轉 active 由總管/leo 對照 Arcrun 現行 active SDD 裁定。
+---
+# library-map（藏書地圖）— Design
+
+## 1. 資料結構：`library_map` Template（照 leo spec §3）
+
+每庫一個 map block。slots：`library`(text)／`narrative`(text，抽自該庫頂層 wiki 首段)／`top_entities`(array，degree 排序 top-N)／`relation_profile`(array，predicate 分布＝庫的性格)／`bridges`(array，同 entity 跨庫 join)／`triplet_count`(number)／`commit_hash`(text)／`status`(active|superseded)。
+
+三元組按庫過濾：先核實現況——rag-ingest-cards v2 的 triplet 已帶 `source_uri`、entries 已有 `metadata.library`（portal-auth P1）；若 triplet 定位庫仍不足，在 Triplet **Template schema** 加 optional `library` slot（改 template 不動表）。
+
+## 2. 重算的家：SQL 只能住基本盤（D6 推論，本 SDD 關鍵歸屬裁定）
+
+degree 排序／predicate 統計／跨庫 join 是聚合 SQL——**D6 鐵律：插件與 workflow 全程禁 SQL**。故重算實作＝**kbdb base 新增內建端點 `POST /map/recompute?library=`**（基本盤內 SQL 合法，一段交易：算→建新 block→舊標 superseded）。ingest workflow（A 類）尾端用 `http_request` 呼此端點——A 類接 B 類 API，牆不破。
+讀取端點 `GET /map`（全館，每庫一行）／`GET /map/:library`（詳圖），MCP/GUI 共用。
+
+## 3. 更新機制（leo spec §4）
+
+ingest 完成 → 取本次 commit diff 涉及的庫集合 → 逐庫呼 `/map/recompute`。無 cron 全量。首次 backfill＝對每個既有庫手動各呼一次（installer/腳本一行）。
+
+## 4. 注入（leo spec §5，本功能重點）
+
+- **MCP instructions**：arcrun-mcp 啟動組 instructions 時拉 `GET /map` 嵌入（快取＋TTL，或每次連線現拉——量數百 token，現拉可接受）。
+- **`get_map` 工具**：薄殼呼 `/map`／`/map/:library`。與 #68 的 kbdb_graph_neighbors 同族（D17 KBDB MCP 面），可同 PR 或緊接。
+- **GUI**：console/portal 首頁 render `GET /map`——庫卡片（narrative＋top entities＋規模）＋跨庫 bridges 一覽；點庫進該庫搜尋。
+
+## 5. 與 D30 檢索治本的連動（本 SDD 新增，超出原 spec）
+
+leo 終景「補充的只 vectorize entities＋一句話」與本件是同一素材的兩用：map block 的 narrative＋top_entities＝卡級/庫級摘要嵌入單位。落法：map block 的 content 欄寫成可嵌人話（`{library}：{narrative}。核心：{top_entities}`），標 embed → **semantic 第一跳打 map 層做庫路由**，第二跳才進庫內（D30「向量做路由、定稿給 LLM 讀」）。#58/#59 的殘影/模型問題在 map 層天然緩解（block 少、可整層重刷）。
+
+## 6. Retrieval 流程（改造後，leo spec §6 原文）
+
+session 啟動 → instructions 已含全館地圖（push 零查詢）→ 需細節 get_map(library) → graph query 找 entity/關係 → 依 index 取 repo wiki 定稿（真相源不變）。
+
+## 7. 歸屬
+
+kbdb base 端點＝B 類（PR）；ingest 尾端接鏈＝A 類（workflow 改版，arcrun-rag/個人庫同款）；MCP＝B 類；GUI＝B 類（console 路由）。全框架件：寫一次，arcrun-rag／Mira／未來客戶全實例受益（bundle 更新分發）。
@@ -0,0 +1,26 @@
+# library-map（藏書地圖）— Requirements
+
+> 來源：Arcrun#39（leo 2026-07-08 拍板立案，spec 全文在 issue／`Leo/InkStoneCo` `6-user/kbdb-library-map-spec.md`）。
+> SDD 出稿：雲端總管 2026-07-19（leo 當日催辦「說了好幾天還沒有 SDD？」）。
+
+## 問題
+
+KBDB 是純 pull 查詢引擎，MCP/GUI 都預設「查詢者已知道要查什麼」。新 LLM session 接上 MCP 看得到 query 工具，卻不知道館裡有哪些藏書——只能拿推理成本掃庫，換一張本可預先算好的地圖。GUI 首頁同樣是空白搜尋框，人也沒有定向層。
+
+## 需求（R）
+
+- R1 每庫一張機械導出的地圖 block（庫名／一句話 narrative／top entities／relation 輪廓／跨庫橋接／規模／鮮度），**全部由 graph 統計算出，零 LLM 生成**。
+- R2 ingest 完成後只對受本次 diff 影響的庫增量重算（新 block＋舊標 superseded），無定時全量重算。
+- R3 MCP：①全館地圖（每庫一行，數百 token 內）注入 server instructions，agent 開場即持有 ②新工具 `get_map`（無參數＝全館；`library` 參數＝該庫詳圖），description 註明「不確定查什麼先呼叫此工具」。
+- R4 GUI：console/portal 首頁改 render 全館地圖（有哪些庫、每庫講什麼、跨庫橋接），非空白搜尋框。
+- R5 KBDB 三表不變量：新 Template＋blocks＋slots，不建表不 ALTER（D6）。
+- R6 版本語意沿用 supersede/deprecate status slot＋commit hash。
+- R7 **與 D30 檢索治本連動**：map block 的 narrative＋top_entities 即「只 vectorize entities＋一句話」的嵌入素材——semantic 路由層優先打 map 層（詳 design §5）。
+
+## 明確不做（leo 原文）
+
+❌ LLM 生成摘要當地圖 ❌ 獨立摘要樹結構 ❌ 無界 embedding ❌ 地圖必須先落檔才入庫（每庫 index.md 輸出＝phase 2 optional）。
+
+## 驗收
+
+新開 claude.ai session 掛 MCP：開場 instructions 見全館地圖；`get_map("kb")` 回該庫詳圖；GUI 首頁見地圖；ingest 一筆新料後該庫地圖自動更新、他庫不動；全程零 LLM 呼叫、map block 數＝庫數。
@@ -0,0 +1,13 @@
+# library-map — Tasks
+
+> 進度真相源。依 design §7 歸屬；動工前總管審本 SDD（#39 明令）。
+
+| # | 任務 | 類 | 依賴 | 狀態 | 備註 |
+|---|---|---|---|---|---|
+| M1 | `library_map` Template＋slots 定義（含 triplet 按庫過濾現況核實；不足則 Triplet template 加 optional library slot） | B | — | ⬜ | D6 零建表 |
+| M2 | kbdb base `POST /map/recompute?library=`＋`GET /map`／`GET /map/:library`（聚合 SQL 住基本盤；交易式 supersede） | B | M1 | ⬜ | PR＋測試；merge 後 gated 部署（leo 閘） |
+| M3 | ingest 尾端接鏈：diff 涉及庫 → 逐庫呼 recompute（rag-ingest-cards v2＋個人庫 ingest 同款改版） | A | M2 | ⬜ | workflow 改版走 bundle 分發 |
+| M4 | MCP：instructions 注入全館地圖＋`get_map` 工具 | B | M2 | ⬜ | 與 #68 同族薄殼 |
+| M5 | GUI 首頁：全館地圖 render（console＋portal） | B | M2 | ⬜ | 取代空白搜尋框 |
+| M6 | D30 連動：map 層 embed＋semantic 庫路由第一跳 | B | M2 | ⬜ | #58/#59/#60 家族的第一片治本 |
+| M7 | dogfood：leo 庫（leo21c）首個實例 backfill＋驗收（requirements 驗收段全項） | A | M3-M5 | ⬜ | 過了才進 demo/客戶 |