input-token-overheads

输入 Token 开销

审计 Hermes Agent 实例上的每一项输入 Token 成本，分两个范围进行。分别测量并按成本排序，然后处理消耗最高的项目。

• 每轮开销审计——检查每轮系统提示词的成本：工具架构、技能索引、系统固定文本、用户资料、记忆召回。脚本：scripts/audit_overheads.py。
• 汇总成本核算审计——统计会话、定时任务触发和工具流量中的输入 Token 总量：Token 用在了哪里、哪些项目消耗最多，以及如何通过更改配置或提示词减少消耗。脚本：scripts/audit.py。（由原 input-token-analysis 技能合并而来；v1.9。）

每轮上下文窗口的健康状况由开销审计负责；如需核查服务提供商的账单争议，请使用其用量仪表板——本地遥测无法查看服务提供商一侧的缓存情况。

适用场景

• 用户提到“Token 开销”“上下文太大”“为什么输入这么贵”
• 上下文稀释导致模型输出质量下降
• 成本优化——每轮输入 Token 越少，API 支出越低
• 添加技能、插件或工具后——验证开销变化
• 每月／每周输入 Token 账单金额巨大且原因不明（例如“30 天内 2.4B Token”）——汇总审计
• 应用节省 Token 的更改后——对照基线衡量变化——汇总审计
• 怀疑定时任务失控，消耗了过多 Token——汇总审计

开销分布图

在实时构建版本（2026-10）的 cli 界面上验证，共 44 个工具：

类别	独立测量（约 tok）	预算（字节/4 tok）	备注
工具架构	~17.9k	~17.9k	最大的一项。 每个启用工具的完整 JSON 架构；builtin/mcp/subagent 分类可单独查看
技能索引	~5.4k	~5.4k	完整索引，始终处于 易变 层级（移至该层级，以便编辑技能时不会使缓存的稳定前缀失效）。不是 Top-K——调整 Top-K 不会减少此项
系统固定文本	~4.2k	~4.1k	身份／指导内容；固定成本
用户资料	~0.8k	~0.8k	注入上限为 3,000 个字符——超出上限的尾部内容会在每轮静默截断
记忆（自身事实）	0	0	Mnemosyne 负责记忆召回时为 0 B；每轮的召回注入内容不计入提示词大小预算——实时测得的总量包含这些内容
服务提供商测得的输入量	—	~25.1k tok	比估算值总和低约 3.2k——服务提供商的分词器对 JSON 工具架构的计数比“字符数/4”更精确

按需内容（不计入每轮）： 通过 skill_view 获取完整 SKILL.md，通过 tool_describe 获取延迟加载的工具架构，通过 skill_view(file_path=...) 获取参考文件。

三路测量（v1.8），逐类别进行：

1. 实测（真实值）：scripts/audit_overheads.py 启动一个真实提示词（hermes -z "Reply with OK" --usage-file ...），然后读取全新会话中服务提供商实际报告的 input_tokens。服务提供商只报告总量。
2. 独立测量（逐类别）：脚本构建 Hermes 自带的离线检查 Agent，呈现真实系统提示词的各个部分，并使用构建版本自带的粗略分词器测量每个类别——系统固定文本、技能索引、记忆、用户资料、builtin/MCP/subagent 工具架构。脚本从呈现后的提示词中重新推导各类别；不会读取提示词大小输出。
3. 预算：hermes prompt-size --json 的字节核算（字节/4 估算器），仅用作对照列。

此外还移植了 context-doctor 的概念（jzOcb/context-doctor，MIT；仅采用其概念，脚本为原生实现）：注入上限检查——TRUNCATED（超过上限，每轮静默截断）、MISSING（引用失效）。任何注入文件需要处理时，退出码为 1。

健康比率

健康指标是开销比率：测得（或估算的）开销 token 数除以模型的上下文窗口。绝对数量关系到成本；比率则关系到质量。

比率	评级	说明
< 5%	极佳	上下文窗口的大部分可用于对话
5-15%	健康	对具备工具、技能和记忆的强大 Agent 而言属于正常范围
15-25%	可接受	接近上限。可考虑精简。
> 25%	不健康	占用对话容量，存在成本和质量风险。

