u6u-partner-guide_1774963267888

u6u Partner Developer Guide — 零件宇宙開發者指南
- 版本：1.0 | 更新：2026-03-27 | 適用對象：外部開發者、整合夥伴
- 本文件使用以下變數，實際值請參考官方通知
  - {BASE_URL} — 工作流執行 API（暫用 https://workflow.finally.click）
  - {REGISTRY_URL} — 零件倉庫 API（暫用 https://registry.finally.click）
- 快速開始
  - u6u 是什麼
    - u6u 是一個以**語義圖（semantic graph）**驅動的工作流引擎
    - 你用自然語言描述「誰完成後做什麼」，u6u 自動找到對應的執行單元（零件），串接成可運行的工作流
    - 不需要設定複雜節點編輯器，也不需要手寫 YAML pipeline——你只需要描述業務邏輯
  - 什麼是零件（Component）
    - 零件是工作流的最小執行單元
    - 每個零件是一個 HTTPS endpoint，接收 POST 請求（帶 JSON body），做一件事，回傳 JSON 結果
    - 例子
      - 發送 Telegram 訊息 — 接收文字，透過 Telegram Bot 送出
      - 呼叫 HTTP API — 接收 URL 和 headers，回傳 response body
      - AI 摘要 — 接收長文本，回傳摘要段落
      - 寫入 Google Sheets — 接收列資料，附加到試算表
    - 零件來源
      - u6u 內建零件（例如 telegram、http-request、filter）
      - 你自己建立並發布到零件宇宙的自定義零件
      - 其他夥伴發布的零件
  - 五步上路
    - 1. Design — 用 >> 語法或 GUI 描述工作流
    - 1. Search — 搜尋現有零件，找出缺口
    - 1. Build — 建立缺少的零件（任意 HTTPS endpoint）
    - 1. Test — 發布前 u6u 自動驗證
    - 1. Publish — 零件上架零件宇宙，全平台可用
- 語義開發三種方式
  - 三種方式最終都轉換成相同的語義三元組（triplets），透過相同的 API 執行
  - Mode A — Code：直接寫 >> 語法
    - 基本語法：零件A >> 關係 >> 零件B
    - 關係類型
      - 完成後 — 零件A 成功回傳後
      - 失敗時 — 零件A 拋出錯誤時
      - 對每個 — 零件A 回傳陣列，對每個元素執行
      - 條件滿足時 — context 中特定條件為 true 時
    - 範例
      - HTTP請求 >> 完成後 >> 解析JSON >> 完成後 >> 發送Telegram
      - 讀取RSS >> 完成後 >> 過濾新文章 >> 對每個 >> AI摘要 >> 完成後 >> 寫入GoogleSheets
      - 監控API >> 完成後 >> 判斷狀態異常 >> 條件滿足時 >> 發送警報 >> 失敗時 >> 記錄錯誤
  - Mode B — GUI：拖拉節點視覺設計
    - 在 u6u canvas 上操作
      - 拖入節點，用自然語言寫節點名稱（例如「取得最新 GitHub PR」）
      - 連接節點，在連線上標記關係（完成後、失敗時等）
      - 完成後送出，系統自動轉換為三元組
    - GUI 設計原則
      - 每個節點代表一個業務動作，而非技術細節
      - 連線上的文字決定觸發條件
      - 節點名稱會用於語義搜尋匹配最適合的零件
  - Mode C — AI 對話：描述需求，AI 生成結構
    - 直接用自然語言告訴 AI 你想做什麼
      - 例：「我想要：當 GitHub PR 被合併時，自動用 AI 寫摘要，然後發到 Telegram 群組」
    - AI 會產生對應的三元組或 GUI 結構，你確認後直接執行
  - 三種方式都走同一條路（設計完後）
    - 步驟 1：搜尋零件
      - POST {BASE_URL}/cypher/search Content-Type: application/json { "triplets": [ "GitHub Webhook >> 完成後 >> 過濾PR合併事件", "過濾PR合併事件 >> 條件滿足時 >> AI摘要", "AI摘要 >> 完成後 >> 發送Telegram" ] }
      - 回傳 { nodes, missing, cypher }，missing 是尚未存在零件的清單
    - 步驟 2：填補缺口
      - missing 清單中的零件尚未在零件宇宙存在，可以
        
        自己建立並發布（見「建立零件」、「發布零件」）
        
        請 AI 自動生成 prototype
        
        等待其他夥伴貢獻
    - 步驟 3：執行工作流
      - POST {BASE_URL}/cypher/execute Content-Type: application/json { "triplets": ["..."], "context": { "repo": "my-org/my-repo", "pr_number": 42 } }
