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