企业官网建设流程全解析

我很少用“架构地图”这四个字去形容一个AI Agent项目，但Hermes Agent确实值得这样画一遍。市面上的Agent框架很多，大多数你玩两天就发现，它不过是在聊天窗口外面套了一层工具调用。Hermes Agent不一样，它更像一套能拆开看的“任务执行系统”：有明确的子系统边界，有可追踪的执行路径，还能在Bot Mode、Windows桌面版、Obsidian知识库之间切换场景。这篇文章不打算讲一堆概念，只做一件事：把Hermes Agent的子系统构成、一次任务从输入到结果走过的完整路径，以及我实际部署和调优时踩过的坑，全部摊开来讲。

适合谁来读？想自己搭AI Agent、被“Agent架构”搞到头晕的人，还有准备把Hermes Agent接到本地知识库或桌面自动化场景的开发者。默认你懂一点Python和命令行，即使不懂架构，跟着路径走一遍也能理解七成。

1. Hermes Agent 整体架构拆解：先看清边界再谈执行

1.1 从“助手”到“执行体”：Hermes Agent的产品定位

Hermes Agent不是那种“一问一答”的聊天机器人。它最核心的定位，是一个能自主拆解任务、调用工具、读写本地知识库的AI执行体。你丢给它一个模糊目标，比如“整理昨天笔记并发送邮件”，它可以自己规划步骤，然后调用文件操作、搜索、甚至桌面自动化来完成这件事。

它有三个比较醒目的能力，这也是它区别于普通对话助手的核心：第一，Bot Mode，可以在无图形界面的服务器环境里跑，适合无人值守任务；第二，Windows桌面版，针对桌面环境做了适配，可以操作本地软件；第三，Obsidian知识库集成，直接读写本地Markdown笔记，让Agent拥有跨任务的长期记忆。

这三项能力不是零散堆砌，而是分别落在架构的不同层级里。理解一个项目的架构，不能只看它“有哪些功能”，要看这些功能被放在哪个模块、模块之间如何通信。功能会变，架构才是长期演化的骨架。所以这篇总览，我先从子系统划分讲起。

1.2 五大子系统的划分逻辑

基于我对Hermes Agent源码和实际运行行为的观察，我会把它拆成五个子系统：交互接入层、Agent核心层、工具执行层、记忆存储层、配置与上下文层。每层各司其职，并且有明显的边界。

为什么按这个方式划分？核心原因是“稳定”。如果模型调用、工具执行、界面逻辑全写在同一个大文件里，改一个按钮都可能影响搜索功能，更没法在Bot Mode和桌面版之间复用逻辑。分层之后，桌面版和Bot Mode只是入口不同，后面共用同一套核心调度和工具执行。这是Hermes Agent能同时支持多种运行模式的关键。

1.3 为什么用“地图思维”看架构

我不太喜欢那种把每个模块单独拎出来讲一遍的架构文章。看完了你也不知道一条真实指令跑起来，到底经过了哪些地方、在哪一步最容易失败。所以这篇我用“执行路径地图”的讲法：从用户输入到最终输出，画出一条主干执行链路，再在主干上标注分支。就像看城市地图，你不用记住每条胡同，但必须知道主干道在哪、路口在哪。

Hermes Agent执行路径的主干非常清晰：输入 → 解析 → 规划 → 执行 → 记忆归档 → 回复。后面所有内容，都是在给这条主干画分支。我刚开始接触Hermes Agent时，找了半天“入口在哪”，后来发现它支持多个入口，官方快速开始和桌面版引导完全不同。这是好事，说明架构有弹性；但也意味着你需要一张地图来定位自己正在哪一层。

2. 执行路径地图：一条指令在Hermes Agent内部的完整旅程

2.1 入口分流：Bot Mode与桌面版的路径差异

