# Design: LI (LLM Interface) for arcrun

> v0.1 — 2026-05-16
> 對應 requirements.md（同目錄）

---

## 1. 設計哲學

| 過去 (UI 時代) | 現在 (LI 時代) |
|---|---|
| 使用者是人，要學軟體 | 使用者是 AI，要被軟體 onboard |
| 操作靠視覺、滑鼠 | 操作靠 MCP tool call |
| 錯誤訊息是技術 stack trace | 錯誤訊息是「下一步該做什麼」 |
| 文件是 long-form 教學 | 文件是結構化 schema + 可程式查 |
| 用戶教學是 onboarding 課程 | 「教學」是 MCP 工具自己會回 hint |
| 回饋靠 helpdesk 工單 | 回饋是 MCP tool（AI 直接 call） |

**原則**：
1. **discoverable** — AI 不靠 grep / 不靠人就能知道有什麼
2. **idempotent** — 同樣輸入兩次結果一樣，可預測
3. **dry-run by default** — preview 是預設、commit 是 explicit
4. **structured errors** — error 是 JSON 含 next_actions，不是字串
5. **closed loop** — AI 卡住的 data 自動回流，平台 self-improving

---

## 2. 系統架構

```
┌────────────────────────────────────────────────────────────────┐
│                        AI agent (Claude / Cursor / ...)         │
└──────────────────┬──────────────────────────────┬───────────────┘
                   │                              │
                   │ ① Read AGENTS.md             │ ② MCP tool calls
                   ▼                              ▼
┌────────────────────────┐   ┌──────────────────────────────────┐
│   AGENTS.md            │   │   arcrun-mcp (擴張 arcrun-mcp)        │
│   (repo + KBDB block)  │   │   25 tools, 5 categories          │
└────────────────────────┘   └──────────────┬───────────────────┘
                                            │
                ┌────────┬─────────┬────────┴────────┬──────────┐
                ▼        ▼         ▼                 ▼          ▼
        ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
        │ cypher- │ │registry │ │  kbdb   │ │ Skills  │ │ Examples │
        │executor │ │         │ │         │ │ (KBDB)  │ │ (git+KV) │
        │ 31 路由 │ │         │ │ 50 路由 │ │         │ │          │
        └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘
                                  ▲
                                  │ ③ AI 部署完 / 卡住 call feedback
                                  │
                    ┌─────────────┴──────────────┐
                    │ report_feedback / agent-telemetry │
                    │ (寫進 KBDB)                       │
                    └─────────────┬──────────────┘
                                  │ ④ 每週聚合
                                  ▼
                    ┌──────────────────────────────┐
                    │ agent_feedback_weekly_review │
                    │ (arcrun workflow, dogfood)   │
                    │ → arcrun-roadmap KBDB block  │
                    └──────────────────────────────┘
```

---

## 3. 五層 LI 模型

### Layer 0：Onboarding（AGENTS.md）

**位置**：
- `arcrun/AGENTS.md`（repo 根，git 可讀）
- KBDB `type=agent-onboarding` block（MCP `get_onboarding_doc()` 拉）

**結構（控 5-8K tokens）**：
1. **30 字 What** — 「arcrun 是用 YAML 把零件串成 workflow 的平台」
2. **5 個核心概念** — component / cypher binding YAML / FOREACH / paused-resume / api_key
3. **連線**：「在你的 MCP config 加 `https://mcp.arcrun.dev/mcp`，bearer `ak_xxx`」
4. **第一個 workflow（minimal example）** — 10 行 YAML，含部署 + 觸發
5. **5 個 URL 慣例與為什麼**（workers.dev vs arcrun.dev / KBDB endpoints）
6. **常見錯誤 5 個 + 怎麼讀**
7. **不確定的時候**：明確列「先 call list_X 再下手」
8. **回報機制**：完成任何 workflow deploy / 卡住，**必須** call `report_feedback`

**部署機制**：
- repo `arcrun/AGENTS.md` 是 source of truth
- GH Actions 監聽該檔變動 → 自動 PATCH KBDB onboarding block
- MCP `get_onboarding_doc()` 從 KBDB 讀（最新）

---

