ARTICLE / 开源项目
补充技能发现与幽灵建议特性的研究
PR 地址：NousResearch/hermes-agent#86940 · 技能发现：幽灵建议、悬停描述与启用开关（Desktop + CLI）
研究摘要
之前，Hermes 携带大量斜杠命令与技能目录，但大多数用户从未发现它们——能力存在，入口难找。现在，能力在打字瞬间变得可发现：Desktop 编辑器里输入自由文本时，后端 LLM 对输入意图排序匹配的斜杠命令，以幽灵文本（ghost）形式淡显，Tab 接受、Shift+Tab 轮换、Esc 撤销，悬停显示完整技能描述（长文本无缝滚动）；输入区上方短暂出现技能条，列出匹配技能的全宽未截断描述；CLI（prompt_toolkit REPL）同样对自由文本给出技能建议，接受时整行替换为 /learn <原文>，回车直接调用技能。整个特性可由 设置 → 外观 → 技能建议 一键关闭，默认开启。
实现刻意复用既有面：Desktop 侧用现有 llm.oneshot RPC（≤60 tokens、300ms 防抖、30s 缓存），CLI 侧用已挂载的 AutoSuggest，零新增服务端面。成本有界：防抖 + 缓存 + ≤4 候选 + ≤60 tokens，离线/冷缓存时零成本关键词回退。安全上建议从不自动执行——用户按 Tab 才生效，无 PII、无遥测。
一、问题背景
技能与斜杠命令的发现困境是双端共存的：Desktop 编辑器与 CLI 提示符都只响应"用户恰好知道的名字"，目录规模越大，未被发现的占比越高。能力应该在意图出现的那一刻（用户正在输入）被呈现，而不是要求用户先记住目录。要做到这一点需要解决三个问题：意图匹配（自由文本 → 哪个技能）、呈现形式（不打断输入流）、成本与安全（LLM 调用有界、绝不自动执行）。
CLI 一侧还有一层技术约束：斜杠命令只在行首解析，用户输入到一半的普通文本永远不可能被识别为技能调用——即使技能目录写得再全，用户也必须在输入之前就知道命令名，这几乎是最差的发现条件。Desktop 一侧的问题方向相反：编辑器有完整的渲染能力，但输入区空间有限，长描述被截断后用户看到的是残缺信息，无法判断这个技能是否真的匹配自己的意图。两端需要不同的解决路径，但共享同一个目标：让"知道有这个能力"这件事的成本降到零。
二、特性设计
2.1 Desktop 渲染端
- 幽灵建议（ghost-suggestion 模块）：用户在自由文本上停顿时，后端 LLM 通过既有
llm.oneshotRPC 对意图排序（≤60 tokens、300ms 防抖、30s 缓存）；零成本关键词回退覆盖离线 / 冷缓存场景。Tab 接受、Shift+Tab 轮换、Esc 撤销；用过的命令不再重复建议。 - 悬停跑马灯：悬停淡显的幽灵文本展示完整技能描述——长文本向左无缝循环滚动，短文本静止；文档级悬停检测保证浮层点击穿透。
- 技能条：输入区上方瞬时提示，列出匹配技能并显示完整未截断描述，4 秒自动隐藏，带持久化的"不再显示"控制。
- 设置开关：外观 → 技能建议（默认开），同时控制幽灵与技能条。
2.2 CLI 经典 REPL
SlashCommandAutoSuggest 现在对自由文本推荐技能：CJK 关键词 → 命令表（学习 / 无人机 → /learn）、描述子串 / bigram 匹配、命令名打分，配严格阈值保证普通对话文本永远不会被幽灵建议。三层信号的职责不同：关键词表覆盖高频中文意图表达，子串 / bigram 匹配处理描述中没有完整关键词的情况，命令名打分则兜底用户已接近命令名但拼写不完全的场景，加权后与严格阈值比较，只有置信度足够高才渲染幽灵文本。接受时把整个草稿替换为 /learn <原文>——因为斜杠命令只在行首解析，这样回车才真正调用技能。新增 auto-suggestion 样式让幽灵文本实际可见。
2.3 形态决策
后端真实保持权威：无新服务端面，复用 llm.oneshot RPC 与已挂载的 prompt_toolkit AutoSuggest；成本有界：防抖 + 30s 缓存 + ≤4 候选 + ≤60 tokens，离线走关键词回退；安全：建议从不自动执行，用户按 Tab 才生效。
三、实测结果
| 项目 | 结果 |
|---|---|
| Desktop ghost / skill 用例（vitest） | 30 个通过；全量套件 3503 passed（2 个预存环境相关失败在 time.ts / billing，与本特性无关） |
CLI test_commands.py | 52 passed；completion / path / gateway 套件 542 passed |
| 实机 CDP 验证 | 幽灵渲染 → Tab 接受（草稿变为 /learn 我要学习无人机）→ 技能条全宽显示 4s → 开关关闭再打开恢复 |
| app.asar 重打包验证 | 零非资源文件丢失（node-pty、electron-main.mjs、electron-preload.js 均保留） |
四、平台兼容性与能力边界
| 面 | 说明 |
|---|---|
| Desktop（Electron，macOS / Windows / Linux） | 意图匹配需要 LLM 能力网关；关键词回退在无网关 / 离线时仍覆盖核心命令 |
CLI（display.interface: cli / hermes --cli 经典 REPL） | 纯本地规则匹配，无 LLM 依赖 |
边界与局限：Desktop 的意图匹配依赖 LLM 能力网关，网关离线时只有关键词回退的核心命令覆盖；CLI 侧 Python 模块在进程启动时缓存，升级后需重启 hermes 才能看到幽灵建议；旧 app.asar 下 Tab 无响应，需重启新版 Desktop；严格阈值意味着部分模糊意图不会触发建议（有意的保守）；技能建议依赖输入暂停（300ms 防抖），连续快速输入时不出现。建议质量还受技能描述文本本身约束——描述含糊的技能难以被关键词与子串匹配命中，只能靠命令名打分兜底，这反过来对技能作者维护描述质量提出了要求。
五、PR 信息
- PR 地址：https://github.com/NousResearch/hermes-agent/pull/86940
- 改动规模：+1452 / -80，21 个文件
- 状态：open
- 提交时间：2026-08-15
本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。