kbdb-ingest-plugin/CLAUDE.md

CLAUDE.md — KBDB-ingest 插件開發規範

上游約束（InkStoneCo 總管）：此 repo 是 InkStoneCo 子專案，受頂層知識庫約束。 動工前讀 github.com/uncle6me-web/InkStoneCo 的 CLAUDE.md + docs/3-specs/mira-dissolve/（本插件的跨專案藍圖）。 定位（leo 2026-06-26）：此 repo = KBDB-ingest 插件（餵食器），堆疊裡最薄一層。掛在 kbdb-graph-plugin 上，graph 又掛在基本盤 arcrun/kbdb 上。 關鍵鐵律：禁跨 repo 自動同步 Actions / 部署繞開 GitHub / API-as-Wall（不碰儲存）。

本檔由 Claude Code 自動讀取。所有此目錄下的開發必須遵守以下規則。

---

🔒 ingest 鐵律（leo 2026-06-26 拍板）

1. 純餵食器，不碰儲存 — ingest 只 POST 候選 envelope 給 graph 的寫入 API，不直連 base、不碰 D1/Vectorize、不碰任何表。牆是「儲存」不是「運算」：准做萃取（LLM 呼叫），不准碰儲存。
2. 不算向量 normalize — 詞+gloss 的語義 normalize 歸 base optional embed 模組，不在 ingest（單檔視角算不準跨庫同義）。
3. 不帶查詢 MCP — ingest 是 ambient 餵食器，沒人互動「問」它。只帶薄 ops CLI（人手動觸發重萃）。觸發由 KBDB MCP 的 refresh 代理。
4. 三守則（北極星 §5.2） — 無環（graph 永不回呼 ingest）、純 API（走 graph HTTP 寫入端，不碰 graph 內部）、凍結契約（contracts/ingest-candidate.json 是唯一耦合面）。
5. 部署繞開 GitHub Actions（被 flag 教訓）— 走 wrangler；runtime 用 GitHub API/webhook 拉 repo 是 runtime 行為，不衝突。

---

職責（採取為主，extract 為 fallback，跨庫織網是主職）

路徑 A（用了 system-dev-template，優先）：
  GitHub 拉 → 本地 CC 已建好的三元組 + gloss → ingest 採取（拉）→ POST envelope
路徑 B（裸原文，fallback）：
  GitHub 拉 → 本地無三元組 → ingest extract（模型用戶可選）→ 候選 (s,p,o)+gloss → POST envelope
共同：跨 repo 匯總 → 織跨庫三元組關聯（ingest 主職，本地做不到）

• 採取 > 萃取：本地萃成效更好（知識連結長在生產當下，LLM Wiki 指引）；ingest 優先採取本地已建的。
• extract 模型用戶可選（像 /model，選意圖非型號）+ 品質門檻（萃得出深層暗示 + 中文過關才入白名單）；預設 Haiku；深萃 Claude via CC（走月費，不走 API）。
• 跨 repo 織網：匯總多 repo 三元組（單 repo 本地看不到的橋/異見）＝ingest 不可取代的價值。

掛載架構

基本盤 arcrun/kbdb（不動）
   ↑ API
kbdb-graph-plugin（三元組領域 + 查詢 + POST /triplets/ingest 寫入端）
   ↑ API（ingest 餵候選 envelope）
kbdb-ingest-plugin（本 repo，純餵食器）
   · SourceAdapter：GitHub 拉 + content-hash（source.uri = github:owner/repo@path）
   · 採取本地三元組 / extract(text, model) fallback
   · POST envelope → graph 寫入 API

凍結契約：contracts/ingest-candidate.json（與 graph repo 同一份）。SDD：docs/3-specs/ingest-pipeline/（待立）。

命名

只養一個品牌 Arcrun；本元件功能名當水管：ingest。