比率为何重要： 三项研究证实，无论内容质量如何，输入长度都会降低模型性能：

1. Lost in the Middle（Liu 等，TACL 2023）——模型遵循 U 形曲线：在上下文开头和结尾的回忆效果最好，在中间则会显著下降。开销位于每轮内容的最前面，但它会将对话历史推入性能下降区域。arxiv.org/abs/2307.03172

2. Same Task, More Tokens（Levy 等，ACL 2024）——推理性能会在远低于模型声明的最大输入长度时就开始下降。即使额外 token 只是填充内容，且不包含任何干扰信息，也会出现性能下降。模型的技术上下文窗口并不等于其有效上下文窗口。aclanthology.org/2024.acl-long.818

3. Context Length Alone Hurts（Du 等，EMNLP 2025）——随着输入长度增加，性能会下降 14-85%；即使检索完全准确、无关 token 被替换为空白，或除相关 token 外的所有 token 都被屏蔽，也依然如此。输入本身的长度就是一种限制。aclanthology.org/2025.findings-emnlp.1264

成本叠加： 每轮都要为开销付费。若每轮开销为 10k 个 token，持续 100 轮，就会有 1M 个输入 token 仅用于开销。将开销减少 2k 个 token，每场 100 轮的会话就能节省 200k 个 token。

研究提出的缓解措施：

研究发现	来源	措施
模型对上下文开头和结尾的内容回忆效果最好；中间部分的效果会下降	Liu 等，2023	将开销保留在最前面（Hermes 已如此处理）。避免将关键对话历史推入中间部分——如果历史内容被过度压缩，可降低压缩阈值
推理性能远在达到声明的上下文窗口上限之前就会下降	Levy 等，2024	将有效上下文窗口视为宣传上限的 50-70%。将开销比率目标设为宣传窗口的 10% 以下，而非有效窗口的 10% 以下
即使检索完全准确且没有干扰，单纯的输入长度也会造成影响	Du 等，2025	大幅减少开销。每减少 1k 个开销 token，都能提升推理质量，而不仅仅是降低成本。该研究提出的缓解措施是：提示模型在解题前复述关键证据——这相当于 Hermes 压缩时对相关上下文进行摘要
工具目录从 8k 个 token 增至 120k 个 token 时，工具调用性能会下降 7-85%	LongFuncEval（arxiv 2505.10570）	保持启用的工具集数量较少。优先使用按需加载的延迟工具，而非始终启用的架构。禁用未使用的工具集

流程

1. 衡量每种开销来源

python3 scripts/audit_overheads.py     # from the input-token-overheads skill dir

运行一次：启动实时单轮提示词（一次推理调用），然后输出分类对比表：

category                     indep est    budget    delta
system fixed text                4,177     4,065      112
skills index                     5,379     5,357       22
memory (own facts)                   0         0        0
user profile                       820       816        4
tool schemas (all)              17,885    17,884        1
TOTAL                           28,261    28,124      137
provider measured                   25,077

• 独立估算 — 使用构建版本的粗略分词器，根据渲染后的提示词重新推导（不涉及提示词大小输出）
• 预算 — hermes prompt-size 字节数 / 4
• 提供方实测 — 全新会话中的实际 input_tokens；这是计算健康比率时应使用的真实分母
• 每个类别的差值若达到几百个 token，说明你认为会发送的内容与实际发送的内容存在偏差 — 调查该类别
• 工具拆分（内置 / MCP / 子 Agent）会在表格下方输出

标志：--platform cli|telegram|discord|...（检查 + 预算范围）、--skip-live（不调用推理；实测行显示为“未测量”）、--json、--chart out.png、--ctx <window>、--live-timeout。退出码 1 = 有注入文件需要处理。

此外，还要衡量两种估算都看不到的内容：每轮的记忆提供方召回大小（在会话中读取新一轮注入的召回块）— 它会叠加到全新会话的实测总量之上，并随着事实增多而增长。

完成标准： 已查看分类表；已根据提供方实测总量计算健康比率；已检查每个注入文件的状态。

