GoRoBot 开发文档

本文档面向插件开发者。阅读完可以做到：写出一个能收发消息、@人、发文件、管理群成员的插件， 并把它导出成可分发、可绑定机器码的加固包。
框架版本 1.0.20261020 · SDK 1.0 · ABI 3

快速开始

插件是一个普通的 .py 文件，里面定义一个继承 Plugin 的类。

from gorobot_sdk import Plugin

class Hello(Plugin):
    name = "Hello"
    version = "1.0.0"
    author = "you"
    description = "最小可用插件"

    def on_load(self):
        self.log("已启动")

    def on_private_message(self, msg):
        self.reply(msg, "收到：" + (msg.get("content") or ""))

装载流程：

1. 打开客户端「插件中心」，开启开发者模式（会要求设置一个开发者口令）。
2. 载入上面这个 .py 文件。宿主发现 Plugin 子类，实例化、注入 self.sdk、 注册你 override 的回调，然后调用 on_load()。
3. 用另一个账号给已登录的飞书账号发条私聊，插件就会回复。

插件基类

类属性

可覆写的方法

回调钩子

只注册你真正重写的钩子，没写的不会挂到总线上。

便捷方法

插件设置页

插件卡片上的「设置」按钮由框架自动生成。声明 settings_schema 后， 框架负责渲染表单、校验取值、原子落盘，并在保存后回调 on_settings_changed()， 插件不需要写任何前端代码；要更自由的界面，覆写 settings_page() 即可， 表单、图表、向导、整套自研 UI 都行。加固包（.grbp）里同样生效。

声明设置项

from gorobot_sdk import Plugin

class MyPlugin(Plugin):
    name = "群管助手"
    version = "1.2.0"

    settings_schema = [
        {"key": "prefix", "label": "回复前缀", "type": "text",
         "default": "🤖", "help": "回复时加在最前面的文字"},
        {"key": "rate", "label": "每分钟上限", "type": "number",
         "default": 5, "min": 1, "max": 60},
        {"key": "mode", "label": "工作模式", "type": "select", "default": "all",
         "options": [{"value": "all", "label": "所有群"},
                     {"value": "white", "label": "仅白名单"}]},
        {"key": "silent", "label": "静默模式", "type": "bool", "default": False},
        {"key": "keywords", "label": "触发词", "type": "textarea",
         "default": "ping\nhello", "rows": 5},
    ]

    def on_load(self):
        # 装载即可读到配置，自动带 schema 默认值
        self.log(f"前缀 = {self.config['prefix']!r}")

    def on_settings_changed(self, values):
        # 用户点了保存；此时新值已生效并落盘
        self.log(f"设置已更新：{values}")

支持的字段类型

公共属性：key（必填，字母/数字/_/-/.）、 label、default、help。坏条目会被静默丢弃而非报错 —— 一个字段写错不影响其它字段，也不影响插件运行。

读写配置

自定义设置页（完全自由 UI）

声明式表单不够用时（图表、二维码、动态联动、多步骤向导、整套自研界面）， 覆写 settings_page() 返回 HTML。插件决定全部 DOM 结构、CSS、JS 框架和交互， 框架不插手渲染，只负责把页面送到浏览器、并把配置读写接口摆好。

class Console(Plugin):
    name = "数据看板"

    # 开成独立原生窗口，不套框架的标题栏与侧栏
    settings_ui = {"mode": "window", "title": "数据看板",
                   "width": 1180, "height": 760}

    settings_schema = [
        {"key": "api", "label": "接口地址", "type": "text", "default": ""},
    ]

    def settings_page(self):
        # 返回完整文档：框架一个字节都不改，自带 CSS / 自带 CDN 都行
        return """<!DOCTYPE html>
<html lang="zh-CN"><head><meta charset="utf-8">
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
<style>html,body{margin:0;background:#0b0e13;color:#e9edf4}</style>
</head><body>
  <main id="app"></main>
  <script>
    grb.get().then(cfg => {
      document.getElementById('app').textContent =
        '当前接口：' + (cfg.values.api || '未配置');
    });
  </script>
</body></html>"""

呈现方式 settings_ui

也可给 dict 精细控制，字符串简写 settings_ui = "window" 等价于 {"mode": "window"}；未知字段忽略、非法 mode 回落 dialog —— 声明写错不会让设置页打不开。