执行路径的起点不是Agent核心，而是入口适配器。Hermes Agent v0.21开始，Bot Mode成了官方推荐的无头运行方式。你在服务器上执行hermes --bot，它会进入一个事件循环，从标准输入、消息队列或者Webhook中读取任务。桌面版则提供图形界面，启动后可以直接填写任务、查看中间步骤、操作文件路径。

两个入口的差异主要发生在“前处理”阶段。桌面版会把用户输入的文本、附件、当前窗口信息一起打包成交互事件；Bot Mode则接收纯文本或JSON消息。但走完入口适配后，两者汇入同一条管道：构建Session、加载配置、创建上下文、启动Agent核心。

这里有一个容易踩的坑：桌面版默认会启用工作区管理，启动时可能弹出路径选择窗口，如果你没点目录，后续任务会找不到基准路径。Bot Mode如果没有预先设置工作目录参数，也可能因为权限问题无法访问文件。所以我的建议是：无论哪个入口，第一次使用前，都先把工作目录和知识库路径设置好，不要依赖交互界面里的临时选择。

2.2 核心调度：Agent核心如何拆解任务

进入Agent核心层后，任务不会直接丢给LLM生成最终回复，而是先经过“规划-执行-观察”的循环。这是现代Agent的主流做法，但Hermes Agent实现得比较克制：它会先把当前上下文、可用工具列表、用户任务拼装成一次模型调用，让模型输出一个结构化规划，通常包含thought、action、action_input三个部分。

举个例子。我让它“把当前目录下所有未整理的md文件移动到archive文件夹，并生成一份清单”。它的规划很直白：

1. 调用list_files工具，获取目录下所有.md文件。
2. 检查archive文件夹是否存在，不存在则创建。
3. 用move_file工具批量移动文件。
4. 用write_file工具输出一份清单。

核心层的工作不是替模型做决定，而是保证每一步工具调用都符合参数Schema，并把执行结果追加到上下文中。如果某一步执行失败，错误信息会被回传给模型，由模型决定是重试还是更换工具。这一步是整个执行路径上最容易卡住的地方。好在Hermes Agent每一步都会生成结构化事件，所有事件构成一条“轨迹”。你可以在控制台开启debug模式，看到每一步耗时和token消耗，这样调试时能精准定位问题。

2.3 工具执行：CUA与常规API调用的路径分支

执行层的第一个分支，是“普通工具调用”和“CUA桌面操作”。

普通工具调用指文件读写、HTTP请求、数据库查询、命令行执行这类功能，它们走executor，直接调用对应函数，然后把返回值写回上下文。这条路径短、速度快，也是日常用得最多的分支。

CUA则是Computer Use Agent的缩写，专门用来操作桌面应用。它和普通工具调用的执行路径差异很大：先截图当前屏幕 → 传给多模态模型 → 模型判断下一步动作，比如点击坐标、输入文本、滚动页面 → CUA执行动作 → 再次截图验证结果。这条路径延迟高、token消耗大，但能解决“只有界面、没有API的软件怎么自动化”的问题。

在这条分支上，权限控制很关键。普通工具调用通常只校验参数格式，CUA动作则必须有“动作白名单”和“敏感操作确认”。我在实际配置里会把CUA的允许操作范围限制在当前显示器内，防止它误点状态栏或系统设置。不要小看这一步，一旦失去约束，模型“自由发挥”的代价非常直接。

2.4 记忆读写与上下文回收：路径中最容易被忽略的环节

很多Agent框架的执行路径里没有“记忆”这个环节，导致每次任务之间都是失忆的。Hermes Agent把记忆拆成两条子路径：短期上下文和长期记忆。

短期上下文保存的是当前任务的思考过程、工具返回、错误信息。它会一直累积，直到接近模型窗口上限，然后触发压缩策略。压缩不是粗暴截断，而是让LLM把当前重要信息归纳成摘要，再放回上下文，这样任务连续性不会断。

