一文看懂 Hermes Agent 的 Prompt Builder：系统提示词到底拼进了什么？

一、先说结论Prompt Builder 是 Hermes 的“提示词总装车间”普通 Chatbot 的系统提示词往往是一段固定文字告诉模型“你是谁、怎么回答”。Hermes Agent 的 Prompt Builder 更像一条总装线它会把身份、记忆、用户画像、项目规则、技能目录、平台差异、工具使用规程、时间信息等材料统一组装形成一次会话真正使用的系统提示词。这件事很关键因为 Agent 不只是回答问题它还会读文件、改代码、调用工具、跨平台回复、延续历史任务。模型要安全地行动必须先知道当前任务边界、项目规则、可用能力、输出渠道和长期约束。官方架构文档把 prompt_builder.py 放在 Prompt System 中说明它负责从 SOUL.md、MEMORY.md、USER.md、Skills、Context Files、工具使用指导和模型特定指令中组装系统提示词。1.1 它解决的不是“写一句好 Prompt”而是“上下文治理”Prompt Builder 的难点不在于写得漂亮而在于判断信息该放在哪里。身份信息、项目规则、长期记忆、一次性提示、技能索引、平台渲染规则如果全混在一起系统就会变得难缓存、难维护、难排查也容易出现上下文污染。所以 Hermes 的设计思路是长期稳定的信息进入 cached system prompt只对当前调用有效的信息放到 ephemeral layers可复用流程沉淀为 Skills历史会话通过 session_search 按需检索项目规则通过 Context Files 加载。二、系统提示词会拼进哪几层内容官方 Prompt Assembly 文档明确给出 cached system prompt 的大致组装顺序Agent Identity、工具感知行为指导、Honcho 静态块、可选 system message、MEMORY 快照、USER 快照、Skills Index、Context Files、时间戳/Session ID、Platform Hint。2.1 第一层Agent Identity也就是“我是谁”最前面的身份层来自 ~/.hermes/SOUL.md。如果存在并且有内容SOUL.md 会替换代码里的默认身份如果不存在Prompt Builder 会回退到 DEFAULT_AGENT_IDENTITY。官方文档也强调SOUL.md 是从 HERMES_HOME 加载不是从当前项目目录加载。这层适合放 Agent 的长期人格、表达风格、工作原则例如“你是一个严谨的工程助手”“回答前优先验证事实”“不要为了显得聪明而编造”。它不适合放某个项目的 API 路径也不适合放一次任务的临时要求。2.2 第二层Tool-aware 行为指导告诉 Agent 如何行动Hermes 不是普通聊天机器人它会调用工具。因此 Prompt Builder 会注入工具相关的行为指导比如什么时候保存 Memory、什么时候使用 session_search、什么时候沉淀 Skill、什么时候必须实际调用工具而不是只描述计划。在 GitHub 的 prompt_builder.py 里可以看到 MEMORY_GUIDANCE、SESSION_SEARCH_GUIDANCE、SKILLS_GUIDANCE、TOOL_USE_ENFORCEMENT_GUIDANCE 等常量。它们不是业务内容而是 Agent 的操作规程。2.3 第三层Honcho 静态块启用时补充更深的记忆上下文当 Hermes 启用 Honcho 等外部记忆增强能力时会有额外的静态上下文块进入提示词。你可以把它理解为更强的用户建模和长期背景增强层。它不是所有安装都必然启用但 Prompt Builder 预留了这个位置。2.4 第四层Optional System Message用于部署或调用方补充某些调用场景会传入额外 system message比如企业部署要求、API Server 层面的统一风格、某个入口自带的约束。Prompt Builder 会把它作为可选层加入而不是让它覆盖全部系统。2.5 第五层和第六层MEMORY 与 USER 快照MEMORY.md 保存长期事实、环境细节、稳定约定USER.md 保存用户画像、长期偏好和习惯。官方文档说明本地 memory 和用户 profile 会在 session 开始时作为冻结快照注入session 中途写入磁盘不会立刻改变已经构建好的系统提示词。2.6 第七层Skills Index技能目录而不是技能全文Skills 是 Hermes 的经验沉淀机制但 Prompt Builder 不会把所有技能全文都塞进系统提示词。它通常放入一个紧凑的 skills index让模型先知道有哪些技能、适合什么场景需要时再通过 skill_view 加载完整内容。这就是 progressive disclosure先放目录再按需加载正文。它能显著降低 token 成本也能避免无关技能干扰当前任务。2.7 第八层Context Files当前项目的规则说明Hermes 通过 Context Files 知道当前项目。官方文档说明启动时会按优先级扫描 .hermes.md / HERMES.md、AGENTS.md、CLAUDE.md、.cursorrules / .cursor/rules/*.mdc命中后读取、扫描、截断并组装到 # Project Context 下。这些文件适合放项目级约定例如技术栈、目录结构、测试命令、提交规范、禁止修改的目录、API 入口、代码风格。它们不适合放用户长期偏好也不适合放一次性任务。2.8 第九层时间戳和 Session ID时间戳让 Agent 知道当前时间避免把过去和现在混淆Session ID 则用于任务追踪、会话恢复、日志关联。对于跨平台、长任务、自动化场景这些元信息非常重要。2.9 第十层Platform Hint告诉 Agent 当前在哪个入口说话同一段回答在 CLI、Telegram、Slack、Email、Cron、WebUI 中表达方式不同。Prompt Builder 会加入平台提示告诉模型应该用什么格式输出、能不能发送媒体、能不能使用 Markdown、能不能反问用户。三、为什么要区分 Cached Prompt 和 Ephemeral Prompt官方文档强调Hermes 有意把 cached system prompt state 和 API-call-time-only additions 分开。这是 Prompt Builder 最重要的设计之一因为它直接影响 token 使用、prompt caching 效果、session 连续性和 memory 语义正确性。3.1 Cached Prompt长期稳定适合缓存SOUL.md、MEMORY 快照、USER 快照、Skills Index、Context Files 这些内容相对稳定适合构成系统提示词前缀。对支持 prompt caching 的模型和 provider 来说稳定前缀越稳定缓存收益越明显。3.2 Ephemeral Prompt只对当前调用有效ephemeral_system_prompt、prefill messages、gateway-derived session overlays、later-turn Honcho recall 等内容只应该影响本次调用。如果把这些临时内容固化进系统提示词会让后续任务受到污染。3.3 这个边界解决了三个工程问题降低成本稳定部分更容易复用缓存减少重复处理。减少污染临时上下文不会变成长期规则。便于排查出现问题时可以判断是长期层错了还是本轮临时层错了。四、Context FilesPrompt Builder 怎么让 Hermes 知道当前项目项目上下文是 Prompt Builder 最容易产生误解的地方。很多人以为 Agent 会自动理解整个仓库其实不是。它依赖明确的项目规则文件把“这个项目怎么做事”写进系统提示词。官方 Context Files 文档给出的启动流程很清楚扫描工作目录、读取文件、执行安全扫描、对超过 20,000 字符的文件做头尾截断、组装到 # Project Context 下然后注入系统提示词。4.1 优先级不是全都加载而是 first match winsPrompt Builder 对项目文件使用优先级机制。官方文档写到.hermes.md / HERMES.md 优先其次是 AGENTS.md然后是 CLAUDE.md最后是 .cursorrules / .cursor/rules/*.mdc。它不是把所有文件都无脑拼进去而是按规则选择项目上下文。4.2 安全扫描防止项目文件变成 Prompt 注入入口Context Files 会被扫描检查类似“ignore previous instructions”、隐藏 HTML、不可见字符、凭证外泄命令、读取 .env 等危险模式。这说明 Prompt Builder 不只是拼文本它还承担了系统提示词入口的安全过滤职责。4.3 子目录规则执行中渐进发现启动时通常加载顶层规则。执行过程中SubdirectoryHintTracker 会从工具调用参数中提取路径在相关目录和父目录中寻找 AGENTS.md、CLAUDE.md、.cursorrules 等文件并把发现的规则追加到工具结果里让模型自然看到更细的目录规则。五、Memory、Skills、Context Files 三者到底怎么分工理解 Prompt Builder最关键的是分清这三类信息。它们都可能进入模型上下文但性质完全不同。信息类型应该放什么不应该放什么进入方式Memory长期稳定事实、环境、用户偏好任务进度、临时 TODO、过期结果MEMORY.md / USER.md 冻结快照Skills可复用流程、复杂任务经验、标准操作步骤一次性事实、当前项目路径Skills Index skill_view 按需加载Context Files当前项目规则、目录结构、测试命令、代码规范个人长期偏好、跨项目事实.hermes.md / AGENTS.md 等注入 # Project ContextEphemeral Layers本次调用临时补充、Gateway 当轮覆盖长期规则、稳定偏好API-call-time-only 附加六、平台提示与环境提示为什么同一个 Agent 在不同入口表现不同Hermes 支持 CLI、Telegram、Discord、Slack、Email、Cron、WebUI 等入口。不同入口的输出格式和交互方式差异很大CLI 不能真正发送附件Telegram 有自己的 Markdown 和媒体发送方式Email 更适合纯文本结构Cron 没有人在场不能反问。prompt_builder.py 中维护了 PLATFORM_HINTS针对不同平台给模型补充输出规则。这样做的好处是同一个任务在不同渠道不会用错表达方式。除此之外还有环境提示。例如 WSL、Windows Bash、Docker、SSH、Modal 等运行环境会影响路径、shell 语法、文件系统位置。Prompt Builder 会把这些差异告诉模型减少“命令跑错环境”的问题。七、Prompt Builder 与 Tool Schema 是什么关系Prompt Builder 主要负责系统提示词内容而工具 schema 则告诉模型“有哪些工具可以调用、每个工具需要什么参数”。在 Agent Loop 中AIAgent 会通过 prompt_builder.py 组装有效系统提示词和工具 schema然后选择 provider/API mode 发起模型调用。可以这样理解Prompt Builder 负责告诉模型“该怎么想、该遵守什么规则、当前任务背景是什么”Tool Schema 负责告诉模型“你可以做哪些动作”。两者结合模型才能从聊天变成可执行的 Agent。八、如果你想改 Hermes 的 Prompt应该改哪里官方文档建议绝大多数用户不要直接改 agent/prompt_builder.py。这个文件是实现代码不是配置面。直接改它等于改全局组装逻辑适合维护 fork 或贡献上游不适合日常使用。8.1 想改身份风格改 SOUL.md例如你希望 Agent 更像严谨工程师、研究助手、运维专家就改 ~/.hermes/SOUL.md。8.2 想改长期事实改 MEMORY.md / USER.md例如用户长期偏好、常用技术栈、固定环境、稳定项目路径可以放进 MEMORY.md 或 USER.md。8.3 想改项目规则改 Context Files例如“这个仓库用 pytest”“提交前运行 make lint”“不要改 generated 目录”应该写入 .hermes.md、AGENTS.md、CLAUDE.md 或 .cursorrules。8.4 想改可复用流程做成 Skill例如“发布流程”“排查线上故障流程”“写技术文章流程”“做代码审查流程”更适合做成 SKILL.md而不是塞进 Memory。8.5 想加单次限制用 Ephemeral 层例如某次任务要求“只输出 JSON”“这次不要改代码只分析”这类临时约束应该走 ephemeral_system_prompt 或调用方覆盖不应该写进长期文件。九、一次 Prompt 构建可以这样理解把 Hermes Prompt Builder 想象成一个“任务说明书生成器”它先从磁盘和配置里收集材料再做安全处理和截断然后按层级组装稳定提示词最后叠加当前平台和当次调用的临时信息送给模型。9.1 用一句话总结完整流程收集身份、记忆、用户画像、项目规则、技能目录和平台环境信息对外部文本做扫描与截断按稳定性和优先级分层组装把稳定部分作为 cached system prompt把当次临时内容作为 ephemeral layer最后交给 AIAgent 和 provider 执行模型调用。十、面向 Java 后端/AI 应用开发者的启发如果你要自己做 Agent 系统Prompt Builder 这套设计非常值得借鉴。不要把所有指令硬编码成一个长 prompt而要把信息分层管理。身份层定义助手是谁、长期风格是什么。记忆层保存长期事实和用户偏好但不要保存临时结果。项目层保存当前项目规则、目录结构、测试命令。技能层保存可复用流程按需加载。工具层通过工具 schema 告诉模型能做什么。平台层根据入口差异控制输出格式。临时层当次调用有效不污染长期状态。这样做之后你的 Agent 系统会更像一个可维护的工程平台而不是一堆堆叠 prompt 的脚本。十一、总结Prompt Builder 是 Agent 从“会聊天”变成“会做事”的前置大脑Hermes Agent 的 Prompt Builder 并不是简单拼接几段提示词而是在做系统级上下文编排。它把 Agent 身份、长期记忆、用户画像、项目规则、技能索引、工具使用指导、平台渲染规则、环境信息和临时调用层有序组织起来。真正值得学习的是它的工程思想稳定和临时分开事实和流程分开项目规则和用户偏好分开技能目录和技能全文分开平台渲染和业务逻辑分开。只有这样Agent 才能在长任务、跨平台、多工具、多会话场景下保持可控。所以Prompt Builder 的价值不是“让模型更会说”而是“让模型知道在什么上下文里、以什么身份、遵守什么规则、调用什么能力、完成什么动作”。这正是 Agent 工程化的核心。