### Layer 1：arcrun-mcp（主戰場）

#### 1.1 命名與部署

- **Server URL**: `https://mcp.arcrun.dev/mcp`（唯一 URL）
- **舊 URL**：`mcp.finally.click` 直接退場（leo 2026-05-16 拍板，理由：「finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層」）
- **Worker rename**：`u6u-mcp` → `arcrun-mcp`（wrangler name 改），repo 路徑 `matrix/u6u-mcp/` → `matrix/arcrun-mcp/`
- **Tool prefix**: 統一 `arcrun_*`（單一 rename，**不保留 `u6u_*` alias**，不留 deprecation 期。用戶量還很少，一次切換可接受。切換前在 mira / telegram 公告）

#### 1.2 Tool 完整清單（25 個，5 類）

##### A. Onboarding & Discovery（5 tools）

| Tool | 對應 HTTP | 用途 |
|---|---|---|
| `arcrun_get_onboarding` | KBDB GET `/blocks?type=agent-onboarding` | 拉 AGENTS.md 內容 |
| `arcrun_list_components` | registry GET `/components` | 所有可用零件 + 1 行 desc |
| `arcrun_get_component_contract` | registry GET `/components/:id` | input/output schema + gherkin tests |
| `arcrun_list_recipes` | cypher GET `/recipes` + `/auth-recipes` | API recipe 一覽 |
| `arcrun_search_examples` | KBDB POST `/search`（type=workflow-example）| 用 use case 搜範例 |

##### B. Workflow CRUD（7 tools）

| Tool | 對應 HTTP | 用途 |
|---|---|---|
| `arcrun_list_workflows` | cypher GET `/webhooks/named` | 用戶現有 workflow |
| `arcrun_get_workflow` | cypher GET `/webhooks/named/:name` | 拿 YAML / graph |
| `arcrun_validate_yaml` | cypher POST `/validate` | dry-run 校驗，不部署 |
| `arcrun_push_workflow` | cypher POST `/webhooks/named` | 部署（也含 validate） |
| `arcrun_delete_workflow` | cypher DELETE `/webhooks/named/:name` | 刪 |
| `arcrun_preview_workflow` | **新增** POST `/preview` | 不寫 KV、模擬 execute |
| `arcrun_diff_workflow` | **新增** POST `/webhooks/named/:name/diff` | 既有 vs 新 YAML 差異 |

##### C. Execution & Trace（5 tools）

| Tool | 對應 HTTP | 用途 |
|---|---|---|
| `arcrun_run_workflow` | cypher POST `/webhooks/named/:name/trigger` | 觸發 + 回 execution_id |
| `arcrun_get_execution_trace` | **新增** GET `/executions/:id` | 結構化 trace（per-node status） |
| `arcrun_list_recent_executions` | **新增** GET `/workflows/:name/executions?limit=10` | 最近 N 次 |
| `arcrun_list_paused_executions` | **新增** GET `/executions/paused` | 卡 callback 的 |
| `arcrun_resume_execution` | cypher POST `/workflows/resume` | 手動 resume |

##### D. Component & Recipe Management（4 tools）

| Tool | 對應 HTTP | 用途 |
|---|---|---|
| `arcrun_search_components` | registry POST search | 語意搜尋 |
| `arcrun_publish_component` | registry POST publish | 上 WASM |
| `arcrun_create_recipe` | cypher POST `/recipes` | 建 API recipe |
| `arcrun_create_auth_recipe` | cypher POST `/auth-recipes` | 建 auth recipe |

##### E. Feedback & Skills（4 tools）

| Tool | 對應 HTTP | 用途 |
|---|---|---|
| `arcrun_report_feedback` | KBDB POST `/blocks`（type=agent-feedback）| AI 主動回報 |
| `arcrun_list_skills` | KBDB GET `/blocks?type=agent-skill` | 列可用 playbook |
| `arcrun_get_skill` | KBDB GET `/blocks/:id` | 拿 skill 內容 |
| `arcrun_publish_skill` | KBDB POST `/blocks`（type=agent-skill）| AI 把學到的存回去 |

#### 1.3 Tool contract 統一規範

每個 tool 都遵守：

