深入解读 BrowserOS 的 @browseros/acpx-ai-provider:基于 acpx 运行时桥接 Vercel AI SDK 的 ACP Agent Provider

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

深入解读 BrowserOS 的 @browseros/acpx-ai-provider:基于 acpx 运行时桥接 Vercel AI SDK 的 ACP Agent Provider

导读

@browseros/acpx-ai-provider 是 BrowserOS(开源 Agentic 浏览器)在仓库内维护的 Vercel AI SDK Provider,它架设在 acpx/runtime 之上,将 AI SDK 的 LanguageModelV2 接口与 Agent Client Protocol(ACP)的规范化事件流连接起来:一次安装即可驱动 Claude Code、Codex、Gemini、Copilot、Cursor、Pi 等任意 ACP Agent。读完本文,你将掌握该 provider 的安装配置、会话与权限模型、工具接入(MCP)、结构化输出、生命周期控制等完整实战能力,并理解其底层事件翻译、会话复用与已知边界。

为什么需要这样一层 Provider

在 ACP 生态中,acp-ai-provider 这类方案虽然能把 Vercel AI SDK 桥接到 Agent Client Protocol,但它建立在裸的 @agentclientprotocol/sdk 之上,消费者仍需自行安装每个 Agent 的 CLI、自行编写 { command, args } 的 spawn 配置。

@browseros/acpx-ai-provider 则向上再抽象了一层,直接构建在 acpx/runtime 之上,由此获得三个关键收益(见 README 的 Why 一节):

  • 零额外安装:acpx 会在首次使用时通过 npx 自动解析并拉起内置 Agent(Claude、Codex、Gemini、Copilot、Cursor、Pi 等),无需手工下载 CLI;
  • 零胶水代码:stdio 管道、初始化握手、认证重试循环、权限弹窗接线全部由运行时接管,调用方无需关心;
  • 薄翻译层:Provider 只负责在 AI SDK 的 LanguageModelV2 与 AcpRuntime 的规范化事件流之间做双向翻译。

从仓库结构看,该包是 BrowserOS 对上游 acpx-ai-provider(原 DaniAkash/acpx)的快照分支(in-repo fork),钉住的上游提交为 ffb54400(tag acpx-ai-provider-v0.0.6),并已从上游的 AI SDK v6 迁移到 AI SDK v7(@ai-sdk/provider ^4、@ai-sdk/provider-utils ^5),工作区包版本为 1.0.0,详见 PROVENANCE.md。

安装与依赖

在 BrowserOS 的 browseros-agent 工作区(使用 bun 管理)中,包本身通过 workspace 引用,acpx 与 ai 是 peer 依赖:

{
  "dependencies": {
    "@browseros/acpx-ai-provider": "workspace:*",
    "acpx": "^0.13.0",
    "ai": "^7.0.0"
  }
}

依据 package.json:ai 的 peer 范围是 >=7.0.0-beta.0(README 提示使用 ai ≥ 6 亦可,但本 fork 已面向 v7 迁移),acpx 使用 0.13.x。包自身只依赖 @ai-sdk/provider 与 @ai-sdk/provider-utils,运行时依赖全部落在 acpx 上,因此它是一个相当薄的翻译层。

快速开始:两段代码跑通 generateText 与流式输出

非流式调用

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)

首次运行时 acpx 会通过 npx 拉取 Claude Code 的 ACP 适配器,之后的调用即为热启动(warm)。

流式调用

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

const provider = createAcpxProvider({ agent: 'claude' })

const { textStream } = streamText({
  model: provider.languageModel(),
  prompt: 'Write a haiku about TypeScript.',
})

for await (const chunk of textStream) process.stdout.write(chunk)

从源码看,languageModel() 返回的是 AcpxLanguageModel 实例(language-model.ts),它实现了 AI SDK 的 LanguageModelV2 接口:specificationVersion = 'v2'、provider = 'acpx',modelId 取自 opts.agent ?? settings.agent。doStream 先确保 ACP 会话句柄,再把 AI SDK prompt 转换成纯文本与附件,交给 runtime.startTurn,最后用 EventTranslator 把运行时的 AcpRuntimeEvent 逐个翻译成 LanguageModelV2StreamPart 流;doGenerate 则是 doStream + 流累积的封装。AI SDK 的 generateText / streamText 因此无需任何自定义适配即可工作。

