← 返回 WebRPA 官网

WebRPA 插件开发文档

开发你的 WebRPA 插件

面向第三方开发者：把"针对特定网站 / 场景的自动化能力"封装成插件，上架到插件市场，供所有 WebRPA 用户一键安装使用。

核心理念：一个插件 = 一组「自定义模块」+ 元信息。安装后，插件贡献的模块会直接出现在编辑器侧栏，可以像内置模块一样拖拽、配置、被工作流调用与执行。无需改动 WebRPA 源码。

一、插件能做什么

为特定网站封装专用模块，例如「抖音后台 - 发布视频」「拼多多商家 - 上下架商品」「某 CRM - 创建客户」。
把一段常用工作流封装成单个模块，降低其他用户的使用门槛。
附带给 AI 小助手的「站点适配知识」，让小助手更懂这个网站的自动化套路。

二、插件包格式（plugin.json）

插件是一个 JSON 文件，结构如下：

{
  "id": "douyin-backend",            // 唯一标识，仅允许字母/数字/-/_
  "name": "抖音后台自动化",            // 展示名
  "version": "1.0.0",
  "author": "你的名字",
  "description": "为抖音创作者后台封装的发布、数据采集模块",
  "homepage": "https://your-site.com",   // 可选
  "keywords": ["抖音", "电商", "运营"],    // 可选
  "knowledge": "抖音后台登录后…（给 AI 小助手的站点适配提示，可选）",
  "modules": [                        // 贡献的模块（数组，可多个）
    {
      "name": "douyin_publish",
      "display_name": "抖音-发布视频",
      "description": "在抖音创作者后台上传并发布一个视频",
      "icon": "🎬",
      "color": "#fe2c55",
      "category": "plugin",
      "parameters": [
        { "name": "videoPath", "label": "视频路径", "type": "string", "required": true },
        { "name": "title", "label": "标题", "type": "string" }
      ],
      "outputs": [
        { "name": "publishUrl", "label": "发布后的链接" }
      ],
      "workflow": {                   // 模块的内部实现：一段标准 WebRPA 工作流
        "nodes": [ /* ... 标准节点 ... */ ],
        "edges": [ /* ... 连线 ... */ ]
      }
    }
  ]
}

modules[].workflow 怎么来？

最简单的做法：在 WebRPA 编辑器里把功能搭成一条工作流，封装为「自定义模块」，再用模块卡片的「导出」拿到它的 JSON；把导出的 parameters / outputs / workflow 等字段填进插件包即可。

字段	说明
`name`	模块内部名（同一插件内唯一）
`display_name`	侧栏显示的名字
`parameters`	用户可配置的输入参数
`outputs`	模块产出的变量
`workflow`	模块的实际执行逻辑（标准工作流 nodes/edges）

三、安装与调试

在 WebRPA 编辑器打开「工作流仓库 → 插件」标签页。
点击「从文件安装」，选择你的 plugin.json。
安装成功后，插件贡献的模块会出现在编辑器侧栏（分类标签 plugin:<你的插件id>），可直接拖拽使用。
在「已安装」中可启用 / 禁用 / 卸载该插件。

禁用插件会移除其贡献的模块但保留安装包，再次启用可一键恢复；卸载会彻底删除。

四、上架到插件市场

插件市场通过一个「市场索引」JSON 提供可安装的插件列表。索引格式：

{
  "plugins": [
    {
      "id": "douyin-backend",
      "name": "抖音后台自动化",
      "version": "1.0.0",
      "author": "你的名字",
      "description": "...",
      "homepage": "https://your-site.com",
      "keywords": ["抖音"],
      "downloadUrl": "https://your-cdn.com/douyin-backend.plugin.json"
      // 或者直接内联完整包：  "package": { ...完整 plugin.json... }
    }
  ]
}

把上面的索引 JSON 部署到任意可公开访问的 URL（你的服务器 / GitHub Raw / 对象存储）。
在 WebRPA「全局配置」里把「插件市场索引地址」设为该 URL。
之后所有用户在「工作流仓库 → 插件 → 插件市场」里即可看到并一键安装你的插件。

