插件快速上手

本文帮助您用最短路径开发并运行第一个 Workova 插件。

插件类型

Workova 支持三类插件，每类解决不同的扩展需求：

类型	定位	典型场景
tool	命令型扩展	本地脚本调用、固定回复、外部 API 封装
channel	渠道接入	钉钉、飞书、Telegram 等消息平台对接
skill	技能桥接	OpenClaw 兼容层、技能类扩展

TIP

第一次开发插件，建议从 tool 类型开始——实现最简单、调试最直观。

第一步：创建插件目录

Workova 会自动扫描以下目录查找插件：

目录	作用域
.agents/plugins/	项目级（推荐）
~/.workova/plugins/	全局

创建您的第一个插件目录：

mkdir -p .agents/plugins/my-first-tool

第二步：编写 manifest

在插件目录中创建 plugin.manifest.json，这是插件的唯一必要文件：

{
  "id": "my-first-tool",
  "name": "我的第一个工具",
  "version": "1.0.0",
  "kind": "tool",
  "description": "一个最简单的工具插件示例",
  "commands": [
    {
      "name": "hello",
      "type": "response",
      "response": "您好，这是来自插件的回复！"
    }
  ]
}

INFO

commands 中每个命令会自动注册为 plugin.my-first-tool.hello 格式的命令 ID。

第三步：验证插件识别

使用 CLI 确认系统已识别到插件：

# 列出所有已识别的插件
workova plugin:list

# 查看插件详情
workova plugin:info --input '{"pluginId": "my-first-tool"}'

# 校验 manifest 格式
workova plugin:validate --input '{"path": ".agents/plugins/my-first-tool"}'

第四步：添加进程命令

固定回复只是起点。下面添加一个调用本地脚本的命令：

{
  "id": "my-first-tool",
  "name": "我的第一个工具",
  "version": "1.0.0",
  "kind": "tool",
  "description": "工具插件示例",
  "commands": [
    {
      "name": "hello",
      "type": "response",
      "response": "您好，这是来自插件的回复！"
    },
    {
      "name": "list-files",
      "type": "process",
      "description": "列出当前目录下的文件",
      "program": "bash",
      "args": ["-c", "ls -la"],
      "timeout_seconds": 10
    }
  ]
}

命令类型说明：

type	说明
response	返回固定文本
template	返回模板渲染结果（支持 {% raw %}{‌{config.xxx}‌} 变量）
process	启动外部进程执行
stdio	通过标准输入输出与外部进程通信

第五步：添加用户配置

如果插件需要用户提供配置（如 API Key），通过 config_schema 声明：

{
  "id": "my-first-tool",
  "name": "我的第一个工具",
  "version": "1.0.0",
  "kind": "tool",
  "config_schema": {
    "type": "object",
    "properties": {
      "welcome_text": {
        "type": "string",
        "title": "欢迎语",
        "description": "hello 命令返回的文本",
        "default": "您好！"
      },
      "api_key": {
        "type": "string",
        "title": "API Key",
        "secret": true,
        "widget": "password"
      }
    },
    "required": ["welcome_text"]
  },
  "commands": [
    {
      "name": "hello",
      "type": "template",
      "response_template": "{% raw %}{‌{config.welcome_text}‌}"
    }
  ]
}

config_schema 采用 JSON Schema 格式，Workova 会自动渲染配置表单。secret: true 的字段在界面上以密码形式显示。

常见问题

插件未被识别

1. 确认 plugin.manifest.json 文件名拼写正确
2. 确认文件位于 .agents/plugins/<plugin-name>/ 目录下
3. 确认 JSON 格式有效（workova plugin:validate 可检查）

命令名冲突

插件命令会自动添加命名空间前缀 plugin.<id>.<name>，因此不同插件的同名命令不会冲突。但同一插件内命令名必须唯一。

kind 值报错

kind 仅接受 tool、channel、skill 三个值，其他值会导致校验失败。

下一步

• 插件完整指南 — 了解渠道插件开发、安全边界和完整能力
• 官方插件模板 — 复制模板快速起步
• Manifest 参数说明 — 查看所有字段定义