Hermes Skill Runtime 架构拆解:三层加载如何压住 Agent 上下文成本
Hermes 用 Level 0/1/2 分层披露,把技能发现、完整说明和参考文件拆开,降低 Agent 上下文成本。
Hermes 的 Skill System 看起来只是一个“按名字加载 Markdown 文件”的工具,但真正有意思的地方不在读取文件本身,而在它怎样控制上下文成本、怎样处理本地技能和外部技能的边界、怎样让插件技能进入同一套解析链路,又不把用户会话一开始就塞满。
这套设计的核心判断很明确:技能系统不能像传统插件市场一样,把所有内容预先索引、预先展开、预先注入。Agent 会话里的上下文窗口太贵,技能越多,越不能一次性把所有细节暴露给模型。Hermes 选择了一条更朴素的路:运行时扫描,分层披露,只有在真正用到某个技能时才付出更多 token。
图:模型先看到技能地图,而不是一次性读完整手册
Skill Runtime 的基本边界:主目录、外部目录与命名空间
Hermes 把 ~/.hermes/skills/ 视为技能的主目录。它是默认读写位置,也是本地技能的单一真实来源。外部目录通过 external_dirs 接入,更多承担扩展和共享的角色,默认不会改变本地主目录的权威性。
典型目录长这样:
~/.hermes/skills/
├── category/
│ └── skill-name/
│ └── SKILL.md
├── .hub/
│ ├── lock.json
│ ├── quarantine/
│ └── audit.log
├── .bundled_manifest
└── .archive/这里有几个工程取舍。SKILL.md 是技能入口;.hub 保存 Hub 相关的本地状态;.archive 和 .bundled_manifest 属于维护层数据,不应该参与正常技能扫描。Hermes 在遍历时会主动排除这些目录,也会跳过 .git、node_modules、虚拟环境、缓存目录等高噪声路径。
EXCLUDED_SKILL_DIRS = frozenset((
".git", ".github", ".hub", ".archive",
".venv", "venv", "node_modules", "site-packages",
"__pycache__", ".tox", ".nox", ".pytest_cache",
".mypy_cache", ".ruff_cache"
))命名空间是另一条边界。普通技能用 skill-name 解析,插件技能用 namespace:skill 解析。这个冒号并不是装饰,它告诉运行时先拆出插件命名空间,再去插件目录里找对应技能。没有这个规则,插件生态很快会撞名。
def parse_qualified_name(name: str) -> Tuple[Optional[str], str]:
if ":" not in name:
return None, name
return tuple(name.split(":", 1))本地优先也很关键。同名技能出现时,Hermes 不会让外部目录悄悄覆盖用户本地版本;真正发生多候选冲突时,它会返回明确错误和所有匹配路径,让用户改用完整相对路径。这个决定减少了“为什么今天调用的不是昨天那个技能”的排查成本。
Level 0:skills_list 只给模型一张轻量地图
会话启动时,Hermes 不会把每个技能的正文都塞进上下文。skills_list() 只返回技能元数据,大约是一个固定的 token 成本。原文估算 Level 0 约为 3k tokens,这笔成本会在会话启动时支付;后面的完整技能内容和参考文件,只有在触发时才成为边际成本。
Level 0: skills_list() -> 仅技能元数据,约 3k tokens
Level 1: skill_view(name) -> 完整 SKILL.md,通常 10-100k tokens
Level 2: skill_view(name, path) -> 技能目录内的某个参考文件Level 0 的目标不是“让模型读懂所有技能”,而是让模型知道有哪些技能、每个技能大概负责什么、是否适合当前平台和环境。它更像一张地图,不是一本手册。
图:Level 0 从目录扫描到条件激活过滤的完整链路
返回值只保留必要字段:
{
"name": "skill-name",
"description": "Brief description...",
"category": "category-name",
"tags": ["tag1", "tag2"]
}这个阶段的扫描没有依赖 SQLite 或预构建 JSON 索引。Hermes 每次执行 skills_list() 都会重新扫文件系统:
def iter_skill_index_files(skills_dir: Path, filename: str):
for root, dirs, files in os.walk(skills_dir, followlinks=True):
dirs[:] = [d for d in dirs if d not in EXCLUDED_SKILL_DIRS]
if filename in files:
yield Path(root) / filenamedirs[:] 的原地修改是一个小但实用的优化。它不是在遍历后过滤结果,而是在 os.walk() 继续递归之前剪掉不该进入的目录。技能数量少于千级时,这种按需扫描足够简单,维护成本也比额外索引低。
Level 0 还会处理平台和环境匹配。platforms 为空时默认通过;macos 会映射到 darwin,linux、windows 也有对应映射。Termux 需要特殊处理,因为它跑在 Android 上,却经常要兼容 Linux 技能。
PLATFORM_MAP = {
"macos": "darwin",
"linux": "linux",
"windows": "win32"
}环境字段也在这个阶段过滤。Hermes 内置识别 kanban、docker、s6,未知环境默认通过。这个默认值有点宽松,但它避免了一个更糟的问题:新环境还没被运行时认识时,技能全部消失。
_KNOWN_ENVIRO…