企业官网建设流程全解析

1. 为什么我要认真聊聊 Hermes Agent 这个智能体框架

第一次看到 Hermes Agent 这个词，是在一个做企业自动化的朋友群里。当时有人甩了个链接，说“又一个开源智能体框架，SKILL.md 那套玩法挺有意思”。我点进去扫了一眼，没太当回事——那阵子智能体框架满天飞，Dify、Coze、LangChain、AutoGen，每个都说自己是下一代。但后来连续有三四个做不同方向的朋友都在提 Hermes，有做销售智能体的，有搞工业设备巡检的，还有在麒麟 V10 上折腾局域网部署的，我才意识到这东西可能真有点不一样。

Hermes Agent 本质上是一个开源的自主 AI 智能体框架，核心思路是用 SKILL.md 这种声明式文件来定义智能体的能力边界和行为逻辑。你可以把它理解成一个“智能体的操作系统”——底层对接大模型，中间层做任务编排和工具调用，上层用 SKILL.md 来描述“这个智能体该干什么、能调什么工具、按什么流程走”。它解决的核心问题是：让智能体开发从“写一堆胶水代码”变成“写清楚你要什么”。

这篇文章适合谁看？如果你是刚接触智能体开发的新手，想搞清楚 Hermes Agent 到底是什么、跟 Dify/Coze 有什么区别，这篇能帮你建立完整的认知框架。如果你已经在用 LangChain 或者 harness 架构做智能体开发，想看看 Hermes 的 SKILL.md 机制能不能简化你的工作流，这篇也能给你一些实操层面的参考。我尽量不堆术语，用实际场景和踩过的坑来讲。

2. Hermes Agent 到底是什么：核心概念拆解

2.1 从“智能体”这个词说起

“智能体”这个词这两年快被用烂了。打开任何一个技术社区，满屏都是“AI 智能体”“多智能体协同”“智能体编排平台”。但剥开这些包装，智能体的本质其实就三件事：感知环境、做出决策、执行动作。传统程序是你写死 if-else，智能体是你给它一个目标，它自己决定怎么一步步达成。

Hermes Agent 在这个基础上加了一个关键约束：用 SKILL.md 来定义能力。这跟 LangChain 那种用代码链式调用工具的方式完全不同。LangChain 是你写 Python 代码，把 LLM、工具、记忆模块串起来；Hermes 是你写一个 Markdown 文件，描述这个智能体有哪些技能、每个技能的输入输出是什么、什么条件下触发。框架负责把 Markdown 解析成可执行的工作流。

这个设计选择背后的逻辑很清晰：降低智能体开发的门槛，同时提高可维护性。代码写的智能体，改一个逻辑要动代码、跑测试、重新部署；SKILL.md 写的智能体，改一个技能描述就像改文档一样，非技术人员也能参与。

2.2 SKILL.md 机制到底怎么工作

SKILL.md 是 Hermes Agent 的核心创新点。一个典型的 SKILL.md 文件大概长这样：

# Skill: 客户询价处理 ## 描述 当客户发送询价信息时，自动提取产品型号、数量、交期要求，并生成报价单草稿。 ## 触发条件 - 消息中包含“询价”“报价”“价格”等关键词 - 消息来自已识别的客户联系人 ## 输入 - 客户消息文本 - 产品目录（从知识库检索） ## 执行步骤 1. 提取产品型号和数量 2. 查询产品目录获取单价和库存 3. 计算总价和交期 4. 生成报价单草稿并发送给销售确认 ## 输出 - 报价单草稿（Markdown 格式） - 确认请求发送给销售

框架解析这个文件后，会自动生成对应的工具调用链、提示词模板和状态机。你不需要写一行 Python 代码，就能让智能体具备处理询价的能力。当然，实际生产环境里还需要配置模型接入、知识库连接、权限控制这些，但核心逻辑确实是用 Markdown 表达的。

我实测下来的感受是：简单场景确实快，复杂场景需要配合自定义工具。比如你要调一个内部的 ERP 接口，还是得写个 Python 函数注册成工具，然后在 SKILL.md 里引用。但至少业务逻辑和代码逻辑分离了，改业务流程不用动代码。