2. 按开销排序

表格会按开销排序。典型排序如下：

1. 工具架构 — 最大的数据块。随启用的工具集数量增加而增长。
2. 技能索引 — 始终完整加载的索引。随索引中的技能数量增加而增长。
3. 系统固定文本 — 固定且稳定的部分。
4. 用户资料 — 有上限，但对于长期运行的 Agent，通常接近预算上限。
5. 记忆提供方召回 — 动态变化、每轮产生，且不计入预算；在会话中衡量，若事实增多则精简事实。

完成标准： 已找出开销最高的 3 项 — 它们就是优化目标。

3. 处理开销最高的项目

工具架构（最大的数据块）：

• 优先使用按需加载的延迟工具，而非始终启用的工具 — 每延迟加载一个工具，就能用约 150 B 的目录行替代完整的 JSON 架构
• 禁用未使用的工具集；移除某个工具集前，检查每项技能 frontmatter 中的 requires_toolsets，确认没有技能依赖它
• 使用 config.yaml 中的 platform_toolsets.<platform> 控制各界面的访问权限（Telegram 界面所需的工具比命令行少）

被截断的文件（脚本退出码为 1）：

• 用户资料被截断是正确性问题，而非成本问题 — 每一轮的尾部内容都会丢失。精简到上限以内（批量缩短或移除过时条目），然后重新运行，直至显示 OK

技能索引：

• 在 config.yaml 的 skills.disabled 下禁用未使用的技能 — 每移除一项，始终加载的索引就会减少约 200-300 个字符
• 将超过约 200 个字符的描述精简；它们会浪费索引预算，却无法改善路由效果

记忆提供方（若已安装）：

• 运行整合，将工作记忆移至情景记忆，从而降低每轮的召回预算
• 使过时事实失效；如果上下文吃紧，则调低召回 limit

压缩： 加载 skill_view(name='hermes-compression-tuning')，调整阈值和目标比率。

完成标准： 已对开销最高的 3 项各应用至少一项优化；所有被截断的文件均已精简到上限以内。

4. 验证变化

重新运行审计脚本（实时）。比较每个类别的差值以及优化前后的提供方实测总量；确认所有注入文件均显示 OK。

完成标准： 已报告优化前后各类别的差值。如果没有明显减少，剩余开销属于结构性开销（工具架构 + 技能索引），需要修改配置，而非精简内容。

汇总开销审计（成本核算）

说明输入 token 的总消耗情况。用数据回答三个问题：token 都用在了哪里、哪些使用方占比最高、哪些配置或提示词改动可以减少消耗。此审计涵盖所有会话、定时任务触发和工具流量的总体用量；上面的逐轮流程则涵盖系统提示词开销。

运行

python3 scripts/audit.py --days 30     # from the input-token-overheads skill dir
# other profiles: --db ~/.hermes/profiles/<name>/state.db
# custom cron ledger: --cron-audit /path/to/usage_audit.jsonl --jobs /path/to/jobs.json

只读，纯标准库。脚本会输出：按任务／模型／提供商汇总的总量、缓存读取和缓存写入列、加权单次调用平均值（长会话和短会话下限）、排名靠前的会话、cron 问题项、仅活跃会话的工具结果量及工具占比，以及超大结果数量。所有数据都来自真实数据库行——脚本能够测量时，绝不手动估算。

预检规范

先核实，再给建议。凭记忆给出的建议不可接受。

1. 配置键和当前值——先读取实时值：hermes config get <key>。绝不要凭记忆陈述当前值，也不要假设正在使用默认值。
2. 默认值和机制——根据已安装版本（hermes_cli/config_defaults.py）或 Hermes 文档，确认配置键是否存在及其作用。如果已安装版本与文档不一致，请说明。
3. 提供商行为——不要假设提供商会报告缓存字段、遵循定价层级，或以某种方式统计 token。提出相关结论前，请先探查或查看其最新文档。
4. 无法核实的说法——在报告中标记为 UNVERIFIED。明确标注未知，好过自信地猜测。

引用了未核实的配置键、值或机制的方案并不完整。请先完成预检，否则就删除该方案。

流程

