Leo
c82d75f742
- tasks.md：R-EXT-4 改寫全 ✅、R-EXT-2 獨立 repo ✅、部署現況（待基本盤上線跑 install.sh） - wiki status：改寫完成快照 + 下次第一件事=實際部署 - wiki mistakes：記「讀違規現狀推翻鐵律」「embedding 非插件職責」兩條 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
62 lines
3.7 KiB
Markdown
62 lines
3.7 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 用 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]
|