配置参数全景

createAcpxProvider 接受一个 AcpxProviderSettings 对象(类型定义见 types.ts):

createAcpxProvider({
  agent: 'claude',                 // 任意 acpx 内置 id,或自定义覆盖
  cwd: '/path/to/repo',            // Agent 的工作目录(默认 process.cwd())
  sessionKey: 'my-session',        // 逻辑会话名(默认 `${agent}::${cwd}`)
  sessionMode: 'persistent',       // 'persistent'(默认,跨轮复用)| 'oneshot'(单轮后销毁)
  permissionMode: 'approve-reads', // 'approve-all' | 'approve-reads' | 'deny-all'
  nonInteractivePermissions: 'deny',
  resumeSessionId: 'sid-xyz',      // 恢复之前的会话
  turnTimeoutMs: 60_000,
  stateDir: '~/.acpx',             // 会话存储位置
  mcpServers: [/* … */],
  agentRegistryOverrides: {
    'my-agent': ['node', './bin/my-agent.js', '--acp'],
  },
  // 高级:注入预构建运行时(测试、多 provider 共享)
  runtime: customRuntime,
})

各参数要点:

参数 类型 默认值 说明
agent string 必填 使用的 ACP Agent id
cwd string process.cwd() Agent 工作目录
sessionKey string `${agent}::${cwd}` 逻辑会话名,见下方解析逻辑
sessionMode 'persistent' | 'oneshot' 'persistent' 会话生命周期
permissionMode 'approve-all' | 'approve-reads' | 'deny-all' 'approve-reads' 权限兜底策略
nonInteractivePermissions 'deny' | 'fail' 'deny' 非交互场景权限处理
resumeSessionId string — 恢复历史会话
turnTimeoutMs number 300_000(5 分钟) 单轮超时
stateDir string ~/.acpx 会话持久化目录
mcpServers AcpxMcpServerConfig[] — MCP 工具服务器
agentRegistryOverrides Record<string, string | string[]> — 自定义 Agent 注册
runtime AcpRuntime — 注入预构建运行时

关于默认值,源码 provider.ts 中明确定义:DEFAULT_PERMISSION_MODE = 'approve-reads'、DEFAULT_NON_INTERACTIVE = 'deny',stateDir 缺省为 path.join(os.homedir(), '.acpx'),turnTimeoutMs 在语言模型侧缺省为 DEFAULT_TURN_TIMEOUT_MS = 5 * 60_000(即 5 分钟)。

sessionKey 的解析逻辑在 AcpxProvider.resolveSessionKey() 中:优先取调用级 opts.sessionKey,其次 settings.sessionKey,最后回退为 `${agent}::${cwd}`。同一个 sessionKey 在 provider 内部通过 handles Map 缓存 ACP 会话句柄(ensureHandle 中按 key 命中即复用),因此相同 key 的多个 languageModel() 实例共享底层 ACP 会话。

buildRuntimeOptions() 展示了 provider 如何把自身配置转译为运行时选项:sessionStore: createFileSessionStore({ stateDir })、agentRegistry: createAgentRegistry({ overrides })、permissionMode、nonInteractivePermissions、timeoutMs、mcpServers 与 onPermissionRequest 一一透传。

内置 Agent 注册表与自定义 Agent

acpx 内置的 Agent id 包括:pi、openclaw、codex、claude、gemini、cursor、copilot、droid、iflow、kilocode、kimi、kiro、opencode、qoder、qwen、trae。行为因 Agent 而异(详见已知限制一节)。

内置注册表只是为流行 Agent 提供便利。任何能在 stdio 上走 ACP 的二进制或脚本都可以接入——通过 agentRegistryOverrides 注册:

const provider = createAcpxProvider({
  agent: 'my-acp-server',
  agentRegistryOverrides: {
    'my-acp-server': ['./bin/my-acp-server', '--stdio'],
    // 任何能产生 ACP-over-stdio 进程的写法都行:
    //   'my-acp-server': ['node', './script.js', '--acp'],
    //   'my-acp-server': ['npx', '@my-org/acp-adapter@1.2.3'],
  },
})

