开发手册 - WanHub

1概述

WanHub 是 WanClaw 的官方插件生态系统，为 AI 助手提供可扩展的技能市场。开发者可以创建并提交插件，经审核后上架，供所有用户安装使用。

插件类型

类型	标识	说明
技能插件	`skill`	扩展 AI 核心能力
适配器插件	`adapter`	连接外部平台
流程插件	`workflow`	自动化工作流
Prompt 模板	`prompt`	AI 提示词模板

插件分类

ecommerce 电商自动化 · im IM智能客服 · office 办公RPA · ai AI增强 · data 数据统计 · ops 系统运维 · workflow 工作流 · ecosystem 插件生态

2快速开始

环境要求

Python 3.8+
pip
WanClaw v2.0.0+

创建第一个插件 — 完整步骤

创建目录并编写 manifest.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的第一个插件",
  "author": "your-name",
  "category": "office",
  "entry_point": "main.py",
  "dependencies": [],
  "permissions": [],
  "wanclaw_version": ">=2.0.0"
}

编写 plugin.json（WanClaw 元数据）

{
  "plugin_id": "yourname.my_plugin",
  "plugin_name": "我的插件",
  "plugin_type": "skill",
  "description": "我的第一个插件",
  "author": "your-name",
  "version": "1.0.0",
  "category": "office",
  "compatible_wanclaw_version": ">=2.0.0",
  "entry_file": "main.py",
  "permissions": []
}

编写入口文件 main.py

"""我的第一个插件"""

async def run(**kwargs) -> dict:
    return {
        "success": True,
        "message": "插件执行成功",
        "data": kwargs
    }

打包插件

python3 scripts/package_plugin.py my-plugin/

上传到 WanHub

curl -X POST https://wanhub.vanyue.cn/api/community/plugins/upload \
  -F "file=@my-plugin.zip" \
  -F "plugin_name=我的插件" \
  -F "plugin_type=skill" \
  -F "category=office" \
  -F "author=your-name"

3插件结构

必需文件

my-plugin/ ├── manifest.json # WanHub 元数据 ├── plugin.json # WanClaw 元数据 └── main.py # 入口函数

manifest.json 字段

字段	必需	说明
`name`	必填	插件目录名（小写+下划线）
`version`	必填	语义化版本，如 1.0.0
`description`	必填	功能描述
`author`	必填	作者名
`category`	必填	分类标识
`entry_point`	必填	入口文件（main.py）
`keywords`	可选	搜索关键词
`dependencies`	可选	Python 依赖列表
`permissions`	可选	权限声明
`platforms`	可选	平台支持
`wanclaw_version`	可选	兼容版本

plugin.json 字段

字段	必需	说明
`plugin_id`	必填	唯一标识，格式: `type.name`
`plugin_name`	必填	显示名称
`plugin_type`	必填	skill / adapter / workflow / prompt
`description`	必填	功能描述
`author`	必填	作者
`version`	必填	版本号
`category`	必填	分类
`compatible_wanclaw_version`	可选	兼容版本
`permissions`	可选	权限列表
`level`	可选	beginner / intermediate / advanced

生命周期

安装

下载插件

加载

安全扫描

注册

插件管理

执行

暴露给Agent

执行入口

async def run(**kwargs) -> dict:
    """
    插件执行入口

    标准返回格式:
      - success: bool   是否成功
      - message: str    用户可见消息
      - data: Any       业务数据（可选）
      - error: str      错误信息（失败时）
    """
    return {
        "success": True,
        "message": "处理完成",
        "data": {...}
    }

4权限系统

插件必须声明所需权限。审核时会检查实际使用的权限是否在声明范围内。原则：最小权限，只申请必需权限。

权限	说明	风险等级
`network`	HTTP 请求	中
`database`	数据库访问	高
`filesystem:read`	读取文件	低
`filesystem:write`	写入文件	中
`exec`	执行命令	极高
`shell`	Shell 命令	极高
`subprocess`	子进程	极高
`email`	发送邮件	中

exec / shell / subprocess 几乎不会被批准，请使用替代方案实现相同功能。

5安全模型

高危代码检测

以下代码模式会导致审核拒绝：

os.system() · subprocess.call() · eval() · exec()
__import__() · import shutil · rm -rf
危险文件写入操作

风险等级

等级	说明	处理方式
low	无危险操作	自动通过
medium	网络/文件操作	人工审核
high	高危代码	拒绝上架

安全预检 API

提交前可使用预检 API 进行自助安全扫描，提前发现潜在问题。

