kbdb-graph-plugin/system-dev/wiki/mistakes.md

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 用 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

---

格式： ⚠️ MISTAKE: [錯誤描述，一句話] 症狀: [CC 通常怎麼表現這個錯] 正確做法: [應該怎麼做] 原因: [為什麼會錯] 日期: [YYYY-MM-DD]