BrowserOS 内嵌 acpx-ai-provider 溯源解析:ACP 语言模型提供者的版本兼容策略与本地化改造

原创2026-09-21 16:20:551,683 阅读
文章标签:AI Agent浏览器控制GUI 自动化MCP 服务MCP ClientsAI 技能桌面应用人工智能前端

BrowserOS 内嵌 acpx-ai-provider 溯源解析:ACP 语言模型提供者的版本兼容策略与本地化改造

PROVENANCE.md 是 BrowserOS 仓库中 @browseros/acpx-ai-provider 软件包的"出生证明":它记录了该包从上游 agent-toolkit 快照内嵌进本仓库的全过程——锁定哪个上游提交、基于哪条 AI SDK 版本线、迁移到 v7 后如何演进、以及 BrowserOS 在本地方向做了哪些改造。阅读本文后,你将掌握该内嵌 fork 的溯源信息、AI SDK v6→v7 的迁移路径、分叉维护政策(Divergence Policy)的运作方式,以及每一项本地补丁对应的源码实现位置,可以直接基于仓库继续深入或二次开发。

文档定位:一张可审计的内嵌快照溯源记录

在 PROVENANCE.md 的开头,文档明确了自己的定位:它是从 DaniAkash/agent-toolkit 单仓库(monorepo,路径 packages/acpx-ai-provider,旧名 DaniAkash/acpx)内嵌(inlined)进来的快照记录。这类文件解决的是软件供应链中的核心问题——当一段第三方代码被复制进仓库并长期演进后,后人如何回答"这段代码从哪来、改了什么、还能不能回上游"。它配套的软件包 README.md 说明了用途:一个构建在 acpx/runtime 之上的 Vercel AI SDK 提供者(provider),一次安装即可接入 Claude Code、Codex、Gemini、Copilot、Cursor、Pi 等任意 ACP 代理。

快照元数据:精确锁定上游版本

溯源文档的第一要务是"钉死"来源版本。文档给出了五条关键元数据:

元数据项 值 含义
上游提交(commit) ffb54400bf581e61c4cfcba3dccfcb72bc5cd44d 快照对应的精确源码版本
上游标签(tag) acpx-ai-provider-v0.0.6 发布标签,便于对照上游发布历史
快照版本 0.0.6 内嵌时上游的包版本
AI SDK 版本线 v6(ai >=6.0.0、@ai-sdk/provider ^3.0.10、@ai-sdk/provider-utils ^4.0.26) 上游当时依赖的 AI SDK 大版本
内嵌时间 2026-07-21 快照进入本仓库的日期

这些元数据不是装饰。当你需要 diff"本地实现 vs 上游 v0.0.6"时,commit hash 和 tag 就是唯一的比对锚点;而 AI SDK 版本线则解释了为什么后面要做一次跨大版本迁移(见下文)。文档还特别提醒:由于仓库曾更名,历史元数据中可能出现旧名 DaniAkash/acpx,这属于正常现象。

为什么选择"内嵌"而不是依赖 npm 发布

文档用一节"Why inlined"解释了架构决策:BrowserOS 希望就地修改(edit in place)这个 provider,而不需要走一遍 npm publish 的发布-安装往返。这意味着:

  • 上游包仍然存在,可能继续独立发布;
  • 但本仓库这份拷贝是一个硬分叉(hard fork),没有自动的上游同步机制;
  • 任何对上游的跟进、补丁移植,都必须由维护者显式完成并在文档中留痕。

从 package.json 可以看到这种"就地"策略的直接体现:包名是作用域化的 @browseros/acpx-ai-provider(version 1.0.0),而 exports 字段直接指向 ./src/index.ts 原始 TypeScript 源码——没有构建步骤,消费者直接消费源码,这与"零往返编辑"的定位完全一致。

版本兼容演进:从 AI SDK v6 迁移到 v7

迁移决策

原始快照面向 AI SDK v6。BrowserOS 之后将这份 fork 迁移到了 AI SDK v7(@ai-sdk/provider ^4、@ai-sdk/provider-utils ^5),workspace 包版本随之提升为 1.0.0(快照版本 0.0.6 仅用于记录原始出处)。在 package.json 中有可验证的对应关系:

{
  "dependencies": {
    "@ai-sdk/provider": "^4.0.0",
    "@ai-sdk/provider-utils": "^5.0.0"
  },
  "peerDependencies": {
    "acpx": "^0.13.0",
    "ai": ">=7.0.0-beta.0"
  }
}

即:本 fork 现在要求 ai >= 7.0.0-beta.0、acpx ^0.13.0,其中 acpx 与 ai 都是 peer 依赖。底层 acpx 运行时本身仍是 pre-1.0 状态,这是使用该集成时需要记住的约束。

上游评审记录

