Hermes Skill Runtime架构解析：三层加载降低Agent上下文成本

首先明确几个核心判断：Hermes 的技能系统设计有一个清晰的出发点——它不打算像传统插件市场那样，将所有内容预先索引、预先展开、预先注入到模型眼中。Agent 会话的上下文窗口极其宝贵，技能越多，越不能一次性把全部细节塞给模型。Hermes 选择了一条更务实的技术路径：运行时扫描、分层披露，仅在真正使用某个技能时，才付出更多 token 成本。

这套技能系统（Skill System）表面上只是一个“按名称加载 Markdown 文件”的工具，但其真正价值并不在于读取文件本身，而在于它如何精细控制上下文开销、如何界定本地技能与外部技能的边界、如何让插件技能融入同一解析链路，同时避免在用户会话一开始就塞满信息。

图：模型先看到技能地图，而非一次性读取完整手册

技能运行时的基础边界：主目录、外部目录与命名空间

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_ENVIRONMENTS = frozenset({"kanban", "docker", "s6"})

条件激活是 Level 0 中更像 Agent 的部分。技能可以声明 requires_toolsets、requires_tools，还可以声明 fallback_for_toolsets、fallback_for_tools。前者表示依赖不可用则隐藏；后者表示主工具可用时自己退场。例如，一个 DuckDuckGo 搜索技能可以仅在正式 Web 工具不可用时出现。

图：依赖工具与 fallback 工具共同决定技能是否显示

这样做的好处是，模型看到的不是“所有可能工具”，而是当前会话中真正有意义的工具。对 Agent 而言，这比单纯减少 token 更重要，因为候选越混乱，错误调用的概率就越高。

Level 1：skill_view 的难点在于名字解析，而非读取文件

当模型决定使用某个技能时，才进入 Level 1。skill_view(name) 会读取完整的 SKILL.md，执行必要的前置处理，然后将完整的技能说明交给模型。

图：Level 1 的命名解析、冲突检查与内容预处理

四层名称解析策略体现了兼容性优先级：

# 策略 1：直接路径
direct_path = search_dir / name
if direct_path.is_dir() and (direct_path / "SKILL.md").exists():
    return direct_path / "SKILL.md"
# 策略 2：递归按目录名匹配
for found_skill_md in iter_skill_index_files(search_dir, "SKILL.md"):
    if found_skill_md.parent.name == name:
        return found_skill_md
# 策略 3：按 frontmatter 的 name 字段匹配
fm, _ = _parse_frontmatter(fm_content)
if fm.get("name") == name:
    return found_skill_md
# 策略 4：兼容旧式扁平 .md 文件
for found_md in search_dir.rglob(f"{name}.md"):
    if found_md.name != "SKILL.md":
        return found_md

直接路径优先，说明 Hermes 鼓励用户在冲突时显式指定位置。目录名匹配符合大多数人的直觉；frontmatter 名称匹配为重命名目录留有空间；legacy .md 负责兼容旧技能。

真正出现名称冲突时，运行时不会装作没事：

if len(candidates) > 1:
    return json.dumps({
        "success": False,
        "error": f"Ambiguous skill name '{name}': {len(candidates)} skills match",
        "matches": [str(smd) for _, smd in candidates],
        "hint": "Use full relative path instead"
    })

这比“按某个顺序静默选取第一个”要可靠得多。技能是会执行命令、写文件、访问外部系统的，名称解析上的模糊不应被吞掉。

插件技能在 Level 1 中走一条相似但带有命名空间的链路。skill_view("plugin:skill") 会先定位插件，再寻找插件内部的技能。如果插件存在但技能不存在，运行时可以列出可用技能；如果找到了，会在返回内容前附加上下文横幅，提醒模型这是哪个插件的一部分，以及有哪些同级技能（sibling skills）可以用限定名调用。

[Bundle context: This skill is part of the 'plugin' plugin.
Sibling skills: skill1, skill2.
Use qualified form to invoke siblings (e.g. plugin:skill1).]

Level 1 的后半段是技能内容预处理。Hermes 支持模板变量：

${HERMES_SKILL_DIR}  -> 当前技能目录的绝对路径
${HERMES_SESSION_ID} -> 当前会话 ID

