跨平台AI编程智能体Agency Agents：四层架构设计与工程实践

在AI辅助编程已经铺开两三年的今天我发现一个挺尴尬的现象工具越来越强但各自的生态却越来越封闭。某天你可能在终端里用一套智能体写脚本在IDE里又是另一套配置到了CI流水线里还得再写一套。项目一多、团队一散这些“智能体”就像各自为战的散兵游勇完全没有形成合力。我去年下半年开始折腾一个名叫“Agency Agents”的跨平台AI编程智能体生态项目目的就是把散落在不同环境里的编程智能体统一起来让同一套逻辑能在终端、IDE、Web甚至移动端跑起来。这篇文章就把我拆解架构、跑通工程实践的完整过程整理出来踩过的坑、想明白的道理、可以直接抄的代码都在里面了。1. 项目起源AI编程工具碎片化带来的真实麻烦1.1 三个让我受不了的典型场景第一个场景是本地开发。我习惯在终端里用CLI模式的智能体做代码重构它会自己读取项目结构、分析依赖、批量改文件。但一旦切到IDE里调试某个具体报错我又得把同一段上下文重新描述一遍IDE里的智能体对我的项目几乎一无所知。第二个场景是团队协作。代码仓库里有几个人提交了不同的AI辅助配置比如私有的提示词模板、自定义工具定义有人用的是A平台有人用的是B平台结果CI流程里根本没法统一跑这些智能体逻辑。代码审查时想调一个历史会话还得问对方用的是哪个版本的Agent。第三个场景是跨端需求。有一次在某外部项目里我需要提供一个“能让非技术同事也用AI问代码库”的入口。最合适的载体是Web页面但当时已有的智能体都是绑定在本机终端的想把它变成服务得重写一遍业务逻辑。三个场景综合下来问题就很直白了智能体的核心能力规划、调用工具、读懂上下文应该和载体平台解耦。Agency Agents这个项目的出发点就是把这套核心能力抽出来做成一个可以挂在任何平台外壳下的“大脑”。1.2 项目名里的三个关键词怎么理解“Agency”不是“代理服务器”那个代理而是强调智能体具备的自主行动能力它能自己拆任务、自己选工具、自己决定下一步干什么。“Agents”强调多智能体。不是一个大号单体机器人而是一群各自分工的智能体负责写代码的、负责跑测试的、负责查文档的、负责审查提交的各干各的活。“跨平台生态”意味着这套智能体不绑定终端、IDE、云端服务等任何一种形态而是通过适配层接驳所有平台外壳。如果你没有在这个领域踩过坑可能觉得这不就是抽象一层接口而已吗但真正做进去才发现难的不是接口抽象而是每个平台对“上下文”“工具调用”“权限限制”这些基础概念的认知完全不一致。架构设计的功夫基本都花在给这些不一致找统一模型上了。2. 架构设计把“大脑”和“身体”拆开2.1 总览四层分离而不是把功能堆在一起我最终采用的方案是四层架构核心智能层负责意图理解、任务规划、决策判断。这一层只依赖模型输入输出的标准格式不关心具体跑在什么平台上。工具执行层把代码搜索、文件读写、命令行执行、HTTP请求等能力封装成标准化工具。每个工具接收JSON格式的参数返回结构化结果。平台适配层这是“跨平台”的关键。终端、IDE、Web服务、移动端各有各的交互协议和权限边界适配层负责把平台事件翻译成核心层能理解的消息。编排协同层管理多智能体的生命周期、分配任务、合并结果、控制上下文窗口。为什么要强行分层我举个实际例子。最初我在IDE插件里直接调代码工具写了一个读取当前打开文件的函数后来发现Web端根本不存在“当前打开文件”这个概念。如果工具和平台强耦合这套逻辑就永远没法复用。分层之后“读取当前缓冲区内容”被抽象成“读取用户当前关注的文件”IDE适配器翻译成获取编辑器选中内容Web适配器翻译成读取前端传来的requestId对应的文件终端的适配器则直接读取终端工作目录下的指定文件。同一套核心逻辑三种完全不同的物理实现。2.2 跨平台适配层设计一张契约和图谱跨平台最容易翻车的做法是“两头各写一套命名都懒得对齐”。我的做法是先定一张平台能力契约表所有适配器都必须实现这些能力能力项统一语义终端CLI实现IDE插件实现Web服务实现获取用户上下文用户当前正在处理的任务信息从命令行参数和会话历史读取读取编辑器当前文件、选中内容从HTTP请求会话中解析展示进度向用户反馈任务进展终端输出流IDE右下角通知栏WebSocket推送 前端渲染确认操作高危操作征求用户确认交互式Y/N提示弹窗确认框点击按钮确认文件访问边界允许读写的目录范围需通过启动参数显式授权跟随IDE信任的项目目录固定在服务端配置的仓库白名单工具执行权限可调用的外部命令受沙箱白名单约束受IDE插件权限模型约束只能调用服务端预注册的API有了这张表写新的适配器就变成了“对着契约逐项翻译”的体力活核心层完全不用动。另外我还建了一张平台图谱记录每个平台的能力差异。比如终端平台天然支持交互式命令Web平台更适合异步任务队列IDE平台有事件驱动的特性。这样编排层拿到一个任务时可以优先选择能力匹配的平台执行而不是所有平台一刀切。2.3 为什么选适配器模式而不是插件模式社区里不少人是走插件模式核心定义一堆扩展点平台方根据扩展点写插件。我也尝试过但很快发现扩展点设计是个无底洞你永远不知道下一个平台需要什么新能力。适配器模式的好处是它面向的是“已存在的能力”做翻译而不是面向“未知的未来”做预留。每接入一个新平台时我只需要对照契约表逐项实现不存在的项直接标记为“不支持”就行核心层降级处理。打个比方插件模式像雇一堆厨师按照你的菜单做菜菜单必须先定完美适配器模式像请翻译官无论对方说哪国语言翻译官的职责都是把意思转成大家都能懂的普通话。工程上翻译官这种模式明显更稳。3. 核心智能层与工具执行层的工程落地3.1 从“提示词工程”升级为“结构化智能体协议”早期版本的智能体完全依赖提示词比如在系统提示里写“你是代码助手你拥有以下工具...”。这是能跑但工程化很差工具一变提示词就要改上下文一长模型就开始“忘”多个智能体之间根本没有协作基础。后来我把所有逻辑改成结构化智能体协议核心是一个标准消息格式{ role: agent, type: task_plan, task_id: 7f3a9c2, intent: refactor_module, memory: session://build-server/config, observations: [ {tool: file_search, result: src/legacy/api.py} ], decisions: [ { next_step: tool_call, tool: code_reader, args: {path: src/legacy/api.py, line_start: 1, line_end: 80} } ] }这个协议有几个实际好处。第一每个智能体的输入输出都是标准JSON不同智能体之间可以直接交换任务结果而不用解析自然语言。第二上下文管理可以精确裁切我只保留observations和decisions里的关键字段不需要每次把全部对话历史都塞给模型。第三工具调用天然具备可追踪性每一个决策步骤都对应着一次工具调用方便复现和调试。3.2 上下文管理窗口不够用是最大的现实困境做AI编程智能体用过的人都知道模型上下文窗口再大也不够用一个大型项目的核心文件加上反馈信息很快就能撑爆。在Agency Agents里我用了三层上下文管理热上下文当前任务正在直接引用的代码块、报错信息、用户最新指令始终保留在窗口内。温上下文任务相关的文件摘要、函数签名、依赖关系图以压缩摘要的形式按需加载。冷上下文历史会话、旧版本代码、备选方案存放在外部向量存储里通过检索召回。具体实现时我用了一个自动裁切器它在每轮对话结束后估算后续可能的工具调用需求把不再可能用到的超长日志、旧文件全文移出热上下文转成摘要存入温上下文。实测下来连续工作三小时以上的长会话效果保持稳定没出现过“忘事”的问题。这里有一个关键参数摘要触发阈值。我最初设置的是“当热上下文占用超过80%时开始压缩”结果发现为时已晚模型在70%左右就已经开始注意力涣散。后来调整成“当热上下文超过65%时就主动压缩温上下文”效果提升明显。经验值供参考不要等到窗口快满再压缩提前阈值至少留出20-30%的余量。3.3 工具执行层让智能体安全地操作外部世界工具执行层最需要关注的是两件事沙箱安全和错误恢复。沙箱安全方面我定义了一套基于策略的权限系统。每个工具调用都带有一个PolicyToken它声明了本次调用允许访问的路径、允许执行的命令、允许连接的网络端点。执行引擎在真正执行前先做校验不匹配的调用直接拒绝并返回原因。比如某次重构任务中智能体想读取~/.ssh/id_rsa这个路径但因为PolicyToken只授权了项目目录引擎直接拦截了这次调用然后自动换了一个替代方案读取项目内配置密钥整个流程没有中断用户体验完全无感。错误恢复方面我实现了可重试工具包装器。它把工具调用分成三类幂等的读文件、搜索、查询、有副作用的写文件、执行构建、外部依赖的HTTP请求、下载依赖。前两类失败后直接重试三次指数退避1s、2s、4s第三类失败后除了重试还会尝试切换备选端点。这个包装器还带来一个副产品所有工具调用的延迟、成功率、错误类型都自动记录了指标数据方便后续做智能体调度优化。class ToolWrapper: def __init__(self, executor, policy, retry_policy): self.executor executor self.policy policy self.retry_policy retry_policy def call(self, tool_name: str, args: dict) - ToolResult: # 1. 策略校验 decision self.policy.evaluate(tool_name, args) if decision ! allowed: return ToolResult(blockedTrue, reasondecision.reason) # 2. 带重试的执行 for attempt in range(self.retry_policy.max_attempts): try: return self._execute_with_timeout(tool_name, args) except RetryableError as e: wait_time self.retry_policy.backoff(attempt) logger.warning(retry tool%.8s attempt%d delay%.1fs, tool_name, attempt, wait_time) time.sleep(wait_time) return ToolResult(errorTrue, messagemax retries exceeded)这套设计跑起来之后整体稳定性上升非常明显。以前智能体一个文件搜索写错了路径整个任务链就断了现在有了自动换路径、重试、降级策略很多小错误都被静默消化了。4. 实操过程把整套系统跑起来4.1 环境准备与项目骨架本地开发我用了Python 3.11 TypeScript双栈。核心智能层用Python因为AI生态的模型SDK和工具库更全适配层和Web前端用TypeScript方便复用类型定义。如果你打算完全复刻这套架构不需要双栈语言统一更好我这里是因为历史包袱才混用。项目骨架大致如下agency-agents/ ├── core/ # 核心智能层 │ ├── protocol.py # 结构化智能体协议 │ ├── planner.py # 任务规划器 │ ├── context.py # 上下文管理器 │ └── memory.py # 冷热温三层记忆 ├── tools/ # 工具执行层 │ ├── registry.py # 工具注册表 │ ├── sandbox.py # 沙箱策略执行器 │ └── wrappers.py # 重试/超时包装器 ├── adapters/ # 平台适配层 │ ├── cli.py # 终端CLI适配器 │ ├── ide.py # IDE插件适配器 │ └── web.py # Web服务适配器 ├── orchestration/ # 编排协同层 │ ├── dispatcher.py # 任务分发器 │ └── agents.py # 多智能体定义 └── config/ └── platform_map.yml # 平台能力契约表项目级配置文件我用的是YAML原因是对非技术人员友好不会写代码的人也能看懂适配器开关。核心智能层的参数放在环境变量里比如ANTHROPIC_API_KEY、MODEL_NAME、MAX_TOKENS这些。4.2 核心层实现一个最小可用的规划器任务规划器是整个系统的大脑。它接收用户目标输出一个步骤列表。我写了一个简化版planner核心逻辑是三步模型分解目标 - 评估工具 - 生成计划。class Planner: def __init__(self, tool_registry, llm_client, context_manager): self.tools tool_registry self.llm llm_client self.context context_manager def create_plan(self, user_objective: str) - list[Step]: # 第一步让模型基于工具列表生成候选步骤 candidate_steps self.llm.generate_steps( objectiveuser_objective, available_tools[t.schema for t in self.tools.list_all()] ) # 第二步本地校验步骤的合法性 validated [] for step in candidate_steps: if step.tool_name not in self.tools.names(): step.status invalid_tool continue if not self.tools.get(step.tool_name).check_args(step.args): step.status invalid_args continue validated.append(step) # 第三步对合法步骤做动态顺序编排 return self._apply_dependencies(validated)这里有个关键点模型建议的步骤不能直接信必须做本地工具合法性校验。模型幻觉在纯聊天场景里只是“说错话”但在操作场景里是“删错文件”。我见过一个案例模型建议用rm -rf清理编译缓存结果路径拼接错误差点删了项目根目录。所以本地校验是安全底线不能省。4.3 适配层实现以IDE适配器为例IDE插件适配器算是整套系统里最复杂的适配器。它不仅要处理编辑器事件还要在UI上展示智能体进度和确认按钮。核心事件处理逻辑如下export class IDEAdapter implements PlatformAdapter { // 实现平台能力契约 async getCurrentUserContext(): PromiseUserContext { const editor vscode.window.activeTextEditor; if (!editor) return { type: empty }; return { type: file_focus, filePath: editor.document.uri.fsPath, selectedRange: editor.selection.isEmpty ? undefined : { start: editor.selection.start, end: editor.selection.end }, languageId: editor.document.languageId, }; } async showProgress(taskStatus: TaskStatus): Promisevoid { // 把任务状态渲染到IDE状态栏和输出面板 this.outputChannel.appendLine( [${taskStatus.agentId}] ${taskStatus.phase}: ${taskStatus.message} ); vscode.window.setStatusBarMessage( $(sync~spin) ${taskStatus.agentName} - ${taskStatus.phase}, 3000 ); } async requestConfirmation(action: HighRiskAction): Promiseboolean { const choice await vscode.window.showWarningMessage( 智能体想要执行: ${action.description}, { modal: true }, 允许一次, 始终允许, 拒绝 ); return choice ! 拒绝; } }IDE适配器里最需要注意的是不要抢占用户光标焦点。最开始我写的showProgress会直接聚焦输出面板结果用户正在写代码时面板突然跳出来体验特别差。后来改成状态栏和右下角通知只有用户主动点击才展开面板。4.4 编排层实践三个智能体的协作流程多智能体编排是这套系统最出彩的部分。我设置了三个智能体CodeWriter负责代码生成和修改TestRunner负责运行测试并反馈结果CodeReviewer负责审查代码变更给出改进意见一个典型任务的流程是这样的用户下达“重构某模块并保证测试通过”的目标dispatcher先把任务拆成重构、测试、审查三个子任务分别派给三个智能体。CodeWriter完成修改后TestRunner拿到变更文件列表自动运行相关测试。如果测试失败TestRunner把失败输出发回给CodeWriterCodeWriter根据反馈做修复。修复循环超过5次仍失败CodeReviewer介入分析根因生成报告给用户。这个流程跑起来之后我发现最重要的工程细节是每个智能体的任务描述必须带上明确完成标准。比如CodeWriter的完成标准是“没有语法错误且所有新增函数包含文档字符串”TestRunner的完成标准是“通过率98%或失败用例全部有明确根因”。没有明确完成标准智能体容易陷入自嗨式的无限循环。4.5 一次全链路实测记录我拿一个模拟购物系统做了一次全链路实测。最初状态有一个老旧的模块cart.py350行耦合严重。用户目标是“把结算逻辑拆出去提升可测试性”。实测过程记录如下Plannar生成计划读取cart.py全貌 - 提取结算相关函数 - 创建新模块checkout.py - 修改cart.py引用 - 运行测试CodeWriter执行步骤期间两处import路径出错第一处被本地校验拦下第二处触发了自动修复调用file_search找到正确模块路径后自动替换TestRunner运行测试后发现原有48个测试有3个失败失败原因不是新代码问题而是旧测试依赖了cart.py内部私有变量。TestRunner自动生成了修复建议CodeWriter按建议改了测试用例CodeReviewer最终给出报告建议把结算模块再拆出优惠券计算子模块标记为“可选项”全程用时4分32秒智能体之间完成了12次消息交换用户只做了一次确认操作这套实测让我确信只要核心层协议化、工具层沙箱化、适配层契约化多智能体协作的可靠性是可以达到生产可用水平的。5. 常见问题与排查技巧实录5.1 平台适配器失败率最高的三个坑路径分隔符与大小写问题。Windows的\和Linux的/是第一个大坑一开始适配层暴露给核心层的路径没有统一标准化结果在Linux上测试通过的工具调用到了Windows就全部404。后来我在适配层入口强制统一成POSIX风格再在物理执行前转换为平台本地路径问题解决。权限模型的语意差异。IDE的权限模型默认信任项目目录终端默认只信任当前工作目录Web默认只信任服务端配置的仓库白名单。开发时最烦的问题是IDE里能读的路径到了Web平台却被沙箱拦截。后来我把所有权限判定收敛到一个统一的策略评估器里三种平台共用一套规则配置只是物理执行器不同。事件驱动模型缺失。终端平台没有“文件变更”事件IDE有。这导致在IDE里智能体可以实时感知文件保存后自动运行测试终端里没有这个触发条件。解决方案是给终端适配器加了一个--watch模式轮询文件系统变更实测虽然笨一点但效果达标。5.2 上下文管理的常见故障速查表现象根因处理方案智能体重复读同一个文件温上下文摘要被裁掉了提升摘要最低保留时长控制在5分钟以上任务后期输出明显变差热上下文被无关日志污染给日志工具增加自动丢弃策略只保留最后50行两个智能体同时改一个文件缺少锁机制在工具层加文件级互斥锁冲突时报错重试工具返回内容过长没有对巨大输出做截断在wrapper返回前做结构化截断保留关键摘要5.3 调试智能体系统的独家技巧一个建议拿到智能体的全部工具调用日志再定位问题。很多开发者只盯着最终输出但智能体的错误几乎都发生在中间工具调用环节。我习惯把每一次工具调用传入参数、返回摘要、执行耗时、失败原因都落盘成JSONL日志出问题时直接按时间轴回放。另一个建议给每个智能体会话一个短ID。现在ID里只有时间戳看起来像20250614-153022-7f3a9c2但云端服务上多个会话并行时这个ID根本不够直观。我后来改成语义化ID比如refactor-cart-username-3a2f1一眼就能看出是哪个用户、哪个任务。还有一个对生产环境很重要的建议不要在本地测完就直接部署Web服务。本地终端和云端容器的文件系统、网络策略完全不一样至少要在容器环境里先跑一遍完整测试再开放外部访问。6. 后续扩展空间与实际体会6.1 可以继续做的三个方向多语言代码库支持当前工具层主要针对Python和TypeScript做了优化如果接Go、Rust或者Ruby的代码分析工具工具注册表需要再扩展一遍。持久化记忆仓库现在的记忆是任务级的跨任务没有累积。如果接一个长期记忆库让智能体记住团队的历史决策和偏好协作效率会更高。人机协作模式升级当前确认操作只支持“允许/拒绝”其实还可以做“修改后执行”让用户在智能体行动前微调参数减少来回操作。6.2 我实际使用中的几点体会第一跨平台架构的价值不在“一套代码到处跑”而在“一套逻辑到处复用”。核心智能层一旦稳定下来接新平台只是适配层的体力活这省下来的维护成本非常可观。第二上下文管理永远比你想的更早成为瓶颈。不管模型窗口参数怎么涨智能体对上下文的组织能力才是工程上限。花在压缩摘要、分层记忆上的时间回报率比调模型参数高得多。第三多智能体协作要克制。不是流程越长越智能每多一个智能体参与整个系统的延迟和不确定性就会增加一截。能用单个智能体解决的问题尽量别设计协作流程。第四安全策略宁可严格不可宽松。智能体能操作真实文件系统以后一个策略缺失的后果远比对话模型说错一句话严重。测试时故意给智能体一些越权路径看它会不会偷偷绕过沙箱——如果绕过成功说明策略实现有漏洞得回去修。这个项目从立项到跑通全链路前后花了大约两个多月的时间中间推倒重来了一次适配层设计。现在再看架构上的四个分层经住了考验工具沙箱和上下文管理也扛住了真实项目的压力。如果你也在做类似的跨平台智能体建议先不要急着写功能代码把平台能力契约表和策略评估器这两块地基打好后面会少走很多弯路。