1. 资料

官网：Hermes Agent | Nous Research

github：https://github.com/NousResearch/hermes-agent

中文文档：Hermes Agent 文档 | Hermes Agent

2. 代码

# 下载代码（在vscode中）
git clone https://github.com/NousResearch/hermes-agent.git

# 版本查看 hermes --version

Hermes Agent v0.17.0 (2026.6.19) · upstream bb7ff7dc
Project: /data/hermes/hermes-agent
Python: 3.12.13
OpenAI SDK: 2.24.0
Up to date

3. 环境

# 操作系统
Ubuntu 24.04.3 LTS (GNU/Linux 6.8.0-88-generic x86_64)

# 显卡信息
NVIDIA-SMI 580.159.03
Driver Version: 580.159.03
CUDA Version: 13.0
NVIDIA A100-SXM4-80GB * 8

# 开发环境
vscode
conda、python=3.12
nvm=0.39.7、node=v22.23.0(hermes要求最低20.19+ or 22.12+)
mysql=8.0
docker=29.1.3, build 29.1.3-0ubuntu3~24.04.2
vllm=0.20.2

# coding辅助模型
Deepseek Pro

# 本地测试模型（没有的就用在线API，在这里网上说minmax2.7和hermes更适配，原因是M2.7 被称为 MiniMax 首个“深度参与自我迭代的模型”。这意味着，M2.7 不仅能执行任务，还能自主构建复杂的 Agent Harness 并优化自身。这正是 Hermes 的核心特性——学习闭环所需的底层能力。因为项目的实际要求，我用的还是Qwen系列）
Qwen3.5-397B-A17B-GPTQ-Int4

# 推理开启日志方便查看完整提示词
CUDA_VISIBLE_DEVICES=4,5,6,7 VLLM_LOGGING_LEVEL=DEBUG vllm serve "/data/models/Qwen3.5-397B-A17B-GPTQ-Int4"   --port 9001   --tensor-parallel-size 4   --enable-auto-tool-choice   --reasoning-parser qwen3   --tool-call-parser qwen3_coder   --speculative-config {"method":"qwen3_next_mtp","num_speculative_tokens":2}'   --served-model-name q397   --language-model-only   --enable-log-requests

4. 目录结构(AI整理)

