从单点助手到多Agent生态：跨平台AI编程智能体架构实践

如果一年前有人跟我说，AI编程的下一代形态不是某个更聪明的IDE插件，而是一群各司其职的智能体在一个系统里互相派活、接力完成任务，我大概率会觉得这是PPT里的故事。直到我们把代号为Agency Agents的跨平台AI编程智能体体系真正跑起来，才发现所谓"生态"不是营销词，而是被现实逼出来的工程结论。这篇文章不聊概念，只聊我们从单Agent工具跨到多Agent协作、从单一IDE入口跨到命令行/Web/CI多端接入之后，沉淀下来的架构分层和工程实践。

这套东西的核心价值很简单：让同一个AI编程能力不再被绑定在某一个编辑器或某一条聊天框里，而是同时存在于IDE插件、命令行工具、网页端和流水线任务中，所有入口共用一套任务编排和上下文记忆。换句话说，用户在IDE里让Agent写了个函数，回到CLI里还能追问"刚才那个函数的测试覆盖补了吗"，Agent记得，也接得住。适合正在搭AI编程工具链、做内部效率平台，或者被"多平台接入怎么做"卡住的技术团队参考。

1. 从"单点助手"到"智能体生态"：我们为什么重新设计整条链路

1.1 一次失败的"理想架构"经历

最早我们没想过搞什么生态。团队里几个人做了一个Agent原型，逻辑很直白：用户在一个IDE插件里提问，Agent把问题拼进提示词，调大模型，拿到代码改动后写回文件。Demo跑得很顺，但一放到真实项目里就露馅了。

真实场景是：用户让Agent"帮我把登录模块的重试逻辑重构一下，跑通测试，再顺手改掉日志里那个敏感信息泄露"。这个任务包含代码编辑、执行测试、跨文件检索、配置修改四个动作，而且动作之间有依赖。单Agent的做法是把所有指令、所有中间结果全都塞进一段上下文，模型越到后面越糊涂，不是忘了前面的约束，就是把测试输出里的无关信息当成结论。最后表现就是——任务失败，所有入口一起失败，根本没有容错空间。

那次失败让我意识到一个问题：单个智能体不是不够强，而是被"什么都要自己做"拖垮了。人的团队怎么工作，Agent体系就应该怎么工作——有人拆需求，有人写代码，有人检查结果，有人跑测试，各干一段，把结论往下游传。这是Agency Agents架构设计的原点。

1.2 多平台带来的三个隐藏痛点

架构重新设计之前，我们先花了几天调研各端接入的真实需求。结果发现，所谓"跨平台"，真正要解决的不是多写几个客户端那么简单，而是三个隐藏痛点。

第一，入口割裂。同一个用户可能在IDE里发起任务，在手机网页上看结果，在CLI里做二次确认。如果每个入口都独立维护一套会话和记忆，用户就要反复解释上下文，Agent永远"没记住你上一步说了什么"。这是体验层面最致命的割裂。

第二，任务接力无人管理。IDE里的Agent执行到一半，用户临时要去开会，到CLI里想看看进度，发现没有入口能查询"当前有哪些任务在跑、跑到哪一步、卡在哪"。因为没有统一的任务状态模型，任何端都拿不到全局视图。

第三，能力不对等。IDE端有完整的文件读写权限，CLI端却能执行shell命令，Web端只能做只读问答。如果各端直接调用同一个Agent内核而不做权限分级，要么功能被压到最低，要么安全上捅出大篓子。

这三个痛点决定了技术架构的大方向：必须把"Agent核心"和"平台外壳"彻底分层，必须在最底层统一会话、任务、上下文、权限四套数据模型。

1.3 Agency Agents设计目标

在动工之前，我们把目标收敛成四条，后面所有设计决策都围绕它们展开。

• 可插拔的平台适配层：新增一个入口，只写适配器，不动核心逻辑。
• 统一的任务模型：任何端发起任务，都走同一条任务队列和状态机。
• 分级权限体系：Agent在什么端、以什么身份、能执行什么工具，都由授权策略决定。
• 全程可观测：每次模型调用、工具调用、文件变更都有trace，能回溯任何一次"奇怪行为"。

这套目标听起来不复杂，但真做起来，每一层都有不少细节。下面按架构分层讲。

2. 总体架构分层：接入层、编排层、执行层、记忆层的边界划分

2.1 四层架构总览

Agency Agents最终稳定下来的架构是四层，每一层职责单一，层与层之间通过明确的数据结构通信。先看整体分层：

