ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

Hermes Agent源码架构地图:子系统分工与请求执行路径全解

Hermes Agent源码架构地图:子系统分工与请求执行路径全解

我把 Hermes Agent 的源码沿着执行路径完整走了一遍,把里面几大子系统的分工、边界和串场机制梳理成了一张可以随时参考的地图。无论你是在二次开发、想接入自己的工具链,还是只是被 Habermas 这个开源项目里一堆模块名绕晕,这篇都适合你。它主要解决三类问题:第一,Hermes 到底由哪些子系统组成;第二,一次用户请求从进入到落地的完整路径是怎么走的;第三,实际运行中出问题该去哪个子系统排查。

先说说为什么我这次要专门写“架构总览”。因为这类 LLM Agent 项目最大的坑不是代码难读,而是“路径不清楚”。你打开代码仓库,能看到一堆目录、模块、服务,但不知道它们在执行时谁先谁后、谁依赖谁。结果就是改一个小功能,把整个调用链都翻一遍,试错成本极高。而 Hermes 的设计其实没有想象中复杂,核心就是几大子系统通过统一的任务上下文串成一条执行流水线。把这条流水线摸清,后面改东西和调 bug 都会轻快很多。

1. 从整体设计思路看子系统划分的动机

1.1 为什么 Hermes 选择“子系统解耦”而不是“一个大循环”

很多初版 Agent 框架其实是“一个大函数”。用户在终端里输入一句请求,代码直接把它丢给大模型,模型返回的文本被正则拆一下,匹配到某个工具就去执行,执行完再把结果拼进下一条 prompt。这种做法在 demo 阶段非常爽,代码量少、跑通快,但一旦工具数量超过五六个,或者要引入多轮记忆、权限控制、上下文压缩,这个大函数就会迅速膨胀到没人敢动的程度。

Hermes 从第一天起就不是这个思路。它把整个系统拆成了入口路由、规划编排、工具执行、记忆管理、CUA 操作、安全审计等若干子系统,每个子系统只处理自己负责的那一段逻辑。这带来的直接好处是:你可以单独替换任意一环而不影响其他部分。比如你不想用默认的规划器,可以只改 Planner 接口的适配层,其他工具照常工作;你希望把记忆从本地改成外置向量库,也只需要动 MemoryService 对接的接口。对于源码阅读者来说,这种切分最大的价值是定位问题快:命令没被识别?去入口路由子系统查;工具调用了但没效果?去执行子系统查;上下文被截断?去记忆子系统查。

从架构术语上看,这属于非常经典的“分层 + 模块化”组合。它不是严格的微服务,也不是无状态的函数式流水线,而是进程内的高内聚模块划分。这里我插一句:好多人一提到架构就想到微服务,觉得要拆成独立进程才专业。但在 Hermes 这类单机运行、桌面级部署的 Agent 里,微服务是过度设计,进程内的模块边界已经足够清晰,而且少了一堆网络通信的延迟和序列化开销。后面第 4 部分我会专门讲它为什么先用模块化单体,而不是一上来就搞微服务。

1.2 划分子系统时依据的三条边界

我在阅读 Hermes 源码和实际部署过程中发现,它的子系统边界不是随意切的,基本遵循三条原则。理解了这三条原则,你就能预测目录里某些模块为什么存在。

第一条是职责边界。每个子系统只回答一个大问题。入口路由只决定“这次请求走聊天还是走任务执行”,规划子系统只负责“把这个目标拆成哪几步”,工具执行子系统只负责“把某一步落实到真实操作”。谁也不要越界去管别人的事情。这样换模型、换工具、换记忆后端时,改动范围都能被控制住。

