Files

T

uncle6 7a29dee357 feat: ingest 寫入端 + deprecate + get_source/refresh + wiki 合併 (issue #1 T3) (#2 )

* chore(wiki): 導入 system-dev-template + 合併 wiki 到新位置

- system-dev/ 模板包進版控（VERSION/docs/scripts/wiki 骨架）
- 逐檔合併舊 .claude/wiki/ → system-dev/wiki/：
  - status/mistakes/decisions-summary 真資料覆蓋空範本
  - INDEX 新「多角度視圖」結構 + 舊決策/導航併入（過時詞「萬物皆 Block」改 API-as-Wall）
  - principles/TAXONOMY 為新位置獨有，保留
- 刪舊 .claude/wiki/（git 識別為 rename，內容完整搬移）
- 三層機敏防護 hooks + wiki 命令更新

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(sdd): 立 ingest-contract SDD + 搬入 ingest-candidate 契約 (T3.1+T3.8)

對應 issue #1（頂層 mira-dissolve T3）。

- contracts/ingest-candidate.json：ingest→graph 邊界契約（自頂層搬入）
- contracts/README.md：標明候選(輸入)≠已存(triplet)
- docs/3-specs/ingest-contract/design.md + tasks.md：
  - ensureTemplate 改 slot-diff 補丁（取代 early-return，免遷移腳本）
  - 補 KbdbClient.updateRecord（base PATCH /records/:id）
  - ingest 流程：驗證(422)→idempotency(uri+hash)→先 append 後 deprecate
  - triplet template 增 source_uri+content_hash slot 承載 idempotency
  - 跨 repo 協調點（3.6 圖工具併 KBDB MCP）明列需 arcrun 配合

總管已認可四個設計決定（issue #1 comment）。鐵律：零建表/零 SQL/零 migration。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(ingest): POST /triplets/ingest 寫入端 + deprecate-then-append (T3.2-3.5)

對應 issue #1 T3 B 段。

- templates: TRIPLET_SLOTS 加 status/superseded_by/source_uri/content_hash；
  ENTITY_SLOTS 加 gloss；recordToTriplet 映射新欄位（缺省 status=active 相容舊資料）
- kbdb-client: ensureTemplate 改 slot-diff 補丁（既有 template 走 PATCH /templates/:id
  補缺 slot，取代 early-return → 免遷移腳本）；新增 updateRecord（PATCH /records/:id）
- triplet-ingest action（88 行純函式）：Zod strict 鏡射 ingest-candidate 契約 →
  idempotency（uri+hash 同→no-op）→ 先 append 後 deprecate（無「全無 active」空窗）
- POST /triplets/ingest route：strict 驗證失敗 → 422（禁送 graph 領域欄位）
- queryTriplets 預設 active-only（traverse/search/neighbors 皆經此），
  includeDeprecated opt-out 供 rollback/考古
- 6 測試案全綠（vitest 16 passed）；mock-client 同步 slot-diff + updateRecord

gates: zero SQL / zero migration / 無 D1·Vectorize·AI 綁定 / dry-run bundle 乾淨

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(graph): get_source + refresh 端點 + keyword 收斂 (T3.6-3.7)

對應 issue #1 T3 C 段（圖工具 HTTP API 備好，MCP 註冊薄殼待 arcrun）。

- get_source (3.7): graph-source.ts + GET /graph/source/:name —
  回節點的 active triplet 來源指標（uri/anchor/block_id/content_hash），去重。
  連帶加 source_anchor slot，ingest 從 source.anchor 帶入
- refresh (3.6/3.6b): graph-refresh.ts + POST /graph/refresh —
  純被動代轉 ingest（KBDB_INGEST_URL），只人發起、無排程/webhook（fan-out 紅線）。
  未設 URL → 誠實 forwarded:false，不假綠
- 3.6d: POST /search 移除公開 keyword 模式（重複 KBDB MCP），收斂 suggest-only；
  keywordSearch helper 留作 suggest 內部建構塊
- 3 新測試（get_source uri+anchor / active-only / refresh 未就緒誠實回報）

gates: vitest 19 passed / zero SQL / 無新綁定 / dry-run bundle 乾淨
待接：MCP 註冊薄殼併 arcrun u6u-mcp-server；refresh 端到端待 ingest(T4) 部署

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: richblack <leo21c@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-26 19:00:54 +08:00

3.8 KiB

Raw Blame History

架構決策摘要

遇到設計判斷時查這裡。完整脈絡在 docs/2-architecture/decisions/。

KBDB-graph 定位 — 2026-06-13

結論：本目錄 = KBDB 的 graph 插件（triplet 採集 + graph 查詢），獨立成 repo，類比 Apache AGE 之於 Postgres。原因：graph 能力較龐大、非基本儲存功能、leo 產權、較複雜 → 不留 arcrun。基本盤（block CRUD，D1 三表）= arcrun/kbdb，不在本目錄。詳細：docs/HANDOFF-kbdb-plugin.md；來源 InkStoneCo 頂層 matrix-rearrange Phase 2 (R2)。

🔒 KBDB 鐵律 + 插件 API-as-Wall 形態 — 2026-06-14（最高原則）

結論：插件【絕不碰表、零 SQL、零 migration】，讀寫全走基本盤 arcrun/kbdb HTTP API。新資料類型=建 template+填 slot，永不建表（連插件自建獨立 D1 都不行）。任何人不准動表（CREATE/ALTER/DROP）。embedding/語意搜尋屬基本盤 optional embed 模組，非插件職責。原因：比 AGE-on-Postgres 更嚴——AGE 能讀 Postgres 表，KBDB 插件連表都不許碰。真正的 API-as-Wall。鐵律已 hook 化（.claude/hooks/pre-{write,bash}-guard-no-table.sh，違反 exit 2）。詳細：InkStoneCo/docs/3-specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md + ADR docs/2-architecture/decisions/0001-api-as-wall.md。

獨立 repo 名 — 2026-06-14

結論：獨立 repo = public uncle6me-web/kbdb-graph-plugin（leo 拍板，沿用目錄名）。無 .github/workflows（不開 Actions）。原因：插件與基本盤 action 層零耦合，抽出乾淨。詳細：docs/3-specs/kbdb-graph-extraction/design.md。

掛載介面 = 基本盤 API（非共用 D1）— 2026-06-14（推翻原判斷）

結論：插件掛載 = HTTP API（KBDB_BASE_URL），不共用 D1、不直接 SQL、不建 VIEW。圖在插件層記憶體從 records 組裝。原因：⚠️ 原版「AGE-on-Postgres 共用 D1 + DB 掛載介面」是讀違規現狀（插件直接 SQL 讀 blocks/entry_values）推出來的錯判斷——那些直接 SQL 是違規歷史產物，不是設計依據。鐵律 > 現狀。詳細：design.md「掛載介面 = 基本盤 API」節 + mistakes.md「讀違規現狀推翻鐵律」。

安裝契約：KBDB_BASE_URL 安裝時 AI 填 — 2026-06-14

結論：KBDB_BASE_URL 不寫死 toml、不叫人填。安裝時 AI 查 CF subdomain 拼 https://arcrun-kbdb.<subdomain>.workers.dev，wrangler secret put + wrangler deploy。本地整合測試用 .dev.vars（非 .env）。原因：因部署而異（每個 self-hosted 用戶 subdomain 不同），但確定性可算（能 deploy 就能查 subdomain，同套 CF 憑證）。詳細：scripts/install.sh；參考 arcrun docs/3-specs/arcrun/sdk-and-website/self-hosted-init.md。

萬物皆 Block（KBDB v3） — 2026-02-28（已淘汰，2026-06-14 修正）

結論：⚠️ 本目錄那套帶獨立 blocks 表 + 0001/0005 CREATE TABLE 的「v3」是長歪的違規殘留，已刪。基本盤真身 = arcrun/kbdb 3 表（entries/templates/entry_values，entry_type='block' 表達 block，不需獨立 blocks 表）。原因：「萬物皆 Block」獨立 blocks 表違反「不建表」鐵律。基本盤規範歸 arcrun/kbdb，本 repo CLAUDE.md 已裁剪。詳細：DECISION-kbdb-v3-baseplane.md 一節「原提問的前提是錯的」。

避免再被 GitHub flag（上游鐵律）— 沿用

結論：禁跨 repo 自動同步 Actions；部署繞開 GitHub（wrangler / scp）；新 repo 預設不開 Actions。原因：當初 monorepo→多 worker 的 Actions 自動同步 + 高頻 API 害帳號被 flag。詳細：InkStoneCo 頂層 CLAUDE.md。

格式：

[主題] — [YYYY-MM-DD]

結論：[一句話] 原因：[簡短說明] 詳細：docs/2-architecture/decisions/[對應檔案]

3.8 KiB Raw Blame History Unescape Escape