接入层往编排层传递的不是"用户问题原文"，而是一个标准化的事件对象：平台标识、用户身份、会话ID、消息类型、意图优先级。编排层往执行层下发的是"工具调用指令"，执行层从来不直接接触模型对话，只负责把工具执行结果变成结构化返回值。

这个边界划分是我踩了很多坑后才想通的。最初我们让Agent直接调工具，结果模型生成的工具参数千奇百怪，执行层又要解析又要容错，代码乱成一团。后来把所有工具调用收敛成编排层的受控指令，模型只负责"决定要做什么并给参数"，执行层只负责"按规则做"，职责一下清爽了。

2.2 接入层：统一网关与平台适配器

接入层最容易犯的错误是让每个端自己封装一遍Agent调用逻辑。我们一开始就约定：各端只做协议翻译，不做任何业务决策。

IDE插件写得最多。它通过LSP协议监听文件变更和光标位置，用户选中代码右键触发"让Agent解释这段代码"时，插件把选中文本、文件路径、仓库信息打包成事件，通过JSON-RPC发到网关。网关做三件事：鉴权、限流、把事件转成内部统一格式。

CLI端则轻量得多。它本质是一个做了JSON-RPC封装的终端程序，用户输入query命令，CLI把命令转成执行计划描述，提交到编排层后阻塞等待结果。这里有个体验细节：CLI端要支持流式输出，Agent每生成一个中间动作，网关就通过SSE把进度推回来，用户能看到"正在读取文件""正在运行测试"这样的实时状态，而不是傻等一个最终响应。

Web端和CI端的适配器就更薄了。Web端走SSE，CI端走Webhook，CI里的事件通常是"构建失败，请定位问题"，适配器把它转成一个debug目标任务，和IDE里发起的任务走同一个队列。接入层真正的工作量都集中在网关的协议映射表上——不同端的事件字段语义有差异，网关统一规约再往下层送。

2.3 编排层：Agent运行时与任务队列

编排层是整个系统的心脏。每个任务在进入队列时会生成一份标准元数据，结构大致如下：

{ "task_id": "task_8f3a2c9e1b", "session_id": "session_0a11f2", "platform": "ide", "user_id": "u_1024", "status": "queued", "intent": "refactor_login_retry", "steps_planned": ["analyze", "edit", "test", "review"], "current_step": "analyze", "context_snapshot": "snapshot_7f2a", "approval_required": false }

状态流转是硬编码的状态机：queued -> running -> waiting_review -> succeeded，任何一步失败都会进入failed，并触发重试策略或人工介入事件。有一点值得强调：任务不只是"一个问题"的答案，它是拥有完整生命周期的工作单元。

调度器从队列里拿出task_id后，先根据intent决定走哪条Agent流水线。比如refactor_login_retry会被拆成四步：先由一个规划Agent分析代码结构，生成最小改动方案；再交给编码Agent执行；编码Agent完成后由测试Agent跑相关用例；最后由审阅Agent检查diff，如果发现问题就回到编码Agent。这个编排逻辑不是写死在代码里的嵌套循环，而是由一个"流程定义表"驱动——每类任务在表里注册自己的步骤序列和每个步骤的Agent角色。

2.4 执行层：命令白名单、工具沙箱与结果回传

执行层是Agent"动手"的地方，也是安全压力最大的地方。我们设计了工具注册表，所有Agent可用的能力都是预先注册的函数，每个函数有三部分：执行器实现、参数schema、权限要求。

# 工具注册表示例（简化） TOOL_REGISTRY = { "read_file": { "executor": read_file_impl, "schema": {"path": "string", "line_range": "string?"}, "permission": "reader", }, "edit_file": { "executor": apply_patch_impl, "schema": {"path": "string", "patch": "string", "description": "string"}, "permission": "editor", }, "run_command": { "executor": exec_in_sandbox_impl, "schema": {"command": "string", "timeout_ms": "int"}, "permission": "executor", }, }

这个设计的核心想法是：Agent能做什么，不是由模型当时的想法决定的，而是由工具注册表决定。模型只能从注册表里选已有工具，不能发明新工具。参数先过schema校验，再过权限校验，最后才进沙箱执行。

工具执行结果统一封装成结构体，包含标准输出、退出码、文件变更摘要、耗时。这些结果会同时进入两处：回传给编排层供Agent下一步决策，写入记忆层供后续任务引用。这样避免让Agent每次都要从头重新读取整个文件，效率和安全都兼顾。

2.5 记忆层：项目上下文索引与长期记忆