第二条是状态边界。记忆与执行是分开的。执行过程产生的中间结果不会直接塞进记忆模块,而是通过统一的上下文对象在系统内流转;只有当一轮任务完成时,记忆子系统才会决定哪些信息值得持久化。这样做避免了“执行过程污染长期记忆”这种很难排查的问题。我可以举个具体例子:假设一次任务里模型临时猜错了一个参数,被系统纠正回来,这个纠正过程属于执行轨迹,如果异常状态被当成长期记忆存进去了,下一次任务就可能被带偏。Hermes 把状态分成“会话态”和“持久态”两套通道,就是防这个。

第三条是安全边界。所有会真实影响外部环境的操作(改文件、跑命令、发网络请求、操作系统界面)都必须经过安全子系统确认。规划子系统可以提出“想删某个目录”,但它没有权限真正执行删除,真正动手前安全子系统还要核验一遍。这个边界在本地 Agent 里尤为重要,因为本地 Agent 的权限通常比云端 Agent 更大,一旦大模型的输出不安全,破坏面也更直接。

这三条边界合在一起,构成了后面整个执行路径地图的骨架。接下来我把核心子系统一个个拆开讲,你看完就能知道每个模块在路径中的作用。

2. 核心子系统逐个拆解与关键职责

2.1 入口路由子系统:先搞清楚用户到底想干什么

入口路由子系统是整个 Hermes 的第一道关卡。它做的事情不只是“把用户的文本送给大模型”这么简单。它会先做一次轻量级意图判断:这轮输入是要继续对话,还是要发起一次具体的任务操作,或者干脆是一条需要走工具链的命令。这个判断通常可以由一个快速的模型调用完成,也可以用规则先做一次预筛,Hermes 的实际实现里是两者结合。

在架构上,这个子系统有一个重要的输出产物叫 AgentRequest。它不等于原始用户文本,而是带上了处理元信息的标准化请求对象,比如请求类型、关联的会话ID、上下文引用、期望的回复风格。后面的规划子系统拿到的就是这种结构化对象,而不是直接拿字符串去做推理,这样规划器可以少做很多类型判断。对于阅读源码的人,我的建议是重点看这个子系统里的 prompt 模板,因为意图判断的效果好坏,大部分取决于模板里的指令写得清不清楚。

我还想提醒一个容易忽略的细节:入口路由子系统负责的是“第一轮初始上下文”的组装,但它不会管后续规划时要追加哪些工具描述。工具描述是在规划阶段动态拼进去的。这个分工经常有人搞混,导致调试时在入口部分拼命找工具定义找不到。工具注册信息不在这里维护,它属于执行子系统的资源目录。

2.2 规划子系统:把目标拆成可执行的步骤序列

规划子系统是 Hermes 架构里最像“大脑”的部分,核心任务是把一个模糊目标拆解成具体步骤。它在实现上有两种模式的混合:一种是 Plan-and-Execute,先一次性生成多步计划,再逐步执行;另一种是 ReAct 式循环,即“推理一步、执行一步、观察结果、再推理下一步”。Hermes 会根据任务复杂度在两者之间切换,简单任务直接走快速执行通道,复杂任务先输出一个完整计划给用户确认,再开始动手。

这里要重点说一个我在实际使用里特别认同的机制:复杂任务先出草稿再动手。Hermes 在规划阶段的“草稿”不会直接触发任何副作用,它只是生成一个方案文本。用户确认后,方案才被翻译成具体的工具调用序列。你别小看这一步,它能让系统在真正执行前拦截掉一大半胡来的规划。很多 Agent 框架不做这个确认,让大模型一边推理一边调用工具,结果经常是改了一个文件之后才发现方向错了,这时候回滚成本极高。

规划子系统的关键参数也值得关注一下。比如 max_steps 代表最多执行几步,temperature 决定计划生成的随机程度,top_p 控制采样范围。我在本地跑 Hermes 时习惯把 max_steps 设到 8 到 12,太少的话复杂任务容易被截断,太多则会让失败任务在循环里空转很久。这个值没有标准答案,取决于你的任务类型和工具数量,但一定要设上限,不然模型可能陷入自我争论式的递归。

