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

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

• 寫 arcrun/AGENTS.md（5697355 + 3892dc3，263 行）
• CI hook：repo AGENTS.md 變動 → 自動同步 KBDB block
• arcrun_get_onboarding MCP tool（讀 KBDB block）

M1.2 Implicit telemetry 收集 ✅

• 建 KBDB block type=agent-telemetry（slots 直接 metadata_json 不走 template）
• webhook-handlers.executeWebhookGraph 末尾加 telemetry（成功 / 失敗 / paused 都記）
• routes/webhooks-named.ts push deploy 事件（deploy_success）
• routes/validate.ts validation 失敗事件（schema_failed / edge_node_missing）
• hashApiKey SHA-256 截 16 字元 helper
• 隱私：只記 workflow name 不記 content
• 實測：KBDB block 68635dcb-62e5-49ca-9c67-33f4ca82b7a0 event=run_success, paused_awaiting_resume

M1.3 Explicit feedback tool ✅

• KBDB block type=agent-feedback
• arcrun-mcp tool arcrun_report_feedback (commit e637c3e)
• Zod enum 鎖死 issue_type
• user_id 從 partnerAuth 取
• tags_json auto: ['agent-feedback', 'issue:{type}', 'blocked'?, 'wf:{name}'?]
• schema 實測：KBDB block 80f1d2d1-c95a-4dfe-a889-d23b2e9b247d

M1.4 驗收 ✅

• 觸發 mira watcher → KBDB agent-telemetry 即時出現
• curl + python verify 8 個 telemetry blocks（event=run_success, workflow_name 對, duration_ms 對）
• feedback block 寫入測 schema 通

---

Milestone 2：gap-fill（補 MCP 工具）

目標：人類 GUI 能做的，AI 透過 MCP 都能做。

M2.1 新增 cypher-executor 路由 ✅

• GET /executions/:task_id — 回結構化 paused state (989fbeb)
• GET /workflows/:name/executions?limit=10 — 走 ANALYTICS_KV stats:* prefix (989fbeb)
• 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）：

• arcrun_validate_yaml — wrap /validate
• arcrun_get_execution_trace
• arcrun_list_recent_executions
• arcrun_list_paused_executions
• arcrun_push_workflow — wrap /webhooks/named POST（取代壞掉的 u6u_deploy_workflow）
• arcrun_list_workflows
• arcrun_get_workflow
• arcrun_delete_workflow (require confirm:true literal)
• 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 統一 ✅

• error_code enum v1 定義在 design.md §1.4 + cypher-executor /executions/* 路由都用
• arcrun-mcp lib/cypher-client.ts errorResponse() / successResponse() 統一 helper
• 所有新 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)

• skill-build_watcher_workflow — cron + 過濾 + trigger 模式
• skill-debug_paused_workflow — claude_api callback 流程 + 怎麼追
• skill-migrate_http_to_trigger_workflow — 從 self-fetch 換 trigger_workflow
• skill-rag_with_arcrun — KBDB search + claude_api 組裝
• 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)

• 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)

• 寫 polaris/mira/arcrun/agent_feedback_weekly_review.yaml
• cron 0 9 * * 1 （台灣 17:00 週一）
• acr push 部署
• 手動觸發測試一次（5/6 nodes success，唯一 fail 是 notify_leo 缺 credential）

M4.2 LLM 聚合 prompt ✅

• prompt 結構化：數字 / Top 5 痛點（含證據 / 嚴重度）/ 成功 pattern / 下週優先 3 件
• 一律繁體中文 + 引用 block_id 為證據
• 存 KBDB type=arcrun-roadmap, page_name=roadmap-latest（每週覆蓋）
• 實測產出真有用：抓到「paused_awaiting_resume 語意不清」「data 量太少」「自動建議包 skill」三個真實 LI 改進建議

M4.3 通知

• notify_leo 節點：telegram chat_id from secret
• leo 補 telegram_bot_token credential 後生效
• 同時寫進 mira 河道（讓 leo 在熟悉介面看）— 暫緩

M4.4 驗收

• 第一次手動觸發 → 收到第一份 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 是硬前置——資料不收，改了也不知道改對沒。