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

你把刚截的图拖进对话框,让 Hermes 看一下报错信息。文件保存成功,路径也打印出来了,但它打开图片的那一步失败了:media file not found。你去 Finder 里看一眼——文件好端端在那里,名字也对得上。
问题出在“对得上”这三个字。macOS 给截图命名时,AM/PM 前面那个空格不是普通空格,而是 U+202F(窄不换行空格)。它在屏幕上和普通空格长得一模一样,宽度略窄一点点,肉眼基本看不出区别。模型把这串名字重打一遍的时候,输出的必然是普通空格 U+0020——两个字节不同,路径自然指向一个不存在的文件。
PR #154046(2026 年 11 月 12 日合并)让视觉分析、视频分析和图像/视频生成都自己去找磁盘上的真实写法。
一个字符导致的失败链
完整链条是这样的:
- 你(或工具)把文件路径写进上下文:
Screenshot 2026-11-12 at 9.51.42 AM.png。这里面第 26 个字符是 U+202F。 - 模型读到的字符串是“看起来正常”的,但它生成新文本时,输出的空格一律是 U+0020。
- 图片查看器拿这个路径去
open(),操作系统按字节比较,找不到文件。 - 报错信息只说
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 里」是发布当时的快照。