企业官网建设流程全解析

1. 从五条动态里拆出来的工程信号

10 月 7 日那天，某个技术社区里一位长期做智能体方向的开发者连续发了五条动态，内容不算长，但信息密度很高。我把这五条动态反复看了几遍，越看越觉得这不是随手记录，而是一个正在成形的工程栈的切片。所谓“编排成主角”，说的就是过去我们做智能体，注意力大多放在模型能力上，觉得模型够强，智能体就能跑起来。但这五条动态传递出来的信号恰恰相反：真正决定一个智能体系统能不能稳定跑下去的，是编排层，也就是把模型、工具、记忆、状态、错误处理串起来的那套工程结构。

这个判断对做智能体开发的人来说很关键。如果你正在搭自己的智能体系统，或者准备把智能体能力接进现有业务里，那这套编排思路就是你绕不开的东西。它解决的不是“模型能不能回答”的问题，而是“模型回答之后，系统怎么接住、怎么继续、怎么不出乱子”的问题。适合谁看？适合已经动手写过智能体 demo、但发现一上真实场景就各种崩的开发者，也适合想理解智能体工程化到底在做什么的技术负责人。

我先把这五条动态的核心信号拆开说。第一条动态讲的是任务拆解和状态传递，大意是“别让模型自己记着上一步干了什么，状态得由编排层管”。第二条讲工具调用的边界，说“工具不是越多越好，每个工具得有明确的输入输出契约”。第三条讲失败重试，提到“重试不是重新问一遍，而是带着上下文和失败原因重新规划”。第四条讲记忆分层，说“短期记忆和长期记忆要分开存，混在一起迟早出问题”。第五条讲可观测性，意思是“智能体跑起来之后，你得能看见它每一步在想什么、调了什么、为什么这么调”。

这五条合在一起，其实就是一个编排层的完整轮廓：状态管理、工具契约、失败恢复、记忆分层、可观测性。下面我按这个顺序，把每一条背后的工程逻辑、实操要点和我自己踩过的坑，一条一条展开。

2. 状态管理：别让模型自己记着上一步

2.1 为什么状态不能交给模型自己管

很多刚上手智能体的人会有一个直觉：既然模型能对话，那让它自己记住上下文不就行了？我一开始也这么想，后来发现这是最容易埋雷的地方。模型记上下文靠的是把历史消息塞进 prompt，但 prompt 有长度限制，而且模型对历史信息的“记忆”是不稳定的——它可能记住三步前的细节，却漏掉两步前的关键约束。

更麻烦的是，当智能体需要调用工具、等待工具返回、再基于返回结果继续推理时，这个中间状态如果只存在对话历史里，一旦某一步出错，你很难定位到底是哪一步的状态丢了。编排层管状态的意思是：把每一步的输入、输出、中间变量、当前任务阶段，都显式地存成一个结构化对象，模型每次只拿到它当前需要的那部分状态，而不是全部历史。

2.2 状态对象该怎么设计

我自己的做法是给每个任务实例建一个状态对象，至少包含这几个字段：任务 ID、当前阶段、已完成步骤列表、当前步骤的输入、当前步骤的输出、待处理步骤队列、全局约束条件。这个对象由编排层维护，模型每次被调用时，编排层把“当前步骤的输入”和“全局约束条件”拼进 prompt，模型返回结果后，编排层负责把结果写回状态对象，再决定下一步。

这样做的好处是，模型不需要“记住”任何东西，它每次只处理当前这一步。状态的一致性由编排层的代码保证，而不是靠模型的记忆能力。我实测下来，同样的任务，用状态对象管理之后，多步任务的完成率比纯靠对话历史高了将近一倍，因为模型不会再因为历史太长而丢失关键约束。

注意：状态对象里的字段不要设计得太细，否则编排层会变得很重。我的经验是，只存“下一步决策需要的信息”，中间过程的细节可以放到日志里，不必全塞进状态对象。

2.3 状态传递的常见坑

第一个坑是状态对象被多个步骤并发修改。如果你的智能体支持并行调用工具，那状态写入必须加锁或者用不可变数据结构，否则会出现两个步骤同时写同一个字段，后写的覆盖先写的。我踩过一次，两个工具同时返回结果，状态里的“已完成步骤”列表丢了一个，导致后续步骤重复执行。

第二个坑是状态对象和 prompt 不同步。有时候你更新了状态对象，但忘了把新状态拼进下一次 prompt，模型就会基于旧状态继续推理。我的解决办法是在编排层里做一个统一的“状态渲染”函数，所有 prompt 都从这个函数生成，避免手写 prompt 时漏字段。