hermes-agent/
├── 📄 根目录文件
│   ├── 🐍 Python 脚本
│   │   ├── cli.py                  # CLI/TUI 主入口
│   │   ├── run_agent.py            # 核心代理类 AIAgent
│   │   ├── hermes_bootstrap.py     # Windows UTF-8 引导
│   │   ├── hermes_constants.py     # 全局常量
│   │   ├── hermes_logging.py       # 日志系统
│   │   ├── hermes_state.py         # 状态管理
│   │   ├── hermes_time.py          # 时间工具
│   │   ├── model_tools.py          # 工具注册系统
│   │   ├── toolsets.py             # 工具集管理
│   │   ├── toolset_distributions.py # 工具集分发配置
│   │   ├── mcp_serve.py            # MCP 服务器
│   │   ├── trajectory_compressor.py # 轨迹压缩
│   │   ├── utils.py                # 通用工具函数
│   │   ├── batch_runner.py         # 批量运行器
│   │   ├── mini_swe_runner.py      # SWE-bench 测试运行器
│   │   ├── test.py                 # 测试脚本
│   │   ├── setup.py                # 传统打包配置
│   │   └── hermes_init.py          # 个人初始化模块
│   ├── 🖥️ Shell 脚本
│   │   ├── hermes                  # Shell 入口脚本（无扩展名）
│   │   └── setup-hermes.sh         # 安装脚本
│   ├── ⚙️ 配置文件
│   │   ├── pyproject.toml          # Python 项目配置
│   │   ├── .env.example            # 环境变量模板
│   │   ├── .envrc                  # direnv 配置
│   │   ├── cli-config.yaml.example # CLI 配置示例
│   │   ├── constraints-termux.txt  # Termux 约束列表
│   │   ├── MANIFEST.in             # Python 包清单
│   │   ├── .hadolint.yaml          # Hadolint 配置
│   │   ├── .gitignore              # Git 忽略规则
│   │   └── .gitattributes          # Git 属性配置
│   ├── 🐳 Docker 配置
│   │   ├── Dockerfile              # Docker 镜像构建
│   │   ├── docker-compose.yml      # Docker Compose 配置
│   │   └── docker-compose.windows.yml # Windows Docker 配置
│   ├── 📦 Nix 配置
│   │   ├── flake.nix               # Nix Flake 定义
│   │   └── flake.lock              # Nix 依赖锁定
│   ├── 📦 Node.js 配置
│   │   ├── package.json            # Node.js 项目配置
│   │   └── package-lock.json       # npm 依赖锁定
│   ├── 🔒 锁定文件
│   │   └── uv.lock                 # uv 依赖锁定
│   ├── 📄 文档文件
│   │   ├── README.md               # 项目主文档
│   │   ├── README.es.md            # 西班牙语 README
│   │   ├── README.ur-pk.md         # 乌尔都语 README
│   │   ├── README.zh-CN.md         # 中文 README
│   │   ├── CONTRIBUTING.md         # 贡献指南
│   │   ├── CONTRIBUTING.es.md      # 西班牙语贡献指南
│   │   ├── SECURITY.md            # 安全策略
│   │   ├── SECURITY.es.md          # 西班牙语安全策略
│   │   ├── LICENSE                 # Apache 2.0 许可证
│   │   ├── AGENTS.md               # Agent 配置
│   │   └── hermes-already-has-routines.md # 已知问题说明
│   ├── 📋 其他文件
│   │   ├── .mailmap                # Git 邮件映射
│   │   └── 文档.md                 # 本文档
│
├── 📁 .github/                      # GitHub 配置
│   └── workflows/                   # CI/CD 工作流
│
├── 📁 .plans/                      # 开发计划文档
│
├── 📁 acp_adapter/                 # ACP 协议适配器
│
├── 📁 acp_registry/                # ACP 代理注册
│
├── 📁 agent/                       # 核心代理模块 ⭐
│   ├── lsp/                        # 语言服务器协议
│   └── transports/                 # 模型传输层
│
├── 📁 apps/                        # 桌面应用
│   ├── desktop/                    # Electron 桌面端
│   └── shared/                    # 共享代码
│
├── 📁 assets/                      # 静态资源
│
├── 📁 cron/                        # 定时任务调度
│   └── scripts/                    # 定时任务脚本
│
├── 📁 docker/                       # Docker 部署
│   └── s6-rc.d/                    # s6 进程管理
│
├── 📁 docs/                        # 项目文档
│   ├── middleware/                 # 中间件文档
│   └── observability/              # 可观测性文档
│
├── 📁 gateway/                     # 消息网关 ⭐
│   ├── platforms/                   # 平台适配器
│   └── relay/                      # 中继服务
│
├── 📁 hermes_cli/                  # CLI 命令行 ⭐
│   └── proxy/                      # 代理服务器
│
├── 📁 locales/                     # 国际化语言包
│
├── 📁 nix/                         # Nix 配置
│
├── 📁 packaging/                   # 打包配置
│   └── homebrew/                   # Homebrew 安装包
│
├── 📁 plugins/                     # 插件系统 ⭐
│   ├── memory/                     # 记忆插件
│   └── web/                        # 搜索插件
│
├── 📁 providers/                   # 模型提供者抽象
│
├── 📁 scripts/                     # 辅助脚本
│
├── 📁 skills/                      # 技能系统 ⭐
│
├── 📁 tests/                       # 测试代码
│
├── 📁 tools/                       # 工具集 ⭐
│   ├── computer_use/               # 计算机使用工具
│   └── environments/               # 环境后端
│
├── 📁 tui_gateway/                 # TUI 网关
│
├── 📁 ui-tui/                      # 终端 UI
│
├── 📁 web/                         # Web 界面
│
└── 📁 website/                     # 项目官网

5. 基础效果验证

5.1 终端

# 目的：保证基础环境、模型、代码可用

# 安装代码、进入到项目根目录（在conda环境中）
pip install -e ".[all,dev]"