规划子系统的输出是 TaskPlan,里面是一组有序步骤。每个步骤包含目标描述、可能的工具候选、前置依赖、预期结果。这个 TaskPlan 不直接调用工具,它只是“图纸”,真正的施工要交给执行子系统。

2.3 工具执行子系统:真正碰触外部世界的地方

工具执行子系统在架构上的定位,是把 TaskPlan 里的每一步翻译成真实调用。它维护着一张工具注册表,每个工具都有名字、参数 schema、执行函数、权限级别。规划器生成工具名和参数后,执行子系统负责校验参数合法性、检查权限、真正调用对应函数,并把返回值整理成模型能消费的结构化消息。

这里最值得讲的是执行子系统的“参数校验”环节。大模型生成的工具参数经常会犯低级错误,比如少传一个必填字段、把布尔值写成字符串、文件名带多余空格。直接在外部系统上撞出错误,虽然也能暴露问题,但代价太大。Hermes 的做法是先做一次 JSON Schema 校验,不合格的调用会被打回重试,而不是直接发给外部环境。这个设计在架构上帮了大忙,因为它把“模型输出的格式噪音”和“工具本身的真实错误”分离了。排错时如果看到 “Tool argument validation failed”,先不要怀疑工具实现,大概率是模型生成的参数格式不对。

工具执行子系统还强制加了超时控制。每一个工具调用都有独立的 timeout,默认值不长,避免某个网络请求或本地命令挂死之后把整条执行链拖垮。超时之后会生成一条 ToolTimeout 消息回传给规划器,规划器可以据此调整策略,比如换个工具或换种参数。我建议你在配置里把超时设成阶梯式:快速工具 10 到 15 秒,慢速工具 60 到 90 秒。万不得已不要用全局统一超时,不然你优化某个慢工具时会误伤所有调用。

执行子系统的返回值会被包装成 ToolResult,包含状态码、执行输出、错误摘要和耗时。这个 ToolResult 会作为新的上下文片段传回规划器,驱动下一轮推理。到这里,你应该能看出来整个主循环的样子:规划→执行→观察→再规划。执行子系统就是那个“真正动手的肢体”,但它没有记忆,也没有决策权,决策权仍在规划器手里。这个隔离非常关键。

2.4 记忆与上下文管理子系统:防止 Agent 失忆的档案系统

记忆子系统处理的对象不是原始聊天记录,而是“哪些信息值得跨任务保留”。它分两个层次:短期上下文和长期记忆。短期上下文就是当前任务窗口里的对话轮次、工具结果、规划草稿,这些数据留在内存里,任务结束就可以丢。长期记忆则会把经过筛选的关键事实写入本地存储或向量数据库,下次任务开始时按相关性召回。

我要强调一个实操教训:上下文压缩是记忆子系统的核心功能,而它的触发时机比压缩算法本身更重要。如果等 token 数快超限了才压缩,很可能已经把关键信息挤出上下文了;如果压缩得太频繁,模型又会丢失太多执行细节,导致后续计划质量明显下降。Hermes 的做法是在每个步骤结束后检查当前 token 消耗量,接近阈值时自动把早期的工具调用摘要化,保留用户原始目标不动。这个“保原始目标、缩中间过程”的策略,我在实际跑长任务时验证过非常有用,能大幅减少模型跑偏的概率。

记忆子系统的检索不是每次请求都做全量召回。它根据入口路由给出的意图标签和当前任务的核心名词,去向量库里捞最相关的几条历史记录。召回结果会拼进系统提示词的尾部,而不是插在用户消息前面。这个顺序安排也很讲究,因为模型对系统提示词和用户消息的注意力权重不同,把历史事实放在系统提示词里会比放在普通消息里更稳定地影响行为。

2.5 安全与审计子系统:给执行路径加上的最后一层护栏

