企业官网建设流程全解析

1. 为什么多智能体这件事，在Office场景里特别难

Office多智能体系统这个系列，我酝酿了很久才动笔。这两年单Agent的文章铺天盖地，大家手里能跑通Demo的不少，但真到要把多个Agent放进同一个办公环境里协同干活的时候，问题一下子就冒出来了：角色怎么分？任务怎么拆？表格被谁改了？邮件该谁发？用户一句“帮我把周报整理一下”落到系统里，到底该唤醒哪个Agent，唤醒之后谁先谁后，中间出错找谁负责？这些问题没有一个能在模型层直接解决，只能靠架构设计硬扛。所以我决定开一个系列，把我在搭建Office多智能体系统时沉淀下来的架构思考、方案取舍和踩坑记录完整写出来。

系列第一篇文章不写代码，也不急着端出某套框架，先把全局的东西讲透：为什么办公场景必须单独设计一套多智能体架构，顶层应该怎么分层，以及三个最核心的机制——角色编排、工具与订阅、记忆与权限——到底怎么落地。如果你正在做智能文档处理、办公自动化、企业知识类助手，或者单纯想看看多智能体系统怎么从概念图变成一套可以跑起来的骨架，这篇都适合你。我毕竟在模拟项目X里完整走过一遍从单Agent到多Agent的全过程，下面讲的每一层都经历过被业务方追问“你这个到底能不能用”的时刻。

1.1 单Agent的边界到底在哪里

先说一个直白的观察：办公场景里，单Agent能解决的问题其实很有限。不是模型能力不够，而是职责全堆在一个上下文里，系统必然走向失控。举个例子，你让一个Agent既读邮件、又维护项目表格、还要生成汇报PPT，它的System Prompt会越写越长，工具描述越堆越多，可用上下文空间被不断挤压。最后的结果就是模型在各种工具之间反复横跳：该查表格的时候去翻了邮件，该写PPT的时候又去改了日程。

我对这个状态的通俗理解是：单Agent本质上像一个人同时干行政、财务、销售助理三份工，短期也许扛得住，一旦任务复杂度上来，出错概率是指数上升的。因为每一份职责都有自己的工具边界、数据来源和错误模式，混在一起之后，你根本分不清一次回答错误到底是因为提示词写得不好，还是因为工具状态和上下文不一致，还是因为模型本身判断错了。

多智能体的出现不是炫技，它解决的是两个很实际的问题：一是职责隔离，让每个Agent只关心自己那一摊事，上下文干净，工具列表短，犯错半径小；二是故障定位，当一个任务处理失败，你能很快知道是哪个环节的问题，而不是在一个巨大的上下文里考古。这两点在Office场景里尤其重要，因为办公任务大多是连续性、多步骤、有明确交付物的，一旦中间出了问题，影响的是整个业务流程。

1.2 Office场景为什么不能照搬通用方案

市面上的多Agent框架很多，但直接拿来套办公场景，你会发现总是差那么一口气。原因在于Office场景有四类很强的特性，是通用闲聊式多Agent架构覆盖不到的。

第一是结构化数据与语义数据的混合。办公任务里，表格是结构化的、字段严格的；邮件是语义化的、语气复杂的；日历是半结构化的，有参与人、忙碌状态、时区。Agent既要做自然语言理解，又要做结构化查询，还要在两者之间做转换。一套设计不好，就会出现“模型把日期字段当成闲聊内容”这种低级但高频的错误。

第二是强时间依赖。办公任务从来不是“你问我答”就能结束的。周报周五前要交，会议周三下午两点开始，合同本周内要审完。Agent必须理解时间约束，并能把任务拆到对应的时间节点上，还要在事件临近时主动唤醒，而不是被动等用户再问一次。这个“主动性和时间感知”是很多通用框架里没有的。

第三是多人协作与共享状态。办公数据天然是共享的。一份在线计划表可能同时被三个人在编辑，一个共享收件箱可能被整个项目组使用。Agent必须能感知到“对象被谁改了”“版本变化了”，而不是每次重新读一遍全表。这种对共享状态变化的响应机制，需要专门设计。

第四是权限与合规。办公系统里流转的全是真实业务内容，客户信息、合同金额、人事数据，无论哪一类泄漏都是大事故。Agent绝对不能拥有比用户本人更高的权限，更不能跨权调用工具。这一点直接决定了权限系统不能做成事后检查，而要做成事前强制隔离。

