Arcrun/mcp/GUIDE.md

u6u 開發指南

u6u 是 AI 優先（AI-First） 的工作流自動化平台。 跟 AI 描述你的意圖，u6u 幫你把它變成可重複執行、不需要 AI 的自動化工作流。

---

目錄

1. 核心概念：三元組（Triplet）
2. 開發流程總覽
3. 建議的專案檔案結構
4. Workflow_Plan_YAML 格式
5. Component_Plan_YAML 格式
6. 工作流（Workflow）部署流程
7. 零件（Component）開發流程
8. 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

# 環境變數（含 API Key，絕對不能 commit）
.env
.env.*
!.env.example

# IDE 內部規劃檔案（非產品程式碼）
.kiro/

# 其他常見
node_modules/
dist/
.DS_Store

---

Workflow_Plan_YAML 格式

產出時機： 每次你向 AI 描述新的業務需求，AI 就會在對話中輸出此 YAML。將它存入 workflows/ 目錄。

格式說明

workflow:
  name: <工作流名稱，kebab-case>
  description: <業務目的說明>
  version: "1.0.0"
  tags:
    - <tag 名稱（選填）>

  triplets:
    - subject: <執行者>
      predicate: <動作>
      object: <對象>
      description: <此步驟說明（選填）>

  context_schema:
    <key>: <type>   # 工作流執行時需要的輸入參數

完整範例：匯率通知

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

完整範例：結帳流程

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。不是每次都需要。

格式說明

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 <預期結果>

完整範例

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：

{
  "triplets": [
    "system fetches exchange-rate",
    "system parses rate-data",
    "system sends telegram-notification"
  ]
}

回應會告知哪些零件已存在、哪些缺失。若有缺件，先完成零件開發流程。

步驟三：沙盒測試

// u6u_execute_workflow
{
  "triplets": [
    "system fetches exchange-rate",
    "system parses rate-data",
    "system sends telegram-notification"
  ],
  "context": {
    "currency_pair": "USD/TWD",
    "chat_id": "123456789"
  }
}

步驟四：正式部署

// u6u_deploy_workflow
{
  "yaml_content": "workflow:\n  name: exchange-rate-notify\n  ..."
}

部署成功後，系統回傳 workflow_id，並自動記錄 metadata 至 KBDB。

步驟五：加上 Tag（選填）

// 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/ 目錄。

步驟二：發佈零件

// u6u_publish_component（API Config 方式）
{
  "component_id": "system-fetches-exchange-rate",
  "api_config": {
    "method": "GET",
    "url": "https://api.exchangerate.host/latest"
  }
}

// u6u_publish_component（Gherkin 方式）
{
  "component_id": "system-sends-confirmation-email",
  "gherkin": "Feature: 訂單確認信\n  Scenario: ..."
}

步驟三：加上 Tag（選填）

// 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 操作

// 建立 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