跳轉到主要內容
文件擴充生態模板與模組市場

模板與模組市場

把做好的 workflow 發布成範本或模組並依版本迭代；下載時自動解析依賴，裝完即可實例化使用。

市集是控制台裡的「市集」頁面：社群與官方發布的範本與模組都在這裡。你可以把別人發布的項目下載到自己的範本庫或模組庫，也可以把自己做好的工作流發布上去，按版本迭代。範本下載後實例化成自己的工作流；模組下載後可以直接被 sub_workflow 步驟引用。

瀏覽與分類

列表支援按類型（範本 / 模組）、分類、標籤篩選，也可以按名稱、描述、標籤搜尋。頂部有三個檢視：全部、我上傳的、我下載的。每張卡片顯示作者、最新版本號與下載次數；平台自帶的項目帶「官方」標記。

  • 分類下拉的選項來自目前已上架項目的實際分類，不是固定清單；分類與標籤會按你的介面語言顯示。
  • 市集裡只顯示已上架且對你可見的項目。發布者可以把項目設為公開、僅團隊成員可見或僅指定使用者可見，不可見的項目不會出現在你的列表裡。
  • 已下載過的項目在卡片上直接標出「已下載」；有新版本時按鈕變成「更新」。

發布你的範本或模組

發布入口在工作流編輯器裡。只有工作流的擁有者能把它發布到市集——管理員也不能替你發布首個版本。

  • 類型：帶模組契約的工作流可以按「模組」發布，否則只能按「範本」發布。想以模組形式發布，先在編輯器裡「提升為模組」並儲存契約。
  • 需要填寫標題（必填，最長 200 字元）、簡介（最長 5000 字元）、分類、標籤（最多 20 個）、圖示、版本號與更新說明。
  • 版本號要求 semver 格式，如 1.0.0 或 1.0.0-beta。
  • 可見性三檔：所有使用者可見、僅我加入的團隊成員可見（填團隊 ID）、僅指定使用者可見（填使用者 ID）。選團隊可見時，你必須是所列每個團隊的成員。
  • 價格：目前只支援免費發布（0 USD），付費能力尚未開放。
  • 序列化後的工作流定義上限 2MB，超出會被拒絕。
bash
curl -X POST https://braidrun.com/api/marketplace/items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceWorkflowId": "<workflow-id>",
    "type": "TEMPLATE",
    "title": "竞品价格日报",
    "description": "每天拉取竞品价格并生成对比表",
    "category": "数据分析",
    "tags": ["监控", "报表"],
    "version": "1.0.0",
    "changelog": "首个版本",
    "visibility": "PUBLIC",
    "priceUsdCents": 0
  }'

上傳後項目進入「待審批」狀態，管理員審批通過才會上架。只有已上架的項目會出現在其他使用者的市集列表裡。被駁回時可以在「我上傳的」檢視裡看到駁回原因。

版本管理

同一個工作流不能重複發布成新項目——編輯器會自動辨識「這個工作流已經發布過」，並把對話框切換成「上傳新版本」。

  • 只有項目的原作者可以發布新版本；平台管理員可以代為發布，但項目的作者歸屬不變。系統內建項目只有管理員能發新版本。
  • 新版本號必須是合法 semver，且不能低於目前最新版本。同一版本號不能重複上傳。
  • 新版本同樣進入待審批；審批期間項目本身保持上架，其他使用者下載到的仍是最新的已上架版本。
  • 已下載該項目的使用者會在市集卡片與「我下載的」裡看到更新提示，重新下載即可更新到最新版。
  • 項目詳情頁會列出完整的版本歷史與每個版本的更新說明。

安裝：相依自動解析

點「下載」把項目存進你的範本庫或模組庫。如果這個範本或模組裡引用了其他模組（sub_workflow 步驟），下載前平台會先解析完整的相依圖，逐個標出每個相依的狀態：

狀態含義
已下載你的庫裡已有該模組的最新版，跳過
需更新你下載過舊版本，本次會一併更新到最新版
可下載市集裡有、你還沒下載，本次會一併下載
缺失市集裡找不到同名模組
不可見模組存在，但被限定為你不在其中的團隊或使用者可見

確認「連同相依一起下載」後，安裝按相依順序進行：先裝最底層被引用的模組，逐層向上，最後裝你點的項目本身。下載過程中，副本裡 sub_workflow 引用的 workflow_id 會自動改寫成你庫中對應副本的 ID——裝完不需要手動改任何引用，範本可以直接實例化執行，模組可以直接被引用。

bash
# 下载最新版，连同依赖一起（返回本次创建的全部下载记录）
curl -X POST "https://braidrun.com/api/marketplace/items/<item-id>/download?withDependencies=true" \
  -H "Authorization: Bearer <token>"

# 下载指定历史版本（只下载该条目本身，不做依赖级联）
curl -X POST "https://braidrun.com/api/marketplace/items/<item-id>/download?version=1.2.0" \
  -H "Authorization: Bearer <token>"
  • 相依解析只在下載最新版時進行；指定歷史版本下載時只下載該項目本身。
  • 循環引用（A 引用 B、B 又引用 A）會被辨識並正常處理，不會卡死安裝。
  • 下載本身不占用工作流配額，後面的實例化才占。

相依顯示「缺失」或「不可見」時，父項目仍然可以裝進庫裡，但對應的 sub_workflow 步驟無法執行，直到該模組被發布出來或對你可見。下載確認框會明確列出這些缺口。

下載之後：實例化

下載只是把項目放進你的庫，副本預設鎖定為唯讀。真正開始用有兩條路徑：

  • 範本：在範本庫裡對下載的項目點「使用」，實例化出一條可編輯的工作流，預設命名為「原名 (從範本建立)」。這一步才計入工作流數量配額。
  • 模組：下載後即可被你的工作流以 sub_workflow 步驟按名稱引用；也可以在模組庫裡實例化出一份可編輯副本再改。

實例化出的工作流與市集項目相互獨立：作者發新版本不會改動你的執行個體；在「我下載的」裡解除安裝某個項目，也不影響你已經實例化出來的工作流。

下載的庫副本支援解鎖：解鎖後可以在編輯器裡直接編輯它。但注意，更新下載會用新版本整體替換這份庫副本，你的改動會遺失——想長期修改，實例化出自己的工作流再改。

常用端點

端點作用
GET /api/marketplace/items瀏覽（分頁，支援類型 / 分類 / 標籤 / 搜尋篩選）
GET /api/marketplace/items/{id}項目詳情 + 版本歷史
GET /api/marketplace/categories目前可見項目的全部分類
POST /api/marketplace/items發布新項目
POST /api/marketplace/items/{id}/versions發布新版本
GET /api/marketplace/items/{id}/dependencies查看相依樹
POST /api/marketplace/items/{id}/download下載（下載最新版時預設連同相依）
GET /api/marketplace/my-uploads我發布的項目
GET /api/marketplace/my-downloads我下載的項目（含更新提示）
POST /api/marketplace/downloads/{itemId}/instantiate把已下載項目實例化成可編輯工作流
DELETE /api/marketplace/downloads/{itemId}解除安裝已下載項目（不影響已實例化的工作流）

相關頁面