- 零件搜尋
  - 語義搜尋（透過三元組）
    - 用三元組描述工作流時，系統自動比對語意相近的零件
    - POST {BASE_URL}/cypher/search { "triplets": ["http請求 >> 完成後 >> 發送Telegram"] }
    - 若 missing 非空，代表這些節點對應的零件尚未在宇宙中存在，需要補建
  - 關鍵字搜尋
    - GET {REGISTRY_URL}/components/search?query=telegram
  - 取得零件完整說明
    - GET {REGISTRY_URL}/components/guide
    - 回傳所有內建零件的完整說明、input/output schema 範例，無需認證
  - 零件分類（五大類）
    - Trigger 零件（工作流入口）
      - 啟動整個工作流，負責接收外部事件並轉換為 context
      - webhook — 被動接收 POST，適合 GitHub、Stripe、LINE 等有 Webhook 支援的服務
      - http-poll — 定期輪詢 API，比較前後結果，有變化才繼續
      - line-bot-incoming — 接收 LINE Bot 訊息
      - telegram-incoming — 接收 Telegram Bot 訊息
    - 流程控制零件
      - filter — 根據條件決定是否繼續執行
      - switch — 多條件分支，類似 switch-case
      - merge — 等待多個並行分支全部完成
      - wait — 延遲執行，等待指定時間
    - 數據處理零件
      - set — 在 context 中設定或修改變數
      - http-request — 呼叫任意 HTTP API
    - 外部整合零件
      - telegram — 發送 Telegram 訊息
      - line-notify — 發送 LINE 通知
      - gmail — 發送 Gmail 郵件
      - google-sheets — 讀寫 Google Sheets
    - 知識操作零件
      - kbdb_search — 語意搜尋知識庫
      - kbdb_write_triplet — 寫入知識圖譜三元組
- 建立零件
  - 零件的本質
    - 一個零件就是一個你已經有的 API endpoint
    - 不需要學任何新技術——只要你的 API 能接收 POST JSON、回傳 JSON，就可以發布成零件
    - 你的 API 可以是：現有後端的某個 endpoint、Cloud Function、任何線上服務的 wrapper
  - 零件需要符合的規格
    - 接收：HTTP POST，body 是 JSON 物件（工作流傳入的 context）
    - 回傳：JSON 物件，內容會合併進 context 供下游零件使用
    - 錯誤：回傳 HTTP 4xx / 5xx，不要回傳 { "success": false } 類型的 200（u6u 用 status code 判斷走向 失敗時 分支）
    - context 範例（你的 endpoint 會收到這樣的 body）
      - { "text": "這是一篇很長的文章...", "max_length": 150 }
    - 回傳範例
      - { "summary": "文章摘要：...", "tokens_used": 342 }
  - 必要欄位（發布時需要）
    - name — 零件唯一識別名稱（例如 ai-summarize）
    - url — 你的 API endpoint（HTTPS）
    - method — HTTP method（通常為 POST）
    - description — 零件功能描述，影響語意搜尋的準確度，請寫清楚
    - 選填：input_schema、output_schema（JSON Schema 格式，填了之後 AI 可以自動組裝工作流）
