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