uncle6me-web
772e4a12ff
- README：CLI 指令補 acr mcp-setup + acr config --where；新增「讓 AI 連到對的 arcrun」MCP 章節 - mcp/README：更新連線設定（acr mcp-setup 為主）、URL studio/finally.click → mcp.arcrun.dev、 移除 pk_live 邀請制框架、inspector URL 更新 - mcp/GUIDE：標題 u6u → Arcrun，註明 u6u_/arcrun_ 工具現況 - llms.txt：token 權限三組 → 兩組（移除已廢的 R2 Edit）；init 流程補「寫 .mcp.json」 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
481 lines
12 KiB
Markdown
481 lines
12 KiB
Markdown
# Arcrun MCP 開發指南
|
||
|
||
> Arcrun 是 **AI 優先（AI-First）** 的工作流自動化平台。
|
||
> 跟 AI 描述你的意圖，Arcrun 幫你把它變成可重複執行、不需要 AI 的自動化工作流。
|
||
>
|
||
> 註：本指南部分工具仍以舊 `u6u_` 前綴記載（registry/component 管理那組）；現役 workflow 工具是
|
||
> `arcrun_*`（見 `mcp/src/tools/`）。連線設定見 `mcp/README.md`（用 `acr mcp-setup`）。
|
||
|
||
---
|
||
|
||
## 目錄
|
||
|
||
1. [核心概念：三元組（Triplet）](#核心概念三元組triplet)
|
||
2. [開發流程總覽](#開發流程總覽)
|
||
3. [建議的專案檔案結構](#建議的專案檔案結構)
|
||
4. [Workflow_Plan_YAML 格式](#workflow_plan_yaml-格式)
|
||
5. [Component_Plan_YAML 格式](#component_plan_yaml-格式)
|
||
6. [工作流（Workflow）部署流程](#工作流workflow部署流程)
|
||
7. [零件（Component）開發流程](#零件component開發流程)
|
||
8. [Tag 管理說明](#tag-管理說明)
|
||
|
||
---
|
||
|
||
## 核心概念：三元組（Triplet）
|
||
|
||
u6u 的一切都建立在「三元組」上。三元組是描述業務邏輯的最小單位，格式極度簡單，AI 不會出錯，人也能一眼看懂。
|
||
|
||
### 格式
|
||
|
||
```
|
||
subject predicate object
|
||
```
|
||
|
||
| 部分 | 說明 | 範例 |
|
||
|------|------|------|
|
||
| `subject` | 執行者（誰） | `user`、`system`、`payment-service` |
|
||
| `predicate` | 動作（做什麼） | `submits`、`validates`、`sends` |
|
||
| `object` | 對象（對什麼） | `form`、`input`、`email` |
|
||
|
||
### 命名規則
|
||
|
||
- 全部小寫，單字以連字號（`-`）連接
|
||
- predicate 用動詞原形
|
||
- 避免縮寫，語意要清楚
|
||
|
||
### 範例：匯率通知工作流
|
||
|
||
```
|
||
system fetches exchange-rate
|
||
system parses rate-data
|
||
system sends telegram-notification
|
||
```
|
||
|
||
三個 triplet，三個動作，串起來就是一個完整的工作流。每個 triplet 對應一個**零件（component）**，零件負責實作那個動作的具體邏輯。
|
||
|
||
### 為什麼這麼簡單？
|
||
|
||
因為 AI 擅長理解意圖，三元組擅長表達意圖。你跟 AI 說「去抓銀行匯率，用 Telegram 通知我」，AI 把它拆成三元組，u6u 查零件庫、組裝、執行。第一次需要 AI，之後自動跑，不再花 Token。
|
||
|
||
---
|
||
|
||
## 開發流程總覽
|
||
|
||
```
|
||
你的意圖
|
||
↓
|
||
AI 產出 Workflow_Plan_YAML（每次規劃新專案）
|
||
↓
|
||
u6u_search_components（查零件庫）
|
||
↓
|
||
有缺件？→ AI 產出 Component_Plan_YAML → u6u_publish_component
|
||
↓
|
||
u6u_execute_workflow（沙盒測試）
|
||
↓
|
||
u6u_deploy_workflow（正式部署）
|
||
↓
|
||
（選填）建立 tag，為工作流與零件分類
|
||
```
|
||
|
||
**重要原則：**
|
||
- Workflow_Plan_YAML 和 Component_Plan_YAML 由 AI 輸出在對話中，**你自行存入本地 repo**
|
||
- MCP Server 不儲存 YAML 全文，只記錄部署成功後的 metadata（ID、名稱、時間）
|
||
- YAML 是你的原始碼，用 Git 管理
|
||
|
||
---
|
||
|
||
## 建議的專案檔案結構
|
||
|
||
```
|
||
your-project/
|
||
├── workflows/ # 工作流 YAML（Workflow_Plan_YAML）
|
||
│ ├── exchange-rate-notify.yaml
|
||
│ └── user-checkout-flow.yaml
|
||
│
|
||
├── components/ # 零件 YAML（Component_Plan_YAML，只在有缺件時才有）
|
||
│ ├── system-fetches-exchange-rate.yaml
|
||
│ └── system-sends-telegram-notification.yaml
|
||
│
|
||
├── .gitignore # 建議加入下方的 ignore 項目
|
||
└── README.md
|
||
```
|
||
|
||
### 建議的 `.gitignore`
|
||
|
||
```gitignore
|
||
# 環境變數（含 API Key，絕對不能 commit）
|
||
.env
|
||
.env.*
|
||
!.env.example
|
||
|
||
# IDE 內部規劃檔案（非產品程式碼）
|
||
.kiro/
|
||
|
||
# 其他常見
|
||
node_modules/
|
||
dist/
|
||
.DS_Store
|
||
```
|
||
|
||
---
|
||
|
||
## Workflow_Plan_YAML 格式
|
||
|
||
**產出時機：** 每次你向 AI 描述新的業務需求，AI 就會在對話中輸出此 YAML。將它存入 `workflows/` 目錄。
|
||
|
||
### 格式說明
|
||
|
||
```yaml
|
||
workflow:
|
||
name: <工作流名稱，kebab-case>
|
||
description: <業務目的說明>
|
||
version: "1.0.0"
|
||
tags:
|
||
- <tag 名稱（選填）>
|
||
|
||
triplets:
|
||
- subject: <執行者>
|
||
predicate: <動作>
|
||
object: <對象>
|
||
description: <此步驟說明（選填）>
|
||
|
||
context_schema:
|
||
<key>: <type> # 工作流執行時需要的輸入參數
|
||
```
|
||
|
||
### 完整範例：匯率通知
|
||
|
||
```yaml
|
||
workflow:
|
||
name: exchange-rate-notify
|
||
description: 每日抓取銀行匯率，透過 Telegram 通知用戶
|
||
version: "1.0.0"
|
||
tags:
|
||
- notification
|
||
- finance
|
||
|
||
triplets:
|
||
- subject: system
|
||
predicate: fetches
|
||
object: exchange-rate
|
||
description: 從銀行 API 取得當日匯率
|
||
- subject: system
|
||
predicate: parses
|
||
object: rate-data
|
||
description: 整理匯率資料格式
|
||
- subject: system
|
||
predicate: sends
|
||
object: telegram-notification
|
||
description: 透過 Telegram Bot 發送通知
|
||
|
||
context_schema:
|
||
currency_pair: string # 例如 "USD/TWD"
|
||
chat_id: string # Telegram chat ID
|
||
```
|
||
|
||
### 完整範例：結帳流程
|
||
|
||
```yaml
|
||
workflow:
|
||
name: user-checkout-flow
|
||
description: 處理使用者結帳，從確認購物車到完成付款
|
||
version: "1.0.0"
|
||
tags:
|
||
- ecommerce
|
||
- payment
|
||
|
||
triplets:
|
||
- subject: user
|
||
predicate: confirms
|
||
object: cart-items
|
||
- subject: system
|
||
predicate: calculates
|
||
object: total-price
|
||
- subject: user
|
||
predicate: submits
|
||
object: payment-info
|
||
- subject: payment-service
|
||
predicate: processes
|
||
object: payment
|
||
- subject: system
|
||
predicate: creates
|
||
object: order-record
|
||
- subject: system
|
||
predicate: sends
|
||
object: confirmation-email
|
||
|
||
context_schema:
|
||
user_id: string
|
||
cart_id: string
|
||
currency: string
|
||
```
|
||
|
||
---
|
||
|
||
## Component_Plan_YAML 格式
|
||
|
||
**產出時機：** 只有當 `u6u_search_components` 回報有缺件時，AI 才會產出此 YAML。不是每次都需要。
|
||
|
||
### 格式說明
|
||
|
||
```yaml
|
||
components:
|
||
- component_id: <零件唯一 ID，kebab-case>
|
||
name: <零件名稱>
|
||
triplet: "<subject> <predicate> <object>"
|
||
description: <零件功能說明，AI 用此進行語意匹配>
|
||
tags:
|
||
- <tag 名稱（選填）>
|
||
|
||
# 選擇其中一種定義方式：
|
||
|
||
# 方式一：API Config（直接呼叫外部 API）
|
||
api_config:
|
||
method: POST
|
||
url: https://api.example.com/endpoint
|
||
headers:
|
||
Content-Type: application/json
|
||
body_template:
|
||
key: "{{context.value}}"
|
||
|
||
# 方式二：Gherkin（行為驅動開發規格，功能型零件使用）
|
||
gherkin: |
|
||
Feature: <功能名稱>
|
||
Scenario: <情境描述>
|
||
Given <前置條件>
|
||
When <觸發動作>
|
||
Then <預期結果>
|
||
```
|
||
|
||
### 完整範例
|
||
|
||
```yaml
|
||
components:
|
||
- component_id: system-fetches-exchange-rate
|
||
name: 系統抓取匯率
|
||
triplet: "system fetches exchange-rate"
|
||
description: 呼叫銀行 API 取得指定貨幣對的當日匯率
|
||
tags:
|
||
- finance
|
||
api_config:
|
||
method: GET
|
||
url: https://api.exchangerate.host/latest
|
||
headers:
|
||
Accept: application/json
|
||
body_template:
|
||
base: "{{context.currency_pair}}"
|
||
|
||
- component_id: system-sends-telegram-notification
|
||
name: 系統發送 Telegram 通知
|
||
triplet: "system sends telegram-notification"
|
||
description: 透過 Telegram Bot API 發送訊息給指定 chat
|
||
tags:
|
||
- notification
|
||
api_config:
|
||
method: POST
|
||
url: https://api.telegram.org/bot{{env.TELEGRAM_BOT_TOKEN}}/sendMessage
|
||
headers:
|
||
Content-Type: application/json
|
||
body_template:
|
||
chat_id: "{{context.chat_id}}"
|
||
text: "{{context.message}}"
|
||
|
||
- component_id: payment-service-processes-payment
|
||
name: 付款服務處理交易
|
||
triplet: "payment-service processes payment"
|
||
description: 呼叫付款閘道 API 處理信用卡交易
|
||
tags:
|
||
- payment
|
||
- ecommerce
|
||
api_config:
|
||
method: POST
|
||
url: https://api.payment-gateway.com/v1/charges
|
||
headers:
|
||
Content-Type: application/json
|
||
Authorization: "Bearer {{env.PAYMENT_API_KEY}}"
|
||
body_template:
|
||
amount: "{{context.total_price}}"
|
||
currency: "{{context.currency}}"
|
||
card_token: "{{context.payment_token}}"
|
||
|
||
- component_id: system-sends-confirmation-email
|
||
name: 系統寄送確認信
|
||
triplet: "system sends confirmation-email"
|
||
description: 透過 Email 服務寄送訂單確認信給使用者
|
||
tags:
|
||
- notification
|
||
- ecommerce
|
||
gherkin: |
|
||
Feature: 訂單確認信
|
||
Scenario: 成功寄送確認信
|
||
Given 訂單已建立，且 context 包含 user_email 與 order_id
|
||
When system sends confirmation-email
|
||
Then Email 服務收到寄信請求
|
||
And 使用者收到包含 order_id 的確認信
|
||
And 回傳 { success: true, message_id: "<id>" }
|
||
```
|
||
|
||
---
|
||
|
||
## 工作流（Workflow）部署流程
|
||
|
||
### 步驟一：取得 Workflow_Plan_YAML
|
||
|
||
向 AI 描述業務需求，AI 輸出 YAML。存入 `workflows/` 目錄。
|
||
|
||
### 步驟二：確認零件完整性
|
||
|
||
呼叫 `u6u_search_components`，傳入所有 triplet：
|
||
|
||
```json
|
||
{
|
||
"triplets": [
|
||
"system fetches exchange-rate",
|
||
"system parses rate-data",
|
||
"system sends telegram-notification"
|
||
]
|
||
}
|
||
```
|
||
|
||
回應會告知哪些零件已存在、哪些缺失。若有缺件，先完成[零件開發流程](#零件component開發流程)。
|
||
|
||
### 步驟三：沙盒測試
|
||
|
||
```json
|
||
// u6u_execute_workflow
|
||
{
|
||
"triplets": [
|
||
"system fetches exchange-rate",
|
||
"system parses rate-data",
|
||
"system sends telegram-notification"
|
||
],
|
||
"context": {
|
||
"currency_pair": "USD/TWD",
|
||
"chat_id": "123456789"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 步驟四：正式部署
|
||
|
||
```json
|
||
// u6u_deploy_workflow
|
||
{
|
||
"yaml_content": "workflow:\n name: exchange-rate-notify\n ..."
|
||
}
|
||
```
|
||
|
||
部署成功後，系統回傳 `workflow_id`，並自動記錄 metadata 至 KBDB。
|
||
|
||
### 步驟五：加上 Tag（選填）
|
||
|
||
```json
|
||
// u6u_tag_resource
|
||
{
|
||
"resource_type": "workflow",
|
||
"resource_id": "wf-abc123",
|
||
"tag_name": "finance"
|
||
}
|
||
```
|
||
|
||
### 查詢已部署的工作流
|
||
|
||
```
|
||
u6u_list_workflows → 列出所有工作流
|
||
u6u_list_workflows(tag=finance) → 按 tag 篩選
|
||
u6u_get_workflow(workflow_id) → 取得特定工作流 metadata
|
||
```
|
||
|
||
---
|
||
|
||
## 零件（Component）開發流程
|
||
|
||
### 步驟一：確認缺件
|
||
|
||
`u6u_search_components` 回報缺件後，AI 產出 Component_Plan_YAML。存入 `components/` 目錄。
|
||
|
||
### 步驟二：發佈零件
|
||
|
||
```json
|
||
// u6u_publish_component（API Config 方式）
|
||
{
|
||
"component_id": "system-fetches-exchange-rate",
|
||
"api_config": {
|
||
"method": "GET",
|
||
"url": "https://api.exchangerate.host/latest"
|
||
}
|
||
}
|
||
```
|
||
|
||
```json
|
||
// u6u_publish_component（Gherkin 方式）
|
||
{
|
||
"component_id": "system-sends-confirmation-email",
|
||
"gherkin": "Feature: 訂單確認信\n Scenario: ..."
|
||
}
|
||
```
|
||
|
||
### 步驟三：加上 Tag（選填）
|
||
|
||
```json
|
||
// u6u_tag_resource
|
||
{
|
||
"resource_type": "component",
|
||
"resource_id": "system-fetches-exchange-rate",
|
||
"tag_name": "finance"
|
||
}
|
||
```
|
||
|
||
### 查詢已發佈的零件
|
||
|
||
```
|
||
u6u_list_components → 列出所有零件
|
||
u6u_list_components(tag=payment) → 按 tag 篩選
|
||
u6u_get_component(component_id) → 取得特定零件 metadata
|
||
```
|
||
|
||
---
|
||
|
||
## Tag 管理說明
|
||
|
||
Tag 是用戶自訂的標籤，可附加至工作流或零件，用於分類與篩選。
|
||
|
||
### Tag 操作
|
||
|
||
```json
|
||
// 建立 tag
|
||
// u6u_create_tag
|
||
{ "name": "finance", "description": "金融相關" }
|
||
|
||
// 列出所有 tag
|
||
// u6u_list_tags（無需參數）
|
||
{}
|
||
|
||
// 刪除 tag（不影響已打上此 tag 的資源關聯）
|
||
// u6u_delete_tag
|
||
{ "tag_name": "deprecated-tag" }
|
||
|
||
// 為資源加上 tag
|
||
// u6u_tag_resource
|
||
{
|
||
"resource_type": "workflow", // 或 "component"
|
||
"resource_id": "wf-abc123",
|
||
"tag_name": "finance"
|
||
}
|
||
|
||
// 移除資源的 tag
|
||
// u6u_untag_resource
|
||
{
|
||
"resource_type": "component",
|
||
"resource_id": "system-fetches-exchange-rate",
|
||
"tag_name": "beta"
|
||
}
|
||
```
|
||
|
||
### Tag 管理建議
|
||
|
||
- 專案開始前先規劃 tag 命名規則，保持一致性
|
||
- 用有意義的名稱（`user-auth` 比 `auth` 好）
|
||
- 同一資源可附加多個 tag，靈活組合篩選
|
||
- 定期清理不再使用的 tag
|