uncle6me-web
922a57fe34
Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。 此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在 richblack/arcrun 與本地 backup 分支）。含： - acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe） - recipe push 把關（資料外流提醒 + 打通檢查） - 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1） - CLI / cypher-executor / registry / 完整 SDD Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
106 lines
6.3 KiB
Markdown
106 lines
6.3 KiB
Markdown
# Design 補充：recipe 入庫把關（push 那一刻）
|
||
|
||
> 2026-06-01。本檔是 `component-gatekeeping/design.md` 的單檔補充（規則 02 §4.3 允許）。
|
||
> **狀態：待 richblack review 才動 code（這是 change）。**
|
||
> 背景：richblack 2026-06-01 方向修正（見下「方向定調」）+ docs/HANDOFF-self-host-harness.md。
|
||
|
||
---
|
||
|
||
## 0. 方向定調（richblack 2026-06-01）
|
||
|
||
把關的對象與位置整個移位了，先講清楚才不會做歪：
|
||
|
||
### 0.1 零件這條路 = 封鎖，且「不再有假零件這件事」
|
||
- 零件由維護者（richblack）管理，**CC 不能自製/修改零件**。
|
||
- 封鎖機制 = **零件投稿走 GitHub PR + 人 merge**（DECISIONS §8 / design 頂部方向修正）。
|
||
AI 偽造不了 GitHub approve，這是天然人類閘門。CC 在本機產不出能進庫的零件。
|
||
- → 因此「擋假零件」（原 W1）這件事**不存在了**：CC 根本造不出零件，workflow 引用 recipe
|
||
（如 `component: kbdb_get`）是**合法且未來唯一的擴充方式**，不該被當假零件擋。
|
||
|
||
### 0.2 零件 PR 把關 = 人工，不自動化（除非未來爆量）
|
||
- richblack 2026-06-01 澄清 BACKLOG 步驟5「不做 hook/自動化」的真意：
|
||
**零件真實數量很少、絕大多數是 recipe** → 原本想做的「驗證零件 PR 的自動化機制」
|
||
（CI 跑 Gherkin/沙箱/向量）**不需要**，量少 → **有 PR 進來就人工檢查**。
|
||
**只有零件開發量變很大時**才回頭想自動化。
|
||
- → component-gatekeeping 的 G4/覆蓋檢查/黃金向量自動化 = **不做**（人工取代），與既有 tasks 收尾一致。
|
||
|
||
### 0.3 真正的 harness 把關 = recipe 入庫（push）那一刻
|
||
CC 唯一能擴充的是 recipe。recipe 一律用「**推（push）**」，**自有庫與公共庫同一套指令**。
|
||
把關依庫別分強度：
|
||
|
||
| 庫別 | 能做到的把關 | 機制 |
|
||
|---|---|---|
|
||
| **自有庫（self-hosted）** | 只能**提醒**（無法在別人機器強制） | (1) 資料外流提醒 (2) 打通檢查 |
|
||
| **公共庫** | 維護者機制**檢核實際打通、真收到成功回傳** | PR/CI relay（DECISIONS §3c，第一期後）|
|
||
|
||
---
|
||
|
||
## 1. 自有庫 push 把關（self-hosted，第一期做）
|
||
|
||
`acr recipe push` 的兩個提醒。**提醒級 = 告知 + 需人類明示同意，不硬擋**（self-hosted 是用戶自己的庫，
|
||
他同意後就是他的責任 — mindset §6 / data-exfil-warning 既有原則）。
|
||
|
||
### 1.1 資料外流提醒（W2.2）
|
||
- **觸發**：push 的 recipe / 或部署的 workflow 會讓「資料對外可見」——主要是產生**對外可被呼叫的 webhook**
|
||
（`POST /webhooks/named/...` 對外 trigger URL），或 recipe 把本地資料 POST 到外部服務。
|
||
- **行為**：CLI 印明確警示「這個動作會讓 X 對外界可見/可呼叫，確認要繼續嗎？」→ 需人類明示同意（y/N）。
|
||
非 TTY（AI 直跑）→ 拒絕，提示「需人類確認」（mindset §7：絕不代替人類做暴露確認）。
|
||
- **與既有 data-exfil-warning 的關係**：已有 API 層 + pre-bash hook（commit 51d40ee 等）。
|
||
本項確認**涵蓋 recipe push 這條路徑**；若已涵蓋則只補文件，若沒涵蓋則補上 push 路徑的提醒。
|
||
- **誠實限制**：AI 技術上能偽造 exposure_consent。價值是法律歸責 + 軌跡可審，不聲稱不可繞過（mindset §7）。
|
||
|
||
### 1.2 打通檢查（W2.3）
|
||
- **目的**：recipe 是「指向外部 API 的指針」，正確性一半在「打不打得通」（DECISIONS §1 recipe 驗收標準 = 2xx）。
|
||
- **行為**：push 時（或 push 後）對 recipe 的 endpoint **實打一次**，回報 HTTP status。
|
||
- 2xx → 「✓ recipe 打通（HTTP 200）」
|
||
- 4xx/5xx → 「⚠️ recipe 未打通（HTTP 401/404/...）」+ 誠實標原因（如「缺 credential → 先 acr creds push」）
|
||
- 連不上 → 「⚠️ 無法連線」
|
||
- **self-hosted 是提醒級**：打不通**不硬擋 push**（用戶可能就是要先 push 再設 credential），只如實回報。
|
||
- **誠實**（mindset §7）：缺 credential 打不到 2xx 就誠實標「未驗收：缺 X」，不 mock 充綠燈。
|
||
|
||
### 1.3 動到的檔案（待 review 後）
|
||
| 檔案 | 動作 |
|
||
|---|---|
|
||
| `cli/src/commands/recipe.ts` | push 流程加 (1) 資料外流提醒 prompt (2) 打通檢查（實打 endpoint 回報 status） |
|
||
| `.claude/hooks/*`（如需）| 確認 data-exfil pre-bash hook 涵蓋 recipe push；缺則補 |
|
||
|
||
**不動**：cypher-executor 執行路徑、零件、credential 解密邏輯。
|
||
|
||
---
|
||
|
||
## 2. 公共庫 push 把關（第一期後）
|
||
|
||
- recipe 進公共庫 = 別人會用 → 需維護者機制檢核「**實際打通、真收到成功回傳**」（不是投稿者自報）。
|
||
- 機制：DECISIONS §3c 的 **test/relay**——push 公共庫走 relay，維護者當下親見真實打通記錄
|
||
（執行者不能驗證自己，§7 閉環）。
|
||
- **範圍**：依賴公共庫 + relay 基建，**第一期不做**（第一期是 self-hosted + 提醒級）。
|
||
- 本檔只記框架，第一期不實作。
|
||
|
||
---
|
||
|
||
## 3. 同一套指令、不同把關強度的切分（W2.4）
|
||
|
||
- `acr recipe push`（自有庫，預設）→ §1 提醒級。
|
||
- `acr recipe push --public`（公共庫，未來）→ §2 relay 檢核級。
|
||
- 同一指令、旗標分流（呼應 design §4.3 公私庫分流：`-p`/`--public`）。
|
||
- 第一期只實作預設（自有庫）路徑。
|
||
|
||
---
|
||
|
||
## 4. 驗收標準（客觀證據，mindset §7）
|
||
|
||
第一期（自有庫提醒級）：
|
||
1. `acr recipe push` 一個會產對外 webhook 的東西 → CLI 印資料外流警示 + 要人類同意；非 TTY → 拒絕。
|
||
2. `acr recipe push` 一個 endpoint 可達的 recipe → 打通檢查回報「✓ HTTP 2xx」。
|
||
3. `acr recipe push` 一個缺 credential 的 recipe → 回報「⚠️ 未打通：缺 credential」（誠實，不假綠），但仍允許 push。
|
||
4. 確認 workflow 引用 recipe（`component: kbdb_get`）**不再被任何 validate 步驟當假零件擋**（W1 已作廢）。
|
||
|
||
---
|
||
|
||
## 5. 與既有 SDD 的一致性確認（無新矛盾）
|
||
|
||
- 不動「零件投稿走 PR + 人工檢查」（§0.1/0.2，與 design 頂部方向修正、DECISIONS §8 一致）。
|
||
- 不重啟「零件 PR 自動化把關」（§0.2，與 BACKLOG 步驟5 真意一致）。
|
||
- 資料外流提醒延續既有 data-exfil-warning 原則（mindset §6），只確認涵蓋 recipe push 路徑。
|
||
- 打通檢查 = recipe 驗收標準 2xx 的落地（DECISIONS §1）。
|