企业官网建设流程全解析

上个月我在梳理内部Agent服务的线上问题，顺便把Hermes Agent的源码翻出来重新读了一遍。说实话，读框架源码远比写业务代码更能让人清醒：真正让一个Agent从“玩具对话”变成“可用服务”的，从来不是底层模型本身有多强，而是会话、工具、MCP、记忆这四个基础能力的工程化程度。

这篇文章就是我对着Hermes Agent这四个模块做完整拆解之后的一份整理。我会把每个模块“为什么要这样设计”的原理、实际使用中会踩的坑、以及我验证过的配置方式都写出来。无论你是刚接触Agent开发、还在纠结框架选型，还是已经在业务里接入Agent、想优化上下文管理和工具调用策略，这篇都值得读一读。读完之后你会发现，Agent的瓶颈往往不在模型能力，而在工程细节。

1. 为什么我把会话、工具、MCP、记忆看成Agent的“四个器官”

先解释一下我的分析框架。一个Agent应用要跑起来，表面上只是“用户发消息、模型回消息”，但真实链路远不止这么简单：用户输入先经过会话层，会话层负责拼接系统提示、历史消息、工具定义和记忆片段，组成一次完整的请求；模型拿到请求后，要么直接生成回答，要么决定“我需要调用某个工具”；工具调用的落地，要么走框架内置的工具注册表，要么走MCP协议接入的外部能力；工具执行完之后，结果要回填给模型，模型再基于新信息继续推理；与此同时，对话中值得长期保留的内容，会被记忆模块抽取、存储，供未来会话使用。

这四件事在Hermes Agent里是四个独立的模块，但运行时又是紧密咬合的。我在代码里把这四块单独拎出来逐一核对，越看越觉得，它们更像是一个生物体的四个器官：会话是感知层，负责接收和梳理信息；工具是行动层，负责对外部世界产生影响；MCP是连接层，负责让Agent能触碰外部生态；记忆是经验层，负责把历史沉淀下来，让下一次对话不再从零开始。缺少任何一块，Agent都只能是“能聊天但干不了活”的演示品。

1.1 一个Agent请求背后到底发生了什么

为了让这个概念更具体，我举个实际的服务调用例子。假设用户问：“帮我查一下上周的订单异常率，并整理成小结。”这条请求到达Hermes Agent之后，会话模块会取出该用户的会话历史，可能包括过去的查询记录、用户偏好的汇报方式；然后把工具定义列表（比如query_order_metrics、generate_summary）和长期记忆中的相关片段一起拼进上下文，交给模型。

模型读完输入，会先判断：我需要先调用query_order_metrics拿数据，再调用generate_summary整理小结。于是模型输出一个工具调用请求，框架解析后执行对应函数，拿到结构化结果，再转成文本回填给模型。模型看到真实数据后，生成最终的小结。小结生成完，会话模块把整个过程写入历史，记忆模块抽取“这位用户偏好按异常率变化趋势来汇报”这条信息，存入长期记忆。整个过程发生在一两秒内，但每一环都有独立的工程逻辑。

1.2 框架层设计为什么比“裸调模型API”更重要

很多初学者会问：我直接调模型的接口，多轮对话就自己拼消息数组，调用工具就自己解析返回体，为什么还要引入一套框架？这个问题我刚开始也有过。但随着会话数量增加、工具数量增加，问题会迅速暴露：不同用户的消息串在一起怎么办？工具定义太长把上下文撑爆怎么办？工具执行失败后怎么告诉模型？用户上一周说过的一句话，这周还应该被记住吗？

这些问题没有标准答案，但必须有一整套约定。Hermes Agent的价值不在于它发明了什么神秘技术，而在于把这四个问题的处理方式固化为可复用的模块。下面的章节，我按会话、工具、MCP、记忆的顺序逐层拆开讲。

2. 会话模块：上下文不是“聊天记录的堆叠”

