跳转到主要内容
文档扩展生态模板与模块市场

模板与模块市场

把做好的工作流发布成模板或模块并按版本迭代；下载时自动解析依赖，装完即可实例化使用。

市场是控制台里的「市场」页面：社区和官方发布的模板与模块都在这里。你可以把别人发布的条目下载到自己的模板库或模块库，也可以把自己做好的工作流发布上去，按版本迭代。模板下载后实例化成自己的工作流；模块下载后可以直接被 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}卸载已下载条目（不影响已实例化的工作流）

相关页面