文档记录了一次针对上游 main 分支的评审(评审基线提交 1afa195fd576ff4d8af7859c5af8e2d672639ef5,日期 2026-09-08,当时上游最新发布的 provider 为 1.0.0)。评审结论是本地方向已有以下能力,无需再移植:

  • 实时用量事件(live usage events);
  • 可用命令订阅(available-command subscriptions);
  • 斜杠命令事件路由(slash-command event routing);
  • 防御性拷贝 getter(defensive-copy getters);
  • 工具输入 ID 关联(tool-input ID correlation);
  • 显式的事件发射器类型(explicit event-emitter type)。

评审中实际移植了一项修复:来自上游提交 0390bb75183bce4a51a13932475c20ea52aada53(issue #80)的选定代理压缩查找修复(selected-agent compaction lookup fix)。

两处关键差异

文档特别强调了与上游的两处分野:

  1. 消息边界处理是 BrowserOS 的修复。截至评审时的上游事件翻译器仍只按 text/reasoning 两种流分组,而本 fork 中的 ACP messageId 边界处理(详见下文"本地补丁")是 BrowserOS 独立实现、上游没有的。
  2. usage 测试契约同步。BrowserOS 同步了五条过期的 usage 测试期望:size 应暴露为 providerMetadata.acpx.contextWindow,而不是缓存的输入 token(cached input tokens)。测试同步前实现其实已经遵循该契约,只是期望值写错了。

分叉维护政策:Divergence Policy

这是溯源文档中最重要的"操作规范",它定义了本目录的长期维护方式,原文要点完整继承如下:

  • 本目录的编辑可以自由进行,没有回同步给上游的义务;
  • 适用的上游修复以普通变更的方式应用到本目录,并在此文档中记录其修订(revision);
  • 保留上述原始快照修订(commit/tag/version 元数据不得删除);
  • 在整体替换源码之前,先审查本地适配。

这套政策让 fork 处于"既不死守快照、也不盲追上游"的稳态:上游每发布修复,维护者评估后决定是否作为普通补丁合入,并在 PROVENANCE 中追加记录;而溯源元数据始终保留,保证任何时刻都能回溯到最初的 0.0.6 快照。

第三方源码声明

文档明确声明:未引入任何第三方源码(None incorporated)。这是一个基于 acpx 运行时构建的 clean-room(净室)provider,其依赖 @ai-sdk/provider、@ai-sdk/provider-utils(均为 MIT 协议)作为普通包依赖声明,并非 vendored 源码。这一点对许可证合规审计很重要——本目录的 LICENSE 为 MIT,版权归属见 LICENSE。

本地补丁逐条解析:与源码一一对应

文档列出六项本地补丁(与快照产生分歧之处),下面结合仓库源码逐条印证。

1. 剥离内部相对导入的 .ts 扩展名

上游源码内部的相对导入写的是 from './x.ts',本 fork 统一改为 from './x'。原因:消费方 apps/server 在 moduleResolution: bundler 且未开启 allowImportingTsExtensions 时对导入的源码做深度类型检查,显式 .ts 说明符会触发 TS5097 错误。这也与兄弟包 agent-mcp-manager 的无扩展名导入约定保持一致。

在 src/provider.ts 中可以验证:import { AcpxLanguageModel } from './language-model'、import { toRuntimeMcpServers } from './mcp-servers',均为无扩展名导入。

2. Biome 检查零差异

补丁要求代码通过仓库的 Biome 配置检查,biome check 无任何改动(不需要重新格式化)。这与整个 browseros-agent 工作区使用 Biome(根目录有 biome.json)的工程规范一致。

3. 未 vendored 的文件

  • test/e2e/:该目录会真实拉起 Claude / Codex / Gemini 等代理进程,属于重型端到端测试,不适合随包分发,故未纳入;
  • bunup.config.ts:本包没有构建步骤(直接导出原始 TS 源码),因此构建配置也不需要。

4. AI SDK v7 文件数据归一化与内联附件

这是上游评审时尚不存在的能力:AI SDK v7 的 file-data 归一化,以及内联 text/JSON 附件支持。在 src/language-model.ts 可以看到 convertPrompt 将 AI SDK 的 prompt 与附件转换为 ACP 运行时所需格式(text + attachments),而 src/convert-prompt.ts 负责具体转换逻辑。

5. close() 时可选的持久化状态删除 + 结构化 argv

  • 可选的持久化状态删除:provider.close() 默认保留持久化会话记录,但可传入 { discardPersistentState: true } 强制删除。实现位于 src/provider.ts,其调用 runtime.close({ handle, reason, discardPersistentState })。这一点在 README 中也有呼应:close() 不清理持久化记录,所以单独调用 close() 不会强制触发新的 session/new。
  • 结构化 argv:agent-registry 覆盖(agentRegistryOverrides)支持 string | string<a href="https://link.gitcode.com/i/94229a69863b95b03671c38ac063eb07" target="_blank">] 两种形态,数组形态可表达完整命令与参数,见 [src/types.ts 的类型定义,以及 src/provider.ts 中 createAgentRegistry({ overrides }) 的传入。

6. ACP messageId 边界 → 独立的 text/reasoning 块

这是六项补丁中最核心的协议级修复,实现位于 src/convert-events.ts 的 handleTextDelta:

  • 缺失 messageId 的块延续当前块:ACP 的 chunk 是 token 片段,只有新的 messageId 或流切换才会开启新的 AI SDK 块;
  • 新出现的 messageId 会分隔之前未标记的文本:第一个被识别出的 message 会截断此前的"无主"文本;
  • 文本逐字保留(verbatim),不做改写;
  • 生成的块 ID 避免在工具调用与 text/reasoning 转换之间产生冲突。

对应行为有专门的集成测试覆盖,见 test/integration/message-boundaries.test.ts。此外,同文件还实现了 plan 事件处理:agent 发出 plan 时,会以独立的 reasoning 块输出、前缀 <a href="https://link.gitcode.com/i/b92ae5424282b34b610dd151f5be7a86" target="_blank">Plan]([src/convert-events.ts),不会打断正在进行的思维链块。

源码级佐证:本地能力的实现位置速查

上文提到"已在本地方向就绪"的若干能力,都可以在源码中找到对应实现:

能力 实现位置
实时用量事件 recordUsage/getUsage 与 provider.events 发射,见 src/provider.ts;usage 聚合见 src/convert-events.ts
可用命令订阅 recordAvailableCommands/getAvailableCommands,见 src/provider.ts
斜杠命令事件路由 runSlashCommand/compact,见 src/provider.ts
防御性拷贝 getter getUsage 返回 { ...snapshot }、getAvailableCommands 逐项拷贝,见 src/provider.ts
工具输入 ID 关联 toolCalls Map 以 toolCallId 为键、输入 delta 去重,见 src/convert-events.ts
显式事件发射器类型 AcpxProviderEvents 泛型化 EventEmitter,见 src/provider.ts
providerMetadata.acpx.contextWindow finish 部分把 size 写入 providerMetadata.acpx,见 src/convert-events.ts
错误模型 AcpxError/AcpxAgentNotFoundError/AcpxAuthRequiredError/AcpxTurnTimeoutError 及 fromRuntimeError 映射,见 src/errors.ts

基于内嵌 fork 的快速使用

虽然本文主体是溯源,但理解这个 fork 最好的方式是用起来。构建在 acpx/runtime 之上意味着零额外安装:acpx 会在首次使用时通过 npx 自动拉取内置代理(Claude、Codex、Gemini、Copilot、Cursor、Pi 等),stdio 管道、初始化握手、认证重试、权限弹窗都由运行时托管。最小示例:

import { createAcpxProvider } from '@browseros/acpx-ai-provider'
import { generateText } from 'ai'

const provider = createAcpxProvider({
  agent: 'claude',
  cwd: process.cwd(),
})

const { text } = await generateText({
  model: provider.languageModel(),
  prompt: 'Summarize this repo in 3 bullets.',
})

console.log(text)

常用的配置项包括 sessionMode(persistent 跨轮复用会话 / oneshot 单次隔离)、permissionMode(approve-all / approve-reads / deny-all)、mcpServers(stdio 与 http/sse 两种 MCP 服务器接入)、sessionOptions.systemPrompt(会话级系统提示词)、stateDir(会话存储位置,默认 ~/.acpx)、以及 runtime(注入预构建运行时,用于测试或多 provider 共享)。完整配置说明见 README.md。

局限与边界(使用前的必要认知)

由于底层 acpx/runtime 仍是 pre-1.0,本 fork 继承了一些明确边界,README 中有完整清单,择要如下:

  • 工具输入与输出共享同一个 text 字段,且工具输入是原始字符串而非解析后的 JSON;
  • 没有输入/输出 token 拆分,只有 cachedInputTokens 流入 AI SDK,单 token 成本计算不可用;
  • 内置代理首次使用有 npx 冷启动,干净安装后首次调用可能耗时 10 秒以上;
  • 会话持久化在 ~/.acpx/sessions/,默认不支持多进程安全;
  • 主机侧 AI SDK 工具(tool({ execute }))v0.1 不支持,工具只能通过 MCP 服务器注入;
  • 认证仅支持环境变量或 ~/.acpx/config.json,无懒重试,缺凭证首次调用即抛 AcpxAuthRequiredError。

这些都是"设计内"的取舍,README.md 的 Known limitations 一节给出了逐代理的行为矩阵(如 claude 是测试最充分的路径、gemini 需要 --experimental-acp、copilot 需先 gh auth login)。

小结:溯源文档的工程价值

PROVENANCE.md 展示了开源项目处理"第三方代码内嵌 + 长期演进"的完整工程实践:用元数据锁定来源,用评审记录跟踪上游,用补丁清单留存差异,用政策规范维护节奏。对于希望在自己的项目中内嵌第三方 provider 的读者,这份文档本身就是一份可复用的模板——先记录快照出处,再声明分叉政策,最后让每一项本地改造都能在源码中精确落地、可审计、可回溯。

登录后查看全文
BrowserOS