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) / filename

dirs[:] 的原地修改是一个小但实用的优化。它不是在遍历后过滤结果,而是在 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…
— 以上为试看内容(约 40%),开通会员后阅读全文 —