第三个坑是状态对象没有版本。当你的编排逻辑升级、状态结构变了，旧的任务实例可能读不出来。所以状态对象里最好带一个 schema 版本号，升级时做兼容处理。

3. 工具契约：每个工具都得有明确的输入输出

3.1 工具不是越多越好

第二条动态说“工具不是越多越好”，这句话我深有体会。刚开始做智能体的时候，我恨不得把所有能调的能力都注册成工具，结果模型面对几十个工具，选择困难，经常调错。后来我做了个统计，发现实际高频使用的工具就那么五六个，剩下的要么很少用，要么用了也经常出错。

工具多的另一个问题是，每个工具的输入输出格式不统一，编排层要写一堆适配代码。所以我现在注册工具的原则是：只注册当前任务真正需要的，而且每个工具必须有明确的输入输出契约。

3.2 输入输出契约怎么定

所谓契约，就是工具接受什么参数、返回什么结构，必须写死，不能含糊。我见过很多工具的描述是“传入一个查询字符串，返回相关结果”，这种描述对模型来说太模糊了，模型不知道查询字符串该长什么样，也不知道返回结果里有哪些字段。

我的做法是给每个工具定义一个 JSON Schema，明确每个参数的类型、是否必填、取值范围，返回结果也定义成固定结构。比如一个搜索工具，输入是{query: string, limit: number}，返回是{results: [{title: string, snippet: string, url: string}], total: number}。这样模型在调用时，能根据 schema 生成正确的参数，编排层也能根据固定结构解析返回结果。

3.3 工具调用的错误处理

工具调用一定会出错，网络超时、参数不合法、返回格式不对，这些都得在编排层处理。我的经验是，工具调用失败后，不要直接把错误抛给模型让它重新调，而是编排层先做一轮判断：如果是参数问题，把 schema 和错误信息一起返回给模型，让它修正参数；如果是网络问题，编排层自己重试，不打扰模型；如果是工具本身返回了业务错误，那就把错误信息作为工具结果返回给模型，让它决定下一步。

提示：工具的错误信息要写得对模型友好。比如“参数 limit 必须是 1 到 100 之间的整数，你传了 200”，比“参数错误”有用得多，模型能直接根据这句话修正。

4. 失败恢复：重试不是重新问一遍

4.1 重试的三种层次

第三条动态讲失败重试，说“重试不是重新问一遍，而是带着上下文和失败原因重新规划”。这句话点出了重试的核心：重试要有信息增量。我把重试分成三个层次。

第一层是瞬时故障重试，比如网络抖动、服务暂时不可用，这种重试就是原样再调一次，编排层自己搞定，不需要模型参与。第二层是参数修正重试，工具返回参数错误，编排层把错误信息和正确 schema 一起给模型，让模型重新生成参数。第三层是规划重试，当前步骤反复失败，说明原计划走不通，需要模型重新规划后续步骤。

很多人的智能体只有第一层重试，遇到第二、三层就卡住了。我实测下来，加上第二、三层之后，复杂任务的最终完成率能提升三成以上。

4.2 重试次数和退避策略

重试不能无限次，得有上限。我的设置是：瞬时故障重试最多 3 次，间隔用指数退避，第一次 1 秒，第二次 2 秒，第三次 4 秒。参数修正重试最多 2 次，因为模型如果两次都改不对参数，再试也是浪费。规划重试最多 1 次，因为重新规划的成本很高，而且如果规划两次都失败，说明任务本身可能超出了当前能力范围，应该上报而不是硬撑。

退避策略这块，我踩过一个坑：早期我用固定间隔重试，结果遇到服务限流时，固定间隔反而加剧了限流。后来改成指数退避加随机抖动，效果好很多。

4.3 失败原因要结构化记录

每次失败，编排层都要记录结构化的失败原因：失败步骤、失败类型、错误信息、重试次数、最终结果。这些记录不只是为了排查问题，还能作为后续任务的参考。比如某个工具在特定参数下经常失败，编排层可以在下次调用前就避开这个参数组合。

我现在的做法是，失败记录写进一个独立的存储，按工具名和错误类型建索引。跑一段时间后，能看出哪些工具最不稳定、哪些参数组合最容易出错，这些都是优化编排逻辑的依据。

5. 记忆分层：短期和长期必须分开

5.1 为什么记忆要分层

