1. 从一张“执行路径地图”说起：Hermes Agent 到底在解决什么问题
第一次接触 Hermes Agent 的人，十有八九会被它的子系统数量劝退。打开官方文档，满屏都是 Agent Core、Tool Runtime、Memory Store、Planner、Executor、CUA 这些名词，每个词单拎出来都认识，拼在一起就不知道谁调用谁。我最初也是这样，装完 Hermes Agent 之后跑了个最简单的任务，日志里刷出一长串模块名，完全不知道哪一步是“大脑”在做决策，哪一步是“手脚”在执行动作。
后来我意识到，理解 Hermes Agent 的关键不在于背下每个子系统的名字，而在于搞清楚一条任务从进入到完成，到底经过了哪些执行路径。这就像看一座城市的交通图：你不需要记住每栋楼的名字，但你必须知道主干道怎么走、哪个路口会分流、哪里容易堵车。这篇内容就是围绕这张“执行路径地图”展开的，把 Hermes Agent 的子系统拆开，再按真实任务的流转顺序重新拼起来。
Hermes Agent 本质上是一个任务编排与执行框架。它接收一个目标（比如“帮我把这份表格整理成周报”），然后自主拆解、调用工具、观察结果、调整策略，直到目标达成。它和普通脚本最大的区别在于：脚本是“你告诉它每一步怎么做”，而 Hermes Agent 是“你告诉它要什么结果，它自己想办法”。这个“自己想办法”的过程，就是子系统协作的过程。
适合读这篇内容的人有三类：一是刚装好 Hermes Agent、想搞懂内部结构再动手配置的；二是已经能跑通简单任务、但遇到复杂场景就卡住、想定位问题出在哪个环节的；三是需要基于 Hermes Agent 做二次开发或集成的工程师，必须清楚每个子系统的边界和接口。不管你是哪一类，只要把执行路径理顺了，后面配置、调试、扩展都会顺很多。
需要提前说明的是，Hermes Agent 的版本迭代比较快，不同版本之间子系统命名和职责划分会有微调。我下面讲的结构以 v0.21 这一代（也就是常说的 bot mode 相对稳定的版本）为基准，如果你用的是更早或更新的版本，个别模块名可能对不上，但整体执行路径的逻辑是一致的。
2. 子系统全景：谁负责思考，谁负责动手，谁负责记忆
在讲执行路径之前，得先把“演员表”过一遍。Hermes Agent 的子系统可以粗略分成四层：决策层、执行层、记忆层、接口层。很多人搞混，是因为把不同层的模块放在一起比较，自然理不清关系。
2.1 决策层：Planner 与 Agent Core 的分工
决策层是整个系统的大脑，核心是Agent Core和Planner两个模块。Agent Core 是总调度，它持有当前任务的全局状态，决定“现在该干什么”。Planner 则是策略生成器，负责把一个大目标拆成可执行的小步骤。
这里有个容易误解的点：很多人以为 Planner 是“一次性把计划全列出来”，实际上不是。Hermes Agent 的 Planner 是增量式规划的——它先给出第一步或前几步，等执行结果回来之后，再根据实际情况决定下一步。这样做的好处是容错性强，如果某一步失败了，不需要推翻整个计划重来。
Agent Core 和 Planner 的关系，有点像项目经理和方案设计师。Planner 出方案，Agent Core 拍板并安排执行，执行结果反馈回来之后，Agent Core 再决定是继续、调整还是终止。理解这个分工，对后面排查“任务跑偏”类问题非常关键——跑偏往往是 Planner 的拆解逻辑出了问题，而不是执行层出错。
2.2 执行层：Tool Runtime 与 CUA 的边界
执行层负责把决策变成真实动作，主要包括Tool Runtime和CUA（Computer Use Agent）两块。
Tool Runtime 管的是“结构化工具调用”，比如读写文件、发 HTTP 请求、查数据库、调用某个 API。这些工具都有明确的输入输出格式，调用起来确定性高。你在配置里注册的每一个 tool，最终都是通过 Tool Runtime 来执行的。
CUA 管的是“非结构化界面操作”，也就是模拟人在图形界面上的点击、输入、拖拽。它解决的是那些没有 API、只能靠界面交互的场景。CUA 的确定性比 Tool Runtime 低很多，因为它依赖屏幕识别和坐标定位，环境一变就可能失效。
提示：能用 Tool Runtime 解决的，尽量不要用 CUA。CUA 是兜底手段，不是首选方案。我见过不少人一上来就用 CUA 去点按钮，结果界面稍微改版就全废了，维护成本极高。
2.3 记忆层：Memory Store 的短期与长期之分
记忆层主要是Memory Store，它分短期记忆和长期记忆两部分。短期记忆保存当前任务的上下文，比如已经执行了哪些步骤、得到了什么中间结果；长期记忆保存跨任务的知识，比如用户的偏好、常用工具的配置、历史任务的结论。
短期记忆的生命周期是“任务级”的，任务结束就清空；长期记忆是“持久化”的，会一直保留。很多人配置 Hermes Agent 时忽略了长期记忆的清理策略，结果跑了几百个任务之后，记忆库膨胀得厉害，检索变慢，甚至出现旧信息干扰新任务的情况。这个坑后面会专门讲。
2.4 接口层：入口与出口的多种形态
接口层是 Hermes Agent 和外界打交道的地方，包括命令行入口、桌面版界面、以及各种集成接口。热词里提到的“windows hermes agent 桌面版 配置”，说的就是接口层的桌面形态。接口层本身不参与决策和执行，但它决定了你以什么方式给 Agent 下指令、以什么方式看结果。
把四层理清楚之后，子系统之间的关系就明朗了：接口层接收任务，决策层拆解任务，执行层完成任务，记忆层贯穿全程提供上下文支持。下面进入正题，看一条任务实际是怎么流动的。
3. 一条任务的完整执行路径：从输入到落地的七个阶段
这一节是全文的核心。我把一条任务在 Hermes Agent 里的流转拆成七个阶段，每个阶段标注涉及的子系统、关键动作和常见卡点。你可以把这七个阶段当成一张地图，以后遇到问题就对照着看卡在哪一段。
3.1 阶段一：任务接入与意图解析
任务从接口层进来，第一站是 Agent Core。Agent Core 会先做意图解析，判断这个任务属于哪一类：是信息查询、是文件操作、是界面自动化，还是混合型任务。这个判断决定了后续会激活哪些工具和哪条执行路径。
意图解析的质量直接取决于你给的任务描述。描述越模糊，解析越容易跑偏。比如“整理一下那个文件”，Agent Core 不知道“那个”指哪个，“整理”是排序、去重还是格式化。我的经验是，任务描述里至少要说清三件事：操作对象、期望结果、约束条件。约束条件包括时间限制、格式要求、不能触碰的资源等。
这个阶段还有一个容易被忽略的动作：权限校验。Agent Core 会检查当前配置下，这个任务需要的工具是否都已授权。如果任务需要写文件但写权限没开，会在这里就被拦下来，而不是执行到一半才报错。所以如果你发现任务根本没启动就失败了，先查权限配置。
3.2 阶段二：上下文装载与记忆检索
意图明确之后，Agent Core 会向 Memory Store 请求上下文。这一步分两个方向：一是拉取当前会话的短期记忆，二是检索相关的长期记忆。
短期记忆的装载是必须的，它保证任务在多轮交互中不丢失上下文。长期记忆的检索则是按需的，Agent Core 会根据任务关键词去匹配历史知识。这里有个性能考量：长期记忆检索是有开销的，如果每次都全量检索，任务启动会明显变慢。所以 Hermes Agent 通常采用相关性阈值机制，只有匹配度超过阈值的记忆才会被装载。
注意：长期记忆的阈值配置很关键。阈值太低，会装载一堆无关的旧信息，干扰当前决策；阈值太高，又可能漏掉真正有用的历史经验。我一般建议从默认值开始，观察几个任务之后再微调。
3.3 阶段三：Planner 生成初始执行计划
上下文就绪后，Planner 开始工作。它结合任务意图和装载的上下文，生成初始执行计划。这个计划不是自然语言描述，而是结构化的步骤序列，每一步都标注了目标、预期使用的工具、以及成功判据。
成功判据这一步特别重要，但很多人不知道它的存在。Planner 在生成每一步时，会同时定义“这一步怎样算成功”。比如“读取配置文件”这一步，成功判据可能是“文件存在且能解析为合法格式”。执行层完成后，会拿实际结果和成功判据比对，决定是否进入下一步。
如果任务比较复杂，Planner 可能只生成前几步，保留后续步骤的动态调整空间。这就是前面说的增量式规划。你在日志里看到计划步骤是分批出现的，属于正常现象，不是 Planner 出错了。
3.4 阶段四：Tool Runtime 执行结构化动作
计划生成后，Agent Core 把当前步骤派发给执行层。如果是结构化动作，走 Tool Runtime。Tool Runtime 的工作流程是：解析步骤参数、匹配已注册的工具、执行调用、捕获返回结果、做基础校验。
这里的关键是工具注册。Hermes Agent 本身只带一批基础工具，更多能力需要你手动注册。注册工具时要提供工具名、参数 schema、执行逻辑和返回格式。schema 定义得越清晰，Tool Runtime 的参数匹配就越准，出错概率越低。
我踩过的一个坑是：工具的参数 schema 写得太宽松，比如某个参数定义成“任意字符串”，结果 Planner 传进来一个格式不对的值，Tool Runtime 照单全收，执行到一半才崩。后来我把 schema 收紧，加上格式校验，问题就少了。所以 schema 不是走形式，它是执行层的第一道防线。
3.5 阶段五：CUA 接管界面级操作
如果当前步骤涉及界面操作，Agent Core 会把它路由给 CUA。CUA 的执行链路比 Tool Runtime 长得多：先截屏、再识别界面元素、再定位目标坐标、再模拟操作、再截屏验证结果。
这条链路里每一步都可能出问题。截屏受分辨率和缩放影响，元素识别受界面主题和语言影响，坐标定位受窗口位置影响，操作模拟受输入法状态影响。所以 CUA 任务的环境要求比 Tool Runtime 苛刻得多。
提示：跑 CUA 任务时，尽量固定屏幕分辨率、关闭无关窗口、把目标应用置顶。这些看似琐碎的准备，能显著提升成功率。我做过对比，同样的任务，环境整理过和没整理过，成功率能差三成以上。
3.6 阶段六：结果回传与成功判据比对
无论走 Tool Runtime 还是 CUA，执行结果都会回传给 Agent Core。Agent Core 拿结果和 Planner 定义的成功判据比对，得出三种结论：成功、失败、部分成功。
“部分成功”是最容易被忽视的状态。比如一个批量操作，十项里成功了七项，这既不算完全成功，也不算完全失败。Hermes Agent 对部分成功的处理策略取决于配置：可以重试失败项、可以跳过继续、也可以整体回滚。这个策略需要你根据任务性质提前设定，默认策略不一定适合你的场景。
3.7 阶段七：记忆写回与任务收尾
任务完成后，Agent Core 会把本次执行的关键信息写回 Memory Store。写回内容包括：任务结论、使用的工具、遇到的异常、以及可复用的经验。短期记忆随任务结束清空，长期记忆按策略保留。
写回策略直接影响 Agent 的“成长性”。如果什么都不写回，Agent 每次都是从零开始；如果写回太多，记忆库会污染。我的做法是只写回三类信息：可复用的成功模式、可规避的失败模式、用户明确表达的偏好。其他中间过程一律不写回。
4. 执行路径上的三个高频故障点与排查链路
理解了正常路径，接下来看异常路径。这一节我挑三个最高频的故障点，把完整的排查链路走一遍。你以后遇到类似问题，可以照着这个思路定位。
4.1 故障点一：任务卡在意图解析，根本没进入执行
现象：任务提交后长时间无响应，日志停在意图解析阶段，没有任何工具调用记录。
排查链路：
- 先看任务描述是否过于模糊。如果 Agent Core 无法确定任务类型，会反复尝试解析，表现为卡住。解决办法是把任务描述改具体。
- 检查权限配置。权限校验不通过时，有些版本不会明确报错，而是静默等待。去配置里确认所需工具都已授权。
- 检查接口层连接。如果是桌面版，确认 Agent 服务是否正常运行；如果是命令行，确认会话是否有效。
- 查看 Memory Store 是否响应超时。长期记忆检索如果卡住，会拖慢整个解析阶段。可以临时关闭长期记忆检索验证。
这个故障点的根因，八成在任务描述或权限配置上，真正是系统 bug 的情况很少。
4.2 故障点二：计划生成正常，但执行层反复失败
现象：日志里能看到完整的计划步骤，但每一步执行都返回失败，任务在原地打转。
排查链路：
- 先区分是 Tool Runtime 失败还是 CUA 失败。看日志里的模块名，Tool Runtime 的失败通常带明确的错误码，CUA 的失败多是“元素未找到”这类描述。
- 如果是 Tool Runtime，检查工具注册是否正确。重点看参数 schema 和实际传入值是否匹配。我遇到过一次，工具期望整数，Planner 传了字符串，每次都失败。
- 如果是 CUA，检查环境是否变化。分辨率、主题、窗口位置、语言设置，任何一项变了都可能导致识别失败。
- 检查成功判据是否定义过严。有时候执行其实成功了，但判据要求太苛刻，被误判为失败。这种情况调整判据即可。
4.3 故障点三：任务能跑完，但结果不符合预期
现象：任务顺利执行完毕，没有报错，但产出的结果不是你要的。
排查链路：
- 回看 Planner 的拆解逻辑。结果不对，往往是拆解方向就偏了。比如你要的是“汇总”，Planner 理解成了“罗列”。
- 检查长期记忆是否污染了决策。如果记忆库里存了过时的偏好，Planner 可能按旧偏好执行。清理相关记忆再试。
- 检查是否有“部分成功”被当成“完全成功”处理。批量任务里这种情况很常见，需要显式配置部分成功的处理策略。
- 检查工具的实际行为是否符合预期。有些工具在特定输入下会走默认分支，产出和预期不符。单独测试该工具验证。
这三个故障点覆盖了大部分日常问题。排查的核心思路是：先定位卡在哪个阶段，再在该阶段内逐项排除。不要一上来就怀疑系统 bug，绝大多数问题都出在配置和描述上。
5. 桌面版与子系统环境下的配置要点
热词里频繁出现“windows hermes agent 桌面版 配置”和“windows 子系统”“android 子系统”这类词，说明很多人的实际使用环境是桌面版加子系统。这一节专门讲这种环境下的配置要点。
5.1 桌面版配置的三个关键项
桌面版和命令行版最大的区别是接口层形态不同，但底层子系统是一样的。桌面版配置有三个关键项容易出错：
第一是工作目录。桌面版默认工作目录可能不是你预期的位置，导致文件操作找不到目标。配置时显式指定工作目录，避免歧义。
第二是权限范围。桌面版为了安全，默认权限往往比较保守。如果你需要文件写入、进程调用等能力，要手动放开。但放开的同时要清楚风险，不要无脑全开。
第三是CUA 的屏幕参数。桌面版跑 CUA 时，必须让 Agent 知道当前屏幕的分辨率和缩放比例。这个参数配错，CUA 的坐标定位会整体偏移，表现为“点不准”。
5.2 子系统环境下的路径与权限映射
在子系统环境里跑 Hermes Agent，最麻烦的是路径映射和权限映射。子系统里的文件路径和宿主系统不一样，Agent 配置里写的路径如果在子系统内执行，可能根本不存在。
我的做法是：统一在子系统内配置和运行，不要跨环境混用路径。如果必须跨环境，就在配置里显式做路径转换，并且测试验证。权限方面，子系统内的用户权限和宿主不同，文件读写、网络访问都可能受限，配置时要逐一确认。
注意：子系统环境下的 CUA 尤其容易出问题，因为图形界面的渲染和坐标体系可能和宿主不一致。如果 CUA 在子系统里表现异常，优先怀疑环境差异，而不是 Agent 本身。
5.3 教务管理等业务子系统的集成思路
热词里出现了“教务管理子系统”这类业务系统词汇，这其实反映了一个真实需求：把 Hermes Agent 和已有的业务子系统集成起来。教务管理这类系统的特点是流程固定、数据敏感、操作需要严谨计划。
集成思路是：把业务子系统的操作封装成 Tool Runtime 的工具，而不是用 CUA 去点界面。因为业务系统通常有数据库或 API，走结构化调用更稳定、更安全。封装工具时，把业务规则写进参数校验里，比如“排课不能冲突”这类约束，在工具层就拦住，不要指望 Planner 每次都记得。
这样做的好处是，Agent 的决策层只需要关心“要做什么”，业务规则由工具层保证，职责清晰，出错也容易定位。
6. 让执行路径更稳的几个实操习惯
最后分享几个我在长期使用中养成的习惯，都是些不起眼的细节，但对稳定性帮助很大。
习惯一：给每个任务写清楚成功判据。不要指望 Agent 猜你的意图。你在任务描述里把“什么样算完成”说清楚，Planner 生成的判据就越准，返工越少。
习惯二：定期清理长期记忆。我一般每周清理一次，把过时的偏好和失效的经验删掉。记忆库干净，决策质量明显提升。
习惯三：CUA 任务前先做环境快照。记录当前的分辨率、主题、窗口布局。任务失败时，对比环境是否变化，能快速定位问题。
习惯四：工具 schema 宁严勿宽。参数校验严格一点，把错误拦在执行之前，比执行到一半崩溃再排查要省事得多。
习惯五：复杂任务先跑小样本。批量任务不要一上来就全量跑，先拿几条数据验证路径通不通，通了再放量。这个习惯帮我避免过好几次大规模返工。
这些习惯说起来简单，但真正坚持下来的人不多。Hermes Agent 这类框架的能力上限很高，但它的稳定性很大程度上取决于使用者的配置习惯。把执行路径理解透，把配置做扎实，它才能稳定地帮你干活。
