From fbd375f7ac3d71e505cc7d088f9932b6e66253ab Mon Sep 17 00:00:00 2001 From: richblack Date: Fri, 26 Jun 2026 19:22:16 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20/wiki-update=20=E2=80=94=20?= =?UTF-8?q?=E8=A8=98=20issue=20#1=20T3=20session=20=E7=B5=90=E6=9E=9C=20+?= =?UTF-8?q?=204=20=E6=B1=BA=E7=AD=96=20+=202=20mistakes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- system-dev/wiki/INDEX.md | 29 +++--------------- system-dev/wiki/decisions-summary.md | 20 ++++++++++++ system-dev/wiki/mistakes.md | 12 ++++++++ system-dev/wiki/status.md | 46 ++++++++++++++++------------ 4 files changed, 63 insertions(+), 44 deletions(-) diff --git a/system-dev/wiki/INDEX.md b/system-dev/wiki/INDEX.md index eb34019..32300ff 100644 --- a/system-dev/wiki/INDEX.md +++ b/system-dev/wiki/INDEX.md @@ -39,21 +39,6 @@ INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT，wiki 是改寫過的記憶。 新增角度只要在這裡加一節（如「決策角度」「原則角度」），指向對應 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` 的軸聚類，指向桶子索引） ```markdown @@ -64,17 +49,11 @@ INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT - [[ai/00-INDEX]] — AI 協作（M 卡） ``` -（尚未建 cards，現有決策見下「決策角度」。） +### 決策角度（取代舊 decisions-summary.md 的視圖） -### 決策角度（取代舊 decisions-summary.md 的視圖；完整脈絡見 `decisions-summary.md` + `docs/2-architecture/decisions/`） - -- **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。 +```markdown +- [[某決策卡]] — 一句話結論（YYYY-MM-DD） +``` > 結構：INDEX（多角度入口）→ `cards//00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。 > 指 `00-INDEX` **一律帶路徑** `[[bucket/00-INDEX]]`（固定名跨桶撞名）；卡片間用裸 `[[卡名]]`。 diff --git a/system-dev/wiki/decisions-summary.md b/system-dev/wiki/decisions-summary.md index e0131e4..82b6389 100644 --- a/system-dev/wiki/decisions-summary.md +++ b/system-dev/wiki/decisions-summary.md @@ -40,6 +40,26 @@ **原因**：當初 monorepo→多 worker 的 Actions 自動同步 + 高頻 API 害帳號被 flag。 **詳細**：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。 + --- 格式： diff --git a/system-dev/wiki/mistakes.md b/system-dev/wiki/mistakes.md index 72bcae7..5076ab7 100644 --- a/system-dev/wiki/mistakes.md +++ b/system-dev/wiki/mistakes.md @@ -51,6 +51,18 @@ 原因: 基本盤 = 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 + --- 格式： diff --git a/system-dev/wiki/status.md b/system-dev/wiki/status.md index fc809c2..e263ea8 100644 --- a/system-dev/wiki/status.md +++ b/system-dev/wiki/status.md @@ -1,35 +1,43 @@ # 當前狀態 -> 更新時間：2026-06-14 +> 更新時間：2026-06-26 > 每次 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）。 -3. ✅ **獨立成 repo**：`git init` + 推 **public `uncle6me-web/kbdb-graph-plugin`**（無 Actions）。 -4. ✅ **裁剪 CLAUDE.md**：移除 KBDB v3 基本盤規範，只留 graph 插件 + 🔒 鐵律 + 安裝契約。 -5. ✅ **部署繞開 GitHub**：`scripts/install.sh`（wrangler 直推），無 .github/workflows。 +完成： +1. ✅ **wiki 合併**：舊 `.claude/wiki/` → `system-dev/wiki/`（導入 system-dev-template）。 +2. ✅ **ingest-contract SDD**（`docs/3-specs/ingest-contract/`）+ 搬入 `contracts/ingest-candidate.json`（T3.1/3.8）。 +3. ✅ **寫入端 + 取代**（T3.2–3.5）：`POST /triplets/ingest`、ensureTemplate slot-diff 補丁、`updateRecord`、idempotency、**先 append 後 deprecate**、active-only 查詢。 +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 第一件事 -**實際部署**：等基本盤 `arcrun-kbdb` 上線/有網址後，跑 `bash scripts/install.sh` 一次到位 -（自動查 CF subdomain 拼 `KBDB_BASE_URL` → `wrangler secret put` → `wrangler deploy`）。 -現在不空跑部署（避免上線一個打不到基本盤的殼）。 +**確認 PR #2 狀態**：若已 merge → 切回 `main` 拉新狀態；若有 review 意見 → 在 `feat/ingest-contract-sdd` 上改。 +本 repo 端 T3 無剩餘可單獨做的 task（其餘待跨 repo / 部署，見下）。 -## 已知缺口（[→arcrun]，待基本盤補） +## 待負責人確認 -- base 無 `PUT /records/:id` → entity addAlias 用「重建 record」覆寫。 -- base 無 `DELETE /records/:id` → triplet/entity update/delete、pending confirm/reject 為 soft（不硬刪）。 -- 語意搜尋 / embedding 屬基本盤 optional embed 模組，插件只做 keyword/exact。 -- arcrun 端 MCP/CLI 的 KBDB 薄殼仍待補（見 arcrun HANDOFF §2）；插件目前直打基本盤 HTTP API。 +- **PR #2 merge** — 等：leo/總管 review。 +- **MCP 註冊薄殼**（圖工具 traverse/neighbors/source/refresh 併入 arcrun `u6u-mcp-server`）— 等：總管協調 arcrun，**不另起 graph MCP**。graph 端 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」缺口已部分解除。