访客模式
从 v2.1.0 起,koipy 支持以 访客模式(Guest Mode) 参与测试。
什么是访客模式
访客模式是 Telegram 官方推出的一种 bot 交互方式。开启后,bot 不需要被拉进群组、也不需要任何管理权限,只要有人在聊天里 @ 它或者回复它的消息,bot 就会收到一条专用的更新,并可以直接在该聊天里回复。
这与传统的使用方式不同:
- 传统模式:需要先把 bot 拉进群,并且赋予它读取消息的权限
- 访客模式:不加入群组,不读取历史消息,被召唤时才会收到上下文并作出一次回复
对 koipy 而言,这意味着用户可以直接在任意群里 @ 一下 bot 并附上测试指令,就能发起一次完整的节点测试,无需任何前置操作。
说明
访客模式不会授予 bot 对消息历史和成员列表的访问权限,因此 koipy 只会在被召唤的那一条消息上工作。关于该特性的官方说明,参见 Telegram 官方文档。
前置条件
访客模式需要在 BotFather 侧开启,开启后无需在 koipy 配置里做额外设置:
- 打开 BotFather 的 MiniApp
- 进入你的 bot 设置页
- 启用 Guest Mode
注意
访客模式是 Telegram 平台侧的能力,需要TG客户端支持。在尚未支持该特性的客户端上,bot 不会收到访客更新。
使用方式
在任意聊天中 @ 你的 bot,并跟上测试指令即可:
text
@koipybot /test TAG也可以回复 bot 的消息来触发,此时会带上被回复消息的上下文。支持的指令与普通模式一致:
text
@koipybot /speed
@koipybot /topo
@koipybot /uspeed
@koipybot /test?s=local引用一条文档消息后 @ bot,同样可以进行文档测试。
交互流程
访客模式下 bot 只能发出一次回复,因此整个测试流程是通过编辑同一条内联消息来完成的:
- bot 先回复一条消息,其中包含当前阶段需要选择的内容
- 用户在按钮上完成选择:后端 → 排序 → 测试项
- 三阶段都确定后,任务自动开始执行
- 进度条与最终测试结果会持续更新在同一条消息里
如果指令里已经用参数指定了后端或排序,对应的选择阶段会被自动跳过,直接进入下一阶段。
与普通模式的区别
| 项目 | 普通模式 | 访客模式 |
|---|---|---|
| 是否需要入群 | 需要 | 不需要 |
| 消息历史 | 可读取 | 不可读取 |
| 回复次数 | 不限 | 被召唤后仅一次(后续通过编辑消息呈现) |
| 实时渲染 | 支持 | 不支持 |
/invite 邀请测试 | 支持 | 不支持 |
| 文档测试 | 支持 | 支持(需引用文档消息) |
注意
访客模式不支持实时渲染。如果在指令参数或规则里指定了 realtime=true,bot 会直接拒绝这次测试并提示原因。
权限与许可证
访客消息同样要走鉴权流程,只有管理员或已授权用户才能发起测试。鉴权失败时,bot 会通过访客回复的通道把提示回显出来。
许可证方面也有额外约束:
- 标准版许可证:仅在私聊中允许发起访客测试;在群组里发起时会被拒绝,并提示「您的激活码不适用于公开测试」
- 内测版许可证:不受上述限制
- 赞助版许可证:不受上述限制
频率限制
访客消息与普通消息共用 bot.echoLimit 的频率限制。由于访客消息走的是独立的更新通道,该限制对访客消息同样生效,可以避免被高频调用刷屏。
日志与审计
每一次访客任务的提交都会写入一条 INFO 级别的日志,包含发起人、用户名、会话 ID、任务 ID 与指令名,便于后续审计与排查滥用:
text
[guest] task submitted: actor=... username=... chat=... task_id=... site=... command=...