自定义 Agent 要无缝接入,必须满足:

  • 通过 stdio 完成 ACP 的 JSON-RPC 握手(运行时仅支持 stdio,不支持 HTTP / SSE / WebSocket 传输);
  • 处理 initialize、session/new(持久会话可选 session/load)、session/prompt;
  • 以标准工具调用状态流转(pending → in_progress → completed / failed)发送 session/update 事件;
  • 返回文档规定的停止原因之一——end_turn / stop_sequence / max_tokens / tool_calls / tool_use,其余值会被映射为 AI SDK 的 finishReason: 'unknown'(映射表见 convert-events.ts 的 STOP_REASON_MAP)。

自定义 Agent 也意味着三件事需要自行负责:没有 npx 自动下载(命令原样执行,需保证二进制在 PATH 上或使用绝对路径)、没有官方的冒烟测试矩阵保障稳定性、凭据管理归你(Agent 读取自己的环境变量或配置文件)。

如果自定义 Agent 是公开分发的 ACP 适配器,更优路径是向 acpx 提 PR 加入内置注册表,这样所有使用者都能享受 npx 自动下载。

认证:环境变量与配置文件驱动

acpx/runtime 从环境变量或 ~/.acpx/config.json 读取凭据。本 provider 不提供程序化凭据注入,也没有认证失败时的惰性重试——凭据缺失时,首次调用就会抛出 AcpxAuthRequiredError。

# 按 Agent 需求设置对应环境变量:
export ACPX_AUTH_OPENAI_API_KEY=sk-…
export ACPX_AUTH_ANTHROPIC_API_KEY=sk-ant-…

需要外部 CLI 认证的 Agent(如 GitHub Copilot),需在构造 provider 前先完成 CLI 登录:

gh auth login

持久会话与系统提示词

默认 sessionMode: 'persistent' 会让 Agent 在多次调用间保留上下文;同一 sessionKey 下的每个 languageModel() 实例共享底层 ACP 会话:

const provider = createAcpxProvider({ agent: 'claude' })
const model = provider.languageModel()

await generateText({ model, prompt: 'Hi, my name is Alice.' })
await generateText({ model, prompt: "What's my name?" }) // 记住了

await provider.close() // 用完销毁
  • 预热会话(不发送提示词即建好会话):await provider.prepare();
  • 单次隔离轮次:createAcpxProvider({ agent: 'claude', sessionMode: 'oneshot' })。

系统提示词与按会话 Agent 选项

通过 sessionOptions 可在新会话上设置 Agent 的 systemPrompt(以及可选的 model、allowedTools、maxTurns),这些值被转发到 ACP 的 session/new _meta,在首轮之前生效:

const provider = createAcpxProvider({
  agent: 'claude',
  sessionOptions: {
    systemPrompt: 'You are an expert Rust reviewer. Be terse.',
    // model: 'claude-opus-4-7',
    // allowedTools: ['read', 'edit'],
    // maxTurns: 5,
  },
})

使用 { append: '…' } 可追加到 Agent 默认提示词而非整体替换:

sessionOptions: {
  systemPrompt: { append: 'When you finish, also propose tests.' },
}

两个必须注意的语义(README 与源码注释一致,见 types.ts 的 sessionOptions 文档):

  • 系统提示词在 session/new 时固定;同一工作区要切换提示词需使用不同的 sessionKey。改变 sessionOptions 并复用同一 key 对已复用的会话记录是 no-op(有意为之)——provider.close() 也不会清除持久记录,所以仅靠 close 不会强制发起新的 session/new;
  • 并非每个 Agent 都认每个选项——Codex / Gemini 会忽略 Claude 专属字段(如 model),无法识别的选项在 ACP 层被静默丢弃。

测试用例 验证了 systemPrompt 字符串与 { append } 形式及其他选项(model、allowedTools、maxTurns)都会被原样转发到 runtime.ensureSession,未配置时则不传该字段。

推理链与计划(Reasoning & Plan Steps)

多数 ACP Agent 会流式输出思维链。provider 将其暴露为 AI SDK 的 reasoning parts,消费者用与处理其他可推理模型完全相同的代码即可渲染:

import { streamText } from 'ai'