安全子系统是整个 Hermes 架构里我最看重的一块,因为它直接决定了这个 Agent 敢不敢被放手使用。它维护一份权限规则表,对工具按危险等级分成“直接放行”“需确认”“默认禁止”三类。例如文件读取是直接放行,文件删除或系统命令执行则需要用户在确认层点头,涉及敏感目录的操作默认禁止。

这个子系统的执行时机藏在工具调用链路上。工具执行子系统在真正调用函数前,会先向安全子系统请求一次“Permission Check”。安全子系统根据规则表、当前会话的可信等级和用户预设的 allowlist 返回放行、拒绝或需要人工确认。人工确认这个分支会暂停整条执行路径,弹出一个交互窗口让用户决定,然后收到结果再继续。这就是执行路径地图里我很强调的一条旁路:主链路不一定一直畅通,有时候会停顿在安全闸门前面。

审计日志也是这个子系统负责。每次工具调用、每一次权限拒绝、每一次用户确认,都会被登记在本地日志里。很多人不重视审计,觉得它只是事后追溯用的,但在实际调试中,审计日志能帮你还原出“模型到底尝试了什么、被什么挡住”。有一次我排查一个 Agent 行为异常,发现模型连续三次尝试删除临时目录,要不是安全子系统拦下来,系统状态早就花掉了。没有审计日志的话,你根本不知道它在后台搞了这些动作。

2.6 CUA 操作子系统:将执行路径扩展到真实界面

CUA,全称 Computer Use Agent,是 Hermes 很亮眼的一块。它的职责是把工具调用的范围从函数库扩展到真实桌面和浏览器界面:模拟鼠标点击、键盘输入、读取屏幕截图、在 Web 页面上进行操作。这个子系统的加入,本质上把 Hermes 从“能调用 API 的聊天机器人”提升成了“能操作一台电脑的智能代理”。

CUA 子系统的执行路径比较特殊,它不是一个普通工具调用,而是一串需要持续观察的动作序列。每一步的流程是:截屏获取当前界面状态→模型分析界面并决定一个动作→模拟器执行动作→再次截屏验证界面变化。这个“观察→动作→再观察”的循环,和规划子系统的主循环是嵌套关系。外层规划器认为“需要打开浏览器完成一项任务”,然后 CUA 子系统接管一段操作,完成后再把结果交还给外层规划器。

这个子系统有几个比较现实的技术点:分辨率适配、元素定位、界面变化检测。Hermes 在这块投入了不少功夫,比如在做动作前会对截图做一次预处理,把大图缩放到模型适用的分辨率;执行点击后不立刻进入下一步,而是等一小段时间让页面渲染稳定,再截屏对比。这样能显著减少因为页面动画导致的状态误判。CUA 子系统的配置在桌面版里需要单独开启,并且建议配一个独立的模型端点,因为它的输入输出模式(截图+动作)和普通文本聊天差异较大。

3. 执行路径地图:一次请求如何完整走完全程

3.1 主链路四阶段的数据流转

理解了单个子系统之后,就可以把它们串成一条完整的执行路径了。我用一个真实场景走一遍:假设用户输入“帮我看看这个文件夹里哪些图片体积最大,超过 5MB 的压缩一下”。这句话进入 Hermes 后,差不多要经历四个阶段。

第一阶段是入口路由。系统把这条消息识别为“需要文件系统操作的复杂任务”,生成 AgentRequest,并初始化一个会话上下文对象。第二阶段是规划。规划器拿到 AgentRequest 后,把目标拆成“遍历文件夹→获取图片尺寸与体积→过滤超过 5MB 的项→调用压缩工具→校验结果”这几步,并输出 TaskPlan。值得一说的是,这一步可能不会要求用户确认,因为任务里没有高危操作,属于默认可执行的范围。第三阶段是执行。执行子系统开始逐个落实步骤,从调用文件遍历函数、读元信息,到调用图像压缩工具,每一步都经过安全子系统的权限核验,并把 ToolResult 反馈回上下文,规划器看到结果后再决定下一步动作。第四阶段是总结回复。所有步骤完成后,规划器把执行摘要交给回复生成模块,生成一段用户可读的结果说明。

