技能文档太大,Hermes 只看到前 1500 字:一个很安静的截断坑

你把一条跑了半年的部署流程写进 SKILL.md:先备份、再灰度、出问题回滚到哪个 tag、最后必须提交给谁审批。写了三十几页,改过几十次,每次都追加一点。某天 agent 执行这条技能,前半段完美,最后一步把变更提交给了错误的人——因为那份“必须提交给 X”的条款,在它读到的内容里根本不存在。
这不是模型不听话,是它压根没看到那一段。
工具结果的硬预算:10 万字符
Hermes 对工具结果有一条通用预算:单次工具结果超过 10 万字符,就不再把整份内容塞进上下文,而是写到磁盘的溢写目录(spillover),上下文里只保留一段预览和一个文件路径。
这条设计本身很合理。一次抓网页、一次跑 find、一次读日志,动辄几十万字符,全塞进上下文既贵又挤掉真正有用的东西。于是有了这套分层:
| 阈值 | 默认值 | 作用 |
|---|---|---|
| 单次结果上限 | 100,000 字符 | 超过就落盘,留预览 |
| 预览长度 | 1,500 字符 | 上下文里实际看到的正文 |
| 单轮总预算 | 200,000 字符 | 一轮里所有工具结果的合计上限 |
| MCP 工具结果 | 50,000 字符 | MCP 返回的载荷通常更大更碎,单独收紧 |
问题在于,这套预算不区分“数据”和“规则”。
对技能来说,截断不是省空间,是丢规则
skill_view 读一份 SKILL.md,返回的是一个 JSON 对象:正文、linked_files、元数据。当正文长到让整个 JSON 超过 10 万字符,它和别的工具一样被落盘,上下文里换成了这样一段:
<persisted-output>
This tool result was too large (103,412 characters, 101.0 KB).
Full output saved to: ~/.hermes/cache/spillover/<id>.txt
Use the read_file tool with offset and limit to access specific sections of this output.
...
Preview (first 1500 chars):
...
</persisted-output>
对一个网页抓取结果,这段提示很尽责:模型知道“内容在文件里,去翻”。但对一份技能,模型的解读往往是“我已经加载了这个技能”——预览里有标题、有前半段步骤、有格式,看起来非常完整。它没有任何信号告诉模型:第 18% 处那条“提交给 X,不要给 Y”被丢掉了。
这正是 issue #151283 报告的现场:报告者的技能里有一段不可推断的固定参数,被截断后模型按“推断的默认值”执行了一次有状态写入,落到了真实的生产系统里。报告者的原话大意是——这种失败是静默且不对称的:对数据无所谓,对策略文档就是事故。
1,500 字里到底能看到什么
实现上有一个体贴的细节:技能结果是 JSON,如果原样落盘,整份文档会变成一行、换行全被转义,read_file 的 offset/limit 分页就没法用了。所以落盘前会把 JSON 里最长的那段多行文本抽出来,做成可翻页的纯文本;而 linked_files、metadata 这些结构化字段会被放到正文后面,避免它们挤占预览。
也就是说,预览里你能看到的通常是:状态、路径这类标量字段 → 正文前 1,500 字符。
对一份两三千字的技能,这够了。对一份十万字符的技能,这只是目录。
怎么写技能才不踩这个坑
这不是“等官方修”就能解决的事,写作者现在就能规避:
1. 先量一下体积。 技能目录里跑一次:
wc -c ~/.hermes/skills/<分类>/<技能名>/SKILL.md
一两万字符是健康区间。超过五万,就该考虑拆分了——不是说超过就一定会截断,而是你离那条线只剩一次“再追加一点”。
2. 把长附录移到 references/。 技能支持附带文件,skill_view 返回的 linked_files 就是它们。SKILL.md 只留“怎么做”的主干和不可违背的硬规则,命令清单、平台差异、历史案例放 references/xxx.md,需要时再读那一份。这既压小了主文档,也让每次加载的上下文更聚焦。
3. 把硬规则放在最前面。 预览取的是正文开头 1,500 字符。审批人、禁止操作、必填参数这类“错一个字就是事故”的条款,应该出现在最前面几百字里,而不是第三章的注意事项里。
4. 看到 persisted-output 就去翻文件。 如果你在会话里看到这条提示,而它对应的是技能,别假设自己读完了——用 read_file 打开提示里的路径,配合 offset/limit 把被截断的部分补上。
5. 技能不是越全越好。 一份什么都写的技能,等于一份谁都不会读完的 runbook。把“每次都要遵守的”和“偶尔查一下的”分开,是这个坑最根本的解法。
目前的状态
截至本文写作时,issue #151283 仍是打开状态,skill_view 还没有“规则被截断”的显式警告。也就是说,这条防线目前靠写作者的结构自律,而不是工具兜底。
技能生态越来越大,一份技能写上半年、追加几十次,很容易长到当初想不到的体量。定期量一下体积、把附录搬走,是成本最低的保险。