logo

部署Hermes Agent后必做:SOUL、USER、AGENTS配置教程

作者:carzy2026.11.17 03:42浏览量:1

简介:Hermes Agent 部署成功后,真正决定使用效果的是 SOUL.md、USER.md、AGENTS.md 三个核心文件。本文给出三者的职责边界、可直接套用的模板、加载优先级与冲突处理规则,并附验证用例和常见故障排查表,帮你把"空壳工具"调成真正懂你的长期协作者。

部署成功只是”装好了”,不等于”配好了”。Hermes Agent 的差异化能力几乎全部来自三个 Markdown 文件: SOUL.md 决定它”是谁、怎么说话”, USER.md 决定它”对你了解多少”, AGENTS.md 决定它”按什么流程干活”。三者缺任何一个,Agent 就会表现出回应生硬、答非所问、不遵守工作流等典型症状。

在动手写这三个文件之前,建议先花几分钟在 百度智能云词元所 上了解不同大模型的能力边界与调用成本——SOUL 里写的人格设定能否被稳定执行、AGENTS 里的多步流程能否跑通,很大程度上取决于底层模型选得对不对。

一、三个文件的职责边界

很多人配置失败,是因为把三件事混在一个文件里写,导致职责重叠、互相打架。

文件 回答的问题 影响范围 缺失时的典型症状
SOUL.md 你是谁、用什么口吻表达 人格、语气、专业边界、拒答方式 回应生硬、风格漂移、像通用客服
USER.md 我是谁、我习惯怎么协作 认知背景、术语理解、输出格式偏好 反复解释基础知识、格式总是不对
AGENTS.md 你按什么规则和步骤工作 工具调用、SOP、代码规范、验证要求 跳步骤、乱改文件、不验证就交付

一个便于记忆的判断标准:SOUL 管 风格 ,USER 管 上下文 ,AGENTS 管 行为 。

二、SOUL.md:定义人格与表达边界

SOUL.md 不是”角色扮演文案”,而是模型每一轮都会读取的行为基线,作用等同于系统设计提示词中的角色指令部分。写好它有三个要点:用可观察的行为描述替代抽象形容词;明确专业边界;给出拒答和求助的标准动作。

  1. # SOUL
  2. ## 身份
  3. 你是一名资深后端工程师,长期与一位 3 年经验的全栈开发者协作。
  4. ## 表达风格
  5. - 结论先行,再给理由;单条回复不超过 300 字,除非用户要求展开。
  6. - 中文技术术语保留英文原词(如幂等、连接池),不翻译成生硬中文。
  7. - 不使用"很高兴为您服务""希望对您有帮助"等客套话。
  8. ## 专业边界
  9. - 涉及生产环境变更、数据删除、权限调整时,先说明风险并等待确认。
  10. - 不确定的事实直接说"不确定",禁止编造 API 参数或版本号。
  11. ## 求助动作
  12. 信息不足时,一次性列出所有缺失项,不要逐轮挤牙膏式提问。

注意:写”要做什么”比堆”不要做什么”有效得多。大段禁止句式会挤占上下文,还容易让模型在边界场景过度保守。

三、USER.md:建立用户身份档案

USER.md 是 Agent 的”长期记忆锚点”,解决的是”每次都从零开始认识你”的问题。建议按 稳定信息 和 易变信息 分层,稳定信息写详细,易变信息标注更新日期。

  1. # USER
  2. ## 基本信息
  3. - 角色:全栈开发者,主要维护一个 SaaS 项目(Node.js + PostgreSQL + React)
  4. - 语言:中文;时区:UTC+8
  5. - 经验:熟悉 CRUD 与 REST 设计,对 Kubernetes 和 KMS 不熟
  6. ## 协作偏好
  7. - 代码示例优先给完整可运行版本,不要伪代码片段
  8. - 涉及架构选择时,给出 2-3 个方案对比表,并标注推荐项及理由
  9. - 排查问题时,先给最可能的原因,再列次要原因
  10. ## 禁忌
  11. - 不要默认使用 TypeScript(本项目为 JavaScript + JSDoc)
  12. - 不要主动引入新依赖,除非说明替代方案
  13. ## 易变信息(更新于 2026-11)
  14. - 当前在做:把单体拆成模块化单体,暂不引入微服务

隐私最小化是这里的硬性原则:身份证号、密钥、客户真实数据不要写进 USER.md,它是明文文件,会随上下文一起进入每次请求。

agents-md-">四、AGENTS.md:把流程写成可执行约束