const result = streamText({
  model: provider.languageModel(),
  prompt: 'Refactor user.ts to use Result<T, E>',
})

for await (const part of result.fullStream) {
  if (part.type === 'reasoning-delta') {
    ui.appendThinking(part.delta) // 流式 "💭…" 气泡
  } else if (part.type === 'text-delta') {
    ui.appendAnswer(part.delta)
  }
}

当 Agent 发出计划("I will: 1. read file 2. fix bug 3. test")时,provider 通过同一通道将其作为带 [Plan] 前缀的独立 reasoning 块呈现:

reasoning-start (id-1)
reasoning-delta (id-1, "[Plan] 1. read file 2. fix bug 3. test")
reasoning-end   (id-1)

实现细节见 convert-events.ts:EventTranslator.handleStatus() 对 tag === 'plan' 的事件生成独立的 reasoning-start/delta/end 三元组(trim 后为空则跳过)。计划块拥有自己的 block id,不会干扰进行中的思考块——Agent 可以一边往一个 id 里持续输出推理,一边在其他 id 上进出计划通告。

不输出推理的 Agent(如某些配置下的 Gemini CLI)则不会产生任何 reasoning-* parts,消费者代码里的 reasoning-delta 分支自然不触发,无需特判。

控制推理强度

多数支持思考的 Agent 接受 reasoning_effort 配置项,用延迟换深度——强度越高,回答前消耗的思维链 token 越多。在下一轮开始前设置:

const provider = createAcpxProvider({ agent: 'claude' })
await provider.setConfigOption('reasoning_effort', 'high')

当前已确认的支持矩阵:

Agent Config key 可选值 默认值
claude reasoning_effort low / medium / high / xhigh medium
codex reasoning_effort(CLI 别名 thought_level) low / medium / high / xhigh medium
gemini、copilot、cursor 等 尚未有文档化确认 — —

注意 thought_level 是 Codex 专属别名——acpx codex set thought_level high 在分发前会被翻译成 reasoning_effort = high,其他 Agent 原样接收 reasoning_effort。

发现某 Agent 的配置键

不在上表中的 Agent(或 acpx 新增的 Agent),其配置词汇表是逐 Agent 的,有三种发现途径:

  1. 运行时能力:询问 Agent 它公告了哪些键:
    const handle = await provider.prepare()
    const caps = await provider.runtime.getCapabilities?.({ handle })
    console.log(caps?.configOptionKeys)
    
  2. acpx CLI:全局安装 acpx 后检查 Agent 的命令树(acpx <agent>)。
  3. 适配器源码:每个已发布的 ACP 适配器都有 session/set_config_option 处理器,列出其接受的键。

注意事项

  • 强度变更作用于下一轮而非进行中的一轮:流中调用 setConfigOption 只对下一次 streamText / generateText 生效;
  • 切换模型不会重置强度:随后 setConfigOption('model', …) 会保留此前设置的推理强度,想恢复默认需显式重置;
  • 对不在表中的 Agent,使用上文发现方法:无法识别的配置键会在下一轮以错误形式暴露,对着 Agent 实际能力列表做试错是安全的。

工具:通过 MCP 服务器接入

工具通过 mcpServers 传入的 MCP(Model Context Protocol)服务器定义。Agent 发现并调用它们,结果通过 provider 的流以 tool-call / tool-result parts 回流:

const provider = createAcpxProvider({
  agent: 'claude',
  mcpServers: [
    {
      type: 'stdio',
      name: 'filesystem',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
      env: { LOG_LEVEL: 'info' },          // stdio 服务器 —— env 为 Record
    },
    {
      type: 'http',
      name: 'remote',
      url: 'https://example.com/mcp',
      headers: { Authorization: 'Bearer …' }, // http/sse 服务器 —— headers 为 Record
    },
  ],
})

env 与 headers 以普通 Record<string, string> 接受(类型见 types.ts 的 AcpxMcpServerStdio / AcpxMcpServerHttp),provider 在交给运行时前把它们转成 ACP 线上格式 Array<{ name, value }>——实现位于 mcp-servers.ts 的 recordToEntries()。此外还支持 type: 'sse' 的远程服务器配置。

