arcrun — AI workflow execution engine (clean history)

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>

.agents/specs/llm-interface/tasks.md

@@ -0,0 +1,272 @@
+# Tasks: LI (LLM Interface) for arcrun
+
+> SDD: design.md + requirements.md（同目錄）
+> 進度標記：`[ ]` pending / `[🔄]` doing / `[x]` done / `[⏸]` blocked
+
+## 進度速覽（2026-05-16）
+
+- **M1 完成**：AGENTS.md / telemetry helper / report_feedback tool 全部 deploy + e2e 驗證 ✅
+- **M2.1 完成**：3 個 introspection endpoints + index 強 consistent 修補 ✅
+- **M2.2 部分**：4 個 introspection + 5 個 CRUD = 9/13 tools，剩下 preview/diff/auth-recipes
+- **M3.1/M3.3 完成**：5 個 skill blocks + 10 個 example workflows ✅
+- **M3.4 完成**：sync-registry-to-kbdb.py 跑通，15 blocks 進 KBDB ✅
+- **M4 完成**：weekly_review workflow 跑通，產出第一份 arcrun-roadmap block ✅
+- **M5 大 rename**：repo / dir / SDD 已 rename，Worker name 待後段 DNS 遷移
+
+阻擋項：GH Actions 用戶層被 disable（leo 申訴中）→ 改用本機 wrangler deploy + scripts/local-deploy.sh fallback。
+
+---
+
+## Milestone 1：可量測（先收 data）✅
+
+### M1.1 AGENTS.md v1
+- [x] 寫 `arcrun/AGENTS.md`（5697355 + 3892dc3，263 行）
+- [ ] CI hook：repo `AGENTS.md` 變動 → 自動同步 KBDB block
+- [ ] `arcrun_get_onboarding` MCP tool（讀 KBDB block）
+
+### M1.2 Implicit telemetry 收集 ✅
+- [x] 建 KBDB block type=`agent-telemetry`（slots 直接 metadata_json 不走 template）
+- [x] `webhook-handlers.executeWebhookGraph` 末尾加 telemetry（成功 / 失敗 / paused 都記）
+- [x] `routes/webhooks-named.ts` push deploy 事件（deploy_success）
+- [x] `routes/validate.ts` validation 失敗事件（schema_failed / edge_node_missing）
+- [x] `hashApiKey` SHA-256 截 16 字元 helper
+- [x] 隱私：只記 workflow name 不記 content
+- [x] 實測：KBDB block `68635dcb-62e5-49ca-9c67-33f4ca82b7a0` event=run_success, paused_awaiting_resume
+
+### M1.3 Explicit feedback tool ✅
+- [x] KBDB block type=`agent-feedback`
+- [x] arcrun-mcp tool `arcrun_report_feedback` (commit e637c3e)
+- [x] Zod enum 鎖死 issue_type
+- [x] user_id 從 partnerAuth 取
+- [x] tags_json auto: ['agent-feedback', 'issue:{type}', 'blocked'?, 'wf:{name}'?]
+- [x] schema 實測：KBDB block `80f1d2d1-c95a-4dfe-a889-d23b2e9b247d`
+
+### M1.4 驗收 ✅
+- [x] 觸發 mira watcher → KBDB agent-telemetry 即時出現
+- [x] curl + python verify 8 個 telemetry blocks（event=run_success, workflow_name 對, duration_ms 對）
+- [x] feedback block 寫入測 schema 通
+
+---
+
+## Milestone 2：gap-fill（補 MCP 工具）
+
+目標：人類 GUI 能做的，AI 透過 MCP 都能做。
+
+### M2.1 新增 cypher-executor 路由 ✅
+
+- [x] `GET /executions/:task_id` — 回結構化 paused state (989fbeb)
+- [x] `GET /workflows/:name/executions?limit=10` — 走 ANALYTICS_KV stats:* prefix (989fbeb)
+- [x] `GET /executions/paused` — 改 per-user index 強 consistent (4e7880c)
+- [ ] `POST /preview` — dry-run，不寫 KV（暫緩）
+- [ ] `POST /webhooks/named/:name/diff` — 新舊 YAML diff（暫緩）
+- [ ] `GET /my-telemetry?limit=N` — 用戶自己看 telemetry（暫緩）
+
+### M2.2 MCP tools ✅ (9/13)
+
+完成（commit faf75cd + f91b1fd）：
+- [x] `arcrun_validate_yaml` — wrap /validate
+- [x] `arcrun_get_execution_trace`
+- [x] `arcrun_list_recent_executions`
+- [x] `arcrun_list_paused_executions`
+- [x] `arcrun_push_workflow` — wrap /webhooks/named POST（取代壞掉的 u6u_deploy_workflow）
+- [x] `arcrun_list_workflows`
+- [x] `arcrun_get_workflow`
+- [x] `arcrun_delete_workflow` (require confirm:true literal)
+- [x] `arcrun_run_workflow` (paused 視為 success)
+
+暫緩（等 endpoint 完成）：
+- [ ] `arcrun_resume_execution` — 包既有 /workflows/resume
+- [ ] `arcrun_preview_workflow` — 待 M2.1 /preview
+- [ ] `arcrun_diff_workflow` — 待 M2.1 diff
+- [ ] `arcrun_list_recipes` / `create_recipe`
+- [ ] `arcrun_list_auth_recipes` / `create_auth_recipe`
+- [ ] `arcrun_my_telemetry`
+
+### M2.3 Error contract 統一 ✅
+
+- [x] `error_code` enum v1 定義在 design.md §1.4 + cypher-executor /executions/* 路由都用
+- [x] arcrun-mcp `lib/cypher-client.ts` errorResponse() / successResponse() 統一 helper
+- [x] 所有新 MCP tool（10 個）都用統一 contract（ok, data?, error_code?, human_message?, next_actions?, hints?）
+- [ ] cypher-executor 既有 route（非 /executions/*）改成統一格式（暫緩）
+- [ ] 每個 error_code 對應 unit test（暫緩）
+
+### M2.4 驗收（部分）
+
+- [ ] 模擬 zero-knowledge AI 跑 hello workflow（待 leo 提供 pk_live）
+- [ ] 量測：from list_components 到 run_workflow 成功 MCP call < 5
+- [ ] 比較人類 GUI 路徑，clickwise 對等
+
+---
+
+## Milestone 3：skill blocks + examples ✅
+
+目標：AI 寫第一個 workflow 不靠猜，有範本和 playbook。
+
+### M3.1 種子 skill blocks ✅ (commit 388c193)
+
+- [x] `skill-build_watcher_workflow` — cron + 過濾 + trigger 模式
+- [x] `skill-debug_paused_workflow` — claude_api callback 流程 + 怎麼追
+- [x] `skill-migrate_http_to_trigger_workflow` — 從 self-fetch 換 trigger_workflow
+- [x] `skill-rag_with_arcrun` — KBDB search + claude_api 組裝
+- [x] `skill-add_new_wasm_component` — TinyGo 寫 + push + 註冊白名單
+
+### M3.2 MCP tools（暫緩，待 M5）
+
+- [ ] `arcrun_list_skills(tag?)`
+- [ ] `arcrun_get_skill(id)`
+- [ ] `arcrun_publish_skill` — AI 把學到的回存
+
+### M3.3 種子 examples ✅ (commit 388c193)
+
+10 個範例都建立（webhook-to-http / cron-watcher / llm-classify /
+rag-search-answer / email-summary / pdf-to-blocks / github-issue-bot /
+daily-digest / parallel-fanout / error-retry），每個含 workflow.yaml +
+description.md + tags.json。
+
+### M3.4 examples 索引 + 搜尋 ✅ (commit 37379b7)
+
+- [x] scripts/sync-registry-to-kbdb.py — 把 registry/examples + skills 同步進 KBDB
+  - 走 kbdb-upsert-block.arcrun.dev (idempotent，page_name 為 key)
+  - examples → type=workflow-example, page_name=example-{slug}
+  - skills → type=agent-skill, page_name=skill-{slug}
+  - 實測 15 blocks created → 第二次 sync 全 PATCH 成功 (idempotent)
+- [ ] `arcrun_search_examples(use_case)` MCP tool（待 M2.x 補）
+
+---
+
+## Milestone 4：closed loop ✅
+
+目標：data 收得到 → 平台自己消化產出 roadmap。
+
+### M4.1 Weekly review workflow ✅ (mira commit de11625)
+
+- [x] 寫 `polaris/mira/arcrun/agent_feedback_weekly_review.yaml`
+- [x] cron `0 9 * * 1` （台灣 17:00 週一）
+- [x] `acr push` 部署
+- [x] 手動觸發測試一次（5/6 nodes success，唯一 fail 是 notify_leo 缺 credential）
+
+### M4.2 LLM 聚合 prompt ✅
+
+- [x] prompt 結構化：數字 / Top 5 痛點（含證據 / 嚴重度）/ 成功 pattern / 下週優先 3 件
+- [x] 一律繁體中文 + 引用 block_id 為證據
+- [x] 存 KBDB type=`arcrun-roadmap`, page_name=roadmap-latest（每週覆蓋）
+- [x] 實測產出真有用：抓到「paused_awaiting_resume 語意不清」「data 量太少」「自動建議包 skill」三個真實 LI 改進建議
+
+### M4.3 通知
+
+- [x] notify_leo 節點：telegram chat_id from secret
+- [ ] leo 補 telegram_bot_token credential 後生效
+- [ ] 同時寫進 mira 河道（讓 leo 在熟悉介面看）— 暫緩
+
+### M4.4 驗收
+
+- [x] 第一次手動觸發 → 收到第一份 roadmap (KBDB block id e924c231-cf5e-4541-89d8-da550ecae2f3)
+- [ ] cron 自動跑首次（下週一驗證）
+- [ ] leo review 後挑 1-2 個 issue 修補
+- [ ] 跑第二週 → 確認該 issue 從 top list 消失
+
+---
+
+## Milestone 5：rename + cleanup（u6u → arcrun 一次切換）
+
+目標：完成 LI 品牌化，u6u branding 整體退場。**leo 2026-05-16 拍板：單一 rename，不留 alias 也不留 deprecation 期**。
+
+### M5.1 切換前準備
+
+- [ ] 全 monorepo `grep -rn "u6u_\|mcp\.finally\.click"` 列出所有受影響檔案 + 用戶配置
+- [ ] mira 河道 + telegram 公告：「ak_xxx 用戶請更新 MCP 配置 URL → mcp.arcrun.dev」（**至少切換前 24h**）
+- [ ] 列 leo 自己的 IDE（Claude Code / Cursor）配置位置，準備同步更新
+
+### M5.2 Repo / Worker rename
+
+- [ ] `matrix/u6u-mcp/` → `matrix/arcrun-mcp/` (git mv)
+- [ ] `matrix/u6u-gui/` → `matrix/arcrun-gui/` (git mv)
+- [ ] `arcrun-mcp/wrangler.toml`: name = `arcrun-mcp`
+- [ ] `arcrun-gui/wrangler.toml`: name = `arcrun-gui`
+- [ ] DNS：`mcp.arcrun.dev` route 接到 arcrun-mcp worker
+- [ ] CI（deploy.yml）若有寫死 path 同步改
+
+### M5.3 Tool rename（一次切換）
+
+- [ ] 所有 `u6u_*` MCP tool 改 `arcrun_*`（不留 alias）
+- [ ] AGENTS.md 全用新名
+- [ ] `arcrun-mcp/README.md` / `GUIDE.md` 全部用新名
+
+### M5.4 舊 URL 退場
+
+- [ ] `mcp.finally.click` 接 410 Gone + 訊息「請改用 mcp.arcrun.dev」
+  - 或 301 redirect 到 arcrun.dev landing 一個說明頁
+- [ ] DNS 紀錄保留 30 天（防意外 client 還沒切）後刪除
+
+### M5.5 文件最終化
+
+- [ ] `arcrun/AGENTS.md` 最終版發布
+- [ ] `matrix/arcrun/.agents/specs/llm-interface/design.md` 加「實際部署狀態」附錄
+- [ ] 寫一篇 retrospective：LI 做完前後 AI 使用 arcrun 的 time-to-first-workflow 對比
+
+### M5.6 連動（不在本 SDD 範圍但要追蹤）
+
+- [ ] `matrix/arcrun/.agents/specs/arcrun-core-mvp/` SDD 改名（另立 task，跨 SDD rename）
+- [ ] `matrix/arcrun/.agents/specs/arcrun-platform-evolution/` 同上
+- [ ] 兩個 SDD 重命名屬「u6u 品牌退場」系列，需要單獨追蹤 task
+
+---
+
+## Backlog（暫不排）
+
+### B.1 KBDB MCP 獨立 SDD
+- LI 範圍只包 KBDB 的 `agent-*` template
+- 完整 KBDB AI 介面（type=note/page/triplet/template/record 等）另立 SDD `kbdb-llm-interface`
+- 跟 mira KM 系統互動最密
+
+### B.2 多 agent 隔離
+- 多 AI 共用同 ak_xxx 時，telemetry 區隔 agent_user_agent
+- 進階：每個 AI 子 namespace（mira / cursor / 自製 agent）
+
+### B.3 AGENTS.md i18n
+- v1 純中文（leo + 自家用）
+- v2 英文版（給開源用戶）
+
+### B.4 自動 skill 萃取
+- weekly_review 產出的 pattern 自動包成 skill draft
+- leo review approve → publish
+
+### B.5 SDK 對等（python-sdk / js-sdk）
+- SDK 提供和 MCP 同樣的 25 個 method
+- 給「不想用 MCP 的人」也能 AI-friendly
+- 走 sdk-and-website SDD 範圍
+
+### B.6 GUI side 補 LI 看板
+- arcrun-gui 加 `/li-dashboard` 顯示用戶自己的 telemetry / feedback
+- 不阻擋 LI 推出（leo 先看 KBDB 原始 block 即可）
+
+---
+
+## 依賴關係
+
+```
+M1 (data 收集)
+   ↓
+M2 (MCP gap-fill)
+   ↓
+M3 (skill + examples)        ← 可與 M2 並行後段
+   ↓
+M4 (closed loop) ←─── 需 M1 data 累積 1-2 週
+   ↓
+M5 (rename)
+```
+
+---
+
+## 工估算
+
+| Milestone | 工 | 阻擋項 |
+|---|---|---|
+| M1 | 5 個工作日 | 無 |
+| M2 | 5 個工作日 | M1 完（telemetry 先就位才好驗證 M2 改動） |
+| M3 | 5 個工作日 | M2 完（tool 介面定型才寫 skill） |
+| M4 | 3 個工作日 | M1 data 累積 1 週 |
+| M5 | 5 個工作日 | M2-M4 完 |
+| **總** | **23 個工作日 (~5 週)** | |
+
+實際視 leo 排程，可邊用邊改、不必一氣呵成。**M1 是硬前置**——資料不收，改了也不知道改對沒。