这个主链路的每一阶段都有专门的输入输出产物。我整理了一个表格方便对照:

阶段入口产物负责子系统输出产物常见失败点
意图识别用户原始文本入口路由AgentRequest意图判断含糊,走了错误分支
任务规划AgentRequest规划子系统TaskPlan步骤过多或依赖关系错误
工具执行TaskPlan 步骤工具执行 + 安全ToolResult参数校验失败、超时、权限拒绝
结果回复执行摘要回复生成模块用户可读文本摘要过于冗长或丢失关键信息

补充一下,第四个阶段在架构上常常被忽略,很多 Agent 框架直接把最后一步 ToolResult 拼回上下文然后让模型自由输出,结果模型会唠叨一大堆执行细节。懂架构的开发者会让规划器在任务完成后生成一份精简摘要,这份摘要才是给最终回复用的,原始执行轨迹留在日志里即可。我说通俗一点:执行路径上的信息像施工工地上的一堆材料,不能全摆给用户看,得拿出去装修过的东西。

3.2 两条重要旁路:人工确认与错误回退

完整的地图不能只画主链路,还要标出旁路。我调试 Hermes 时踩过最多的坑,就是只沿着主链路查问题,忽略了旁路分支。

第一条旁路是人工确认。当规划器想执行的工具命中“需确认”等级时,执行路径会在工具调用前暂停,进入 Confirmation Desk 状态。系统会把将要执行的命令、影响范围和原因以可读形式展示给用户,等待 yes/skip 答复。这个暂停不是系统故障,它是有意的控制点。如果你在日志里看到路径走到一半突然没有后续,第一反应应该是检查是否有安全确认悬在那里,而不是怀疑程序卡死。很多“看起来死机”的情况,其实只是程序在等一个用户答复。

第二条旁路是错误回退。当工具调用失败时,Hermes 不会立即终止整个任务,而是会把错误信息回传给规划器,由规划器决定下一步。回退策略通常有三种:换参数重试、换另一个工具、放弃当前分支并给用户说明。这里有一个架构上非常微妙的点:错误信息也是一种上下文,但它和正常 ToolResult 的格式必须有明显区分,否则模型可能把失败当成功,直接说“搞定了”但实际啥都没做。Hermes 在 ToolResult 里强制要求携带 success 布尔位,这个字段在提示词里会被反复强调,目的就是把“模型容易含糊应对”的地方拧紧。

3.3 上下文串场机制:执行路径上所有模块共用的信息载体

执行路径上所有子系统,并不是靠全局变量互相传数据的。它们通过一个统一的会话上下文对象串接。这个对象里最关键的三块内容是:原始用户请求、任务计划、工具执行记录。我把它们类比成工程档案袋:用户请求是合同,任务计划是施工图纸,工具执行记录是监理日志,三者拼起来才能还原全部上下文。

在模型端,这些上下文会被组织成 system、user、tool 三类消息序列。系统提示词里装的是 Agent 人设、工具说明和规范约束,用户消息里是当前这一轮的实际请求,tool 消息记录的是每次调用的输入输出。这个顺序不是随意排的,它直接决定模型注意力如何分配。我发现一种很实战的组装技巧:每次工具调用之后,不把原始输出原封不动放回去,而是先截断到合理长度,再用格式化的方式压缩,因为工具返回的长文本很容易把窗口占满,导致后面步骤的推理质量下降。这个动作在架构上没有专门的子系统,通常由执行子系统在返回 ToolResult 前顺手处理好。

上下文串场机制还解释了另一个问题:为什么 Hermes 的子系统很多,但代码没有乱成一团。因为所有交互都是通过上下文对象传递标准化的 Request 和 Result 结构,各模块不需要感知彼此内部的实现。可以说,上下文对象就是这条执行路径的地基,子系统相当于盖在上面的房间,每个房间彼此隔离但共用同一套水电管线。

