Files

K2cr2O1 03bcded7ed feat: 新增自动同意请求插件和API文档

docs: 更新文档结构和内容

2026-01-14 23:53:56 +08:00

4.2 KiB

Raw Blame History

API 基础

这一页讲的是 NEO Bot 里 API 调用的底层原理。如果你只是写插件发消息，可以直接跳过这页，去看消息 API。

但如果你想了解背后发生了什么，或者想自己封装一些高级功能，那这里的信息会帮到你。

API 调用流程

简单来说，当你调用 bot.send_group_msg() 时：

你的插件 → bot.send_group_msg(123456, "hello")
Bot 类 → 把它打包成 OneBot 标准的 JSON
WebSocket → 通过 ws.py 发给 NapCatQQ（或其他 OneBot 实现）
OneBot 实现 → 收到请求，真的把消息发到 QQ 群里
响应返回 → 原路返回，告诉 Bot “消息发送成功”

整个过程是异步的，所以你要用 await。

call_api 方法

所有 API 最终都会调用 BaseAPI.call_api() 方法。这是最底层的接口：

async def call_api(self, action: str, params: Optional[Dict[str, Any]] = None) -> Any:

action: API 动作名，比如 "send_group_msg"、"get_login_info"
params: 参数字典，比如 {"group_id": 123456, "message": "hello"}

返回值

call_api 返回的是 OneBot 响应中的 data 字段。如果 API 调用失败（返回 {"status": "failed", ...}），它会记录一条警告日志，但不会抛出异常（除非网络错误）。

这样设计是为了让插件能更灵活地处理失败情况。比如：

try:
    result = await bot.call_api("send_group_msg", {"group_id": 123456, "message": "test"})
    if result is None:
        print("API 调用失败，但没抛异常")
except Exception as e:
    print(f"网络或底层错误: {e}")

响应格式

OneBot v11 的标准响应格式是：

{
  "status": "ok",
  "retcode": 0,
  "data": { ... },
  "message": "",
  "echo": "请求时的 echo 值（如果有）"
}

status: "ok" 或 "failed"
retcode: 状态码，0 表示成功
data: 真正的返回数据
message: 错误信息（失败时）
echo: 用来匹配请求和响应的标识（WebSocket 用）

NEO Bot 的 call_api 方法会自动提取 data 字段返回给你。如果 status 是 "failed"，它会在日志里记录警告，但依然返回 data（通常是 None 或空字典）。

错误处理

API 调用可能因为各种原因失败：

网络问题: WebSocket 断开、超时
权限不足: 机器人不是管理员却想踢人
参数错误: 群号不存在、消息太长
客户端不支持: 某些 OneBot 实现可能没实现某些 API

建议在插件里做好错误处理：

@matcher.command("kick")
async def handle_kick(event: MessageEvent, args: str):
    target_id = int(args) if args.isdigit() else 0
    if not target_id:
        await event.reply("参数错误，需要 QQ 号")
        return
    
    try:
        result = await event.bot.set_group_kick(event.group_id, target_id)
        if result.get("status") == "failed":
            await event.reply(f"踢人失败: {result.get('message', '未知错误')}")
        else:
            await event.reply("踢人成功")
    except Exception as e:
        await event.reply(f"网络错误: {e}")

直接调用 vs 高级封装

NEO Bot 提供了两种调用 API 的方式：

1. 直接调用 `call_api`

await bot.call_api("send_group_msg", {"group_id": 123456, "message": "hello"})

什么时候用？

你想调用的 API 没有被封装成独立方法（很少见）
你在调试，想看看原始请求和响应
你在写框架代码，需要动态生成 action 名

2. 使用封装好的方法

await bot.send_group_msg(123456, "hello")

这是推荐的方式，因为：

有类型提示，编辑器能帮你补全
参数有文档，不用去查 OneBot 标准
有些方法有额外逻辑（比如缓存、参数转换）

下一步

现在你了解了 API 调用的基础。接下来可以去看看具体的 API 类别：

消息 API: 最常用，先看这个
群组 API: 管理群聊
好友 API: 好友相关操作
账号 API: 机器人自身状态
媒体 API: 图片、语音

4.2 KiB Raw Blame History Unescape Escape