未配置远程索引时，WebRPA 会显示内置示例插件，方便你参考结构。

五、扩展 API（后端 REST）

插件能力同样开放为 REST 接口，便于自动化集成：

方法 / 路径	说明
`GET /api/plugins/installed`	已安装插件列表
`GET /api/plugins/market`	插件市场列表
`POST /api/plugins/install`	安装本地插件包 `{package:{...}}`
`POST /api/plugins/install-from-market/{id}`	从市场安装
`POST /api/plugins/{id}/enable`	启用/禁用 `{enabled:true\|false}`
`DELETE /api/plugins/{id}`	卸载插件
`POST /api/plugins/market-url`	设置市场索引地址 `{url}`
`GET /api/plugins/{id}/export`	导出市场就绪包 JSON
`POST /api/plugins/{id}/publish`	一键发布/上架 `{hubUrl?}`
`GET /api/plugins/{id}/reviews`	获取评分/评论（本地与 hub 合并）
`POST /api/plugins/{id}/reviews`	提交评分 `{rating:1-5, comment, user}`

六、最佳实践

一个插件聚焦一个网站 / 一类场景，模块命名清晰、参数有默认值。
选择器尽量稳健（优先 id / 稳定属性），并在 knowledge 中写明该站点的登录方式、关键页面结构。
版本号遵循语义化版本；升级时保持参数向后兼容。
遵守目标网站的服务条款与相关法律法规。

— 进阶开发 —

上面是入门：会搭工作流、会导出模块就能做插件。下面是真正决定插件“好不好用、能不能上架被人长期使用”的进阶内容。

七、模块内部：参数注入与产出回传

每个插件模块的 workflow 就是一条标准 WebRPA 工作流（等价于一个“子流程”）。理解参数/产出如何与内部工作流打通，是写出可复用模块的关键：

参数即变量：用户在模块卡片上填的每个 parameters[].name，在模块内部工作流里就是一个同名变量，可用 {参数名} 直接引用（如选择器、URL、文本框里写 {title}）。
产出即变量：内部工作流用「设置变量」模块写一个与 outputs[].name 同名的变量，模块执行完该值就会回传给外层工作流，供后续节点引用。
作用域隔离：模块内部的变量作用域与主流程相互独立，不会互相污染；只有“参数（入）”和“产出（出）”是约定的交换通道。

// 一个“登录并返回 cookie”模块的思路：
parameters: [ {name:"username"}, {name:"password"} ]   // 外部传入 → 内部可用 {username}/{password}
outputs:    [ {name:"loginCookie"} ]                    // 内部「设置变量 loginCookie=...」→ 回传给外层
workflow:   打开页面 → 输入 {username} → 输入 {password} → 点击登录 → 取 cookie → 设置变量 loginCookie

最稳妥的做法仍是：在编辑器里把功能搭成工作流 → 封装为「自定义模块」并定义好参数/产出 → 用模块卡片「导出」拿到完整 JSON，直接作为 modules[] 的一项。手写容易漏字段。

八、参数类型与高级控件

参数不止 string。在编辑器「创建自定义模块」面板里可为每个参数选择控件类型，导出后即体现在 parameters[].type 上，让使用者填得更省心、更不易出错：

类型	呈现的控件	适用场景
`string`	单行文本	选择器、URL、关键词
`text` / 多行	多行文本框	消息正文、JSON、脚本片段
`number`	数字输入 / 滑块	数量、阈值、超时
`boolean`	复选框	开关项（是否无头、是否覆盖）
`select` / 多选	下拉（单选 / 多选）	固定可选值（画质、格式）

每个参数都建议给 label（中文显示名）、required（是否必填）、default（默认值），并在 description 里写清填写示例。良好的默认值能极大降低别人的上手成本。

九、一个插件，多个模块

modules 是数组——一个插件可以贡献一整套相关模块，构成某网站/场景的“工具箱”。例如「某 CRM 适配」插件可同时提供：登录、创建客户、查询订单、导出报表。安装后它们会一起出现在侧栏，并带统一的分类标签 plugin:<你的插件id>，方便用户成组识别。