1. 确定基线。 针对相关时间范围运行脚本。记录：总输入量、按任务细分的数据、排名前 10 的会话、cron 问题项统计、工具字符占比、缓存列、成本总计。将输出与计划进行的更改一并保存。

完成标准：最终报告中的每个数字都能追溯到脚本中的对应行。

2. 预检每个候选方案。 在将任何方案纳入提案之前，请在实时实例上核实：配置键存在（hermes config get）、当前值已知，且其机制与已安装版本或文档一致。提出与缓存相关的结论前，请检查提供商的报告行为。

完成标准：草案中的每个方案都具有已核实的配置键和当前值，或者标记为 UNVERIFIED 并说明缺少什么信息。

3. 排序并对应方案。 按 token 数和估算成本对消耗项排序（两者的排名可能不同）。对于排名前三的消耗项，分别指出预检过的方案。如果某个消耗项没有对应方案，请明确说明，而不是凭空编造。

完成标准：排名前三的消耗项都有预检过的方案，或者明确判定“没有本地方案”。

4. 提出更改。 按影响从大到小排列方案，每项包含：配置键或提示词修改、预期节省量、回退方式。按各个 billing_provider 应用对应的缓存折扣，计算预期节省量；如果提供商不报告缓存字段，请说明估算有上限，并在提供商仪表板上核实。配置更改必须通过 hermes config set 进行——工具会阻止直接编辑 config.yaml（已于 2026-09-02 核实）。修改 cron 提示词：先备份旧提示词，再编辑，然后验证格式（{"jobs": [...], "updated_at": ...}）和计划任务是否保留。

完成标准：用户批准每项更改，并且更改已应用且回读验证通过。

5. 安排差异检查。 创建一个约 30 天后执行的单次 cron，在其提示词中附上旧基线，以便重新运行此审计。包含：基线数字、已应用更改列表，以及每项更改的通过标准（例如，“job X avg prompt_tokens/fire >2M = not fixed”）。

完成标准：差异检查 cron 已创建（hermes cron list 中可见），且其提示词包含基线数字、已应用更改列表和通过标准。

解读

先对消耗项排序，再为每项匹配一个预先检查过的调节手段：

发现	信号	调节手段
长会话占主导	顶部会话 >200 api_calls、>40M 输入	先检查提供商的缓存折扣。启用缓存后，预热会话重新读取历史记录的成本很低；只有未缓存的冗余内容占主导时才重置。每次重置都会以全价重新支付完整前缀的费用。检查压缩是否确实生效（compact count >0）
background_review 占比高	task='background_review' >总量的 5%	使用 auxiliary.background_review.max_input_tokens（默认值为 600000），或设置 enabled: false；手动执行 /refine 仍然可用。还可以将 auxiliary.background_review.model 路由到更便宜的模型——不同模型会重放精简摘要，而不是完整转录
单个 cron 作业占主导	每次触发的平均 prompt_tokens 达到数百万	重写其提示词，加入读取预算：按日期限定源数据、跳过超大条目、缩小滚动窗口、达到上限即停止并延后处理
Cron 成本已触底	每次触发的平均 token 数接近单次调用下限（25-30k）	单次调用的固定脚手架开销乘以触发次数才是主要成本：减少触发频率或合并作业，而不是缩短提示词
工具结果占据大量上下文	工具字符数 >STORED 活跃内容的 70%（这是已发送内容的上限；脚本会打印占比）	设置 tool_output.max_bytes（默认值为 50000）、file_read_max_chars（默认值为 100000）和溢出预算。启用提供商缓存后，节省的费用主要来自结果首次出现时，以及避免压缩；通过缓存重新读取的稳定结果成本很低。超大结果会以预览内容和路径的形式溢出到 $HERMES_HOME/cache/spillover/
技能重复加载	每个会话中同一技能正文被加载 N 次	采用行为规则：已在上下文中的技能，不要再次调用 skill_view。启用缓存后，直接重读可享受折扣；真正的损害是上下文压力导致更早压缩，从而使缓存失效
短会话的单次调用下限偏高	脚本统计的 <50 次调用会话加权平均值（通常为 25-40k）	这是固定基线（系统提示词 + 工具架构定义）——应按上述每轮开销流程降低，而不是通过此审计处理
子 Agent 扇出开销大	delegate_task 启动次数多；每次都会在未缓存的情况下重新支付完整系统提示词 + 工具架构定义	将 delegation.model 路由到更便宜的模型来处理机械性子任务；将多个工具调用合并为一次 execute_code 调用，而不是扇出；限制并发子 Agent 数量
压缩频繁触发	每个会话的压缩事件次数多；compression_ineffective_count >0	每次压缩都会将历史记录改写为新的前缀，因此之后的所有内容都会产生全价缓存未命中。权衡 compression.threshold 与提供商的缓存折扣；将压缩摘要器（auxiliary.compression.model）路由到便宜的模型——它会读取整个对话
某提供商的 cache_read ≈ 0	提供商完全不返回缓存 token 字段（此时本地 input 就是完整提示词，无法衡量占比——请检查提供商的计费控制面板）；或者提供商返回了该字段但值为 0（缓存确实未启用：可能是会话较短、前缀不稳定或 TTL 已过期——请排查）
优惠任务流量使用高端模型	主模型上出现 title_generation/approval/vision 记录	将每个 auxiliary.<task>.model 路由到 flash 级模型；对频繁的小型调用而言，节省的费用接近于零
Token 排名不等于成本排名	便宜模型消耗的 token 是高端模型的 10 倍	按 billing_provider 统计 estimated_cost_usd/actual_cost_usd 并排序；将 billing_mode='subscription_included' 记录（边际成本为零）排除在优化工作之外

