从零搞懂：Hermes 如何自动生成 agent.md（保姆级实操教程）

11次阅读

玩 AI Agent 开发的小伙伴，大概率都听过 Hermes Agent——这款主打「轻量化、可自进化、多智能体协作」的框架，彻底降低了自定义 AI 智能体的门槛。

用过 Hermes 的朋友都知道，agent.md 是整个智能体的核心配置文件，直接决定 Agent 的能力边界、工作流程、工具权限和协作规则。很多新手卡在不会手写配置、不懂参数含义，其实 Hermes 自带全自动生成 agent.md 能力，无需手动堆砌代码，几分钟就能生成规范、可直接运行的配置文件。

今天这篇博文，就带大家彻底搞懂：Hermes 生成 agent.md 的底层逻辑、两种实操方式、文件核心结构及避坑技巧，看完人人都能搞定专属 AI 智能体配置。

一、先搞懂：agent.md 到底是什么？

在 Hermes 框架体系中，整套智能体由多份 markdown 配置文件协同驱动，各司其职：

soul.md：负责「身份人设」，定义 Agent 的角色、定位、性格、行为底线，是智能体的“灵魂”
agent.md：负责「工作能力」，是智能体的“工作手册”，核心定义 技能清单、工具权限、执行流程、响应规则、协作逻辑
memory.md / user.md：负责记忆留存、用户偏好记录，支撑 Agent 持续进化

简单来说：soul.md 决定 Agent 是谁，agent.md 决定 Agent 会干什么、怎么干。没有规范的 agent.md，Agent 会出现能力混乱、不会调用工具、执行逻辑错乱、多智能体协作失效等问题。

而 Hermes 最核心的优势之一，就是无需手动编写复杂配置，通过交互式引导，自动生成标准化 agent.md，适配绝大多数场景需求。

二、核心原理：Hermes 自动生成 agent.md 的逻辑

很多人好奇，Hermes 凭什么能自动生成专业的 agent 配置？其底层核心是 Profile 角色映射 + 场景化能力装配 + 标准化模板渲染，全程自动化闭环：

角色初始化：用户创建自定义 Profile（自定义 Agent 角色），确定智能体基础定位（程序员、文案、运维、数据分析等）
能力匹配筛选：Hermes 内置海量场景化能力模板，根据用户选择的角色，自动匹配对应核心技能、必备工具、执行规范
规则自动装配：结合框架通用运行规则、工具调用权限、报错重试机制、输出格式要求，完成配置组装
模板渲染生成：将所有配置信息注入官方标准化模板，自动输出结构完整、语法合规的 agent.md 文件，同时联动生成对应的 soul.md
本地持久化存储：文件自动保存至对应 Agent 目录，框架可实时读取加载，无需额外配置

整个过程零代码、零手写，且生成的配置完全贴合 Hermes 运行规范，不会出现语法报错、适配失效等问题。

三、实操教程：两种方式生成 agent.md（新手首选）

Hermes 提供 交互式自动生成 和 手动辅助生成 两种方式，新手优先选第一种，高效零出错。

方式一：终端交互式一键自动生成（推荐）

这是官方最推荐、使用率最高的方式，全程对话式引导，傻瓜式操作。

1. 前置准备

已完成 Hermes 安装、环境变量配置，终端可正常执行 hermes --version 验证版本。

2. 执行创建命令

打开终端，执行 Profile 创建命令，自定义你的 Agent 名称：

hermes profile create coder

这里的 coder 是自定义智能体名称，可替换为 writer、ops、data 等任意角色名。

3. 跟随引导完成配置

执行命令后，系统会自动弹出交互式引导，按需选择即可：

选择 Agent 核心定位：例如「全栈开发专家」「技术文案撰写师」「运维排查专家」
确认模型配置：默认使用全局主模型，可单独为该 Agent 定制模型
确认能力范围：按需勾选代码编写、bug 修复、文档生成、工具调用等核心能力

4. 自动生成文件

确认所有配置后，Hermes 会自动创建专属文件夹，同步生成 agent.md 和 soul.md 双文件，无需任何手动操作。

生成路径默认位于当前工作目录的子目录中，框架会惰性加载识别，即时生效。

方式二：手动初始化生成（适合定制化场景）

如果需要深度定制 Agent，可先手动创建项目上下文，再触发 agent.md 生成：

