Arcrun/mcp/GUIDE.md

# u6u 開發指南

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

---

## 目錄

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