如果配置允许，还可以执行内联 shell：

Current date: !`date -u +%Y-%m-%d`
Git branch: !`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

这个能力非常强大，因此应被视为受控扩展，而非普通 Markdown 特性。技能内容一旦能执行命令，路径安全和注入检测就必须跟上。Hermes 对技能名做了绝对路径、Windows drive、.. 路径穿越检查，也内置了一批 prompt injection 模式，例如 ignore previous instructions、system prompt:、。

Hub 安装的技能还会额外进行安全扫描，重点检查数据渗出、破坏性命令、Shell 注入和 prompt 注入。它不能证明技能绝对安全，但能拦截一批低成本攻击。

配置注入也发生在 Level 1。技能可以在 frontmatter 中声明自己需要的配置项：

metadata:
  hermes:
    config:
      - key: wiki.path
        description: Path to wiki directory
        default: ~/wiki
        prompt: Wiki directory path

运行时会从配置文件读取 skills.config.，若没有值则使用默认值，再展开 ~ 和环境变量。最后将结果追加到技能内容后面：

[Skill config (from ~/.hermes/config.yaml):
  wiki.path = /Users/erik/wiki
]

这里可以看出 Hermes 对“技能加载”和“技能管理”做了清晰区分。加载是按需读取和注入；管理则走 skill_manage，支持 create、patch、edit、delete、write_file、remove_file。如果开启了 skills.write_approval，写入不会直接落盘，而是进入 ~/.hermes/pending/skills/，等待用户 review、diff、approve 或 reject。

Level 2：参考文件将长技能拆解为可控切片

图：低频细节被延后到参考文件，按需进入上下文

许多技能的主文件不应无限膨胀。Hermes 的 Level 2 允许按路径读取技能目录内的参考文件：

skill_view("skill-name", "references/api.md")

这一步解决的是另一个 token 问题：某些知识只在特定分支下需要，例如 API 细节、样式规范、平台适配说明。将这些内容全部塞进 SKILL.md，会让每次技能加载都变重；拆分到 references/ 后，主技能只负责路由和原则，细节按需进入上下文。

可以将三层加载机制理解为下表：

原文尾部提到的性能优化、安全机制、平台环境匹配，其实都应放回这三层结构中来看。Level 0 负责过滤和候选控制；Level 1 负责解析、预处理和安全检查；Level 2 负责将低频细节延后处理。这样理解后，Hermes Skill System 就不再是“技能列表 + 技能详情”的二段式接口，而是一套围绕上下文窗口精心设计的运行时系统。

一次完整调用：从会话启动到技能内容进入上下文

会话启动时，Hermes 读取配置，解析外部目录，然后扫描技能元数据：

图：会话启动时仅注入精简技能元数据

用户触发技能后，完整内容才进入模型上下文：

图：技能被触发后才读取完整说明进入上下文

如果技能进一步请求 references/api.md，才进入 Level 2。这一顺序使得技能系统能够支持大量技能，又不必在每次会话中一次性支付全部成本。

这个设计真正解决的问题

Hermes 的选择并不复杂。它没有一开始就构建一套重索引系统，也没有将技能包管理做成独立数据库。它依赖文件系统、frontmatter、运行时扫描和少量缓存，换来的好处是透明、易于调试、便于迁移。

更值得肯定的是，它将 Agent 运行时最稀缺的资源——上下文窗口——放在了设计中心。技能并非越完整越好，也并非越早暴露越好。Level 0 让模型知道“有什么”，Level 1 让模型知道“这个技能怎么用”，Level 2 仅在需要时补上“具体细节”。这是一种非常适合 Agent 时代的插件系统思路：能力可以很多，但上下文必须克制。

如果后续要继续演进，真正值得加强的或许不是复杂的索引，而是两个方向：一是更好的冲突解释与推荐限定路径，二是对 references/ 的结构化摘要，让模型在进入 Level 2 前就能判断该读取哪个文件。前者减少用户困惑，后者继续压低 token 成本。至于数据库化索引，除非技能数量和外部目录规模确实上升，否则它未必比当前的按需扫描更划算。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Hermes Skill Runtime架构解析：三层加载降低Agent上下文成本要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题