docs(wiki): /wiki-update — 記 issue #1 T3 session 結果 + 4 決策 + 2 mistakes
- status.md：2026-06-26 進度（PR #2、T3 A/B/C 段完成、跨 repo 待接、缺口表） - decisions-summary.md：先 append 後 deprecate / idempotency slot / ensureTemplate slot-diff / refresh 純被動代轉 - mistakes.md：照字面刪 action 沒查反向依賴 / 拿錯 gate(tsc) 誤判改壞 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -39,21 +39,6 @@
|
|||||||
INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT，wiki 是改寫過的記憶。
|
INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT，wiki 是改寫過的記憶。
|
||||||
新增角度只要在這裡加一節（如「決策角度」「原則角度」），指向對應 cards 或 push 檔——**不必新增實體特殊檔**。
|
新增角度只要在這裡加一節（如「決策角度」「原則角度」），指向對應 cards 或 push 檔——**不必新增實體特殊檔**。
|
||||||
|
|
||||||
### 快速導航（本專案速覽）
|
|
||||||
|
|
||||||
**這個專案是什麼**：KBDB-graph —— KBDB 的 graph 插件（triplet 採集 + graph 查詢），類比 Apache AGE 之於 Postgres。已抽成獨立 public repo `uncle6me-web/kbdb-graph-plugin`（leo 產權）。基本盤（block CRUD，D1 三表）在 `arcrun/kbdb`，不在這。
|
|
||||||
|
|
||||||
**動工前必讀**：
|
|
||||||
- `docs/HANDOFF-kbdb-plugin.md` —— 本目錄專屬交棒。
|
|
||||||
- 上游約束見 `CLAUDE.md` 最頂 + `github.com/uncle6me-web/InkStoneCo`。
|
|
||||||
|
|
||||||
**文件去哪找**：
|
|
||||||
- SDD（design+tasks）→ `docs/3-specs/`（現有：kbdb-graph-extraction、blocks-edit-api、plugin-install、arcrun-key-auth）
|
|
||||||
- 歷史記錄 / bug 復盤 → `docs/5-records/`（PATCH 403 bug、upsert feature request）
|
|
||||||
- 分類規則全表 → `docs/README.md`
|
|
||||||
|
|
||||||
**絕對限制**：本目錄只做 graph 插件 / **API-as-Wall（插件絕不碰表、零 SQL、零 migration、零建表）** / 部署繞開 GitHub、禁跨 repo Actions / 樂高法（actions < 100 行）。
|
|
||||||
|
|
||||||
### 標籤角度（按 `TAXONOMY.md` 的軸聚類，指向桶子索引）
|
### 標籤角度（按 `TAXONOMY.md` 的軸聚類，指向桶子索引）
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
@@ -64,17 +49,11 @@ INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT
|
|||||||
- [[ai/00-INDEX]] — AI 協作（M 卡）
|
- [[ai/00-INDEX]] — AI 協作（M 卡）
|
||||||
```
|
```
|
||||||
|
|
||||||
（尚未建 cards，現有決策見下「決策角度」。）
|
### 決策角度（取代舊 decisions-summary.md 的視圖）
|
||||||
|
|
||||||
### 決策角度（取代舊 decisions-summary.md 的視圖；完整脈絡見 `decisions-summary.md` + `docs/2-architecture/decisions/`）
|
```markdown
|
||||||
|
- [[某決策卡]] — 一句話結論（YYYY-MM-DD）
|
||||||
- **KBDB-graph 定位**（2026-06-13）— 本 repo = KBDB 的 graph 插件，獨立成 repo，類比 AGE 之於 Postgres。
|
```
|
||||||
- **🔒 KBDB 鐵律 + API-as-Wall**（2026-06-14，最高原則）— 插件絕不碰表、零 SQL、零 migration，讀寫全走基本盤 HTTP API；新類型=建 template+填 slot，永不建表。
|
|
||||||
- **獨立 repo 名**（2026-06-14）— public `uncle6me-web/kbdb-graph-plugin`，無 Actions。
|
|
||||||
- **掛載介面 = 基本盤 API（非共用 D1）**（2026-06-14，推翻原判斷）— 圖在插件層記憶體從 records 組裝，不直接 SQL、不建 VIEW。
|
|
||||||
- **安裝契約：KBDB_BASE_URL 安裝時 AI 填**（2026-06-14）— AI 查 CF subdomain 拼 URL → `wrangler secret put` + `deploy`；本地測試用 `.dev.vars`。
|
|
||||||
- **~~萬物皆 Block（v3）~~**（2026-02-28 提出，2026-06-14 淘汰）— 帶獨立 blocks 表的「v3」是違規殘留已刪；基本盤真身 = arcrun/kbdb 3 表。
|
|
||||||
- **避免再被 GitHub flag**（上游鐵律）— 禁跨 repo 自動同步 Actions；部署繞開 GitHub。
|
|
||||||
|
|
||||||
> 結構：INDEX（多角度入口）→ `cards/<bucket>/00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。
|
> 結構：INDEX（多角度入口）→ `cards/<bucket>/00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。
|
||||||
> 指 `00-INDEX` **一律帶路徑** `[[bucket/00-INDEX]]`（固定名跨桶撞名）；卡片間用裸 `[[卡名]]`。
|
> 指 `00-INDEX` **一律帶路徑** `[[bucket/00-INDEX]]`（固定名跨桶撞名）；卡片間用裸 `[[卡名]]`。
|
||||||
|
|||||||
@@ -40,6 +40,26 @@
|
|||||||
**原因**：當初 monorepo→多 worker 的 Actions 自動同步 + 高頻 API 害帳號被 flag。
|
**原因**：當初 monorepo→多 worker 的 Actions 自動同步 + 高頻 API 害帳號被 flag。
|
||||||
**詳細**：InkStoneCo 頂層 CLAUDE.md。
|
**詳細**：InkStoneCo 頂層 CLAUDE.md。
|
||||||
|
|
||||||
|
## ingest 取代用「先 append 後 deprecate」— 2026-06-26（總管採納，優於頂層原寫法）
|
||||||
|
**結論**：`POST /triplets/ingest` 同 source.uri 出新 content_hash 時，**先 append 新批 active，再翻舊批 status=deprecated**。非頂層 SDD 原寫的「deprecate-then-append」。
|
||||||
|
**原因**：先翻舊批會出現「全無 active」的中途空窗（若 append 失敗）；先 append 保證任一時刻都有 active 集合可查。總管已回頭把頂層 design §5 對齊成此寫法。
|
||||||
|
**詳細**：`docs/3-specs/ingest-contract/design.md` §5；issue #1 總管確認 comment。
|
||||||
|
|
||||||
|
## idempotency 鍵存進 triplet template slot — 2026-06-26
|
||||||
|
**結論**：triplet template 增 `source_uri`+`content_hash`（+`source_anchor` 供 get_source）slot 承載 ingest idempotency；按 `source_uri` 分組 deprecate、同 hash no-op。`source_block_id`（Logseq）不夠用。
|
||||||
|
**原因**：純 plugin 領域 slot（base 不需知道），合鐵律（slot 非建表）；contract `ingest-candidate.json` 本就有 source.uri+content_hash，落地存進 slot 是自然動作，**不改 contract**。
|
||||||
|
**詳細**：`design.md` §3/§5；issue #1。
|
||||||
|
|
||||||
|
## ensureTemplate 改 slot-diff 補丁 — 2026-06-26
|
||||||
|
**結論**：`ensureTemplate` 命中既有 template 時，比對 slot 差集 → 缺的走 base `PATCH /templates/:id` 補上（**取代原 early-return**）。
|
||||||
|
**原因**：原 early-return 不補新 slot → seed 後新增的 slot（status/gloss…）對既有環境永遠進不來。slot-diff 讓既有+全新環境都自動收斂，免另跑一次性遷移腳本。
|
||||||
|
**詳細**：`src/lib/kbdb-client.ts`；issue #1 前置警示1。
|
||||||
|
|
||||||
|
## refresh 純被動代轉（人發起，守 fan-out 紅線）— 2026-06-26
|
||||||
|
**結論**：`POST /graph/refresh` 只代轉 ingest 重抓+萃，**只能人發起調用觸發**，禁排程/webhook/cron 自動 refresh。graph 自己不抓不萃（ingest 純餵食器職責）。
|
||||||
|
**原因**：自動 fan-out 正是當初害 GitHub flag 的模式。`KBDB_INGEST_URL` 未設時誠實回 `forwarded:false`，不假綠。
|
||||||
|
**詳細**：`src/actions/graph-refresh.ts`；issue #1 T3.6b。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
格式：
|
格式：
|
||||||
|
|||||||
@@ -51,6 +51,18 @@
|
|||||||
原因: 基本盤 = D1 only（免費、無信用卡）；embed 是可選加購層。插件混進來會破壞分層。
|
原因: 基本盤 = D1 only（免費、無信用卡）；embed 是可選加購層。插件混進來會破壞分層。
|
||||||
日期: 2026-06-14
|
日期: 2026-06-14
|
||||||
|
|
||||||
|
⚠️ MISTAKE: 照「移除某端點」字面就整檔刪 action（沒查反向依賴）
|
||||||
|
症狀: issue 寫「移除 search-query.ts 代理 base 關鍵字那條」→ 差點整個刪 search-query.ts，但 search-suggest.ts 內部依賴 keywordSearch helper，刪了會連帶弄壞 suggest。
|
||||||
|
正確做法: 動手前 grep 反向依賴（誰 import 它）。「移除公開端點」≠「刪內部 helper」——收斂 POST /search 為 suggest-only，keywordSearch 留作 suggest 的內部建構塊。
|
||||||
|
原因: 把「移除對外能力」誤當「刪實作檔」。一個 helper 常同時餵公開端點和內部功能，刪檔前必須看清它還餵誰。
|
||||||
|
日期: 2026-06-26
|
||||||
|
|
||||||
|
⚠️ MISTAKE: tsc 報一堆錯就以為自己改壞了
|
||||||
|
症狀: 跑 `tsc --noEmit` 看到 index.ts/entities.ts/graph.ts 一片 Hono 型別錯，疑心是這次改動破壞編譯。
|
||||||
|
正確做法: 先確認專案的 gate 是什麼——本 repo gate = `vitest run`（package.json test script），不是 tsc。那些 Hono 型別錯是既有 noise（改動前就在）。判斷「我是否弄壞」要對齊專案真正的驗收命令，不是隨手挑一個工具。
|
||||||
|
原因: 預設 tsc 乾淨＝健康，但此 repo tsc 從來沒乾淨過；拿錯的 gate 當基準會誤判。
|
||||||
|
日期: 2026-06-26
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
格式：
|
格式：
|
||||||
|
|||||||
+27
-19
@@ -1,35 +1,43 @@
|
|||||||
# 當前狀態
|
# 當前狀態
|
||||||
|
|
||||||
> 更新時間：2026-06-14
|
> 更新時間：2026-06-26
|
||||||
> 每次 session 結束必須更新此檔（用 /wiki-update）。
|
> 每次 session 結束必須更新此檔（用 /wiki-update）。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 已完成（2026-06-14：按 leo 鐵律全面改寫 + 獨立成 repo）
|
## 最新（2026-06-26：issue #1 T3 — ingest 寫入端 + graph 端 API）
|
||||||
|
|
||||||
HANDOFF 5 項待辦全做完：
|
開 PR [#2](https://github.com/uncle6me-web/kbdb-graph-plugin/pull/2)（分支 `feat/ingest-contract-sdd`，4 commits，未 merge）。對應 [issue #1](https://github.com/uncle6me-web/kbdb-graph-plugin/issues/1)（頂層 mira-dissolve T3）。
|
||||||
|
|
||||||
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）。
|
1. ✅ **wiki 合併**：舊 `.claude/wiki/` → `system-dev/wiki/`（導入 system-dev-template）。
|
||||||
3. ✅ **獨立成 repo**：`git init` + 推 **public `uncle6me-web/kbdb-graph-plugin`**（無 Actions）。
|
2. ✅ **ingest-contract SDD**（`docs/3-specs/ingest-contract/`）+ 搬入 `contracts/ingest-candidate.json`（T3.1/3.8）。
|
||||||
4. ✅ **裁剪 CLAUDE.md**：移除 KBDB v3 基本盤規範，只留 graph 插件 + 🔒 鐵律 + 安裝契約。
|
3. ✅ **寫入端 + 取代**（T3.2–3.5）：`POST /triplets/ingest`、ensureTemplate slot-diff 補丁、`updateRecord`、idempotency、**先 append 後 deprecate**、active-only 查詢。
|
||||||
5. ✅ **部署繞開 GitHub**：`scripts/install.sh`（wrangler 直推），無 .github/workflows。
|
4. ✅ **get_source + refresh**（T3.6/3.7）：`GET /graph/source/:name`、`POST /graph/refresh`（純被動代轉）、keyword 收斂（3.6d）。
|
||||||
|
|
||||||
驗證：`wrangler deploy --dry-run` 通過（bundle 無 D1/AI/Vectorize）；`vitest run` 10 passed（mock client）；全違規掃描零命中；所有 action ≤100 行。
|
驗證：`vitest run` **19 passed**（mock）；zero SQL / 無 D1·Vectorize·AI；`wrangler deploy --dry-run` bundle 乾淨；所有 action ≤100 行。
|
||||||
|
|
||||||
## 同場修正的 SDD 錯誤判斷
|
## 正在做 / 阻擋
|
||||||
|
|
||||||
design.md 原本「讀現狀（21 個直接 SQL）推翻鐵律、問要不要共用 D1」是**讀違規現狀推翻規則**的錯。已改正為 **API-as-Wall（走 API，非共用 D1，零建表/零 SQL）**，並記進 mistakes.md。
|
- [🔄] **PR #2 待 review/merge** — 阻擋點：等 leo/總管。graph repo 端 T3 實作面已收斂，剩跨 repo 接通。
|
||||||
|
|
||||||
## 下次 session 第一件事
|
## 下次 session 第一件事
|
||||||
|
|
||||||
**實際部署**：等基本盤 `arcrun-kbdb` 上線/有網址後，跑 `bash scripts/install.sh` 一次到位
|
**確認 PR #2 狀態**：若已 merge → 切回 `main` 拉新狀態；若有 review 意見 → 在 `feat/ingest-contract-sdd` 上改。
|
||||||
（自動查 CF subdomain 拼 `KBDB_BASE_URL` → `wrangler secret put` → `wrangler deploy`）。
|
本 repo 端 T3 無剩餘可單獨做的 task（其餘待跨 repo / 部署，見下）。
|
||||||
現在不空跑部署（避免上線一個打不到基本盤的殼）。
|
|
||||||
|
|
||||||
## 已知缺口（[→arcrun]，待基本盤補）
|
## 待負責人確認
|
||||||
|
|
||||||
- base 無 `PUT /records/:id` → entity addAlias 用「重建 record」覆寫。
|
- **PR #2 merge** — 等：leo/總管 review。
|
||||||
- base 無 `DELETE /records/:id` → triplet/entity update/delete、pending confirm/reject 為 soft（不硬刪）。
|
- **MCP 註冊薄殼**（圖工具 traverse/neighbors/source/refresh 併入 arcrun `u6u-mcp-server`）— 等：總管協調 arcrun，**不另起 graph MCP**。graph 端 HTTP API 已備好。
|
||||||
- 語意搜尋 / embedding 屬基本盤 optional embed 模組，插件只做 keyword/exact。
|
|
||||||
- arcrun 端 MCP/CLI 的 KBDB 薄殼仍待補（見 arcrun HANDOFF §2）；插件目前直打基本盤 HTTP API。
|
## 已知問題 / 缺口
|
||||||
|
|
||||||
|
| 問題 | 優先級 | 狀態 |
|
||||||
|
|------|--------|------|
|
||||||
|
| refresh 端到端走通 | 🟡 | 待 ingest repo（T4）部署 + `KBDB_INGEST_URL` 設定；未設時誠實回 `forwarded:false` |
|
||||||
|
| semantic normalize | 🟡 | 仍 exact-only，留接口；待 base embed（Arcrun #7，code done 待部署） |
|
||||||
|
| MCP 工具實際可用 | 🟡 | graph 端 API 備好，待 arcrun 註冊薄殼 |
|
||||||
|
| base `DELETE /records/:id` | ⚪ | 仍無 → triplet/entity delete 為 soft（不硬刪）；死資料清除原則見頂層 T8 |
|
||||||
|
|
||||||
|
> 註：base `PATCH /records/:id` **已就緒**（Arcrun #6 closed，本 session ingest deprecate 即用此）。舊 status 列的「base 無 PUT /records/:id」缺口已部分解除。
|
||||||
|
|||||||
Reference in New Issue
Block a user