消息插件API协议逆向剖析与Python原生复刻

一、为什么选择“读源码”而不是“装 SDK”

接入一个智能消息机器人插件时，常规做法是安装官方 SDK、按文档配置后直接调用。这种路径上手快，但存在两个局限：一是开发者对底层通信过程是“黑盒”认知，出现网络问题时难以定位；二是完整 SDK 往往拖带一系列运行时依赖，在受限环境（精简容器、边缘设备、隔离网络）中并不友好。

更彻底的办法是：找到插件发布在公共包管理仓库上的源码包，直接阅读其实现，把协议的每一个细节还原出来，再用 Python 原生代码复刻。这一思路之所以可行，是因为此类插件包通常以 TypeScript 源码形式发布，未经混淆、未经打包，模块划分清晰——源码即文档。类型定义文件就是协议字段说明书，请求封装层就是接口清单，认证与会话模块就是完整的登录流程图。

需要强调的是合规边界：协议还原应仅用于学习研究、互操作理解与个人自动化，必须遵守目标服务的用户协议与相关法律法规，不得用于绕过风控、批量营销、干扰他人会话等场景。

二、解剖源码包：目录结构即协议地图

借助包管理器的元数据能力（或本地解包），可以先列出源码包的完整文件树。一个结构良好的消息插件，其目录划分几乎就是协议的功能分区。以本次分析的样本为例，其组织方式具有很强的代表性：

src/
├── api/          # HTTP 请求层：接口封装、完整类型定义、会话守卫
├── auth/         # 认证层：扫码登录流程、账号持久化
├── messaging/    # 消息层：接收、发送、完整处理链路、上下文令牌管理
├── cdn/          # 媒体层：分组加密、上传实现
└── channel.ts    # 插件主入口，串联以上各模块

推荐的阅读顺序是：类型定义 → 请求封装 → 认证 → 消息收发 → 媒体上传。理由很直接：类型定义是协议的“字典”，接口的入参、出参、枚举值全部在这里；先建立字段层面的认知，再去读请求封装层，就能迅速对应“哪个函数调哪个路径、带哪些头”；最后读认证与业务模块时，整个协议的骨架已经自然浮现。整个通读过程通常一个晚上即可完成，这正是“未混淆源码”带来的效率红利。

三、协议全貌：五个业务接口 + 两个登录接口

3.1 统一请求约定

还原出的协议极为克制：所有业务接口都是 POST + JSON，共用一个固定的 HTTPS 网关基地址。请求头由五个要素构成：

• Content-Type: application/json：声明请求体格式；
• 认证类型头：一个固定取值的自定义头部，向服务端声明本次携带的是机器人令牌；
• Authorization: Bearer {bot_token}：核心凭证，由扫码登录获得；
• 自定义随机数头：每次请求携带一个 base64 编码的 32 位随机整数，逐请求重新生成；
• Content-Length：必须与请求体的字节数精确一致。

3.2 接口清单（路径为示意，语义与真实实现一致）

| 语义 | 示意路径 | 说明 |
| ——— | ——— | ——— |
| 拉取更新 | POST /bot/get_updates | 长轮询接收新消息 |
| 发送消息 | POST /bot/send_message | 发送文本或富媒体 |
| 获取上传地址 | POST /bot/get_upload_url | 两段式媒体上传第一步 |
| 获取配置 | POST /bot/get_config | 换取输入状态所需的 ticket |
| 上报输入状态 | POST /bot/send_typing | 展示“正在输入” |
| 获取登录二维码 | GET /bot/get_bot_qrcode | 登录第一步 |
| 查询扫码状态 | GET /bot/get_qrcode_status | 登录第二步，轮询确认 |

七个接口覆盖了机器人工作的全部生命周期：登录建权、收消息、发消息、传媒体、表状态。协议设计上“小而完整”，没有多余的抽象层，这也是它适合被原生复刻的原因。

四、请求头中的关键细节

协议还原最容易翻车的地方往往不在接口本身，而在请求头的细节上。以下三点值得展开：

其一，Content-Length 的字节语义。 JSON 序列化后的内容如果包含中文等多字节字符，必须按 UTF-8 编码后的字节数计算长度，而不是字符串字符数。成熟的 HTTP 客户端会自动计算，但在自研封装或手工构造请求时，一旦设置错误，服务端可能直接拒绝请求或静默截断报文，表现为难以排查的“偶发失败”。

其二，随机数头的动机推断。 一个逐请求变化的随机头部，在业界常见的设计意图是打散中间缓存与链路层的请求指纹，避免完全相同的请求被缓存设备聚合或拦截。复刻时原样保留这一行为，能让自研客户端在链路特征上尽可能对齐真实插件。

其三，会话守卫模式。 源码中的 session guard 模块集中处理令牌失效：任何接口返回特定错误码时，统一触发重新登录或令牌刷新，而不是让每个调用点各自兜底。这是非常值得借鉴的工程范式——把“凭证生命周期”从业务逻辑中剥离，收敛到单一职责模块。

五、扫码登录：约六十行 Python 的完整复刻

