Leo
fbd375f7ac
- 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>
5.0 KiB
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: 照「移除某端點」字面就整檔刪 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
格式： ⚠️ MISTAKE: [錯誤描述，一句話] 症狀: [CC 通常怎麼表現這個錯] 正確做法: [應該怎麼做] 原因: [為什麼會錯] 日期: [YYYY-MM-DD]