Workova 文档

Appearance

插件 Manifest 参数说明 ​

本页基于当前 schema 定义 plugin.manifest.json 的完整字段。所有字段描述以实际代码识别的为准。

顶层字段 ​

字段必填类型说明
id是string插件唯一标识，用于命令命名空间和去重
name是string展示名称
version是string版本号（建议语义化版本）
kind是string插件类型：tool / channel / skill
description否string插件功能说明
capabilities否string[]能力声明（如 ["tool:command"]、["channel:dingtalk"]）
permissions否string[]权限声明
config_schema否object用户配置的 JSON Schema 定义
ui_schema否object配置表单界面渲染提示
entrypoints否object入口点定义（命令入口、渠道适配器）
commands否Command[]命令定义列表（tool 类型插件的快捷方式）
compatibilityMode否string兼容模式，默认 native
openclaw否objectOpenClaw 兼容配置（仅 openclaw 模式需要）
signing否object签名信息
min_runtime_version否string最低运行时版本要求
metadata否object额外扩展信息

kind ​

kind 决定插件类型，仅接受以下值：

值说明
tool命令型、本地工具型扩展
channel渠道连接、消息收发
skill技能桥接兼容或技能类扩展

WARNING

填写其他值将导致 schema 校验失败。

commands ​

commands 定义插件暴露的命令列表。每个命令自动注册为 plugin.<plugin-id>.<command-name> 格式。

命令字段 ​

字段必填类型说明
name是string命令名（同一插件内唯一）
description否string命令说明
type否string命令执行类型
response否string固定响应内容（type: response 时使用）
response_template否string模板响应（type: template 时使用，支持 {‌{config.xxx}‌}）
program否string外部程序路径（type: process / stdio 时使用）
args否string[]程序参数
required_config否string[]依赖的配置项
timeout_seconds否number超时时间（秒）

type 取值 ​

值说明示例场景
response返回固定文本帮助信息、版本号
template返回模板渲染结果基于配置的动态回复
process启动外部进程调用 bash 脚本、Python 脚本
stdio标准输入输出通信需要交互的外部程序

命令示例 ​

json
{
  "commands": [
    {
      "name": "greet",
      "type": "template",
      "description": "基于配置返回欢迎语",
      "response_template": "{‌{config.welcome_text}‌}"
    },
    {
      "name": "run-script",
      "type": "process",
      "description": "执行自定义脚本",
      "program": "node",
      "args": ["scripts/run.js"],
      "timeout_seconds": 30,
      "required_config": ["api_key"]
    }
  ]
}

config_schema ​

config_schema 声明插件的用户配置项，采用 JSON Schema 格式。Workova 根据此定义自动渲染配置表单。

基本结构 ​

json
{
  "config_schema": {
    "type": "object",
    "properties": {
      "field_name": {
        "type": "string",
        "title": "字段标题",
        "description": "字段说明"
      }
    },
    "required": ["field_name"]
  }
}

WARNING

最外层必须是 {"type": "object", "properties": {...}}。直接写字段定义（缺少 type: "object" 包裹）会导致表单无法渲染。

字段属性 ​

属性说明
type字段类型：string、number、boolean、array、object
title显示标题
description字段说明文本
placeholder输入框提示文本
default默认值
enum枚举选项列表
items数组项定义（type: "array" 时使用）
properties嵌套对象字段（type: "object" 时使用）
required嵌套必填字段列表
format格式提示（如 email、uri）
widgetUI 组件提示（如 textarea、password）
secret是否为敏感信息（true 时前端以密码形式显示）

配置示例 ​

json
{
  "config_schema": {
    "type": "object",
    "properties": {
      "api_key": {
        "type": "string",
        "title": "API Key",
        "description": "用于认证的密钥",
        "secret": true,
        "widget": "password"
      },
      "mode": {
        "type": "string",
        "title": "运行模式",
        "enum": ["production", "development"],
        "default": "production"
      },
      "max_retries": {
        "type": "number",
        "title": "最大重试次数",
        "default": 3
      },
      "description": {
        "type": "string",
        "title": "备注",
        "widget": "textarea"
      }
    },
    "required": ["api_key"]
  }
}

ui_schema ​

ui_schema 补充表单展示层信息，不影响数据校验，仅作为界面渲染建议。

entrypoints ​

entrypoints 定义插件的入口点。

entrypoints.commands ​

命令入口点，与顶层 commands 字段等效。推荐使用顶层 commands。

entrypoints.channel_adapter ​

渠道型插件的核心配置段。

字段必填说明
mode是接入模式
supported_channels是支持的渠道列表（如 ["dingtalk", "feishu"]）
channel_type否渠道类型标识
lifecycle否生命周期钩子定义

INFO

supported_channels 也可写作 camelCase 形式 supportedChannels，两种写法均被识别。

mode 取值 ​

值说明
managed_webhook托管 Webhook（钉钉、飞书）
direct_wsWebSocket 直连（Telegram、Discord）
direct_stream流式直连
direct_polling轮询直连

lifecycle 钩子 ​

可声明的生命周期阶段：

install、validate、connect、disconnect、receive、send、health、route、archive_media

每个钩子的值可以是：

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

渠道适配器示例 ​

json
{
  "entrypoints": {
    "channel_adapter": {
      "mode": "managed_webhook",
      "supported_channels": ["dingtalk"],
      "lifecycle": {
        "validate": "scripts/lifecycle.js",
        "receive": "scripts/lifecycle.js",
        "send": "scripts/lifecycle.js",
        "health": true
      }
    }
  }
}

compatibilityMode ​

值说明
nativeWorkova 原生接入（默认）
openclaw兼容 OpenClaw 桥接协议
skill_bridge技能桥接兼容层

openclaw ​

当 compatibilityMode 为 openclaw 时必须提供：

字段必填类型说明
adapter是string桥接适配器名称
entry是string入口文件路径
capabilities否string[]能力列表

最小可用示例 ​

工具插件 ​

json
{
  "id": "demo-tool",
  "name": "Demo Tool",
  "version": "1.0.0",
  "kind": "tool",
  "commands": [
    {
      "name": "hello",
      "type": "response",
      "response": "hello workova"
    }
  ]
}

渠道插件 ​

json
{
  "id": "demo-channel",
  "name": "Demo Channel",
  "version": "1.0.0",
  "kind": "channel",
  "capabilities": ["channel:demo"],
  "entrypoints": {
    "channel_adapter": {
      "mode": "managed_webhook",
      "supported_channels": ["demo"],
      "lifecycle": {
        "receive": "scripts/handler.js",
        "send": "scripts/handler.js"
      }
    }
  }
}

常见错误 ​

错误原因解决方案
kind 校验失败kind 值不是 tool/channel/skill修正为合法值
config_schema 表单不渲染缺少外层 type: "object"用 {"type": "object", "properties": {...}} 包裹
openclaw 模式报错设为 openclaw 但缺少配置段补充 openclaw.adapter 和 openclaw.entry
渠道适配器报错缺少 supported_channels添加至少一个渠道标识
命令未出现命令 name 为空确保每个命令都有非空 name

相关文档 ​

Workova 官方文档

Copyright © Workova