截图明明还在,Hermes 却说找不到文件:文件名里藏着一个看不见的空格


你把刚截的图拖进对话框,让 Hermes 看一下报错信息。文件保存成功,路径也打印出来了,但它打开图片的那一步失败了:media file not found。你去 Finder 里看一眼——文件好端端在那里,名字也对得上。

问题出在“对得上”这三个字。macOS 给截图命名时,AM/PM 前面那个空格不是普通空格,而是 U+202F(窄不换行空格)。它在屏幕上和普通空格长得一模一样,宽度略窄一点点,肉眼基本看不出区别。模型把这串名字重打一遍的时候,输出的必然是普通空格 U+0020——两个字节不同,路径自然指向一个不存在的文件。

PR #154046(2026 年 11 月 12 日合并)让视觉分析、视频分析和图像/视频生成都自己去找磁盘上的真实写法。

一个字符导致的失败链

完整链条是这样的:

  1. 你(或工具)把文件路径写进上下文:Screenshot 2026-11-12 at 9.51.42 AM.png。这里面第 26 个字符是 U+202F。
  2. 模型读到的字符串是“看起来正常”的,但它生成新文本时,输出的空格一律是 U+0020。
  3. 图片查看器拿这个路径去 open(),操作系统按字节比较,找不到文件。
  4. 报错信息只说 media file not found——它不会告诉你“有一个参数差了一个字节”。

最难受的是它看起来像权限问题或者路径问题,于是你会去查路径、查权限、查沙箱,而真正的原因是一个你看不见的字符。

顺带一句:read_file 其实早就能处理这种情况了。所以当时的体验很割裂——同一个文件,read_file 读得到,vision_analyze 读不到。

现在的做法:按“视觉等价”匹配一次,但只在候选唯一时

改动分成两层。

第一层是匹配键。 tools/file_operations_common.py 新增了 filename_match_key,把文件名归一化到“人眼看着一样”的形式:NFC/NFD 两种 Unicode 组合形式、各种窄空格和特殊空格、弯引号,全部折算掉。

第二层是找工作。 tools/image_source.py 里的 _on_disk_spelling 在路径 miss 之后,去同目录里找“只有不可见字符不同”的那一个文件:

目标名字(归一化后):screenshot 2026-11-12 at 9.51.42 am.png
目录里实际存在:      Screenshot 2026-11-12 at 9.51.42<U+202F>AM.png   ← 命中

规则里有两个细节值得记住:

  • 只有唯一候选才用。 如果同一目录里有 a AM.png 和 a<U+202F>AM.png 两个文件,它不猜——猜错就会读到另一张图,那比报错更糟。
  • 找到之后照样过安全检查。 解析出来的路径仍然要过媒体目录的围栏检查和凭据读取守卫,也就是说这个“自动纠正”没有绕过任何一条安全边界。而且它只在本地后端生效(TERMINAL_ENV=local);在沙箱里,路径 miss 必须交给容器内的读取去判定,否则就破了沙箱边界。

覆盖到哪些工具

同一个“磁盘上的真实写法”解析器现在被这几个入口共用:

工具 之前 现在
vision_analyze(看图片) media file not found 找到真实文件,正常分析
视频分析 同样的 miss 同样找到(_materialize_video 会返回 U+202F 的真实路径)
图像生成 / 视频生成(以本地文件为参考图) 直接失败 _confine_source_images 把 image_url 和 references 改写成磁盘上的写法,URL 和不存在的文件不动
read_file 早就能处理 不变

实测记录里最直接的一条:同一张截图,旧分支的工具结果是 "success": false … media file not found,新分支是 "success": true,模型随后正确答出了图里的颜色。测试套件里新增了 tests/tools/test_image_source_unicode_space.py,在旧分支上会以 SourceNotFound 失败。

你可以自己做点什么

这个修复让 Hermes 自己扛住了,但你也可以从源头绕开:

  • 改个名字。 把截图重命名为 shot-1.png 之类,任何看不见的字符都不会进来。这在批量脚本里尤其值得做。
  • 想看看到底有没有隐藏字符:ls -b 会把不可见字符转义显示,或者用 Python 打印 repr(path),U+202F 会直接露出来。
  • 拖放优先。 让工具自己去拿文件路径(拖拽、附件上传),比让模型复述一个长文件名可靠得多。

同类问题不止这一个字符。NFD 形式的文件名(macOS 上带重音符号的文件名很常见)和弯单引号(' 与 ')造成的 miss,这次一起被同一个匹配键覆盖了。

如果图片相关的报错反复出现,可以先看图片上下文预算(大图被压缩后的行为)和HEIC 照片的处理。另外两个方向:终端里贴图和剪贴板图片命令——它们各自绕开“模型复述路径”这个环节。

上线状态

PR #154046 于 2026 年 11 月 12 日合并进 main,修的是 issue #76334,并且是 cherry-pick 了更早的 #62126(作者署名保留)。v0.23.1 是 11 月 10 日发布的,不含这次修复。相关的 #76376 和 #124742 处理的是重叠但不相同的场景(提示词侧引导、NFD 与弯引号),这次的匹配键把这几类一起收了。

更新(2026-11-17):这里说的改动已随 v0.23.2 发布(2026-11-16),hermes update 就能拿到。上文「不在 v0.23.1 里」是发布当时的快照。