两种返回方式的差别

连 grb 都不要的话，设 inject_helper: false，自己用 fetch 调下面这些接口即可（都走框架本机端口的同源请求，无需鉴权头，id 为插件 ID）：

页面里的 window.grb

在设置页里读数据

设置页是浏览器里的一段 HTML，没有 self.sdk。要显示「已登录账号」 「群列表」「群成员」这类数据，用框架注入的只读数据桥——后端用该插件的 sdk 实例 代查一次，把 JSON 递回页面。

// 一行拿到数据，返回就是插件钩子里看到的那种结构
const accounts = await grb.accounts();        // [{id, name, user_id, region, online}]
const groups   = await grb.groups();          // [{id, name, type, ownerId}]
const contacts = await grb.contacts(100);     // 通讯录（含外部联系人）
const members  = await grb.members(chatId);   // [{user_id, name, avatar, role}]

// 通用入口
const r = await grb.data('members', {chat_id: chatId});
// r = {ok, what, source, count, rows}

// 失败会抛异常，记得 catch
try { render(await grb.members(chatId)); }
catch (e) { showError(e.message); }          // 如「查询超时（20s）」

数据源全清单（grb.data(what, params)）

返回统一为 {ok, what, source, count, rows}：ok 为假时 grb.data() 直接抛 Error（消息可直接展示给用户）， 便捷方法则已经帮你取好了 rows。做能力探测用 await grb.sources()，每项形如 {what, method, params}。

完整可运行示例见 sdk/example_data_page.py：四个标签页分别展示 账号、群、通讯录、群成员，点群可下钻看成员。

保存时发生了什么

1. 逐字段校验：数字超范围收敛到边界，下拉不在选项内回落默认， 多选过滤非法项，颜色非法回落默认，布尔接受 "yes"/"1"/"on"
2. 写内存 + 原子落盘（先写 .tmp 再替换，断电不留半个文件）
3. 调用 on_settings_changed(values) —— 回调抛异常不会撤销已保存的配置， 但会写进事件日志，方便排查「改了没反应」
4. 界面提示本次改了哪些字段，被自动修正的字段会单独说明

消息对象

回调收到的 msg 是一个 dict。常用字段：

SDK · 框架信息与配置

SDK · 账号

只读。登录能力不在 SDK 里。

SDK · 会话与群

SDK · 消息发送

返回值约定

发送类方法成功返回 message_id 字符串，失败返回 None； 被版本限制、节流拦截时抛 SDKError。建议统一这么写：

mid = self.sdk.send_text(chat_id, "hello", account_id=acc)
if not mid:
    self.log(f"发送失败：{chat_id}", "WARN")

富文本与 @人

富文本混排

send_rich 的 parts 是有序列表，每项可以是 dict 或 (kind, value) 元组。

self.sdk.send_rich(chat_id, [
    {"kind": "text",  "value": "公告："},
    {"kind": "at",    "value": {"user_id": "7512049628787802140", "name": "张三"}},
    {"kind": "text",  "value": " 请查看 "},
    {"kind": "link",  "value": {"url": "https://example.com/doc", "text": "这份文档"}},
    {"kind": "emoji", "value": "JOYFUL"},
    {"kind": "img",   "value": image_key},
], account_id=acc)

@人（三种写法）

# 1) 正文内嵌标记，框架自动解析（默认开启）
sdk.send_text(chat_id, "@张三 记得交报表")              # 按群成员昵称解析
sdk.send_text(chat_id, "@{7512049628787802140} 你好")   # 直接给 user_id
sdk.send_text(chat_id, "@all 十分钟后开会")             # @所有人

# 2) 显式传 at 参数
sdk.send_text(chat_id, "记得交报表", at="7512049628787802140")
sdk.send_text(chat_id, "大家好", at=["7512…", "7513…"])
sdk.send_text(chat_id, "全员注意", at="all")

# 3) 富文本里塞 at 元素，可与链接 / 图片混排
sdk.send_rich(chat_id, [
    {"kind": "at",   "value": {"user_id": "7512…", "name": "张三"}},
    {"kind": "text", "value": " 看下这个"},
])

配套方法：

要点：