注意:宿主侧 AI SDK 工具(acp-ai-provider 中的 acpTools() / TCP 回调方案)在 v0.1 不支持,见已知限制。

逐调用权限控制

默认情况下,Agent 发出的每个权限请求(写文件、执行 shell 命令、删除等)都由前置的 permissionMode 设置统一裁决。若要用自己的 UI 拦截单个请求,传入 onPermissionRequest 回调:

const provider = createAcpxProvider({
  agent: 'codex',
  cwd: '/path/to/repo',
  permissionMode: 'approve-reads', // 未处理情况的兜底
  onPermissionRequest: async (req, { signal }) => {
    // Agent 此时暂停在轮次中间等待你的裁决。
    // 尊重 `signal`,这样取消轮次不会让它挂起。
    const decision = await myUi.prompt({
      title: req.raw.toolCall.title,
      kind: req.inferredKind, // 'edit' | 'shell' | 'delete' | …
      args: req.raw.toolCall.input,
    })
    return decision
    // 返回 `undefined` 则回退到基于模式的裁决器。
  },
})

回调收到的字段:

字段 含义
req.sessionId ACP 会话 id(多会话宿主很实用)
req.raw ACP SDK 的完整原始 RequestPermissionRequest
req.inferredKind 'read' | 'search' | 'edit' | 'delete' | 'move' | 'execute' | 'fetch' | 'think' | 'other' 之一——根据工具标题做的最佳努力分类
ctx.signal 轮次取消或会话关闭时触发中止

可返回的裁决值:

  • { outcome: 'allow_once' } — 批准本次单次调用
  • { outcome: 'allow_always' } — 批准同类调用直到本轮结束
  • { outcome: 'reject_once' } — 拒绝本次调用;Agent 继续其余任务
  • { outcome: 'reject_always' } — 拒绝并记住直到本轮结束
  • { outcome: 'cancel' } — Agent 视该调用为已取消(通常结束本轮)
  • undefined — 回退到基于模式的裁决器

重要注意点:

  • 回调仅当 provider 自行构建运行时(不传 runtime)时才被调用。若通过 runtime 传入预构建运行时,请把 onPermissionRequest 设置在那个运行时上;
  • 回调内抛错会回退到基于模式的逻辑并由运行时记录日志——别让 UI 错误拖垮整轮;
  • Agent 在你的 promise 解决前是暂停的。provider 不强制超时——请自行接线(或依赖 Agent 内部超时,通常 5–10 分钟)。

列出与切换模型

部分 Agent(Claude Code、Codex)会在会话打开时公告它们可驱动的模型。用 getModels() 读取可用列表与当前选中 id:

const models = await provider.getModels()
if (models) {
  console.log(models.availableModelIds) // ['claude-haiku-4-5', …]
  console.log(models.currentModelId) // 'claude-opus-4-7'
}

返回 undefined 的场景:Agent 未公告任何模型(如 Gemini CLI、省略 NewSessionResponse.models 的自定义适配器);底层运行时未实现 getStatus。

getModels() 在会话未打开时会惰性拉起 ACP 会话(与 prepare() 相同)。多会话 provider 请传入与 languageModel() 相同的 { sessionKey, agent }:

const models = await provider.getModels({ sessionKey: 'codex::/repo' })

切换模型使用生命周期控制里的 setConfigOption('model', id)。源码上 getModels() 依赖 runtime.getStatus 是否存在(AcpxProvider.getModels() 先检查 getStatusImpl,无则返回 undefined)。

结构化输出(JSON)

generateObject / streamObject 通过 JSON 模式工作。provider 在 prompt 前追加结构化输出指令,并从输出流中剥离 markdown 围栏(json … ),让 AI SDK 的解析器拿到干净的 JSON:

import { generateObject } from 'ai'
import { z } from 'zod'

const { object } = await generateObject({
  model: provider.languageModel(),
  schema: z.object({
    name: z.string(),
    ingredients: z.array(z.string()),
  }),
  prompt: 'Give me a recipe for chocolate chip cookies.',
})

streamObject 同样可用。

