BrowserOS 内嵌 acpx-ai-provider 溯源解析:ACP 语言模型提供者的版本兼容策略与本地化改造
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)。
两处关键差异
文档特别强调了与上游的两处分野:
- 消息边界处理是 BrowserOS 的修复。截至评审时的上游事件翻译器仍只按 text/reasoning 两种流分组,而本 fork 中的 ACP
messageId边界处理(详见下文"本地补丁")是 BrowserOS 独立实现、上游没有的。 - 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 的读者,这份文档本身就是一份可复用的模板——先记录快照出处,再声明分叉政策,最后让每一项本地改造都能在源码中精确落地、可审计、可回溯。