模块之间可通过“产出 → 参数”串联：前一个模块输出 loginCookie，后一个模块把它作为参数传入。
模块内部也可调用你封装的其它子流程，复用公共步骤（如统一的登录流程）。

十、命名空间与冲突规避（自动）

为避免和用户已有模块、或其它插件撞名，安装时 WebRPA 会自动处理命名空间，你无需手动加前缀：

每个模块在本地的真实 id 会被改写为 plugin_<插件id>_<模块名>；
自动附加标签 plugin:<插件id>，侧栏据此归类；
未指定 category 时默认归到 plugin 分类。

因此你在 plugin.json 里用简洁的模块名即可，平台保证全局唯一。

十一、版本升级与启用 / 禁用机制

升级：用相同 id 再次安装即视为升级——平台会先移除旧版本贡献的模块，再装入新版本，干净替换。版本号请遵循语义化版本（主.次.修订），升级时保持参数向后兼容。
启用 / 禁用：安装时平台会备份原始包（<id>.pkg.json）。禁用插件会移除它贡献的模块文件（但保留安装包），再次启用会据备份自动重建模块——禁用是“临时下线”，卸载才是“彻底删除”。

十二、搭建你自己的插件中心（Hub）

除了把单个 plugin.json 放到任意 URL 当作市场索引，你也可以自建一个中心化插件仓库（WebRPA 提供了参考实现 frameworkHub）。后端按以下约定与 Hub 交互，把地址填到「全局配置 → 插件市场索引地址」即可：

方法 / 路径	说明
`GET /api/plugins`	返回市场索引 `{ plugins:[ {id,name,version,...,downloadUrl} ] }`
`GET /api/plugins/{id}/download`	返回该插件的完整包 JSON（供一键安装拉取）
`POST /api/plugins/publish`	接收完整插件包以上架（对应编辑器/接口的“发布”）
`POST /api/plugins/reviews`	接收评分 `{pluginId, rating, comment, user}`
`GET /api/plugins/reviews/{id}`	返回某插件的评分/评论 `{reviews:[...]}`

市场索引里每个插件可二选一提供安装来源：downloadUrl（指向完整包）或直接内联 package（完整 plugin.json）。配置了 Hub 后，发布 会把包 POST 到 {hub}/publish，评分 会与 Hub 双向合并。

十三、让 AI 小助手帮你开发插件

WebRPA 小助手内置了完整的插件开发技能，可以用自然语言驱动“开发 → 校验 → 隔离测试 → 发布”闭环：

“帮我把当前画布封装成一个名为 xxx 的插件模块” → 生成插件包结构；
隔离测试：小助手能在后端直接运行插件模块封装的工作流（不动你的画布），跑完看日志验证正确性；
“校验这个插件包格式是否合法” / “安装并启用” / “导出市场就绪包” / “发布到我的 Hub”，都可一句话完成。

这让没有后端经验的人也能做出可上架的插件。

十四、能力边界、安全与合规

能力范围：插件模块本质是“一条工作流”，因此它能用 WebRPA 的全部内置模块——包括网页/桌面/键鼠、Excel/文件、HTTP 请求，乃至「Python 脚本」「JS 注入」模块。能力很强，但也意味着你要为模块内的脚本负责。
站点适配知识（knowledge）：在包级 knowledge 字段写清该网站的登录方式、关键页面结构、易错点，安装后能帮 AI 小助手更懂这个站点的自动化套路。
选择器稳健性：优先用 id / 稳定属性，配合“选择器自愈”；动态站点多用属性包含 + 文本 + 相对轴（详见官网选择器指南）。被风控的站点可改用 DP（反检测）系列网页模块。
安全：不要把账号口令、密钥硬编码进插件包（它会被分发）。让用户用参数填，或引用 WebRPA 的「加密凭据库」。
合规：务必遵守目标网站的服务条款与相关法律法规；插件造成的使用后果由插件作者与使用者承担。

十五、联系与反馈

开发中遇到问题，欢迎联系作者彭明航：QQ 2124691573 · 微信 QyPmh20061026 · QQ 群 115069513。

← 返回 WebRPA 官网