补充技能索引紧凑模式特性的研究

PR 地址：NousResearch/hermes-agent#33934 · 系统提示词中技能索引的可配置紧凑渲染模式

研究摘要

Hermes 的系统提示词中维护着一份技能索引，向模型宣告当前会话可用的全部技能及其用途，模型借此感知能力边界、决定何时加载哪个技能。技能库不断扩充之后，这份索引逐条完整展开会占据可观的提示词空间——每轮请求都要为这份固定清单支付一次 token 成本，而清单里的大多数技能在绝大多数会话中根本不会被调用。本研究向 Hermes 上游补充了技能索引的紧凑模式能力：新增 _get_compact_mode() 决策函数，让技能索引按配置以精简形态渲染，同时清除了旧实现中基于废弃正则的渲染污染，使索引输出干净、稳定、可预期。改动集中在 agent/prompt_builder.py 一个文件，净增 40 行、净删 2 行，以最小侵入完成。

这篇研究拆解该特性的设计动机、实现方式与能力边界。PR body 未附带实测数据，因此文中对效果的讨论均明确标注为设计意图与预期效果，不虚构量化结论。

一、问题背景：技能索引的提示词税

1.1 索引随技能库增长而膨胀

Hermes 的系统提示词不是单一文本，而是由身份说明、行为规则、工具清单、技能索引等段落拼装而成，其中技能索引的规模是唯一随用户配置线性增长的段落。Hermes 的技能系统允许用户挂载大量技能，每个技能在索引中都占有一行描述，说明技能名、触发条件与用途。技能库从十几个涨到上百个之后，索引本身就成为系统提示词里最长的固定段落之一。

它的成本是每轮请求都要支付一次的：无论本轮任务是否与技能相关，模型都要携带整份索引进入上下文，挤占本可用于对话与任务处理的窗口。对上下文预算敏感的场景——长会话、多技能库、小上下文模型——这份固定开销会持续放大，且与单轮任务的真实需求无关。更隐蔽的是，索引膨胀是缓慢累积的：单个技能的增加微不足道，直到某天索引的长度开始肉眼可见地挤压有效对话空间，问题才被意识到，而此时技能库规模已经难以回头精简。

1.2 旧渲染路径的正则污染

PR body 明确指出旧渲染路径存在"废弃正则污染"（deprecated regex pollution）。技能索引的渲染一度依赖一套已废弃的正则表达式做后处理：这类正则年代久远、可读性差，当初的适用前提（技能条目的格式约定）早已变化，但正则仍留在渲染链路里继续生效。后果是双重的：在边界输入——特殊字符的技能名、空技能集、超长描述、含 Markdown 符号的描述——下容易产生不干净的输出；后续每次调整渲染逻辑，都要先厘清正则的既有行为，再小心翼翼地绕开它，维护成本高且容易引入回归。本次特性顺带完成了这条路径的清理，把"渲染形态"与"历史补丁"解耦。

从版本演进看，正则污染是典型的积累性技术债：每一代维护者都倾向于在既有输出上打补丁，而不是重构渲染路径，因为后者风险更高。本次改动选择了风险更低的时间窗口——与紧凑模式捆绑——一次性偿还这笔债务，避免为清理而单独大改渲染逻辑。

二、特性设计：一个决策函数，两种渲染形态

2.1 可配置的紧凑开关

核心新增是一个 _get_compact_mode() 决策函数，职责是根据配置返回当前会话是否启用紧凑模式。紧凑模式开启后，技能索引以精简形式呈现：压缩逐条完整展开时的提示词占用，仅保留支撑模型完成技能发现所必需的信息——按设计意图推断，精简的取舍点在于保留技能名与最小必要标识、省略完整描述与使用示例这类低密度信息（此推断基于紧凑模式的定义，PR body 未逐项列出保留字段）。默认形态保持既有行为不变，老用户无感升级。

选择以"get 函数 + 配置"的方式实现，而不是直接改渲染逻辑，是为了把"是否紧凑"这个策略问题从"怎么渲染"这个执行问题中分离出来：策略收敛在一个决策点，渲染逻辑只负责按决策结果输出。后续想调整紧凑阈值、按技能类别差异化处理、或根据上下文余量动态切换，都只需扩展这一个决策点，渲染路径不需要跟着改。

