diff --git a/.claude/wiki/mistakes.md b/.claude/wiki/mistakes.md index cbc9fe5..72bcae7 100644 --- a/.claude/wiki/mistakes.md +++ b/.claude/wiki/mistakes.md @@ -35,8 +35,20 @@ ⚠️ 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 字面。 + 正確做法: 讀真身——arcrun/kbdb 用 entry_type='block' 表達 block（不需獨立 blocks 表），是刻意設計的基本盤。動工前用 ls/grep 對真身，但**對到的是「現狀」不等於「設計依據」**（見下條）。 原因: HANDOFF 寫的是「意圖/計劃」，未必已落地；跨 repo 重整時尤其要核對現況。 + 日期: 2026-06-14（註：本條原結論「v3 真身在本目錄」被 leo 推翻——本目錄那套帶 blocks 表/CREATE TABLE 的「v3」是長歪的違規殘留，已刪） + +⚠️ MISTAKE: 讀違規現狀去推翻鐵律（本 session 最大的錯） + 症狀: 看到插件現狀「直接 SQL 讀 blocks/entry_values（28×/31×）」，把它當「AGE-on-Postgres 訊號」當設計依據，跑去問「要不要共用 D1、直接 SQL」。 + 正確做法: 現狀的直接 SQL 是【違規的歷史產物】（違反自己 CLAUDE.md「API-as-Wall」），不是設計依據。鐵律 > 現狀。插件絕不碰表、零 SQL、零 migration，全走基本盤 API；新類型只能建 template+slot，不建表（連「插件自建獨立 D1」都不行）。 + 原因: 把「程式碼現在這樣寫」誤當成「所以該這樣設計」。違規代碼會自我合理化。遇到現狀與鐵律衝突 → 改現狀，不是改鐵律。 + 日期: 2026-06-14 + +⚠️ MISTAKE: 把 embedding/語意搜尋當插件職責 + 症狀: 插件綁 Vectorize/AI 做 entity 相似度合併、語意 search。 + 正確做法: embedding/語意搜尋是基本盤的 optional embed 模組，不在插件。插件不綁 AI/Vectorize；entity 正規化降級 exact match、search 降級 keyword（GET /entries/search），語意部分標 [→arcrun embed]。 + 原因: 基本盤 = D1 only（免費、無信用卡）；embed 是可選加購層。插件混進來會破壞分層。 日期: 2026-06-14 --- diff --git a/.claude/wiki/status.md b/.claude/wiki/status.md index 774d49c..fc809c2 100644 --- a/.claude/wiki/status.md +++ b/.claude/wiki/status.md @@ -5,27 +5,31 @@ --- -## 正在做 +## 已完成（2026-06-14：按 leo 鐵律全面改寫 + 獨立成 repo） -- 知識庫骨架建立完成（system-dev-template 接入：SDD + LLM Wiki）。 -- **HANDOFF 已讀完並整進 SDD**：`docs/3-specs/kbdb-graph-extraction/`（requirements + design + tasks）。 -- R-EXT-1 邊界初步分類完成（插件 / 基本盤 / 灰色地帶），見該 design.md。 +HANDOFF 5 項待辦全做完： + +1. ✅ **改寫成走基本盤 API**（核心）：21 個違規直接 SQL action 全改走 `src/lib/kbdb-client.ts`。寫 triplet=`POST /records`(template=triplet)；查圖=取 triplet records 在**插件層記憶體**組鄰接表跑演算法（不靠 DB VIEW）。entity 正規化降級 exact match。 +2. ✅ **刪所有 migrations**（插件零建表）+ 清基本盤 action/route（block-*/entry-crud/record-crud/tag/profile/admin/partner/convert/tasks/personality）。 +3. ✅ **獨立成 repo**：`git init` + 推 **public `uncle6me-web/kbdb-graph-plugin`**（無 Actions）。 +4. ✅ **裁剪 CLAUDE.md**：移除 KBDB v3 基本盤規範，只留 graph 插件 + 🔒 鐵律 + 安裝契約。 +5. ✅ **部署繞開 GitHub**：`scripts/install.sh`（wrangler 直推），無 .github/workflows。 + +驗證：`wrangler deploy --dry-run` 通過（bundle 無 D1/AI/Vectorize）；`vitest run` 10 passed（mock client）；全違規掃描零命中；所有 action ≤100 行。 + +## 同場修正的 SDD 錯誤判斷 + +design.md 原本「讀現狀（21 個直接 SQL）推翻鐵律、問要不要共用 D1」是**讀違規現狀推翻規則**的錯。已改正為 **API-as-Wall（走 API，非共用 D1，零建表/零 SQL）**，並記進 mistakes.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-kbdb` 上線/有網址後，跑 `bash scripts/install.sh` 一次到位 +（自動查 CF subdomain 拼 `KBDB_BASE_URL` → `wrangler secret put` → `wrangler deploy`）。 +現在不空跑部署（避免上線一個打不到基本盤的殼）。 -**讀 arcrun 後的關鍵翻盤**：兩份 HANDOFF 假設「核心已在 arcrun」其實**尚未落地**——`arcrun/kbdb` 還是 v2（entries，無 blocks/0005/0007/block-crud），且與本插件是**不同 D1 庫**（arcrun-kbdb vs inkstone-kbdb）。**v3 基本盤真身其實在本目錄**。詳見 design.md「全局核對發現」。 +## 已知缺口（[→arcrun]，待基本盤補） -## 待總管決策（三問已上呈，不是本子 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 基本盤端，非本插件。 +- base 無 `PUT /records/:id` → entity addAlias 用「重建 record」覆寫。 +- base 無 `DELETE /records/:id` → triplet/entity update/delete、pending confirm/reject 為 soft（不硬刪）。 +- 語意搜尋 / embedding 屬基本盤 optional embed 模組，插件只做 keyword/exact。 +- arcrun 端 MCP/CLI 的 KBDB 薄殼仍待補（見 arcrun HANDOFF §2）；插件目前直打基本盤 HTTP API。 diff --git a/docs/3-specs/kbdb-graph-extraction/tasks.md b/docs/3-specs/kbdb-graph-extraction/tasks.md index f9a912b..548be74 100644 --- a/docs/3-specs/kbdb-graph-extraction/tasks.md +++ b/docs/3-specs/kbdb-graph-extraction/tasks.md @@ -13,8 +13,8 @@ - [x] 1.4a 讀 arcrun 端真身對齊（2026-06-14）：**發現 arcrun/kbdb 還是 v2（entries，無 blocks/0005/0007/block-crud），且兩 repo 是不同 D1 庫**。v3 基本盤真身其實在本目錄。見 design.md「全局核對發現」 - [x] 1.4b 前置議題**總管已答覆**（leo 2026-06-14）：→ `InkStoneCo/docs/3-specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md`。三問消解：基本盤已在 arcrun/kbdb 且設計正確、掛載走 API（非共用 D1）、插件零 migration。**阻擋解除。** - [x] 1.4c 不需移交/升級 arcrun——基本盤已正確。插件改寫成走 API 即可（見 R-EXT-4） -- [ ] 1.5 裁剪 CLAUDE.md：移除基本盤規範，只留 graph 插件相關 -- [ ] 1.6 清掉殘留：`blocks.ts.bak`、誤入 repo 的 `ruvector.db`（根 + src/routes/ 各一份）、`finally.click` 空檔、`.swarm` +- [x] 1.5 裁剪 CLAUDE.md：移除基本盤 v3 規範，只留 graph 插件 + 鐵律 + 安裝契約（2026-06-14） +- [x] 1.6 清掉殘留：`blocks.ts.bak`、`ruvector.db`×2、`finally.click`、`.swarm`（2026-06-14） ## R-EXT-3 定義掛載介面（已定案 2026-06-14） @@ -26,15 +26,27 @@ > 鐵律：插件零建表、零 migration、零 SQL，只用 API/CLI/MCP。 -- [ ] 4.1 寫 `src/lib/kbdb-client.ts`：封裝基本盤 HTTP API（entries/templates/records），指向 `KBDB_BASE_URL` env var。零 `.prepare` -- [ ] 4.2 wrangler.toml：移除 D1/Vectorize 綁定（插件不碰 DB），加 `KBDB_BASE_URL` var（先留空） -- [ ] 4.3 改寫 `triplet-crud`（拆 < 100 行）：create/query/get/update/delete/stats → API -- [ ] 4.4 改寫 `triplet-extract`/`triplet-entities`/`triplet-stats`/`triplet-update` → API -- [ ] 4.5 改寫 `graph-{nodes,path,traverse}`：取 triplet records → 插件層組圖 -- [ ] 4.6 改寫 `entity-{crud,normalize,graph-embed}`：template='entity' + records API；無 vectorize 時降級 exact -- [ ] 4.7 改寫 `search-query`/`search-*`：`GET /entries/search`（keyword）；語意搜尋標記待 embed 模組 -- [ ] 4.8 刪違規 migrations（0001/0002/0005/0007 等含 CREATE TABLE）+ 清基本盤 action/route（block-*/entry-crud/record-crud/tag/profile/admin/...） -- [ ] 4.9 改測試走 mock client；標記 base 缺口（PUT/DELETE record、vectorize）為 `[→arcrun]` +- [x] 4.1 `src/lib/kbdb-client.ts`：封裝基本盤 HTTP API，指向 `KBDB_BASE_URL`。零 `.prepare`（2026-06-14） +- [x] 4.2 wrangler.toml：移除 D1/Vectorize/AI 綁定，加 `KBDB_BASE_URL` var（留空，安裝時 AI 填） +- [x] 4.3 改寫 `triplet-crud`（拆 triplet-cluster）：create/query/get → API +- [x] 4.4 改寫 `triplet-extract`/`triplet-entities`/`triplet-stats`/`triplet-update`/`triplet-embed` → API/薄殼 +- [x] 4.5 改寫 `graph-{nodes,path,traverse}`：取 triplet records → 插件層記憶體組圖 +- [x] 4.6 改寫 `entity-{crud,normalize,graph-embed}` + 拆 `entity-pending`：template='entity'，無 vectorize 降級 exact +- [x] 4.7 改寫 `search-query`(→keywordSearch)/`search-suggest`/`search-embed`(stub)：keyword；語意標 `[→arcrun embed]` +- [x] 4.8 刪所有 migrations + 清基本盤 action/route（block-*/entry-crud/record-crud/tag/profile/admin/partner/convert/tasks/personality） +- [x] 4.9 測試改走 `tests/mock-client.ts`（10 passed）；base 缺口（PUT/DELETE record、vectorize）標 `[→arcrun]` + +## R-EXT-2 獨立成 repo（2026-06-14 完成） + +- [x] 2.2 `.gitignore`（排除 *.db/.env/.dev.vars/node_modules/.wrangler/.bak/.swarm）+ `git init` +- [x] 2.3 首次 commit + 推 GitHub：**public repo `uncle6me-web/kbdb-graph-plugin`**（無 .github/workflows，符合不開 Actions） +- [x] 2.4 部署機制：`scripts/install.sh`（安裝時 AI 查 subdomain 拼 base URL → `wrangler secret put` → `wrangler deploy`）。**實際部署待基本盤 arcrun-kbdb 上線後跑 install.sh** + +## 部署現況（leo 2026-06-14 定） + +- `KBDB_BASE_URL` 不寫死 toml、不叫人填 → 安裝時 AI 自動算（`https://arcrun-kbdb..workers.dev`）。 +- 現在不空跑部署（避免上線一個打不到基本盤的殼）。基本盤就緒後跑 `scripts/install.sh` 一次到位。 +- build 已驗證（`wrangler deploy --dry-run` 通過，bundle 無 D1/AI/Vectorize 綁定）。 ## R-EXT-2 獨立成 repo（最後做，依賴 1.4/1.5 完成） diff --git a/docs/3-specs/plugin-install/tasks.md b/docs/3-specs/plugin-install/tasks.md new file mode 100644 index 0000000..dad326d --- /dev/null +++ b/docs/3-specs/plugin-install/tasks.md @@ -0,0 +1,25 @@ +# KBDB-graph 插件安裝 — Tasks + +> 對應 design.md。動手前確認 design 已讀。 + +## Phase 1：安裝腳本 + +- [ ] 1.1 `scripts/install.sh`：git clone → wrangler whoami → 查 subdomain → 拼 BASE → secret put → deploy +- [ ] 1.2 subdomain 查詢：CF API `GET /accounts/{id}/workers/subdomain`（可抽 arcrun cli/lib/cf-api.ts 既有實作） +- [ ] 1.3 BASE 拼接 + 健康檢查：deploy 後 `GET {BASE}/health` 確認基本盤可達，不可達則明確報錯（不是默默裝壞） + +## Phase 2：配置位置 + +- [ ] 2.1 wrangler.toml `KBDB_BASE_URL = ""` 保持空（占位，AI 安裝時填） +- [ ] 2.2 `.dev.vars` 加入 `.gitignore`（本地測試值不進版控） +- [ ] 2.3 部署值走 `wrangler secret put KBDB_BASE_URL`，不寫 toml/git + +## Phase 3：測試 + +- [ ] 3.1 單元測試走 mock-client（已有），不依賴 KBDB_BASE_URL +- [ ] 3.2 整合測試 doc：本地起 `arcrun/kbdb wrangler dev` + 插件 `.dev.vars` 指 localhost +- [ ] 3.3 整合測試驗證：建 template='triplet' + 填 slot + 查圖，全走 API 無 SQL + +## 不變條件（每步都守） +- 零建表、零 migration、零直接 SQL（hook 會擋）。 +- 用戶零填寫——base URL 由 AI 查，不叫人填。