1. ACI的组成
1.1. 观察面
ACI 决定模型看到哪些环境状态、以什么结构和精度呈现。网页可返回可访问树、DOM 或截图；代码环境可返回文件片段、诊断或测试结果。观察表示改变，任务难度也随之改变。
观察应保留可定位标识和版本信息，使后续动作能够引用稳定对象。只返回视觉描述或自然语言摘要，会丢失精确操作所需坐标。
可把 ACI 表示为观察函数 与动作解释器 。环境真实状态 往往过大， 选择并编码模型可见的 observation；模型在动作空间 中生成调用， 校验并作用于环境。改变 或 ，即使模型权重与任务不变，也会改变问题难度。ACI 因此是 Agent 实验条件的一部分，而非无关包装。
观察包含内容、定位和反馈三类信息。内容说明当前事实，定位让后续动作引用对象，反馈说明上一动作造成的差异。代码观察中的路径、行号与内容哈希，浏览器观察中的页面 URL、元素 ID 与页面版本，都承担定位职责。若接口只给摘要，模型可能理解页面含义，却无法准确选择要点击的对象。
1.2. 动作面
API 动作语义明确，Shell 组合能力强，GUI 覆盖面广但对页面变化敏感。系统可以混合接口，并按风险设置不同授权与验证路径。
动作面越开放，Runtime 越需要沙箱、资源限额和审计。通用 Shell 不应因为参数是字符串就绕过文件与网络权限。
动作设计要与模型擅长的输出结构匹配。人类可以在终端中记住当前目录、编辑器光标和滚动位置，语言模型每轮只能依据上下文恢复这些隐式状态。ACI 将隐式状态显式返回，提供带范围的查看、搜索和编辑动作，可以减少模型维护终端会话细节的负担。与此同时，过高层动作会把关键决策藏进工具，导致成功率无法归因。
API、Shell 与 GUI 可以形成分层回退。稳定业务优先使用语义 API；仓库探索使用受控搜索、补丁和命令；只有缺少 API 时才使用浏览器元素或视觉坐标。回退顺序进入策略与权限配置，模型不能因为 Shell 更自由就默认选择风险最大的接口。
2. 代码ACI与基础协议边界
2.1. SWE-agent的接口假设
SWE-agent 把语言模型视为一种新的计算机用户，为仓库导航、文件查看、搜索、编辑和命令执行设计专用 ACI。核心观察是，人类使用的裸 Shell 给模型留下大量隐式交互状态：命令输出可能过长，编辑依赖交互式程序，文件查看缺少稳定窗口，错误反馈也不总能提示下一步。专用命令限制输出并持续反馈当前文件与修改效果。
该系统用 GPT-4 Turbo 在 2294 个 SWE-bench 测试任务上解决 12.47%，论文摘要报告 HumanEvalFix pass@1 为 87.7%。在 300 个 SWE-bench Lite 实例上的 ACI 消融中，完整 SWE-agent 相比只使用默认 Linux Shell 的基线多解决 10.7 个百分点。Claude 3 Opus 搭配同一 ACI 解决 10.5%，说明收益并非完全绑定单一模型。
2.2. 文件查看与导航
代码 ACI 的查看动作应返回路径、行号区间、内容和剩余范围提示。固定窗口避免一次输出整个大文件，行号让模型产生精确补丁，内容哈希用于发现并发修改。搜索动作返回命中位置与少量上下文，模型再选择需要展开的文件。这样的渐进观察把 token 花在当前假设相关区域。
工作目录、当前文件和最近搜索可以作为显式状态显示，但不能成为唯一定位方式。动作参数仍使用完整或受控相对路径，防止会话状态与模型记忆不一致。符号搜索、文本搜索和文件树各有用途：符号搜索定位定义与引用，文本搜索查配置和错误字符串，文件树建立模块边界。将三者压成一个模糊 search 会使查询意图难以校验。
2.3. 编辑与反馈
编辑动作可以采用补丁、范围替换或带基线的字符串替换。无论形式如何，都要在执行前确认目标片段唯一且版本一致，执行后返回实际差异。整文件重写会放大未读区域风险，交互式编辑器又要求模型控制光标和模式；面向差异的动作更适合语言模型的文本生成能力。
编辑成功只证明文件发生变化。随后需要语法检查、相关测试和版本差异观察。若补丁匹配失败，错误应指出未找到、匹配多处或版本过期，而不是返回统一失败。精确反馈能让模型重新读取局部状态，不必猜测编辑器做了什么。
ACI消融怎样解释。
SWE-agent 的消融说明接口可改变端到端成功率，但不能简单理解成“新增几个命令即可”。专用命令同时改变动作粒度、输出长度、反馈格式与隐式状态，实验收益是这组设计的联合结果。复现时需要固定模型、提示、预算、任务子集和测试 Harness，并报告每项接口变更。
更严格的消融可以逐项替换：把文件查看改回 cat，把编辑改回流式编辑器，移除搜索结果行号，或取消输出截断。除了解决率，还统计无效命令、重复查看、编辑失败、平均步数与 token。这样才能判断哪一项降低了模型负担，哪一项只是改变运行成本。
MCP提供什么。
MCP 为客户端与服务器之间的能力发现、资源访问和工具调用提供共同协议。它降低集成成本，并让工具描述能够跨不同 Agent Host 复用。
协议消息仍需由 Host 绑定身份、权限和用户确认。远端服务器暴露一个工具，不代表当前任务自动获得调用权。
MCP不提供什么。
MCP 不定义应用的业务事务、完成条件、重试策略或风险分级。工具调用返回成功后，Host 仍需根据环境状态验证结果。
服务器返回的文本和资源也属于不可信输入。它们可以影响模型后续决策，因此需要来源标识、内容隔离和提示注入防护。
3. 浏览器环境中的ACI
3.1. Observation的多种表示
浏览器可提供原始 HTML、DOM、可访问树、截图、当前 URL、标签页、焦点元素和上一动作错误。HTML 保留属性与结构，却可能很长并含大量脚本和隐藏节点；可访问树压缩到语义角色、名称与层级，更接近可交互对象；截图保留视觉布局和画布内容，但文字与坐标定位需要视觉模型。实际系统常组合可访问树与截图，并给元素分配短期稳定标识。
BrowserGym 提供统一的 observation 与 action space，用于 WebArena、WorkArena 等网页基准。WorkArena++ 的实现会给出目标、当前页面 HTML 或可访问树、焦点元素与上一动作错误，并使用元素标识执行点击和输入。WebArena 的自托管站点让任务可重置，完成判定读取网站中的功能状态，而非比较模型回复文本。
3.2. 动作空间与页面版本
常见浏览器动作包括导航、点击、输入、选择、滚动、打开或关闭标签页，以及向用户提问。高层 click(element_id) 比裸坐标更稳定，前提是 observation 提供元素标识；视觉坐标用于画布或缺少语义节点的页面。输入动作要区分追加、清空后填写和键盘快捷键，避免模型对浏览器默认行为作隐含假设。
页面导航、弹窗和局部刷新会使旧元素引用失效。每个 observation 带页面版本，动作引用同一版本；不一致时返回 STALE_REFERENCE 并要求重新观察。若执行器擅自把旧文本名称匹配到新页面，可能点击同名但不同语义的按钮。精确失败比“尽力操作”更适合高风险任务。
3.3. 网页任务的实验边界
WebArena 论文报告，当时最佳 GPT-4 Agent 的端到端任务成功率为 14.41%，人类为 78.24%。差距同时包含网页理解、长程规划、元素定位、会话状态和错误恢复，不能全部归为基础模型知识不足。观察类型、动作实现和任务终局验证都会影响结果。
浏览器 ACI 消融可比较纯文本可访问树、纯截图与多模态观察，比较元素动作与坐标动作，并固定模型、页面快照和步骤预算。除成功率外，记录无效元素、页面版本过期、重复导航、误提交和 observation token。多模态观察更丰富，也可能增加成本和无关视觉信息；没有一种表示对所有页面占优。
4. MCP的协议层与接口演化
4.1. Host、Client与Server
MCP 采用 Host—Client—Server 架构。Host 是运行模型并协调用户体验的应用；每个 Client 维护与一个 Server 的协议连接；Server 暴露工具、资源和提示。一个 Host 可以连接多个 Server，但服务器彼此不会因为共享 Host 自动获得通信能力。Host 负责合并名称、选择暴露内容和维护信任边界。
工具是可执行函数，资源是可读取数据，提示是可复用模板。官方规范还区分控制方式：提示通常由用户选择，资源由应用管理，工具可由模型建议调用。这个分类描述协议原语，不授予真实权限。Host 仍要决定当前主体能否读资源、能否执行工具，以及调用前是否需要用户批准。
4.2. 数据层与传输层
MCP 数据层基于 JSON-RPC，定义能力发现、工具列表与调用、资源读取、提示获取、通知和进度等消息语义。传输层负责连接、消息边界与认证，可使用本地标准输入输出或远程 Streamable HTTP。相同工具定义可以通过不同传输交换，但威胁模型不同：本地子进程涉及主机权限，远端连接涉及网络身份、令牌和服务端信任。
版本与能力协商避免客户端调用不支持的方法。Server 的工具列表还可能动态变化并发出通知。Host 收到列表变化后应重新做名称冲突、权限和风险筛选，不能把新增工具直接暴露给正在运行的模型。远端 Server 提供的描述与结果都属于不可信输入，需要与系统指令隔离。
4.3. 调用序列、聚合与信任
一次调用怎样穿过协议栈。
一次典型序列是 Host 建立 Client，Client 与 Server 协商协议和能力，Host 请求 tools/list，筛选后把部分工具定义交给模型。模型提出调用，Host 做参数与权限校验，再由 Client 发送 tools/call。Server 返回内容或错误，Host 转换为内部 observation，并决定是否继续模型循环。
协议成功只到“Server 返回响应”为止。响应声明写入成功后，Host仍需按业务要求读取资源或调用验证工具。长操作的进度通知用于界面和取消，不等于最终提交。调用标识、MCP Server 身份、工具版本与内部动作标识要在 trace 中关联，才能跨协议边界定位故障。
名称、聚合与信任。
多个 Server 可能同时暴露名为 search 或 read_file 的工具。聚合器需要以 Server 身份或命名空间消歧，并避免恶意 Server 用相似名称和描述冒充可信工具。模型看到的展示名可以简短，执行记录必须保留完整来源。
工具数量增加也会降低选择质量并推高上下文成本。Host 可以先按领域与任务筛选 Server，再按权限筛选工具；需要时让模型调用能力发现，而非预先注入全部定义。筛选器本身属于 Agent 系统，不由 MCP 规范替应用完成。
兼容与版本。
schema 变化会直接改变模型动作分布。接口版本应和评测任务、轨迹及训练数据一起记录，重大语义变化应使用新动作而非静默改变旧字段。
调用方与工具服务对错误码、可选字段和结果上限要有明确契约。模糊兼容会把确定的接口错误转化为模型难以理解的文本异常。
协议版本兼容要与工具语义版本分开。MCP 消息仍符合当前规范，不代表某个 deploy 工具的参数和副作用没有变化。Server 在工具定义或元数据中给出自身版本，Host 把版本写入轨迹和缓存键。破坏性变化需要显式升级，避免运行中的 Agent 使用旧参数解释新工具。
结果大小同样需要协商。Server 可以返回文本、图像或嵌入资源，Host 决定哪些内容进入模型上下文，哪些只保存为产物。截断应产生明确标记和后续读取方式；静默截断会让模型误以为观察完整。
最小权限。
能力发现应按主体和任务过滤，不把不可用工具展示给模型。执行时再次校验，防止上下文污染或模型输出绕过发现阶段。
高风险动作采用窄参数、预览、审批和提交后验证。安全边界落在执行器和环境，不依赖模型承诺谨慎使用。
最小权限在三处执行。发现阶段隐藏不可用工具，减少模型选择面；调用阶段根据主体、任务和资源重新授权，防止伪造调用；环境阶段使用沙箱、服务账户和网络策略限制真实能力。三处权限互补，任何一处都不应把模型输出当作可信证明。
Server 的工具结果可能包含提示注入内容，工具组合还可能形成数据外泄路径：一个工具读取私有文件，另一个工具向外部网络发送文本。单工具权限看似合理，组合后却违反信息流策略。Host 需要按数据标签限制结果能流向哪些动作，并在高风险跨域传输前要求审批。
5. 接口比较与验收
5.1. 接口比较与路径选择
接口消融矩阵。
评测 ACI 时可构造二维矩阵：观察侧比较完整原始状态、裁剪文本、结构化树和多模态表示；动作侧比较裸 Shell 或坐标、带标识原子动作和高层业务动作。每个单元固定模型、任务、预算与 Runtime，报告成功率、步骤、token、无效动作和安全事件。
消融结论要对应具体机制。带行号查看减少错误编辑，说明定位信息有效；输出截断降低 token 却增加漏读，说明裁剪规则需要任务感知；高层工具提高成功率但掩盖内部决策，说明能力转移到了工具。没有上下文的总分不能回答接口为何更好。
选择 API、Shell 还是 GUI。
选择顺序取决于语义稳定性与覆盖范围。API 具有结构化参数和结果，最适合稳定业务；受控 Shell 适合代码、构建和本地自动化；GUI 覆盖没有 API 的应用，却受到布局、异步渲染和会话状态影响。系统可以把三者作为不同能力，而不是让模型通过通用命令任意绕行。
同一任务中也可混合使用：API 获取订单数据，浏览器完成网页提供的人工确认，提交后再用 API 查询结果。每次跨接口都要保留共同资源标识，防止模型把页面显示名称与 API 实体错配。
5.2. 上线验收与跨环境标识
上线前验收。
接口验收包括 schema 样例与反例、错误分类、结果上限、幂等和提交语义、版本策略、权限、审计字段与验证动作。随后用代表性模型跑正常任务、缺失参数、过期引用、部分失败、超时、提示注入和越权请求。测试不仅看是否拒绝，还看 observation 是否足以引导安全恢复。
上线后按工具与版本监测选择率、参数错误、拒绝、未知提交、平均结果大小和任务成功率。工具描述或页面结构变化会造成分布漂移。ACI 是运行系统的一部分，需要与模型和任务一起持续回归，而不是发布后保持不可见。
跨环境任务的共同标识。
真实任务经常跨代码、浏览器和业务 API。Agent 在仓库中读取部署配置，通过云 API 创建预览环境，再打开浏览器验证页面。三个接口必须共享部署 ID、提交 SHA 与环境 URL，模型才能判断浏览器中的页面来自刚才修改的版本。只靠名称或时间邻近关联，容易验证到旧部署。
共同标识由 Runtime 维护，并在 observation 中显示。代码工具返回提交 SHA，部署工具接受该 SHA 并返回 deployment ID，浏览器会话绑定 deployment ID 对应的 URL。验证器读取页面版本端点再次比较 SHA。模型负责选择动作，跨系统实体关系由结构化状态保证。
如果某一环境无法暴露稳定标识，接口应明确不确定性。例如第三方网页只显示订单名称，系统可联合账户、时间和金额做候选匹配，再要求用户确认。适配器不能静默选择第一个同名对象，把定位风险藏在成功结果中。
6. 成本、运行时可靠性与最终评测
6.1. 接口设计的成本函数
ACI 设计同时权衡任务损失、交互成本和风险。可以写成 ，其中 衡量终局错误， 包含 token、步骤和延迟， 衡量越权与不可逆副作用。高层动作可能降低 ，却扩大隐藏决策带来的 ；丰富 observation 可能降低任务损失，却增加上下文成本。
权重取决于任务。只读资料探索可以接受更多并行查询，付款和发布则把风险权重设得更高。接口消融因此不能只追求最短轨迹，还要报告完成质量与安全约束。一个用单次通用 Shell 命令完成任务的 Agent 可能步骤最少，却最难授权、审计和恢复。
成本函数也解释了为什么人类 UI 不一定适合模型。图形界面把大量状态通过视觉连续性呈现给人类，模型每轮重建状态的成本很高；专用 ACI 用结构化文本降低这一成本。反过来，把应用所有内部对象完整暴露给模型会增加选择与隐私成本。接口优化是在任务所需信息与最小能力之间寻找可验证边界。
最终验收要回到完整任务。模型通过专用命令编辑成功、MCP 调用返回正常、浏览器点击命中元素，都只是局部接口指标。只有环境终局满足目标、轨迹遵守权限、成本位于预算内，接口设计才真正支持了 Agent。局部指标用于定位改进方向，不能替代端到端验证。
这也是 ACI 与普通 SDK 的差别：它同时面向模型可学性、运行时控制和环境验证，而不仅是把已有函数换一种调用格式。
6.2. 运行时可靠性
资源接口与工具接口也要区分。资源提供可读取、订阅或引用的内容，工具产生计算或副作用。把读取文档实现成任意命令，会扩大权限与审计难度；把复杂计算伪装成静态资源，又失去参数、错误和取消语义。Host 根据契约选择缓存和授权方式。
通知通道只传递状态变化，不能默认具备可靠队列语义。连接断开可能丢通知，重连后 Client 需要按版本拉取当前状态或从游标补事件。若 UI 与模型仅依赖瞬时通知，刷新后会出现“任务消失”。推送提高实时性，拉取恢复权威事实。
Server 生命周期包含启动、初始化、健康、能力变更、关闭和异常退出。工具调用进行中服务崩溃时，Client 不能一律判为未执行；只读动作可按策略重试，写动作依据幂等键查询。重新连接得到的新 Server 实例也不能接管旧请求而不核对动作状态。
多 Server 聚合还会出现语义重复。两个搜索服务都声明 search，一个访问公网，一个访问内部资料。名称重写只能解决冲突，策略还需看到数据范围、隐私与时效差异。Host 可按任务隐藏不相关服务，降低选择熵和意外数据流。
错误可观测性贯穿协议边界。传输断开、协议解析、Server 内部异常、业务校验和权限拒绝分别编码；错误链保留最初 cause，但对模型过滤秘密。把所有异常变成 -32603 Internal error 虽符合通用形状，却使恢复策略失明。
跨语言 SDK 需要契约测试。空值、整数范围、枚举未知值、二进制内容和取消信号在不同实现中可能变化。生成 schema 样本做往返，故意注入边界错误，并用同一 golden trace 比较各 Client。互操作不能只靠各自单测宣布。
6.3. 最终评测与契约文档
最终评测把 ACI 当成系统变量。固定基础模型与任务，记录终局、动作数、无效观察、恢复和风险；再对模型升级重复。接口让弱模型更稳定，往往比只在强模型上减少一两个步骤更具普适价值，但结论仍需在多个环境验证。
接口文档也是版本化产物。描述、schema 与实现从同一来源生成，并在发布时运行示例。文档声称只读而实现发生写入，属于权限事故；实现新增字段但描述未更新，则会制造系统性参数错误。发布门禁同时核对三者哈希和契约测试结果。