实现层面(json-output.ts):doStream 在 callOptions.responseFormat?.type === 'json' 时给输出流接上 createJsonCleanupTransform();该 TransformStream 策略性地保留 text-start 直到确认前几个字节是围栏还是裸 JSON,识别到开围栏即剥离(需要换行才能确定语言标签结束位置),流式期间保留 12 字节的小后缀缓冲以去掉尾部闭合围栏,从而无需缓冲整个 payload。同时 convert-prompt.ts 的 buildJsonSchemaPrompt() 会生成 [Structured Output Instruction] 指令块,明确要求"只输出单个合法 JSON 值、不要 markdown 围栏、不要前后附加解释"。

生命周期控制

await provider.cancel('user pressed stop')   // 取消进行中的轮次
await provider.setMode('plan')               // 切换会话模式(若 Agent 支持)
await provider.setConfigOption('model', 'opus') // 调整 Agent 配置项
const report = await provider.doctor()       // 来自运行时的诊断信息
await provider.close('done')                 // 释放所有会话

setMode、setConfigOption、doctor 在底层 Agent 未实现时为 no-op(源码中分别检查 runtime.setMode / setConfigOption / doctor 是否存在,不存在则直接返回)。可用 provider.runtime.getCapabilities() 查看支持情况。close() 还支持 { discardPersistentState: true } 可选地丢弃持久化状态(这是本 fork 相对上游的本地补丁之一,见 PROVENANCE)。

AcpxProvider 还额外暴露了若干运行时无关的辅助能力(源码 provider.ts):

  • provider.events(EventEmitter<AcpxProviderEvents>):订阅 usage 与 availableCommands 推送事件;
  • getUsage(sessionKey?) / getAvailableCommands(sessionKey?):同步读取最近的用量快照与 Agent 公告的斜杠命令列表(返回防御性拷贝);
  • runSlashCommand({ name, … }) / compact():发送如 /compact 的斜杠命令——ACP 本身没有 compact 动词,斜杠由 Agent 侧解释;compact() 会从已公告命令中解析 compact / condense 并执行。

已知限制:alpha 软件的真实边界

这是 alpha 级软件,多数粗糙边缘来自同样未到 1.0 的 acpx/runtime。以下限制在 README 中逐条列出,并结合源码给出佐证。

继承自 acpx/runtime

  • 工具输入与输出共用一个文本字段:tool-call.input 与 tool-result.result 是同一个字符串。运行时把两者折叠进一个 text 字段——底层 ACP 协议里它们是分开的,但运行时的规范化器丢弃了这一区分(见 convert-events.ts 的 finalizeToolCall(),input 与 result 均取 state.emittedText);
  • 工具输入是原始字符串而非解析后的 JSON:Agent 输出合法 JSON 时需自行 JSON.parse,否则预期会失败;
  • 没有输入/输出 token 拆分:只有 cachedInputTokens 流入 AI SDK,inputTokens、outputTokens、totalTokens 为 undefined,逐 token 成本计算不可用(见 EventTranslator.accumulatedUsage()——仅在有 per-turn breakdown 时填充 inputTokens/outputTokens/reasoningTokens);
  • 无流式用量更新:只有运行时最近的 usage_update 会存续到 finish part 上;上下文窗口大小通过 providerMetadata.acpx.contextWindow 暴露(usage_update 的 size 字段,见 finish() 与测试);
  • 权限策略默认基于模式:未提供 onPermissionRequest 回调时,请求回退到 permissionMode + nonInteractivePermissions;
  • 认证由环境变量 / 配置文件驱动,无惰性重试:凭据缺失在首次使用时即抛错;
  • 首次使用 Agent 时的 npx 冷启动:内置 Agent 通过 npx 自动下载,全新安装后的首次调用可能耗时 10 秒以上;
  • 会话以文件形式持久化在 ~/.acpx/sessions/:默认不是多进程安全的,必要时用 stateDir 覆盖;
  • 轮次中途的 AbortSignal 尊重程度因 Agent 而异:signal 会被转发给 runtime.startTurn,但 Agent 停止多快各不相同,provider.cancel() 是最强信号;
  • 可选控制方法可能 no-op:setMode、setConfigOption、doctor、getStatus 并非每个 Agent 都实现。