所以我的结论很明确：Office多智能体系统需要一套面向办公语义的领域架构，而不是把一套通用聊天机器人框架外挂几个工具就算完事。这也是这个系列要逐步展开的核心内容。

1.3 这个系列准备讲什么

既然叫“系列一”，先把整体路线图放出来，方便你判断哪篇对你最有价值。

• 系列一（本篇）：整体架构与三大核心机制总览
• 系列二：编排器设计，任务分解、Agent选派、冲突裁决与状态恢复
• 系列三：工具接入协议，从同步工具调用到异步订阅机制的完整设计
• 系列四：记忆分级与权限隔离，短中长期记忆的边界、权限穿透问题的解法
• 系列五：可观测性与排错实践，日志、追踪、决策审计和线上问题复盘

这个顺序基本对标了一套系统从设计到落地的完整路径。第一篇先把大框架立起来，后面每一篇再深入一个具体点，这样你不会有“道理都懂但不知从哪下手”的感觉。

2. 顶层架构：一张图看懂六个层

在设计多智能体系统时，我最反感的一件事就是把架构图画得花里胡哨，十几条箭头绕着七八个圆圈转，看半天也不知道数据到底往哪流。所以这套架构我只保留六个层，每个层只干一类事，边界画得清清楚楚。

2.1 六层拓扑与数据流向

整个系统从用户入口开始，自上而下依次是：

• 接入层：面向用户的交互入口，包括网页对话框、IM机器人、Office套件内部插件、语音助手这类终端形态。接入层不承载业务逻辑，只负责把原始用户输入转成统一消息格式，再交给编排层。
• 编排层：整套系统的大脑。做四件事：会话管理、任务分解、Agent选派、状态记录。用户说一句“整理本周项目周报”，在这里被解析成任务树，指派给对应的Agent，并在状态表里留下这一步的动作。
• 智能体层：真正干活的角色。我按办公对象拆成文档Agent、表格Agent、邮件Agent、日历Agent、演示Agent等。每个Agent维护自己的上下文和工具列表，只对自己负责的那类对象有操作能力。
• 能力层：包括工具注册中心、订阅中心、三方代理。这是Agent的操作底座，所有对外读写都通过这一层，不允许Agent直接连外部系统。
• 数据层：负责所有状态的沉淀，包括向量库、结构化存储、知识库索引、事件日志。
• 基础设施层：横向底座，包含模型网关、权限引擎、审计服务、监控告警。它不直接参与业务，但所有请求都要经过它的校验。

调用链路上，用户请求先进编排层，编排层完成任务拆解后把子任务分发给对应Agent，Agent通过能力层操作数据对象，得到结果后返回编排层，最后由编排层汇总并回复用户。整个链路是显式的、可追踪的，任何一步出问题都能定位到具体层。

2.2 三条设计原则：可降级、可观测、可回滚

架构分层只是骨架，真正的灵魂是设计原则。我在这个项目里给自己定了三条红线，任何层设计冲突时，都以这三条为准。

第一条是可降级。整个系统必须能在Agent层完全不可用的时候，退回到最基础的自动化工具链或者人工流程。用户说“帮我整理周报”，就算所有Agent都挂了，至少要能给出各人提交给自己的周报原文链接，而不是直接报错。办公场景最忌讳的就是智能体成了唯一的操作入口，AI一挂整个业务就瘫了。所以我在架构里单独留了一条“裸通路”，不经过Agent，直接从编排层调用底层工具，保证核心动作永远可用。

第二条是可观测。多智能体系统的特点就是决策链长，一个任务的完成往往经历理解、拆分、选派、执行、汇总五个阶段。任何一个阶段都有可能是模型“自由发挥”出来的结果，如果每个阶段的理由都没有记录，出了问题你连从哪查起都不知道。所以我在设计里强制要求：每个Agent的关键决策、每次工具调用、每个汇总依据，都必须写入决策日志。这条后面会专门展开。

第三条是可回滚。办公系统里全是真实业务数据，Agent一旦写错，影响是实实在在的。我把所有写操作都设计成“先走代理、再落库”，执行前保留对象基线，任何一步失败了都能还原。这就意味着用户的在线表格、共享文档永远有救。

2.3 为什么选“中心化编排”而不是“Agent自由交流”