**Input**：
- Zod schema declarative
- 每個參數有 `.describe('...')`（給 AI 看的）
- optional 標 default

**Output（成功）**：
```typescript
{
  ok: true,
  data: T,
  hints?: string[],  // optional next-step suggestion，e.g.「你剛部署了，可 call run_workflow 測試」
}
```

**Output（失敗）**：
```typescript
{
  ok: false,
  error_code: 'enum_value',
  human_message: string,
  next_actions: string[],   // 可程式化的下一步
  detail?: unknown,         // 原始錯誤（debug）
}
```

#### 1.4 error_code enum（v1，可加不可刪）

| error_code | 對應狀況 |
|---|---|
| `auth_missing` | api_key 沒帶 |
| `auth_invalid` | api_key 無效 |
| `not_found` | workflow / block 不存在 |
| `validation_failed` | YAML / schema 不過 |
| `component_not_found` | 零件 ID 沒對應 |
| `component_not_in_whitelist` | 零件存在但 cypher-executor 不認 |
| `paused_awaiting_resume` | workflow 在等 callback |
| `rate_limited` | 太頻繁 |
| `internal_error` | 平台 bug（含 detail） |
| `dependency_unavailable` | 下游服務（claude / mira daemon / KBDB）掛 |

---

### Layer 2：Skill blocks（KBDB-native playbook）

#### 2.1 Schema

```typescript
type AgentSkill = {
  id: string;
  type: 'agent-skill';
  page_name: `skill-${slug}`;
  content: string;          // markdown playbook
  tags_json: string[];      // ['watcher', 'debug', 'rag', ...]
  source: 'manual' | 'auto-extracted';
  metadata_json: {
    when_to_use: string;
    example_use_case: string;
    contributed_by?: string; // agent user_agent
    success_count?: number;
  };
};
```

#### 2.2 種子 skill（先建 5 個，以 mira 經驗為本）

| skill page_name | 用途 |
|---|---|
| `skill-build_watcher_workflow` | cron 掃資料 → 觸發處理（mira_feed_watcher pattern） |
| `skill-debug_paused_workflow` | claude_api / 任何 async callback paused 怎麼追 |
| `skill-migrate_http_to_trigger_workflow` | self-fetch 換 trigger_workflow（剛踩過的） |
| `skill-rag_with_arcrun` | 用 KBDB + claude_api 做 RAG |
| `skill-add_new_wasm_component` | 從 TinyGo 寫到 deploy 全流程 |

#### 2.3 自動萃取機制（後期）

`agent_feedback_weekly_review` 跑出來的 Top patterns，LLM 包成 skill draft，leo review 後 publish。

---

### Layer 3：Examples（可搜尋的範例庫）

#### 3.1 存放

- `arcrun/registry/examples/{slug}/`
  - `workflow.yaml`
  - `description.md`（解決什麼問題、怎麼 trigger、預期結果）
  - `tags.json`（`["webhook", "llm", "cron", ...]`）
- CI build 出 `examples-index.json` 推 KBDB（type=workflow-example，內容是 YAML + tags）

#### 3.2 搜尋

- `arcrun_search_examples(use_case)` 走 KBDB `/search`（既有 semantic）
- 命中 → 回 YAML + description + 「你可以基於這個改 X」hint

#### 3.3 第一批範例（10 個）

| slug | 用途 |
|---|---|
| `webhook-to-slack` | 簡單轉發 |
| `cron-watcher` | mira_feed_watcher 簡化版 |
| `llm-classify` | claude_api 分類 |
| `rag-search-answer` | 從 KBDB 找 context → 回答 |
| `email-summary` | gmail → claude → telegram |
| `pdf-to-blocks` | convert → ingest |
| `github-issue-bot` | webhook → claude → 留 comment |
| `daily-digest` | cron → 多源聚合 → 推送 |
| `parallel-fanout` | 一份輸入分發多 workflow |
| `error-retry` | try_catch + wait + retry |

---

### Layer 4：Telemetry & Feedback Loop

#### 4.1 兩條線

