Leo/Arcrun

Files

T

Leo 17a076d35c feat(arcrun): Phase 2 降級假零件成 recipe + credential 鏈路修復

Phase 1（credential 注入鏈路）：
- 修 auth_static_key ENCRYPTION_KEY 漂移根因（見 docs/incidents）
- component-loader: readBodyOnce() 修 "Body has already been used"

Phase 2（降級假零件成 recipe，registry/components 33→22）：
- 引擎: RecipeDefinition 加 auth_service（多 recipe 共用一把 auth）
  auth-dispatcher 先查 recipe.auth_service 再 fallback componentId
- 引擎: auth_static_key inject.path + makeRecipeRunner {{auth.K}}
  （endpoint 可插 secret，解 telegram 類 URL-path token）
- 引擎: makeRecipeRunner auto-body 剔除 _ 前綴內部欄位
- 降級並刪除: kbdb_{get,create_block,patch_block,delete,ingest}
  gmail/telegram/line_notify/google_sheets（改建為 recipe）
- 刪除: ai_transform_{compile,run}（Arcrun 是 AI 呼叫的工具，
  工作流不該內嵌 AI 節點回頭呼叫 AI）
- deferred（源碼暫留）: claude_api/km_writer（交 Mira 收成工作流）、
  kbdb_upsert_block（交 KBDB 出 upsert endpoint）

文件: DECISIONS.md（工作流是 default/建零件人類閘門/AI→工具）、
BACKLOG.md、auth-recipe.md §七、docs/incidents 加密 key 漂移

驗收: KBDB get/create/ingest/delete 2xx；telegram auth 注入綠；
gmail/sheets/line recipe 正確但缺 credential 未驗收；
kbdb patch 403 為 KBDB 端 bug（已交 kbdb/docs）

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-05-29 16:18:18 +08:00

12 KiB

Raw Blame History

Arcrun 待辦（BACKLOG.md）

流動的待辦清單。做完一項就劃掉（[x]）或移到「已完成」。穩定的決策在 DECISIONS.md。

原則：一次只推進一步。不在「整理」的慣性裡順手做下一件事。

最後更新：2026-05

第一期（鎖定範圍，依序做，不跳）

步驟 1 — 清 cypher-executor 的 KBDB 污染

刪除 cypher-executor/src/lib/kbdb-partner.ts
auth.ts 移除 kbdb-partner import 與 3 處呼叫
wrangler.toml 移除 KBDB_BASE_URL 與 KBDB_INTERNAL_TOKEN 註解
component-loader.ts 白名單移除 claude_api + 6 個 kbdb_*
component-loader.ts 修正說謊的 doc comment / 中段註解
graph-executor.ts 註解的 kbdb 範例替換、types.ts 移除 KBDB_BASE_URL 型別
tsc --noEmit 編譯通過
commit 第一步（commit message 寫清楚範圍）

步驟 2 — `acr recipe test`：recipe 形式的 curl

目的很簡單：把一個早就存在的 API endpoint（如 KBDB）變成 Arcrun recipe。流程：看 API 文件 → 申請 API Key → 設進 credential → 寫 recipe → 用 test 打一次。 test 就是「用 recipe 形式 curl 一次」——打通（2xx）就成了。不寫記錄、不是入庫關卡、不防任何東西。防作弊/公共庫那些是第二期。

順序：先 2c（為 KBDB 建 auth recipe，否則 test 打 KBDB 會 401）→ 再 2a。

2c. 為 KBDB 建 auth recipe（static_key） — POST /auth-recipes，建 auth_recipe:kbdb。讓 auth-dispatcher 能把 KBDB API Key 注進 test 的請求。static_key 新路已支援（見 DECISIONS §3b）。
2a. acr recipe test <id> [--input k=v] 指令 — 藄殼：組單節點 ExecutionGraph → 走現有 /execute → 顯示 HTTP status 與回應。就是 recipe 形式的 curl。不碰 cypher-executor、不改 RecipeDefinition 型別、不寫任何記錄。

步驟 3 — 降級假零件成 recipe（2026-05-29 大部分完成）

