插件完整指南

本文介绍 Workova 插件体系的完整能力、安全边界和各类插件的开发流程。

插件体系概览

Workova 插件系统支持三类扩展，通过 plugin.manifest.json 声明能力：

类型	定位	capabilities 示例
`tool`	命令和工具	`["tool:command"]`
`channel`	渠道接入	`["channel:dingtalk", "channel:feishu"]`
`skill`	技能桥接	`["skill:bridge"]`

已支持的能力

自动扫描插件目录并识别 plugin.manifest.json
兼容 openclaw.plugin.json 格式
在 Agent 页面绑定插件命令
根据 config_schema 自动渲染配置表单
自动注册并隔离插件命令（命名空间 plugin.<id>.<name>）
插件安装、启用/禁用、卸载和 manifest 校验

安全边界

WARNING

插件不能修改 LLM 渠道配置。以下字段由平台统一控制，插件不得声明或覆盖：

provider、api_key、base_url
model_gateway、llm_provider、llm_override

模型路由由平台统一管控，这是不可突破的安全边界。

工具插件开发

工具插件是最简单的插件类型，通过 commands 定义一组可调用的命令。

命令类型

type	说明	适用场景
`response`	返回固定文本	帮助信息、状态回复
`template`	返回模板渲染结果	基于配置的动态回复
`process`	启动外部进程	调用脚本、CLI 工具
`stdio`	标准输入输出通信	需要交互的外部程序

完整工具插件示例

json

{
  "id": "dev-helper",
  "name": "开发辅助工具",
  "version": "1.0.0",
  "kind": "tool",
  "description": "提供常用开发命令的快捷入口",
  "capabilities": ["tool:command"],
  "config_schema": {
    "type": "object",
    "properties": {
      "workspace_root": {
        "type": "string",
        "title": "工作区根目录",
        "default": "."
      }
    }
  },
  "commands": [
    {
      "name": "hello",
      "type": "template",
      "description": "欢迎信息",
      "response_template": "当前工作区: {‌{config.workspace_root}‌}"
    },
    {
      "name": "list-files",
      "type": "process",
      "description": "列出工作区文件",
      "program": "bash",
      "args": ["-c", "ls -la {‌{config.workspace_root}‌}"],
      "timeout_seconds": 10
    }
  ]
}

渠道插件开发

渠道插件将外部消息平台接入 Workova，是最复杂的插件类型。

目录结构

text

my-channel-plugin/
  plugin.manifest.json    # 必须：插件声明
  scripts/
    lifecycle.js          # 生命周期脚本
  assets/                 # 可选：静态资源

接入模式

通过 entrypoints.channel_adapter.mode 指定：

模式	说明	适用场景
`managed_webhook`	托管 Webhook	钉钉、飞书等支持 Webhook 的平台
`direct_ws`	WebSocket 直连	Telegram、Discord 等实时通信
`direct_stream`	流式直连	SSE 推送场景
`direct_polling`	轮询直连	无推送能力的平台

生命周期钩子

渠道插件通过生命周期钩子处理各阶段事件：

钩子	触发时机	说明
`install`	插件安装时	初始化配置和资源
`validate`	保存配置时	验证用户填写的配置是否有效
`connect`	建立连接时	启动消息监听
`disconnect`	断开连接时	清理资源
`receive`	收到消息时	将平台消息转换为统一格式
`send`	发送消息时	将统一格式转换为平台消息
`health`	健康检查	确认连接状态
`route`	消息路由	决定消息分发策略
`archive_media`	媒体归档	处理图片、文件等附件

每个钩子的值可以是：

true / false — 启用或禁用
字符串路径 — 指向处理脚本（如 "scripts/lifecycle.js"）

脚本环境变量

生命周期脚本执行时，Workova 注入以下环境变量：

变量	说明
`WORKOVA_PLUGIN_ACTION`	当前生命周期（`install`、`receive`、`send` 等）
`WORKOVA_PLUGIN_CHANNEL`	渠道标识（`dingtalk`、`feishu` 等）
`WORKOVA_PLUGIN_CONFIG`	插件配置（JSON 字符串）
`WORKOVA_PLUGIN_CONTEXT`	当前上下文（JSON 字符串）
`WORKOVA_PLUGIN_MESSAGE`	文本消息内容

统一消息格式