会话管理是最容易被低估的模块。很多人以为会话就是把消息存起来、下次接着发，但实际聊过一轮之后你就会发现，上下文的结构、长度、生命周期，直接影响模型的表现和接口成本。我在Hermes Agent里看到的会话设计，远比“存个数组”复杂得多。

2.1 会话生命周期与会话隔离

先说生命周期。Hermes Agent中每个会话都有一个唯一ID，一般用session_id表示。一次业务交互从session.create()开始，之后每次用户消息通过session.append()写入，结束时可以显式关闭，也可以由会话空闲超时机制回收。这个生命周期管理的核心目的，是保证上下文只属于同一个业务逻辑单元。

会话隔离是个很容易踩的坑。如果所有用户共用同一个会话ID，或者一个用户的所有任务都塞进同一个会话，就会出现严重的上下文串味。举个我实际遇到的案例：某内部工具最初只设计了一个全局会话，A用户查完订单，B用户接着问“我刚才查的订单号是多少”，模型居然从历史里翻出了A用户的订单号。这个事故直接促使我们把会话维度细化为“用户ID + 任务类型 + 会话ID”三级结构。简单说，每个用户的任务必须各自独立会话，不能贪图方便复用。

2.2 上下文窗口的token预算分配

上下文窗口有限，这是所有Agent应用绕不开的物理约束。Hermes Agent的做法是把一次请求的token预算明确切分成几个部分：系统提示、工具定义、长期记忆召回片段、近期会话历史、当前用户的输入。每个部分预留多少，直接影响模型的发挥空间。

我自己的经验值是：系统提示占5%左右，工具定义占15%到25%，长期记忆召回片段占10%，当前输入占10%，剩下的全部留给最近对话历史。当工具数量很多时，工具定义部分经常会超预算，这时候就需要动态裁剪——只暴露当前任务可能用到的工具，而不是把注册表全量塞进去。这一点后面的工具模块会展开讲。

上下文预算不只是“要不要截断”的问题，还涉及压缩策略。Hermes Agent在历史超过窗口限制时，会触发两种手段：滑动窗口和摘要压缩。滑动窗口简单直接，只保留最近N条消息，适合快速场景；摘要压缩是把较早的对话用一条模型生成的摘要替代，适合需要跨长时间段追踪来龙去脉的场景。两者可以叠加使用，但要注意：摘要压缩本身是一次模型调用，会带来额外延迟，不能每条消息都触发。

2.3 会话持久化与消息结构

会话不能只活在内存里，服务一重启就什么都没了。Hermes Agent把消息结构化之后写入持久化存储，每条消息会记录角色（system、user、assistant、tool）、内容、时间戳、关联的工具调用ID等字段。这样设计是为了排查问题时能还原完整的调用链。

我在实际项目中用到的消息存储结构大概是这样的：

# 示意：会话消息的字段设计 message = { "session_id": "sess_8f3a...", "role": "assistant", "content": "已为您整理本周订单异常率，详见小结。", "tool_calls": [ { "id": "call_01", "name": "query_order_metrics", "arguments": {"date_range": "2025-05-12~2025-05-18"} } ], "created_at": "2025-05-19T10:24:00Z" }

存储介质的选择看场景：单机开发可以用本地文件或SQLite级别的东西，线上多实例部署一般用关系型数据库或键值存储。重点不是选哪个数据库，而是消息结构必须稳定，因为后续的历史截断、摘要生成、审计追溯都依赖这套结构。很多项目后期改消息结构，代价极大，最好一开始就设计到位。

3. 工具调用：从模型决策到函数执行，中间隔着哪些工程细节

工具调用是Agent从“嘴炮”变成“实干”的关键。业界早就提供了函数调用能力，也就是让模型输出一个结构化指令，说明“我要调用哪个函数、参数是什么”，然后由程序去真正执行。但把这条链路跑稳，细节比想象中多得多。

3.1 工具注册与Schema设计