4. 版本演进与部署形态对执行路径的影响

4.1 v0.21 bot mode 如何改写主链路

Hermes v0.21 里一个较大的变化是 bot mode,它和交互模式最大的区别在于执行路径的起点和终点。交互模式里,入口路由子系统要维护多轮对话的分支状态,记忆子系统需要承担持续的会话跟踪;而 bot mode 是单次执行,典型场景是“运行一个命令,Agent 自动完成目标,然后退出”。

从架构视角来看,bot mode 其实是把主链路截短了:没有多轮对话分支,不需要长期记忆召回,入口路由拿到命令行参数后直接进入规划阶段,任务结束后直接输出结果到标准输出。这个设计让我想到一个架构原则:不是所有部署形态都要包含所有子系统,执行路径应该是可裁剪的。v0.21 里如果你开了 bot mode,相当于在配置里关掉了对话管理相关的子模块,其他子系统保持不动。

这种“路径可裁剪”带来一个特别实际的好处:排查问题更简单。交互模式跑出问题时,你不太确定是对话历史导致的还是规划逻辑导致的;bot mode 里没有对话历史变量,问题范围瞬间缩小到“规划+执行+工具”三件套。我建议所有做 Agent 调试的人,遇到诡异行为先尝试在 bot mode 复现一次。如果 bot mode 能复现,说明问题出在任务链路本身;如果 bot mode 复现不了,那就是多轮上下文惹的祸。这个方法我用了很久,命中率极高。

4.2 桌面版配置与子系统裁剪思路

Windows 桌面版是 Hermes 比较有代表性的部署形态,它在模块化单体里可以灵活裁剪。基础配置一般包括模型 API 的接入配置、本地数据存储位置、日志级别;如果要用 CUA,还需要单独开启相关能力,并配置浏览器或桌面环境的运行权限。

子系统的裁剪原则可以这样理解:用不到的子系统就别加载,加载本身会引入额外的上下文空间和安全风险。例如,如果你的使用场景只是做文件整理和文本处理,完全可以关闭 CUA 相关模块,这样入口路由不会对桌面操作类请求做复杂意图建模,规划器的工具候选列表也更干净。反过来说,如果你要用 Agent 操作网页,那么 CUA 模块必备,并且建议给它单独配置一个延迟更低的模型端点,因为 CUA 链路要频繁截屏和推理,响应速度直接影响操作效果。

这里延伸回答一个很多人问过的问题:Hermes 为什么不用微服务架构?关键原因是它的典型运行场景是本地桌面或单一服务器,传统微服务带来的网络开销、分布式事务和服务发现复杂度,在这个场景里都是负资产。Hermes 选择的是模块化单体,模块之间通过接口和事件通信,逻辑边界和执行路径的清晰度已经足够。只有当你确定要把它改造成多用户 SaaS 服务,才值得把记忆、规划和工具执行拆成独立服务。这个演进路径和很多老牌项目的路径是一样的:先模块化单体把业务跑通,再根据真实瓶颈做分布式拆分,而不是开局就铺一个大而全的微服务架子。这种克制我觉得挺值得学习。

5. 实操中常见的路径断点与排查实录

5.1 四个高频异常场景复盘

先说规划死循环。这是我遇到最多的问题,现象是 Agent 在同一类操作上反复进出执行子系统,日志里能看到相似的工具调用一遍遍出现,但每次参数都差一点点。排查思路很简单:先看 max_steps 是否设置,再看每次 ToolResult 反馈给规划器的错误信息是不是足够具体。大部分死循环是因为错误信息太模糊,模型不知道错在哪,只能换几个词再试。解决办法是把工具返回的错误结构化,区分“格式错误”“权限不足”“资源不存在”三类,规划器就能更准确调整策略。