多智能体架构里有一条路线之争：是采用一个中心编排器统一调度，还是让Agent像一群人围在桌子前自由聊天、自行协作。我两种模式都调研过，最后毫不犹豫选了中心化编排。原因用一句话说就是：办公任务需要可预期的交付路径，自由协作的失控风险太高。

两种方案的对比，我拆成一张表来看：

自由协作模式的诱人之处在于理论上更灵活，Agent之间可以自己协商分工。但现实是，办公任务往往涉及明确的责任边界和审批链路，一旦Agent之间为了“谁负责更新表格”争起来，用户根本不知道这个任务下一步会变成什么样。所以我的选择是：现阶段强制上中心编排，所有Agent之间的交互都通过编排器转发；等系统成熟、可观测性做扎实后，再逐步放开局部场景的Peer通信，但全链路依然保留trace。这个思路在落地过程中被验证是效率最高的。

3. 核心机制一：角色编排与任务分解

架构是骨架，下面是第一块核心器官：角色与编排。这是Office多智能体系统能不能“干正事”的关键。我见过太多项目栽在角色定义上：角色概念做了，但完全写死在代码里，每次调整都要发版，或者角色之间职责重叠，一个表格修改请求能触发三个Agent同时动手改同一份数据，场面完全失控。

3.1 把角色做成配置，而不是写死在代码里

先说角色定义这件事。我的做法是：Agent角色是一份结构化配置，而不是一段逻辑代码。配置里包含名称、描述、可用模型、关联工具列表、权限边界和行为策略。这样做有三个好处。

第一，业务调整不需要发版。Office场景的权限和工具范围经常变：某个人从项目组调走、某个表格对某个角色只读、某个新周报模板上线。这些在配置里改一行就生效，不用动代码。

第二，能针对不同任务选择不同模型。一顿早饭级别的任务用重模型就是浪费成本。角色配置里允许指定模型策略，高复杂度任务走推理能力强的模型，低复杂度任务走快模型，成本能差出一个量级。

第三，角色和模型解耦后，切换底线模型不会破坏整个体系。以前有人问“换了个新模型，我的几个Agent要不要全部重新调一遍”，答案是只调角色配置里的模型字段即可。下面是一份简化的角色配置文件例子：

agent: name: "mail_agent" model_policy: "fast_model" description: "负责收件箱摘要、邮件分类和草稿生成" tools: - name: "mail.inbox.summary" permission: "read" - name: "mail.outline.draft" permission: "write_draft" policies: - "发送邮件必须经过用户确认" - "外部收件人地址需要二次校验"

这段配置看着简单，但它规定了Agent能干什么、不能干什么、边界在哪，比在代码里写几百行if else要清晰得多，也安全得多。

3.2 从用户一句话到任务拆解的完整链路

角色定义好了，真正的考验是“任务分解”。我先拿一个你一定会遇到的实际场景举例：用户说“整理一下本周项目周报，周五之前帮我生成汇报PPT”。

这句话落到编排器里，会经历下面几个步骤。

第一步，语义解析与实体抽取。编排器从请求里提取出实体对象：本周、项目周报、汇报PPT、周五。这里的难点不是提取词，而是判断实体之间的约束关系：周报数据源是哪些邮件和表格？PPT的受众是谁？周五是最终截止还是初稿截止？这些在普通对话系统里可以模糊，但在办公系统里必须明确，否则后面Agent没法执行。

第二步，构建任务树。编排器把目标拆成四个相互依赖的子任务：汇总邮件与周报素材，更新项目进度表格，基于表格生成PPT初稿，整体校对和格式修正。这四个子任务不是并列的，是有先后依赖的。所以任务树里必须带依赖关系，表格生成Agent必须等素材聚合Agent完成之后才能启动，PPT Agent必须等表格更新完毕才能读数据。

第三步，Agent选派。编排器根据任务树和角色配置，选出三个参与者：邮件Agent负责素材聚合，表格Agent负责数据更新，演示Agent负责PPT生成。每个参与者的职责边界是清晰的，不会出现“邮件Agent顺手改表格”的情况。

第四步，结果汇总与一致性校验。三个Agent各自返回成果物后，编排器要做校验：日期是否符合、数据是否前后一致、PPT里的图表是否引用了最新表格。这里的校验不能只依赖模型“觉得行”，必须有明确的事实性工具做比对。