• 昵称解析走群成员表（chat_member_names，60 秒缓存），按最长命中匹配，避免「小李」命中「李」。
• 解析不到时按原样当 user_id 传，不会发失败；要精确控制就用 @{user_id} 或 at=。
• innerText 会自动补上 @名字，所以通知栏与未读预览也能看到 @ 了谁。
• 不想让正文里的 @xxx 被解析（本身就是文本内容），传 parse_at=False。

上传、文件与图片

发文件 / 图片的入参形态

send_image / send_file / send_video / send_media 的 file 参数都支持：

# 给路径就行
sdk.send_file(chat_id, r"C:\tmp\报告.pdf", account_id=acc)

# 一次上传，多处复用
key = sdk.upload_file(r"C:\tmp\报告.pdf")
sdk.send_file(chat_id, {"key": key, "name": "报告.pdf",
                        "mime": "application/pdf", "size": 102400}, account_id=acc)

# 不关心类型就交给 send_media
sdk.send_media(chat_id, r"C:\tmp\clip.mp4", account_id=acc)

# 只上传不发送
info = sdk.upload_auto(r"C:\tmp\a.png")   # {"file_key": …, "kind": "image", …}

上传与媒体方法

上传行为

• 走飞书文件域 POST /uni_api/upload/file，multipart：data 是元信息 JSON，file 是内容。
• 实测单次全量上传 50MB 稳定（约 7 秒），未走分片链路；框架软上限 200MB，超过直接报错不白传。
• 超时按体积自适应（20 秒 + 1.5 秒/MB），网络类失败自动重试 2 次（退避 1s / 2s）。
• 消息里显示的文件名以「上传时的 name」为准。要让文件名不同，得在上传时指定： upload_file(path, name="季度报告.pdf")，只改 send_file 的 name 无效。
• 视频是独立类型，时长需显式给：send_video(..., duration_ms=8000)，不给客户端显示 0 秒。

成员与群管理

搜索与通讯录

返回结构

搜索结果：{"type": "user" | "bot" | "group", "id", "name", "desc", "avatar_key"}， id 可直接用于 @、create_chat()、add_friend()、invite()。

通讯录：{"id", "user_id", "name", "avatar", "type"}。 user_id 是发消息 / @ / 加好友要用的；id 是头像 key；avatar 是头像直链。 服务端会把同一个人的信息拆成两类条目返回，SDK 已按 user_id 合并。

add_friend 返回 {"ok", "chat_id", "message_id", "reason"}：

r = sdk.add_friend("7171061198375518212", "你好，我是小助手")
# {'ok': True, 'chat_id': '7512049932271435795',
#  'message_id': '7698546570173664273', 'reason': '已建单聊并发送打招呼消息'}

日志、去重与注入

装饰器式回调注册

宿主会自动注册被 override 的钩子；也可以在运行时手动挂载、解绑：

def handle(msg):
    self.log("收到：" + (msg.get("content") or ""))

self.sdk.on_message(handle)          # 运行中追加
self.sdk.unbind_all()                # 解绑全部（on_unload 时宿主会自动调用）

内置保护机制

这些在框架层，插件不用实现，但必须知道，否则会踩坑。

免费版与收费版

授权账号没有激活天数时按免费版运行；有剩余天数或永久授权则是收费版。

插件里如何兼容

两种写法，任选。推荐第二种（先判断版本，能给出更友好的提示）：

from gorobot_sdk import Plugin, SDKError

class Demo(Plugin):
    name = "版本自适应示例"
    version = "1.0.0"

    def on_group_message(self, msg):
        chat_id = msg["chat_id"]
        acc = msg.get("_account")
        ed = self.sdk.edition()          # {'tier': 'free'|'pro', 'features': {...}, ...}

        if ed["tier"] != "pro":
            self.sdk.send_text(chat_id, "[免费版] 发图需升级收费版", acc)
            return
        self.sdk.send_image(chat_id, r"C:\tmp\a.png", acc)

    def on_private_message(self, msg):
        try:
            self.sdk.send_file(msg["chat_id"], r"C:\tmp\报表.pdf", msg.get("_account"))
        except SDKError as e:
            self.sdk.log(f"发送被拦截：{e}", "WARN")
            self.sdk.send_text(msg["chat_id"], "当前版本不支持发文件", msg.get("_account"))

edition() 返回结构：

