Files
Arcrun/BACKLOG.md
T
Leo 20c7610371 refactor: 移除已廢棄的自管加密金鑰機制(credential 全面託管 CF Workers Secrets)
leo 2026-07-20 明令:「已經改用 cf 自己的 secrets,不要再說它了」
「我希望以後再也看不到這個詞再出現」

背景:credential 早已遷移至 CF Workers per-script Secrets + D1 目錄,
舊的自管金鑰(client 端 AES-GCM + KV 密文 + crypto_decrypt)是遷移期遺留。
本次連根移除,含一併作廢的死 SaaS 碼。

移除:
- 舊 KV 密文解密路徑(credential-injector.ts 整檔、dual-read fallback)
  前置驗證:leo21c / youlin 兩帳號 CREDENTIALS_KV 實測 *:cred:* 皆 0 筆
- migrate-to-workers-secrets 搬家端點(回填已完成,無可回填)
- /register 路由與 generateApiKey(HMAC 產 ak_ key 是 SaaS 遺物;
  self-hosted 走 namespace 明碼 D21,已無人使用)
- platform_crypto component(三帳號實測 404 已退役,無 workflow 引用)

保留(附理由):
- crypto_decrypt 保留為永遠回失敗的 stub——現役三個 auth .wasm 仍宣告該
  import,缺項會讓 WASM instantiate 直接失敗。待零件重編後可真正刪除。

順帶修復(原不在範圍,但會實際壞事):
- /auth/callback 有 `if (!key) redirect(server_error)` 閘,未設該 secret 的
  實例會登入直接失敗 → 已移除
- OAuth 兩處把 provider token 寫進舊加密 KV(租戶鍵與實際 api_key 在 rotate
  後必然分歧,已失效)→ 改導向 Workers Secrets,包 try/catch 不影響登入
- acr init Standard 模式呼叫已刪除的 /register → 改引導 OAuth 取 key
- .claude/rules 與 system-dev/docs 是同一規範的兩份鏡像,先前只改 rules
  導致鏡像仍在教舊做法 → 已同步(此類雙檔同步應納入檢查)

新用戶安裝從此零 secret 前置。
測試 187/188(唯一 fail 為 pre-existing,stash 驗證與本次無關);
cypher-executor 與 cli typecheck 全綠。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-21 01:32:48 +08:00