长期记忆保存的是跨任务的重要事实、笔记、决策记录。默认情况下，Hermes Agent可以把记忆写入Obsidian仓库，每次任务结束时生成一个Markdown文件，内容包括任务目标、关键步骤、最终结果、个人反思。这条设计特别适合知识管理场景。如果你给Obsidian配上本地向量插件，Hermes Agent下一次任务开始时还能检索相关旧笔记，实现“带着记忆干活”。

这里我要特别提醒：长期记忆写入应该是异步的，不要放在主执行路径上同步等待。如果你在配置里把记忆同步设为同步模式，每一步任务结束都要等磁盘写入，整个执行速度会慢到让你怀疑人生。

2.5 结果聚合与返回：从内部事件流到用户可读输出

最后一步是结果聚合。Agent核心会收集所有执行轨迹事件，过滤掉debug级别的内部日志，只保留规划、执行记录、最终结论。桌面版会展示一个时间线，Bot Mode则打印一段简洁总结。如果执行过程中有工具调用失败，返回结果会区分“成功的部分”和“失败的部分”，不会假装全流程圆满成功。

有一个很影响体验的参数叫final_answer_style，你可以设置成concise或detailed。我平时用concise，除非要做任务审计。另一个参数include_tool_logs默认关闭，调试时可以临时打开。到了这一步，一条完整指令在Hermes Agent内部的路径就走完了。不过要真正用顺手，还得深入配置、记忆和CUA这三个子系统。

3. 核心子系统深度解析：配置、记忆与工具调用

3.1 配置子系统：从Bot Mode到Windows桌面版的关键参数

Hermes Agent的配置通常是一份YAML文件。启动时，它会自动合并“默认配置”“用户配置”“环境变量”三层，优先级从高到低是环境变量、用户配置、默认配置。这个设计很适合多环境复用，你可以在不同机器上用同一份主体配置，只靠环境变量区分敏感信息。

以Windows桌面版为例，安装后会在用户目录下生成一份hermes_config.yaml。我建议重点关注这几个参数：

• model.provider：模型服务商，支持OpenAI兼容接口，也可以填本地模型服务地址。
• model.temperature：取值范围0到1，执行类任务建议0.2以下，不然模型容易“发挥过度”。
• agent.max_steps：任务最多执行多少步，默认20，复杂任务我一般改成40。
• workspace.path：工作目录，Bot Mode没有它基本跑不动。
• memory.obsidian_path：Obsidian仓库的绝对路径。
• executor.timeout：单次工具调用的超时时间，默认30秒，网络慢时改成60。

这里给一份我常用的配置片段：

model: provider: openai-compatible base_url: http://127.0.0.1:8000/v1 api_key_env: HERMES_API_KEY temperature: 0.2 agent: max_steps: 40 final_answer_style: concise workspace: path: D:/agent-workspace memory: obsidian_path: D:/ObsidianVault/hermes-notes sync_mode: async executor: timeout: 60 cua_enabled: true

请注意：不要把你的API密钥直接写进YAML。用环境变量，比如HERMES_API_KEY。我见过有人把密钥提交到Git仓库，第二天就被脚本扫描到，白白损失了一笔费用。密钥管理是使用AI Agent的基础功课。

3.2 记忆子系统：Obsidian集成与长期记忆落盘机制

为什么选择Obsidian作为长期记忆的载体？因为它是纯本地Markdown，没有私有格式。Hermes Agent可以把记忆写成一个个普通md文件，你直接用Obsidian查看、编辑、建立双向链接。这种设计最大的好处是：你的记忆不绑定在某个Agent的私有数据库里，记忆属于你，Agent只是代笔。

记忆子系统的结构可以分成三块：

1. 短期上下文缓存：一个环形缓冲区，只保留最近N轮对话和工具结果。
2. 记忆摘要器：任务结束后，把短期上下文压缩为结构化摘要，再交给写入器。
3. Obsidian写入器：按yyyy-mm-dd-topic.md的命名规则生成文件，并在文件头部写入YAML front matter，如tags、related、created。

