字节笔记本
2026年6月21日
hermes教程-提示词组装
提示词组装
Hermes 有意将以下部分分离:
- 缓存的系统提示词状态
- 临时的 API 调用时附加内容
这是项目中最重要的设计选择之一,因为它会影响:
- token 使用量
- 提示词缓存效果
- 会话连续性
- 记忆正确性
主要文件:
run_agent.pyagent/prompt_builder.pytools/memory_tool.py
缓存的系统提示词层级
缓存的系统提示词按三个有序层级组装(参见 agent/system_prompt.py):
- 稳定层 — 身份(
SOUL.md或后备)、工具/模型指导、技能提示、环境提示、平台提示 - 上下文层 — 调用者提供的
system_message以及项目上下文文件(.hermes.md/AGENTS.md/CLAUDE.md/.cursorrules) - 易变层 — 内置记忆快照(
MEMORY.md)、用户画像快照(USER.md)、外部记忆提供者块、时间戳/会话/模型/提供者行
最终的系统提示词按以下顺序拼接:稳定层 → 上下文层 → 易变层。
这种顺序对于优先级讨论很重要:
- 技能属于稳定层
- 记忆/画像快照属于易变层
- 两者都仍在缓存的系统提示词中(它们不会作为临时的回合中覆盖层注入)
当设置了 skip_context_files(例如子代理委派)时,不会加载 SOUL.md,而是使用硬编码的 DEFAULT_AGENT_IDENTITY。
具体示例:组装后的系统提示词
以下是所有层级都存在时最终系统提示词的简化视图(注释显示了每个部分的来源):
## 第1层:代理身份(来自 ~/.hermes/SOUL.md)
You are Hermes, an AI assistant created by Nous Research.
You are an expert software engineer and researcher.
You value correctness, clarity, and efficiency.
...
## 第2层:工具感知行为指导
You have persistent memory across sessions. Save durable facts using
the memory tool: user preferences, environment details, tool quirks,
and stable conventions. Memory is injected into every turn, so keep
it compact and focused on facts that will still matter later.
...
When the user references something from a past conversation or you
suspect relevant cross-session context exists, use session_search
to recall it before asking them to repeat themselves.
## 工具使用强制(仅适用于 GPT/Codex 模型)
You MUST use your tools to take action — do not describe what you
would do or plan to do without actually doing it.
...
## 第3层:Honcho 静态块(启用时)
[Honcho personality/context data]
## 第4层:可选系统消息(来自配置或 API)
[User-configured system message override]
## 第5层:冻结的 MEMORY 快照
## Persistent Memory
- User prefers Python 3.12, uses pyproject.toml
- Default editor is nvim
- Working on project "atlas" in ~/code/atlas
- Timezone: US/Pacific
## 第6层:冻结的 USER 画像快照
## User Profile
- Name: Alice
- GitHub: alice-dev
## 第7层:技能索引
## Skills (mandatory)
Before replying, scan the skills below. If one clearly matches
your task, load it with skill_view(name) and follow its instructions.
...
<available_skills>
software-development:
- code-review: Structured code review workflow
- test-driven-development: TDD methodology
research:
- arxiv: Search and summarize arXiv papers
</available_skills>
## 第8层:上下文文件(来自项目目录)
## Project Context
The following project context files have been loaded and should be followed:
## AGENTS.md
This is the atlas project. Use pytest for testing. The main
entry point is src/atlas/main.py. Always run `make lint` before
committing.
## 第9层:时间戳 + 会话
Current time: 2026-03-30T14:30:00-07:00
Session: abc123
## 第10层:平台提示
You are a CLI AI Agent. Try not to use markdown but simple text
renderable inside a terminal.SOUL.md 在提示词中的呈现方式
SOUL.md 位于 ~/.hermes/SOUL.md,作为代理的身份——系统提示词的第一部分。prompt_builder.py 中的加载逻辑如下:
## 来自 agent/prompt_builder.py(简化版)
def load_soul_md() -> Optional[str]:
soul_path = get_hermes_home() / "SOUL.md"
if not soul_path.exists():
return None
content = soul_path.read_text(encoding="utf-8").strip()
content = _scan_context_content(content, "SOUL.md") # 安全扫描
content = _truncate_content(content, "SOUL.md") # 默认上限 20k 字符,可配置
return content当 load_soul_md() 返回内容时,它会替换硬编码的 DEFAULT_AGENT_IDENTITY。随后调用 build_context_files_prompt() 时传入 skip_soul=True,以防止 SOUL.md 出现两次(一次作为身份,一次作为上下文文件)。
如果 SOUL.md 不存在,系统会回退到:
You are Hermes Agent, an intelligent AI assistant created by Nous Research.
You are helpful, knowledgeable, and direct. You assist users with a wide
range of tasks including answering questions, writing and editing code,
analyzing information, creative work, and executing actions via your tools.
You communicate clearly, admit uncertainty when appropriate, and prioritize
being genuinely useful over being verbose unless otherwise directed below.
Be targeted and efficient in your exploration and investigations.上下文文件的注入方式
build_context_files_prompt() 使用优先级系统——只加载一种项目上下文类型(第一个匹配项胜出):
## 来自 agent/prompt_builder.py(简化版)
def build_context_files_prompt(cwd=None, skip_soul=False):
cwd_path = Path(cwd).resolve()
## 优先级:第一个匹配项胜出——只加载一个项目上下文
project_context = (
_load_hermes_md(cwd_path) # 1. .hermes.md / HERMES.md(向上遍历到 git 根目录)
or _load_agents_md(cwd_path) # 2. AGENTS.md(仅当前工作目录)
or _load_claude_md(cwd_path) # 3. CLAUDE.md(仅当前工作目录)
or _load_cursorrules(cwd_path) # 4. .cursorrules / .cursor/rules/*.mdc
)
sections = []
if project_context:
sections.append(project_context)
## 来自 HERMES_HOME 的 SOUL.md(独立于项目上下文)
if not skip_soul:
soul_content = load_soul_md()
if soul_content:
sections.append(soul_content)
if not sections:
return ""
return (
"# Project Context\n\n"
"The following project context files have been loaded "
"and should be followed:\n\n"
+ "\n".join(sections)
)上下文文件发现细节
| 优先级 | 文件 | 搜索范围 | 说明 |
|---|---|---|---|
| 1 | .hermes.md, HERMES.md | 当前工作目录向上到 git 根目录 | Hermes 原生项目配置 |
| 2 | AGENTS.md | 仅当前工作目录 | 通用代理指令文件 |
| 3 | CLAUDE.md | 仅当前工作目录 | Claude Code 兼容性 |
| 4 | .cursorrules, .cursor/rules/*.mdc | 仅当前工作目录 | Cursor 兼容性 |
所有上下文文件都会:
- 进行安全扫描 — 检查提示注入模式(不可见 Unicode、“忽略之前的指令”、凭证窃取尝试)
- 进行截断 — 限制在
context_file_max_chars字符(默认 20,000),使用 70/20 头尾比例并带有截断标记 - 剥离 YAML 前置元数据 — 移除
.hermes.md的前置元数据(保留用于未来的配置覆盖)
仅 API 调用时添加的层级
以下部分有意不持久化到缓存的系统提示词中:
ephemeral_system_prompt- 预填充消息
- 网关派生的会话上下文覆盖
- 后续回合中注入到当前回合用户消息的 Honcho/外部召回
pre_llm_call 插件上下文也位于此 API 调用时路径中:它被追加到当前回合的用户消息中,而不是写入缓存的系统提示词。当多个插件返回上下文时,Hermes 会拼接这些上下文块(参见 Hooks → pre_llm_call)。
这种分离保持了稳定前缀的稳定性,有利于缓存。
记忆快照
本地记忆和用户画像数据被捕获在系统提示词的易变层中。会话中的写入会更新磁盘状态,但不会改变已构建的缓存系统提示词,直到触发重建路径(新会话,或显式失效/重建流程,例如压缩触发的重建)。
上下文文件
agent/prompt_builder.py 使用优先级系统扫描和清理项目上下文文件——只加载一种类型(第一个匹配项胜出):
.hermes.md/HERMES.md(向上遍历到 git 根目录)AGENTS.md(启动时的当前工作目录;子目录在会话期间通过agent/subdirectory_hints.py逐步发现)CLAUDE.md(仅当前工作目录).cursorrules/.cursor/rules/*.mdc(仅当前工作目录)
SOUL.md 通过 load_soul_md() 单独加载,用于身份槽。当加载成功时,build_context_files_prompt(skip_soul=True) 会防止它出现两次。
长文件在注入前会被截断。
技能索引
当技能工具可用时,技能系统会向提示词贡献一个紧凑的技能索引。
支持的提示词自定义接口
大多数用户应将 agent/prompt_builder.py 视为实现代码,而非配置接口。支持的自定义路径是更改 Hermes 已加载的提示词输入,而不是直接编辑 Python 模板。
优先使用这些接口
~/.hermes/SOUL.md— 用你自己的代理角色和固定行为替换内置的默认身份块。~/.hermes/MEMORY.md和~/.hermes/USER.md— 提供跨会话的持久事实和用户画像数据,这些数据应被快照到新会话中。- 项目上下文文件,如
.hermes.md、HERMES.md、AGENTS.md、CLAUDE.md或.cursorrules— 注入仓库特定的工作规则。 - 技能 — 打包可重用工作流和参考,无需编辑核心提示词代码。
- 可选的系统提示词配置 / API 覆盖 — 添加部署特定的指令文本,无需分叉 Hermes。
- 临时覆盖,如
HERMES_EPHEMERAL_SYSTEM_PROMPT或预填充消息 — 添加回合范围的指导,不应成为缓存提示词前缀的一部分。
何时改为编辑代码
仅当你有意维护一个分支或向上游贡献行为变更时,才编辑 agent/prompt_builder.py。该文件为每个会话组装提示词管道、缓存边界和注入顺序。直接编辑该文件是全局产品变更,而非针对用户的提示词自定义。
换句话说:
- 如果你想要不同的助手身份,编辑
SOUL.md - 如果你想要不同的仓库规则,编辑项目上下文文件
- 如果你想要可重用的操作流程,添加或修改技能
- 如果你想要改变 Hermes 为所有人组装提示词的方式,修改 Python 并将其视为代码贡献
为什么提示词组装要这样拆分
该架构有意优化以:
- 保留提供者端的提示词缓存
- 避免不必要地变更历史记录
- 保持记忆语义清晰易懂
- 让网关/ACP/CLI 添加上下文而不污染持久提示词状态