企业官网建设流程全解析

Agent 这个赛道，过去一年最大的变化不是模型变强了，而是大家终于承认：真正难的不是让模型会说话，而是让它能稳定地干活。Orkas 这次底层重构，本质上就是在回答一个被很多人绕过去的问题——当 Agent 从 Demo 走向真实业务，原来那套"能跑就行"的地基还撑不撑得住。我前后跟过几个 Agent 项目，从最早的单轮工具调用，到后来的多智能体编排，踩过的坑基本都集中在同一类地方：模型调用链路一长就失控，工具一多就互相打架，记忆一写就脏，并发一上来就雪崩。Orkas 这次重写，把这些散落的问题收拢到一套统一的地基上，值得拆开讲讲它到底动了哪些地方，以及这些改动对正在做 Agent 开发的人意味着什么。

1. 为什么"能跑通"的 Agent 架构迟早要推倒重来

1.1 Demo 阶段被掩盖的三个结构性缺陷

大部分 Agent 项目的第一版都是这么长出来的：一个主循环，里面塞一个模型调用，模型返回工具调用就执行，执行完把结果拼回上下文，再调一次模型，直到模型不再要工具为止。这套东西在演示阶段非常好用，因为演示的路径是线性的、可控的、没有并发的。但只要往真实场景推一步，三个缺陷就会同时暴露。

第一个缺陷是控制流和数据流混在一起。主循环既负责决定下一步调哪个模型，又负责维护上下文，还负责执行工具，三件事耦合在一个函数里。结果是任何一处要改，整条链路都得动。你想加个重试，得改循环；你想换个记忆策略，得改循环；你想加个中间审核节点，还是得改循环。这种耦合在单智能体时还能忍，一旦引入多智能体编排，主循环就变成了一个谁都不敢碰的黑盒。

第二个缺陷是状态没有明确的归属。上下文、工具调用历史、中间结果、用户会话，这些东西往往散落在几个字典和列表里，靠约定俗成的命名维持秩序。短期记忆和长期记忆的边界模糊，working memory 和持久化存储之间没有清晰的转换点。等到需要做记忆压缩、需要做会话恢复、需要做多轮任务续跑的时候，你会发现根本找不到一个权威的状态源。

第三个缺陷是错误处理是事后补的。模型调用超时、工具返回格式不对、工具执行抛异常、模型输出无法解析成结构化调用，这些在 Demo 里都是小概率事件，所以第一版通常只有一个 try-catch 兜底。但在生产环境里，这些是常态。没有分层的错误处理，一个工具的小抖动就能让整个任务链断掉，而且断在哪里、为什么断，日志里往往看不出来。

1.2 重构的触发点通常不是性能，而是可维护性

很多人以为底层重构是因为性能扛不住，其实更常见的触发点是改不动了。我见过一个项目，加一个新的工具类型要改四个文件，加一个新的模型供应商要动主循环，加一个记忆后端要重新梳理状态流转。这种时候性能可能还没到瓶颈，但团队的迭代速度已经归零了。

Orkas 这次重写，从描述上看，核心动机就是把"模型调用、多智能体编排、工具生态"这三块从耦合状态里拆出来，各自有清晰的边界和契约。这个判断是对的，因为 Agent 系统的复杂度增长不是线性的，而是随着工具数量、智能体数量、模型供应商数量的乘积增长的。只有把维度拆开，才能让每一块的复杂度独立可控。

1.3 一个判断标准：你的 Agent 地基该不该重写

给一个我自己用的判断标准，如果下面这几条你中了三条以上，那基本可以考虑重构了：

• 加一个新工具需要改动核心循环代码
• 换一个模型供应商需要动到编排逻辑
• 记忆的读写散落在多个模块，没有统一入口
• 并发场景下出现过状态串扰或上下文污染
• 错误处理靠全局兜底，无法定位到具体环节
• 多智能体之间的通信靠共享变量而不是显式消息