第五步，回复与等待确认。编排器把汇总结果交给用户确认，用户在拿到最终PPT前还有一道确认闸门。这个过程对用户的体验是：看起来只有“一句话需求”，但系统内部已经跑完了一套完整有序的流水线。

3.3 Agent之间意见不一致时，谁说了算

多Agent系统还有一个绕不开的问题：Agent之间的信息不一致怎么办。我遇到过真实的例子：日历Agent判断周五下午空闲，但会务Agent认为高管会议占用了周五下午整个时段。两个Agent都在“陈述事实”，但事实彼此冲突。

这时候编排器不能和稀泥，必须有明确的裁决顺序。我的规则是三条。

第一条，事实优先于推理。当Agent之间话说不到一起的时候，一律以工具返回的实时数据为准。日历Agent说周五有空，那好，直接调用日历查询接口核实；会务Agent说有空，那也直接查。模型不负责“记得事实”，它只负责“解释事实”。这个原则极大减少了幻觉在协作场景中的危害。

第二条，影响面评估。如果两个答案都指向合法的操作路径，编排器需要计算方案的影响面。改一个临时会议的时间，影响10个人；改一个项目里程碑的时间，影响整个部门的后续排期。影响面决定要不要升级人工处理。

第三条，人工升级机制。凡是涉及外部发送、批量修改、跨部门协调的操作，不管Agent之间讨论得多一致，都自动生成待确认项，挂在状态表里等用户或管理员拍板。宁可多一次确认，也不能让Agent自作主张搞出不可逆的操作。

这些裁决过程都要形成决策日志，记录当时的上下文、参与裁决的Agent、依赖的哪些工具数据、最终依据是什么。只有这样，事后审计才有据可查。

3.4 会话状态表的设计

聊到编排就不能不提状态管理。很多多Agent系统跑着跑着就崩了，根本原因是Agent之间的状态没有统一维护，每个Agent自己记一套“我认为现在是什么状态”，结果自然对不上。

我在架构里设计了一张会话状态表，每个会话生命周期内只能有一个实例，所有Agent的每一次动作都往里面更新记录。它的核心字段长这样：

{ "session_id": "sess_01H...", "turn_id": 7, "task_tree": { "root": "生成周五汇报PPT", "dependencies": {} }, "roster": ["mail_agent", "sheet_agent", "slides_agent"], "context_refs": [ "object://spreadsheet/project-plan/rev_003", "object://mail/inbox/summary_0421" ], "pending_approvals": [ {"action": "send_ppt_email", "status": "waiting"} ], "decision_log": [ {"time": "2025-01-01 14:23:01", "agent": "orchestrator", "reason": "use_sheet_agent_because_data_update_required"} ], "recovery_point": "task_2_completed" }

这个表的作用有两个。第一，它是会话的“唯一事实源”，任何一个Agent需要了解当前整体状态时，不靠猜，直接读表。第二，它天然支持恢复，编排器崩溃重启之后，能从recovery_point字段接着往下跑，不用从头开始。这是多Agent系统能真正落地的关键，没有状态表之前，我每次重启服务都像在玩抽签，恢复谁丢谁完全不可控。

4. 核心机制二：工具层与订阅层的双通道

角色编排解决的是“谁干什么”，工具层解决的是“Agent靠什么干活”。这一层在我眼里是整个Office多智能体系统的地基，因为它决定了Agent能不能安全、稳定地操作真实业务数据。

4.1 两条通道各管什么事

办公环境里Agent操作数据有两种典型模式。一种是你问它答，Agent需要查一个东西，主动去调一个函数拿到结果，这是同步的请求-响应模式；另一种是数据自己变了，系统需要主动通知Agent“你关心的对象发生了变化”，这是异步的订阅事件模式。两种模式缺一不可。

我习惯用打电话和收推送来类比：工具调用像打电话，你拨过去，对方接了，你拿到答复，确定性很强；订阅事件像订阅新闻推送，不用你天天问“发生什么了吗”，事件一发生就会推到你面前。Office场景里，同步工具负责“按需查询”和“主动执行”，订阅事件负责“感知变化”和“自动响应”。两个通道分开设计，互不混用，整个能力层就清晰了。

4.2 工具注册中心：所有能力必须过一道登记

Agent不能随便调一个方法就算“用工具”了。我在系统里强制要求：每个对外操作能力都必须先在工具注册中心登记，写清楚名字、用途、输入输出格式、所需权限、幂等性和是否是破坏性操作。没有登记的能力，Agent在意图上再接近也调用不了。