实际使用中，记忆文件会沉淀出很多有价值的东西。我曾经让它调研“本地模型部署的三种方案”，它写下的不只有结论，还有它推理时的关键依据和排除的方案。这些笔记直接进入Obsidian知识库，我写周报时可以直接搜索引用。

记忆读取路径同样重要。新任务启动时，Agent核心会先向记忆检索模块发送一个查询，比如“我最近有没有看过本地模型部署相关笔记？”。检索模块会先在Obsidian目录里做文件名和标签的粗筛，再做正文关键词匹配。如果配置了语义搜索插件，它还能通过本地HTTP接口调用向量召回。召回结果通常限制在3条以内，再注入提示词上下文。这样既不会丢失关键记忆，也不会把整个知识库塞进上下文导致token爆炸。

3.3 工具注册与权限：CUA执行桌面操作的架构细节

Hermes Agent的工具执行层，不是一个写满if-else的大函数，而是一个“工具注册表”。每个工具都是一个插件，注册表负责加载、校验、调用、回收资源。新增工具时，你需要写一个Python类，实现execute和schema两个方法，然后通过工具装饰器注册。

工具注册表的结构大致长这样：

{ "tool_name": "cua_click", "description": "Simulate mouse click on desktop", "parameters": { "type": "object", "properties": { "x": {"type": "integer"}, "y": {"type": "integer"} } }, "permissions": ["cua.mouse"], "timeout": 15 }

这里的permissions是Hermes Agent的安全设计。你可以在配置里开启“敏感操作确认”模式，当Agent要执行cua_click、file_delete、shell_exec这类高风险操作时，会先暂存动作，等待人工确认。Bot Mode下可以用auto_approve参数跳过确认，但强烈不建议全局开启。

CUA组件是我觉得最有趣也最容易翻车的部分。它确实能自动操作Windows软件，比如打开Excel、调整窗口尺寸、点击按钮；但问题也出在坐标偏差和分辨率适配。一个很有效的技巧是：把CUA的动作空间归一化到百分比坐标，而不是绝对像素。这样换一台显示器，它也能大致命中。同时，每次点击后加一个“验证截图”步骤，否则它自以为点了“保存”，其实对话框根本没弹出来。

4. 部署与实战：安装配置、调优思路与问题排查

4.1 从零安装：Windows桌面版与Bot Mode的共性和差异

先说清楚：Hermes Agent不是一个“下一步下一步”就能装完的普通软件，它需要你有一点折腾的耐心。我在Windows上安装桌面版时，流程大致是这样的：

1. 从发布页面下载对应平台的安装包，解压到D:/hermes。
2. 安装Python 3.10以上，并确保python命令在PATH里。
3. 首次启动桌面版，引导填写模型接口地址和API Key。
4. 配置Obsidian记忆目录和工作目录。
5. 跑一个简单任务，比如“列出当前工作目录下的文件”，验证链路通畅。

Bot Mode的安装流程其实差不多，只是多了两步：拉取源码后执行pip install -r requirements.txt，再用命令行启动hermes --bot --config ./config.yaml。如果部署在服务器上，建议用systemd或PM2守护进程，崩溃后自动重启。

这里有个容易混淆的点：桌面版和Bot Mode的配置字段大部分相同，但桌面版会额外包含ui.enable、ui.workspace_switcher等选项。如果你把桌面版的配置原封不动丢给Bot Mode，大概率会因为缺少Session初始化参数而启动失败。反过来倒是比较安全。

4.2 配置调优：让执行路径更稳定的几个参数

跑了一段时间后，我总结出几个“保命参数”，每次遇到不稳定问题，优先检查它们。

temperature要压低。Agent不是创意写作比赛，它是在执行任务。温度太高，模型可能编造不存在的工具，或凭空生成文件路径。执行类任务我推荐0.1到0.2，如果任务本身需要创意，再单独调高。

max_steps要设上限。默认20步听起来不少，但一个复杂桌面自动化流程很快就能耗尽。不过步数越多，token消耗越大。我一般设40，同时配合step_token_limit，比如每步限制2000 token，防止失控。