在项目根目录创建 .hermes.md 项目上下文文件，定义项目整体场景、需求规范
执行初始化命令，绑定项目场景与 Agent 角色
系统根据项目上下文 + 角色定位，自适应生成定制化 agent.md

该方式适合复杂项目、多智能体协作场景，生成的配置会贴合项目专属规则。

方式三：已有存量项目生成 agent.md（核心刚需）

前面两种方式适用于全新创建 Agent，而绝大多数落地场景是：已有成熟项目代码/业务场景，需要基于现有项目自动适配生成专属 agent.md，避免从零配置、适配错位的问题。Hermes 支持存量项目一键识别、场景适配生成，适配各类旧项目、迭代型项目。

1. 适用场景

已有本地项目代码，需要定制专属执行 Agent（开发、运维、复盘、文档Agent）
项目无 Hermes 配置文件，需要快速接入 Hermes 智能体能力
原有 Agent 配置老旧，需要基于最新项目代码重新生成标准化 agent.md

2. 完整实操步骤

第一步：进入项目根目录

终端 cd 到你的已有项目根目录，确保目录内包含项目核心代码、配置、README 等文件，为框架场景识别提供依据。

第二步：初始化项目全局上下文

执行项目初始化命令，让 Hermes 自动扫描项目结构、业务场景、技术栈、项目规范：

hermes init

执行后框架会自动分析项目类型（前端/后端/数据分析/脚本项目等）、技术栈、核心功能，在根目录生成 .hermes.md 项目全局配置文件，留存项目专属上下文信息。

第三步：基于项目上下文生成 Agent 配置

依托已识别的项目场景，创建对应职能的 Agent，自动适配项目逻辑生成 agent.md：

hermes profile create project-agent

创建过程中，交互式选择的 Agent 能力会自动匹配当前项目场景，例如后端项目自动适配代码调试、接口排查、部署运维能力；文档项目自动适配校对、更新、排版能力。

第四步：重载配置生效

生成完成后，执行重载命令，让 Hermes 加载适配当前项目的 agent.md 配置：

hermes reload

3. 存量项目生成核心优势

零适配成本：无需手动定义项目规则，框架自动扫描项目结构生成适配配置
能力精准匹配：Agent 技能、工具权限完全贴合当前项目，不会出现能力冗余/缺失
支持迭代更新：项目迭代更新后，可重新执行 init + reload，刷新 agent.md 配置

4. 专属注意事项

已有项目无需手动新建文件夹，Hermes 会自动在全局配置目录生成 Agent 文件夹，不污染原有项目结构
若项目有自定义开发规范、业务规则，可提前写入 README 或项目说明文件，框架扫描时会自动纳入 agent.md 执行规则
多模块项目可针对不同模块创建多个专属 Agent，各自生成独立 agent.md，分工处理不同模块任务

四、拆解 agent.md 核心结构（看懂就能自定义修改）

Hermes 自动生成的 agent.md 结构高度标准化，核心分为 5 大模块，看懂后可自由微调优化：

1. 角色能力概述

简要说明当前 Agent 的核心职责、服务场景、核心价值，是框架识别角色定位的基础。

2. 技能清单（核心）

罗列 Agent 所有可执行能力，比如代码开发、文档撰写、日志排查、数据统计等，对应场景化功能。

3. 工具调用权限

定义 Agent 可调用的系统工具、第三方插件、命令行能力，限制越权操作，保障运行安全。

4. 执行流程规范

规定任务处理步骤、思考逻辑、报错重试规则、超时处理机制，保证 Agent 执行稳定可控。

5. 输出约束规则

定义输出格式、内容规范、禁止行为、排版要求，统一 Agent 响应风格。

五、常见避坑指南（新手必看）

很多人生成 agent.md 后 Agent 运行异常，大多是以下问题，提前规避：

禁止缺失 soul.md：agent.md 依赖 soul.md 的身份定位，只生成 agent.md 会导致角色混乱、能力失效，创建时必须双文件配套生成
不盲目手动大改：新手不建议大幅删减自动生成的基础规则，容易破坏执行逻辑，微调技能和输出规则即可
路径不要中文/空格：Agent 文件夹路径避免中文、特殊字符、空格，否则框架无法加载配置文件
多 Agent 独立配置：多个智能体需独立创建 Profile，各自拥有专属 agent.md，不要共用配置文件