# 测试、出现cli界面成功
hermes

# tui 安装、进入hermes-agent/web下
npm install && npm run build

# 测试，我是在远程服务器上，代码模型本地安全访问，所以用以下命令启动。出现HERMES_DASHBOARD_READY port=9119 Hermes Web UI → http://0.0.0.0:9119 就成功

hermes dashboard --host 0.0.0.0 --insecure 

# 配置自定义模型
hermes model

5.2 vscode运行

# 找到对应的hermes_cli文件夹下的main.py运行和终端效果一样

# 这里可以替换一下/命令改为中文，看着方便点，替换hermes_cli文件夹下的commands.py就可以。资料已经上传改一下名字替换

至此所有基础工作完成

6. 核心模块

6.1 AIAgent

# 测试AIAgent运行,通过改脚本查看核心运行流程
# 两种方式都可以,chat就是对run_conversation再一次封装,核心都是run_conversation
# test_stream.py

from run_agent import AIAgent

def print_stream(text: str):
    """流式回调函数，逐字打印"""
    print(text, end="", flush=True)

agent = AIAgent(
    model="q397",
    base_url="http://localhost:9001/v1",
    quiet_mode=True
)


def test1():
    # 传入 stream_callback 启用流式
    result = agent.run_conversation(
        user_message="你好",
        stream_callback=print_stream
    )

    # 最后换行
    print("\n")
    print(f"最终回复: {result['final_response']}")

def test2():
    response = agent.chat(
        "你好，你是？",
        stream_callback=print_stream
    )
    print("\n")
test2()

效果（我已经改了SOUL.md文件中的内容，同时修改了一些英文输出改中文），接下来就可以打断点进行跟踪了，我整理了一份流程：

6.1.1 DEBUG流程

6.1.1.1 执行顺序

6.1.1.2 完整流程

6.1.1.3 详细流程

6.1.1.4 工具流程

6.1.1.5 VLLM输出

6.1.1.6 总结

conversation_loop.py核心就一个方法run_conversation（4000行）

如果之前写过function call实现的话，这里理解起来就会容易一点，原理一样的

