Leo
efe8e165cf
按 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>
50 lines
2.3 KiB
Markdown
50 lines
2.3 KiB
Markdown
# 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]
|