fix(kbdb): 藏書地圖加 entry_count——triplet_count=0 不再被誤讀成「沒有知識」（Arcrun#87 三次收尾） #117

2026-08-13T05:51:04Z

Leo commented

2026-08-13 05:51:04 +00:00

目的（Arcrun#87 三次收尾）

kbdb_get_map 過去只回 triplet_count——kb 以外幾乎全部庫顯示「0 triplets」，讀起來像空庫，AI 一開場看到就放棄查詢。實際上那些庫的 entries（原始 ingest 內容）都在，只是三元組萃取從沒對它們跑過。

改了什麼

kbdb/src/actions/library-map.ts：新增 liveEntryCountsByLibrary（即時統計 entries，排除 entry_type='value' 存儲細節與 library_map 自己的 block），entry_count 並排 triplet_count 回傳（全館 listLibraryMaps + 單庫 getLibraryMapDetail）。
mcp/src/lib/library-map.ts：renderLibraryMapLines（MCP instructions 首屏文字）在 triplet_count=0 且 entry_count>0 時明講「有內容、只是還沒萃取，kbdb_search 查得到」，不再讓 0 觸目即誤讀成空庫。
mcp/src/tools/kbdb_map.ts：kbdb_get_map 全館視圖的 hints 會點名「entry-only」的庫；單庫詳圖在 triplet_count=0/entry_count>0 時附同款提示。
console-ui/public/console/index.html：看板卡片同步顯示「N 筆原始內容（尚未萃取）」。
新增測試：kbdb/tests/library-map.test.ts（entry_count 計數口徑）、mcp/tests/unit/tools/kbdb-map.test.ts（hints 內容、渲染文字、舊部署缺欄位容錯）。

驗證

kbdb：19 test files / 215 tests all green（含新測試 21 tests）
mcp：7 test files / 120 tests all green（含新測試）
tsc --noEmit：mcp 乾淨；kbdb 既有 4 個型別錯誤與本次改動無關（entries.ts route / auth.test.ts，本分支未觸碰的檔案，main 上本來就有）
手動印出實際 kbdb_get_map 回應 JSON（見 PR 討論留言），確認 hints 會明講「triplet_count=0 但 entry_count>0 的庫別當空庫」

部署（未做，需 leo 手動觸發，兩支 worker + 一個靜態站）

merge 後，leo 自己在對應目錄下跑既有的發佈指令即可（kbdb worker、mcp worker、console-ui 靜態站各一次）。CLI 未變更，不需要重新打包。

## 目的（Arcrun#87 三次收尾） `kbdb_get_map` 過去只回 `triplet_count`——kb 以外幾乎全部庫顯示「0 triplets」，讀起來像空庫，AI 一開場看到就放棄查詢。實際上那些庫的 entries（原始 ingest 內容）都在，只是三元組萃取從沒對它們跑過。 ## 改了什麼 - `kbdb/src/actions/library-map.ts`：新增 `liveEntryCountsByLibrary`（即時統計 entries，排除 `entry_type='value'` 存儲細節與 `library_map` 自己的 block），`entry_count` 並排 `triplet_count` 回傳（全館 `listLibraryMaps` + 單庫 `getLibraryMapDetail`）。 - `mcp/src/lib/library-map.ts`：`renderLibraryMapLines`（MCP instructions 首屏文字）在 `triplet_count=0 且 entry_count>0` 時明講「有內容、只是還沒萃取，kbdb_search 查得到」，不再讓 0 觸目即誤讀成空庫。 - `mcp/src/tools/kbdb_map.ts`：`kbdb_get_map` 全館視圖的 hints 會點名「entry-only」的庫；單庫詳圖在 triplet_count=0/entry_count>0 時附同款提示。 - `console-ui/public/console/index.html`：看板卡片同步顯示「N 筆原始內容（尚未萃取）」。 - 新增測試：`kbdb/tests/library-map.test.ts`（entry_count 計數口徑）、`mcp/tests/unit/tools/kbdb-map.test.ts`（hints 內容、渲染文字、舊部署缺欄位容錯）。 ## 驗證 - kbdb：19 test files / 215 tests all green（含新測試 21 tests） - mcp：7 test files / 120 tests all green（含新測試） - tsc --noEmit：mcp 乾淨；kbdb 既有 4 個型別錯誤與本次改動無關（entries.ts route / auth.test.ts，本分支未觸碰的檔案，main 上本來就有） - 手動印出實際 `kbdb_get_map` 回應 JSON（見 PR 討論留言），確認 hints 會明講「triplet_count=0 但 entry_count>0 的庫別當空庫」 ## 部署（未做，需 leo 手動觸發，兩支 worker + 一個靜態站） merge 後，leo 自己在對應目錄下跑既有的發佈指令即可（kbdb worker、mcp worker、console-ui 靜態站各一次）。CLI 未變更，不需要重新打包。

