Leo
4137043be2
- 鋪檔 SDD-LIFECYCLE.md / pending-changes.md / 新版 sdd-guard.sh / sdd-check.md / sdd-active-check.sh - ingest-pipeline design.md 掛 status: paused（實作 18/19 完成、部署收尾懸置、無現行開發）→ 0 active 合法 - CLAUDE.md 加 SDD 鐵律段（濃縮五條＋現況註記） - wiki status 更新＋記 PR #3 src 管線只在 github-dead/main 的斷層 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
66 lines
4.7 KiB
Markdown
66 lines
4.7 KiB
Markdown
# 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](https://github.com/uncle6me-web/kbdb-graph-plugin) 上，graph 又掛在基本盤 `arcrun/kbdb` 上。
|
||
> 關鍵鐵律：禁跨 repo 自動同步 Actions / 部署繞開 GitHub / API-as-Wall（不碰儲存）。
|
||
|
||
> 本檔由 Claude Code 自動讀取。所有此目錄下的開發必須遵守以下規則。
|
||
|
||
---
|
||
|
||
## 📐 SDD 生命週期鐵律（全文：`system-dev/docs/3-specs/SDD-LIFECYCLE.md`，2026-07-17 leo 拍板）
|
||
|
||
1. **單一活性**：全 repo 任何時刻最多一份 `status: active` 的 SDD，所有開發任務唯一對應它的 tasks；找不到對應任務→停下來問。
|
||
2. **禁止自建 SDD**：CC 任何情況不得主動開新 SDD；任務層變更改現行 tasks 標日期，規格層變更走第 3 條。
|
||
3. **規格變更只有一條路**：proposal 寫入 `system-dev/docs/3-specs/pending-changes.md` 後**停止**，等使用者明說 confirm；沒 confirm 就照現行 SDD 繼續。
|
||
4. **開新 SDD 先搬任務**：confirm 後先把舊 SDD 未完成任務逐條搬入新 SDD——搬完前不准寫任何程式碼；舊的標 closed+superseded_by 移入 archive/。
|
||
5. **session 開始三數字回報**：「現行規格〈名稱〉＋未完成任務 N＋待裁決 proposal M」，回報出現兩份 active＝當場糾正。
|
||
|
||
> **本 repo 現況（2026-07-17）**：唯一 SDD `ingest-pipeline` 標 `status: paused`（實作 18/19 完成，剩 Worker 部署＋端到端驗證懸置）→ **目前 0 份 active，合法**（無現行開發）。要恢復開發＝由人把 ingest-pipeline 升回 active。硬約束：`.claude/hooks/sdd-guard.sh`（PreToolUse 擋無 active 時寫 code 檔）＋ `system-dev/scripts/sdd-active-check.sh`（獨立檢查，可掛 pre-commit/CI）。
|
||
|
||
---
|
||
|
||
## 🔒 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`。
|