一份工具声明的关键内容长这样：

{ "tool_name": "spreadsheet.query", "description": "查询在线表格指定区域的内容", "input_schema": { "spreadsheet_id": "string", "range": "string", "filters": "optional" }, "auth": { "type": "user_impersonation", "scopes": ["read"] }, "mutating": false, "requires_approval": false }

这段描述里的几个字段都很有讲究。auth字段表示这个工具必须以“当前主用户身份”调用，子Agent不能用自己的身份越权；mutating标记是否是修改操作，改数据的走写通道；requires_approval标记是否需要人工确认，比如发送邮件、批量删除这类高风险动作必须为true。工具注册中心还有一个隐藏功能：它会在编排器做Agent选派时，自动过滤那些“当前Agent无权调用”的工具，从源头杜绝权限穿透。

按接入类型看，Office场景下的工具大致有三类：第一类是SaaS在线工具，比如在线文档、在线表格、共享日历，走公开API接入；第二类是本地文件与内网服务，比如企业知识库、内部审批系统，走内网网关接入；第三类是存量企业系统，比如CRM、ERP，通常只有只读或固定写接口。每一类在注册中心里的权限描述和审批策略都不一样，但统一收口在同一个注册中心管理，这是安全底线。

4.3 订阅事件模型：让Agent主动感知变化

工具层另一半是订阅中心。办公场景里有大量“我不问你也要知道”的场景：共享表格被另一个同事改了；一封重要邮件到了；一个会议被发起人改了时间。如果这些变化都要靠编排器被用户问到才发现，系统就退化成了“会说话的数据库”，而不是“主动协作的智能体”。

我的设计方案是定义一套统一事件模型，核心字段包括：

{ "event_id": "evt_880213", "topic": "spreadsheet.updated", "entity": "spreadsheet://project/plan/rev_003", "payload": { "modified_by": "user_02", "changed_range": "C3:D9", "before_rev": "rev_002", "after_rev": "rev_003" }, "occurred_at": "2025-01-01 14:33:12" }

这套事件模型有几个关键要求。一是每个事件必须有全局唯一的event_id，用来做消费幂等，同一个事件永远不会被处理两次。二是事件必须绑定具体实体对象，也就是entity字段，这样订阅者可以精确知道自己关心的哪个对象发生了变化。三是事件要保留before和after的版本引用，Agents不只知道“变了”，还能知道“从哪里变到了哪里”。

消费事件的时候，还有一个很现实的问题：事件风暴。想象一下，三个人同时在线改一份项目计划表，每改一个单元格就产生一个事件，如果不加控制，表格Agent会被频繁唤醒几百次，系统资源全浪费在处理“单元格被改了0.1秒”这种无关痛痒的变化上。我的解法是事件聚合并采用“滑动窗口去重”：在很短的时间窗口内，把同一实体对象的多个变更事件合并成一条变更摘要，只触发一次Agent响应。窗口值我一般设在几百毫秒到几秒之间，具体需要按照业务容忍度调整。这个设计被实际验证极其重要，没有它订阅通道早就被打爆了。

5. 核心机制三：记忆分级与权限隔离

最后一块核心机制，也是办公场景里最敏感的一块：记忆与权限。我发现很多多智能体项目在Demo阶段完全不考虑这两个问题，等一上线就被安全部门叫停。这里面的坑很深，我逐层拆开讲。

5.1 记忆分级：短期、中期、长期各管一摊

多Agent系统的记忆不能是一个大池子，所有Agent都往里写、往里读。那样一来，上下文互相污染，权限无法控制，成本还高得离谱。我的做法是分成三级，每一级有明确的存储载体、生命周期和访问边界。

分级背后有两个逻辑。第一个是成本控制：长期知识库里的每一个Token都要通过向量检索花真金白银，短期记忆里的每一段内容都在吃掉模型上下文窗口，不分级，成本没人扛得住。第二个是安全边界：办公数据分密级，不是每个Agent都有权访问为期三周的合同纪要；把长期知识库做细颗粒度授权之后，才能实现“文档Agent能读纪要，但邮件Agent只能读标题摘要”这种细粒度管控。