这几条本质上都指向同一个问题：边界不清。重构的目标不是把代码写得更漂亮，而是把边界划清楚，让每一块能独立演进、独立测试、独立替换。

2. Orkas 重构里最值得抄的一刀：模型调用层的抽象

2.1 把"调用模型"抽象成什么粒度才合适

模型调用层的抽象粒度是个很容易做错的地方。抽象得太细，比如把 HTTP 请求都包一层，那换供应商的时候还是要改一堆东西；抽象得太粗，比如直接暴露一个chat()方法，那不同供应商的能力差异（工具调用格式、流式输出、多模态输入、结构化输出）就没法统一处理。

比较合理的粒度是按能力抽象，而不是按接口抽象。也就是说，抽象出来的不是"发一个请求"，而是"完成一次带工具的对话""完成一次结构化输出""完成一次流式生成"。Orkas 在模型调用层的处理，从关键词"调用 pb 模型""claude code 调用 lmstudio 的本地模型"这些热搜词能看出来，社区里对本地模型和远程模型混用的需求很强烈，这就要求调用层必须能屏蔽掉底层是本地还是远程、是哪种协议这些差异。

具体来说，一个合格的模型调用抽象应该包含这几层：

• 能力声明层：每个模型适配器声明自己支持哪些能力，比如是否支持工具调用、是否支持并行工具调用、是否支持结构化输出、上下文窗口多大。
• 请求归一化层：把上层传下来的统一请求格式，转换成具体供应商需要的格式。
• 响应归一化层：把供应商返回的各种格式，统一成上层能消费的结构，尤其是工具调用部分。
• 错误归一化层：把超时、限流、内容过滤、格式错误这些不同供应商的不同错误码，映射成统一的错误类型。

这四层里，响应归一化层是最容易被低估的。不同模型返回工具调用的格式差异极大，有的用 JSON，有的用特定标记，有的把多个工具调用塞在一个字段里，有的分开返回。如果这一层没做好，上层的编排逻辑就得写一堆 if-else 来兼容，最后又变成耦合。

2.2 本地模型和远程模型混用时，抽象层要额外扛什么

本地模型和远程模型混用是现在很普遍的需求，尤其是做 Agent 开发时，有些敏感数据不想出本地，有些复杂推理又想用更强的远程模型。这种混用对调用层提出了额外要求。

第一是超时和重试策略要能按模型配置。本地模型可能响应慢但稳定，远程模型可能快但偶尔限流，用同一套超时参数是不合理的。调用层应该允许每个模型适配器自带超时、重试次数、退避策略。

第二是上下文窗口的差异要提前处理。本地小模型的上下文窗口可能只有几 K，远程模型可能有几百 K。如果上层不感知这个差异，直接把长上下文丢给本地模型，就会静默截断或者直接报错。调用层应该在请求归一化阶段就做窗口检查，超限时给出明确信号，而不是让底层去截断。

第三是流式输出的兼容。本地模型的流式实现和远程模型差别很大，有的按 token 流，有的按块流，有的干脆不支持流式。调用层要把这些统一成一种流式接口，让上层不用关心底层怎么流。

提示：做本地和远程混用时，建议在调用层加一个"模型能力探测"的启动检查，在服务启动时就把每个配置好的模型探一遍，确认它实际支持的能力和声明的是否一致。我踩过的坑是配置文件里写支持工具调用，实际那个本地模型版本根本不支持，结果运行到一半才报错。

2.3 调用层重构后，上层编排能简化到什么程度

调用层抽象做好之后，上层编排的代码会明显变薄。原来编排层要处理的各种供应商差异、格式转换、错误映射，全部下沉到调用层。编排层只需要关心：这一步要完成什么能力，用哪个模型，传什么上下文，拿到归一化后的结果继续往下走。

这种简化带来的直接好处是编排逻辑可以独立测试。你可以用一个假的模型适配器，返回预设的响应，来测试编排逻辑是否正确，而不需要真的去调模型。这在做多智能体编排时特别重要，因为多智能体的路径组合爆炸，靠真实调用测试根本测不过来。