```
explicit feedback (AI call)        implicit telemetry (platform auto-log)
        │                                       │
        ▼                                       ▼
   KBDB block type=                    KBDB block type=
   agent-feedback                      agent-telemetry
        │                                       │
        └──────────────┬───────────────────────┘
                       ▼
              agent_feedback_weekly_review
              (arcrun workflow, 週一 9am cron)
                       ▼
              LLM 聚合 + 分類
                       ▼
              KBDB block type=arcrun-roadmap
              （leo 收到 + 寫進 mira 河道）
```

#### 4.2 agent-feedback schema

```typescript
type AgentFeedback = {
  type: 'agent-feedback';
  content: string;            // description 原文
  source: 'mcp-tool-call';
  user_id: string;            // 用戶 namespace
  metadata_json: {
    workflow_name?: string;
    issue_type: 'doc_unclear' | 'tool_missing' | 'error_unhelpful'
              | 'unexpected_behavior' | 'feature_request' | 'success_story';
    retry_count?: number;
    blocked: boolean;
    suggested_fix?: string;
    agent_user_agent: string; // 'claude-code/1.x' etc
  };
  tags_json: ['agent-feedback', `issue:${issue_type}`];
};
```

#### 4.3 agent-telemetry schema

```typescript
type AgentTelemetry = {
  type: 'agent-telemetry';
  source: 'cypher-executor';
  metadata_json: {
    event_type: 'deploy_success' | 'deploy_fail' | 'run_success'
              | 'run_fail' | 'validation_error' | 'mcp_tool_call';
    workflow_name?: string;
    component_id?: string;
    error_code?: string;
    duration_ms: number;
    api_key_hash: string;  // 雜湊，不存原值
    agent_user_agent: string;
  };
};
```

寫入點：
- `webhook-handlers.executeWebhookGraph` 完成（成功 / 失敗都記）
- `routes/webhooks-named.ts` push（deploy 記）
- `routes/cypher.ts` validate 失敗（validation_error 記）
- arcrun-mcp 每個 tool call wrap 記（mcp_tool_call）

#### 4.4 隱私

- api_key 一律 SHA-256 截前 16 字元（不可逆，可聚合）
- workflow content 不 log（只記 name）
- 用戶看自己的 telemetry：MCP `arcrun_my_telemetry(limit)`，只回自己 hash

#### 4.5 weekly review workflow

```yaml
name: agent_feedback_weekly_review
description: 每週一聚合 AI 回饋 + telemetry，產出 Top 痛點

flow:
  - "weekly_cron >> ON_SUCCESS >> fetch_feedback"
  - "fetch_feedback >> ON_SUCCESS >> fetch_telemetry"
  - "fetch_telemetry >> ON_SUCCESS >> aggregate"
  - "aggregate >> ON_SUCCESS >> llm_summarize"
  - "llm_summarize >> ON_SUCCESS >> publish_roadmap_block"
  - "publish_roadmap_block >> ON_SUCCESS >> notify_telegram"

config:
  weekly_cron:
    component: cron
    cron_expr: "0 9 * * 1"  # 週一 9 am UTC
  fetch_feedback:
    component: kbdb_get
    type: 'agent-feedback'
    created_after: "{{ now - 7d }}"
    limit: 500
  fetch_telemetry:
    component: kbdb_get
    type: 'agent-telemetry'
    created_after: "{{ now - 7d }}"
    limit: 5000
  aggregate:
    component: filter   # 或寫個 `group_by` 邏輯零件
    items: "{{fetch_feedback.blocks}}"
    group_by: 'metadata_json.issue_type'
  llm_summarize:
    component: claude_api
    prompt: |
      你是 arcrun 平台的回饋分析師。下面是這週 AI agent 的所有回饋 +
      telemetry 失敗事件。請：
      1. 列 Top 5 痛點（含證據引用）
      2. 為每個痛點建議具體改動（文件 / MCP tool / 錯誤訊息）
      3. 評估嚴重程度（blocked AI vs 略不便）
      
      Feedback：{{aggregate}}
      Telemetry 失敗事件：{{fetch_telemetry.blocks}}
  publish_roadmap_block:
    component: kbdb_create_block
    type: 'arcrun-roadmap'
    page_name: 'roadmap-week-{{date.iso_week}}'
    content: "{{llm_summarize.data.text}}"
  notify_telegram:
    component: telegram
    chat_id: "{{ leo_chat_id }}"
    text: "Arcrun 週報出爐：{{publish_roadmap_block.data.id}}"
```