记忆层解决的是"Agent到底记得多少"的问题。我们做过统计，一次中型重构任务，Agent需要读取的文件可能超过20个，如果每个文件全文都塞进上下文，一次任务要消耗几十万token，成本直接失控。

所以记忆层不存全文，存的是三层结构：项目索引、变更集、会话快照。项目索引由后台任务定期扫描仓库生成，记录文件树、每个文件的语义摘要、关键函数定位点，用向量化存入检索库。Agent请求上下文时不是"给我整个仓库"，而是"定位登录模块里与重试相关的文件"，靠索引定向检索。

变更集则是每次工具调用产生的diff和文件变化记录，存成不可变对象，用于审计和回滚。会话快照记录多轮对话中Agent关键决策的摘要，用于跨端恢复上下文。这三层结构有个好处——记忆和模型解耦，换模型、清prompt，记忆还在。

3. 跨平台状态同步：同一个Agent如何在不同入口之间无缝接力

3.1 会话状态机：一个任务，多个入口

"在IDE发起，在CLI查看，在Web审批"是我们的核心使用场景。要实现这点，光有任务队列还不够，必须将会话状态和任务状态分开管理。

会话是一个长期存在的主体，可以跨多个任务。用户在IDE里说"把登录模块的重试逻辑重构一下"，这是一个新任务；用户在CLI里问"刚才那个重构任务里改过哪些文件"，实际上是在查询同一个session_id下关联的任务历史。每个入口发起请求时，会在事件头里带上session_id，网关用这个ID把请求路由到对应的会话上下文。

为了支撑多入口并发访问，会话对象附带了一个乐观锁：每次对话追加时检查版本号，如果用户在CLI看到了旧版本上下文又提交了新消息，版本冲突时系统会提醒"上下文已更新，请刷新"。在真实协作中，这个版本号机制比想象中更常用——因为经常出现开发者一边在IDE里看Agent干活，一边用手机端继续补充指令的情况。

3.2 事件总线与任务消息的可靠传递

跨端状态同步的底层依赖是消息传递。我们选型时没有一上来就上重型中间件，而是先用内置的轻量消息总线顶着，后续任务量大了再替换。每类事件都有固定的topic：task.progress、task.failed、tool.executed、human.approval.required。

这里关键的是事件顺序和幂等设计。任务A生成过程中会连续发出多个progress事件，如果消费者处理顺序倒灌（后发事件先到），状态机就会错乱，把已完成的任务回退成运行中。我们的做法是给每个事件加上自增序号，消费端维护一个"当前已处理最大序号"，丢弃乱序事件，再用事务保证最后落库的状态一致。幂等性则靠task_id+event_seq做唯一键，重复投递不会产生重复副作用。

3.3 上下文打包与解包：跨端对话保持

Agent在实际对话时只保留精简后的上下文，完整数据留在记忆层。每次跨端切换，我们都会做一次"上下文打包"：把项目索引命中结果、相关文件摘要、当前任务进度、此前关键决策记录合并成一个context_snapshot，回传给新入口的客户端。

这个快照不是一次性传输，而是分片推送——先推任务级摘要（用户立刻能看到"任务在跑第2步"），再推代码级细节（用户展开某个文件才能看到），最后推补充材料。这样避免了"切一个平台就等十几秒加载"的糟糕体验。有一次用户从Web端接管CLI里一个长时间运行的任务，他打开页面时先看到任务进度条，等他点进代码详情时相关文件摘要才慢慢加载到位，整个接管流程非常顺滑。

3.4 同步踩坑记录：乱序与连接中断

跨端同步里最严重的踩坑是连接中断导致任务卡死。用户从IDE发起长任务后在CLI查看，CLI进程被用户Ctrl+C中断，断开的连接会把正在运行的任务一并取消。最初我们图省事，把会话连接和任务生命周期绑定，结果就是中断即失败，体验极差。

后来把任务和连接彻底解耦：任务运行状态持久化，连接只是"观察者"。断线后任务继续跑，重连时根据游标位置补发遗漏事件，而不是重头推全量。这个改动虽然增加了事件存储的开销，但换来一个关键能力——任何入口现在都能安全退出，任务状态不会丢。

4. 多Agent任务编排模式：从"链式"到"事件驱动"

4.1 串行编排：单Agent逐步执行与回调

第一版编排器是最朴素的串行模式：一个Agent收到任务，自己拆解出步骤列表，然后一步步往下执行，每一步执行完后把结果追加到上下文里，继续下一步。这种模式适合流程固定、依赖关系强的场景，比如"版本升级后的自动化回归测试修复"。