这三级记忆在运行时是协同工作的：用户进入会话时，编排器会把“用户身份”和“长期知识库中与该用户相关的授权索引”加载进上下文；任务进行中，工作区记忆由各Agent共享更新；每一轮对话结束，新得到的洞察经过摘要处理，再决定要不要沉淀回长期知识库。这套机制跑起来之后，Agent不会再出现“我记得上次给A用户做过一个类似的模板，但找不到内容”这种记忆断裂的问题。

5.2 权限模型的核心：让边界变成工具可见性

很多人理解权限就是“Agent不要读不该读的东西”，这种理解太浅了。真正安全的权限模型是：权限不是靠Agent自觉遵守，而是靠系统层的工具可见性强制过滤——一个Agent能看到和调用的工具列表里，压根就不包含它无权操作的能力。

例如在配置栏里，邮件Agent只注册了“收件箱摘要”和“草稿生成”能力，发送邮件的工具就不会出现在它的可见工具列表里。模型就算有千般想“自作主张”的冲动，也没有对应的工具可以调用。这和现实中“他没有保险柜钥匙，自然开不了门”是同一个道理。

下面是一个简化的角色权限矩阵，供你参考：

每个子Agent在调用工具时，必须带着主用户身份令牌去调用，不能用自己的服务身份。这样权限的最底线是：Agent永远不可能比用户本人拥有更多权限。用户没权限读某份合同，Agent就算知道合同存在也读不到正文。

5.3 三方动作代理与审批闸门

最后说“三方动作”这个概念。Agent直接操作本地内存里的数据没什么风险，但如果动作是发一封邮件、修改一份共享文档、删除一批历史记录，这就是“影响第三方的动作”，必须走代理和执行审批。我把它称为三方动作代理机制。

具体流程是这样的：Agent提交一个动作意图，这个意图不会直接执行，而是先进入批准引擎。批准引擎会校验三件事：当前Agent是否具备执行该动作的权限、动作影响面有多大、是否在审批白名单内。校验通过后，如果动作类型是低风险且用户预先设置了自动批准策略，就自动执行；否则就挂起到待办清单，等待用户或管理员做一级/二级审批。所有审批记录连同动作执行结果一起写入审计日志，形成完整闭环。

这个流程的好处是既守住了安全底线，又不至于把Agent的所有操作都拖入人工审核的泥潭。用户配置风格是“允许自动执行”的动作快速通过，凡是涉及外发或批量变更的动作一律人工把关。我见过不少项目为了“让Agent更自由”砍掉了审批闸门，上线第一周就发生了误发给全部客户群发邮件的严重事故。所以在这个设计上，我的态度非常保守：宁可多等一次确认，也不要追求完全无人值守的自动化。

6. 落地排错：我踩过的坑和四条建议

前面讲的都是设计层的东西，最后这部分聊点实战经验。多智能体系统的复杂性在跑起来之后才会真正爆发。我这里整理了几个我亲自遇到过、并且花费了较长时间才化解的典型坑，以及四条给新手的建议。

6.1 我在具体落地时遇到过的四个坑

这个部分是我的排错实录，每一个坑都对应一个具体的架构修正措施。

第一个坑是Agent之间的“甩锅”导致死循环。现象很经典：邮件Agent说“我需要表格Agent的统计结果才能生成周报摘要”，表格Agent说“我需要邮件Agent的素材才能更新统计”，两个Agent互相等待，谁也不先动手，整个任务就卡在那里了。原因在于我没有给Agent协作设置超时和最终裁决机制。修正方案是：编排器为每个子任务设定硬超时，超时后自动触发降级策略——要么用缓存数据生成部分结果，要么带着现有数据直接询问用户如何继续，绝不允许无限等待。

第二个坑是上下文爆炸。我最初让每个Agent把检索到的全文原样传给下一个Agent，因为觉得这样信息最全。结果系统Token消耗直接翻了四五倍，而且后面的Agent收到的上下文越来越长，真正有价值的信息被海量噪声淹没。修正方案是改为“上下文引用指针+结构化摘要”：Agent传给下游的不是全文，而是对象引用和一段结构化摘要，下游需要细节时再按引用主动拉取。这个改动让Token成本骤降，效果很明显。

