如果一年前有人跟我说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最终稳定下来的架构是四层每一层职责单一层与层之间通过明确的数据结构通信。先看整体分层层级职责关键组件典型接口接入层承接各端请求做协议转换平台适配器、统一网关LSP / JSON-RPC / SSE / Webhook编排层管理任务生命周期、分发Agent指令任务队列、状态机、调度器任务元数据JSON执行层调用工具、运行命令、落盘文件工具注册表、沙箱执行器execute_tool / run_command记忆层持久化上下文、项目索引、任务历史向量索引、变更集存证、会话快照context_snapshot / search_context接入层往编排层传递的不是用户问题原文而是一个标准化的事件对象平台标识、用户身份、会话ID、消息类型、意图优先级。编排层往执行层下发的是工具调用指令执行层从来不直接接触模型对话只负责把工具执行结果变成结构化返回值。这个边界划分是我踩了很多坑后才想通的。最初我们让Agent直接调工具结果模型生成的工具参数千奇百怪执行层又要解析又要容错代码乱成一团。后来把所有工具调用收敛成编排层的受控指令模型只负责决定要做什么并给参数执行层只负责按规则做职责一下清爽了。2.2 接入层统一网关与平台适配器接入层最容易犯的错误是让每个端自己封装一遍Agent调用逻辑。我们一开始就约定各端只做协议翻译不做任何业务决策。IDE插件写得最多。它通过LSP协议监听文件变更和光标位置用户选中代码右键触发让Agent解释这段代码时插件把选中文本、文件路径、仓库信息打包成事件通过JSON-RPC发到网关。网关做三件事鉴权、限流、把事件转成内部统一格式。CLI端则轻量得多。它本质是一个做了JSON-RPC封装的终端程序用户输入query命令CLI把命令转成执行计划描述提交到编排层后阻塞等待结果。这里有个体验细节CLI端要支持流式输出Agent每生成一个中间动作网关就通过SSE把进度推回来用户能看到正在读取文件正在运行测试这样的实时状态而不是傻等一个最终响应。Web端和CI端的适配器就更薄了。Web端走SSECI端走WebhookCI里的事件通常是构建失败请定位问题适配器把它转成一个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 事件总线与任务消息的可靠传递跨端状态同步的底层依赖是消息传递。我们选型时没有一上来就上重型中间件而是先用内置的轻量消息总线顶着后续任务量大了再替换。每类事件都有固定的topictask.progress、task.failed、tool.executed、human.approval.required。这里关键的是事件顺序和幂等设计。任务A生成过程中会连续发出多个progress事件如果消费者处理顺序倒灌后发事件先到状态机就会错乱把已完成的任务回退成运行中。我们的做法是给每个事件加上自增序号消费端维护一个当前已处理最大序号丢弃乱序事件再用事务保证最后落库的状态一致。幂等性则靠task_idevent_seq做唯一键重复投递不会产生重复副作用。3.3 上下文打包与解包跨端对话保持Agent在实际对话时只保留精简后的上下文完整数据留在记忆层。每次跨端切换我们都会做一次上下文打包把项目索引命中结果、相关文件摘要、当前任务进度、此前关键决策记录合并成一个context_snapshot回传给新入口的客户端。这个快照不是一次性传输而是分片推送——先推任务级摘要用户立刻能看到任务在跑第2步再推代码级细节用户展开某个文件才能看到最后推补充材料。这样避免了切一个平台就等十几秒加载的糟糕体验。有一次用户从Web端接管CLI里一个长时间运行的任务他打开页面时先看到任务进度条等他点进代码详情时相关文件摘要才慢慢加载到位整个接管流程非常顺滑。3.4 同步踩坑记录乱序与连接中断跨端同步里最严重的踩坑是连接中断导致任务卡死。用户从IDE发起长任务后在CLI查看CLI进程被用户CtrlC中断断开的连接会把正在运行的任务一并取消。最初我们图省事把会话连接和任务生命周期绑定结果就是中断即失败体验极差。后来把任务和连接彻底解耦任务运行状态持久化连接只是观察者。断线后任务继续跑重连时根据游标位置补发遗漏事件而不是重头推全量。这个改动虽然增加了事件存储的开销但换来一个关键能力——任何入口现在都能安全退出任务状态不会丢。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消耗拉出来看过分布让所有人都很意外消耗来源占比说明系统提示词与工具定义12%每个Agent都要注入的角色和行为规范项目文件全文48%最容易被忽略的大头一读就是几千行历史对话记录25%多轮沟通的全量保留越长越吃工具返回结果15%测试输出、命令日志往往远超预期项目文件全文是最贵的。一个近千行的模块文件读一次就要消耗近万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端默认editorCLI端默认executorWeb端默认reader。这个默认角色设计来自真实需求用户在IDE里希望Agent帮忙改代码所以给editor用户在CLI里问问题不希望它擅自改仓库所以给readerCI里的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生态真正的地基。