**這個 workflow 是 dogfood inception**：arcrun 自己跑分析 arcrun 自己。

---

## 4. Coverage Matrix（人類 vs AI）

> 這份表是 NFR-5「覆蓋率可量化」的具體實踐。每個 release 重新檢視。

### 4.1 人類 GUI 能做的事 × LI 對應

| 人類在 arcrun-gui 做的 | LI MCP 工具 | 對等？ |
|---|---|---|
| 看現有 workflow 列表 | `arcrun_list_workflows` | ✅ |
| 點開 workflow 看 YAML | `arcrun_get_workflow` | ✅ |
| 編輯 workflow YAML | `arcrun_push_workflow`（含 update） | ✅ |
| 執行 workflow | `arcrun_run_workflow` | ✅ |
| 看執行結果 | `arcrun_get_execution_trace` | ✅（新增） |
| 翻零件庫 | `arcrun_list_components` + search | ✅ |
| 看零件 contract | `arcrun_get_component_contract` | ✅ |
| 上傳 WASM 零件 | `arcrun_publish_component` | ✅ |
| 設 credential | `arcrun_create_recipe` + （手動 push credential） | ⚠️ 部分（credential 提交需安全考量，AI 不全自動） |
| 翻歷史執行 | `arcrun_list_recent_executions` | ✅（新增） |
| 看 paused 工作流 | `arcrun_list_paused_executions` | ✅（新增） |
| 手動 resume | `arcrun_resume_execution` | ✅ |
| 視覺化 canvas 拖拉 | — | ❌（純視覺，LI 不複製） |
| 看排版 prototype | — | ❌（同上） |
| Flip UI/Logic view | — | ❌（同上） |
| Action log（操作軌跡） | `arcrun_my_telemetry` | ✅（含更多資料）|

**Gap**：3 個視覺類動作 LI 不需要對等；其他全等。

### 4.2 cypher-executor 31 路由 × LI 暴露

| 路由 | LI 暴露？ | 工具 |
|---|---|---|
| `/health`、`/docs`、`/openapi.json` | ❌ infra | — |
| `/execute` | ✅ | `arcrun_run_workflow`（內部） |
| `/cypher/search`、`/cypher/execute` | ✅ | discovery 內部用 |
| `/workflows/resume` | ✅ | `arcrun_resume_execution` |
| `/webhooks/named*` | ✅ | CRUD 對應 5 個 tools |
| `/webhooks/*` (anonymous) | ❌ deprecated | — |
| `/credentials*` | ⚠️ | 只 list + delete，POST 走人類流程（安全考量） |
| `/recipes*`、`/auth-recipes*` | ✅ | 4 個 tools |
| `/validate` | ✅ | `arcrun_validate_yaml` |
| `/auth/*`、`/register`、`/me*` | ❌ admin | — |

**新增需建路由**：`/preview`、`/executions/:id`、`/workflows/:name/executions`、`/executions/paused`、`/webhooks/named/:name/diff`、`/my-telemetry`（共 6 個）

### 4.3 KBDB 50 路由 × LI 暴露

LI **不直接 expose KBDB 50 個路由**。AI 透過 arcrun-mcp 的 abstracted tool（`get_skill` / `list_skills` / `report_feedback` 等）間接用 KBDB。

例外（值得直接 expose 的）：
- `arcrun_kbdb_search(query)` — 走 `/search` semantic
- `arcrun_kbdb_get_block(id)` — 看 block 內容（debug 用）

KBDB schema 設計 / triplets / records 這些屬於另一個 SDD（KBDB MCP），不在本 LI 範圍。

---

## 5. AGENTS.md 模板

