Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(llm-interface): apply leo's decisions — drop u6u + finally.click

Browse Source 
leo 2026-05-16 拍板（除 dual-hostname 外照原設計）：
1. MCP URL: 單一 mcp.arcrun.dev，mcp.finally.click 直接退場（不並存）
   - 理由：finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層
2. u6u branding 整體退場：
   - u6u-mcp repo → arcrun-mcp
   - u6u-gui repo → arcrun-gui
   - u6u_* tool prefix → arcrun_*
   - 一次切換，不留 alias，不留 deprecation 期
   - 理由：u6u 不存在了

SDD 三件套同步更新：
- requirements.md: 開放問題章節改決策紀錄；移除「保留 15 tool deprecation」自相矛盾
- design.md: §1.1 命名 + §6 migration plan + §8 決策表全部改成「單一切換」
- tasks.md: M5 重組成 6 個 sub-step（準備 / repo rename / tool rename / 舊 URL 退場 / 文件 / 連動 SDD 追蹤）

連動但不在本 SDD 範圍：
- matrix/arcrun/.agents/specs/u6u-core-mvp/ 改名
- matrix/arcrun/.agents/specs/u6u-platform-evolution/ 改名
（M5.6 列出，另起 task 追蹤）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
richblack
2026-05-16 15:09:48 +08:00
parent c2a2f82ade
commit 5d99302681
3 changed files with 104 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/specs/llm-interface/design.md
+47 -21
View File
@@ -35,7 +35,7 @@
│ ① Read AGENTS.md │ ② MCP tool calls │ ① Read AGENTS.md │ ② MCP tool calls
▼ ▼ ▼ ▼
┌────────────────────────┐ ┌──────────────────────────────────┐ ┌────────────────────────┐ ┌──────────────────────────────────┐
│ AGENTS.md │ │ arcrun-mcp (擴張 u6u-mcp) │ │ AGENTS.md │ │ arcrun-mcp (擴張 arcrun-mcp) │
│ (repo + KBDB block) │ │ 25 tools, 5 categories │ │ (repo + KBDB block) │ │ 25 tools, 5 categories │
└────────────────────────┘ └──────────────┬───────────────────┘ └────────────────────────┘ └──────────────┬───────────────────┘
│ │
@@ -93,9 +93,10 @@
#### 1.1 命名與部署 #### 1.1 命名與部署
- **Server URL**: `https://mcp.arcrun.dev/mcp`（新增 route，對應 `mcp.finally.click` 既有 worker） - **Server URL**: `https://mcp.arcrun.dev/mcp`（唯一 URL）
- **過渡**：u6u-mcp Worker rename `arcrun-mcp`，雙路由（finally.click + arcrun.dev）並存 90 天 - **舊 URL**：`mcp.finally.click` 直接退場（leo 2026-05-16 拍板，理由：「finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層」）
- **Tool prefix**: 統一 `arcrun_*`（既有 `u6u_*` 加 alias 對應，舊名 deprecation 公告） - **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 類） #### 1.2 Tool 完整清單（25 個，5 類）
@@ -402,7 +403,7 @@ config:
### 4.1 人類 GUI 能做的事 × LI 對應 ### 4.1 人類 GUI 能做的事 × LI 對應
| 人類在 u6u-gui 做的 | LI MCP 工具 | 對等？ | | 人類在 arcrun-gui 做的 | LI MCP 工具 | 對等？ |
|---|---|---| |---|---|---|
| 看現有 workflow 列表 | `arcrun_list_workflows` | ✅ | | 看現有 workflow 列表 | `arcrun_list_workflows` | ✅ |
| 點開 workflow 看 YAML | `arcrun_get_workflow` | ✅ | | 點開 workflow 看 YAML | `arcrun_get_workflow` | ✅ |
@@ -527,14 +528,29 @@ Even "success" stories help — they tell us what's working.
--- ---
## 6. Migration plan（u6u-mcp → arcrun-mcp） ## 6. Migration plan（u6u-mcp → arcrun-mcp 一次切換）
### 6.1 不破壞 ### 6.1 切換方式
- u6u-mcp Worker rename `arcrun-mcp`（wrangler name 改） leo 2026-05-16 拍板：u6u branding 整體退場，**單一 rename，不留 alias 也不留 deprecation 期**。
- 兩個 hostname 並存：`mcp.finally.click` + `mcp.arcrun.dev`（route 加一條）
- 舊 tool 名（`u6u_*`）保留，加 alias 對應新名（`arcrun_*`） - Worker 部署 name 改：`u6u-mcp` → `arcrun-mcp`（wrangler.toml）
- 90 天 deprecation 期，舊 tool call → 回 warning hint「`u6u_X` → 改用 `arcrun_X`」 - 路由改：`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） ### 6.2 新增 tools（按 phase）
@@ -570,7 +586,7 @@ Phase 3（auto-loop）：
- 開始收 data - 開始收 data
### Milestone 2：gap-fill（1 週） ### Milestone 2：gap-fill（1 週）
- u6u-mcp 補上 6 個 Phase 1 tools - arcrun-mcp 補上 6 個 Phase 1 tools
- 新 endpoints 在 cypher-executor 加 - 新 endpoints 在 cypher-executor 加
- 每個 tool 結構化 error contract - 每個 tool 結構化 error contract
@@ -585,22 +601,32 @@ Phase 3（auto-loop）：
- leo 收到第一份週報 - leo 收到第一份週報
### Milestone 5：rename + cleanup（1 週） ### Milestone 5：rename + cleanup（1 週）
- u6u-mcp → arcrun-mcp 公開 - arcrun-mcp → arcrun-mcp 公開
- 舊 tool 加 deprecation warning - 舊 tool 加 deprecation warning
- AGENTS.md 同步 KBDB - AGENTS.md 同步 KBDB
--- ---
## 8. 開放決策（待 leo） ## 8. 決策紀錄
| 決策 | 推薦 | 理由 | ### 8.1 已拍板（2026-05-16 leo）
| 決策 | 結果 | 理由 |
|---|---|---| |---|---|---|
| MCP server URL | `mcp.arcrun.dev`（route 並存 `mcp.finally.click` 90 天） | 品牌統一 | | MCP server URL | `mcp.arcrun.dev` 單一 URL，舊 `mcp.finally.click` 直接退場 | finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層 |
| 擴張 u6u-mcp vs 建新 | 擴張 + rename | 不 fork，零移轉痛 | | u6u branding | 整體退場改 arcrun（repo / worker / tool 命名一次 rename） | u6u 不存在了 |
| AGENTS.md 位置 | `arcrun/AGENTS.md` + KBDB 自動同步 | 兩面都拿到 | | Deprecation 期 | 不留（一次切換 + 公告） | 用戶量極少，留 alias 反而讓新 AI 學到舊名 |
| feedback 是否要 auth | 要（驗 ak_ 存在即可，不查餘額） | 防 spam | | 擴張 vs 建新 | 擴張既有 u6u-mcp（rename 成 arcrun-mcp） | 不 fork，零移轉痛 |
| LI 是否包含 KBDB MCP | 部分（abstracted），KBDB MCP 另立 SDD | 範圍清楚 | | AGENTS.md 位置 | repo `arcrun/AGENTS.md` + 自動同步 KBDB block | 兩面都拿到（git-access 也 OK，純 MCP 也 OK） |
| Telemetry 保留多久 | 90 天 hot + 1 年 cold archive | 平衡 cost 與 review | | 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 開源時補 |
--- ---
.agents/specs/llm-interface/requirements.md
+23 -19
View File
@@ -8,7 +8,7 @@
## 背景 ## 背景
arcrun 是 n8n-like workflow 平台，平台本身的 end-user 有兩類： arcrun 是 n8n-like workflow 平台，平台本身的 end-user 有兩類：
- **人類**：透過 u6u-gui canvas / arcrun.dev landing 操作 - **人類**：透過 arcrun-gui canvas / arcrun.dev landing 操作
- **AI agent**：透過 MCP / API 操作（Claude Code、Cursor、Codex、自製 agent 等） - **AI agent**：透過 MCP / API 操作（Claude Code、Cursor、Codex、自製 agent 等）
過去設計集中在「人」（UI / docs）。AI 對 arcrun 的「可用性」沒被當第一公民。 過去設計集中在「人」（UI / docs）。AI 對 arcrun 的「可用性」沒被當第一公民。
@@ -76,8 +76,8 @@ LI 不是「新建一個 service」，是**跨 5 個既有系統的橫向 layer*
|---|---|---| |---|---|---|
| **arcrun cypher-executor** | 31 HTTP 路由 | 哪些對外、哪些 AI 該看得到 | | **arcrun cypher-executor** | 31 HTTP 路由 | 哪些對外、哪些 AI 該看得到 |
| **arcrun registry** | component 管理 Worker | discovery layer | | **arcrun registry** | component 管理 Worker | discovery layer |
| **u6u-mcp** | 15 MCP tools（HTTP→MCP 薄包裝） | 主擴張面（gap-fill） | | **arcrun-mcp**（目前 `matrix/u6u-mcp/`，本 SDD M5 改名） | 15 MCP tools（HTTP→MCP 薄包裝） | 主擴張面（gap-fill） |
| **u6u-gui** | 人類 canvas IDE | 取其 endpoint 觀念，不取其 UI 元素 | | **arcrun-gui**（目前 `matrix/u6u-gui/`，本 SDD M5 改名） | 人類 canvas IDE | 取其 endpoint 觀念，不取其 UI 元素 |
| **kbdb** | 50 個 HTTP 路由 | KBDB 該不該直接給 AI、用什麼姿勢 | | **kbdb** | 50 個 HTTP 路由 | KBDB 該不該直接給 AI、用什麼姿勢 |
| **arcrun CLI (acr)** | Node CLI | LI 不依賴 CLI（CLI 是人的工具） | | **arcrun CLI (acr)** | Node CLI | LI 不依賴 CLI（CLI 是人的工具） |
@@ -103,7 +103,7 @@ LI 不是「新建一個 service」，是**跨 5 個既有系統的橫向 layer*
### FR-2：完整 CRUD + Discovery 對等 ### FR-2：完整 CRUD + Discovery 對等
人類在 u6u-gui 能做的 8 個動作（list_workflows / get / update / execute / search_components / get_component / list_templates / list_credentials），**MCP 至少同等覆蓋**，不能有「人類能做但 AI 不能做」的 gap。 人類在 arcrun-gui 能做的 8 個動作（list_workflows / get / update / execute / search_components / get_component / list_templates / list_credentials），**MCP 至少同等覆蓋**，不能有「人類能做但 AI 不能做」的 gap。
### FR-3：Dry-run 是預設行為 ### FR-3：Dry-run 是預設行為
@@ -174,10 +174,12 @@ LI 不是「新建一個 service」，是**跨 5 個既有系統的橫向 layer*
### NFR-1：向下相容 ### NFR-1：向下相容
LI 是新層，不破壞既有： LI 在「擴張」階段（M1-M4）不破壞既有：
- u6u-mcp 既有 15 tool 全保留（廢棄走標準 deprecation） - M1-M4 階段：arcrun-mcp 既有 15 tool 保留，新增 13 個 tool（pre-rename）
- u6u-gui 不動 - arcrun-gui 不動
- cypher-executor 既有路由不改 contract - cypher-executor 既有路由不改 contract（只加新 endpoint）
M5（rename）階段是 breaking change（leo 拍板），需事前公告。
### NFR-2：transport 不鎖死 ### NFR-2：transport 不鎖死
@@ -193,7 +195,7 @@ MCP 主，但 HTTP 同等可用（讓沒 MCP 客戶端的 agent 也可用）。
### NFR-5：覆蓋率可量化 ### NFR-5：覆蓋率可量化
- 「人類在 u6u-gui 能做但 MCP 不能做」清單必須能列出 - 「人類在 arcrun-gui 能做但 MCP 不能做」清單必須能列出
- 每次 LI 改動後，這份清單往 0 收斂 - 每次 LI 改動後，這份清單往 0 收斂
--- ---
@@ -225,18 +227,20 @@ MCP 主，但 HTTP 同等可用（讓沒 MCP 客戶端的 agent 也可用）。
| AI 不照 AGENTS.md 規範用 | implicit telemetry 不依賴自覺，仍能收 data | | AI 不照 AGENTS.md 規範用 | implicit telemetry 不依賴自覺，仍能收 data |
| MCP tool 設計錯誤越改越亂 | 每個 tool 有 contract test，error_code enum 版本化 | | MCP tool 設計錯誤越改越亂 | 每個 tool 有 contract test，error_code enum 版本化 |
| feedback 雜訊太多無法 review | review workflow 用 LLM 聚合，不靠人讀原始 | | feedback 雜訊太多無法 review | review workflow 用 LLM 聚合，不靠人讀原始 |
| u6u-mcp 重構搞壞既有 | 走 deprecation，舊 tool 留 90 天 | | arcrun-mcp 重構搞壞既有用戶 | 用戶量還很少（dogfood 階段），一次切換可接受；切換前公告 |
| KBDB telemetry 量爆掉 | sample rate / 老資料自動 archive | | KBDB telemetry 量爆掉 | sample rate / 老資料自動 archive |
--- ---
## 開放問題（待 leo 決策） ## 決策（2026-05-16 leo 拍板）
1. **deployment 名稱**：MCP server URL 用 `mcp.arcrun.dev` 還是沿用 `mcp.finally.click`？ 1. **deployment 名稱**：✅ `mcp.arcrun.dev` 單一 URL
- 推薦：`mcp.arcrun.dev`（品牌一致，符合 mira CLAUDE.md §1.7） - `mcp.finally.click` 直接退場，不並存
2. **新 MCP vs 擴張 u6u-mcp**：在現有 u6u-mcp 加 tool，還是建 `arcrun-mcp` 取代？ - 理由（leo）：「finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層」
- 推薦：先擴張 u6u-mcp（避免 fork 痛），長期可改名 2. **u6u branding 整體退場**：✅ u6u 命名全部改 arcrun
3. **AGENTS.md 放哪**：`arcrun/AGENTS.md` repo 根？還是 KBDB block？或兩個地方都？ - `u6u-mcp` repo → `arcrun-mcp`
- 推薦：repo `arcrun/AGENTS.md` + KBDB 自動同步 block（讓沒 git access 的 AI 也能讀） - `u6u-gui` repo → `arcrun-gui`
4. **feedback 寫入是否需 auth**：AI report bug 要不要 api_key？ - 工具命名 `u6u_*` → `arcrun_*`（**單一 rename，不留 alias 也不留 deprecation 期**）
- 推薦：要（防 spam），但 tier 低（只要驗 ak_ 存在） - 理由：「u6u 不存在，改成 Arcrun」
3. **AGENTS.md 位置**：✅ repo `arcrun/AGENTS.md` + 自動同步 KBDB block（兩面都拿到）
4. **feedback 寫入需 auth**：✅ 驗 ak_ 存在即可（防 spam，tier 低不查餘額）
.agents/specs/llm-interface/tasks.md
+34 -19
View File
@@ -24,7 +24,7 @@
### M1.3 Explicit feedback tool ### M1.3 Explicit feedback tool
- [ ] 建 KBDB template `agent-feedback`（slots: issue_type, workflow_name, retry_count, blocked, suggested_fix, agent_user_agent） - [ ] 建 KBDB template `agent-feedback`（slots: issue_type, workflow_name, retry_count, blocked, suggested_fix, agent_user_agent）
- [ ] u6u-mcp 加 tool `arcrun_report_feedback` - [ ] arcrun-mcp 加 tool `arcrun_report_feedback`
- [ ] Zod schema 鎖死 issue_type enum - [ ] Zod schema 鎖死 issue_type enum
- [ ] 寫入時 `user_id` 從 partner-auth middleware 拿 - [ ] 寫入時 `user_id` 從 partner-auth middleware 拿
- [ ] 寫入時 tag 自動補（`agent-feedback`, `issue:{type}`） - [ ] 寫入時 tag 自動補（`agent-feedback`, `issue:{type}`）
@@ -72,7 +72,7 @@
### M2.3 Error contract 統一 ### M2.3 Error contract 統一
- [ ] 定義 `error_code` enum v1（design.md §3.1.4） - [ ] 定義 `error_code` enum v1（design.md §3.1.4）
- [ ] u6u-mcp 所有 tool 統一 error wrap（helper function） - [ ] arcrun-mcp 所有 tool 統一 error wrap（helper function）
- [ ] cypher-executor 所有 route 統一 error response（含 error_code + next_actions） - [ ] cypher-executor 所有 route 統一 error response（含 error_code + next_actions）
- [ ] 寫測試：每個 error_code 至少一個 case - [ ] 寫測試：每個 error_code 至少一個 case
@@ -154,34 +154,49 @@
--- ---
## Milestone 5：rename + cleanup ## Milestone 5：rename + cleanup（u6u → arcrun 一次切換）
目標：完成 LI 品牌化，u6u-mcp 退場。 目標：完成 LI 品牌化，u6u branding 整體退場。**leo 2026-05-16 拍板：單一 rename，不留 alias 也不留 deprecation 期**。
### M5.1 部署 ### M5.1 切換前準備
- [ ] u6u-mcp Worker 改 wrangler name → `arcrun-mcp` - [ ] 全 monorepo `grep -rn "u6u_\|mcp\.finally\.click"` 列出所有受影響檔案 + 用戶配置
- [ ] 加 route `mcp.arcrun.dev/*` - [ ] mira 河道 + telegram 公告：「ak_xxx 用戶請更新 MCP 配置 URL → mcp.arcrun.dev」（**至少切換前 24h**）
- [ ] 舊 route `mcp.finally.click/*` 保留 90 天 - [ ] 列 leo 自己的 IDE（Claude Code / Cursor）配置位置，準備同步更新
### M5.2 Tool rename ### M5.2 Repo / Worker rename
- [ ] 每個 `u6u_*` tool 加 alias `arcrun_*` - [ ] `matrix/u6u-mcp/` → `matrix/arcrun-mcp/` (git mv)
- [ ] 舊 tool call → response 含 `deprecation_warning` 欄 - [ ] `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 全用新名 - [ ] AGENTS.md 全用新名
- [ ] `arcrun-mcp/README.md` / `GUIDE.md` 全部用新名
### M5.3 文件 ### M5.4 舊 URL 退場
- [ ] `arcrun/AGENTS.md` 最終版 - [ ] `mcp.finally.click` 接 410 Gone + 訊息「請改用 mcp.arcrun.dev」
- [ ] `u6u-mcp/README.md` 標 deprecated，指向新位置 - 或 301 redirect 到 arcrun.dev landing 一個說明頁
- [ ] `matrix/arcrun/.agents/specs/llm-interface/design.md` 更新「實際部署狀態」附錄 - [ ] DNS 紀錄保留 30 天（防意外 client 還沒切）後刪除
### M5.4 觀察 90 天 ### M5.5 文件最終化
- [ ] 監控舊 tool name 使用率 - [ ] `arcrun/AGENTS.md` 最終版發布
- [ ] 0 使用 → 移除 alias - [ ] `matrix/arcrun/.agents/specs/llm-interface/design.md` 加「實際部署狀態」附錄
- [ ] 寫一篇 retrospective：LI 做完前後 AI 使用 arcrun 的 time-to-first-workflow 對比 - [ ] 寫一篇 retrospective：LI 做完前後 AI 使用 arcrun 的 time-to-first-workflow 對比
### M5.6 連動（不在本 SDD 範圍但要追蹤）
- [ ] `matrix/arcrun/.agents/specs/u6u-core-mvp/` SDD 改名（另立 task，跨 SDD rename）
- [ ] `matrix/arcrun/.agents/specs/u6u-platform-evolution/` 同上
- [ ] 兩個 SDD 重命名屬「u6u 品牌退場」系列，需要單獨追蹤 task
--- ---
## Backlog（暫不排） ## Backlog（暫不排）
@@ -209,7 +224,7 @@
- 走 sdk-and-website SDD 範圍 - 走 sdk-and-website SDD 範圍
### B.6 GUI side 補 LI 看板 ### B.6 GUI side 補 LI 看板
- u6u-gui 加 `/li-dashboard` 顯示用戶自己的 telemetry / feedback - arcrun-gui 加 `/li-dashboard` 顯示用戶自己的 telemetry / feedback
- 不阻擋 LI 推出（leo 先看 KBDB 原始 block 即可） - 不阻擋 LI 推出（leo 先看 KBDB 原始 block 即可）
--- ---