進度（2026-05-29）：registry/components/ 33 → 22。引擎加了 auth_service（多 recipe 共用 auth）與 inject.path（endpoint 可插 secret，解 telegram URL-path token）。詳見 auth-recipe.md §七 + DECISIONS §1。

KBDB 降級：建 kbdb_get/create_block/patch_block/delete/ingest 5 recipe（共用 auth_service=kbdb），刪 5 零件目錄 - 驗收：get 200 / create 201 / ingest 201 / delete 200 綠；patch 403 = KBDB PATCH org-check bug（已交 kbdb/docs，非 recipe 問題） - kbdb_upsert_block 未降：KBDB 無 upsert endpoint，是 client 拼湊 → 已交 KBDB feature request 出 POST /blocks/upsert，源碼暫留
gmail/telegram/line_notify/google_sheets 降級：建 recipe（gmail_send / telegram_send / line_notify_send / google_sheets_read|append）+ 補 auth_recipe（line_notify / telegram），刪 4 零件目錄 - telegram_send：✅ auth 注入驗收（inject.path，400 chat not found = 過認證） - gmail/sheets/line：⚠️ 未驗收：缺 credential（google SA JSON / line token），recipe + auth 鏈路本身已驗正確
claude_api + km_writer 未降，標 deferred：是 Mira 自用服務的膠水，不該是公共零件/recipe → 交 Mira refactor 文件（收成工作流後刪），源碼暫留
ai_transform_compile + ai_transform_run 刪除：Arcrun 是 AI 呼叫的工具、不該內嵌 AI 節點回頭呼叫 AI（誤搬 n8n 心智模型，見 DECISIONS）
灰色地帶裁決：cron / platform_crypto 留（引擎能力，組工作流必要）
KBDB recipe 採 Supabase 模式：顯示在公共零件庫，要用需申請 API Key（未做，屬服務側/封測後）
「降級」定義：萃取 endpoint/method/auth 寫成 API recipe → 刪零件目錄（已照做）
遺留：orphaned 部署 worker 待 wrangler delete（richblack 手動，rule 05）： arcrun-kbdb-{get,create-block,patch-block,delete,ingest} / arcrun-{gmail,telegram,line-notify,google-sheets} / arcrun-ai-transform-{compile,run}
[~] 降級後 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，但要明確標「未實作」，不可假裝通過

步驟 5 — 建零件的人類閘門 + 白名單 hook（原步驟 4）

強化規格（richblack 2026-05-29 定，原因見下）：建零件不是 AI 能自己決定的事。風險：自用服務（通訊錄/帳本）連驗證都沒設好就變成零件進公共庫 → 全 arcrun 生態都能打 → 機密外洩。這種安全/意圖判斷機器做不了，必須人看。規範會被忘記，hook 不會（DECISIONS §7：把判準寫成機械紅燈）。

把關點 = 「建立零件的 API」本身，不是「寫檔案」。 零件建立有四條入口（CLI acr / MCP / Python lib / JS lib），它們不靠本機寫檔，是呼叫 registry Worker 的「投稿/建立零件」endpoint。所有路都要收斂到這一關。

主閘門：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

配套（讓 AI 不選難路，ABC 三管齊下，與本閘門合為四道）： A 審核當場擋零件（步驟 4 假零件偵測，§7 層二）+ B 工作流範本好寫（步驟 7 acr new，§7 層一）

C mindset 明示「工作流是 default，零件是稀有例外」（步驟 7 mindset Skill，§7 層三）。原理：難路走的當下要痛、易路選的當下要爽、事先有聲音說易路是 default。CC 把自用服務錯做成零件，正因這三者當時全缺。

步驟 6 — 搬家（拆 matrix）（原步驟 5）

先給 kbdb、ghost(identity/personality-system/persona-sdk) 各自 git init + 建 GitHub repo （它們現在沒有自己的 .git，是被 inkstone-matrix 追蹤的子目錄——刪 matrix/.git 前必須先安置）
分揀 matrix 的孤兒檔案（清單見下方附錄）
arcrun / kbdb / ghost 各自 git status 確認乾淨、已 push
GitHub 上 inkstone-matrix 設為 archived（不刪）
本機刪 matrix/.git，matrix 降級成普通資料夾
比對兩份 cypher-executor（matrix 頂層 vs arcrun 底下），釐清死活