3. 多智能体编排：从"共享状态"到"显式消息"

3.1 多智能体最容易踩的坑是隐式共享状态

多智能体编排这块，社区里讨论最多的框架和编排方式，但真正决定成败的往往不是用了哪个框架，而是智能体之间怎么通信。我见过最多的错误做法是让多个智能体共享一个上下文对象，谁都能往里写，谁都能从里读。这种做法在智能体数量少、逻辑简单时能跑，但很快就会出问题。

问题在于，共享状态让智能体之间的依赖变成了隐式的。A 智能体改了上下文里的某个字段，B 智能体读到了，但 B 不知道这个字段是谁改的、什么时候改的、为什么改的。一旦出现不符合预期的结果，你根本没法追溯。而且共享状态天然和并发冲突，两个智能体同时写同一个字段，结果取决于执行顺序，这种不确定性在生产环境里是灾难。

Orkas 这次重构把编排层独立出来，从方向上看应该是往显式消息传递走的。也就是说，智能体之间不共享状态，而是通过明确的消息来通信，每条消息有发送者、接收者、类型、载荷。这样做的好处是通信路径可追溯、可测试、可重放。

3.2 显式消息传递下，编排器该负责哪几件事

一旦采用显式消息传递，编排器的职责就清晰了。它不再是一个什么都管的主循环，而是一个消息路由器加调度器。具体来说，它要负责：

• 路由：根据消息类型和目标，决定把消息投递给哪个智能体。
• 调度：决定多个待处理消息的执行顺序，是串行、并行还是按依赖关系。
• 生命周期管理：智能体的创建、挂起、恢复、销毁。
• 失败处理：某个智能体处理消息失败时，是重试、转交给其他智能体，还是终止整个任务。
• 可观测性：记录每条消息的流转，方便事后追溯。

这几件事里，调度和失败处理的组合是最难的。比如一个任务需要三个智能体并行处理，其中两个成功一个失败，编排器要决定是等全部完成再统一处理失败，还是失败就立即中断。这个策略不能写死，应该可配置，因为不同业务对失败的容忍度不一样。

3.3 编排层和调用层解耦后，并发问题怎么处理

并发是 Agent 系统绕不过去的坎，热搜词里"ai agent 怎么扛并发"出现频率很高，说明这是普遍痛点。编排层和调用层解耦之后，并发处理可以分层来做。

在调用层，并发主要体现为对模型供应商的并发请求控制。每个供应商的限流策略不同，调用层应该为每个模型适配器维护独立的并发控制和限流器，避免一个供应商的限流影响到其他供应商。

在编排层，并发主要体现为多个智能体或任务的并行执行。这里的关键是状态隔离，每个并行执行单元要有自己独立的状态空间，不能共享可变状态。如果确实需要共享，也要通过消息传递或者显式的同步机制，而不是直接读写同一个对象。

在工具层，并发主要体现为工具执行的资源竞争。有些工具是有状态的，比如操作文件系统、操作数据库，这些工具在并发执行时需要加锁或者串行化。工具层应该能声明自己的并发特性，让编排层知道哪些工具可以并行调，哪些必须串行。

注意：并发问题最隐蔽的地方不是崩溃，而是结果错乱。系统不报错，但结果就是不对，而且时对时错。这种问题排查起来极其痛苦，所以状态隔离一定要在架构层面保证，不能靠开发者自觉。

4. 工具生态：让工具能被安全地发现、调用和隔离

4.1 工具注册和发现机制该怎么设计

工具生态是 Agent 能力的来源，但工具一多，管理就成了问题。我见过一个项目，工具注册靠一个全局字典，谁都能往里加，结果出现了重名工具、功能重叠工具、废弃但没删的工具，最后模型经常调错工具。

合理的工具注册机制应该包含这几件事：

