ARTICLE / 开源项目

补充主动能力路由建议特性的研究

Updated
Reading time
6 min

PR 地址：NousResearch/hermes-agent#81582 · 在正确的时机，建议正确的 Hermes 能力

研究摘要

Hermes 拥有几十种能力——并行子代理、定时任务、记忆、MCP、看板——但没有任何一层告诉 agent"此刻该用哪个"。技能是被动加载的：用户提到相关关键词才被唤起；能力与需求之间的匹配完全靠 agent 临场发挥，用户不知道"这件事 Hermes 有专门的能力"，能力也不知道"这个需求正是我的用武之地"。

本 PR 新增主动能力路由器（+718 行，5 个文件）：一个声明式的能力注册表描述"什么信号对应什么能力"，回合级引擎在每轮对话开始前匹配信号，命中后把建议以文本形式附加进当前回合的上下文——“检测到 3 个独立子任务，可考虑使用 delegate_task”。默认只建议不执行、默认全局关闭、任何环节失败都只是"这轮没有建议"。

一、问题背景：能力丰富的 agent，路由贫瘠的时机

1.1 被动加载的缺口

Hermes 的能力接入方式是被动引用：技能在 prompt 里被引用才加载，工具被调用才生效。这带来一个结构性盲区——“什么能力适配当前需求"这个判断，没有人在回合开始前做。用户在说"帮我并行处理这 3 个文件"时，系统不会主动提示"这适合并行子代理”；用户说"每天早上下载数据"时，系统不会主动提示"这适合定时任务"。

1.2 先例检索的结果

PR 作者对仓库做了先例检索（proactive、feature suggestion、capability routing），结论是没有任何既有基础设施：记忆系统的 nudge 与 prefetch 持久化的是事实，不是能力路由；技能按引用被动加载；没有人在回合时评估"哪个 Hermes 特性适配这个请求"。相关议题（#57731、#13588）的诉求是"让 Hermes 知道它能做什么"，本 PR 是这件事的应用半边——与配套的 What’s New PR（发现半边）互补成完整回路。

1.3 主动提示的两难

主动提示天然面临两难：提示得太勤是噪音，提示得不准是误导，提示失败还可能拖垮回合。设计上必须同时解决"准"（信号匹配）、“静”（限速与开关）、“稳”（失败即无建议）。

二、特性设计：注册表 + 回合级引擎 + sidecar 注入

2.1 声明式能力注册表

agent/feature_registry.py 定义能力注册表，每条目包含：能力 ID、触发信号（关键字/模式，OR 语义——任一命中即触发）、该特性的最低置信度阈值、以及一条可解释的 why 字符串（建议给出时说明为什么建议它）。

两个关键约束：

  • 只引用已审计的既有能力：注册表条目引用 delegate_task、cronjob、web_search、memory、/whats-new 这类已经存在的工具与能力，不新增任何核心工具（遵守 AGENTS.md 的窄腰规则）；
  • 白名单守卫：条目若引用了未知能力名，直接丢弃——纵深防御，保证注册表条目无法被指向危险目标。

2.2 回合级引擎

agent/feature_router.py 在每个回合开始前运行：

  • 默认只建议（SUGGEST）：输出是附加到当前回合 API 副本的咨询文本；auto_apply 是显式选择加入的，且自动应用仍走正常审批管线，破坏性操作过审批门；
  • 限速：一次建议后抑制后续 N 个回合，避免连续刷屏；
  • 两级开关：每个特性独立的 kill switch + 全局主开关（默认关闭）；
  • 非致命：任何错误路径都只导致"本轮无建议"，一个坏路由器永远拖不垮一个回合。

2.3 sidecar 注入：不碰系统提示，不动存储

路由结果经由 agent/turn_context.py + agent_init.py 走既有的 ext_prefetch_cache → api_content sidecar 通道——与记忆 provider 同一条管道。它从不修改存储内容、从不改动系统提示词，保住 prompt-cache 不变量；注入发生在回合起始，CLI / TUI / 网关（飞书、Telegram 等）所有界面天然共享。

2.4 配置与示例

配置面集中在 proactive_features 段：enabled 控制总开关（默认关闭）；min_confidence 设全局置信度下限（默认 0.7，约等于至少一个信号命中）；rate_limit_turns 控制一次建议后抑制的回合数（默认 5）；auto_apply 决定是否允许 agent 免确认应用建议（默认 false，开启后破坏性操作仍过审批门）；features 映射提供每特性独立开关，例如 parallel_subtasks 与 scheduled_recurring 可单独启停。运行时可用 hermes config set proactive_features.enabled true 打开，关闭同理。

预期示例（PR body）：“帮我并行处理这 3 个文件” → 建议 delegate_task；“每天早上下载数据” → 建议 cronjob；“搜索今天的新闻” → 建议 web_search。

三、实测结果

3.1 测试套件

测试组结果
tests/hermes_cli/test_feature_router.py（匹配、置信度、限速、开关、失败路径）25 passed
tests/agent/test_turn_context.py + test_system_prompt.py49 passed
ruff check全部干净（PLW1514 已遵守）

测试覆盖了设计承诺的不变量：默认关闭基线、能力名白名单守卫、无网络、无子进程、限速生效、非致命失败路径、sidecar 注入不破坏 prompt-cache（字节稳定性推理 + 测试双重验证）。

四、平台兼容性与能力边界

平台支持
macOS / Linux / Windows平台无关（纯 Python，无子进程、无 shell）
CLI / TUI / 网关（飞书、Telegram 等）回合起始经共享 api_content 路径注入，全表面可用
Docker / serverless无网络出口、除 HERMES_HOME 外无文件系统假设

能力边界与已知约束：

  • 默认关闭：不开启配置的用户完全无感知，特性不产生任何默认行为；
  • v1 是确定性匹配：关键字是精确子串匹配，注册表是种子形态——未收录的说法不会触发建议；LLM 评分分类被列为 v2 选项（需配幻觉护栏）；
  • 建议不是执行：即使开启，默认也只产出建议文本；auto_apply 开启后破坏性操作仍过审批门；
  • 不覆盖"用户已知道的能力"：路由只解决"该用时提示"，不负责教学用户全部能力；
  • 无遥测：建议计数仅本地，外发按仓库遥测规则需显式选择加入；
  • PR 状态为 open，自测数据为开发记录，尚未合入主线。

五、PR 信息

  • PR 地址：https://github.com/NousResearch/hermes-agent/pull/81582
  • 改动规模：+718 / -0，5 个文件
  • PR 状态：open
  • 提交时间：2026-08-08

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

RELATED SIGNALS

继续探索