From 53080ffa53d30e1e9e6d1cef1cc6fb1c8ac801ca Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 05:37:54 +0000 Subject: [PATCH] =?UTF-8?q?docs(mcp):=20GUIDE/README=20=E5=85=A8=E9=9D=A2?= =?UTF-8?q?=E6=94=B9=E6=95=99=20arcrun=5F*=EF=BC=8C=E6=B8=85=E6=8E=89?= =?UTF-8?q?=E6=AD=BB=20u6u=5F=20=E5=B7=A5=E5=85=B7=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 死文件治理：GUIDE.md（25 處）與 README.md（21 處）仍在教 u6u_* 工具名， 含本 PR 已刪的 4 個 tool（deploy/execute/get/list_workflows），下個 CC 照著走會撞牆。 - 全部 u6u_* → 現役 arcrun_*（component/tag/gui 那批用新名） - 已刪 tool 改指現役：execute→run、deploy→push、get/list_workflows→crud 版 - 修正因換工具而失真的流程與參數：沙盒測試段改為 arcrun_validate_yaml（部署前 schema 驗證）→ arcrun_push_workflow（部署）→ arcrun_run_workflow（觸發，帶 api_key/name/input）；get_workflow 參數 workflow_id→name - 順帶把兩處品牌 prose "u6u" 改 "Arcrun" - grep 確認兩檔零 u6u brand.ts：釐清 ARCRUN_TOOL_PREFIX 覆蓋僅內部 rebrand 過渡 / 測試鉤子， Workers runtime 無 process 全域基本不生效、勿當對外特性。 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk --- mcp/GUIDE.md | 85 ++++++++++++++++++++++++++---------------------- mcp/README.md | 54 ++++++++++++++++-------------- mcp/src/brand.ts | 6 ++-- 3 files changed, 79 insertions(+), 66 deletions(-) diff --git a/mcp/GUIDE.md b/mcp/GUIDE.md index 4ad0d18..b88f02e 100644 --- a/mcp/GUIDE.md +++ b/mcp/GUIDE.md @@ -3,8 +3,7 @@ > Arcrun 是 **AI 優先（AI-First）** 的工作流自動化平台。 > 跟 AI 描述你的意圖，Arcrun 幫你把它變成可重複執行、不需要 AI 的自動化工作流。 > -> 註：本指南部分工具仍以舊 `u6u_` 前綴記載（registry/component 管理那組）；現役 workflow 工具是 -> `arcrun_*`（見 `mcp/src/tools/`）。連線設定見 `mcp/README.md`（用 `acr mcp-setup`）。 +> 註：所有工具一律 `arcrun_*` 前綴（見 `mcp/src/tools/`）。連線設定見 `mcp/README.md`（用 `acr mcp-setup`）。 --- @@ -23,7 +22,7 @@ ## 核心概念：三元組（Triplet） -u6u 的一切都建立在「三元組」上。三元組是描述業務邏輯的最小單位，格式極度簡單，AI 不會出錯，人也能一眼看懂。 +Arcrun 的一切都建立在「三元組」上。三元組是描述業務邏輯的最小單位，格式極度簡單，AI 不會出錯，人也能一眼看懂。 ### 格式 @@ -55,7 +54,7 @@ system sends telegram-notification ### 為什麼這麼簡單？ -因為 AI 擅長理解意圖，三元組擅長表達意圖。你跟 AI 說「去抓銀行匯率，用 Telegram 通知我」，AI 把它拆成三元組，u6u 查零件庫、組裝、執行。第一次需要 AI，之後自動跑，不再花 Token。 +因為 AI 擅長理解意圖，三元組擅長表達意圖。你跟 AI 說「去抓銀行匯率，用 Telegram 通知我」，AI 把它拆成三元組，Arcrun 查零件庫、組裝、執行。第一次需要 AI，之後自動跑，不再花 Token。 --- @@ -66,13 +65,15 @@ system sends telegram-notification ↓ AI 產出 Workflow_Plan_YAML（每次規劃新專案） ↓ -u6u_search_components（查零件庫） +arcrun_search_components（查零件庫） ↓ -有缺件？→ AI 產出 Component_Plan_YAML → u6u_publish_component +有缺件？→ AI 產出 Component_Plan_YAML → arcrun_publish_component ↓ -u6u_execute_workflow（沙盒測試） +arcrun_validate_yaml（部署前 schema 驗證） ↓ -u6u_deploy_workflow（正式部署） +arcrun_push_workflow（正式部署） + ↓ +arcrun_run_workflow（觸發執行，帶 input） ↓ （選填）建立 tag，為工作流與零件分類 ``` @@ -214,7 +215,7 @@ workflow: ## Component_Plan_YAML 格式 -**產出時機：** 只有當 `u6u_search_components` 回報有缺件時，AI 才會產出此 YAML。不是每次都需要。 +**產出時機：** 只有當 `arcrun_search_components` 回報有缺件時，AI 才會產出此 YAML。不是每次都需要。 ### 格式說明 @@ -325,7 +326,7 @@ components: ### 步驟二：確認零件完整性 -呼叫 `u6u_search_components`，傳入所有 triplet： +呼叫 `arcrun_search_components`，傳入所有 triplet： ```json { @@ -339,38 +340,45 @@ components: 回應會告知哪些零件已存在、哪些缺失。若有缺件，先完成[零件開發流程](#零件component開發流程)。 -### 步驟三：沙盒測試 +### 步驟三：部署前 schema 驗證 ```json -// u6u_execute_workflow +// arcrun_validate_yaml { - "triplets": [ - "system fetches exchange-rate", - "system parses rate-data", - "system sends telegram-notification" - ], - "context": { - "currency_pair": "USD/TWD", - "chat_id": "123456789" - } + "yaml_content": "workflow:\n name: exchange-rate-notify\n ..." } ``` ### 步驟四：正式部署 ```json -// u6u_deploy_workflow +// arcrun_push_workflow { + "api_key": "ak_xxx", "yaml_content": "workflow:\n name: exchange-rate-notify\n ..." } ``` 部署成功後，系統回傳 `workflow_id`，並自動記錄 metadata 至 KBDB。 -### 步驟五：加上 Tag（選填） +### 步驟五：觸發執行 ```json -// u6u_tag_resource +// arcrun_run_workflow — 觸發已部署的 workflow，input 帶進 trigger context +{ + "api_key": "ak_xxx", + "name": "exchange-rate-notify", + "input": { + "currency_pair": "USD/TWD", + "chat_id": "123456789" + } +} +``` + +### 步驟六：加上 Tag（選填） + +```json +// arcrun_tag_resource { "resource_type": "workflow", "resource_id": "wf-abc123", @@ -381,9 +389,8 @@ components: ### 查詢已部署的工作流 ``` -u6u_list_workflows → 列出所有工作流 -u6u_list_workflows(tag=finance) → 按 tag 篩選 -u6u_get_workflow(workflow_id) → 取得特定工作流 metadata +arcrun_list_workflows → 列出所有工作流 +arcrun_get_workflow(name) → 取得特定工作流 metadata ``` --- @@ -392,12 +399,12 @@ u6u_get_workflow(workflow_id) → 取得特定工作流 metadata ### 步驟一：確認缺件 -`u6u_search_components` 回報缺件後，AI 產出 Component_Plan_YAML。存入 `components/` 目錄。 +`arcrun_search_components` 回報缺件後，AI 產出 Component_Plan_YAML。存入 `components/` 目錄。 ### 步驟二：發佈零件 ```json -// u6u_publish_component（API Config 方式） +// arcrun_publish_component（API Config 方式） { "component_id": "system-fetches-exchange-rate", "api_config": { @@ -408,7 +415,7 @@ u6u_get_workflow(workflow_id) → 取得特定工作流 metadata ``` ```json -// u6u_publish_component（Gherkin 方式） +// arcrun_publish_component（Gherkin 方式） { "component_id": "system-sends-confirmation-email", "gherkin": "Feature: 訂單確認信\n Scenario: ..." @@ -418,7 +425,7 @@ u6u_get_workflow(workflow_id) → 取得特定工作流 metadata ### 步驟三：加上 Tag（選填） ```json -// u6u_tag_resource +// arcrun_tag_resource { "resource_type": "component", "resource_id": "system-fetches-exchange-rate", @@ -429,9 +436,9 @@ u6u_get_workflow(workflow_id) → 取得特定工作流 metadata ### 查詢已發佈的零件 ``` -u6u_list_components → 列出所有零件 -u6u_list_components(tag=payment) → 按 tag 篩選 -u6u_get_component(component_id) → 取得特定零件 metadata +arcrun_list_components → 列出所有零件 +arcrun_list_components(tag=payment) → 按 tag 篩選 +arcrun_get_component(component_id) → 取得特定零件 metadata ``` --- @@ -444,19 +451,19 @@ Tag 是用戶自訂的標籤，可附加至工作流或零件，用於分類與 ```json // 建立 tag -// u6u_create_tag +// arcrun_create_tag { "name": "finance", "description": "金融相關" } // 列出所有 tag -// u6u_list_tags（無需參數） +// arcrun_list_tags（無需參數） {} // 刪除 tag（不影響已打上此 tag 的資源關聯） -// u6u_delete_tag +// arcrun_delete_tag { "tag_name": "deprecated-tag" } // 為資源加上 tag -// u6u_tag_resource +// arcrun_tag_resource { "resource_type": "workflow", // 或 "component" "resource_id": "wf-abc123", @@ -464,7 +471,7 @@ Tag 是用戶自訂的標籤，可附加至工作流或零件，用於分類與 } // 移除資源的 tag -// u6u_untag_resource +// arcrun_untag_resource { "resource_type": "component", "resource_id": "system-fetches-exchange-rate", diff --git a/mcp/README.md b/mcp/README.md index ac99203..cd7acb1 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -53,40 +53,41 @@ Claude Code 進此資料夾就連對的 MCP。`acr init` 也會自動順帶跑 | Tool | 說明 | |------|------| -| `u6u_get_component_guide` | **開發新零件前必須先呼叫。** 取得 TinyGo 開發指引，包含白名單 import、禁止行為、contract YAML 範例、本地測試指令。 | -| `u6u_search_components` | 用自然語言語意搜尋零件庫。例如：「查詢 Google Sheets 資料」、「發送 LINE 訊息」。回傳零件清單含 canonical_id、描述、評分。 | -| `u6u_get_component` | 取得指定零件的完整合約（input_schema、output_schema、gherkin_tests、評分統計等）。 | -| `u6u_publish_component` | 提交 TinyGo WASM 零件。需提供 `contract`（合約物件）與 `wasm_base64`（編譯後的 .wasm base64）。Registry 自動執行沙盒驗收。 | +| `arcrun_get_component_guide` | **開發新零件前必須先呼叫。** 取得 TinyGo 開發指引，包含白名單 import、禁止行為、contract YAML 範例、本地測試指令。 | +| `arcrun_search_components` | 用自然語言語意搜尋零件庫。例如：「查詢 Google Sheets 資料」、「發送 LINE 訊息」。回傳零件清單含 canonical_id、描述、評分。 | +| `arcrun_get_component` | 取得指定零件的完整合約（input_schema、output_schema、gherkin_tests、評分統計等）。 | +| `arcrun_publish_component` | 提交 TinyGo WASM 零件。需提供 `contract`（合約物件）與 `wasm_base64`（編譯後的 .wasm base64）。Registry 自動執行沙盒驗收。 | ### 工作流執行 | Tool | 說明 | |------|------| -| `u6u_execute_workflow` | 在沙盒中執行工作流。輸入 `triplets`（三元組陣列）與 `context`，用於部署前驗證。 | -| `u6u_deploy_workflow` | 將工作流 YAML 部署至雲端引擎。輸入 `yaml_content`。 | +| `arcrun_validate_yaml` | 部署前驗證工作流 YAML 的 schema。輸入 `yaml_content`。 | +| `arcrun_push_workflow` | 將工作流 YAML 部署至雲端引擎。輸入 `api_key` 與 `yaml_content`。 | +| `arcrun_run_workflow` | 觸發已部署的工作流執行。輸入 `api_key`、`name`，選填 `input`（帶進 trigger context）。 | ### 工作流管理 | Tool | 說明 | |------|------| -| `u6u_list_workflows` | 列出已部署的工作流。可傳入選填的 `tag` 參數篩選。 | -| `u6u_get_workflow` | 取得指定工作流的 metadata。輸入 `workflow_id`。 | +| `arcrun_list_workflows` | 列出已部署的工作流。可傳入選填的 `tag` 參數篩選。 | +| `arcrun_get_workflow` | 取得指定工作流的 metadata。輸入 `name`。 | ### 零件管理 | Tool | 說明 | |------|------| -| `u6u_list_components` | 列出已發佈的零件。可傳入選填的 `tag` 參數篩選。 | +| `arcrun_list_components` | 列出已發佈的零件。可傳入選填的 `tag` 參數篩選。 | ### Tag 管理 | Tool | 說明 | |------|------| -| `u6u_create_tag` | 建立新 tag。輸入 `name`（必填）與 `description`（選填）。 | -| `u6u_list_tags` | 列出當前命名空間下所有 tag。 | -| `u6u_delete_tag` | 刪除指定 tag。輸入 `tag_name`。 | -| `u6u_tag_resource` | 為工作流或零件加上 tag。輸入 `resource_type`、`resource_id`、`tag_name`。 | -| `u6u_untag_resource` | 移除工作流或零件的 tag。 | +| `arcrun_create_tag` | 建立新 tag。輸入 `name`（必填）與 `description`（選填）。 | +| `arcrun_list_tags` | 列出當前命名空間下所有 tag。 | +| `arcrun_delete_tag` | 刪除指定 tag。輸入 `tag_name`。 | +| `arcrun_tag_resource` | 為工作流或零件加上 tag。輸入 `resource_type`、`resource_id`、`tag_name`。 | +| `arcrun_untag_resource` | 移除工作流或零件的 tag。 | --- @@ -97,7 +98,7 @@ Arcrun 的零件是 TinyGo 編譯的 `.wasm`，透過 stdin/stdout JSON 通訊 ### 步驟一：取得開發指引 ``` -u6u_get_component_guide +arcrun_get_component_guide ``` 指引包含：TinyGo 白名單 import、禁止行為、`component.contract.yaml` 完整範例、本地測試指令。 @@ -105,7 +106,7 @@ u6u_get_component_guide ### 步驟二：搜尋現有零件 ``` -u6u_search_components("查詢 Google Sheets 資料") +arcrun_search_components("查詢 Google Sheets 資料") ``` 若已有符合的零件，直接使用，不需要重新開發。 @@ -137,7 +138,7 @@ echo '{"input_field":"value"}' | wasmtime my_component.wasm ### 步驟四：提交零件 ``` -u6u_publish_component( +arcrun_publish_component( contract={...}, // component.contract.yaml 內容 wasm_base64="..." // base64(my_component.wasm) ) @@ -152,23 +153,26 @@ Registry 自動執行沙盒驗收（體積、syscall 掃描、Gherkin 測試） ### 步驟一：搜尋零件 ``` -u6u_search_components("查詢匯率") -u6u_search_components("發送 Telegram 訊息") +arcrun_search_components("查詢匯率") +arcrun_search_components("發送 Telegram 訊息") ``` -### 步驟二：沙盒測試 +### 步驟二：部署前驗證 ``` -u6u_execute_workflow( - triplets=["system >> 查詢匯率 >> get-exchange-rate", ...], - context={"currency_pair": "USD/TWD"} -) +arcrun_validate_yaml(yaml_content="...") ``` ### 步驟三：部署 ``` -u6u_deploy_workflow(yaml_content="...") +arcrun_push_workflow(api_key="ak_xxx", yaml_content="...") +``` + +### 步驟四：觸發執行 + +``` +arcrun_run_workflow(api_key="ak_xxx", name="exchange-rate-notify", input={"currency_pair": "USD/TWD"}) ``` --- diff --git a/mcp/src/brand.ts b/mcp/src/brand.ts index 1b600bb..3ae4ac8 100644 --- a/mcp/src/brand.ts +++ b/mcp/src/brand.ts @@ -12,8 +12,10 @@ * * 語意後綴（push_workflow / list_tags …）保留可讀，只有「品牌前綴」被變數化。 * - * 可用環境變數 ARCRUN_TOOL_PREFIX 覆蓋（測試 / 未來 rebrand 過渡用），預設 "arcrun"。 - * （Workers runtime 無 process 全域，故用 globalThis 安全取值，取不到就 fallback。） + * 前綴預設 "arcrun"。內部另留一個 rebrand 過渡 / 單元測試用的覆蓋鉤子 + * （ARCRUN_TOOL_PREFIX，經 globalThis.process 安全取值）——但 Cloudflare + * Workers runtime 沒有 process 全域，部署後此覆蓋「基本不生效」、一律 fallback 到 + * "arcrun"。**這不是對外 / 用戶可用特性，勿寫進對外文件**；正式 rebrand 請直接改本檔預設值。 */ const envPrefix = (globalThis as { process?: { env?: Record } })