```markdown
# Arcrun for AI Agents

## What is Arcrun (30 sec)
Arcrun lets you compose Cloudflare Workers (WASM components) into workflows via YAML.
You write YAML, push to KV, trigger via webhook or cron. Each component is a
TinyGo/AssemblyScript WASM with stdin/stdout JSON I/O.

## Connect (one step)
Add to your MCP config:
\`\`\`json
{
  "mcpServers": {
    "arcrun": {
      "url": "https://mcp.arcrun.dev/mcp",
      "headers": {"Authorization": "Bearer $ARCRUN_API_KEY"}
    }
  }
}
\`\`\`
Get your ak_ key at https://arcrun.dev/me.

## Your first workflow (5 min)
1. `arcrun_list_components()` → see what's available
2. Write 3-line YAML in chat (assistant does this)
3. `arcrun_validate_yaml(yaml)` → confirm
4. `arcrun_push_workflow(yaml)` → deploy
5. `arcrun_run_workflow(name, input)` → test
6. `arcrun_get_execution_trace(id)` → see results

## Core concepts (5 things)
- **Component**: WASM Worker. Use existing or `arcrun_publish_component`.
- **Cypher binding YAML**: triplets `A >> relation >> B` define graph.
- **FOREACH**: `>> 對每個 X >> next_node` iterates lists.
- **Paused-resume**: claude_api etc pause workflow; resumes via callback.
- **api_key**: ak_xxx, all calls need this in MCP auth.

## URL conventions (why this matters)
- `cypher.arcrun.dev` = orchestration API (you push here)
- `arcrun-{kebab}.{user}.workers.dev` = component workers (workers.dev avoids CF self-fetch)
- `kbdb-*.arcrun.dev` = KBDB component workers (your data lives here)

## Common errors
| error_code | What to do |
|---|---|
| `component_not_found` | call `list_components`, check spelling |
| `validation_failed` | read `next_actions` field, fix YAML |
| `paused_awaiting_resume` | normal for claude_api; wait or `get_execution_trace` |
| `auth_invalid` | ak_ wrong, re-fetch from /me |

## Unsure? Do this:
- Don't know what's available → `list_components` / `list_workflows` / `search_examples`
- Don't know syntax → `get_skill('skill-build_X')` for playbooks
- Hit weird behavior → **MUST** call `report_feedback(issue_type='unexpected_behavior', ...)`

## Feedback (required)
After every workflow deploy or debug session, call:
\`\`\`
arcrun_report_feedback({
  workflow_name: '...',
  issue_type: 'success_story' | 'doc_unclear' | 'tool_missing' | 'error_unhelpful' | 'feature_request',
  description: '...',
  blocked: false,
  retry_count: N,
  suggested_fix: '...'  // optional
})
\`\`\`

Even "success" stories help — they tell us what's working.
```

---

## 6. Migration plan（u6u-mcp → arcrun-mcp 一次切換）

### 6.1 切換方式

leo 2026-05-16 拍板：u6u branding 整體退場，**單一 rename，不留 alias 也不留 deprecation 期**。

- Worker 部署 name 改：`u6u-mcp` → `arcrun-mcp`（wrangler.toml）
- 路由改：`mcp.finally.click/*` → `mcp.arcrun.dev/*`（DNS + worker route 同步切）
- 舊 URL 退場：`mcp.finally.click` 不保留（要嘛 410 Gone，要嘛 301 redirect 到 arcrun.dev landing 一個說明頁）
- Tool 名一次改：所有 `u6u_*` rename 成 `arcrun_*`，**舊名直接消失**
- repo 路徑改：`matrix/u6u-mcp/` → `matrix/arcrun-mcp/`

### 6.2 切換前須做

- [ ] 全 monorepo `grep u6u_` 確認所有 client（mira / 自家腳本 / leo 自己的 IDE 配置）
- [ ] 公告：在 mira 河道 + telegram 通知「ak_xxx 用戶請更新 MCP 配置：URL → mcp.arcrun.dev」
- [ ] 切換當天 worker 部署兩個 name（過渡 1 天可回滾），確認流量切完才把舊 worker disable

### 6.3 為什麼不做 deprecation

- 用戶量極少（dogfood 階段，主要是 leo 自己）
- 留 alias 會讓新 AI agent 學到舊名，違背「LI 一致性」原則
- 90 天監控成本 > 一次切換 + 公告