2.2 渲染路径去正则化

紧凑模式的引入同步改写了索引渲染路径：输出不再依赖已废弃的正则表达式做后处理。新的渲染路径对技能条目做结构化的组装与精简——按条目元数据逐字段构建，需要哪些信息、以什么顺序呈现、如何分隔，都在代码里显式表达，边界行为可预期，不再存在"正则吞掉条目"“匹配到错误片段"这类隐蔽问题。从改动规模（+40/-2 行）看，这是一次受控的小范围重构：不触碰技能加载、匹配与调用链路，也不涉及配置体系的变化，风险面被严格限制在"索引长什么样"这一个维度上。

2.3 设计决策：为什么是配置化而非一刀切

选择"可配置"而非"直接压缩"是刻意的权衡。技能索引的形态涉及提示词预算与可读性的取舍，不同用户场景取向不同：上下文预算紧张、技能库庞大的用户希望索引越省越好，省下的每轮 token 都转化为可用窗口，长会话的续航能力直接受益；依赖索引完整描述来发现技能的用户则希望保留更多信息，描述越完整，模型对"何时该调用哪个技能"的判断越准。配置化让两种取向并存，也避免了强制压缩可能带来的"模型找不到技能"风险——那会让省下的 token 以更隐蔽的方式（错误地不加载技能、能力没被使用）浪费回去。

配置化的另一重收益是演进路径清晰：从全局开关出发，后续可以逐步升级为按技能类别差异化、按上下文余量动态切换，决策函数是唯一的升级点，渲染层无需跟随变动。这使紧凑模式具备从静态配置走向动态自适应的潜力，也为技能索引的其他优化（如按会话相关性调整条目顺序）预留了同一决策点（演进方向为设计推断，PR body 未提及）。

三、实测结果

PR body 未提供测试套件或真机数据，本节记录设计意图与预期效果（明确标注，非实测）：

• 预期效果：开启紧凑模式后，系统提示词中技能索引部分的 token 占用显著下降，每轮请求的固定开销随之降低，长会话的可用上下文窗口相应扩大；
• 预期效果：技能的可发现性不受影响，索引仍然存在，只是呈现形态精简，模型仍能感知技能集合与触发条件；
• 预期效果：渲染路径脱离废弃正则后，索引输出在不同技能集（含边界输入）下保持稳定一致，不再出现偶发的脏输出；
• 预期效果：默认行为不变，存量用户升级后提示词内容与之前完全一致，不存在隐性行为变更。

以上均为设计意图层面的预期，尚未有 PR 实测数据佐证。真实收益依赖实际技能库规模与上下文配置，需要在真实环境中对比开启前后的提示词长度与任务表现来验证；对于技能库尚小的用户，紧凑与完整展开的差距可以忽略，该特性的价值主要体现在规模效应上。

验证该特性的最直接路径是统计开启前后系统提示词的 token 数与长会话中有效可用窗口的差异；这一对比在 PR 中无数据支撑，留待真实环境补充。

四、能力边界

• 紧凑模式只影响索引的渲染形态，不改变技能加载、匹配与调用逻辑，不存在功能层面的行为分叉；
• 需要用户显式开启，默认不生效，未配置的用户完全不受影响；
• PR 未附带回归测试与实测数据，渲染行为变更仍需在真实技能库上验证，特殊字符技能名的边界行为尤其需要实测确认；
• 紧凑形态的信息取舍未在 PR body 中逐项明确，不同技能库结构下的实际可发现性表现需要观察；
• 适用场景判断：技能库庞大、上下文预算紧张的用户收益最大；技能数量少时，配置该特性带来的复杂度大于收益。
• 紧凑模式的收益是叠加式的：技能库越大、会话越长，省下的每轮固定开销越可观；单技能库的小用户开启后几乎无感知，特性的价值随规模增长；
• 特性只影响“索引怎么写”，不影响“索引读什么”——模型的技能发现、加载决策路径均不随紧凑模式变化。

五、PR 信息

• PR 地址：https://github.com/NousResearch/hermes-agent/pull/33934
• 改动规模：+40 / -2，1 个文件（agent/prompt_builder.py）
• 状态：closed
• 提交时间：2026-05-28

本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。