docs(sdd): SDD 生命週期鐵律遷移 + SDD 位置統一到 system-dev/docs/3-specs/

- 位置統一：舊 docs/3-specs/ 五份 SDD git mv 到 system-dev/docs/3-specs/，舊位置留 README 指針 - 狀態判定：0 份 active（無現行開發，合法）；paused×3（ingest-contract/kbdb-graph-extraction/plugin-install，等跨 repo 接通）；closed×2 入 archive/（arcrun-key-auth/blocks-edit-api 死件，附封存原因） - 鋪檔（自 system-dev-template v1.15.0）：SDD-LIFECYCLE.md、pending-changes.md、sdd-guard.sh 新版、sdd-check.md、sdd-active-check.sh - hook 掛載：settings.json PreToolUse Write|Edit 加 sdd-guard.sh - CLAUDE.md：SDD 鐵律段（濃縮五條＋0-active 註明重啟先升 active）＋修正遷移後舊路徑 - 驗證：sdd-active-check exit 0；guard pipe-test 0-active 擋 code 寫入(exit 2)/md 放行(exit 0) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-17 17:03:58 +08:00
parent b53c5c94a9
commit d2618758e2
20 changed files with 279 additions and 21 deletions
@@ -0,0 +1,124 @@
+---
+status: closed        # active | draft | paused | closed（生命週期鐵律見 ../../SDD-LIFECYCLE.md）
+superseded_by: ""
+---
+
+> **封存（2026-07-17）**：舊 KBDB 時代草稿（等 richblack review，帳號已 suspend）。key auth 屬基本盤 arcrun/kbdb 職責，非本插件範圍（2026-06-14 API-as-Wall 改寫後失效）。
+
+# KBDB — Arcrun Key Auth
+
+> 建立：2026-05-05
+> 狀態：草稿，待 richblack review
+
+---
+
+## 背景
+
+KBDB 是 Arcrun 平台的子服務（對外統稱 Arcrun）。目前 KBDB 有兩種身份：
+
+- **Internal**：後端機器使用 `KBDB_INTERNAL_TOKEN`（hex secret）
+- **Partner**：外部系統使用 `pk_live_xxx` API Key，需先由 internal 建立 partner 記錄
+
+問題：Arcrun 用戶（人類或 AI agent）登入 arcrun.dev 取得的 `ak_xxx` Key 無法直接存取 KBDB。要存 KBDB 目前沒有自助路徑。
+
+## 目標
+
+讓 Arcrun 用戶的 `ak_xxx` Key **直接可用於 KBDB**，不需要額外申請第二把 Key。
+
+---
+
+## 設計決策
+
+### Key 格式不變
+
+Arcrun Key 格式維持 `ak_` 前綴（32 char hex），KBDB 新增對這個前綴的識別邏輯。
+不引入新的 Key 格式，不改 Arcrun 的 Key 產生邏輯。
+
+### KBDB 驗證路徑新增 `ak_` 支援
+
+現有 `index.ts` auth middleware 的 Partner 驗證區塊（line 103）僅接受 `pk_` 前綴。
+改為同時接受 `pk_` 和 `ak_`，查詢同一張 partner 表（tpl-partner）。
+
+```
+if (effectiveToken.startsWith('pk_') || effectiveToken.startsWith('ak_')) {
+  const partner = await lookupPartner(c.env.DB, tokenHash);
+  ...
+}
+```
+
+### Arcrun 登入時寫入 KBDB partner 記錄
+
+Arcrun `cypher-executor/src/routes/auth.ts` 的 OAuth callback（`/auth/callback`）
+在建立 UserRecord 後，呼叫 KBDB `POST /partners` 建立對應的 partner 記錄。
+
+寫入時機：
+- 新用戶首次登入 → 建立 partner 記錄（`upsert` 語意：若已存在則跳過）
+- Key rotate（`PUT /me/api-key/rotate`）→ 舊 partner revoke，建新 partner 記錄
+- Key revoke（`DELETE /me/api-key`）→ KBDB partner 設為 revoked
+
+寫入內容：
+```json
+{
+  "name": "arcrun:{email}",
+  "org_namespace": "arcrun:{email}",
+  "api_key_hash": "SHA-256(ak_xxx)",
+  "status": "active"
+}
+```
+
+`org_namespace` 用 `arcrun:{email}` 格式，與 KBDB 原有的 partner namespace 不衝突。
+
+### Namespace 隔離
+
+用戶只能存取自己 `org_namespace` 下的 KBDB 資料，與其他用戶完全隔離。
+`org_namespace = 'arcrun:{email}'`，不是 admin，不會被提升為 internal。
+
+### 服務啟用 UI（Dashboard /keys）
+
+初期：Arcrun 用戶登入即自動建立 KBDB partner 記錄（無需勾選），
+因為「KBDB 是 Arcrun 的捆綁服務」，就像 n8n 登進去 Data Table 就在那裡。
+
+未來（有計費需求時）：Dashboard `/keys` 頁面可加 toggle 控制，切換時
+呼叫 `PATCH /me/kbdb` → cypher-executor 再去 KBDB 啟用/停用 partner。
+
+---
+
+## 實作範圍（本 SDD）
+
+### KBDB 側（`matrix/kbdb/`）
+
+**修改** `src/index.ts`：
+- auth middleware Partner 驗證區塊：將 `effectiveToken.startsWith('pk_')` 改為同時接受 `ak_`
+
+**不改**：
+- `src/actions/partner-auth.ts`（`hashToken` / `lookupPartner` 邏輯不變）
+- `src/routes/partners.ts`（`POST /partners` 介面不變，Arcrun 呼叫此 endpoint 建記錄）
+- D1 schema（`tpl-partner` template 不變）
+
+### Arcrun 側（`matrix/arcrun/cypher-executor/`）
+
+屬於 `frontend-redesign` SDD 範圍內的後端補充，見該 SDD tasks.md。
+本 SDD **不**負責 Arcrun 側實作，僅說明預期行為：
+
+1. OAuth callback 成功後，以 `KBDB_INTERNAL_TOKEN` 呼叫 KBDB `POST /partners`
+2. Key rotate 時：先 KBDB `DELETE /admin/partners/{id}` (revoke)，再建新記錄
+3. Key revoke 時：KBDB `DELETE /admin/partners/{id}`
+
+---
+
+## 不做的事
+
+- 不改 Key 格式（`ak_` 保留）
+- 不合併 Arcrun USERS_KV 和 KBDB partner 表（兩邊各自維護）
+- 不做跨 namespace 的資料共享
+- 不做 KBDB 側的 OAuth 驗證（KBDB 永遠只驗 token hash）
+
+---
+
+## 風險
+
+| 風險 | 緩解 |
+|------|------|
+| Arcrun 寫 KBDB 失敗（KBDB 暫時不可用） | 登入仍成功；寫 KBDB 失敗靜默 log，用戶下次 rotate key 時重建 |
+| `ak_` Key 被猜測 | 32 char hex，entropy 足夠；與 `pk_` 同等安全 |
+| email 含特殊字元破壞 namespace | `org_namespace` 用 `arcrun:` + raw email，D1 存 TEXT 無問題 |
@@ -0,0 +1,60 @@
+# KBDB Arcrun Key Auth — Tasks
+
+> 建立：2026-05-05
+> 權威進度來源：本檔。完成一項立刻 `[x]`，不批次。
+
+---
+
+## Phase 0 — SDD 建立
+
+- [x] 撰寫 `design.md`
+- [x] 撰寫 `tasks.md`（本檔）
+- [ ] richblack review + 認可 → 開 Phase 1
+
+---
+
+## Phase 1 — KBDB auth middleware 接受 `ak_` Key
+
+**修改檔案**：`matrix/kbdb/src/index.ts`
+
+- [x] 1.1 將 line 103 的 `effectiveToken.startsWith('pk_')` 改為
+      `effectiveToken.startsWith('pk_') || effectiveToken.startsWith('ak_')`
+- [ ] 1.2 本地跑現有測試確認不 break：`pnpm test`
+
+---
+
+## Phase 2 — Arcrun OAuth callback 寫入 KBDB partner 記錄
+
+**修改檔案**：`matrix/arcrun/cypher-executor/src/routes/auth.ts`
+
+> 注意：此 Phase 需要 Arcrun 側有 `KBDB_INTERNAL_TOKEN` 和 `KBDB_BASE_URL` 兩個 env binding。
+
+- [x] 2.1 在 `Bindings` type（`types.ts`）加入 `KBDB_INTERNAL_TOKEN?: string` 和 `KBDB_BASE_URL?: string`
+- [x] 2.2 建立 helper `src/lib/kbdb-partner.ts`：
+      - `ensureKbdbPartner(env, email, apiKey)` → PUT /admin/partners/by-key-hash，失敗靜默 log
+      - `revokeKbdbPartner(env, oldApiKey)` → DELETE /admin/partners/{id}，失敗靜默 log
+- [x] 2.3 在 OAuth callback（UserRecord 建立/取得後）呼叫 `ensureKbdbPartner`（fire-and-forget）
+- [x] 2.4 在 `PUT /me/api-key/rotate` 呼叫：`revokeKbdbPartner(oldKey)` + `ensureKbdbPartner(newKey)`
+- [x] 2.5 在 `DELETE /me/api-key` 呼叫 `revokeKbdbPartner`
+- [ ] 2.6 `wrangler secret put KBDB_INTERNAL_TOKEN`（cypher-executor Worker）← 需要人工執行
+- [x] 2.7 在 `wrangler.toml` 加 `KBDB_BASE_URL = "https://kbdb.finally.click"`
+
+另外：KBDB `admin.ts` 新增 `PUT /admin/partners/by-key-hash` endpoint（upsert by hash，不產生新 key）。
+KBDB `types.ts` 加入 `KBDB_INTERNAL_TOKEN` 到 Bindings。
+KBDB `admin.ts` 放寬 `org_namespace` regex（允許 `arcrun:email@domain` 格式）。
+
+---
+
+## Phase 3 — 驗證
+
+- [ ] 3.1 新用戶 OAuth 登入 → 確認 KBDB partner 記錄建立（`GET /admin/partners` 查詢）
+- [ ] 3.2 用 `ak_xxx` Key 直接打 KBDB `GET /blocks` → 確認 200（非 401）
+- [ ] 3.3 Key rotate → 確認舊 Key 401，新 Key 200
+- [ ] 3.4 Key revoke → 確認舊 Key 401
+
+---
+
+## 目前狀態
+
+- Phase 0 已完成（等 richblack 認可）
+- Phase 1–3 全部 `[ ]`，等認可後動工
@@ -0,0 +1,234 @@
+---
+status: closed        # active | draft | paused | closed（生命週期鐵律見 ../../SDD-LIFECYCLE.md）
+superseded_by: ""
+---
+
+> **封存（2026-07-17）**：基於舊「萬物皆 Block／blocks 表」架構，該架構已判定為違規殘留並刪除（2026-06-14 改寫）；base `PATCH /records/:id` 已由 Arcrun #6 實作取代本需求。
+
+# KBDB — Blocks Edit API
+
+> **建立**：2026-05-06
+> **狀態**：草稿，待 richblack review
+> **依賴**：`matrix/kbdb/CLAUDE.md`（萬物皆 Block 架構，2026-02-28 鎖定）
+> **驅動需求**：`polaris/mira/.agents/specs/mira-app/design.md`（前端 inline edit 直寫 KBDB 的需求）
+
+---
+
+## 0. 背景
+
+KBDB v3「萬物皆 Block」架構鎖定後，現役 routes 涵蓋 Block CRUD 多數操作，但**缺少編輯既有 block 的 PATCH endpoints**。具體缺口：
+
+| 操作 | 現役狀態 |
+|---|---|
+| `POST /blocks/ingest`（建立） | ✅ 已有 |
+| `GET /blocks/{id}`（讀取單筆） | ✅ 已有 |
+| `GET /blocks/`（列表 / 查詢） | ✅ 已有 |
+| `DELETE /blocks/{id}`（刪除） | ✅ 已有 |
+| **`PATCH /blocks/{id}`（部分更新）** | ❌ **缺** |
+| `POST /triplets/`（建立） | ✅ 已有 |
+| **`PATCH /triplets/{id}` / `DELETE /triplets/{id}`** | ❌ **缺** |
+| `PUT /templates/{name}` | ✅ 已有 |
+| `PATCH /tasks/{id}/status` | ✅ 已有 |
+
+→ 沒有 PATCH/UPDATE block 內容的 API，前端「inline edit 寫回 KBDB」做不了。
+
+> **註**：`src/routes/blocks.ts.bak` 有 PUT /:id 的舊實作可參考，但已被 v3 取代並停用。**不直接複用 .bak 檔案**，按 v3 規範重寫。
+
+---
+
+## 1. 範圍
+
+本 SDD 涵蓋兩件事：
+
+1. **補三組 endpoint**：`PATCH /blocks/{id}`, `PATCH /triplets/{id}`, `DELETE /triplets/{id}`
+2. **建三個 templates**：`data-source-config`, `source-skill`, `wiki-page`（為 mira-app 準備）
+
+**不在範圍內**：
+- 改 schema（v3 鎖定，禁止 ALTER TABLE）
+- 改既有 endpoint 行為（純加新 endpoint）
+- 多用戶權限細分（partner key 已能做 org 隔離，沿用即可）
+- 編輯歷史 / undo（未來 SDD）
+
+---
+
+## 2. PATCH /blocks/{id}
+
+### 2.1 用途
+
+部分更新一個既有 block。前端 inline edit 場景：使用者點 edit icon，改 content / refs / tags，按儲存 → 送 PATCH。
+
+### 2.2 規格
+
+```
+PATCH /blocks/{id}
+Authorization: Bearer <api_key>
+Content-Type: application/json
+
+Body (所有欄位皆 optional，至少要有一個)：
+{
+  "content": "新的內容",
+  "tags": ["tag1", "tag2"],          // 完整覆寫 tags 陣列
+  "refs": ["block-id-1", "block-id-2"], // 完整覆寫 refs 陣列
+  "slots": { "key": "value" },       // 完整覆寫 slots 物件
+  "source": "...",                   // 通常不改，但允許
+  "metadata_json": { ... }           // 完整覆寫
+}
+
+Response 200:
+{
+  "id": "...",
+  "content": "...",
+  "updated_at": "2026-05-06T...",
+  ...完整 block 欄位
+}
+
+Response 400:
+{ "error": "no fields to update" }
+
+Response 403:
+{ "error": "block belongs to different org" }
+
+Response 404:
+{ "error": "block not found" }
+```
+
+### 2.3 行為
+
+- 只更新 body 內提供的欄位
+- 自動更新 `updated_at`
+- 自動重新計算 `content_hash`（如 content 變動）
+- 自動觸發 embedding 重算（如 content 變動，async）
+- **權限**：partner key 只能改自己 org 內的 block（透過 user_id 對應），internal token 可改任何 block
+- **content_hash 衝突**：partner key 不可修改 v3「`source` 為 `system` 的 admin 標記資料」（沿用既有 admin-preservation 規則）
+
+### 2.4 實作位置
+
+- Action: `src/actions/update-block.ts`（< 100 行，按 KBDB CLAUDE.md 樂高法）
+- Route: `src/routes/blocks.ts` 加新 OpenAPI route
+- Test: `tests/blocks-update.test.ts`
+
+---
+
+## 3. Triplet 編輯：使用既有 `PUT /records/:id` + `DELETE /records/:id`
+
+**設計修正（2026-05-06 實作時發現）**：
+
+v3 萬物皆 Block 架構下，triplet 是 `tpl-triplet` template 的 record（用 entry_values 存 subject/predicate/object slots）。**既有 `PUT /records/:id` 跟 `DELETE /records/:id` 已涵蓋編輯/刪除需求**，無需新增 `PATCH /triplets/:id`。
+
+→ 前端編輯異見牆上的 triplet：
+- 編輯：`PUT /records/{triplet_record_id}` body `{ values: { subject, predicate, object } }`
+- 刪除：`DELETE /records/{triplet_record_id}`
+
+→ **本 SDD 不再規劃新 triplet endpoint**。
+
+---
+
+## 5. 三個新 Templates
+
+按 KBDB v3 規範，新資料類型透過 template 定義，**不動 schema**。
+
+### 5.1 template: `data-source-config`
+
+每個資料源實例對應一個此 template 的 block。Mira 的「來源篩選」、cron workflow 的「每天去抓什麼」都讀這個。
+
+```yaml
+template_name: data-source-config
+slots:
+  - name: string             # "電子時報"、"我的 Logseq"
+  - channel: string          # rss / telegram / km-writer / voice-stt / ai-comment / ai-canon
+  - config: object           # channel-specific (e.g., rss: {url, schedule})
+  - skill_id: string?        # 連到 source-skill block 的 id
+  - enabled: bool
+  - ai_comment: bool         # 是否需要 AI 加註解
+  - ai_comment_style: string?  # 提示給 claude_api 的風格
+```
+
+### 5.2 template: `source-skill`
+
+每個 source 累積的「分析配方」（prompt + few-shot）。可在前端編輯、版本化。
+
+```yaml
+template_name: source-skill
+slots:
+  - name: string             # 例 "電子時報科技類分析"
+  - prompt: text             # system_prompt 內容
+  - examples: text?          # few-shot examples（markdown）
+  - version: int
+  - based_on: string?        # 上一版的 block id
+```
+
+### 5.3 template: `wiki-page`
+
+AI 從河道對話合成的定稿。
+
+```yaml
+template_name: wiki-page
+slots:
+  - entity_name: string
+  - summary: text            # markdown
+  - key_blocks: array<string>  # 引用的 source block ids
+  - conflicts: array<string>?  # 標記為矛盾的 block ids
+  - generated_at: timestamp
+  - version: int
+  - based_on: string?
+```
+
+### 5.4 建立方式
+
+不寫 SQL migration（v3 規範禁止）。改用 KBDB 既有的 `POST /templates`：
+
+```bash
+curl -X POST https://kbdb.finally.click/templates \
+  -H "Authorization: Bearer <internal_token>" \
+  -d '{"name": "data-source-config", "slots": [...]}'
+```
+
+→ tasks.md 列為 P0 任務（用 internal token 一次性建好）。
+
+---
+
+## 6. 實作步驟
+
+### Phase 1：補 endpoints
+
+1. 寫 `src/actions/update-block.ts`（純函數，< 100 行，含權限檢查）
+2. 寫 `tests/blocks-update.test.ts`（含 happy path、403、404、no-fields 三案）
+3. 寫 `src/routes/blocks.ts` 的 PATCH route（OpenAPI 定義 + 呼叫 action）
+4. 補 `src/routes/triplets.ts` PATCH（wrapper）+ DELETE（alias）
+5. 部署 + smoke test
+
+### Phase 2：建 templates
+
+6. 用 internal token 呼叫 `POST /templates` 建三個 template
+7. 驗證：用 partner key (mira 用的) 創建一個 `data-source-config` block 看能否寫成功
+
+### Phase 3：補 OpenAPI spec
+
+8. 確認新 routes 自動進 swagger.json（OpenAPIHono 應該自動，需驗證）
+
+---
+
+## 7. 風險
+
+- **embedding 重算成本**：PATCH content 會觸發 vectorize 重算，頻繁 inline edit 可能拖慢。**對策**：embedding 改為 async（行為已是 async，需確認）。
+- **content_hash 計算遺漏**：忘記重算會讓查重失效。**對策**：在 action 內統一處理，不讓 route 層管。
+- **partner key 越權**：必須驗 user_id 對應，不能讓 partner A 改 partner B 的 block。**對策**：write tests 涵蓋此案。
+- **三個 templates 命名衝突**：若 KBDB 已有同名 template 會 fail。**對策**：建立前先 GET /templates/{name} 檢查。
+
+---
+
+## 8. 不在範圍內
+
+- 編輯歷史 / undo / version diff（未來 SDD）
+- Block soft delete（v3 已有 hard delete，softdelete 是 enhancement）
+- Bulk PATCH（一次改多個 block，未來看需求）
+- Field-level permissions（特定欄位只能某些 user 改）
+- WebSocket 通知 block 改了（即時協作）
+
+---
+
+## 9. 變更紀錄
+
+| 版本 | 日期 | 內容 |
+|---|---|---|
+| v0 | 2026-05-06 | 初稿。對應 mira-app 的 inline edit 需求。 |
@@ -0,0 +1,68 @@
+# KBDB Blocks Edit API — Tasks
+
+> 對應 SDD：[design.md](design.md)
+> 上次更新：2026-05-06（Phase 1 + Phase 2 完成）
+
+---
+
+## Phase 1：補 PATCH endpoint ✅ 完成
+
+### 1. PATCH /blocks/{id}
+
+- [x] 1.1 zod schema 直接放在 route 檔（既有 pattern）
+- [x] 1.2 寫 `src/actions/block-update.ts`（96 行，符合樂高法 < 100）
+  - 取既有 block + getBlock fallback（id 或 logseq_uuid）
+  - 權限檢查：partner key 比對 user_id 前綴
+  - 自動重算 content_hash（如 content 變）
+  - 觸發 embedding async 重算（不阻塞 PATCH 回應）
+  - 寫回 D1
+  - 回傳更新後的 block
+- [x] 1.3 寫 `tests/blocks-update.test.ts`（**7 case 全通過**）
+  - happy: content + content_hash 重算
+  - happy: tags + refs 同改
+  - 400: 無欄位
+  - 404: 不存在
+  - 403: partner 越權
+  - 200: partner 改自己 namespace
+  - content_hash 在只改 tags 時不變
+- [x] 1.4 在 `src/routes/blocks.ts` 加 PATCH route（OpenAPI）
+- [x] 1.5 部署到 prod（kbdb.finally.click）+ smoke test 4 case 通過
+
+### 2. Triplet 編輯：使用既有 `PUT/DELETE /records/:id`
+
+- [x] 2.1 設計修正：v3 萬物皆 Block，triplet 是 record，既有 endpoints 已涵蓋。本任務組無需新增 endpoint。
+- [ ] 2.2 在 mira-app 前端「異見牆」實作呼叫 `PUT /records/:id`（待 mira 階段 3）
+
+### 3. OpenAPI spec 同步
+
+- [x] 3.1 OpenAPIHono 自動產 swagger.json（route 用 createRoute 已自動納入）
+- [ ] 3.2 部署後驗證 swagger UI 顯示新 route（待手動驗證）
+
+---
+
+## Phase 2：建三個 templates ✅ 完成
+
+- [x] 4.1 確認 KBDB 內無同名 template（透過 GET /templates 確認）
+- [x] 4.2 用 internal token POST /templates 建 `data-source-config`（id: `tpl-data-source-config`）
+- [x] 4.3 用 internal token POST /templates 建 `source-skill`（id: `tpl-source-skill`）
+- [x] 4.4 用 internal token POST /templates 建 `wiki-page`（id: `tpl-wiki-page`）
+- [x] 4.5 驗證：3/3 templates 在 GET /templates 列表內
+
+---
+
+## 風險追蹤
+
+- ~~風險 1：partner key 跨 org 越權~~ — ✅ unit test 已涵蓋（403 partner 越權）
+- ~~風險 2：embedding 重算造成 D1 寫入 spike~~ — ✅ 改成 fire-and-forget（不 await），不阻塞 PATCH
+- ~~風險 3：content_hash 不一致~~ — ✅ unit test 驗證 hash 重算對應內容
+
+## Known Issues（不在本 SDD 範圍，待另開）
+
+- **`POST /blocks/ingest` 不寫入 `source` 欄位**：input 接受 `source` 參數但僅用於 id slug 生成，未寫進 block 的 source 欄位（block-ingest.ts:84 的 INSERT 缺欄位）。對 mira 影響：所有 source 區分目前無效，需等 KBDB 修復或直接走 `POST /blocks` + slots。建議下一份 KBDB SDD `block-ingest-source-fix` 處理。
+
+---
+
+## 部署紀錄
+
+- 2026-05-06: Worker version `b7df3c38-e138-41fb-a16c-cc9d2dfeebea` 部署上線
+- Smoke test 通過：content 改寫 + hash 重算、tags 改寫、400 空 body、404 不存在