但串行模式有一个天然缺陷：Agent如果中途判断错了方向，后续步骤都基于错误前提展开，直到最后审阅环节才会暴露，浪费大量执行时间。而且单Agent上下文会越积越长，越往后越容易忽略早期约束。我们后来把串行模式限制在"短链路任务"里，凡是超过四步的任务都强制走多Agent编排。

4.2 规划-执行-审阅循环：让"拆任务"这件事从对话里独立出来

真正稳定的任务编排是规划、执行、审阅三个角色分工的循环。规划Agent负责分析需求，产出结构化的任务清单：

{ "plan_id": "plan_e42b", "goal": "refactor_login_retry", "steps": [ {"id": 1, "type": "analyze", "target": "retry_logic.py", "output": "call_graph"}, {"id": 2, "type": "edit", "file": "login_client.py", "patch_ref": "patch_01"}, {"id": 3, "type": "test", "command": "pytest tests/test_login_retry.py", "timeout_ms": 120000}, {"id": 4, "type": "review", "diff_ref": "diff_01"} ] }

规划Agent只做分析，不做编辑。它把需求变成任务清单后，任务清单进入队列，编码Agent才登场。编码Agent拿到的是已经拆好的步骤，而不是杂乱的原始需求，它的上下文里少了大量"理解需求"的负担，可以专心改代码。它改完一个文件，测试Agent登场跑测试，测试报告作为结构化数据传给审阅Agent。审阅Agent检查diff时如果发现问题，会把问题描述作为新的子任务重新丢回队列，编码Agent收到后针对性修复。

这个循环的精华在于"每次只给Agent减负后的上下文"。规划Agent只负责看到全局，编码Agent只负责看到要改的文件，测试Agent只负责看到测试命令和相关输出，审阅Agent只负责看到diff和测试结果。每个Agent看到的上下文都最小化，模型表现反而更稳定。

4.3 事件驱动协作：规划Agent发"订单"，编码Agent消费"订单"

当任务量上来之后，队列里的任务互相之间还有依赖，串行循环就不够用了。我们引入事件驱动协作：规划Agent产出任务清单后，不是自己顺序消费，而是把每个步骤作为一个独立消息发布到对应Agent的任务队列里。每个Agent都是消费者，处理完自己的部分后，把结果事件发回总线，下游Agent监听事件后接力。

这种模式的调度比串行灵活太多。比如测试Agent发现某个失败用例需要改测试代码本身，它不是自己动手改，而是发出一个"fix_test_fixture"事件，测开Agent消费这个事件，修完再发"test_fixture_fixed"事件，测试Agent重新跑。整个过程没有全局指挥官，各Agent按事件契约协作。

当然事件驱动也带来了可观测性压力。每个事件都需要追踪链路，我们给每个原始任务分配一个trace_id，所有派生子任务都继承这个ID，这样任何时候输入trace_id，整个协作图谱都能完整还原出来。

4.4 失败重试与人工介入闸门

多Agent协作里，失败重试不能简单"同一件事再跑一遍"，我们先分类再决定策略。

• 可重试失败：沙箱超时、依赖服务暂时性不可用。用指数退避重试，最多三次。
• 不可重试失败：模型输出格式校验不通过、工具参数校验不通过。直接fail，同时保留原始请求供人工排查。
• 高风险失败：涉及删除、改权限、对外发消息等动作，失败后不自动重试，而是触发人工审批事件。

人工介入闸门是一个独立机制：Agent在执行某些工具之前，如果权限校验发现操作属于高影响类别，系统不会直接拒绝，而是发出human.approval.required事件，把命令、影响面、风险等级打包推给用户审批。用户在CLI里输入approve或reject，审批结果作为事件写回总线，Agent解除阻塞继续执行。这套机制在后续安全部分还会细说。

5. 上下文工程与成本控制：Agent上下文就是你的内存条

5.1 token消耗的"大头"在哪

我们把一次中型任务的实际token消耗拉出来看过，分布让所有人都很意外：

项目文件全文是最贵的。一个近千行的模块文件，读一次就要消耗近万token，而Agent往往只关心其中某一个函数。context工程的核心目标就是把这个48%尽量压掉。

5.2 项目索引：不是搜"关键词"，而是定位"语义块"

我们废弃了"直接把整个文件喂给Agent"的做法，改为构建细粒度的项目索引。索引的最小单位不是文件，而是语义块——一个函数、一个类、一个配置段落。后台任务解析AST生成语义块清单，每个语义块附带一段向量表示，存进检索库。