239 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Arcrun 待辦(BACKLOG.md
> 流動的待辦清單。做完一項就劃掉(`[x]`)或移到「已完成」。
> 穩定的決策在 `DECISIONS.md`。
>
> 原則:一次只推進一步。不在「整理」的慣性裡順手做下一件事。
>
> 最後更新:2026-06-10(與 `.claude/wiki/status.md` 對齊)
---
## 🔥 當前優先序(權威來源:`.claude/wiki/status.md` 2026-06-09
> 此區是「現在該做什麼」的頂層視圖。下方「第一期步驟」多已完成(見各步驟 `[x]`),
> 真正待推進的兩個 P0 在 2026-05 版 BACKLOG 完全沒記,補在這裡。
### 🔴 P0(用戶一用就撞 / 威脅核心承諾)
- [~] **credential 注入 401 修復**`{{credential.X}}` 注入失敗,用戶被迫把 token 明文寫進 workflow。
**根因**:此語法系統沒實裝(三條 template 路徑都不認 `credential.` namespace)。
**修法**design §8richblack 2026-06-10 確認):auth_static_key 加 `resolve_credentials` actionWASM 解密)
+ graph-executor `resolveCredentialRefs` 偵測回填(不碰金鑰,rule 02 §2.2)。
**8.1-8.4 done**tinygo build OK + tsc 0 + §2.2 自檢綠)。**待 8.5 端對端驗收**(部署 + 真 OpenAI key + 全新帳號打 2xx)。
- [ ] **§8 P1/P2 recipe/workflow list 遷 D1** — CF KV list 免費僅 1000/日,不修=用戶用一用就 429,
免費承諾破功。D1 現已可建(依賴解除),架構拍板走 kbdb `/entries` HTTP 雙寫不加 binding。
**大、易出錯 → 另開乾淨 session + 壓測**,不要在雜事 session 順手做。
### 🟡 P1(封測門檻 / 技術債)
- [ ] credential-primitives-wasm **Phase 0.7**component-loader WASM runner)→ **Phase 1-2**auth_static_key / auth_service_account WASM 零件)。0.6 已完成。
- [ ] **Phase 3** 清除違規 TScredential-injector.ts / jwt-signer.ts / BUILTIN_*)—— 須先有 Phase 1-2 WASM 頂上。
- [ ] 4 份 inline http_request host fn 抽共用 helperdedup;假綠修是逐份改的)。
### ⚪ P2(不擋封測)
- [ ] `arcrun.dev/llms.txt` servelanding/public 補檔)
- [ ] MCP account-source、recipe submit uuid 回傳
- [ ] 文件遷移階段二/三 + wiki modules/
- [ ] 下方第一期殘項:步驟 2(acr recipe test)、步驟 5b(資料外流警示 SDD)、步驟 6(搬家拆 matrix
---
## 第一期(鎖定範圍,依序做,不跳)
### 步驟 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 recipestatic_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 — 降級假零件成 recipe2026-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` 降級:建 recipegmail_send / telegram_send / line_notify_send / google_sheets_read|append+ 補 auth_recipeline_notify / telegram),刪 4 零件目錄
- telegram_send:✅ auth 注入驗收(inject.path400 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_blockdeferred
### 步驟 4 — 補零件庫真把關(2026-05-30 收尾:投稿改走 PR
> 方向修正:零件投稿走 **GitHub PR**(人 merge=閘門、CI 跑把關),廢 registry self-service。
> SDD`.agents/specs/component-gatekeeping/`(含完整決策過程)。
- [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 從語義寫,不機器自動化)— 不急
### 步驟 5 — ~~建零件的人類閘門 + 白名單 hook~~2026-05-30 被 PR 方向取代)
> **取代說明**:原規劃「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「資料外流警示」(見下方第一期新增項)。
**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 到公司群)。
- [ ] 新建 SDDrequirements/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
(它們現在沒有自己的 .git,是被 inkstone-matrix 追蹤的子目錄——刪 matrix/.git 前必須先安置)
- [ ] 分揀 matrix 的孤兒檔案(清單見下方附錄)
- [ ] arcrun / kbdb / ghost 各自 `git status` 確認乾淨、已 push
- [ ] GitHub 上 `inkstone-matrix` 設為 archived(不刪)
- [ ] 本機刪 `matrix/.git`matrix 降級成普通資料夾
- [ ] 比對兩份 cypher-executormatrix 頂層 vs arcrun 底下),釐清死活
### 步驟 7 — 收尾(原步驟 6)
- [x] `arcrun-mindset` Skill(給 AI 操盤手的世界觀,見 DECISIONS §7 層三)
`skills/arcrun-mindset/SKILL.md`(2026-05-30)。涵蓋:工作流是default/零件稀有、
AI→工具、arcrun不做授權、暴露需人類同意、誠實(不假綠/不假防偽/不代替人類確認/完成=客觀證據)。
同步 `.claude/rules/06-mindset.md`arcrun repo 內 CC 開發時讀)。
- [ ] 會回嘴的 CLIacr 偵測走歪 → exit 2 + 指回正路,見 DECISIONS §7 層二)
→ 部分已做:pre-bash hook 擋假零件/暴露動作 + 指回正路;CLI 本身的 exit-2 回嘴待補
- [ ] README 重寫成單一路徑(砍掉「玩法一/二/三」三選一)
- [ ] `acr init --self-hosted`:貼 CF token → 自動建 KV、部署 Worker、自動 workers.dev
subdomain、寫回 config(用戶自己建 tokenCLI 不代管)
---
## 第一期之後 / 待決策(不要現在做)
- [ ] **用戶自己的 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 展開」功能**
`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`
## 未來方向:本機零帳戶試玩(local playground)— leo 2026-06-15 提,記錄不插隊
**洞察**self-hosted 最低門檻入口=裝 wrangler → 本機 miniflare 跑 arcrun → **連 CF 帳戶都不用**先玩玩看。
**現有障礙**(為何現在不開箱即用):
- `acr init --self-hosted` 第一步強制貼 CF Account ID + API Tokenself-hosted-init.md),無「無帳戶本機模式」入口。
- `wasmWorkerUrl()`component-loader.ts:59)寫死組 `https://arcrun-{x}.{subdomain}.workers.dev`,假設零件部署在 workers.dev,非 localhost。
- 多 workercypher/kbdb/registry + 零件)串接 + service binding 要本機編排。
**要做**(未來,非現在):
- `acr init --local`:跳過 CF tokensubdomain/URL 走 localhost。
- `wasmWorkerUrl()` local 模式組 `http://localhost:port`
- 多 worker 用 wrangler 本機多服務模式編排(D1/KV miniflare 模擬,已支援)。
**現況可行的最小片**:單 workerkbdb`wrangler dev` + D1 模擬本機跑得起來(=KBDB 插件整合測試路徑)。全系統一鍵本機跑才是新功能。
**優先級**:未來方向,不插現在隊列(mira 解耦 + KBDB 缺口優先)。
## 未來方向:SaaS ⇄ self-hosted 雙向遷移(一等公民)— issue #3 待辦 2 / wishlist C72026-06-24
**緣由**14-Eleo 把 KBDB 資料從官方 SaaS 搬回 leo21c self-hosted458,357 筆 gap=0 完成)暴露框架級缺口。
過程因 `KBDB_BASE_URL` fallback bug(已修,issue #2 commit 9c4333d+ **沒有遷移工具**,資料默默寫錯庫
~11 萬筆 `owner_id=leo` 誤寫進官方 prod kbdb,清理 SOP 見 `docs/5-records/2026-06-24-official-kbdb-cleanup-leo-misdelete.md`)。
今天是 leo dogfood 踩了能修;**若是未來真實用戶 = 數據災難 + 信任崩塌**。
**缺口本質**arcrun 沒有「SaaS ⇄ self-hosted 雙向遷移」的框架級一等公民支持。
leo 今天靠 dump + 手寫翻譯腳本 + 階梯式踩雷(`d1 import` 被 wrangler 4 移除 / statement 切斷 /
SQLite 深度上限 / SQLITE_TOOBIG / 超大 content)硬趟過去。
**要做**backlog,不急):
- `acr migrate` 一等公民路徑:schema 翻譯 + 資料層整包灌 + 驗數 + **隔離保證(絕不寫錯庫)**
- 遷移前**庫歸屬驗證**(probe:寫一筆確認落在預期庫)→ 把今天的 fallback 災難從源頭擋掉。
- **雙向**self-hosted → SaaS(上雲)和 SaaS → self-hosted(下雲)都要順。
**牽動**arcrun-cli + cypher-executor + kbdb。**優先級**:未來方向,不插現在隊列。
**頂層願景源**`docs/1-vision/product-wishlist.md` C7。