AGENTS.md 是三份文件里技术含量最高的一份,本质是把你的工作流显式化。写得越具体,Agent 就越接近”可控的工作流形态”,而不是完全依赖模型即兴发挥的自主规划形态。

  1. # AGENTS
  2. ## 标准任务流程(代码修改类)
  3. 1. 读取相关文件,列出受影响的模块清单
  4. 2. 说明修改方案,等待确认后再动手
  5. 3. 修改代码,遵守 .eslintrc 与现有命名风格
  6. 4. 运行 `npm test`,失败则修复后重跑,最多重试 2 次
  7. 5. 输出变更摘要:改了哪些文件、为什么改、如何验证
  8. ## 工具使用规则
  9. - 读文件优先用检索工具定位,不要整目录遍历
  10. - 禁止直接执行 `git push`、`rm -rf`、数据库 DROP 语句
  11. - 安装依赖前先检查 package.json 是否已有同类库
  12. ## 输出模板
  13. 变更摘要 / 验证结果 / 遗留风险(三段式,缺一不可)
  14. ## 升级条件
  15. 同一问题连续 2 次修复失败,停止尝试并输出失败原因分析。

五、加载优先级与冲突处理

三份文件同时存在时必然出现指令冲突,必须提前定义优先级,否则模型行为会随机漂移。推荐的裁决顺序:

  1. 安全与合规约束 (AGENTS.md 中的禁止项)
  2. AGENTS.md 的流程与规范
  3. SOUL.md 的人格与表达风格
  4. USER.md 的个人偏好

举例:USER.md 写”回答尽量简短”,AGENTS.md 要求”输出三段式变更摘要”,此时按流程走,因为流程属于工作契约,偏好属于风格倾向。建议在 AGENTS.md 顶部直接写明这条优先级,比事后靠提示词纠正稳定得多。

六、配置完成后如何验证

不要凭感觉判断”配好了”,用一组固定用例做回归测试:

  • 风格一致性 :问一个闲聊问题,检查语气、长度、客套话是否符合 SOUL。
  • 背景理解 :说”帮我优化下那个查询”,看它是否知道指的是哪个项目的哪段代码。
  • 流程遵从 :给一个改代码任务,检查是否走完”列影响面 → 等确认 → 改 → 跑测试 → 摘要”。
  • 越界兜底 :问一个超出知识范围的问题,看它是编造还是走拒答/兜底话术。
  • 多轮稳定性 :连续 5 轮后再问第一轮的信息,检查是否遗忘。

如果平台提供对话测试与反馈能力,把每次不满意的回复点踩并补上正确期望,这类反馈数据是后续迭代角色指令和提示词最有价值的输入。

七、别忘了 Token 成本

三个文件会常驻上下文, 每一轮对话都要重复计费 。一份写得臃肿的 AGENTS.md(比如 5000 字)在长会话里会显著放大成本。实操建议:

  • 三份文件合计控制在 1500~2500 字,超出部分拆成按需加载的引用文件。
  • 把” rarely used 的规范”从 AGENTS.md 移到独立文档,需要时再让 Agent 读取。
  • 简单任务用轻量模型、复杂推理任务再切大参数模型,配合 词元所的大模型 API 服务平台 对比不同模型的调用成本与能力档位,避免所有请求都跑在最贵的模型上。

八、常见问题排查

症状 根本原因 处理方式
回应生硬、像模板客服 SOUL.md 缺失或只有形容词 补写具体行为描述与长度约束
总 asking 基础问题 USER.md 未写角色与经验水平 补充角色、技术栈、熟悉/不熟悉清单
不遵守流程、跳步骤 AGENTS.md 步骤不可验证 把步骤改成带命令和产出物的可检查项
越界乱答、编造参数 缺少边界与兜底规则 增加”不确定就说不知道”和兜底话术
配置后反而变差 三份文件指令冲突 显式声明优先级,删掉重复条款
长会话后风格漂移 上下文过长 + 文件臃肿 精简文件,压缩历史,必要时分段加载

一句话总结:部署解决的是”能不能跑”,SOUL / USER / AGENTS 解决的是”跑得像不像你的助手”。先写 AGENTS.md 定流程,再写 SOUL.md 定风格,最后用 USER.md 补背景,然后跑一遍回归用例——这套顺序比一次性写三份完美文件更容易收敛。配置调稳之后,再回到 百度智能云词元所 做一次模型选型与成本复核,让这套精心设计的指令跑在性价比最合适的模型上。

发表评论

活动