From 7d8cbe4299ef23a3969fe796d7c0b4655066daf9 Mon Sep 17 00:00:00 2001 From: richblack Date: Sat, 30 May 2026 13:42:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=203=20=E6=94=B6=E5=B0=BE=20?= =?UTF-8?q?=E2=80=94=20=C2=A78=20=E9=87=90=E6=B8=85=E9=9B=B6=E4=BB=B6?= =?UTF-8?q?=E6=8A=95=E7=A8=BF=E8=B5=B0=20PR=E3=80=81BACKLOG=20=E8=A8=98?= =?UTF-8?q?=E6=96=B0=E9=9C=80=E6=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - DECISIONS §8 釐清：執行鏈路(高頻)不依賴 CI；零件投稿(稀有)走 PR/CI 是例外、不違反精神 （CF Workers 不能 runtime 編譯 wasm，CI 是唯一能跑 wasm 又執行者碰不到的 venue） - BACKLOG 步驟 4 收尾（投稿改 PR，標已做/不做/未來搬 CI） - BACKLOG 步驟 5 被 PR 方向取代；新增步驟 5b 資料外流警示（先做，需新 SDD） - BACKLOG 待決策加：用戶 API 保護機制（入站認證，資安優勢）、recipe/part/function 架構釐清 - component-gatekeeping tasks.md 收尾狀態 Co-Authored-By: Claude Opus 4.8 --- .agents/specs/component-gatekeeping/tasks.md | 16 +++++ BACKLOG.md | 69 ++++++++++++-------- DECISIONS.md | 17 +++-- 3 files changed, 69 insertions(+), 33 deletions(-) diff --git a/.agents/specs/component-gatekeeping/tasks.md b/.agents/specs/component-gatekeeping/tasks.md index 51c4d28..49f9b92 100644 --- a/.agents/specs/component-gatekeeping/tasks.md +++ b/.agents/specs/component-gatekeeping/tasks.md @@ -5,6 +5,22 @@ --- +## ⚠️ 收尾狀態（2026-05-30，方向修正後） + +投稿改走 **GitHub PR**（廢 registry self-service，見 design 頂部「方向修正」）。本 SDD 收尾於： +- **已完成且 commit**：G1（detectFakeComponent）、G3（wasmImports）、G5/G6（unimplemented_steps）、 + G0 registry 人類閘門（保留不刪）。測試 15 綠。 +- **改去向**：G4 Gherkin / 覆蓋檢查 → 未來接 CI PR check（CI 能跑 wasm）。G1/G3 邏輯可複用。 +- **不做**：CI PR check（richblack：人工 review 就夠，primitive 極少）、R5 本機 hook + （PR/merge + G1 + 沙箱已防「未經同意變公共零件」，hook 過度工程）、registry self-service、 + acr parts publish 加閘門、平台 sandbox 重跑。 +- **黃金向量**：人工核對（另起 session 從語義寫），不急、不機器自動化。 +- **轉出範圍**：真正的裸奔風險在「資料外流」（recipe/webhook 把資料送出去），不分公私庫 + → 另開新 SDD「資料外流警示」（API 層警示 + AI 動手前 hook）。用戶 API 保護（入站認證） + + recipe/part/function 架構釐清 → 記 BACKLOG 待決策。 + +--- + ## G1 假零件偵測（R2，Q2=兩者硬擋） - [x] 1.1 `registry/src/actions/detectFakeComponent.ts`：(a) 外部 URL/domain 偵測（掃 contract 文字 + wasm binary 文字）硬擋；(b) http_request 子集偵測硬擋 - [x] 1.2 排除 `auth_*` primitive 與 `http_request` 自己 diff --git a/BACKLOG.md b/BACKLOG.md index e51a350..9fcc98e 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -57,40 +57,41 @@ - [~] 降級後 registry/components/ 現 22 個：17 白名單 primitive（流程6+資料7+http_request1+auth3） + cron/platform_crypto（引擎能力）+ claude_api/km_writer/kbdb_upsert_block（deferred） -### 步驟 4 — 補零件庫真把關（原步驟 3，第一期最大工程） -- [ ] `sandboxAcceptance.ts` 的 Gherkin 驗收：目前是 `return null` 空殼，要真實作 -- [ ] 新增「假零件偵測」：primitive 子集偵測 + 寫死 endpoint 偵測 → 自動退稿並告知正路 -- [ ] 把關目標擴充：不只「安全 + Gherkin」，還要「純 WASI preview1、零宿主特定依賴」 - （這是避免「runtime 鎖定債」的唯一時機，見 DECISIONS §4） -- [ ] 冷啟動 / runtime 相容兩步可暫留 mock，但要明確標「未實作」，不可假裝通過 +### 步驟 4 — 補零件庫真把關（2026-05-30 收尾：投稿改走 PR） -### 步驟 5 — 建零件的人類閘門 + 白名單 hook（原步驟 4） +> 方向修正：零件投稿走 **GitHub PR**（人 merge=閘門、CI 跑把關），廢 registry self-service。 +> SDD：`.agents/specs/component-gatekeeping/`（含完整決策過程）。 -> 強化規格（richblack 2026-05-29 定，原因見下）：**建零件不是 AI 能自己決定的事**。 -> 風險：自用服務（通訊錄/帳本）連驗證都沒設好就變成零件進公共庫 → 全 arcrun 生態都能打 → 機密外洩。 -> 這種安全/意圖判斷機器做不了，必須人看。規範會被忘記，hook 不會（DECISIONS §7：把判準寫成機械紅燈）。 +- [x] 假零件偵測（detectFakeComponent.ts）：外部 URL/domain + http_request 子集，硬擋退稿指回 recipe +- [x] 純 WASI 把關（wasmImports.ts）：import module 白名單（只准 wasi_snapshot_preview1 + u6u） +- [x] cold_start / runtime_compat / gherkin 標 unimplemented_steps（不假綠） +- [x] G0 registry 人類閘門（已 commit；投稿改 PR 後非主管道，保留不刪） +- [ ] Gherkin 真跑 + 覆蓋檢查 → 未來接 **CI PR check**（CI 能跑 wasm，繞 CF venue 牆）。 + richblack：人工 review 就夠，primitive 極少 → CI 暫不做，邏輯已寫好隨時能搬。 +- [x] **不做 R5 本機 hook**：PR/merge + 假零件偵測 + 純WASI 沙箱已防「未經同意變公共零件」→ hook 過度工程。 +- [ ] 黃金向量：人工核對（另起 session 從語義寫，不機器自動化）— 不急 -**把關點 = 「建立零件的 API」本身，不是「寫檔案」。** 零件建立有四條入口（CLI `acr` / MCP / Python lib / JS lib）， -它們不靠本機寫檔，是呼叫 registry Worker 的「投稿/建立零件」endpoint。所有路都要收斂到這一關。 +### 步驟 5 — ~~建零件的人類閘門 + 白名單 hook~~（2026-05-30 被 PR 方向取代） -- [ ] **主閘門：registry Worker「建立零件」API** —— 預設**拒絕**，除非請求帶： - (a) 人類已確認的明示憑證（CLI `acr component create` 強制互動式問人類，AI 在非互動環境生不出）； - (b) 舉證欄位 `reason_why_not_workflow`（AI 必須說明「為何這件事無法用工作流達成」，舉證責任在 AI， - 預設假設工作流能做）。沒帶 → 403 + 指回正路（先試工作流）。 -- [ ] **四路 client 配合**：CLI / MCP / Python lib / JS lib 的「建零件」都改成必經主閘門（帶人類確認 + 舉證） -- [ ] **本機 hook 兜底**：pre-write / pre-bash hook 偵測「CC 直接在 `registry/components/{白名單外新名}/` 造目錄 - 或 mkdir」→ exit 2（擋繞過 API、直接改 repo 造零件等 CI 部署這條旁門） -- [ ] **誠實限制（要寫進 mindset）**：沒有技術能 100% 防 AI 假冒人類確認（它能塞任何 flag）。 - 靠「閘門 + 舉證留記錄 + mindset 明示『絕不可代替人類確認建零件』+ 軌跡可審計」讓假冒成為明確越界， - 不是聲稱「不可能繞過」。 -- [ ] `MVP_COMPONENTS.txt` 白名單檔 -- [ ] pre-write hook：`registry/components/` 目錄清單 ≠ 白名單 → exit 2 -- [ ] pre-write hook：`registry/components/` 底下出現 `.ts` → exit 2 +> **取代說明**：原規劃「registry submit API 人類閘門 + 四路 client + 本機 hook」。 +> 2026-05-30 改：**零件投稿走 GitHub PR**（人 merge = 天然人類閘門，AI 偽造不了 GitHub approve）。 +> → registry self-service 主閘門、四路 client、本機 hook **都不做**（PR/merge + 假零件偵測 + +> 純WASI 沙箱已防「未經同意變公共零件」，hook 過度工程）。並進步驟 4。 +> +> **真正的裸奔風險不在零件，在「資料外流」**（recipe/webhook 把資料送出去，不分公私庫）。 +> → 另開新 SDD「資料外流警示」（見下方第一期新增項）。 -> **配套（讓 AI 不選難路，ABC 三管齊下，與本閘門合為四道）**： -> A 審核當場擋零件（步驟 4 假零件偵測，§7 層二）+ B 工作流範本好寫（步驟 7 acr new，§7 層一） -> + C mindset 明示「工作流是 default，零件是稀有例外」（步驟 7 mindset Skill，§7 層三）。 -> 原理：難路走的當下要痛、易路選的當下要爽、事先有聲音說易路是 default。CC 把自用服務錯做成零件，正因這三者當時全缺。 +**ABC 配套仍有效**（讓 AI 不選難路）：A 假零件偵測（步驟 4）+ B 工作流範本（步驟 7 acr new） ++ C mindset「工作流是 default、零件稀有例外」（步驟 7 mindset Skill）。 + +### 步驟 5b — 資料外流警示（2026-05-30 新增，richblack：先做） + +> 風險根源：arcrun 讓「產生 API」變很簡單（資料+webhook trigger=API）→ AI 可能不知不覺把含個資 +> 的東西變成可被呼叫的 endpoint。不分公私庫（私人=公司用也會把個資 POST 到公司群）。 + +- [ ] 新建 SDD（requirements/design 交 richblack review 才動 code） +- [ ] **API 層警示**：任何「把資料送出去」的動作（recipe push / webhook 等）不論哪條路都警示/需人類同意 +- [ ] **hook**：AI 動手做這類動作前先警告（防在前；API 層防在送出前，兩道互補） ### 步驟 6 — 搬家（拆 matrix）（原步驟 5） - [ ] 先給 kbdb、ghost(identity/personality-system/persona-sdk) 各自 `git init` + 建 GitHub repo @@ -112,6 +113,16 @@ ## 第一期之後 / 待決策（不要現在做） +- [ ] **用戶自己的 API 保護機制（入站認證）**（richblack 2026-05-30）— 做成零件或功能： + (1) 用戶可發 API Key 給別人；(2) 不同權限設定。現況缺口：webhook 只有 X-Arcrun-API-Key + （誰有我的 key 誰能打），沒有「發受限 key 給別人 / per-caller 認證 / rate limit」。 + **這是 arcrun 資安優勢**：n8n 用簡單 USN/PWD 做不好，AI coding 又怕資安沒做好，我們系統幫搞定、 + 一個動作能用。注意區分：credential/auth recipe 是出站（呼叫別人 API 帶我的 token），這是入站（保護我的 API）。 +- [ ] **架構詞彙釐清（recipe / part / function / 工作流組合）**（richblack 2026-05-30，要思考一下）： + - recipe：用零件去打的設置文件（endpoint+設定） + - part（零件）：需 PR + update/upgrade + - function：把一批功能做好可用 cypher 拉進來（例：API 認證，我做好幾個讓用戶拉）。是 part+recipe？ + - **多零件/工作流組合成新工作流**（第一個走完連第二個）—「好像還沒有」，要思考 - [ ] **砦 `injectCredentials` 舊路 + `BUILTIN_CREDENTIALS_MAP`** — credential 系統現為新舊兩路並存， 舊路是 TS 裡解密的半成品（註解自認 Phase 1.9 刪）。是獨立清理，**不擋降級**。見 DECISIONS §3b - [ ] **決策：開源版 cypher-executor 是否保留「KBDB block 展開」功能** diff --git a/DECISIONS.md b/DECISIONS.md index ccf6f0b..e9833e2 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -313,11 +313,20 @@ arcrun-gui 拖拉畫布、arcrun-mcp 命名大改、新 primitive、Gemini/Codex --- -## 8. 不依賴 GitHub Actions +## 8. 執行鏈路不依賴 GitHub Actions（零件投稿例外，2026-05-30 釐清） -Arcrun 第一期的執行鏈路（init / push / run / 零件投稿）全在「用戶機器 + Cloudflare」之間， -不經過 GitHub Actions。零件編譯 / 測試本地跑即可（TinyGo 編譯、Gherkin 測試都是本地一行指令）。 -理由見 §0 第一條。 +Arcrun 第一期的**執行鏈路**（init / push / run / recipe）全在「用戶機器 + Cloudflare」之間， +不經過 GitHub Actions。這是常態高頻動作，用戶不該被 CI 卡住。理由見 §0 第一條。 + +**零件投稿是例外，走 GitHub PR + CI（2026-05-30）：** +- 零件投稿是**稀有低頻**事件（primitive 極少、未來絕大部分是 recipe；建零件要過人類閘門）。 +- 稀有事件用 PR 治理最自然：**PR 必須有人 merge = 人類閘門**（AI 偽造不了 GitHub approve）； + 把關（假零件偵測 / 純WASI / Gherkin / 覆蓋檢查）由 **CI（PR check）跑**。 +- 為何非 CI 不可：**CF Workers 禁止 request-time 編譯 WASM** → registry Worker 跑不了 Gherkin / 向量； + CI 有 tinygo + 能 runtime 跑 wasm，是唯一既能跑 wasm 又「執行者碰不到」的 venue。 +- **這不違反 §8 精神**：§8 防的是「高頻執行鏈路被 CI 卡住」；零件投稿稀有、且該由 PR 把關， + 用 PR/CI 反而更對。兩者是不同性質的事。 +- 詳見 `.agents/specs/component-gatekeeping/`。 ---