步驟 7 — 收尾（原步驟 6）

arcrun-mindset Skill（給 CC 的世界觀，見 DECISIONS §7 層三）
會回嘴的 CLI（acr 偵測走歪 → exit 2 + 指回正路，見 DECISIONS §7 層二）
README 重寫成單一路徑（砍掉「玩法一/二/三」三選一）
acr init --self-hosted：貼 CF token → 自動建 KV、部署 Worker、自動 workers.dev subdomain、寫回 config（用戶自己建 token，CLI 不代管）

第一期之後 / 待決策（不要現在做）

砦 injectCredentials 舊路 + BUILTIN_CREDENTIALS_MAP — credential 系統現為新舊兩路並存，舊路是 TS 裡解密的半成品（註解自認 Phase 1.9 刪）。是獨立清理，不擋降級。見 DECISIONS §3b
決策：開源版 cypher-executor 是否保留「KBDB block 展開」功能 （recipe-expander.ts 仍讀 env.KBDB_BASE_URL、prompt-recipe-schema.ts 的 kbdb_block 型別）按定位應移除（屬 KBDB 訂閱層），但牽涉型別，需單獨想清楚
決策：開源版遙測去 KBDB 化 （telemetry.ts 的 kbdbCreateBlockUrl + fetch 到 arcrun-kbdb-create-block）開源版遙測寫去哪？本地？關掉？寫用戶自己的 ANALYTICS_KV？
新增 kv_store 暫存 primitive：解決「workflow 中途暫存」需求（像 n8n data table）。用 Arcrun 執行環境內建暫存，不依賴外部服務 → 可為 primitive。介面要抽象（CF 上是 KV，wazero 上是本地檔/記憶體），才能三層通用
「專案」概念落地：CLI 的 acr project 指令、專案=引用 workflow 的三元組
公共零件庫 KBDB 語義搜尋：AI 查意圖 → 回傳零件選項；self-hosted 用本地關鍵字比對
事後機制第二層：不變式測試套件（核心原則寫成自動測試，接 CI / pre-commit）
事後機制第一層：執行軌跡完整化（基於現有 executions.ts）
acr project init：把閉環三件（mindset Skill + CLAUDE.md 判準 + exit-2 hook + 不變式測試）一次裝進用戶專案
視覺化 Skill：固定格式的「給人看的圖」（取代 arcrun-gui 拖拉畫布）。目的是「讓人看完放心地說『跑吧』」，是信任產出物不是美術產出物
arcrun-gui 處置：降級為「零件庫 / recipe 貢獻者牆」展示站，掛 arcrun.dev（非工具）
arcrun-mcp 對齊：u6u_* → arcrun 命名、finally.click → arcrun.dev、移除 GUIDE.md 教 api_config 的反模式、確認 MCP 是薄殼
acr update 設計：常態只拉 recipe；動到 primitive 一定要用戶確認，不可默默 deploy
recipe 「貢獻回公眾」的路徑：別人測好的 recipe 怎麼變成所有人能用（飛輪的關鍵）

附錄：matrix 孤兒檔案分揀清單（步驟 5 用）

移進 arcrun：

.agents/specs/arcrun/、.agents/specs/u6u-core-mvp/、.agents/specs/u6u-platform-evolution/
.agents/steerings/（tech.md / coding-rules.md / product.md / structure.md）
docs/user_requirements/arcrun/
cypher-executor/（matrix 頂層那份——先比對死活）

移進 arcrun-gui（若保留）：

.agents/specs/u6u-gui-platform/、.agents/specs/prototype-editor/（先看一眼確認）

移進 ghost / 其他：

ghost.md、identity/、personality-system/、persona-sdk/ → ghost
.agents/specs/matrix-admin-api-fixes/、inkstone-admin/ → inkstone-admin

需判斷（多半過時，留在 archived 的 inkstone-matrix 即可）：

API-CATALOG.md、AVM-PROTOCOL.md、MODULE-CONTRACT.md、頂層 CLAUDE.md / GEMINI.md
docs/user_requirements/rearrange.md / test.md
.claude/ / .github/ / .vscode/ / .wrangler/ / .swarm/ / ruvector.db

12 KiB Raw Blame History Unescape Escape