• 唯一标识：每个工具有全局唯一的标识，不能靠名字，因为名字会冲突。
• 能力描述：工具要声明自己能做什么，这个描述要足够清晰，让模型能判断什么时候该用它。
• 参数模式：工具的参数要有明确的模式定义，包括类型、是否必填、取值范围，这样模型生成的调用才能被校验。
• 并发特性：工具要声明自己是否可并发、是否有状态、是否有副作用。
• 权限要求：工具要声明自己需要什么权限，这样在调用前可以做权限检查。

这几件事里，参数模式的定义是最影响实际效果的。参数模式定义得好，模型生成的调用就准确；定义得模糊，模型就会瞎猜。我的经验是，参数描述要写得像给一个新同事解释一样，把边界情况、默认值、单位都写清楚。

4.2 工具调用的安全边界：从参数校验到执行隔离

工具调用是 Agent 系统里风险最高的环节，因为工具往往有真实的副作用，比如写文件、发请求、改数据库。热搜词里"agent安全"是个高频话题，说明大家对这个问题的关注度在上升。

安全边界要分几层来做：

第一层是参数校验。模型生成的参数不能直接透传给工具，必须先按参数模式校验。类型不对、必填缺失、取值越界，都要在调用前拦下来，返回明确的错误让模型重新生成。

第二层是权限检查。每个工具声明自己需要的权限，调用前检查当前上下文是否有这些权限。比如一个删除文件的工具，需要文件删除权限，如果当前任务没有这个权限，直接拒绝。

第三层是执行隔离。工具执行应该在受控的环境里，尤其是那些执行代码、访问网络、操作系统的工具。隔离可以是进程级的，也可以是容器级的，取决于风险等级。

第四层是结果过滤。工具返回的结果不能直接塞回上下文，要过滤掉敏感信息、限制大小、做必要的脱敏。这一步经常被忽略，但很重要，因为工具返回的内容可能包含不该进入模型上下文的东西。

4.3 工具生态的版本管理和向后兼容

工具生态一旦成型，就会面临版本管理的问题。工具的参数变了、行为变了、返回值变了，怎么保证已有的 Agent 逻辑不被破坏？

我的做法是工具标识里带版本，比如file_read@v2。这样旧版本可以继续存在，新版本并行上线，Agent 逻辑按需选择版本。等所有调用方都迁移到新版本后，再下线旧版本。这种做法会增加一些维护成本，但能避免"改一个工具搞挂一片 Agent"的情况。

向后兼容的另一个要点是参数只增不减，语义只扩不缩。新增参数要有默认值，已有参数的语义不能悄悄改变。如果确实要做破坏性变更，那就走新版本，不要在原版本上改。

5. 记忆系统：working memory 和长期记忆的边界怎么划

5.1 记忆不是越多越好，关键是分层

Agent 记忆这块，热搜词里"agent记忆""agent 存储 working memory"都是高频。很多人一开始的想法是"记忆越多越好"，把所有历史都塞进上下文，结果就是上下文爆炸、成本飙升、模型注意力被稀释。

正确的做法是分层。至少分三层：

• 工作记忆：当前任务正在用的信息，容量小、访问快、生命周期短，任务结束就释放。
• 会话记忆：当前会话的历史，容量中等，会话结束可以归档。
• 长期记忆：跨会话的知识，容量大，需要检索，写入要谨慎。

这三层的边界要清晰，不能混。工作记忆不该持久化，长期记忆不该直接进上下文，会话记忆要有压缩策略。

5.2 记忆写入的时机和策略

记忆写入是个很容易做错的地方。写得太频繁，存储压力大，而且会写入很多噪音；写得太少，关键信息丢失，下次会话接不上。

我的经验是按重要性分级写入。任务的关键结论、用户的明确偏好、重要的中间结果，这些值得写入长期记忆。日常的对话细节、临时的工具返回，这些留在会话记忆里就够了，会话结束就归档或丢弃。

写入时机上，我倾向于在任务的关键节点写入，而不是每轮都写。比如任务完成时、用户明确表达偏好时、出现重要决策时。这样写入的内容质量高，噪音少。

5.3 记忆检索：怎么让模型拿到该拿的记忆