- 發布零件
  - 取得 API Key
    - 發布零件前，需要向 InkStone 申請 API Key（格式：u6u_xxxxxxxxxxxxxxxx）
    - 申請方式見「API Key 申請」
    - 取得後，你就可以將零件發布到零件宇宙，對所有 u6u 使用者開放
  - 發布 API
    - POST {REGISTRY_URL}/components/publish X-Api-Key: u6u_xxxxxxxxxxxxxxxx Content-Type: application/json { "name": "ai-summarize", "url": "https://my-ai-summarize.your-subdomain.workers.dev", "method": "POST", "description": "使用 AI 將長文本摘要為指定字數以內的段落", "input_schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "description": "要摘要的原始文字" }, "max_length": { "type": "integer", "description": "摘要最大字數" } } }, "output_schema": { "type": "object", "properties": { "summary": { "type": "string" }, "tokens_used": { "type": "integer" } } } }
  - 驗證流程
    - 發布時，系統會自動驗證你的零件是否正常運作
      - 系統呼叫你的 component URL，帶入測試用空 context {}
      - 回傳有效 JSON → 標記為已發布，201 Created，上架零件宇宙 ✅
      - 回傳錯誤或逾時 → 回傳 422，開發者修復後重試
    - 重複發布同名零件 → 409 Conflict
  - 發布後
    - 出現在語意搜尋結果中
    - 其他 u6u 工作流可以引用你的零件
    - 你的組織 tag（org:your-org-id）跟隨零件，確保可追溯
    - 如需更新邏輯，直接更新你的 endpoint，無需重新發布（URL 不變時）
- Trigger 設計
  - Trigger 是什麼
    - Trigger 是工作流的入口點，負責將外部事件轉換為 context，然後啟動工作流
    - 一個工作流只有一個 Trigger，但可以有多個 Trigger 類型
  - Trigger 類型總覽
    - Webhook Trigger
      - 適用場景：對方支援 Webhook，外部事件主動推送進來
      - 例子：GitHub push、Stripe 付款、LINE 訊息、表單送出
    - HTTP Poll Trigger
      - 適用場景：對方沒有 Webhook，需要定期去拉取資料
      - 例子：Gmail 新信、RSS 更新、API 資料輪詢
      - 原理：u6u 定期呼叫你指定的 API，比較前後結果，有變化才觸發工作流
    - Manual Trigger
      - 適用場景：開發測試、手動執行、一次性任務
      - 直接 POST 到 webhook_url 觸發
    - Scheduled Trigger
      - 適用場景：定時自動執行，不需要外部觸發
      - 例子：每日報表、每小時同步、定期清理
  - Webhook Trigger：將工作流註冊為 Webhook
    - 步驟 1：把工作流轉換為 Webhook
      - POST {BASE_URL}/webhooks Content-Type: application/json { "name": "github-pr-summary", "triplets": [ "過濾PR合併事件 >> 條件滿足時 >> 取得PR詳情", "取得PR詳情 >> 完成後 >> AI摘要", "AI摘要 >> 完成後 >> 發送Telegram" ], "context": { "telegram_chat_id": "-1001234567890" } }
      - 回應：{ "webhook_url": "https://.../webhooks/wh_abc123/trigger" }
    - 步驟 2：將 webhook_url 設定到外部服務
      - 以 GitHub 為例：Settings → Webhooks → Add webhook → Payload URL 填入 webhook_url
    - 步驟 3：手動測試觸發
      - POST .../webhooks/wh_abc123/trigger Content-Type: application/json { "action": "closed", "pull_request": { "merged": true, "title": "..." } }
  - HTTP Poll Trigger：輪詢沒有 Webhook 的服務
    - 在 u6u 工作流中加入一個 http-poll 節點，設定
      - url — 要輪詢的 API endpoint
      - interval — 輪詢頻率（例如 */10 * * * * 每 10 分鐘）
      - compare_field — 用來比較是否有變化的欄位（選填）
    - u6u 自動處理：定期呼叫、比較、有變化才往下執行
    - 你不需要自己處理排程邏輯
  - Scheduled Trigger：純定時任務
    - 建立工作流時指定 schedule（cron 格式），u6u 自動定時觸發
    - 例：每天早上 9 點執行 → "schedule": "0 9 * * *"
- 工作流管理
  - 查詢已註冊的 Webhook
    - GET {BASE_URL}/webhooks/:token
    - 回應：{ token, name, triplets, created_at, last_triggered }
  - 執行歷史
    - 工作流每次執行後，結果自動記錄，可透過 GET /webhooks/:token 查看 last_triggered 和執行狀態
  - 管理建議
    - 使用有意義的 name（例如 github-pr-summary、daily-report）方便識別
    - 在 context 中預先設定工作流所需的常數（例如 telegram_chat_id）
    - 工作流更新時，先用 Manual Trigger 測試，確認正常再接上真實事件來源
- 完整範例：GitHub PR 合併 → AI 摘要 → 發 Telegram
  - 步驟 1：設計工作流（>> 語法）
    - ```
    GitHub Webhook
      >> 完成後 >>
    過濾PR合併事件
      >> 條件滿足時 >>
    HTTP請求取PR詳情
      >> 完成後 >>
    AI摘要
      >> 完成後 >>
    發送Telegram
```
- 步驟 2：搜尋零件，找出缺口
  - POST .../cypher/search { "triplets": [ "GitHub Webhook >> 完成後 >> 過濾PR合併事件", "過濾PR合併事件 >> 條件滿足時 >> HTTP請求取PR詳情", "HTTP請求取PR詳情 >> 完成後 >> AI摘要", "AI摘要 >> 完成後 >> 發送Telegram" ] }
  - 結果：filter ✅、http-request ✅、telegram ✅ 內建可用
  - missing: ["GitHub Webhook", "AI摘要"]
    - GitHub Webhook — Trigger 型，直接用 /webhooks API 處理，不需要發布為零件
    - AI摘要 — 需要自己建立
- 步驟 3：建立 AI摘要 零件
  - 你需要一個 HTTPS endpoint，接收 { title, body }，回傳 { summary, message }
  - 用任何你熟悉的語言/平台實作都可以，只要符合零件規格（接收 POST JSON，回傳 JSON）
  - 部署後取得 URL，例如 https://my-ai-summarize.example.com/summarize
- 步驟 4：發布 AI摘要 零件
  - POST {REGISTRY_URL}/components/publish X-Api-Key: u6u_xxxxxxxxxxxxxxxx { "name": "ai-pr-summarize", "url": "https://ai-pr-summarize.your-subdomain.workers.dev", "method": "POST", "description": "使用 AI 為 GitHub PR 生成繁體中文摘要，輸出適合 Telegram 的格式", "input_schema": { "required": ["title"], "properties": { "title": { "type": "string" }, "body": { "type": "string" } } }, "output_schema": { "properties": { "summary": { "type": "string" }, "message": { "type": "string" } } } }
  - 系統驗證通過後，回傳 { "id": "ai-pr-summarize", "published": true }
- 步驟 5：將工作流註冊為 Webhook
  - POST .../webhooks { "name": "github-pr-summary", "triplets": [ "過濾PR合併事件 >> 條件滿足時 >> HTTP請求取PR詳情", "HTTP請求取PR詳情 >> 完成後 >> ai-pr-summarize", "ai-pr-summarize >> 完成後 >> telegram" ], "context": { "github_token": "ghp_xxxx", "telegram_chat_id": "-1001234567890", "telegram_bot_token": "123456:ABC-DEF..." } }
  - 回應：{ "webhook_url": "https://.../webhooks/wh_abc123/trigger" }
- 步驟 6：在 GitHub 設定 Webhook
  - 前往目標 Repo → Settings → Webhooks → Add webhook
  - Payload URL：填入 webhook_url
  - Content type：application/json
  - Which events：選 Pull requests
- 步驟 7：驗證
  - POST .../webhooks/wh_abc123/trigger { "action": "closed", "pull_request": { "merged": true, "number": 42, "title": "feat: 新增深色模式", "body": "實作整站深色模式切換功能" } }
  - 幾秒後 Telegram 群組收到：「PR 合併通知 / feat: 新增深色模式 / 這個 PR 為應用程式新增了深色模式支援…」
- API Key 申請
  - API Key 是什麼
    - 格式：u6u_xxxxxxxxxxxxxxxx
    - 讓你可以將自建零件發布到零件宇宙，對所有 u6u 用戶開放
    - 你發布的零件自動標記你的組織 ID，方便管理和版本追蹤
  - 如何申請
    - 發送申請到：[email protected]
    - 附上
      - 組織名稱
      - 聯絡人姓名與職稱
      - 預計建立的零件類型（簡短描述即可）
      - 技術聯絡信箱
    - 通常 1-3 個工作天內收到回覆
  - 注意事項
    - API Key 只用於 X-Api-Key header
    - 請勿將 API Key 提交到公開版本控制系統
    - 如需輪換或撤銷，聯繫同一信箱
- API 參考
  - 工作流執行
    - POST /cypher/search
      - Host：{BASE_URL}
      - 搜尋三元組對應的零件，確認零件是否存在
      - Request：{ "triplets": ["零件A >> 關係 >> 零件B"] }
      - Response：{ "nodes": {...}, "missing": [...], "cypher": "..." }
    - POST /cypher/execute
      - Host：{BASE_URL}
      - 執行工作流（一次性）
      - Request：{ "triplets": [...], "context": { "key": "value" } }
      - Response：{ "result": {...}, "execution_id": "exec_abc123", "steps_completed": 3 }
  - 零件管理
    - GET /components/guide
      - Host：{REGISTRY_URL}
      - 取得所有內建零件的說明與 schema，無需認證
    - GET /components/search?query=xxx
      - Host：{REGISTRY_URL}
      - 關鍵字或語意搜尋零件
      - Query params：query（搜尋關鍵字）、tag（按 tag 過濾）、limit（預設 20）
    - POST /components/publish
      - Host：{REGISTRY_URL}
      - Header：X-Api-Key: u6u_xxxxxxxxxxxxxxxx
      - 發布零件到零件宇宙
      - Request：{ name, url, method, description, input_schema?, output_schema? }
      - Status codes
        
        201 Created — 發布成功
        
        400 Bad Request — 缺少必要欄位
        
        401 Unauthorized — API Key 無效或缺少
        
        409 Conflict — 同名零件已存在
        
        422 Unprocessable Entity — 零件驗證失敗（endpoint 無法正常回應）
  - Webhook 管理
    - POST /webhooks
      - Host：{BASE_URL}
      - 將工作流註冊為 Webhook，取得可供外部服務呼叫的 URL
      - Request：{ "name": "my-workflow", "triplets": [...], "context": {...} }
      - Response：{ "token": "wh_abc123", "webhook_url": "...", "name": "...", "created_at": "..." }
    - POST /webhooks/:token/trigger
      - Host：{BASE_URL}
      - 觸發已註冊的 Webhook 工作流
      - Request body：任意 JSON，內容會合併進工作流的初始 context
      - Response：{ "execution_id": "exec_xyz789", "status": "started" }
    - GET /webhooks/:token
      - Host：{BASE_URL}
      - 查詢已註冊 Webhook 的詳情與狀態
      - Response：{ token, name, triplets, created_at, last_triggered }

探索

u6u-partner-guide_1774963267888_0

關係圖譜