chore: template 1.9.x 知識庫遷移 → system-dev/
把 system-dev-template 1.9.x 的知識庫基建搬進 git（從功能 PR 拆出，獨立成筆）： - system-dev/wiki/：LLM 記憶系統（principles 鐵律 + 5 張 ingest 卡 + INDEX/TAXONOMY + status/mistakes） - system-dev/docs/：SDD 新家（3-specs/ + 2-architecture/ + README/SKILL）；ingest-pipeline SDD 從 docs/3-specs/ 搬來 - system-dev/scripts/：install/update - .claude/：wiki/SDD harness（commands + hooks：session-recall / sdd-guard / wiki-secret-scan） SDD 位置統一：docs/3-specs/ingest-pipeline → system-dev/docs/3-specs/ingest-pipeline （對齊 SDD guard hook 預期路徑 + template 1.9.x 規約）。 純基建遷移，不含任何功能程式碼（src/tests/contracts 在功能 PR #3）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,76 @@
|
||||
# [子系統名稱] — Design
|
||||
|
||||
> 狀態：[草稿 / 審核中 / 已採納 / 已廢棄]
|
||||
> 建立：[YYYY-MM-DD] | 最後更新：[YYYY-MM-DD]
|
||||
> 負責人：[名稱]
|
||||
|
||||
---
|
||||
|
||||
## 一句話說明
|
||||
|
||||
[這個子系統做什麼，一句話。]
|
||||
|
||||
---
|
||||
|
||||
## 背景與問題
|
||||
|
||||
[為什麼需要這個子系統？解決了什麼問題？]
|
||||
|
||||
---
|
||||
|
||||
## 範圍
|
||||
|
||||
### 包含（In Scope）
|
||||
- [這個 SDD 涵蓋的功能]
|
||||
|
||||
### 不包含（Out of Scope）
|
||||
- [明確排除的功能，避免 CC 自行延伸]
|
||||
|
||||
---
|
||||
|
||||
## 設計
|
||||
|
||||
### 架構概覽
|
||||
|
||||
[用文字或 ASCII 描述系統結構]
|
||||
|
||||
```
|
||||
[元件 A] → [元件 B] → [元件 C]
|
||||
```
|
||||
|
||||
### 關鍵決策
|
||||
|
||||
| 決策 | 選擇 | 原因 | 放棄的選項 |
|
||||
|------|------|------|----------|
|
||||
| [問題] | [選擇] | [原因] | [其他選項] |
|
||||
|
||||
### API / 介面定義
|
||||
|
||||
[端點、資料格式、輸入輸出規格]
|
||||
|
||||
### 資料模型
|
||||
|
||||
[資料結構、欄位說明]
|
||||
|
||||
---
|
||||
|
||||
## 技術限制
|
||||
|
||||
- [不能用什麼]
|
||||
- [必須相容什麼]
|
||||
- [效能要求]
|
||||
|
||||
---
|
||||
|
||||
## 驗收標準
|
||||
|
||||
完成的定義（CC 完成任何 task 前必須確認）：
|
||||
- [ ] [可客觀驗證的條件，例如：POST /api/xxx 回傳 200]
|
||||
- [ ] [...]
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [連結到相關 ADR]
|
||||
- [連結到相關 SDD]
|
||||
@@ -0,0 +1,50 @@
|
||||
# [子系統名稱] — Tasks
|
||||
|
||||
> 權威來源：此檔案是進度真相，不是 CLAUDE.md 或對話。
|
||||
> 規則：動手前標 [🔄]，完成立刻標 [x]，不批次更新。
|
||||
|
||||
---
|
||||
|
||||
## Phase 1：[Phase 名稱]
|
||||
|
||||
### 前置條件
|
||||
- [ ] [這個 Phase 開始前必須完成的事]
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] 1.1 [task 描述]
|
||||
- 驗收：[客觀可驗證的完成標準]
|
||||
- 注意：[CC 容易犯的錯，可選]
|
||||
|
||||
- [ ] 1.2 [task 描述]
|
||||
- 驗收：[...]
|
||||
|
||||
---
|
||||
|
||||
## Phase 2：[Phase 名稱]
|
||||
|
||||
> 前置條件：Phase 1 全部完成
|
||||
|
||||
- [ ] 2.1 [task 描述]
|
||||
- 驗收：[...]
|
||||
|
||||
---
|
||||
|
||||
## 完成定義
|
||||
|
||||
整個 SDD 完成 = 以下全部達成：
|
||||
- [ ] 所有 tasks 標 [x]
|
||||
- [ ] 驗收標準通過（有客觀證據）
|
||||
- [ ] design.md 與實作一致（如有出入需更新）
|
||||
|
||||
---
|
||||
|
||||
## 狀態說明
|
||||
|
||||
| 標記 | 意義 |
|
||||
|------|------|
|
||||
| `[ ]` | 未開始 |
|
||||
| `[🔄]` | 進行中（當前 session）|
|
||||
| `[x]` | 完成（有驗收證據）|
|
||||
| `[~]` | 暫緩（說明原因）|
|
||||
| `[!]` | 阻擋中（說明阻擋原因）|
|
||||
@@ -0,0 +1,38 @@
|
||||
# ingest pipeline — Design
|
||||
|
||||
> 對應 requirements.md。**架構設計（envelope 契約、職責切割、normalize 歸屬、MCP 邊界、模型策略）在 InkStoneCo `docs/3-specs/mira-dissolve/design.md`。本檔只放 ingest 內部設計。**
|
||||
|
||||
## 1. 資料流
|
||||
|
||||
```
|
||||
GitHub repo MD（精耕 LLM Wiki）
|
||||
│ commit / content-hash 變動
|
||||
▼
|
||||
SourceAdapter（拉 + content-hash）
|
||||
│
|
||||
├─ 路徑 A：本地已建三元組+gloss → 採取（拉）
|
||||
└─ 路徑 B：裸原文 → extract(text, model) → 候選 (s,p,o)+gloss
|
||||
│
|
||||
▼ 跨 repo 匯總（織跨庫關聯）
|
||||
▼ POST envelope（contracts/ingest-candidate.json）
|
||||
graph 寫入端 POST /triplets/ingest
|
||||
```
|
||||
|
||||
## 2. envelope（= contracts/ingest-candidate.json）
|
||||
|
||||
形狀與職責切割見 InkStoneCo design §3。ingest 給：原始 s/p/o + source.* + extractor.* + nodes[].gloss/type + confidence。**禁送**：id / clusters / bridge_score / 時間戳 / 邊上 type（graph 算）。
|
||||
|
||||
## 3. extract 模型策略
|
||||
|
||||
見 InkStoneCo design §6.6：用戶選意圖非型號、品質門檻白名單（深層暗示+中文）、預設 Haiku、深萃 Claude via CC、難度隨來源分層（AI 報告弱模型夠/人類 vault 須好模型）。
|
||||
|
||||
## 4. 觸發
|
||||
|
||||
被 KBDB MCP `refresh` 代轉（人發起，非自動 fan-out）。flag 紅線見 InkStoneCo design §6.7：禁 Actions/webhook 自動觸發。
|
||||
|
||||
## 5. cherry-pick 來源
|
||||
|
||||
- `polaris/mira/tools/_kbdb_client.py` → 純餵食器 client。
|
||||
- `polaris/mira/arcrun/wiki_synthesis.yaml` classify 節點 → extract。
|
||||
- 兩個 KBDB skill block（精耕規則 prompt）。
|
||||
詳 InkStoneCo requirements §6。
|
||||
@@ -0,0 +1,27 @@
|
||||
# ingest pipeline — Requirements
|
||||
|
||||
> 建立：2026-06-26
|
||||
> **跨專案藍圖在 InkStoneCo `docs/3-specs/mira-dissolve/`（R7 攝入分工、§6.6 模型策略、§6.7 MCP 邊界）。本 SDD 只放 ingest 內部實作細節。**
|
||||
> 凍結契約：`contracts/ingest-candidate.json`（與 graph repo 同一份，唯一耦合面）。
|
||||
|
||||
## 範圍
|
||||
|
||||
ingest 插件內部：SourceAdapter（拉）+ 採取/extract + 跨庫織網匯總 + POST envelope 給 graph。**不涉**graph 內部圖演算法、不涉 base 儲存。
|
||||
|
||||
## 需求
|
||||
|
||||
- **R1 SourceAdapter**：GitHub 拉 repo + content-hash（`source.uri = github:owner/repo@path`）。webhook/排程觸發，或被 KBDB MCP `refresh` 代轉觸發。
|
||||
- **R2 採取（路徑 A，優先）**：用了 system-dev-template 的 repo → 本地 CC 已建三元組 + gloss → ingest 拉取，不重萃。
|
||||
- **R3 extract（路徑 B，fallback）**：裸原文 → 萃 (s,p,o)+gloss。模型用戶可選（意圖非型號）+ 品質門檻白名單（深層暗示 + 中文）；預設 Haiku；深萃 Claude via CC；JSON-fail 升級閘。
|
||||
- **R4 跨 repo 織網**：匯總多 repo 三元組（單 repo 看不到的橋/異見）＝主職。
|
||||
- **R5 輸出**：POST envelope（嚴格符合 contract）給 graph `POST /triplets/ingest`，不直連 base。
|
||||
- **R6 ops CLI**：手動觸發重萃。不帶查詢 MCP。
|
||||
|
||||
## 約束（沿用 ingest 鐵律，見 CLAUDE.md）
|
||||
|
||||
- 純餵食器、不碰儲存、不算向量、不帶查詢 MCP、部署繞 Actions、三守則（無環/純 API/凍結契約）。
|
||||
|
||||
## 待對端
|
||||
|
||||
- graph 的 `POST /triplets/ingest` 寫入端（InkStoneCo T3.3，graph repo 實作）。
|
||||
- 模型品質門檻測試集（含中文 + 人類暗示樣本，InkStoneCo §6.6）。
|
||||
@@ -0,0 +1,48 @@
|
||||
# ingest pipeline — Tasks
|
||||
|
||||
> 唯一進度來源。狀態：[ ] 未開始 [🔄] 進行中 [x] 完成 [⏸] 卡住
|
||||
> 跨專案藍圖：InkStoneCo `docs/3-specs/mira-dissolve/`。
|
||||
> 實作分支：`claude/ingest-t1-t5-implementation`（vitest 28 passed / tsc clean / dry-run 乾淨）。
|
||||
|
||||
## T0 repo 骨架
|
||||
|
||||
- [x] 0.1 建 public repo `uncle6me-web/kbdb-ingest-plugin`
|
||||
- [x] 0.2 CLAUDE.md（上游指針 + ingest 鐵律）+ README + .gitignore
|
||||
- [x] 0.3 `contracts/ingest-candidate.json`（從頂層 SDD 複製，凍結契約）
|
||||
- [x] 0.4 SDD 三件式骨架（本輪搬到 `system-dev/docs/3-specs/`，對齊 SDD guard hook）
|
||||
- [x] 0.5 package.json / tsconfig / wrangler.toml / vitest.config（參考 kbdb-graph-plugin：Hono + zod-openapi，無 D1/Vectorize/AI 綁定）
|
||||
|
||||
## T1 SourceAdapter（R1）— `src/lib/source-adapter.ts`
|
||||
|
||||
- [x] 1.1 GitHub 拉 repo（runtime git/trees + contents API，非 Actions）；GitHubFetcher 介面（測試走 mock）
|
||||
- [x] 1.2 content-hash（per-file sha256；source.uri = github:owner/repo@path，makeSourceUri/parseSourceUri round-trip）
|
||||
- [x] 1.3 被 graph `POST /graph/refresh` 代轉觸發的受理端：`POST /refresh`（`src/index.ts`，被動代轉、無排程）
|
||||
|
||||
## T2 採取（R2，路徑 A 優先）— `src/lib/harvest.ts`
|
||||
|
||||
- [x] 2.1 採取本地 CC 已建三元組 + gloss（template 1.8.0+ 格式：frontmatter gloss、`## 實體`、`## 關聯` typed-edge；卡對卡 vs 內文端點分流）
|
||||
- [x] 2.2 cherry-pick `_kbdb_client.py` → 改純餵食器 `src/lib/graph-client.ts`（POST envelope，**不寫 KBDB/base**）
|
||||
|
||||
## T3 extract（R3，路徑 B fallback）— `src/lib/extract.ts`
|
||||
|
||||
- [x] 3.1 cherry-pick `wiki_synthesis.yaml` classify 模式 → extract prompt（JSON nodes[]+triplets[]）
|
||||
- [x] 3.2 模型用戶可選（意圖非型號，LlmCaller 介面，預設 shallow/Haiku、deep/Claude via CC）
|
||||
- [ ] 3.3 模型測試集（中文 + 人類暗示樣本，轉回歸測試）— **deferred**（先跑預設；護欄 + parse 已有單元測試）
|
||||
- [x] 3.4 JSON-fail 升級閘（淺萃 fail/過稀 → 升 deep 一次）
|
||||
- [x] 3.5 第一版不 embed（仍【打標】embed/predicate_embed 供未來 base 讀標；embed 動作等 Arcrun #7）
|
||||
- [x] 3.x 端點對齊硬自檢護欄（`src/lib/endpoint-check.ts`，leo 壓測 14→0；自檢 + autoAlign 補齊）
|
||||
|
||||
## T4 跨 repo 織網（R4，主職）— `src/lib/weave.ts`
|
||||
|
||||
- [x] 4.1 匯總多 repo 三元組 → 偵測跨庫橋（同名 node 跨 ≥2 repo）+ 異見（同 s/o 對、不同謂詞）；**不算 bridge_score**（graph 領域，禁送）
|
||||
|
||||
## T5 輸出 + CLI（R5/R6）
|
||||
|
||||
- [x] 5.1 POST envelope 給 graph `POST /triplets/ingest`（嚴格符合 contract；buildEnvelope strict + 顯式禁送欄位自檢提早攔）。對齊【full contract】（含 embed/id/aliases/predicate_embed，總管裁定 ingest 不退）
|
||||
- [x] 5.2 薄 ops CLI（`scripts/ingest-cli.mjs`：refresh 經 Worker / pull dry-run）；**不帶查詢 MCP**
|
||||
|
||||
## 阻擋項 / 誠實標記
|
||||
|
||||
1. ⏸ **端到端 ingest→graph 走通**：依賴 graph receiver 補對齊 full contract（graph#1 補對齊任務，**現 .strict() 會 422 新向量化欄位**）+ ingest 部署 + `GRAPH_BASE_URL` 設定 → **待部署驗**，未假綠。
|
||||
2. ⏸ embed 依賴 base vectorize（Arcrun #7）。第一版不 embed（只打標）已動。
|
||||
3. T3.3 模型測試集 deferred；refresh 端 extract（Workers AI）第一版只走採取，深萃留 CLI/CC。
|
||||
Reference in New Issue
Block a user