curl -X POST https://wanhub.vanyue.cn/api/community/plugins/scan \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@my-plugin.zip"

6开发指南

完整示例 — 天气查询插件

"""天气查询插件 — 查询城市天气"""

import logging
from typing import Dict, Any

logger = logging.getLogger(__name__)


async def run(**kwargs) -> Dict[str, Any]:
    query = kwargs.get("query", "")
    if not query:
        return {"success": False, "message": "请提供城市名称"}

    city = query.replace("天气", "").replace("查询", "").strip()

    try:
        import httpx
        async with httpx.AsyncClient(timeout=10) as client:
            resp = await client.get(
                "https://api.example.com/weather",
                params={"city": city}
            )
            data = resp.json()

        return {
            "success": True,
            "message": f"{city}今日天气：{data['weather']}，气温 {data['temp']}°C",
            "data": data
        }
    except Exception as e:
        logger.error(f"天气查询失败: {e}")
        return {"success": False, "message": "查询失败，请稍后重试"}

关键规则

入口函数必须是 async def run(**kwargs)
返回值必须包含 success 和 message 字段
使用 logging 模块记录关键操作
所有外部输入做校验
网络请求必须设置 timeout
不硬编码敏感信息，使用环境变量替代

7API 参考

认证方式

Authorization: Bearer <token>

插件 API

方法	路径	说明
`GET`	`/api/community/plugins/list`	插件列表
`GET`	`/api/community/plugins/detail`	插件详情
`GET`	`/api/community/plugins/download`	下载链接
`POST`	`/api/community/plugins/upload`	上传插件
`POST`	`/api/community/plugins/scan`	安全预检
`GET`	`/api/community/plugins/comments`	评论列表
`POST`	`/api/community/plugins/comments`	发表评论
`GET`	`/api/community/stats`	社区统计

上传插件

curl -X POST https://wanhub.vanyue.cn/api/community/plugins/upload \
  -F "file=@my-plugin.zip" \
  -F "plugin_name=我的插件" \
  -F "description=功能描述" \
  -F "plugin_type=skill" \
  -F "category=office" \
  -F "author=your-name" \
  -F "permissions=[\"network\"]"

8审核流程

提交

打包上传

预检

安全扫描

人工审核

管理员复核

上架 / 拒绝

通知结果

通过条件

必需文件完整（manifest.json、plugin.json、main.py）
main.py 语法正确，可正常加载
权限声明合理，无高危权限
无高危代码（exec、eval 等）
描述清晰，功能完整

拒绝原因

高危代码（exec/shell/subprocess 等）
缺少必需文件
权限过度申请
剽窃或侵权内容
违法内容

审核状态

状态	说明
`pending`	等待审核
`approved`	已上架
`rejected`	已拒绝

9最佳实践

代码质量

使用 async/await 异步处理 · 完善的错误捕获与处理 · 使用 logging 记录关键操作 · 添加类型注解提升可读性

安全规范

敏感信息通过环境变量注入 · 外部输入严格校验 · 网络请求设置合理 timeout · 避免任何命令执行

用户体验

消息简洁易懂 · 失败操作给出明确原因 · 耗时操作提供进度反馈 · 错误信息用户友好

性能优化

避免同步阻塞操作 · 使用连接池复用网络连接 · 大量数据采用流式处理 · 合理缓存避免重复请求

版本规范

遵循语义化版本 major.minor.patch：

major — 不兼容的重大 API 变更
minor — 向后兼容的新功能
patch — 向后兼容的问题修复

10常见问题

Q: 审核需要多久？

A: 通常 1-3 个工作日完成审核。如遇节假日或高峰期可能顺延。

Q: 被拒绝后能重新提交吗？

A: 可以。收到拒绝通知后，请查看拒绝原因并修复问题，然后重新打包上传即可。

Q: 可以申请 exec/shell 权限吗？

A: 几乎不会批准。请重新设计插件架构，使用替代方案（如 HTTP API、Python 内置功能）实现相同目标。

Q: 插件更新需要用户重新安装吗？

A: 不需要。WanClaw 会自动检测到新版本并向用户推送更新提示，用户可一键更新，无需手动操作。

Q: 如何撤回已发布的插件？

A: 请通过插件市场的意见反馈功能联系管理员，提供插件名称和撤回原因，管理员将在 24 小时内处理。

Q: 支持哪些编程语言？

A: 当前主要支持 Python 插件（需要 async def run 函数）。未来将扩展 JavaScript/TypeScript 支持。

WanHub 开发手册

1概述