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

4.5 KiB

Raw Permalink Blame History

system-dev/wiki/ — LLM 記憶系統

新 session 開始時從這裡導航。目的：讓 CC 不需要重新學習已知的事。維護者：CC（人不手動編輯這裡）

push 檔（session 開始由 hook 主動注入，CC 行動前必看見）

檔案	注入形態	內容
`status.md`	全文	當前進度、下一步（時態狀態）
`principles.md`	全文（一行一條）	跨全局設計原則，行動前必服從
`mistakes.md`	標題+一行症狀，全文按需展開	踩過的坑、被糾正的誤解（防不自覺盲區）

為什麼這三個 push 而非 pull：它們是「CC 不會主動查、但不看就出事」的盲區。詳見 /wiki-init 的「push vs pull」。

pull：cards/（CC 按需檢索）

一切知識內容——原文摘要、AI 筆記、決策、概念知識——都寫成 cards/<bucket>/ 的概念原子卡。 decisions-summary.md 已降級為 cards（決策＝知識內容）；既有的保留為相容。

維護規則

只增不刪——記錄 append，內容改了加新條目說明「舊的已更新」
status.md 每次 session 結束更新；mistakes/principles 一發現就 append
principles 一行一條、≤15 條（超過代表該合併或下放成 card）
新增一個檢索角度 = 在下方「多角度視圖」加一節，不開新實體檔、不問用戶

多角度視圖（由 /wiki-init、/wiki-capture 填入）

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` 的軸聚類，指向桶子索引）

#### 知識管理
- [[pkm/00-INDEX]] — PKM 知識管理（N 卡）

#### AI 協作
- [[ai/00-INDEX]] — AI 協作（M 卡）

（尚未建 cards，現有決策見下「決策角度」。）

決策角度（取代舊 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。

結構：INDEX（多角度入口）→ cards/<bucket>/00-INDEX.md（桶子索引，固定名）→ 概念原子卡。指 00-INDEX 一律帶路徑 [[bucket/00-INDEX]]（固定名跨桶撞名）；卡片間用裸 [[卡名]]。分類由卡片 frontmatter tags: 承載，標籤字典見 TAXONOMY.md。詳見 /wiki-init 規範。

4.5 KiB Raw Permalink Blame History Unescape Escape