接收消息（receive 钩子接收的数据）：

json

{
  "channel_type": "dingtalk",
  "message_id": "msg_123",
  "conversation": {
    "id": "chat_001",
    "type": "group",
    "title": "研发群"
  },
  "sender": {
    "id": "user_001",
    "name": "张三",
    "type": "user"
  },
  "message": {
    "type": "text",
    "text": "消息内容",
    "attachments": []
  },
  "received_at": "2026-03-30T10:00:00+08:00"
}

发送消息（send 钩子接收的数据）：

json

{
  "channel_type": "dingtalk",
  "conversation_id": "chat_001",
  "reply_to_message_id": "msg_123",
  "message": {
    "type": "text",
    "text": "回复内容",
    "attachments": []
  }
}

支持的消息类型：text、image、file、video、audio。附件通过 attachments 数组传递，包含 type、url、name、mime_type、size_bytes 等字段。

渠道插件最小示例

json

{
  "id": "my-dingtalk",
  "name": "钉钉接入",
  "version": "1.0.0",
  "kind": "channel",
  "capabilities": ["channel:dingtalk"],
  "config_schema": {
    "type": "object",
    "properties": {
      "webhook_url": {
        "type": "string",
        "title": "Webhook 地址",
        "description": "钉钉机器人的 Webhook URL"
      },
      "secret": {
        "type": "string",
        "title": "签名密钥",
        "secret": true,
        "widget": "password"
      }
    },
    "required": ["webhook_url"]
  },
  "entrypoints": {
    "channel_adapter": {
      "mode": "managed_webhook",
      "supported_channels": ["dingtalk"],
      "lifecycle": {
        "validate": "scripts/lifecycle.js",
        "receive": "scripts/lifecycle.js",
        "send": "scripts/lifecycle.js"
      }
    }
  }
}

OpenClaw 兼容模式

如果您已有 OpenClaw 风格的插件，Workova 可直接识别 openclaw.plugin.json：

json

{
  "id": "china-channels",
  "version": "0.1.0",
  "channels": ["dingtalk", "feishu"]
}

Workova 会自动将其规范化为：

kind → channel
compatibilityMode → openclaw
capabilities → ["channel:dingtalk", "channel:feishu"]

建议逐步迁移为 Workova 原生 plugin.manifest.json 格式，以获得完整的配置表单和生命周期支持。

当前支持矩阵

能力	状态
工具插件 — 固定回复	生产就绪
工具插件 — 本地进程	生产就绪
渠道插件 — Telegram	生产就绪
渠道插件 — Discord	生产就绪
渠道插件 — 飞书（托管）	生产就绪
渠道插件 — 企业微信（托管）	生产就绪
渠道插件 — 钉钉 Webhook	部分支持
OpenClaw 兼容	生产就绪
技能桥接	生产就绪

调试检查清单

开发过程中遇到问题，按以下顺序排查：

manifest 校验：workova plugin:validate --input '{"path": "插件目录"}'
插件列表：workova plugin:list 确认插件被识别
命令列表：workova plugin:commands --input '{"pluginId": "插件ID"}' 确认命令已注册
config_schema 格式：确认 type: "object" 在最外层，properties 内定义字段
命令命名：确认命令 name 非空且在同一插件内唯一

常见陷阱

config_schema 最外层必须是 {"type": "object", "properties": {...}}，不能直接写字段定义
命令名为空会被自动过滤，不会出现在命令列表中
kind 只接受 tool、channel、skill，其他值校验失败

插件完整指南 ​

插件体系概览 ​

已支持的能力 ​

安全边界 ​

工具插件开发 ​

命令类型 ​

完整工具插件示例 ​

渠道插件开发 ​

目录结构 ​

接入模式 ​

生命周期钩子 ​

脚本环境变量 ​

统一消息格式 ​

渠道插件最小示例 ​

OpenClaw 兼容模式 ​

当前支持矩阵 ​

调试检查清单 ​

相关文档 ​

插件完整指南

插件体系概览

已支持的能力

安全边界

工具插件开发

命令类型

完整工具插件示例

渠道插件开发

目录结构

接入模式

生命周期钩子

脚本环境变量

统一消息格式

渠道插件最小示例

OpenClaw 兼容模式

当前支持矩阵

调试检查清单

相关文档