feat: KBDB-graph 插件獨立 — 全面改寫成走基本盤 API（API-as-Wall）
按 leo 鐵律（2026-06-14）把插件從「直接 SQL 操作基本盤表」改寫成 「只透過基本盤 arcrun/kbdb HTTP API 讀寫」。零建表、零 migration、零 SQL。 - 新增 src/lib/kbdb-client.ts：唯一對外通道，封裝 entries/templates/records API - 新增 src/lib/templates.ts：triplet/entity template 定義（替代建表） - 改寫 21 個違規 action（triplet/graph/entity/search）→ 走 client，圖在插件層記憶體組裝 - 移除所有 migrations、D1/Vectorize/AI 綁定；embedding/語意搜尋歸基本盤 optional 模組 - index.ts 只掛 triplets/graph/entities/search 路由；基本盤路由歸 arcrun/kbdb - 測試改走 mock client（純 node）；裁剪 CLAUDE.md 只留 graph 插件 + 鐵律 - 修正 SDD design.md「讀現狀推翻鐵律」的錯誤判斷（共用 D1 → API-as-Wall） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
# .claude/wiki/ — LLM 記憶系統
|
||||
|
||||
> 新 session 開始時從這裡導航。
|
||||
> 目的：讓 CC 不需要重新學習已知的事。
|
||||
> 維護者：CC（人不手動編輯這裡）
|
||||
|
||||
---
|
||||
|
||||
## 核心檔案
|
||||
|
||||
| 檔案 | 何時讀 | 內容 |
|
||||
|------|-------|------|
|
||||
| `status.md` | session 開始第一件事 | 當前進度、下一步 |
|
||||
| `mistakes.md` | 做新功能前 | 已知誤解、快速檢查清單 |
|
||||
| `decisions-summary.md` | 遇到設計判斷時 | 架構決策摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 維護規則
|
||||
|
||||
1. 只增不刪——記錄 append，決策改了加新條目說明「舊決策已更新」
|
||||
2. status.md 每次 session 結束更新
|
||||
3. mistakes.md 每次被糾正後 append
|
||||
4. 發現新的重要決策 → 同時更新 decisions-summary.md 和 docs/2-architecture/decisions/
|
||||
|
||||
---
|
||||
|
||||
## 快速導航
|
||||
|
||||
**這個專案是什麼**：KBDB-graph —— KBDB 的 graph 插件（triplet 採集 + graph 查詢），類比 Apache AGE 之於 Postgres。要抽成獨立 repo（leo 產權）。基本盤（block CRUD）在 `arcrun/kbdb`，不在這。
|
||||
|
||||
**動工前必讀**：
|
||||
- `docs/HANDOFF-kbdb-plugin.md` —— 本目錄專屬交棒（待辦：確認邊界 / 改名+git init+推 GitHub / 定義掛載介面）。
|
||||
- 上游約束見 `CLAUDE.md` 最頂 + `github.com/uncle6me-web/InkStoneCo`。
|
||||
|
||||
**文件去哪找**：
|
||||
- SDD（design+tasks）→ `docs/3-specs/`（現有：arcrun-key-auth、blocks-edit-api）
|
||||
- 歷史記錄 / bug 復盤 → `docs/5-records/`（現有：PATCH 403 bug、upsert feature request）
|
||||
- 分類規則全表 → `docs/README.md`
|
||||
|
||||
**絕對限制**：本目錄只做 graph 插件 / 萬物皆 Block（禁 CREATE/ALTER TABLE）/ API-as-Wall / 部署繞開 GitHub、禁跨 repo Actions / 樂高法（actions < 100 行）。
|
||||
@@ -0,0 +1,34 @@
|
||||
# 架構決策摘要
|
||||
|
||||
> 遇到設計判斷時查這裡。
|
||||
> 完整脈絡在 docs/2-architecture/decisions/。
|
||||
|
||||
---
|
||||
|
||||
## KBDB-graph 定位 — 2026-06-13
|
||||
**結論**：本目錄 = KBDB 的 graph 插件（triplet 採集 + graph 查詢），獨立成 repo，類比 Apache AGE 之於 Postgres。
|
||||
**原因**：graph 能力較龐大、非基本儲存功能、leo 產權、較複雜 → 不留 arcrun。基本盤（block CRUD，D1 三表）= `arcrun/kbdb`，不在本目錄。
|
||||
**詳細**：`docs/HANDOFF-kbdb-plugin.md`；來源 InkStoneCo 頂層 `matrix-rearrange` Phase 2 (R2)。
|
||||
|
||||
## 獨立 repo 名 + 邊界乾淨度 — 2026-06-14
|
||||
**結論**：獨立 repo = 新 repo `uncle6me-web/kbdb-graph-plugin`（leo 拍板，沿用目錄名）。grep 證實插件與基本盤 action 層零耦合，耦合只在 DB 層（讀 blocks/entry_values + triplets VIEW）。
|
||||
**原因**：乾淨的 AGE-on-Postgres，插件抽出無程式碼牽連；唯一要設計的是 DB 掛載介面。
|
||||
**詳細**：`docs/3-specs/kbdb-graph-extraction/design.md`（灰色地帶結論 + 掛載介面）。
|
||||
|
||||
## 萬物皆 Block（KBDB v3）— 2026-02-28
|
||||
**結論**：一張 Block 表 + type 欄位，禁 CREATE/ALTER TABLE，新資料類型用 template；API-as-Wall。
|
||||
**原因**：零 migration 擴充；所有讀寫經 API 不繞過直打 D1。
|
||||
**詳細**：`CLAUDE.md` 下半（v3 全規範，含基本盤，待裁剪只留 graph 插件相關）。
|
||||
|
||||
## 避免再被 GitHub flag（上游鐵律）— 沿用
|
||||
**結論**：禁跨 repo 自動同步 Actions；部署繞開 GitHub（wrangler / scp）；新 repo 預設不開 Actions。
|
||||
**原因**：當初 monorepo→多 worker 的 Actions 自動同步 + 高頻 API 害帳號被 flag。
|
||||
**詳細**：InkStoneCo 頂層 CLAUDE.md。
|
||||
|
||||
---
|
||||
|
||||
格式：
|
||||
## [主題] — [YYYY-MM-DD]
|
||||
**結論**：[一句話]
|
||||
**原因**：[簡短說明]
|
||||
**詳細**：docs/2-architecture/decisions/[對應檔案]
|
||||
@@ -0,0 +1,49 @@
|
||||
# CC 已知誤解 + 避坑方法
|
||||
|
||||
> 做新功能前讀一遍。
|
||||
> 格式：每條必須有症狀 + 正確做法 + 原因。
|
||||
|
||||
---
|
||||
|
||||
## 快速檢查清單（做任何事前）
|
||||
|
||||
- [ ] 有對應 SDD 嗎？沒有 → 停手
|
||||
- [ ] 這次修改會影響哪些模組？有沒有連帶破壞？
|
||||
- [ ] 驗收標準是什麼？有客觀證據嗎？
|
||||
|
||||
---
|
||||
|
||||
## 誤解記錄
|
||||
|
||||
⚠️ MISTAKE: 把基本盤 block CRUD 當成本目錄的職責
|
||||
症狀: 在本目錄改/實作 block CRUD、migration 0001/0002、整套 v3 規範。
|
||||
正確做法: 本目錄只做 graph 插件（triplet/graph/entity）。基本盤歸 arcrun/kbdb。動手前先讀 docs/HANDOFF-kbdb-plugin.md 確認邊界。
|
||||
原因: 2026-06-13 定調 KBDB-graph = 插件（AGE-on-Postgres 模式），但舊 CLAUDE.md 下半仍是整套 v3 規範，易誤導。
|
||||
日期: 2026-06-13
|
||||
|
||||
⚠️ MISTAKE: 以為本目錄在 git 版控內、用 git mv 搬檔
|
||||
症狀: git mv 報 "not under version control" / "source directory is empty"。
|
||||
正確做法: 本目錄無獨立 git（matrix 降級後脫離，且被頂層 gitignore）→ 用普通 mv。改名 KBDB-graph 後才 git init。
|
||||
原因: git repo 是 InkStoneCo 頂層，本目錄被 gitignore。
|
||||
日期: 2026-06-14
|
||||
|
||||
⚠️ MISTAKE: 部署或同步走 GitHub Actions
|
||||
症狀: 設計依賴 GitHub API 列檔、push 觸發跨 repo 自動同步。
|
||||
正確做法: 部署繞開 GitHub（wrangler 直推 / scp）；讀檔走本地 fs；新 repo 不開 Actions。
|
||||
原因: 上游鐵律——當初正是這模式害帳號被 flag。
|
||||
日期: 2026-06-14
|
||||
|
||||
⚠️ MISTAKE: 假設「核心已在 arcrun」是既成事實
|
||||
症狀: 照 HANDOFF 字面以為 arcrun/kbdb 已是 v3 基本盤、插件直接掛上去、共用同一 D1。
|
||||
正確做法: 讀真身——arcrun/kbdb 其實還是 v2（entries，無 blocks/0005/0007/block-crud），與本插件是不同 D1 庫（arcrun-kbdb vs inkstone-kbdb）。v3 基本盤真身其實在本目錄。動工前用 ls/grep 對真身，不信 HANDOFF 字面。
|
||||
原因: HANDOFF 寫的是「意圖/計劃」，未必已落地；跨 repo 重整時尤其要核對現況。
|
||||
日期: 2026-06-14
|
||||
|
||||
---
|
||||
|
||||
格式：
|
||||
⚠️ MISTAKE: [錯誤描述，一句話]
|
||||
症狀: [CC 通常怎麼表現這個錯]
|
||||
正確做法: [應該怎麼做]
|
||||
原因: [為什麼會錯]
|
||||
日期: [YYYY-MM-DD]
|
||||
@@ -0,0 +1,31 @@
|
||||
# 當前狀態
|
||||
|
||||
> 更新時間：2026-06-14
|
||||
> 每次 session 結束必須更新此檔（用 /wiki-update）。
|
||||
|
||||
---
|
||||
|
||||
## 正在做
|
||||
|
||||
- 知識庫骨架建立完成（system-dev-template 接入：SDD + LLM Wiki）。
|
||||
- **HANDOFF 已讀完並整進 SDD**：`docs/3-specs/kbdb-graph-extraction/`（requirements + design + tasks）。
|
||||
- R-EXT-1 邊界初步分類完成（插件 / 基本盤 / 灰色地帶），見該 design.md。
|
||||
|
||||
## 下次 session 第一件事
|
||||
|
||||
讀 `docs/3-specs/kbdb-graph-extraction/tasks.md`。R-EXT-1 邊界 + grep + 讀 arcrun 全局核對都做完。**主阻擋 = 前置議題定案（task 1.4b）**，等 leo/arcrun 答覆三問（見下）。定案後：升 arcrun v3 / 定掛載形態 → 移交 → 裁剪 CLAUDE.md → git init 推 `uncle6me-web/kbdb-graph-plugin`。
|
||||
|
||||
**讀 arcrun 後的關鍵翻盤**：兩份 HANDOFF 假設「核心已在 arcrun」其實**尚未落地**——`arcrun/kbdb` 還是 v2（entries，無 blocks/0005/0007/block-crud），且與本插件是**不同 D1 庫**（arcrun-kbdb vs inkstone-kbdb）。**v3 基本盤真身其實在本目錄**。詳見 design.md「全局核對發現」。
|
||||
|
||||
## 待總管決策（三問已上呈，不是本子 repo 能拍板）
|
||||
|
||||
leo 指示「整理成 wiki、由總管決策」。已寫成頂層決策文件：
|
||||
📍 `InkStoneCo/.agents/specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md`（頂層 tasks Phase 2 task 2.5 已連結）
|
||||
|
||||
三問：(1) v3 基本盤怎麼進 arcrun (2) 掛載形態共用 D1 vs 走 API (3) 0005 歸屬。總管答覆後本 repo 才能解除 1.4b / R-EXT-3 阻擋。
|
||||
|
||||
## 已知問題
|
||||
|
||||
- 本目錄目前**無獨立 git**（matrix 降級後脫離），改名後需 `git init`。
|
||||
- `CLAUDE.md` 下半部仍是整套 KBDB v3 規範（含基本盤 Block CRUD），與「只做 graph 插件」新定位不符，待裁剪（HANDOFF 待辦 1 的一部分）。
|
||||
- 上游 bug 未解：`PATCH /blocks/:id` 回 403（見 `docs/5-records/incidents/BUG-2026-05-29-...`）——屬 arcrun/kbdb 基本盤端，非本插件。
|
||||
Reference in New Issue
Block a user