记忆检索的核心问题是相关性判断。用户问一个问题，系统要从长期记忆里找出相关的部分塞进上下文。这个"相关"怎么判断，直接决定了记忆系统的效果。

常见做法是向量检索，把记忆和查询都转成向量，算相似度。但纯向量检索有个问题，它擅长语义相似，不擅长精确匹配和时间推理。比如用户问"上周那个方案"，向量检索可能找不出"上周"对应的记忆，因为它不理解时间。

比较稳的做法是混合检索：向量检索负责语义相关，关键词检索负责精确匹配，时间过滤负责时间范围，最后做融合排序。这样能覆盖更多场景。

提示：记忆检索出来的内容不要直接全塞进上下文，要先做去重和压缩。我见过检索出十条记忆，其中五条是重复的，白白占了上下文。

6. 重构之后，怎么验证地基真的稳了

6.1 用可观测性验证边界是否清晰

重构完不能只看"能跑"，要看边界是否真的清晰。验证方法是看可观测性数据：模型调用、工具调用、消息流转、记忆读写，这些是否都有独立的埋点和指标。如果某个环节出问题，能不能从指标上快速定位到是哪一层的问题。

具体来说，我会关注这几个指标：

这些指标齐全，说明各层的边界是清晰的，因为只有边界清晰才能独立埋点。

6.2 用故障注入验证错误处理是否到位

错误处理是重构里最容易被糊弄的部分，因为正常路径测不出问题。验证方法是故障注入：人为让模型超时、让工具返回错误、让记忆存储不可用，看系统怎么反应。

好的错误处理应该做到：错误被归类到正确的层级，有明确的重试或降级策略，错误信息足够定位问题，不会因为一个环节的错误导致整个系统不可用。如果故障注入时系统直接崩了，或者错误信息含糊不清，那说明错误处理还没做到位。

6.3 用并发压测验证状态隔离是否可靠

并发问题在低负载下测不出来，必须压测。压测的重点不是看吞吐量，而是看结果是否正确。具体做法是：构造一批并发任务，每个任务有明确的预期结果，压测后检查所有结果是否都符合预期。如果有结果错乱，说明状态隔离有问题。

压测时还要关注资源竞争。比如多个任务同时调用同一个有状态工具，看是否出现竞争。这种问题在低负载下不会暴露，高负载下才会显现。

7. 从 Orkas 这次重构里，我提炼的几条通用经验

7.1 抽象要按能力，不要按接口

这是我在多个项目里反复验证的一条。按接口抽象，换一个供应商就要改上层；按能力抽象，上层只关心"要完成什么能力"，底层怎么实现是底层的事。这条经验不仅适用于模型调用，也适用于工具、记忆、存储。

7.2 状态要么隔离，要么显式传递

共享可变状态是万恶之源。要么每个执行单元有独立状态，要么状态通过显式消息传递。不要有中间地带，中间地带就是 bug 的温床。

7.3 错误处理要在设计阶段就分层

错误处理不是事后补的，是设计的一部分。每一层要处理自己这层的错误，向上层暴露归一化后的错误类型。全局兜底只能作为最后一道防线，不能作为主要手段。

7.4 可观测性不是可选项

Agent 系统的复杂度决定了它必须可观测。没有可观测性，出了问题只能靠猜。埋点要在重构时就加上，不要等出了问题再补。

7.5 重构的目标是让下一版更好改

重构不是为了这一版更漂亮，是为了下一版更好改。判断重构是否成功，看的是加新功能、换新模型、接新工具时，改动量是不是变小了。如果重构完还是改一处动全身，那重构就没达到目的。

我在实际做 Agent 项目时最大的体会是，地基这东西平时感觉不到它的存在，只有在你需要往上加东西的时候，才知道它稳不稳。Orkas 这次重写把模型调用、多智能体编排、工具生态这几块拆开，方向是对的，剩下的就是看每一块的契约定得够不够清楚。契约清楚，后面加什么都不会太痛苦；契约模糊，加什么都是在还债。