第四条动态说“短期记忆和长期记忆要分开存，混在一起迟早出问题”。这个判断非常准。短期记忆是当前任务上下文里的信息，比如刚才调了什么工具、返回了什么结果，这些信息只在当前任务生命周期内有效。长期记忆是跨任务的知识，比如用户的偏好、历史任务的结论、领域知识，这些信息需要在任务结束后保留。

如果把两者混在一起存，会出现两个问题。一是短期记忆污染长期记忆，当前任务的临时信息被当成永久知识存下来，下次任务读到就出错。二是长期记忆拖慢短期推理，每次都要从大量长期记忆里检索，prompt 变得很长，模型反而抓不住重点。

5.2 短期记忆的管理

短期记忆我建议直接放在状态对象里，跟着任务走，任务结束就释放。如果任务很长，短期记忆也需要压缩，我的做法是保留最近 N 步的完整信息，更早的步骤只保留摘要。摘要由编排层生成，比如“第 3 步调用了搜索工具，找到了 5 条相关结果”，不需要保留原始返回内容。

压缩的触发时机很重要。我试过按步数压缩，也试过按 token 数压缩，最后发现按 token 数更合理，因为不同步骤的信息量差异很大。我的设置是短期记忆超过 2000 token 就触发压缩，把最老的步骤替换成摘要。

5.3 长期记忆的检索

长期记忆的关键是检索，不是存储。存进去容易，用的时候能准确捞出来才难。我的做法是给长期记忆建向量索引，检索时用当前任务的目标和约束作为查询，捞最相关的几条。但向量检索有个问题，就是可能捞到语义相似但实际无关的内容，所以我会再加一层过滤，用规则或者小模型判断捞出来的记忆是否真的适用于当前任务。

注意：长期记忆写入前一定要做去重和冲突检测。我遇到过两次任务结论矛盾的情况，长期记忆里同时存了“方案 A 可行”和“方案 A 不可行”，检索时两条都捞出来，模型直接懵了。后来我加了冲突检测，新记忆写入前先检查是否有矛盾记录，有的话标记出来人工确认。

6. 可观测性：得能看见智能体在想什么

6.1 可观测性的三个维度

第五条动态讲可观测性，说“智能体跑起来之后，你得能看见它每一步在想什么、调了什么、为什么这么调”。这句话拆开就是三个维度：推理过程、工具调用、决策依据。

推理过程的可观测性，指的是模型每一步的输入 prompt 和输出结果都要记录。工具调用的可观测性，指的是每次工具调用的参数、返回、耗时、是否成功都要记录。决策依据的可观测性，指的是编排层为什么选择这一步、为什么重试、为什么终止，这些决策逻辑也要记录。

很多人的智能体只记录了最终结果，中间过程全丢了，出了问题根本没法排查。我现在的做法是，每个任务实例生成一条完整的执行轨迹，包含所有步骤的上述信息，存成结构化日志。

6.2 执行轨迹的存储和查询

执行轨迹的数据量不小，一个复杂任务可能有几十步，每步都有 prompt 和返回。我的存储方案是：热数据存内存或者高速缓存，保留最近 24 小时；温数据存普通数据库，保留 30 天；冷数据归档到对象存储，长期保留但查询慢。

查询这块，我建了几个索引：按任务 ID 查、按工具名查、按错误类型查、按时间范围查。最常用的是按任务 ID 查，排查问题时直接拉出整个轨迹。按工具名和错误类型查，用来分析工具稳定性。

6.3 从轨迹里能看出什么

执行轨迹不只是排查工具，还能用来优化编排逻辑。我定期分析轨迹，看几个指标：平均步数、工具调用成功率、重试率、任务完成率、每步耗时分布。这些指标能告诉我编排逻辑哪里有问题。

比如有一次我发现某个任务的平均步数特别高，拉出轨迹一看，是模型在两步之间反复横跳，一会儿调工具 A，一会儿调工具 B，来回好几次。这说明编排层没有给模型足够的约束，模型在探索。后来我在状态对象里加了“已尝试方案”列表，模型看到之前试过什么，就不会重复横跳了。

7. 编排层的整体架构怎么搭

7.1 分层架构

把上面五块拼起来，编排层的整体架构可以分成四层。最底层是工具层，负责实际执行搜索、计算、存储这些操作，每个工具实现自己的输入输出契约。往上一层是状态层，负责维护任务状态对象、短期记忆、长期记忆的读写。再往上一层是编排层核心，负责决策下一步做什么、调用哪个工具、失败怎么处理。最上层是接口层，负责接收任务、返回结果、暴露可观测性数据。

这个分层的好处是每层职责清晰，工具层只管执行，状态层只管存取，编排层只管决策，接口层只管交互。改任何一层都不影响其他层。我早期把所有这些逻辑混在一个大函数里，后来重构分层，维护成本降了很多。

