# /// # API.md # 描述：WXAuto Center API 接口文档 # 作者：AI Generated # 创建日期：2026-04-06 # 更新日期：2026-04-06 # /// # WXAuto Center API 接口文档 ## 概述 本系统提供完整的 RESTful API，支持节点管理、消息发送、插件管理、外部程序接入、Webhook 管理等功能。所有 API 均使用 JSON 格式进行请求和响应。 ## 基础信息 | 项目 | 说明 | |------|------| | Base URL | `http://{host}:{port}/api/v1` | | 默认端口 | 8080 | | 内部 API 认证 | Header: `X-API-Key: your-external-api-key` | | 外部 API 认证 | Header: `X-ExternalKey: your-external-api-key` | | 响应格式 | JSON | ## API 列表 ### 节点管理 `/api/v1/nodes` | 方法 | 路径 | 说明 | |------|------|------| | GET | `/nodes/` | 获取所有节点 | | GET | `/nodes/{node_id}` | 获取指定节点信息 | | POST | `/nodes/` | 添加节点 | | PUT | `/nodes/{node_id}` | 更新节点信息 | | DELETE | `/nodes/{node_id}` | 删除节点 | | GET | `/nodes/{node_id}/status` | 检查节点状态 | | POST | `/nodes/{node_id}/enable` | 启用节点 | | POST | `/nodes/{node_id}/disable` | 禁用节点 | | GET | `/nodes/{node_id}/friends` | 获取节点好友列表 | | GET | `/nodes/{node_id}/groups` | 获取节点群列表 | | GET | `/nodes/{node_id}/messages/{chat_name}` | 获取聊天消息 | ### 消息管理 `/api/v1/messages` | 方法 | 路径 | 说明 | |------|------|------| | POST | `/messages/send` | 发送消息 | | POST | `/messages/send_group` | 发送群消息 | | POST | `/messages/batch` | 批量发送消息 | | POST | `/messages/template/{node_id}/{who}` | 发送模板消息 | | GET | `/messages/history/{node_id}/{chat_name}` | 获取消息历史 | ### 插件管理 `/api/v1/plugins` | 方法 | 路径 | 说明 | |------|------|------| | GET | `/plugins/` | 获取所有插件 | | GET | `/plugins/{plugin_name}` | 获取插件详情 | | GET | `/plugins/{plugin_name}/schema` | 获取插件表单Schema | | POST | `/plugins/{plugin_name}/enable` | 启用插件 | | POST | `/plugins/{plugin_name}/disable` | 禁用插件 | | PUT | `/plugins/{plugin_name}/config` | 更新插件配置 | | POST | `/plugins/{plugin_name}/execute` | 执行插件 | | GET | `/plugins/{plugin_name}/logs` | 获取插件日志 | | POST | `/plugins/{plugin_name}/logs/clear` | 清空插件日志 | | GET | `/plugins/type/{plugin_type}` | 按类型获取插件 | ### 回调接口 `/api/v1/callback` | 方法 | 路径 | 说明 | |------|------|------| | POST | `/callback/node/reset` | 重置节点微信状态 | | POST | `/callback/node/check` | 检测节点微信状态 | | GET | `/callback/node/{node_id}/status` | 获取节点回调状态 | ### Webhook 管理 `/api/v1/webhook` | 方法 | 路径 | 说明 | |------|------|------| | GET | `/webhook/` | 获取所有Webhook | | GET | `/webhook/{webhook_id}` | 获取指定Webhook | | POST | `/webhook/` | 添加Webhook | | PUT | `/webhook/{webhook_id}` | 更新Webhook | | DELETE | `/webhook/{webhook_id}` | 删除Webhook | | POST | `/webhook/{webhook_id}/enable` | 启用Webhook | | POST | `/webhook/{webhook_id}/disable` | 禁用Webhook | ### 外部接口 `/api/v1/external` | 方法 | 路径 | 说明 | |------|------|------| | POST | `/external/send` | 外部接口-发送消息 | | POST | `/external/trigger` | 外部接口-触发数据处理 | | POST | `/external/plugin/execute` | 外部接口-执行插件 | | GET | `/external/plugins` | 外部接口-获取可用插件列表 | | GET | `/external/nodes` | 外部接口-获取可用节点 | | POST | `/external/ai/process` | 外部接口-AI处理消息 | | POST | `/external/webhook/{event}` | 外部接口-Webhook接收 | --- ## 节点管理 API 详解 ### 获取所有节点 ``` GET /api/v1/nodes/ ``` **响应示例：** ```json { "success": true, "data": [ { "node_id": "wx1", "name": "微信1", "api_url": "http://192.168.20.84:5000", "enabled": true, "description": "", "group": "wechat", "status": "error", "wechat_status": "online", "is_healthy": false } ], "count": 1 } ``` ### 添加节点 ``` POST /api/v1/nodes/ ``` **请求体：** ```json { "node_id": "wx1", "name": "微信1", "api_url": "http://192.168.20.84:5000", "api_key": "your-node-api-key", "description": "测试节点", "group": "wechat" } ``` ### 更新节点 ``` PUT /api/v1/nodes/{node_id} ``` **请求体：** ```json { "api_url": "http://192.168.20.84:5000", "api_key": "updated-key" } ``` --- ## 消息发送 API 详解 ### 发送消息 ``` POST /api/v1/messages/send ``` **请求体：** ```json { "node_id": "wx1", "who": "文件传输助手", "msg": "测试消息", "msg_type": "text" } ``` **响应示例：** ```json { "success": true, "message": "消息发送成功" } ``` ### 发送群消息 ``` POST /api/v1/messages/send_group ``` **请求体：** ```json { "node_id": "wx1", "group_name": "测试群", "msg": "群消息测试", "msg_type": "text" } ``` --- ## 插件管理 API 详解 ### 获取所有插件 ``` GET /api/v1/plugins/ ``` **响应示例：** ```json { "success": true, "plugins": [ { "name": "http_scheduled_sender", "version": "1.0.0", "type": "scheduled_task", "description": "定时HTTP数据源推送", "enabled": true, "config": { "node_id": "wx1", "receiver": "asq", "cron": "0 8 * * *" } } ], "count": 1 } ``` ### 配置插件 ``` PUT /api/v1/plugins/{plugin_name}/config ``` **请求体：** ```json { "name": "http_scheduled_sender", "config": { "node_id": "wx1", "receiver": "文件传输助手", "cron": "0 8 * * *", "http_url": "https://api.example.com/news", "message_template": "📰 {title}\n{url}" } } ``` ### 执行插件 ``` POST /api/v1/plugins/{plugin_name}/execute ``` **请求体：** ```json { "action": "preview" } ``` **action 选项：** - `send` - 执行完整流程 - `fetch` - 仅请求API - `parse` - 请求并解析数据 - `preview` - 预览格式化后的消息 - `test` - 测试cron表达式 --- ## 通用响应格式 **成功：** ```json { "success": true, "data": {}, "message": "操作成功" } ``` **失败：** ```json { "success": false, "error": "错误描述" } ``` --- ## 插件类型 | 类型 | 值 | 说明 | |------|-----|------| | `message_handler` | MESSAGE_HANDLER | 消息处理器 | | `data_source` | DATA_SOURCE | 数据源 | | `action_trigger` | ACTION_TRIGGER | 动作触发器 | | `ai_agent` | AI_AGENT | AI智能体 | | `scheduled_task` | SCHEDULED_TASK | 定时任务 | | `http_scheduled_sender` | HTTP_SCHEDULED_SENDER | 定时HTTP推送 | | `custom` | CUSTOM | 自定义 | --- ## 节点数据模型 ```json { "node_id": "wx1", "name": "微信1", "api_url": "http://192.168.20.84:5000", "api_key": "your-key", "enabled": true, "description": "", "group": "wechat", "status": "active", "wechat_status": "online", "is_healthy": true } ``` | 字段 | 类型 | 说明 | |------|------|------| | node_id | string | 节点唯一标识 | | name | string | 节点显示名称 | | api_url | string | 节点API地址 | | api_key | string | 节点API密钥 | | enabled | bool | 是否启用 | | description | string | 节点描述 | | group | string | 节点分组 | | status | string | API状态 (active/inactive/error) | | wechat_status | string | 微信状态 (online/offline) | | is_healthy | bool | 健康状态 |