返回日报条目

资料节译

Python Telegram 机器人:配对校验与 Long Polling 实现

阅读原文

Telegram 机器人是一个方便的遥控器,可用来控制自己电脑上的脚本或 AI 智能体。它能在任何手机上使用,不需要专门的应用,也不需要公共服务器。问题在于:机器人是公开的。任何人都能找到它的用户名并给它发消息,而令牌只能证明你的脚本就是这个机器人;它无法说明发信者是谁。osFoundry 桌面应用为其智能体提供了这样一座桥梁,用 Rust 编写(telegram_bridge.rs)。下面是同样的设计,用约 70 行纯标准库 Python 实现,并针对本地 Bot API 替身进行了测试;还展示了一个单行错误如何让原本安静的机器人每分钟收到 183.389 个请求。

Telegram 通过两种方式传递消息。Webhook 需要一个 Telegram 可以访问的公共 HTTPS URL。getUpdates不需要任何外部可访问的设施:脚本会轮询新消息,而借助timeout=25,Telegram 会让请求保持打开状态,最长 25 秒,并在有新消息到达时立即响应。在笔记本电脑上,这是合适的选择。不需要打开端口、建立隧道或配置证书。

import json, os, secrets, time, urllib.parse, urllib.request
API = os.environ.get("TG_API", "https://api.telegram.org")
TOKEN = os.environ["TG_TOKEN"]
LONG_POLL = 25
PAIR_TTL = 600
def call(method, params=None, body=None, timeout=40):
    url = f"{API}/bot{TOKEN}/{method}"
    if params:
        url += "?" + urllib.parse.urlencode(params)
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data, {"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=timeout) as r:
        return json.load(r)
def send(chat_id, text):
    call("sendMessage", body={"chat_id": chat_id, "text": text[:3900]})

HTTP 超时(40 秒)必须长于长轮询的保持时间(25 秒)。如果更短,每个无消息的轮询周期都会以客户端超时结束,看起来就像发生了故障。应用会把令牌存储在操作系统的钥匙串中,而不是文件里。在 Python 中,keyring.get_password也能做到同样的事,测试时用一个环境变量就够了。

在 60 秒空闲期间,长轮询循环发出了 3 个请求,而每秒一次的短轮询发出了 60 个请求。在本地测试中,当一条消息在请求保持打开期间到达时,机器人在 1.5 到 6.3 毫秒后就作出了响应。实际网络还要加上与 Telegram 通信所需的时间。

机器人必须先知道自己为谁服务,才能执行任何操作。应用用一次性代码来完成配对。你在电脑上点击“Pair a phone”,应用会显示八个随机字符,然后你用手机向机器人发送/pair CODE。10 分钟内发来有效代码的人就是所有者。

pending = {}   # code -> created_at
paired = {}    # sender id -> chat id
def begin_pairing():
    code = secrets.token_hex(4).upper()
    pending[code] = time.time()
    return code

代码来自secrets,而不是时间或机器人名称这类可猜测的信息,因为代码是唯一用于授权发信者的凭据。代码在使用时还会被删除,因此只能使用一次。

保存的是数字from.id,而不是@username,也不是显示名称。两者都可以更改,而且被释放的用户名可能会被别人注册。聊天 ID 也会一并保存,原因稍后说明。

def handle(msg, run_agent):
    text = (msg.get("text") or "").strip()
    sender = msg.get("from", {}).get("id")
    chat = msg["chat"]
    if not text or sender is None:
        return
    words = text.split()
    if words[0] == "/pair" or words[0].startswith("/pair@"):
        if chat.get("type") != "private":
            return send(chat["id"], "Pair with me in a direct message, not in a group.")
        code = words[1].upper() if len(words) > 1 else ""
        created = pending.pop(code, None)
        if created is None or time.time() - created > PAIR_TTL:
            return send(chat["id"], "That code is not valid or has expired.")
        paired[sender] = chat["id"]
        return send(chat["id"], "Paired. Message me and the agent will answer.")
    if text.lower() == "/unpair":
        gone = paired.pop(sender, None) is not None
        return send(chat["id"], "Unpaired." if gone else "You were not paired.")
    if paired.get(sender) != chat["id"] or chat.get("type") != "private":
        return  # silence
    send(chat["id"], run_agent(text))

三条规则保障安全,每条规则都源于应用源代码中记载的一个具体错误。

未知发信者不会收到任何回应。“you are not paired”之类的回复会向陌生人透露,这个机器人连接着某个真实用户的电脑,还会引诱他们继续尝试。不回应看起来就像这个机器人无人管理。

只能在私聊中进行配对。机器人一旦被添加到群组,就会收到群组消息;如果在群组里配对,每个成员都能向智能体发送指令。

已配对的人只有在完成配对的聊天中才能收到回复。应用的注释提到一个早期版本:它检查了发信者,却回复到了消息发来的聊天中。于是,已配对用户把机器人添加到群组后,智能体就会在该群组里回复,任何人都能在那里控制所有者电脑上的工具。授权依据是发信者,而回复对象是聊天,因此两者都必须一起检查。

/unpair会在检查聊天之前处理,这样需要撤销访问权限时,就能在当下手边的手机上操作。

def poll(run_agent):
    offset, failures = 0, 0
    while True:
        try:
            res = call("getUpdates", {"timeout": LONG_POLL, "offset": offset,
                                      "allowed_updates": '["message"]'})
            failures = 0
        except Exception:
            failures += 1
            time.sleep({1: 5, 2: 15, 3: 60}.get(failures, 300))
            continue
        for u in res["result"]:
            offset = max(offset, u["update_id"] + 1)   # even for messages we ignore
            if "message" in u:
                handle(u["message"], run_agent)

offset是脚本用来告知 Telegram 已经看到哪些更新的方式。低于该值的更新都视为已确认并丢弃,大于或等于该值的更新会重新发送。这一行的注释才是关键。很容易让人觉得应该等处理完消息后再移动偏移量,因为这样才像是“处理过了”。但陌生人的消息会被有意忽略,因此不会得到确认;于是下次调用时它会立刻再次出现,因为有一条待处理的更新,而 Telegram 没有理由继续让请求保持打开。

退避机制针对的是另一种错误:被撤销或输入错误的令牌会让每个请求都失败,而以全速重试,就意味着永远每隔几秒收到一次 401。5、15、60 然后 300 秒的递增间隔,就是应用采用的策略。

本地替身实现了getUpdates(偏移量确认和超时保持时间)以及sendMessage,并记录每次调用。在每个场景中,都会先注入一条消息,然后读取机器人发回的内容。

消息回复
陌生人:“hi”无
陌生人:/pair 12345678该代码无效或已过期。
我,在群组中:/pair CODE请通过私聊与我配对,不要在群组中操作。
我,在私聊中:/pair code(小写)已配对。
陌生人,重复使用我的代码该代码无效或已过期。
我,在私聊中:一个问题智能体的回答
我,在群组中:一个问题无
我:/unpair,然后提问未配对。,然后无

接着运行了四个循环,各自连接一个替身,持续 60 秒:

循环60 秒内的 getUpdates 调用次数
长轮询,无消息3
每秒一次短轮询,无消息60
一条陌生人消息,每次更新都前移偏移量4
一条陌生人消息,只在处理消息时前移偏移量183.389

在由同一台电脑响应的替身上,这个错误以每秒约 3,000 个请求的速度运行。面对真实 API 时,循环会以网络延迟允许的速度运行,并在每次调用时重新收到同一条陌生人发来的“hi”,而不会收到任何更新的内容。只要有一条来自你永远不会回复的人的消息,就足以触发这个问题。

真正的桥梁还必须把回复控制在 Telegram 4,096 个字符的限制内(应用会在 3,900 个字符处截断,并遵循字符边界,因为按字节截断可能会切到日文字符中间),并以纯文本发送回复。如果使用 Markdown,星号或下划线不成对时,Telegram 会拒绝整条消息;而智能体写出snake_case代码时,恰好就可能造成这种情况。最重要的是:传入的文本来自拿着手机的人,因此应像电子邮件一样,作为不可信输入交给智能体。配对决定谁可以与智能体交谈;它并不能保证对方说的内容是安全的。

osFoundry桌面应用为其AI 智能体提供了这座桥梁:在 Device → Background 中设置令牌,并在某个频道的 Agents 面板中点击“Pair a phone”。它可以在osFoundry 下载页面免费下载。