其次是上下文溢出。这个在高版本 Hermes 里有所缓解,但在长时间任务中仍然会踩到。现象是任务执行到后半段,模型开始记不住前面的步骤,重复做已经完成的工作。排查方向是看记忆子系统的压缩策略有没有生效,尤其是 ToolResult 过大导致的单条消息膨胀。我的建议很朴实:能在工具层做截断的,就不要把完整输出留给模型。例如文件读取工具返回前先按行数截断,而不是把整个文件内容塞进上下文。

第三个是工具超时。这个往往容易被误认为 Agent 模型出了问题,但实际是执行子系统配给某个工具的 timeout 不够。网络请求类工具和本地计算类工具对时延的容忍度完全不同,我之前遇到过一个网络 API 调用偶尔要 20 秒,而默认超时只有 10 秒,导致 Agent 误以为工具不可用,频繁切换其他方案。解决方案是给慢工具单独调高超时,并在工具描述里注明它可能较慢。

第四个是 CUA 任务卡住。现象是 Agent 一直停留在“观察界面”阶段,没有动作输出。大多不是模型没想好动作,而是截图返回的图像分辨率或格式不合理,导致视觉模型无法稳定识别界面内容。建议先检查 CUA 子系统的截屏分辨率设置,把它调到模型训练时常用的尺寸;如果页面有弹窗或动画,也容易卡观察循环,这时可以把多次截图的差异集中对比后再决定动作。

5.2 问题排查速查表与方法论

我把这些经验整理成一个速查表,当你遇到 Hermes 异常时,先按表定位可能出问题的子系统,再去看那块代码,效率会高很多。

现象优先排查的子系统核心检查点常见解法
任务执行几步后停住安全子系统是否有 pending 的人工确认查看安全日志,处理确认请求
反复调用同一工具规划子系统max_steps 是否设够、错误信息是否详细提高步数上限,结构化工具错误
上下文被截断或模型健忘记忆子系统压缩触发阈值、ToolResult 长度工具层截断输出,调低压缩阈值
工具一直未响应执行子系统该工具 timeout 配置、依赖服务状态单独调高超时,检查健康检查
CUA 一直不动CUA 子系统截图分辨率、页面元素可见性调分辨率,等待渲染稳定后再截屏
回复内容偏离原始目标上下文串场系统提示词里的目标是否被压缩掉压缩时保留原始用户请求

排查方法论上,我个人的核心建议是“先断路径,再猜代码”。遇到 bug,不要上来就深入某个子系统的内部实现,先确定路径断在哪一跳。要看日志就盯着阶段切换点看:入口路由是否输出 AgentRequest、规划器是否输出 TaskPlan、执行器是否输出 ToolResult、安全子系统是否留下 Permission 记录。这四个检查点一围,问题范围能缩小到原来的十分之一。这一步听起来特别简单,但很多人在实际调试时会因为着急而跳过,直接在工具函数里打日志找问题。花五分钟确认路径走到哪儿断了,比花半小时猜代码有用得多。

最后分享一点我的实践经验

从我实际部署 Hermes v0.21 的经验来看,最有效的上手方式不是啃完所有源码再动手,而是先把执行路径的主干描出来,然后找一条最简单的任务跑通,再逐步叠加工具和模块。我也犯过一个典型的错误:一开始就打开了 CUA 和长记忆机制,结果一个简单的文件重命名任务都被我搞出上下文溢出来。后来我把 CUA 关掉、上下文压缩阈值调低,整个世界都清净了。所以我特别建议你,在配置里尽量做到“最小加载”,也就是只用当前场景需要的子系统,等确实遇到场景需求了再加回来。工具链多了并不会让 Agent 变聪明,只会让它更容易踩到无关的东西。在本地 Agent 架构上,大多数“它为什么不听话”的根源,其实都是上下文里的干扰项太多。这条经验希望对你有用。

返回列表