技能文档太大,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 还没有“规则被截断”的显式警告。也就是说,这条防线目前靠写作者的结构自律,而不是工具兜底。

技能生态越来越大,一份技能写上半年、追加几十次,很容易长到当初想不到的体量。定期量一下体积、把附录搬走,是成本最低的保险。

相关阅读:命令参考里的技能管理命令、把技能放进仓库的项目级技能、官方新增的三个可选技能。