我要做二次开发，就可以从这里入手先优化一分部代码，我是TO-B的内网，不涉及那么多的模型。像以下的逻辑就可以优化一部分

    1. .hermes.md / HERMES.md 

    2. AGENTS.md / agents.md

    3. CLAUDE.md / claude.md 

    4. .cursorrules / .cursor/rules/*.mdc  

我最主要的还是使用run_conversation和gateway这部分，至于TUI暂时可以当做后台的一个入口，逐步替换或者融合到自己的项目中

可以仔细阅读一下AGENTS.md这个文件，我把他也翻译了一下

6.1.2 记忆机制

Hermes 的记忆系统分为两层架构

层级 类型 存储位置 说明
内置记忆 文件型记忆 $HERMES_HOME/memories/ 目录 始终可用，基于 MEMORY.md 和 USER.md 文件
外部记忆提供者 插件化后端 取决于插件（Honcho、Hindsight、Mem0 等） 通过配置启用，最多同时启用一个外部提供者

6.1.2.1 代码清单

1. 核心管理器

文件 作用
memory_manager.py 记忆管理器，协调所有记忆提供者（内置+外部）
memory_provider.py 记忆提供者抽象基类，定义插件接口

2. 内置记忆实现

文件 作用
memory_tool.py 内置记忆工具，实现 MemoryStore 类，基于 MEMORY.md/USER.md

3. 插件加载

文件 作用
plugins/memory/__init__.py 外部记忆插件发现和加载器

4. 集成点

文件 作用
agent_init.py Agent 初始化时创建记忆系统
system_prompt.py 将记忆注入系统提示词
turn_context.py 回合开始前的记忆预取
turn_finalizer.py 回合结束后的记忆同步

5.核心方法

方法 调用时机
system_prompt_block() 系统提示词构建时
prefetch(query, session_id) 每轮之前，召回相关上下文（同步，应快速）
queue_prefetch(query, session_id) 每轮之后，后台为下一轮预取
sync_turn(user, asst, session_id, messages) 每轮之后，持久化完成的回合（后台异步）
handle_tool_call(tool_name, args, **kwargs) 处理模型的工具调用
shutdown() 关闭时清理
6.1.2.2 内部记忆

** 注意内部记忆是全局共享的

以下情况会主动存储记忆，你也可以主动要求他记录：

1. 用户表达偏好时 — 比如"我喜欢简洁的回答"、"用中文回复我"    
2. 用户纠正我时 — 比如"不是这样，应该是..."    
3. 发现稳定的环境事实 — 比如项目结构、工具使用习惯      
4. 学到对以后有用的信息 — 比如工作方式、常用流程   

# 触发条件，默认10轮对话才会触发
memory:
  # Agent 的个人笔记：环境事实、项目规范、学到的经验
  memory_enabled: true
  
  # 用户画像：偏好、沟通风格、期望
  user_profile_enabled: true
  
  # 字符数限制（~2.75 字符 ≈ 1 个 Token，与模型无关）
  memory_char_limit: 2200   # ~800 个 Token
  user_char_limit: 1375     # ~500 个 Token

  # 周期性记忆提示：每隔 N 轮用户消息提醒 Agent 考虑保存记忆。
  # 设为 0 则禁用。仅在记忆功能启用时生效。
  nudge_interval: 10        # 每 10 轮用户消息提醒一次（0 = 禁用）

  # 记忆刷新：在上下文即将丢失前（/compression, /new, /reset, exit），
  # 给 Agent 一轮机会保存记忆。设为 0 则禁用。
  # 对于退出/reset，只有会话至少达到这个用户消息轮数才会触发。
  flush_min_turns: 6        # 触发刷新所需的最小用户消息轮数（0 = 禁用）

# 触发的提示词在background_review.py:34-43
_MEMORY_REVIEW_PROMPT = (
    "回顾上面的对话，考虑是否适合保存到记忆中。\n\n"
    "重点关注：\n"
    "1. 用户是否透露了关于自己的信息——他们的身份、愿望、偏好，"
    "或值得记住的个人细节？\n"
    "2. 用户是否表达了对你的行为期望、他们的工作风格，"
    "或希望你的操作方式？\n\n"
    "如果有值得注意的内容，使用 memory 工具保存下来。"
    "如果没有值得保存的内容，只需说'Nothing to save.'并停止。"
)

总结一下
对于我的实际项目来说，这里需要改造一下，根据不同用户设置不同的MEM和USER，这样更符合业务需求，USER是一个，MEM有个全局的分类目录，下边按照类型进行存储。做一个查找逻辑

你也可以使用hermes的profile进行操作，对应页面的多Agent配置

6.1.2.2 外部记忆

7. 提示词

项目中的内置提示词，方便修改

7.1 系统核心提示词（Agent 身份 + 工具引导）

变量名 文件位置 作用
DEFAULT_AGENT_IDENTITY agent/prompt_builder.py:123-131 Agent 默认身份设定（"你是 Hermes Agent..."），没有 SOUL.md 时用这个
HERMES_AGENT_HELP_GUIDANCE agent/prompt_builder.py:133-142 告诉模型遇到 Hermes 自身问题时去查官方文档
MEMORY_GUIDANCE agent/prompt_builder.py:144-165 记忆工具使用指导——存什么、不存什么、怎么写
SESSION_SEARCH_GUIDANCE agent/prompt_builder.py:167-171 会话搜索使用指导——用户提到过去对话时先搜再问
SKILLS_GUIDANCE agent/prompt_builder.py:173-180 技能使用指导——做完复杂任务后存技能，发现过时就更新
KANBAN_GUIDANCE agent/prompt_builder.py:182-220+ Kanban 任务执行协议——看板任务的生命周期规范

构建入口：

7.2 后台自我审查提示词

变量名 文件位置 作用
_MEMORY_REVIEW_PROMPT agent/background_review.py:34-43 记忆审查提示词——判断对话中有没有值得保存的用户偏好/信息
_SKILL_REVIEW_PROMPT agent/background_review.py:45-148 技能审查提示词——判断对话中有没有值得保存的工作流/技巧
_COMBINED_REVIEW_PROMPT agent/background_review.py:150-... 合并审查提示词——同时做记忆和技能审查

触发时机：每 N 个回合（默认 10 轮）后，后台 fork 一个 agent 用这些提示词自我审查。

7.3 上下文压缩（摘要）提示词

变量/函数 文件位置 作用
_summarizer_preamble agent/context_compressor.py:1423-1435 摘要器前置说明——告诉模型这是生成上下文检查点，不是回答问题
_temporal_anchoring_rule agent/context_compressor.py:1443-1453 时间锚定规则——把已完成的动作改成过去时态，避免重复执行
_generate_summary() agent/context_compressor.py:1376-1562 动态构建完整摘要提示词，包含多个结构化 section

作用：对话上下文超长时，用辅助模型把中间轮次压缩成摘要，省 token。

7.4 标题生成提示词

变量名 文件位置 作用
_TITLE_PROMPT agent/title_generator.py:22-... 根据第一轮对话生成会话标题的提示词

7.5 策展人（Curator）审查提示词

变量名 文件位置 作用
CURATOR_REVIEW_PROMPT agent/curator.py:365-... 技能策展人审查提示词——自动整理、合并、删除过时的技能

7.6 Kanban 看板相关提示词

变量名 文件位置 作用
_SYSTEM_PROMPT (profile_describer) hermes_cli/profile_describer.py:47-... 看板 profile 描述生成器
_SYSTEM_PROMPT (kanban_specify) hermes_cli/kanban_specify.py:53-... 看板任务细化——把模糊需求拆成具体任务规范
_SYSTEM_PROMPT (kanban_decompose) hermes_cli/kanban_decompose.py:52-... 看板任务分解——把大任务拆成子任务

7.7 目标判断提示词

变量名 文件位置 作用
JUDGE_SYSTEM_PROMPT hermes_cli/goals.py:95-... 目标完成度评审——判断一个目标是否达成

7.8 Cron 分类提示词

变量名 文件位置 作用
_CLASSIFY_INSTRUCTIONS cron/scripts/classify_items.py:82-90 主动推送紧急度分类——给待办条目打 0-10 分的紧急度

7.9 多智能体聚合提示词

变量名 文件位置 作用
AGGREGATOR_SYSTEM_PROMPT tools/mixture_of_agents_tool.py:83-... MoA 聚合器——把多个模型的回答综合成一个高质量回答

7.10 图像生成相关提示词

变量名 文件位置 作用
UPSCALER_DEFAULT_PROMPT tools/image_generation_tool.py:440 图像放大的默认正向提示词
UPSCALER_NEGATIVE_PROMPT tools/image_generation_tool.py:441 图像放大的默认负向提示词
_CODEX_INSTRUCTIONS plugins/image_gen/openai-codex/init.py:78-... Codex 图像生成的指令

7.11 飞书评论相关指令

变量名 文件位置 作用
_COMMON_INSTRUCTIONS plugins/platforms/feishu/feishu_comment.py:868-... 飞书评论机器人的通用指令

7.12 贴纸视觉提示词

变量名 文件位置 作用
STICKER_VISION_PROMPT gateway/sticker_cache.py:23-... 用视觉模型识别贴纸/表情包的提示词

7.13 技能指令标记（不是完整提示词，是标记片段）

变量名 文件位置 作用
_SINGLE_SKILL_INSTRUCTION agent/skill_commands.py:49-52 单技能调用的指令标记头
_BUNDLE_USER_INSTRUCTION agent/skill_commands.py:54 技能包中用户指令的分隔标记

8.SKILLS(技能)

技能部分主要把规范说一下，同步有个示例
官方地址：skills官方标准

顶层配置
配置项 类型 必需 说明
name string ✅ 是 Skill 的唯一标识符，用于在系统中引用、加载和调用该 Skill。建议使用小写字母和连字符（如 coal-sales-attribution）
description string ✅ 是 Skill 的简短描述，会显示在 Skill 搜索和列表结果中，帮助用户理解该 Skill 的用途
version string ❌ 否 语义化版本号（如 1.0.0），用于管理 Skill 的更新和兼容性
author string ❌ 否 Skill 作者或维护者名称，便于其他人联系或溯源
license string ❌ 否 开源许可证类型（如 MIT、Apache-2.0），明确使用和分发权限
platforms array ❌ 否 限制 Skill 运行的操作系统平台。可选值：macos、linux、windows。省略则默认在所有平台加载。设置后在不兼容平台上自动隐藏

metadata.hermes 配置项

配置项 类型 必需 说明
tags array ❌ 否 标签列表，用于 Skill 的分类和搜索。用户可通过标签快速找到相关 Skill
related_skills array ❌ 否 关联的其他 Skill 名称列表，提示 Agent 或用户存在可配合使用的 Skill，促进 Skill 协作
requires_toolsets array ❌ 否 声明 Skill 依赖的 toolset。当列出的任意 toolset 未激活时，Skill 被隐藏。用于确保在满足依赖时 Skill 才出现
requires_tools array ❌ 否 声明 Skill 依赖的特定 tool。当列出的任意 tool 不可用时，Skill 被隐藏。比 requires_toolsets 粒度更细
fallback_for_toolsets array ❌ 否 当列出的 toolset 已可用时，隐藏该 Skill。用于创建替代方案 Skill，作为主要能力的后备（如免费搜索 Skill 作为付费搜索 tool 的替代）
fallback_for_tools array ❌ 否 当列出的 tool 已可用时，隐藏该 Skill。与 fallback_for_toolsets 类似，但针对单个工具
config array ❌ 否 声明 Skill 需要的非密钥配置项，存储在 config.yaml 的 skills.config 命名空间下。用于路径、偏好设置等非敏感配置

metadata.hermes.config[]配置项

config.key string ✅ 是 配置项的点路径（如 coal.db.host），用于在 config.yaml 中定位和存储该配置
config.description string ✅ 是 说明该配置项的作用，帮助用户理解配置项的含义
config.default string ❌ 否 用户未配置时的默认值
config.prompt string ❌ 否 hermes config migrate 时向用户显示的提示文本；若未设置则回退到 description

顶层required_environment_variables 配置项

配置项 类型 必需 说明
required_environment_variables array ❌ 否 声明 Skill 需要的环境变量，用于存储密钥和敏感信息（如 API key、密码），存储在 ~/.hermes/.env，不向模型暴露
required_environment_variables[].name string ✅ 是 环境变量名称
required_environment_variables[].prompt string ❌ 否 提示用户输入时的文本
required_environment_variables[].help string ❌ 否 获取该值的帮助文本或 URL
required_environment_variables[].required_for string ❌ 否 描述哪个功能需要此变量

配置项分类汇总

类别 相关字段 核心作用
标识与发现 name, description, tags 唯一标识 Skill，支持搜索和分类
版本与归属 version, author, license 版本控制和作者归属
平台限制 platforms 限制运行的操作系统环境
依赖控制 requires_toolsets, requires_tools 正向条件：仅在依赖 tool/toolset 可用时显示 Skill
替代控制 fallback_for_toolsets, fallback_for_tools 反向条件：当主要 tool/toolset 可用时隐藏该 Skill（作为后备方案）
非密钥配置 config 存储路径、偏好等非敏感配置（存于 config.yaml）
密钥/敏感信息 required_environment_variables 存储 API key、密码等敏感信息（存于 .env，不暴露给模型）

# python
Logo
加入AMD AI开发者计划！

免费领 150 小时云算力，进群参与显卡、AI PC 幸运抽奖

更多推荐

cover

WSL2 GPU 直连与 vLLM 大模型推理

avatar AMD开发者中国社区

DCU使用技术报告_中篇_gfx936_DCU_Qwen3.5-27B_Triton-ROCm_Attention与GEMV深度优化实战

系列文章中篇。上篇解决了环境、基线和 Profile 的可信度问题；这一篇进入算子层，记录专用 Prefill Attention、Q10/Q20 Query 复用、Gate/Up Triton GEMV，以及一批看起来合理但最终没有采用的实验。

avatar AMD开发者中国社区
cover

nano-vllm环境安装

avatar AMD开发者中国社区