7.2 编排循环的核心逻辑

编排层的核心是一个循环：读状态、决定下一步、执行、写状态、判断是否结束。这个循环看起来简单，但每个环节都有讲究。

读状态时，要只读当前步骤需要的那部分，不要把整个状态对象都塞进 prompt。决定下一步时，可以用模型决策，也可以用规则决策，我的做法是混合：常规步骤用规则，遇到需要判断的步骤用模型。执行时，要处理超时、重试、错误。写状态时，要保证原子性，避免并发写冲突。判断是否结束时，要有明确的终止条件，不能无限循环。

7.3 终止条件的设置

终止条件我设了四个：任务完成、达到最大步数、连续失败超过阈值、模型明确表示无法继续。这四个条件满足任何一个就终止。最大步数我设的是 50 步，超过就判定为异常，上报人工。连续失败阈值是 3 次，同一个步骤连续失败 3 次就终止。

提示：终止时一定要把当前状态和执行轨迹完整保存下来，方便后续分析。我见过有人终止时只存了个“失败”，什么上下文都没有，排查起来非常痛苦。

8. 实操中踩过的坑和排查技巧

8.1 模型不按契约返回参数

这是最常见的坑。你定义了工具的参数 schema，但模型返回的参数就是不符合。我的排查思路是：先看 schema 描述是否清晰，如果 schema 本身有歧义，模型当然会错；再看 prompt 里有没有给足够的示例，模型需要看到正确参数的样例；最后看是不是模型能力不够，换个更强的模型试试。

解决办法我试过几个：一是在 prompt 里加 few-shot 示例，给两三个正确调用的例子；二是在编排层加参数校验和自动修正，比如模型返回了字符串类型的数字，编排层自动转成数字；三是把 schema 描述写得更详细，每个字段都说明用途和格式。

8.2 任务跑着跑着就偏了

任务偏离是另一个高频问题。模型在中间某一步做了个不太对的决策，后面就越走越偏。我的排查方法是拉出执行轨迹，找到第一个偏离点，看那一步的 prompt 和状态是什么。

偏离的原因通常有两个：一是状态里缺少关键约束，模型不知道哪些事不能做；二是 prompt 里没有强调当前阶段的目标，模型被历史信息带偏了。解决办法是在状态对象里加“禁止操作”列表，在 prompt 里明确当前阶段目标，并且每一步都重申全局约束。

8.3 工具返回结果太长撑爆 prompt

工具返回的结果有时候很长，比如搜索返回了 20 条结果，每条都有大段摘要，全塞进 prompt 就超长了。我的处理办法是在编排层做结果截断和摘要：只保留最相关的几条，每条只保留关键字段，长文本用摘要代替。

截断策略我试过按数量截断和按 token 截断，最后用按 token 截断，因为不同结果的长度差异很大。摘要我用一个小模型生成，把长文本压缩成一句话，既保留关键信息又控制长度。

8.4 并发任务互相干扰

当多个任务同时跑时，如果它们共享某些资源，比如同一个长期记忆库、同一个工具配额，就可能互相干扰。我踩过一次，两个任务同时写长期记忆，结果其中一条被覆盖了。

解决办法是给共享资源加锁或者用队列串行化。长期记忆写入我改成了队列模式，所有写入请求排队处理，避免并发冲突。工具配额我改成了按任务分配，每个任务有独立的配额，不会互相抢。

8.5 常见问题速查表

9. 编排层后续可以怎么扩展

这套编排思路跑通之后，能扩展的方向不少。我目前在做的一个扩展是编排逻辑的版本化，把不同版本的编排策略存下来，跑任务时可以选择用哪个版本，方便做 A/B 对比。另一个扩展是编排层的自适应，根据任务类型自动选择不同的编排策略，比如简单任务用规则编排，复杂任务用模型编排。

还有一个方向是把编排层的决策过程也交给模型，让模型不仅决定调什么工具，还决定怎么编排。这个方向风险比较大，因为编排逻辑一旦交给模型，可控性会下降，但潜力也大。我现在的做法是半自动：编排层给出几个候选策略，模型从中选一个，而不是完全自由发挥。

最后分享一个小技巧：编排层的日志一定要带 trace ID，从任务开始到结束，所有步骤、所有工具调用、所有状态变更都带上同一个 trace ID。这样排查问题时，一个 ID 就能拉出全链路，不用在多个日志文件里来回找。这个习惯我坚持了两年，省下来的排查时间非常可观。