# Arcrun 待辦（BACKLOG.md）

> 流動的待辦清單。做完一項就劃掉（`[x]`）或移到「已完成」。
> 穩定的決策在 `DECISIONS.md`。
>
> 原則：一次只推進一步。不在「整理」的慣性裡順手做下一件事。
>
> 最後更新：2026-05

---

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

### 步驟 1 — 清 cypher-executor 的 KBDB 污染
- [x] 刪除 `cypher-executor/src/lib/kbdb-partner.ts`
- [x] `auth.ts` 移除 kbdb-partner import 與 3 處呼叫
- [x] `wrangler.toml` 移除 `KBDB_BASE_URL` 與 `KBDB_INTERNAL_TOKEN` 註解
- [x] `component-loader.ts` 白名單移除 `claude_api` + 6 個 `kbdb_*`
- [x] `component-loader.ts` 修正說謊的 doc comment / 中段註解
- [x] `graph-executor.ts` 註解的 kbdb 範例替換、`types.ts` 移除 `KBDB_BASE_URL` 型別
- [x] `tsc --noEmit` 編譯通過
- [x] **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。

- [x] 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`，源碼暫留
- [x] `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 鏈路本身已驗正確
- [x] `claude_api` + `km_writer` **未降，標 deferred**：是 Mira 自用服務的膠水，不該是公共零件/recipe → 交 Mira refactor 文件（收成工作流後刪），源碼暫留
- [x] `ai_transform_compile` + `ai_transform_run` **刪除**：Arcrun 是 AI 呼叫的工具、不該內嵌 AI 節點回頭呼叫 AI（誤搬 n8n 心智模型，見 DECISIONS）
- [x] 灰色地帶裁決：`cron` / `platform_crypto` 留（引擎能力，組工作流必要）
- [ ] KBDB recipe 採 Supabase 模式：顯示在公共零件庫，要用需申請 API Key（**未做**，屬服務側/封測後）
- [x] 「降級」定義：萃取 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`