Skip to content

访客模式 ​

从 v2.1.0 起,koipy 支持以 访客模式(Guest Mode) 参与测试。

什么是访客模式 ​

访客模式是 Telegram 官方推出的一种 bot 交互方式。开启后,bot 不需要被拉进群组、也不需要任何管理权限,只要有人在聊天里 @ 它或者回复它的消息,bot 就会收到一条专用的更新,并可以直接在该聊天里回复。

这与传统的使用方式不同:

  • 传统模式:需要先把 bot 拉进群,并且赋予它读取消息的权限
  • 访客模式:不加入群组,不读取历史消息,被召唤时才会收到上下文并作出一次回复

对 koipy 而言,这意味着用户可以直接在任意群里 @ 一下 bot 并附上测试指令,就能发起一次完整的节点测试,无需任何前置操作。

说明

访客模式不会授予 bot 对消息历史和成员列表的访问权限,因此 koipy 只会在被召唤的那一条消息上工作。关于该特性的官方说明,参见 Telegram 官方文档。

前置条件 ​

访客模式需要在 BotFather 侧开启,开启后无需在 koipy 配置里做额外设置:

  1. 打开 BotFather 的 MiniApp
  2. 进入你的 bot 设置页
  3. 启用 Guest Mode

注意

访客模式是 Telegram 平台侧的能力,需要TG客户端支持。在尚未支持该特性的客户端上,bot 不会收到访客更新。

使用方式 ​

在任意聊天中 @ 你的 bot,并跟上测试指令即可:

text
@koipybot /test TAG

也可以回复 bot 的消息来触发,此时会带上被回复消息的上下文。支持的指令与普通模式一致:

text
@koipybot /speed
@koipybot /topo
@koipybot /uspeed
@koipybot /test?s=local

引用一条文档消息后 @ bot,同样可以进行文档测试。

交互流程 ​

访客模式下 bot 只能发出一次回复,因此整个测试流程是通过编辑同一条内联消息来完成的:

  1. bot 先回复一条消息,其中包含当前阶段需要选择的内容
  2. 用户在按钮上完成选择:后端 → 排序 → 测试项
  3. 三阶段都确定后,任务自动开始执行
  4. 进度条与最终测试结果会持续更新在同一条消息里

如果指令里已经用参数指定了后端或排序,对应的选择阶段会被自动跳过,直接进入下一阶段。

与普通模式的区别 ​

项目普通模式访客模式
是否需要入群需要不需要
消息历史可读取不可读取
回复次数不限被召唤后仅一次(后续通过编辑消息呈现)
实时渲染支持不支持
/invite 邀请测试支持不支持
文档测试支持支持(需引用文档消息)

注意

访客模式不支持实时渲染。如果在指令参数或规则里指定了 realtime=true,bot 会直接拒绝这次测试并提示原因。

权限与许可证 ​

访客消息同样要走鉴权流程,只有管理员或已授权用户才能发起测试。鉴权失败时,bot 会通过访客回复的通道把提示回显出来。

许可证方面也有额外约束:

  • 标准版许可证:仅在私聊中允许发起访客测试;在群组里发起时会被拒绝,并提示「您的激活码不适用于公开测试」
  • 内测版许可证:不受上述限制
  • 赞助版许可证:不受上述限制

频率限制 ​

访客消息与普通消息共用 bot.echoLimit 的频率限制。由于访客消息走的是独立的更新通道,该限制对访客消息同样生效,可以避免被高频调用刷屏。

日志与审计 ​

每一次访客任务的提交都会写入一条 INFO 级别的日志,包含发起人、用户名、会话 ID、任务 ID 与指令名,便于后续审计与排查滥用:

text
[guest] task submitted: actor=... username=... chat=... task_id=... site=... command=...

文档内容同步自 koipy-public