企业官网建设流程全解析

一、先说结论：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 Files：Prompt Builder 怎么让 Hermes 知道当前项目？

项目上下文是 Prompt Builder 最容易产生误解的地方。很多人以为 Agent 会自动理解整个仓库，其实不是。它依赖明确的项目规则文件，把“这个项目怎么做事”写进系统提示词。

官方 Context Files 文档给出的启动流程很清楚：扫描工作目录、读取文件、执行安全扫描、对超过 20,000 字符的文件做头尾截断、组装到 # Project Context 下，然后注入系统提示词。

4.1 优先级：不是全都加载，而是 first match wins

Prompt 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，最关键的是分清这三类信息。它们都可能进入模型上下文，但性质完全不同。

六、平台提示与环境提示：为什么同一个 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 工程化的核心。