executor.timeout一定要设。哪怕你用的是本地模型，也可能因为某个工具挂起导致整个任务卡死。设成60秒后，再给模型反馈“上次调用超时”，它能自己决定重试还是换方案。

concurrency是双刃剑。Bot Mode支持并发任务，但并发数调高后，模型服务的rate limit会被瞬间打满，导致大量重试。我宁愿一个一个来，并发数保持2，整体反而稳定得多。

最后一个参数是log_level。日常使用设为info，排查问题设为debug。debug日志会记录每次LLM请求的原始返回，也包括工具调用的入参和返回值。几乎所有“它为什么要这么干”的疑问，都能在debug日志里找到答案。

4.3 常见问题排查表

我把实际遇到过、以及社区里高频反馈的问题整理成一张表：

这张表的思路是：先定位问题发生在哪一层——入口、调度、工具、还是记忆，不要一出问题就怀疑模型能力。

5. 架构演进与二次开发建议：把Hermes Agent变成自己的框架

5.1 从v0.21到新版本：Bot Mode背后的架构变化

我最初接触Hermes Agent时，比较稳定的是v0.21的Bot Mode。那时它更像一个命令行助手，执行路径也很简单：读输入、调模型、返回回复。后来工具调用、桌面版、CUA陆续引入，核心层逐渐重构成事件驱动架构。

为什么选事件驱动？因为多个入口和子系统之间如果全部写成同步调用，会变成一团乱麻。事件驱动让每个子系统只关心自己收到的消息，执行路径变成了一条“事件链”。比如桌面版点击“开始”，发射task_created事件；Agent核心监听事件，开始规划；工具执行层完成后发射tool_completed事件；记忆子系统订阅task_completed事件，异步归档。这种设计的好处是：你不改核心逻辑，也能挂一个新的监听器，做日志、统计、审计。

Bot Mode在这个架构里的位置，本质上是一个“事件队列消费者”。它从队列里读取任务，每拿到一条就发射task_created事件，后续流程和桌面版完全一致。所以你完全可以让桌面版和Bot Mode同时监听同一个队列，实现“一个控制台，多端执行”。

5.2 二次开发：如何挂载一个自定义子系统

如果你想给Hermes Agent增加一个自己的能力，比如接入内部系统，可以按下面这个路径来。

第一步，确定挂载在哪一层。对外提供数据，就做成工具；处理Agent的思考过程，就做事件监听器；存储额外信息，就做记忆写入器。以工具为例，只需要在tools/my_tool.py里写一个类：

from hermes.tool import BaseTool, tool @tool("query_internal_api") class QueryInternalAPI(BaseTool): def schema(self): return { "type": "object", "properties": {"endpoint": {"type": "string"}}, "required": ["endpoint"] } def execute(self, params): # 调用内部API，返回结果 return {"data": "ok"}

第二步，在配置的tools列表里加上query_internal_api，配置它需要的权限和环境变量。

第三步，用debug模式跑一遍，确认模型能够发现并调用这个工具。如果你发现模型从来不用它，很可能是description写得太模糊。模型靠description决定何时调用工具，所以一定要写清楚“什么时候用、输入什么、返回什么”。

如果你想挂一个全新的子系统，比如“定时任务调度器”，方向就是监听task_created事件，再根据调度规则发射新任务。核心层不关心你的实现细节，只要在事件总线上注册好就行。

对我个人来说，调Hermes Agent最难忘的一个场景，是凌晨两点看到一个任务卡在“工具调用”上，怎么重试都过不去。打开debug日志之后才发现，CUA组件在点击一个弹窗时坐标偏移了20个像素，而且每次点击后没有验证，所以它一直没意识到自己没点上。从那以后我给自己定了一条规矩：任何涉及桌面操作的任务，必须开启“截图验证”和“动作日志”。工具调用不是越智能越好，而是越可验证越好。能做到可观测、可干预，你才算真正掌握这个系统。