Leo added 1 commit 2026-08-13 05:51:05 +00:00

fix(kbdb): 藏書地圖加 entry_count——triplet_count=0 不再被誤讀成「沒有知識」（Arcrun#87 三次收尾） 614fe44812

leo21c 實測：kbdb_get_map() 9 庫裡 8 庫 triplet_count:0／top_entities:[]（kb 以外全部），
一個全新 session 讀到這份地圖會合理但錯誤地判定「這些庫沒有知識」而放棄查詢——但
kbdb_search(mode=keyword) 找得到 42 筆真內容（來源 gitea:Leo/Arcrun@…／gitea:Leo/mira@…等），
其中 15 筆 entries 的 metadata_json.library 已正確標成 arcrun/mira/arcrun-harness/arcrun-rag。

查證（唯讀，未動 leo21c 任何寫入）：
- entries（原始 ingest 內容）與 triplet（從 entries 萃取出的三元組）是兩個不同存放處。
- kb 以外 7 庫：entries 有、library 標記正確；triplet 一筆都沒有——不是「三元組沒貼標」，
  是「三元組從沒被萃取」（另一條偵察線在查斷在哪一段，跨 repo，本 PR 不處理）。
- general 庫（未標 library 的三元組兜底分類）即時計數也是 0 ⇒ 沒有任何「有三元組但沒標庫」
  的候選 ⇒ Leo/Arcrun#87 先前那條批次補標通道（PR #114）在目前資料現況下會補到 0 筆，
  它解的是另一個問題，不是這次「地圖看起來是空的」的真因。

本次修法（純讀端加欄位，不碰任何寫入/部署/線上資源）：
- kbdb/src/actions/library-map.ts：新增 liveEntryCountsByLibrary()，依 entries 自己的
  metadata_json.$.library 分組即時計數（排除 entry_type='value' 儲存碎片與地圖自己的歷史
  摘要 block，避免自我膨脹）。listLibraryMaps／getLibraryMapDetail／recomputeLibraryMap
  的回傳都加上 entry_count，與 triplet_count 並排、互不覆蓋。
- mcp/src/lib/library-map.ts：renderLibraryMapLines（MCP 連線開場注入的那份地圖原文）
  triplet_count=0 但 entry_count>0 時改印「0 triplets／N 筆原始內容（尚未萃取關係，
  kbdb_search 查得到）」，不再只印「0 triplets」。
- mcp/src/tools/kbdb_map.ts：kbdb_get_map 工具的全館/單庫回應都帶 entry_count，並在符合
  條件時附加提示，明講「triplet_count=0 不代表沒有知識」。
- console-ui/public/console/index.html：藏書地圖看板卡片同步顯示，人類看的畫面同一件事。

順手修掉一個真 SQL bug：entry_count 排除條件原寫
`NOT (entry_type='block' AND json_extract(...)='library_map')`，SQL 三值邏輯下
metadata_json 沒有 $.kind 欄位時 json_extract 回 NULL、`NULL = 'library_map'` 為 NULL
（非 false），整條 WHERE 判定 NULL 而把所有列濾掉——改用 COALESCE(...,'') 修正
（新增測試以 sqlite 實跑驗證抓到並鎖住這個修法）。

測試：kbdb 21/21（新增 2 案，全套 215/215）；mcp kbdb-map 33/33（新增 7 案，全套 120/120）。
cypher-executor 既有 map/portal-data 相關測試（library-map-scope-108／kbdb-map-proxy／
portal-data）103/104 綠，唯一失敗（/portal HTML 殼 404）在未動過的 main checkout 上同樣
失敗，環境既有問題、與本次改動無關。

CP：◐ 半通。程式碼在此分支，測試綠燈，未併 main、未部署 leo21c——entry_count 要讓
leo21c 的真實使用者看到，需部署 kbdb＋mcp（cypher-executor 未改動，portal-data.ts
是透明轉發不需重部署）。三元組萃取斷在哪一段（真因）與 23/42 entries 未 embed
（語意搜尋覆蓋率）兩件不在本 PR 範圍，分別交給另一條偵察線與 embed reconcile 管線。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Leo referenced this pull request

2026-08-13 06:08:54 +00:00

AI 一打開沒有全景圖，不知道庫裡有哪些子庫、各裝了什麼 #81

Leo referenced this pull request

2026-08-13 06:10:42 +00:00

AI 一連上就知道「這裡有主人的知識庫」＋「讀不到」不再講成「不存在」 #118

Leo referenced this issue from a commit

2026-08-15 17:53:13 +00:00

Merge PR #117: 藏書地圖分開講「有幾筆內容」與「萃出幾條關係」（總管審過）

Leo referenced this issue from a commit

2026-08-15 17:53:13 +00:00

chore(builds): 重編成品——把 #117 地圖 entry_count 與 #118 讀不到≠不存在放進執行檔