Agent需要上下文时，先进行语义检索：比如"登录重试的指数退避逻辑在哪个文件哪个函数"，检索库返回命中的函数名、文件路径、行号范围和一段摘要。这段摘要通常只有几百token，远比整个文件划算。必要时Agent再通过read_file工具读取完整文件指定行区间。实测下来，同样的任务，token消耗从5万降到2万左右，效果还更稳定，因为Agent不会被无关代码干扰。

5.3 上下文裁剪策略：不是所有历史都值得留

多轮对话历史同样需要裁剪。我们采用三级历史策略：

• 全量历史：保留在记忆层，任何时候可回溯。
• 近期窗口：最近五轮对话原样给Agent，保证连续性。
• 远期摘要：更早的对话压缩成要点列表，比如"用户已确认采用重试间隔翻倍方案"。

裁剪策略的核心是把"事实"和"过程"分开。Agent最终执行靠的是结论性事实（哪个方案、哪个文件、哪个约束），过程性讨论（用户吐槽、需求变更的来回拉扯）对执行没有帮助，全部摘要化即可。有一次我们忘记对某类长对话做摘要，Agent在决策时被一段早已作废的早期需求带偏，白白多执行了一轮错误修改。从那以后，凡是超过五轮的多轮任务，强制前置一次"历史摘要压缩"。

5.4 实测成本模型：一次中型任务的Token构成

分享一组我们内部测算的数据（基于自建模型网关的计费口径）：一次包含规划、编码、两次测试、审阅的典型重构任务，总token约在18万左右。其中规划Agent 3万、编码Agent 6.5万、测试Agent 4.5万、审阅Agent 4万。

这个数字比单Agent方案的35万降低了近一半，原因是多Agent各取所需，每个Agent只保留自己职责相关的上下文。成本控制不是抠门，而是让token花在刀刃上。如果发现编码Agent的token异常增高，通常意味着索引没有命中正确的语义块，Agent在"大海捞针"式读文件，这时优先优化索引而不是降模型档位。

6. 安全防线：Agent能跑命令，谁来管它？

6.1 权限模型：最小权限不是理论

Agent体系里有个很容易被忽视的事实：每个Agent都有自己的权限边界，不是系统管理员。我们给Agent定义了三种角色：reader（只读问答）、editor（可改文件）、executor（可跑命令）。角色在任务创建时由发起者选定，不同入口的默认角色不同——IDE端默认editor，CLI端默认executor，Web端默认reader。

这个默认角色设计来自真实需求：用户在IDE里希望Agent帮忙改代码，所以给editor；用户在CLI里问问题不希望它擅自改仓库，所以给reader；CI里的Agent需要跑构建命令，所以给executor。角色决定了Agent能调用哪些工具、能访问哪些路径。一个reader角色的Agent即使被诱导发起edit_file调用，执行层也会直接拒绝。

6.2 命令白名单与参数校验

executor角色能跑命令，但跑什么命令有硬性约束。白名单里只有明确安全类别的命令：读文件、跑测试、构建、解析AST、格式化代码。被明确禁止的包括：删除命令、递归写全局目录、外网请求、包管理器全局安装。

光靠字符串黑名单挡不住问题。我们给每条命令做参数级校验，用解析器而不是字符串匹配。比如run_command接收到的command先经过一个AST解析器，识别出实际执行的可执行文件和参数列表，再对照策略文件判断。路径参数还要做越界检查——即使用户合法地让Agent清理临时文件，也只允许在仓库目录或指定的临时目录范围内，仓库之外的路径一律拒绝。

6.3 沙箱执行环境与审计日志

所有executor角色的命令都在沙箱级别执行，不是直接在开发者机器上跑裸命令。我们用的是进程级沙箱：隔离文件系统视图、限制网络访问、限定CPU和内存配额。Agent跑测试或构建时，如果在沙箱里意外执行了危险操作，影响范围被封死在沙箱内，不会波及宿主机。

审计日志是另一条必做的防线。每个工具调用都记录：调用时间、用户会话、Agent角色、工具名、参数列表（涉密参数脱敏）、执行结果哈希、触发方式。审计不是为了追责，而是为了能回答"这个Agent为什么做了这个操作"。有一次用户反馈某文件被意外改动，我们靠审计日志还原了完整链路：测试Agent在分析测试报告时误将输出中的建议当成指令，执行了不相关的edit_file。如果没有审计，这个Bug几乎无法定位。