2.3 Hermes 跟 Dify、Coze、LangChain 的本质区别

很多人问这个问题，我直接用一个表格说清楚：

Hermes 的定位很明确：给需要自托管、需要多智能体协同、又不想写太多代码的团队用的。Dify 和 Coze 更适合快速搭个 Demo 或者轻量应用，但一旦流程复杂起来，可视化编排就会变得非常臃肿。LangChain 灵活但学习曲线陡，而且版本迭代快，维护成本高。

Hermes 的 SKILL.md 机制在“灵活”和“易用”之间找了个平衡点。你可以用 Markdown 描述 80% 的常规逻辑，剩下 20% 的特殊需求用自定义工具补上。

3. 核心架构与运行原理：拆开看里面有什么

3.1 整体架构分层

Hermes Agent 的架构可以分成四层，我从下往上说：

模型接入层负责对接各种大模型。官方支持 OpenAI 兼容接口，所以 DeepSeek、通义千问、本地部署的模型都能接。这一层做的是请求封装、流式输出、Token 计数这些脏活累活。

核心引擎层是框架的心脏。它负责解析 SKILL.md、管理智能体状态、调度工具调用、处理多智能体之间的消息传递。这一层用 Python 写的，核心模块包括 SkillParser、AgentRuntime、ToolRegistry、MessageBus。

工具与插件层提供内置工具和自定义工具注册机制。内置的有 HTTP 请求、文件读写、知识库检索、代码执行等。自定义工具通过装饰器注册，框架会自动生成工具描述供模型调用。

交互层包括 WebUI、API 接口和 CLI。WebUI 是基于 Gradio 或者类似框架做的，可以对话、查看执行日志、管理 SKILL.md 文件。API 接口方便集成到现有系统。

3.2 一个请求的完整生命周期

我拿一个实际例子来串一遍。假设你在 WebUI 里输入“帮我查一下上个月华东区的销售数据，生成一个趋势图”。

第一步，意图识别与技能匹配。核心引擎收到消息后，先调用模型做意图分类，判断这属于“数据查询+可视化”类任务。然后扫描已加载的 SKILL.md 文件，找到匹配的技能定义。

第二步，任务规划。根据 SKILL.md 里定义的执行步骤，引擎生成一个任务计划：先调数据库查询工具，再调数据处理工具，最后调图表生成工具。如果步骤之间有依赖，引擎会构建 DAG（有向无环图）来确定执行顺序。

第三步，工具调用与状态更新。引擎按计划依次调用工具。每次调用前，会把当前上下文和工具描述发给模型，让模型生成具体的调用参数。调用结果写回智能体状态，供后续步骤使用。

第四步，结果汇总与输出。所有步骤完成后，引擎把最终结果格式化，通过 WebUI 返回给用户。同时把整个执行链路写入日志，方便排查问题。

这个过程里，SKILL.md 的作用是约束模型的自由发挥空间。没有 SKILL.md 的时候，模型可能自己编一个查询语句，或者跳过某个必要步骤。有了 SKILL.md，模型只能在定义的步骤和工具范围内做选择，可靠性大幅提升。

3.3 多智能体协同是怎么实现的

Hermes 的多智能体不是简单的“多个 Bot 各干各的”，而是有明确的协同机制。每个智能体有自己的 SKILL.md 定义，有自己的工具集和知识库。智能体之间通过 MessageBus 通信，可以互相发消息、请求协助、传递中间结果。

举个例子：一个销售智能体收到客户询价，它发现自己没有库存查询权限，就发消息给库存智能体请求协助。库存智能体查询后把结果返回，销售智能体继续生成报价单。整个过程对用户透明，用户只看到最终报价。

这种设计的好处是权限隔离和职责分离。销售智能体不需要知道库存系统的细节，库存智能体也不需要理解销售话术。每个智能体只关注自己的 SKILL.md 定义，降低了复杂度和出错概率。

配置多智能体的时候，需要在主配置文件里声明各个智能体的角色、通信权限和路由规则。我踩过的坑是：路由规则没配好，消息会在两个智能体之间来回弹。后来加了最大跳转次数限制才解决。

4. 从零开始：Hermes Agent 安装与基础配置