{
  "tier": "free",                       # free / pro / none
  "label": "免费版",
  "reason": "授权账号未激活天数，按免费版使用",
  "max_accounts": 1,                    # 0 表示不限
  "blocked_send": ["rich", "image", "file", "video", "media", "sticker", "audio"],
  "blocked_names": ["富文本消息", "图片", "文件", "视频", "媒体文件", "表情包", "语音"],
  "features": {"rich": False, "image": False, "file": False,
               "video": False, "multi_account": False}
}

数据目录

self.sdk.data_dir 是宿主为该插件分配的独立目录 （<数据目录>/plugins/<插件ID>/），配置、缓存、下载产物都写这里。 卸载后仍保留，避免污染其它插件。

p = os.path.join(self.sdk.data_dir, "state.json")
with open(p, "w", encoding="utf-8") as f:
    json.dump(self.state, f, ensure_ascii=False)

打包成 exe 后，数据目录为 %LOCALAPPDATA%\GoRoBot\plugins\<插件ID>。

生命周期与分发

导出加固包后，源码不再以明文存在；绑定机器码的包只能在同一台机器上运行， 适合交付给客户但不希望代码外流的场景。

完整插件示例

关键词应答 + @人 + 富文本公告 + 私聊找人 + 收到文件落盘。可直接运行。

import os
from gorobot_sdk import Plugin, SDKError


class Helper(Plugin):
    name = "小助手"
    version = "1.1.0"
    author = "me"
    description = "关键词应答 / @人 / 富文本公告 / 收文件落盘"

    def on_load(self):
        self.log("小助手已启动")

    def on_group_message(self, msg):
        text = (msg.get("content") or "").strip()
        acc = msg.get("_account")
        chat_id = msg["chat_id"]

        if text == "菜单":
            self.sdk.send_text(chat_id, "1) 帮助\n2) 状态", acc)

        elif text.startswith("艾特"):
            # 正文内嵌 @：按昵称解析；@all 全员
            who = text[2:].strip() or "all"
            self.sdk.send_text(chat_id, f"@{who} 你被叫到了", acc)

        elif text == "公告":
            # 富文本混排：@所有人 + 文本 + 链接 + 表情（收费版）
            try:
                self.sdk.send_rich(chat_id, [
                    {"kind": "at_all"},
                    {"kind": "text", "value": " 本周例会改到周五 15:00，详见 "},
                    {"kind": "link", "value": {"url": "https://example.com/notice",
                                               "text": "通知原文"}},
                    {"kind": "emoji", "value": "OK"},
                ], acc)
            except SDKError as e:
                self.sdk.send_text(chat_id, "公告：本周例会改到周五 15:00", acc)
                self.log(f"富文本降级：{e}", "WARN")

        elif text == "发文件":
            try:
                self.sdk.send_file(chat_id, r"C:\tmp\报告.pdf", acc)
            except SDKError:
                self.sdk.send_text(chat_id, "当前版本不支持发文件", acc)

        elif msg.get("msg_type_name") == "FILE":
            # 收到的文件直接落盘（大文件走流式，不整块进内存）
            saved = self.sdk.save_file(msg, self.sdk.data_dir, acc)
            self.log(f"收到文件：{saved}")

        elif msg.get("msg_type_name") == "IMAGE":
            data = self.sdk.message_media(msg, acc)
            if data:
                p = os.path.join(self.sdk.data_dir, f"{msg['msg_id']}.jpg")
                with open(p, "wb") as f:
                    f.write(data)

    def on_private_message(self, msg):
        acc = msg.get("_account")
        txt = msg.get("content") or ""

        if txt.startswith("找人"):
            # 搜索陌生人，把命中的前 3 个告诉用户
            hits = self.sdk.search_users(txt[2:].strip(), account_id=acc)[:3]
            if hits:
                lines = "\n".join(f"{u['name']}（{u['type']}）{u['id']}" for u in hits)
                self.reply(msg, "找到：\n" + lines)
            else:
                self.reply(msg, "没搜到")
        else:
            self.reply(msg, "收到：" + txt)

    def on_event(self, evt):
        if evt.get("source") == "accounts":
            self.log(f"账号事件：{evt.get('text')}")

下一步

• 把插件导出成 .grbp 加固包分发给客户。
• 需要更多底层能力时用 raw_call(cmd, payload) 直接打网关指令。
• 遇到行为异常先看客户端「消息日志」与去重统计，多数问题出在重复投递或回声上。