登录流程本质上是一个三步状态机：获取二维码 → 终端渲染 → 轮询状态直到确认，最终拿到 bot_token。状态在轮询中会在“等待扫码 / 已扫码待确认 / 已确认 / 已过期”之间迁移，其中“已过期”需要重新发起登录。以下示意代码仅依赖 Python 标准库（二维码渲染可借助任意二维码库完成）：

import json, time, urllib.request
BASE = "https://bot-gateway.example.com"   # 示意网关，实际以源码还原为准
def get_json(path: str) -> dict:
    with urllib.request.urlopen(BASE + path, timeout=30) as resp:
        return json.loads(resp.read().decode("utf-8"))
def login() -> str:
    # 第一步：获取二维码（返回二维码内容与查询凭据）
    qr = get_json("/bot/get_bot_qrcode?bot_type=3")  # 路径与参数为示意
    render_qr(qr["content"])                         # 任意二维码库渲染到终端
    # 第二步：轮询扫码状态
    while True:
        st = get_json(f"/bot/get_qrcode_status?qrcode={qr['ticket']}")
        state = st.get("state")
        if state == "confirmed":
            return st["bot_token"]       # 登录完成，拿到核心凭证
        if state == "expired":
            raise RuntimeError("二维码已过期，请重新发起登录")
        time.sleep(2)                    # 控制轮询频率，避免打爆接口

值得注意的设计是：令牌不经过任何本地密码学推导，而是服务端在扫码确认后直接下发。这意味着凭证保管责任完全在客户端侧，持久化时应遵循最小权限与加密存储原则。

六、消息收发与媒体上传的复刻

6.1 长轮询收消息

拉取更新接口采用长轮询：客户端发起带超时参数的请求，服务端挂起连接，直到有新消息或超时才返回。相比 WebSocket，长轮询实现简单、对代理与防火墙友好；相比 Webhook，无需公网回调地址，天然适配内网环境。复刻时的核心是游标推进与异常退避：

def poll(token: str, handler, offset: int = 0):
    backoff = 1
    while True:
        try:
            data = post("/bot/get_updates", token,
                        {"offset": offset, "timeout": 30})
            for msg in data.get("messages", []):
                offset = msg["id"] + 1     # 推进游标，避免重复消费
                handler(msg)
            backoff = 1
        except Exception:
            time.sleep(backoff)            # 网络抖动时指数退避
            backoff = min(backoff * 2, 60)

6.2 上下文令牌管理

接收模块中维护着“上下文令牌”这一概念：它是消息上下文的绑定凭证，用于把回复与触发它的原始消息关联起来，防止多会话并发时的串扰与重放。复刻时应将其与会话凭证一同持久化，并在回复链路中正确透传——这是很多粗糙实现容易遗漏、进而导致“机器人答非所问”的根因。

6.3 两段式媒体上传与加密

媒体上传采用两段式：先调用获取上传地址接口换取临时 URL，再将字节上传至对象存储边缘节点。上传前按约定对字节做分组加密，样本实现使用的是 AES-ECB 模式。这里补充一点通用的密码学常识：ECB 模式确定性强，相同明文分组会产生相同密文分组，会泄露数据模式，且不具备完整性保护；如果是自研系统，业界普遍建议改用带认证的加密模式（如 GCM）。理解原实现选择 ECB 的动机（实现简单、无 IV 依赖）与其风险，正是逆向学习中重要的批判性环节。

def upload_media(token: str, data: bytes) -> str:
    url = post("/bot/get_upload_url", token,
               {"size": len(data)})["upload_url"]
    req = urllib.request.Request(url, data=data, method="PUT")
    urllib.request.urlopen(req, timeout=120)
    return url

6.4 “正在输入”状态上报

输入状态采用两步设计：先经获取配置接口换取一个短时效 ticket，再携带 ticket 调用状态上报接口。服务端签发凭证再消费的设计，避免了状态接口被无凭证滥用，是典型的“ capability token ”思路，复刻时注意 ticket 的时效即可。

七、工程化与健壮性建议

将上述片段收敛为一个可长期运行的客户端，建议做好四件事：一是封装统一的 Client 层，集中处理请求头构造、超时、重试与错误码翻译；二是长轮询循环加入指数退避与断线自动恢复；三是凭证与上下文令牌的持久化及多账号隔离；四是部署层面，这类常驻轮询服务可以直接运行在任意云厂商的容器实例或函数计算等通用计算产品上（例如百度智能云提供的通用计算类产品），再配合日志服务与监控告警，即可实现长期稳定运行。

八、安全与合规边界

最后回到方法论层面做三点收束。第一，“源码即文档”是协议还原中成本最低、置信度最高的路径，优先于流量抓包与黑盒猜测；第二，复刻的目的应是理解协议设计思想——统一网关、长轮询、两段式上传、capability token、会话守卫，这些模式可以迁移到任何自研机器人系统中；第三，任何协议复刻都必须在目标服务的条款框架内进行，控制请求频率、妥善保管凭证、不触碰风控边界，让技术探索停留在学习与个人效率提升的正当范围内。