4.1 环境准备与依赖检查

Hermes Agent 对运行环境的要求不算高，但有几个硬性依赖必须满足。我用的是 Ubuntu 22.04，Python 3.10+，Docker 24.0+。如果你在麒麟 V10 上部署，Python 版本可能需要手动升级到 3.10，系统自带的 3.7 跑不起来。

先检查基础环境：

python3 --version docker --version docker-compose --version git --version

如果 Docker 拉镜像慢，可以配置国内加速源。编辑/etc/docker/daemon.json：

{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://dockerproxy.com" ] }

然后重启 Docker 服务。这一步在局域网部署场景下特别重要，不然拉镜像能等到天荒地老。

4.2 三种安装方式对比与选择

Hermes Agent 提供三种安装方式，我分别试过，说下各自的适用场景：

方式一：pip 直接安装。适合快速体验，一条命令搞定：

pip install hermes-agent hermes init hermes start

但这种方式依赖系统 Python 环境，容易跟其他项目冲突。而且默认只装核心依赖，一些可选工具（比如浏览器自动化）需要额外装。

方式二：Docker 单容器部署。适合测试和小规模使用：

docker run -d \ --name hermes-agent \ -p 8080:8080 \ -v ./data:/app/data \ -v ./skills:/app/skills \ hermesagent/hermes:latest

数据目录和技能目录挂载出来，方便备份和修改。但单容器模式下，如果智能体需要调外部服务（比如数据库），网络配置会比较麻烦。

方式三：Docker Compose 多容器部署。这是生产环境推荐的方式，也是热词里提到的“3 个容器和 5 条命令”方案。典型配置包括 agent 容器、web 容器、数据库容器：

version: '3.8' services: hermes-agent: image: hermesagent/hermes:latest volumes: - ./skills:/app/skills - ./data:/app/data environment: - MODEL_API_KEY=${MODEL_API_KEY} - MODEL_BASE_URL=${MODEL_BASE_URL} depends_on: - postgres hermes-web: image: hermesagent/hermes-web:latest ports: - "8080:8080" environment: - AGENT_API_URL=http://hermes-agent:8080 depends_on: - hermes-agent postgres: image: postgres:15 environment: - POSTGRES_DB=hermes - POSTGRES_USER=hermes - POSTGRES_PASSWORD=${DB_PASSWORD} volumes: - ./pgdata:/var/lib/postgresql/data

启动命令就五条：

cp .env.example .env vim .env # 填入模型 API Key 和数据库密码 docker-compose pull docker-compose up -d docker-compose logs -f

我实测下来，多容器方案在局域网环境里最稳。Web 容器和 Agent 容器分开，升级的时候可以单独重启，不影响正在执行的任务。

4.3 模型接入配置的坑

Hermes 支持 OpenAI 兼容接口，所以配置模型的时候，关键是base_url和api_key两个参数。如果你用 DeepSeek，配置大概是：

model: provider: openai base_url: https://api.deepseek.com/v1 api_key: sk-xxxxxxxx model_name: deepseek-chat max_tokens: 4096 temperature: 0.3

这里有个坑：temperature 不要设太高。智能体场景下，模型需要稳定地按 SKILL.md 定义的步骤执行，temperature 超过 0.5 就容易“自由发挥”，跳过步骤或者编造工具调用。我一般设 0.1 到 0.3 之间。

另一个坑是max_tokens 要留足。SKILL.md 解析后的提示词可能很长，加上工具描述和上下文，很容易超过 4096。如果模型返回被截断，智能体会执行到一半卡住。建议至少设 8192，如果模型支持的话。

5. SKILL.md 编写实战：从简单到复杂

5.1 第一个 SKILL.md：天气查询智能体

别一上来就搞复杂的，先用一个最简单的例子跑通流程。创建一个skills/weather/SKILL.md：

# Skill: 天气查询 ## 描述 查询指定城市的当前天气和未来三天预报。 ## 触发条件 - 用户消息中包含“天气”“气温”“下雨”等关键词 - 消息中能提取到城市名称 ## 输入 - 城市名称（字符串） - 查询类型（当前天气/预报） ## 执行步骤 1. 从用户消息中提取城市名称 2. 调用 weather_api 工具获取天气数据 3. 格式化输出结果 ## 工具依赖 - weather_api: 天气查询接口 ## 输出格式 - 当前天气：温度、湿度、风力、天气状况 - 预报：未来三天每天的最高温、最低温、天气状况

然后在tools/目录下注册weather_api工具：

from hermes import tool @tool(name="weather_api", description="查询城市天气") def weather_api(city: str, query_type: str = "current"): # 实际调用天气 API import requests resp = requests.get(f"https://api.weather.com/v1/{city}") return resp.json()

重启 Agent 后，在 WebUI 里输入“北京今天天气怎么样”，就能看到智能体自动提取城市、调用工具、格式化输出。这个流程跑通，你就理解了 Hermes 的基本工作方式。

5.2 进阶：带条件分支和循环的技能

实际业务里，很少有线性执行到底的场景。更多是“如果库存不足就通知采购，如果库存充足就生成发货单”这种分支逻辑。SKILL.md 支持用自然语言描述条件分支：

## 执行步骤 1. 查询产品库存 2. 如果库存 >= 订单数量： - 生成发货单 - 通知物流部门 3. 如果库存 < 订单数量： - 计算缺口数量 - 生成采购申请 - 通知采购部门 4. 无论哪种情况，都发送确认邮件给客户

框架解析这种描述时，会生成对应的条件节点。但这里有个经验：条件判断尽量用明确的数值比较，不要用模糊描述。比如“库存充足”这种说法，模型可能理解成“大于 0”也可能理解成“大于安全库存”。写成“库存 >= 订单数量”就明确多了。

循环逻辑也是类似。比如“对每个未处理的订单，执行以下步骤”，框架会生成循环节点。但要注意设置最大循环次数，防止死循环。我一般会在 SKILL.md 里加一句“最多处理 100 条记录”。

5.3 多智能体协同的 SKILL.md 设计

多智能体场景下，每个智能体的 SKILL.md 需要额外声明协作接口。比如销售智能体：

# Skill: 销售询价处理 ## 协作接口 - 可请求：inventory_agent（库存查询） - 可请求：pricing_agent（价格计算） - 可被请求：order_agent（订单状态查询） ## 执行步骤 1. 提取客户询价信息 2. 请求 inventory_agent 查询库存 3. 请求 pricing_agent 计算价格 4. 生成报价单 5. 如果客户确认，请求 order_agent 创建订单

这里的关键是明确声明谁能请求谁。不声明的话，框架默认不允许跨智能体调用。我见过有人没配协作接口，结果销售智能体一直报“无权限调用库存工具”，排查了半天才发现是 SKILL.md 里没写。

6. 常见问题与排查技巧实录

6.1 安装部署类问题

问题一：pip 安装后 hermes 命令找不到。这通常是 PATH 没配好。pip install默认把可执行文件放在~/.local/bin，但这个目录可能不在 PATH 里。解决办法是加到.bashrc：

export PATH="$HOME/.local/bin:$PATH" source ~/.bashrc

问题二：Docker 容器启动后立即退出。先看日志：

docker-compose logs hermes-agent

最常见的原因是模型 API Key 没配或者配错了。Hermes 启动时会尝试连接模型，连不上就直接退出。检查.env文件里的MODEL_API_KEY和MODEL_BASE_URL。

问题三：麒麟 V10 上 Docker 拉镜像失败。这是网络环境问题，配置 Docker 加速源就行。如果加速源也不通，可以找台能上网的机器把镜像拉下来，docker save成 tar 包，再拷贝到目标机器docker load。

6.2 SKILL.md 解析类问题

问题四：SKILL.md 写了但智能体不触发。检查三个地方：触发条件的关键词是否匹配、技能文件是否放在正确的skills/目录下、Agent 是否重启加载了新技能。我习惯改完 SKILL.md 后执行hermes reload热加载，不用重启整个服务。

问题五：工具调用参数不对。这通常是工具描述写得太模糊。模型是根据工具描述来生成调用参数的，描述里没写清楚参数格式，模型就瞎猜。比如weather_api的描述如果只写“查询天气”，模型可能传{"city": "北京", "date": "今天"}，但实际接口只接受city参数。把描述改成“查询城市天气，参数：city（字符串，城市名称）”，问题就解决了。

问题六：多智能体消息循环。两个智能体互相请求，谁也不干活，消息来回弹。解决办法是在主配置里设max_agent_hops: 5，超过跳转次数就强制终止并报错。

6.3 性能与稳定性问题

问题七：响应太慢。智能体执行慢通常是模型调用次数太多。每个步骤都要调一次模型生成参数，步骤多了自然慢。优化方向：合并简单步骤、用更快的模型做意图识别、开启流式输出让用户先看到部分结果。

问题八：执行到一半卡住。看日志里最后一条工具调用是什么。常见原因是工具超时没设限制，或者模型返回了无法解析的格式。给所有工具加超时：

@tool(name="weather_api", timeout=10) def weather_api(city: str): ...

问题九：内存占用越来越高。长时间运行后容器内存涨到几个 G，这是上下文没清理。Hermes 默认保留所有对话历史，跑久了就爆了。在配置里设max_history_tokens: 4096，超过就自动截断旧消息。

6.4 常见问题速查表

7. 我踩过的坑和实测有效的经验

说几个文档里不会写、但实际部署一定会遇到的问题。

第一个坑：SKILL.md 的编码格式。我一开始用 Windows 记事本编辑 SKILL.md，保存后框架解析报错。排查发现是 BOM 头的问题。后来统一用 VS Code 编辑，保存为 UTF-8 无 BOM 格式，再没出过问题。如果你在麒麟系统上用 Vim 编辑，注意:set fileencoding=utf-8。

第二个坑：工具注册的顺序。Hermes 启动时先加载工具再加载技能。如果 SKILL.md 里引用了还没注册的工具，技能加载会失败但不会报错，只是静默跳过。我建议在 SKILL.md 里加一个“工具依赖”章节，启动后检查日志确认所有依赖都加载成功。

第三个坑：模型选择。不是所有模型都适合做智能体。我试过用某个轻量模型跑 Hermes，意图识别准确率只有 70% 左右，经常把“查询订单”识别成“创建订单”。后来换成 DeepSeek 或者通义千问的 7B 以上模型，准确率明显提升。智能体场景对模型的指令遵循能力要求很高，别在这上面省钱。

第四个坑：局域网部署的时区问题。容器默认 UTC 时区，日志时间跟本地差 8 小时，排查问题的时候很迷惑。在 docker-compose 里加TZ=Asia/Shanghai环境变量就能解决。

第五个坑：备份策略。SKILL.md 文件和数据库都要备份。我见过有人改 SKILL.md 改出问题，想回滚发现没备份，只能重写。建议用 Git 管理skills/目录，每次修改都 commit，出问题随时回滚。

8. 下一步可以怎么扩展

基础篇到这里其实已经把 Hermes Agent 的核心概念、安装部署、SKILL.md 编写和常见问题都覆盖了。如果你已经跑通了天气查询那个例子，接下来可以尝试几个方向：

一是接入真实业务系统。把天气 API 换成你公司的 CRM 或者 ERP 接口，写一个处理真实业务流程的 SKILL.md。这是从 Demo 到生产的关键一步。

二是尝试多智能体协同。搭两个智能体，一个负责接收需求，一个负责执行，通过 MessageBus 通信。体会一下权限隔离和职责分离带来的好处。

三是研究自定义工具开发。内置工具覆盖不了所有场景，学会写自定义工具才能发挥 Hermes 的全部能力。重点看工具描述怎么写才能让模型准确生成参数。

四是性能调优。当你的智能体每天要处理几百上千个请求时，模型调用成本、响应延迟、并发处理都会成为问题。这时候需要研究缓存策略、批量处理、异步执行这些优化手段。

我在实际使用中的体会是：Hermes Agent 的 SKILL.md 机制确实降低了智能体开发的门槛，但“降低门槛”不等于“不需要理解原理”。你得知道框架怎么解析 SKILL.md、怎么调度工具、怎么管理状态，才能在出问题的时候快速定位。光会写 Markdown 是不够的，底层逻辑还是要懂。