第三个坑是权限穿透。发生得很隐蔽：我在日志里发现某个子Agent在处理一个文档时读到了另一个项目分区的数据。排查后发现原因是创建子Agent任务时，我没有把主用户的上下文令牌透传下去，子Agent在某些路径上用了默认的“系统内部身份”，绕过了部分权限过滤，导致越权读取。修正方案是在编排层强制统一令牌透传逻辑，并加了一层角色可见性过滤，保证任何子Agent的可见工具列表都在主用户权限覆盖范围内。

第四个坑是订阅事件风暴。在线表格多人协作时，每一处单元格改动都会触发变更事件，事件消息量在高峰期直奔每秒几百条，表格Agent被频繁唤醒，系统CPU和Token成本同时飙升。我在第4.3节提过解法：事件聚合加滑动窗口去重，把短时间内的多处改动打包成一条变更摘要，只触发一次Agent响应。这个方案上线后，事件量直接下降了一个数量级。这种问题在设计阶段往往看不到，到了负载测试阶段才会暴露，所以我强烈建议第一版就把事件聚合机制内置进去。

6.2 可观测性怎么设计才不是事后补丁

多智能体系统的可观测性，比普通微服务项目复杂得多。因为除了服务状态，还要观测“模型在每个步骤里为什么做出这个决策”。我建议从第一天就把两层日志设计好。

第一层是执行日志，记录每个Agent的每次工具调用和耗时，字段包括trace_id、session_id、agent_id、调用的工具名、传入参数的摘要键、耗时和模型调用成本。有了这层日志，你可以快速回答“昨天下午那个PPT生成请求为什么花了四十秒”这类问题。

第二层是决策日志，记录“Agent在这个点为什么这么选”。比如编排器为什么把任务派给表格Agent而不是文档Agent，某个Agent为什么判定当前事件不需要响应。这一层日志的价值在于：当用户投诉某个结果不对时，你不是只能看看数据有没有传错，而是能翻出当时的判断依据，找到是信息缺失导致的误判，还是模型本身理解有误。

这里我还要强调一个技巧：日志字段一定要结构化，不要纯文本。纯文本日志在出错时很难程序化检索，而结构化的KV字段可以被监控系统直接消费并触发告警。我在模拟项目中吃过这个亏，早期用文本日志，出了问题全靠肉眼扫，硬生生把排查效率拖慢到原来的三分之一。

6.3 给第一次做Office多智能体系统的人四条建议

如果你准备开始做一个Office多智能体项目，我掏心窝子给你四条建议。

第一条，第一天就把日志和权限点埋好。权限点和结构化日志不是上线前的“锦上添花”，而是系统能不能活下来的地基。后期在已经运转的业务里补权限，代价是巨大的，因为所有人都已经习惯了原来的调用方式。

第二条，先用两个Agent、一条流程、三个工具跑通，再去扩展。多智能体的复杂度是指数增长的，你一开始就上八个Agent，只会得到一个“看起来热闹但每一步都在出问题”的系统。先用最少的组合把一条完整链路走通，你要验证的核心是编排逻辑和状态管理跑不跑得顺，而不是Agent数量多不多。

第三条，同步链路稳定之前，不要碰订阅机制。异步事件看似方便，但一旦没有完善的聚合和幂等机制，就是一场灾难。先把“用户让Agent做什么Agent就做什么”的确定性链路做到极致，再往系统加“系统自己感知变化并主动响应”的异步能力。

第四条，角色和工具描述要用标准化配置，不要散落在代码分支里。这一步的价值不在于“代码整洁”，而在于权限能被统一审计，角色能被快速调整，模型能被随时替换。Office场景的业务变化频率远高于你的预期，没有配置化，你迟早会陷入一改一句业务规则就要发版的泥潭。

我在实际搭建这套Office多智能体系统时最大的体会是：多智能体的复杂性是呈指数增长的，架构设计的功劳不是消灭这种复杂性，而是把复杂性关进一个可控的格子里。这个格子是角色配置、是状态表、是工具注册中心、是审批闸门、是日志系统。它们每一个单独看都谈不上惊艳，但组合在一起，就成了支撑一套办公多智能体系统稳定运行的骨架。

这个系列接下来会沿着编排器设计、工具接入、订阅机制、记忆与权限、可观测性这几条线继续拆。下一期我打算直接从编排器的任务分解逻辑开始，把一棵任务树从根节点到叶节点的完整生成过程写出来。第一次动手做多智能体的朋友，可以先试着把我这篇里状态表和工具注册中心的模板拿过去，垫在你自己的设计文档里，跑不通的时候你会回来谢我的。