一个 PR 修掉三个安静的 gateway bug:写错的变量弄死了回复、脱敏吃掉了 job key、导入把 sys.path 搅了


告警路由把一条消息投进了错误的队列。你打开日志找那个 job key,看到的是 ITEM-000042:***。那显然是脱敏干的,于是你去查配置:security.redact_secrets、厂商密钥前缀、bearer token 规则,一项一项都对。看到第二遍才看出真正的形状——它根本没匹配到任何密钥。正则从一个普通标识符的中间开始匹配,把结尾那串数字当成了凭证,顺手把整个 key 一起吞了。

三个 bug,同一层

gateway 是 Desktop 背后、也是所有聊天平台接入背后的那个进程。平台适配器——Telegram、WhatsApp、Discord、Slack、Raft——是夹在这个进程和各家网络 API 之间的薄翻译层。它们做三件很平常的事:从环境里读配置、往日志里写会被脱敏过滤器扫过的行、从仓库里导入兄弟模块。三件平常事,三个 bug。

三个修复来自同一个 gateway 层的 PR(#151738,2026-11-09 合入)。它们看起来毫无关系,某种意义上确实没有。但它们同处一层,而且脾气一样:出故障的地方,永远不是出错的地方,所以它们从来不会以「一条你能搜到的报错」的形式出现。

这也是这类缺陷难查的第一个原因。适配器里的回归不会表现得像适配器的问题:它看起来像一个坏掉的 job key,一个突然不理人的机器人,或者一个版本号忽然报错的库。你第一个小时花在了错误的文件上。

第一个:.env 里错一个字符,整条回复死掉

Telegram 的「忙时跟进」路径需要知道等多久,才能判断新来的这条消息是真正的跟进,还是正在进行的那轮对话的一部分。这个值来自 HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS,而代码当时直接拿它做浮点转换。

于是 abc 这种值——一个手滑、一个占位符残留、或者一个「3s 读起来更顺」——在 run_inbound.py:697 抛出了 ValueError: could not convert string to float: 'abc'。这个异常没有在边界上被接住,它把整个 inbound handler 一起掀了,结果是用户那条消息一条回复都没有。不是跟进晚了几秒,是这一轮直接死掉。

修法是把这次读取改走 gateway.run._float_env,也就是那个模块里其它超时参数早就在用的辅助函数。坏值不再抛错,回落到 3 秒,跟进消息照常排队,agent 继续干活。

# 错的:这三种都是字符串,不是数字
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3s
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=
# 对的:一个纯数字,单位是秒
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3

为什么它藏得住:这条路径只在「一轮还在跑、用户又发了一条」的时候才会走到,绝大多数测试碰不到。而它一旦触发,症状表现为「机器人不理我」——于是人先去查 token,再查 webhook,再查网络,没人会想到几周前自己敲的一个配置值。环境变量本身没有类型系统,在解析它的那一行执行之前,没有任何东西会校验它。

第二个:脱敏从词中间开始匹配

脱敏是带承诺的模式匹配:找到密钥,别碰其它东西。坏就坏在后半句,而且坏得很安静。

正则不知道什么叫「词」。除非你明确告诉它只能从边界开始,否则任何满足模式的字符都可以成为匹配的起点。旧的 Telegram 脱敏模式 _TELEGRAM_RE 就愿意从一个 ASCII 标识符的中间开始——具体说,从它尾部那串数字开始。于是一个普通的 job key(长得像 ITEM-000042:job-a12345678:q- 后面接一长串 a),从中段被匹配上,然后整段被替换成了 ***。

没有异常,没有告警。日志行少了一个 key,值班的人少了二十分钟。

修法是收窄「匹配可以从哪里开始」:只能从标识符边界开始,或者从一个固定宽度的转义分隔符之后开始(\n、\uXXXX、%XX 这一类适配器真的会产出的东西)。那个用来防止扫描器在一长串数字上反复回走的数字串 lookbehind 保留了下来——把它删掉,脱敏就会在一串长数字上退化成二次复杂度。

顺带有一条测试断言被放宽了,原因值得知道:main 上处理 JSON key 名的逻辑现在会先把 credential 的值屏蔽掉,再处理 key 名,所以「key 名应该原样出现」这条断言已经不再描述代码的真实行为了。这是测试在追一次有意的改动,不是把窟窿糊上。

这个教训不限于这个仓库。如果你的脱敏规则是一串正则,而其中没有一条在边界上锚定,那你不是「没有脱敏 bug」,你只是还没遇到第一个以八位数字结尾的标识符。

第三个:导入适配器会重排导入路径

一句话解释 sys.path:它就是 Python 在你写 import something 时,从前到后依次翻的那张目录清单,第一个翻到的目录赢。位置 0 高于一切,包括正正规规装进环境里的包。

以前安装任何平台适配器——telegram、whatsapp、discord、slack、raft,还有 gateway.platforms.base、cron.scheduler、tools.cronjob_tools——都会把仓库目录插到 sys.path[0]。从那一刻起,任何同时存在于仓库和环境里的模块名,都会解析到仓库那份。

PR 里的复现很干净:先导入真正的 evals 包,再导入一个适配器,然后重新 import evals——它绑定到了仓库自己的 evals 目录,而不是装好的那个发行版。修之前 10 次全红,修之后 10 次全绿。适配器现在完全不动 sys.path 的顺序。

这是三个里面最安静的一个。没有异常、没有警告、没有弃用提示。导入成功,返回一个对象——只是这个对象和进程里其它代码路径以为的那个不是同一个。任何依赖「装好的那个发行版」身份的东西(版本元数据、entry points、插件发现)都开始返回属于另一个包的答案;而症状会出现在当初查询那个模块的子系统里,离挪动路径的那个适配器十万八千里。

一个值得养成的习惯:启动时给所有有分量的模块打一行 module.__file__。一行代码,能在第一次就抓住这一整类 bug,而不是等到第三次。

前后对照:四行 probe,说人话

PR body 里带了一张简短的对照表。去掉测试框架,实际变化就是这样:

探针 修之前 修之后
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc,一轮对话进行中又收到消息 ValueError 把回复打断 坏值回落到 3 秒,跟进照常排队
一个普通 job key,形如 ITEM-000042:job-a12345678:q- 后接一长串 a 整个 key 变成 *** key 原样留在日志里
同一段日志里的一条真实凭证 被屏蔽 仍然被屏蔽
导入了适配器之后 import evals,而 evals 是从 PyPI 装的 绑定到仓库那份,10 次全中 绑定到装好的包,10 次全中

第三行和第二行一样重要。把模式收紧很容易;收紧的同时不丢掉它原本保护的东西,才是真正的工作量,而这一行是你在信任任何脱敏改动之前应该先看的。

在你自己的安装上验一下

两个检查,各跑一次就够,因为这两个 bug 在咬到你之前都是隐形的。

# 这个解释器实际解析到的 `evals` 是哪一个?
python3 -c "import evals; print(evals.__file__)"

# 确认跟进宽限值是个纯数字
grep -n FOLLOWUP_GRACE .env

第一行如果打印的是你 checkout 里的路径而不是 site-packages 里的,那你看到的就是上面描述的那个故障。第二行对应的值现在即便不是数字也不会抛错了,只会静默回落到 3 秒默认值——但静默回落仍然是错误配置,该改值还是得改,别指望兜底。

脱敏那一半:在自己日志里 grep ***,然后读它周围的几行。被屏蔽的 Authorization 头说明系统在正常工作;被屏蔽的 job key、request id、trace id 说明系统干得太卖力了,而这个靠翻配置是翻不出来的。

谁修了什么

三个修复,三个来源,一起合入:

  • 脱敏边界修复(#145664)从 @liuhao1024 的版本 cherry-pick,@yuzilongleif-collab 补了补丁。
  • 跟进宽限修复(#50120)从 @Bartok9 的 #51324 cherry-pick。
  • sys.path 修复(#117698)基于 @beardthelion 的 #117699。

一句话总结

一个 bug 有多难查,大致等于它的症状离病因有多远。环境变量里一个写错的浮点数,看起来像机器人坏了;一条从词中间开始匹配的正则,看起来像脱敏在正常工作;一个被重排的导入路径,看起来像导入成功了。

比起这三个补丁,更值得带走的是那三个检查习惯:给自己依赖的模块打 __file__;别让配置值不经兜底就进解析器;每条脱敏正则都在边界上锚定,并回头读一遍它上次到底匹配到了什么。这三个 bug,任何一个习惯都能在几分钟内抓住。

相关阅读:日志里的一条 Cookie 就是你的登录态、一个 Telegram 409 以前要付多大代价、阻塞调用是怎么把 gateway 事件循环冻住的,以及这几个环境变量所在的配置参考。