在Hermes Agent里，每个工具都需要注册成一份结构化描述。注册信息包括三部分：工具名称、工具描述、参数Schema。参数Schema通常采用JSON Schema格式，因为模型对这份格式的理解最稳定。工具不是“写个函数就行”，它的名称和描述直接影响模型的选择准确率。

我拿一个订单查询工具举例，注册Schema长这样：

{ "name": "get_order_info", "description": "根据订单号查询订单状态与物流信息", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，例如 SO-2025-0001" } }, "required": ["order_id"] } }

这里有个经验：描述要写“这个工具是干什么的、什么时候用它”，不要写实现细节。描述不是越详细越好，过长的描述会挤占上下文，模糊模型的选择判断。我见过一个工具描述写了三百字，结果模型在多个相似工具之间反复选错，把描述精简到一两句话之后准确率明显上升。

3.2 从模型输出工具调用到执行完成的完整链路

当模型决定调用工具时，返回的不是真正执行结果，而是一个调用请求。Hermes Agent的链路是：解析模型输出的工具调用请求 → 按Schema校验参数 → 执行对应的函数 → 把返回值转成文本 → 作为tool角色消息回填给模型 → 模型继续推理。

参数校验是最容易被省略但最不能省略的一步。模型偶尔会输出类型不正确的参数，比如数字写成了字符串、必填字段缺失。不校验就执行，轻则函数报错，重则产生脏数据。我在项目里强制规定：所有工具执行前必须过一遍Schema校验，校验失败就直接返回一个“参数错误”的结果给模型，让它自己纠正。模型对错误信息非常敏感，给它明确的错误提示，它会自动修正参数重新发起调用。

工具结果回填也有讲究。我踩过的坑是，最初把工具返回的原始JSON整个塞回给模型，结果模型被里面大量无关字段干扰，反而答非所问。后来我总结出一个原则：工具返回值在执行函数时保留完整结构，但回填给模型的必须是为模型“消化过”的文本。比如查询订单返回了一个包含几十个字段的JSON，回填时可以提炼成“订单SO-2025-0001状态为已发货，预计到达时间5月20日”，这种文本对模型最友好。

3.3 错误处理、超时与重试策略

工具执行一定会出错，这是工程常态。问题是出错之后怎么办。我在Hermes Agent里实践下来的策略是：所有工具调用都设置超时上限，比如5秒；超时后不等结果，直接返回“调用超时”的错误信息给模型，让模型选择重试、换工具还是放弃并向用户解释。

错误信息要“面向模型”编写。模型不会看堆栈，它需要的是可行动的错误描述，比如“查询订单号不存在，请检查订单号是否正确”，而不是“NullPointerException at line 42”。面向模型写错误信息这一点，很多开发者在初期都会忽略，但它对最终用户体验的影响非常大。模型只有理解了错误，才能给出符合用户预期的补救方案。

3.4 工具数量增长后的路由难题

当工具注册表里的工具越来越多，模型选错工具的概率会迅速上升。这不是模型变笨了，而是信息过载了。想象一下，你给模型塞了50个工具定义，每个都长得相似，它要从中选出一个合适的，难度自然不小。

我采用的解决思路是工具分级暴露：根据会话的意图预处理结果，先判断当前任务可能涉及哪个领域，只把该领域的工具定义放进请求。比如用户问的是订单，就只暴露订单相关的五个工具，而不是把物流、售后、库存的全都塞进去。Hermes Agent在这块提供了类似的路由机制，核心就是“宁可少给，不要多给”。工具定义数量控制在十个以内，模型的选择准确率会显著高于全量暴露。

4. MCP：把工具接入从“私养接口”变成“标准插座”

如果说工具模块解决的是“Agent如何调用一个已注册的函数”，那MCP解决的是“Agent如何标准化地接入外部系统”，也就是Model Context Protocol，模型上下文协议。这是我最近重点研究的部分，因为它的设计思路能解决Agent生态最痛的集成问题。

4.1 MCP到底解决了什么问题

在MCP出现之前，每接入一个外部系统，Agent都要写一套定制适配逻辑。比如要连某个协作软件，你需要搞清楚它的接口文档、鉴权方式、数据格式，开发量跟写一个SDK差不多；再接第二个系统，又要重复一遍。这种模式在工具少的时候还能忍，工具一多，适配工作就会成为维护噩梦。

MCP的做法是定义一套通用协议：外部系统通过实现一个MCP服务器，把自己能力暴露出来；Agent作为MCP客户端，通过标准方式发现这些能力、发起调用。只要对方实现了MCP，Agent这边就只需要一套客户端代码，后面所有系统都按同一个标准接入。用生活类比来解释：以前每个家电品牌都有自己的插座规格，你必须给每个电器准备一个转接头；MCP就是大家统一用同一个国标插座，电器只管按规格做好插头就行。

4.2 MCP的三类能力原语

MCP定义了三个核心能力原语，初学者很容易混淆：工具、资源、提示。工具代表可执行的动作，比如“创建任务”“发送消息”；资源代表可读的数据，比如“项目文档”“配置信息”；提示代表可复用的模板化指令，比如“按周报格式汇总项目进展”。

理解这三者的区别很重要。工具是会改变系统状态的操作，调了就会产生副作用；资源是只读的信息源，主要用来补充上下文；提示则是引导模型更好完成某类任务的文本模板。在Hermes Agent里挂载一个MCP服务器之后，这三个原语会被分别映射到不同的处理逻辑：工具走工具调用链，资源由按需读取，提示则注入到系统提示词中。

4.3 在Hermes Agent中挂载MCP服务器的实操

挂载MCP服务器的配置方式，比写定制SDK简单很多。在Hermes Agent的配置文件中，声明服务地址、传输方式和超时时间就可以了。下面是一个典型的配置片段：

mcp: servers: wiki-server: url: "mcp://localhost:9100" transport: "streamable" timeout: 8

服务启动后，Hermes Agent会与MCP服务器握手，自动拉取它的工具列表、资源列表和提示模板列表。拉取到的工具会被转成标准的工具Schema，注册进工具模块，之后就跟普通工具一样参与模型调用。这一步对开发者来说几乎是无感的——你不需要关心远程系统内部怎么实现，只需要像使用本地工具一样使用MCP暴露的能力。

4.4 MCP接入的边界与安全

MCP降低了接入成本，但同时也放大了安全风险。一个MCP服务器可能暴露几十个工具，如果这些工具都无条件被模型调用，后果难料。我在生产环境里制定了几条规则：MCP服务器接入前必须声明各自工具的执行权限；Agent对MCP工具执行鉴权映射，不能使用“全部放开”模式；所有MCP调用记录审计日志，保留工具名称、参数、调用时间。安全不是协议本身能解决的，协议只是铺路，路上的交通规则还得自己定。

5. 记忆分层：短期、长期与显式记忆的配合方式

记忆是Agent能力升级的关键，也是市面上讨论最多、误会最多的地方。我在很长一段时间里都以为“记忆就是把对话历史存下来”，直到处理跨会话的场景才意识到，记忆不是聊天记录的堆叠，而是分层设计和主动管理。

5.1 短期记忆与会话历史的边界

短期记忆本质就是会话模块里的上下文窗口，它负责保存“当前任务过程中需要临时引用的信息”。比如用户刚才提到“订单号SO-2025-0001”，短时间里模型需要记得这个订单号，才能回答后续问题。短期记忆由会话管理控制，窗口一滚动，这些信息就被自然丢弃，不需要单独持久化。

需要强调的是，短期记忆和长期记忆不能互相替代。如果把所有短期信息都长期保存，记忆库会迅速膨胀，检索效率下降，模型还可能被过期信息误导。我一开始就是“什么都记”，结果记忆库越来越脏，召回的内容经常与当前任务无关。后来采用的策略是：会话历史归会话模块管，记忆模块只负责抽取值得跨会话保留的高价值信息。

5.2 长期记忆：抽取、写入与检索

长期记忆的写入链路，是Hermes Agent里最考验设计的地方。对话结束后，记忆模块会从消息中抽取“可沉淀的结论”。抽取的方式通常是规则加模型判断：先通过关键词、句法规则找出候选片段，再用模型打分，只有置信度超过阈值的片段才允许写入。这一步相当于“信息过滤”，避免把垃圾信息存进长期记忆。在Hermes Agent中，每个写入的记忆项会附带命名空间、时间戳、来源会话ID等元数据，并向量化后存入向量库。检索时，系统先把当前问题向量化，再从向量库中召回相似片段。但召回不等于直接使用——一定要加上相关性阈值，低于阈值的不予信任。

我在项目里写过一个典型的记忆写入策略，大致逻辑如下：

# 示意：记忆抽取与写入策略 messages = session.get_messages(session_id) candidates = memory.extract_candidate_facts(messages) # 规则提取候选事实 for fact in candidates: score = memory.judge_importance(fact) # 模型打分：是否值得长期保存 if score > 0.85 and fact.is_duplicate(existing_memory) is False: memory.store( content=fact.text, namespace="user_preferences", source_session=session_id, created_at=now() )

这套策略看起简单，实操里要注意两个点。第一是重复判断，同一个用户偏好可能会在多轮对话中被反复提到，如果没有去重，记忆库会堆满冗余内容。第二是命名空间隔离，多用户场景下，如果不按用户或团队隔离记忆，会出现A用户的信息被B用户召回的情况，这后果很严重，甚至比会话串味更可怕。

5.3 显式记忆与用户可控性

除了模型自动抽取的隐式记忆，Hermes Agent还支持显式记忆：用户主动说“记住我每周三要做汇报”，或者调用记忆管理工具主动添加一条记录。显式记忆比自动抽取的记忆优先级更高，因为它表达了用户的明确意图，不会有额外地误判。

显式记忆同时意味着用户需要遗忘能力。一个健康的记忆系统必须有“删除记忆”和“更新记忆”的接口。我在实际使用中遇到过这样的场景：用户上一季度偏好看表格汇报，这一季度改成看图，如果系统只有写入没有更新，模型就会一直按旧偏好输出。正确的做法是，当新的记忆与旧记忆冲突时，要么覆盖旧记忆，要么把旧记忆标记为过期，确保模型不会同时收到相互矛盾的偏好指示。

5.4 记忆召回与临时性信息的过滤

最后一个记忆使用细节是召回时间过滤。向量检索擅长找“语义相似”，但它不擅长判断“时间有效性”。比如用户问“本周任务”，系统可能从记忆库召回一条上周的任务总结，模型如果没有时间概念，就可能把上周数据当成本周的，闹出笑话。

我在Hermes Agent的配置里，给所有记忆项都加了时间元数据，召回时除了相关性排序，还按任务需求做时间窗口过滤。比如本周类问题只召回一周内的记忆，长期偏好类问题则不限时间。这个看似简单的过滤，在不经意间解决了很多RAG系统最大的输出问题：信息过时。

6. 实测复盘：用Hermes Agent搭一个带工具和记忆的周报助手Demo

讲完理论，我放一个实测的完整案例。最近我内部搭了个周报助手Demo，规模不大，但覆盖了会话、工具、MCP、记忆四个模块的全部联动。这个Demo的运行数据对我理解框架设计帮助很大。

6.1 Demo的需求与架构

这个Demo面向一个小型团队，要做的事情很简单：用户说“帮我整理本周周报”，Agent自动读取任务列表、汇总本周进展，并按用户偏好的格式输出周报。架构上，会话模块负责多用户隔离；工具模块注册了两个工具，一个读取任务数据，一个汇总统计结果；MCP接入了一个知识库服务器，里面存有团队名称、成员分工等可供参考的静态信息；记忆模块负责记录用户偏好的周报输出风格。

这个Demo最值得观察的点，是同一个请求“帮我整理本周周报”在第一次调用和第二次调用之间的差别。

6.2 关键配置与调用链路

配置方面，工具注册、MCP挂载、记忆命名空间这三块各占一段配置。简化后的MCP挂载配置与前面类似。工具注册的示意如下：

{ "name": "get_week_tasks", "description": "获取指定时间段内已标记完成的任务列表", "parameters": { "type": "object", "properties": { "start_date": {"type": "string", "description": "开始日期，格式YYYY-MM-DD"}, "end_date": {"type": "string", "description": "结束日期，格式YYYY-MM-DD"} }, "required": ["start_date", "end_date"] } }

记忆命名空间设置为团队ID加用户ID，确保不同团队、不同用户的偏好不串味。调用时，Hermes Agent会先根据会话历史判断这是不是第一次交互，如果是，就只靠工具和MCP提供的信息工作；如果不是，则额外把记忆中的偏好片段注入上下文。

6.3 实测效果与调参记录

第一轮测试里，用户第一次说“帮我写周报”，模型先调用get_week_tasks读取任务，再调用知识库资源确认团队信息，输出了一份规规矩矩的周报。第二次同样的问题，记忆模块召回了用户偏好“按项目分组、并标注风险事项”，模型直接按这个格式输出，不仅更切合需要，调用轮次也少了一次。

但这个Demo在调试中也暴露了几个问题，值得逐个说一下。第一个问题是工具描述过长导致上下文膨胀。最初get_week_tasks的描述写得很详细，占用了不少token，我把描述精简为一句话后，上下文压力明显下降。第二个问题是记忆误召回，某个用户在一次对话中提到“上周任务延期”，这条信息被自动记入长期记忆，导致后面询问本周任务时，模型误把延期事件当作本周内容。解决方案就是我前面说的，对“本周类”问题做时间窗口过滤，只召回七天内的记忆。第三个问题是历史消息不截断带来的延迟上升，会话越长，每次请求发送的消息越多，响应延迟从1秒涨到了3秒以上。后来配置了滑动窗口加摘要压缩，延迟回到1.5秒左右。这组实测数据再次印证：Agent框架四个模块的配置深度，决定了应用的可用性上限。

7. 最后还想单独讲的几个工程细节

在收尾之前，我要额外说几个不常被写在文档里、但实际运维中遇到的工程细节。它们不属于某一个模块，却影响着四者的协同效果。

首先是工具循环上限。模型可能因为工具返回结果不理想而反复重试，形成死循环。我在Hermes Agent中把单次用户请求的工具调用轮数上限设为4，超过后强制结束循环，模型必须基于已有信息作答。这个上限既保证了多轮工具协作的可能性，又避免了一次请求消耗过多资源。

其次是工具结果截断。工具返回给模型的内容不能无限长，如果某个工具返回了很长的数据，我会截取前2000字左右，并在末尾补充“结果过长，已截断”。让模型知道自己看到的是部分信息，而不是让它误以为看到了全部，这一点很重要，能避免模型基于不完整数据做出错误判断。

然后是幂等控制。部分工具有明显的副作用，比如发送通知、扣减余额、创建任务，如果因为超时重试而被调用两次，后果很严重。我给这类工具统一增加了request_id参数，同一请求ID执行多次只生效一次。这个机制和会话管理、工具执行、记忆写入都能配合使用，属于高性价比的防御设计。

最后是记忆权限问题。记忆存储的往往是用户偏好、工作内容等敏感性较强的信息。在多用户、多团队场景下，记忆的读写必须严格按命名空间隔离，并且提供用户主动查询、导出、删除记忆的接口。一个小建议：在正式上线前，把“记忆清理”作为运维流程的一部分，定期归档过期记忆，控制记忆库规模，而不是让它无限膨胀。这一点很多项目初期意识不到，等记忆库大到检索卡顿时再来处理，代价就大了。

这些细节单独看都不起眼，但它们恰恰是我在实际项目里花时间最多的地方。Agent能不能稳定跑在业务线上，靠的不是模型的一两次高光表现，而是这些边缘地带是否处理得够细。