AI SDK 集成层面

  • LanguageModelV2 兼容模式警告:AI SDK v6 首次使用会打印警告("specificationVersion is used in a compatibility mode"),无害,迁移到 V3 后消失;
  • 无宿主侧 AI SDK 工具:v0.1 只支持 Agent 通过 MCP 服务器学到的工具;传给 streamText 的 AI SDK tool({ execute }) 回调不会被本 provider 调用——Agent 并不知道它们;
  • tool-call.providerExecuted 恒为 true:所有工具调用都被标记为已由 Agent 执行;
  • 多步 / stopWhen:AI SDK 的循环在 SDK 层工作,但每一步都是全新的 runtime.startTurn,请使用默认的 sessionMode: 'persistent' 让 Agent 跨步保留自己的上下文;
  • generateObject / streamObject 走 JSON 模式:非 JSON 严格的 Agent 可能输出畸形 JSON;围栏剥离转换只处理 markdown 包装,不处理坏 JSON;
  • request.body 与 response.headers 是合成的:request.body 为 { agent, sessionKey },response.headers 恒为 {}——本 provider 没有 HTTP 层。

各 Agent 的怪癖

不同内置 Agent 行为不同,推荐起始矩阵:

Agent 备注
claude 测试最充分路径,文本 + 工具干净
codex JSON 输出最受益于围栏清理
pi 冒烟测试最便宜的选择
gemini 需要 --experimental-acp(注册表已自动传入),能力面仍在演进
copilot 需要已认证的 GitHub Copilot CLI,先执行 gh auth login

v0.1 明确不在范围内

这些是有意为之的非目标,而非缺陷:宿主侧 AI SDK 工具;单个 streamText 调用内的流中模型切换;provider 定义的动态工具路由;实时 token 成本计算;按 languageModel() 的独立 Agent 注册表。

错误处理

provider 导出四个错误类(errors.ts):

import {
  AcpxError,
  AcpxAgentNotFoundError,
  AcpxAuthRequiredError,
  AcpxTurnTimeoutError,
} from '@browseros/acpx-ai-provider'
  • AcpxError:基类,携带 code 与 retryable 标志;
  • AcpxAgentNotFoundError:code = 'agent_not_found',retryable = false;
  • AcpxAuthRequiredError:code = 'auth_required',retryable = false,缺省消息提示设置 ACPX_AUTH_<METHOD> 环境变量或填充 ~/.acpx/config.json;
  • AcpxTurnTimeoutError:code = 'turn_timeout',retryable = true。

用 AcpxError 捕获宽泛场景,三个子类覆盖常见可诊断原因。其余情况回退到基类并保留运行时的 code。fromRuntimeError() 会基于错误文本中的关键词(agent_not_found、auth_required / unauthenticated、timeout 等)做启发式归类。测试验证了失败轮次抛出的错误携带 Agent 的错误数据(with-generate-text.test.ts 中断言 code: 'rate'、message: 'boom')。

在 BrowserOS 中的定位与延伸阅读

@browseros/acpx-ai-provider 位于 BrowserOS 仓库 packages/browseros-agent/packages/acpx-ai-provider/ 目录,是 browseros-agent 工作区中供内部消费的 scoped workspace 包。它的使命是让 AI SDK 应用(尤其是 BrowserOS 自身的 Agent 侧产品)以统一编程模型驱动任意 ACP Agent,而无需关心具体 CLI 的安装、spawn 配置与协议细节。

想深入了解实现细节,可继续阅读:

  • Provider 实现:会话句柄管理、配置转译、生命周期与斜杠命令
  • LanguageModel 实现:LanguageModelV2 的 doStream / doGenerate
  • 事件翻译器:AcpRuntimeEvent → AI SDK stream part 的完整映射
  • Prompt 转换:多轮消息、附件与 JSON 指令的文本化
  • JSON 围栏清理:流式剥离 json 的 TransformStream
  • 错误层次:错误分类与运行时错误归一化
  • 类型定义:全部设置项与类型别名
  • 来源说明:上游快照、本地补丁与分叉策略
  • 测试目录:单元测试(事件翻译、prompt 转换、sessionOptions、get-models、json-output、mcp-servers、provider)与集成测试(generateText / streamText 全链路、会话生命周期、消息边界等)

许可证

MIT © Dani Akash(本仓库内复制件的许可证声明见 LICENSE)。

登录后查看全文
BrowserOS