### 6.2 新增 tools（按 phase）

Phase 1（gap-fill）：
- `arcrun_validate_yaml`（既有 `/validate` 已存，包 MCP 即可）
- `arcrun_get_execution_trace`（需 cypher-executor 新加 `/executions/:id`）
- `arcrun_list_recent_executions`（新 endpoint）
- `arcrun_list_paused_executions`（新 endpoint）
- `arcrun_report_feedback`（新 tool）
- `arcrun_get_onboarding`（KBDB read）

Phase 2（advanced）：
- `arcrun_preview_workflow`（新 endpoint，沒 KV side-effect）
- `arcrun_diff_workflow`
- `arcrun_my_telemetry`
- `arcrun_search_examples`（KBDB write + search 已存）
- `arcrun_list_skills` / `arcrun_get_skill` / `arcrun_publish_skill`

Phase 3（auto-loop）：
- `agent_feedback_weekly_review` workflow
- `arcrun-roadmap` block 生成
- LLM extract skill 自動化

---

## 7. 開發順序與里程碑

### Milestone 1：可量測（1 週）
- 寫 AGENTS.md v1
- 加 implicit telemetry 寫入點（cypher-executor）
- 加 `arcrun_report_feedback` MCP tool
- 建 `agent-feedback` / `agent-telemetry` KBDB template
- 開始收 data

### Milestone 2：gap-fill（1 週）
- arcrun-mcp 補上 6 個 Phase 1 tools
- 新 endpoints 在 cypher-executor 加
- 每個 tool 結構化 error contract

### Milestone 3：skill + example（1 週）
- 種子 5 個 skill blocks
- 種子 10 個 example workflows
- `search_examples` 跑通

### Milestone 4：closed loop（半週）
- weekly_review workflow 部署
- 第一份 arcrun-roadmap block 產出
- leo 收到第一份週報

### Milestone 5：rename + cleanup（1 週）
- arcrun-mcp → arcrun-mcp 公開
- 舊 tool 加 deprecation warning
- AGENTS.md 同步 KBDB

---

## 8. 決策紀錄

### 8.1 已拍板（2026-05-16 leo）

| 決策 | 結果 | 理由 |
|---|---|---|
| MCP server URL | `mcp.arcrun.dev` 單一 URL，舊 `mcp.finally.click` 直接退場 | finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層 |
| u6u branding | 整體退場改 arcrun（repo / worker / tool 命名一次 rename） | u6u 不存在了 |
| Deprecation 期 | 不留（一次切換 + 公告） | 用戶量極少，留 alias 反而讓新 AI 學到舊名 |
| 擴張 vs 建新 | 擴張既有 u6u-mcp（rename 成 arcrun-mcp） | 不 fork，零移轉痛 |
| AGENTS.md 位置 | repo `arcrun/AGENTS.md` + 自動同步 KBDB block | 兩面都拿到（git-access 也 OK，純 MCP 也 OK） |
| feedback 寫入 auth | 要（驗 ak_ 存在即可，不查餘額） | 防 spam |

### 8.2 仍可商議（小議題）

| 議題 | 建議 |
|---|---|
| LI 是否包含 KBDB MCP | 部分（abstracted），KBDB MCP 另立 SDD `kbdb-llm-interface` |
| Telemetry 保留多久 | 90 天 hot + 1 年 cold archive |
| AGENTS.md 第一版用中文還是英文 | 中文（leo 自家 + mira 一致），英文版 v2 開源時補 |

---

## 9. 跨 SDD 連動

| 其他 SDD | 連動點 |
|---|---|
| `credential-primitives-wasm` | LI 不重做 auth，只用 `auth_static_key` 等既有零件 |
| `recipe-system` | LI 暴露 recipe CRUD tool 對應 |
| `component-registry-canon` | LI `list_components` / `get_contract` 走 registry |
| `resumable-workflow` | LI `list_paused_executions` / `resume` 用 |
| `arcrun-platform-evolution` | LI 是 evolution 之一，未來分 user-tier 時要考慮 |
| **mira-app** (polaris/mira) | LI 是 mira dogfood 痛點轉化的產物，roadmap 含對 mira 的回饋 |