记录一次黑窗口的排查（2026-06-01）

如果你发现自己在打补丁，先退一步：上游修了吗

那天要解决的毛病很小——小到可以忍，但每次都在提醒你它的存在。

那个一闪而过的黑窗口

现象是：每执行一次终端命令，屏幕上就闪一下黑色的 cmd 窗口。

它不影响结果，命令照跑，输出也正常。但一天下来闪几百次，人会烦。更要命的是它给人一种"这东西没做干净"的感觉。

查下来是本地装的 Hermes 0.14.0（v2026.5.16，2026-05-18 发布）的一个已知 bug：Windows 上每次调用终端都会弹一个控制台窗口。

先查上游，再动手改

第一反应当然是"把弹窗的地方关掉"——找到 Popen 的调用点，加个 Windows 专用的隐藏标志就行。

但我先多做了一步：去看看上游有没有修。

结果很干脆：这个 bug 在 0.15.0（v2026.5.28）里已经修了，做法是加了一个 windows_hide_flags() 的辅助函数。而当时 PyPI 上最新是 0.15.2（v2026.5.29.2）——本地落后了整整两个补丁版本。

那正确的修法就只有一条：

1	pip install --upgrade hermes-agent

不是自己去改源码。

这一步看起来简单，但它其实是个分水岭。如果我当时直接动手打补丁，会有两个后果：

我改的是旧版本，问题在上游早就解决了
我打的补丁会覆盖掉未来的升级——下次升级还得先记住"这里有个我自己改的地方"

自己动手改上游代码，最贵的不是改的成本，是**以后每次升级都要重新想一遍"我改过什么"**。

一条更通用的排查方法

那天顺手把一套"本地装的到底是不是最新"的查法沉淀了下来。

常规做法是去查 GitHub API，但未认证的情况下一小时只有约 60 次请求——稍微折腾几轮就见底了。

更好的办法是直接对着 raw 内容比：

1	raw.githubusercontent.com/<repo>/<tag>/<path>

它不需要认证，也没有限流。把本地 site-packages 里的文件和对应 tag 上的原始文件拉下来一比，就知道本地到底是哪个版本、有没有被改动过。

这个小技巧后来一直在用。凡是要判断"我装的这个是不是旧的""这个 bug 修了没有"，第一反应就是它。

顺便办了两件事

那天除了修窗口，还顺手处理了两个相关的：

一是 OpenViking 的账号结构。 确认了当前的版本（0.3.17）运行正常，底下挂着 default、wu-account、memtest 几个账号空间。同时给 wu 这个用户建了正式的访问密钥——account: default、user: wu、role: admin，密钥本身就隐含绑定了账户和用户，直接当 x-api-key 用就行，不用再额外带头。

二是升级卡住了。 想往 0.3.21 走，但一直报 EmbeddingRebuildRequiredError，也就是向量重建过不去。这条没解决，只能先记下"卡在这里，需要联系上游"。

有意思的是，这件事和黑窗口刚好是两个方向的对照组：黑窗口是"上游已经修好了，你只要升级"；而这次是"上游还没好，你只能等"。先查上游这个动作，对两种情形的价值是一样的——一个让你省掉白干，一个让你省掉瞎猜。