汇总分析中的陷阱

1. 以只读模式打开 state.db（file:...?mode=ro，uri=True，并对路径进行 URL 编码）。该数据库处于实时使用状态，可能有数百 MB；使用写连接可能导致锁定。
2. 不同提供方的线路格式对 input_tokens 的语义定义不同。 Anthropic 风格的线路会在 input 之外报告 cache_read_tokens（实际提示词 ≈ input + cache_read + cache_write）；OpenAI 风格的线路中，prompt_tokens 已包含作为子集的缓存令牌。经验判断：如果某行的 cache_read > input_tokens，则该提供方未将缓存计入 input。切勿跨提供方比较原始 input_tokens；应按 billing_provider 计算有效提示词量。缓存占比仅在同一种统计口径内有意义。
3. jobs.json 有两种已观察到的结构——{"jobs": [...], "updated_at": ...} 和一个裸列表。编辑前后都要兼容这两种结构；每次写入后都要验证容器结构。
4. 缓存占比为 0 并不能证明没有缓存。 有些提供方的 usage 中根本不返回缓存令牌字段（已于 2026-09-02 验证过一个此类提供方——其 usage 对象只包含 prompt/completion/total），因此本地遥测无法观测到它们的缓存情况。其他提供方会逐次调用报告缓存读取量。请查阅各提供方的文档和账单面板，以获取实际情况。
5. sessions.input_tokens 与 session_model_usage 的差异来自归因方式，而不仅是时间差异：任务行按会话累计，并按 last_seen 归因（会将窗口开始前的消耗计入窗口），而逐会话排名使用开始日期／活动日期。总数无法对账时，应说明偏差方向；切勿将这两种总数混在同一个合计中。
6. token_count 列经常为 NULL——使用 LENGTH() 测量内容大小，并记住字符数 ≈ 令牌数/4 只是粗略估算。
7. 压缩和不活跃状态会使存储内容产生偏差。 按 active=1 筛选消息：压缩后的行已被摘要取代，不活跃行则不再发送。存储的活跃内容仍是已发送内容的上限（采集时已应用截断）。区分实时内容与压缩内容，有助于解释为什么会话的数据库大小可能超过其上下文大小。
8. 单次触发就可能远超其他数据——在计算平均值前，先扫描 cron 台账中的最大 prompt_tokens；一次包含数百万令牌的触发会隐藏在看似正常的均值中。
9. cron 台账中 prompt_tokens 的统计口径按单次触发计算，且文档不充分——每次触发对应一行，但一次 Agent 式触发会进行多次 API 调用，每次调用都会重新发送上下文。应将每次触发的平均令牌数视为实际 cron 输入量的下限；需要精确数据时，应与该次触发对应的会话行核对。
10. 逐次调用的平均值必须加权——使用 SUM(input)/SUM(calls)，绝不能对逐会话比例取 AVG；否则一个 200 次调用的会话与一个 10,000 次调用的会话权重相同。
11. tool_output.max_bytes 仅限制终端输出（已通过 config_defaults.py 验证：“终端工具输出上限，以字符计”）。不要用它评判 read_file/skill_view/网页结果是否超限；read_file 有自己的 file_read_max_chars（默认 100k）。脚本中“活跃结果超过 50k”这一行统计的是所有工具，因此大部分结果都不受终端上限机制影响——在认定上限失效之前，应按 tool_name 拆分超限数据。
12. skill_view 存储的结果有两种形式——原始 JSON（包含 "name": "…"）以及压缩时降级为占位符的内容（[skill_view output demoted at compaction …]）。只能从 JSON 字段提取名称；占位符无法按名称匹配。因此，测得的重复加载率是一个下限；同时报告未解析的数量。
13. 切勿通过在原始 jobs.json 文本中搜索子串来确认 cron 任务是否存在——其他任务的提示词可能会引用该 ID（审计任务的提示词会提及基准任务 ID）。解析容器，并逐个匹配任务的 id 字段；找不到该 ID 表示任务已删除（请检查台账中的历史触发记录）。