6.4 一次真实的危险操作拦截

这块想分享一个具体案例。某开发者让CLI端Agent"清理项目里那些没用的构建产物目录"，Agent规划后准备执行一条命令，语义上等价于"递归删除dist和build目录"。参数校验时发现了一个风险点：build目录的路径解析结果指向了仓库外的共享编译目录，不是项目本地的build。

系统没有直接执行，而是发出human.approval.required事件，把解析出的真实路径、风险等级、影响范围推给了开发者。开发者看了一眼立刻明白：他的环境变量把BUILD_DIR指到了公共目录，Agent是根据那个变量推导出来的路径。他在CLI里reject掉，然后修正了环境变量配置。这个案例给我的体会是：Agent本身没有恶意，但它无法判断"用户口中的目录"和"系统解析出的目录"是否一致，参数校验这一层必须有。权限系统不是用来防恶意的，是用来防意外的——AI的意外往往比人为失误更隐蔽。

7. 踩坑清单与调试手段：给正在搭建同类系统的你

7.1 Agent"自说自话"：模型输出格式校验

多Agent协作里，Agent之间的通信全靠结构化协议。最开始我们吃了大亏：模型在返回工具调用指令时，偶尔会在JSON里夹带解释性文字，比如"好的，这是我生成的调用：{"tool": "edit_file", ...}"。下游解析器一看到非JSON内容就报错，整个任务链断裂。

解决思路是双层校验：先做格式宽松提取（从模型输出里定位JSON块再做解析），再用JSON Schema做字段级校验。更重要的是，校验失败后不能直接fail，而是把错误信息回传给Agent，让它自己修正格式后重试。这个"自修复循环"把格式引发的失败率从11%压到了1%以下。如果Agent连续三次格式校验失败，系统会自动降级为人工处理，防止无限循环空转。

7.2 工具返回超长导致上下文爆掉

测试命令的输出可能是几千行日志，不能全量塞进Agent上下文。我们的方案是给工具结果增加"摘要器"：每种工具类型配一个专用的摘要函数。测试命令的结果只提取：通过/失败、失败用例列表、断言错误摘要、耗时；文件读取的结果只提取：路径、行数、函数签名列表。

工具原始输出的完整内容仍然会写入记忆层存储，Agent需要细看时可以通过read_log工具主动读取指定区间。这样既保证上下文精简，又不丢失原始信息。有一次排查一个罕见的并发失败，Agent最初的摘要里只有"test_flaky_race failed"，后来人工靠原始日志定位到是环境问题，而不是代码Bug——如果当初为了省存储直接丢弃原始日志，这个结论根本得不出。

7.3 多Agent同时改一个文件的冲突

事件驱动协作模式放开之后，冲突问题随之而来。两个子任务可能同时要编辑同一个文件，各改各的，后写回的覆盖先写回的，diff丢失。

我们的解法分两层。第一层是文件级锁：工具注册表在执行edit_file之前先检查目标文件是否被其他Agent持锁，持锁则任务重排。第二层是Git暂存区快照机制：每次编辑前把当前文件版本哈希存进变更集，写回前校验哈希是否与预期一致，不一致直接返回冲突错误，而不是强行覆盖。冲突错误会触发上游规划Agent重新规划，把两个有冲突的编辑任务串行化。

7.4 可观测性：把每一步都记录下来

最后强烈建议，从一开始就要把可观测性做成系统的一部分，而不是事后补。Agency Agents里每条任务链路都有一个trace记录，包含事件时间线、每个Agent的输入输出摘要、token计数、工具调用耗时、重试信息。调试的时候输入一个trace_id，就能把一次完整任务的所有环节按时间展开。

我们甚至做了一个简单的时间线视图：横轴是时间，纵轴是Agent角色，每个节点是一个事件块，点击能看到具体参数。这个工具让排查效率提升了不止一个量级。有一次线上问题导致Agent循环执行推理，全靠trace里暴露的"同一规划步骤反复进入队列"数据才定位到调度器的去重缺陷。

我自己做了几百次任务调试后的最大心得是：这套系统的复杂度已经从"模型会不会写代码"转移到了"多个Agent协作者之间的通信是否可靠"——所以几乎所有调试手段，本质上都是让Agent之间的协作过程变透明。如果你也在搭类似的跨平台AI编程体系，建议不要急着追求复杂的模型能力，先把任务模型、上下文裁剪、权限边界这三件事做扎实，它们才是多Agent生态真正的地基。