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

Tasks: LI (LLM Interface) for arcrun

SDD: design.md + requirements.md（同目錄） 進度標記：[ ] pending / [🔄] doing / [x] done / [⏸] blocked

---

Milestone 1：可量測（先收 data）

目標：1 週內把「平台自己收 AI 用得好不好」的數據管道接通。

M1.1 AGENTS.md v1

• 寫 arcrun/AGENTS.md（按 design.md §5 模板）
• CI hook：repo AGENTS.md 變動 → 自動同步 KBDB block
• arcrun_get_onboarding MCP tool（讀 KBDB block）

M1.2 Implicit telemetry 收集

• 建 KBDB template agent-telemetry（slots: event_type, workflow_name, error_code, duration_ms, api_key_hash, agent_user_agent）
• cypher-executor webhook-handlers.executeWebhookGraph 末尾加 telemetry 寫入（成功 / 失敗都記）
• cypher-executor routes/webhooks-named.ts push 加 deploy 事件
• cypher-executor routes/cypher.ts validate 失敗 → validation_error 事件
• api_key SHA-256 截 16 字元 helper
• 隱私 check：workflow content 不 log，只 name

M1.3 Explicit feedback tool

• 建 KBDB template agent-feedback（slots: issue_type, workflow_name, retry_count, blocked, suggested_fix, agent_user_agent）
• u6u-mcp 加 tool arcrun_report_feedback
• Zod schema 鎖死 issue_type enum
• 寫入時 user_id 從 partner-auth middleware 拿
• 寫入時 tag 自動補（agent-feedback, issue:{type}）

M1.4 驗收

• 用 Claude Code 跑 mira 開發 1-2 天，自然累積 telemetry + feedback
• 用 curl kbdb-get.arcrun.dev type=agent-telemetry 確認有 data
• 用 curl kbdb-get.arcrun.dev type=agent-feedback 確認 enum 有效

---

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

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

M2.1 新增 cypher-executor 路由

• GET /executions/:id — 回結構化 trace（讀 EXEC_CONTEXT KV）
  • 既有資料：graph-executor.ts trace array，需確認 KV 持久化
• GET /workflows/:name/executions?limit=10 — 最近 N 次執行 ID + 摘要
  • 需 ANALYTICS_KV 或新 index
• GET /executions/paused — 列當前 paused executions
  • 走 EXEC_CONTEXT KV scan paused:* prefix
• POST /preview — dry-run，不寫 KV
  • 複用 GraphExecutor，env.EXEC_CONTEXT 改 in-memory mock
• POST /webhooks/named/:name/diff — 新舊 YAML diff
• GET /my-telemetry?limit=N — 用戶自己看 telemetry

M2.2 MCP tools（包既有 + 新增 endpoint）

• arcrun_validate_yaml — 包 /validate
• arcrun_get_execution_trace
• arcrun_list_recent_executions
• arcrun_list_paused_executions
• arcrun_resume_execution — 包 /workflows/resume
• arcrun_list_workflows — 既有但確認
• arcrun_get_workflow
• arcrun_delete_workflow
• arcrun_preview_workflow
• arcrun_diff_workflow
• arcrun_list_recipes / arcrun_create_recipe
• arcrun_list_auth_recipes / arcrun_create_auth_recipe
• arcrun_my_telemetry

M2.3 Error contract 統一

• 定義 error_code enum v1（design.md §3.1.4）
• u6u-mcp 所有 tool 統一 error wrap（helper function）
• cypher-executor 所有 route 統一 error response（含 error_code + next_actions）
• 寫測試：每個 error_code 至少一個 case

M2.4 驗收

• 模擬 zero-knowledge AI（新 conversation）按 AGENTS.md 部署一個 hello workflow
• 量測：從 list_components 到 run_workflow 成功總 MCP call < 5
• 比較人類 GUI 路徑，clickwise 對等

---

Milestone 3：skill blocks + examples

目標：AI 寫第一個 workflow 不靠猜，有範本和 playbook。

M3.1 種子 skill blocks（5 個）

• 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

• arcrun_list_skills(tag?)
• arcrun_get_skill(id)
• arcrun_publish_skill — AI 把學到的回存

M3.3 種子 examples（10 個）

• webhook-to-slack
• 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，放 arcrun/registry/examples/{slug}/。

M3.4 examples 索引 + 搜尋

• CI build 範例 → KBDB block type=workflow-example（含 YAML + tags + description）
• arcrun_search_examples(use_case) MCP tool（走 KBDB /search）

---

Milestone 4：closed loop

目標：data 收得到 → 平台自己消化產出 roadmap。

M4.1 Weekly review workflow

• 寫 polaris/mira/arcrun/agent_feedback_weekly_review.yaml（依 design.md §4.5 範本）
• cron 0 9 * * 1（週一早 9 UTC）
• acr push
• 手動觸發測試一次

M4.2 LLM 聚合 prompt

• 寫 prompt：把 feedback + telemetry 餵 Claude → 產出 Top 5 痛點 + 建議
• 結果格式固定：markdown sections（痛點 / 證據 / 建議 / 嚴重度）
• 存 KBDB block type=arcrun-roadmap

M4.3 通知

• notify_telegram 節點：推給 leo
• 同時寫進 mira 河道（讓 leo 在熟悉介面看）

M4.4 驗收

• 跑滿 1 週 → 收到第一份 roadmap
• leo review 後挑 1-2 個 issue 修補
• 跑第二週 → 確認該 issue 從 top list 消失

---

Milestone 5：rename + cleanup

目標：完成 LI 品牌化，u6u-mcp 退場。

M5.1 部署

• u6u-mcp Worker 改 wrangler name → arcrun-mcp
• 加 route mcp.arcrun.dev/*
• 舊 route mcp.finally.click/* 保留 90 天

M5.2 Tool rename

• 每個 u6u_* tool 加 alias arcrun_*
• 舊 tool call → response 含 deprecation_warning 欄
• AGENTS.md 全用新名

M5.3 文件

• arcrun/AGENTS.md 最終版
• u6u-mcp/README.md 標 deprecated，指向新位置
• matrix/arcrun/.agents/specs/llm-interface/design.md 更新「實際部署狀態」附錄

M5.4 觀察 90 天

• 監控舊 tool name 使用率
• 0 使用 → 移除 alias
• 寫一篇 retrospective：LI 做完前後 AI 使用 arcrun 的 time-to-first-workflow 對比

---

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 看板

• u6u-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 是硬前置——資料不收，改了也不知道改對沒。