验证（汇总）

• 脚本已以只读方式运行，检查每个相关的配置文件数据库（默认配置文件和所有活动配置文件）
• 已核对总数，并注明归因偏差（按 last_seen 统计任务行，按 start/activity 统计会话）
• 每个主要消耗项都已对应到预先检查过的调整项，或标记为“无本地调整项”
• 每个拟议的调整项都已预先检查：键存在、已实时读取当前值、机制已确认
• 已回读并验证应用的更改（hermes config get，重新解析 cron jobs.json）
• 旧提示词/配置已备份，并记录路径
• 已安排差异检查 cron，并在其提示词中注明基准值和通过标准

常见陷阱

问题	原因	修复方法
已测量的行显示“未测量”	使用了 --skip-live 运行，或者一次性运行未能写入其用量文件	不使用 --skip-live 运行；检查实时运行错误行
Skills 索引的独立估算值为 0，但预算显示数千	在错误的层级中搜索了渲染结果的 <available_skills> 块	脚本会先搜索易变层级，再搜索稳定层级（当前布局将索引保存在易变层级中）
提供方测量值比估算总和低约 3k	分词器差异：chars/4 和粗略估算器都会高估 JSON 工具架构	比率应以提供方数值为准；用类别差值检测漂移，而非视为绝对真值
Memory 块为 0 B，但每轮都会收到召回文本	提供方（Mnemosyne）在提示词大小预算之外注入召回内容	在会话中测量召回内容；精简记忆事实，而非该块
Skills 索引成本不受 top-K 设置影响	当前构建会注入完整索引	通过 skills.disabled 和描述长度进行优化，而非 top-K
用户配置文件被标记为 TRUNCATED	超过了 3,000 字符的注入上限	精简至上限以内；在此之前，每轮都会丢失末尾内容
禁用某个工具集导致工作流中断	某项技能依赖该工具集	禁用前检查技能 frontmatter 中的 requires_toolsets
精简记忆时移除了所需事实	未检查最后使用时间就进行了激进删除	移除前检查 recall_count 和 last_recalled
压缩触发过早/过晚	threshold 设置过低/过高	使用 hermes-compression-tuning 调整；压缩摘要本身也会消耗令牌
似乎无法避免必需技能的开销	在行为规则中进行了配置	接受这项开销，或在配置中移除强制加载要求

验证

• 审计脚本（实时）会输出完整的类别表，其中包含由提供方测量的 TOTAL 行
• 重新运行审计脚本——各类别差值和测量总量均已下降
• hermes tools——确认只启用了必需的工具集
• 监控下一次会话：上下文缩减不应导致质量下降