浏览器

dozin.capabilities 里有 browser 时，Connector 或任务会得到 ctx.browser，用来读取和操作 Cowork 标签页里的网页。只能使用用户交出的标签页；写了 dozin.origins 时，还只能使用这些网站上的页面。

ctx.browser.adoptTab(tabId)

接管一个标签页。用户要求 Extension 接管某个页面时，Cowork 把 tabId 交给 Extension；Extension 不能自己挑选标签页。

名称	类型	必填	说明
tabId	string	是	Cowork 交过来的标签页

返回 Promise<{ tabId, url, documentId }>。页面每次加载新文档时 documentId 都会变。同一时间最多 8 个标签页。

const tab = await ctx.browser.adoptTab(tabId);
ctx.log(`watching ${tab.url}`);

ctx.browser.releaseTab(tabId)

交还标签页。它注入的脚本和音频会停止。

名称	类型	必填	说明
tabId	string	是	这个 Extension 接管的某个标签页

返回 Promise<void>。

await ctx.browser.releaseTab(tabId);

ctx.browser.evaluate(tabId, script)

在页面里运行一次脚本，并返回结果。

名称	类型	必填	说明
tabId	string	是	已接管的标签页
script.source	string	是	一个函数的源码，最多 64 KB；它接收 args
script.args	unknown	否	以 JSON 传入，不会拼接进源码

返回 Promise<unknown>：结果，以 JSON 形式，最多 64 KB。

const title = await ctx.browser.evaluate(tabId, { source: '(args) => document.title' });

ctx.browser.inject(tabId, script)

安装一个留在页面里、可以回传消息的脚本。

名称	类型	必填	说明
tabId	string	是	已接管的标签页
script.id	string	是	1–80 个字母、数字、_ 或 -；在这个标签页内唯一
script.source	string	是	一个函数 (args, { emit, onDispose }) => cleanup?，最多 64 KB；emit(data) 以 message 事件送达
script.args	unknown	否	以 JSON 传入

返回 Promise<void>。每个标签页最多 16 个脚本。

await ctx.browser.inject(tabId, {
  id: 'chat-watch',
  source: `(args, { emit }) => {
    const observer = new MutationObserver(() => emit({ count: document.querySelectorAll(args.selector).length }));
    observer.observe(document.body, { childList: true, subtree: true });
    return () => observer.disconnect();
  }`,
  args: { selector: '.message' }
});

ctx.browser.uninject(tabId, injectionId)

移除一个注入的脚本，并运行它的清理函数。

名称	类型	必填	说明
tabId	string	是	已接管的标签页
injectionId	string	是	传给 inject 的 id

返回 Promise<void>。

await ctx.browser.uninject(tabId, 'chat-watch');

ctx.browser.captureAudio(tabId)

还需要 audio。开始采集标签页的声音。

名称	类型	必填	说明
tabId	string	是	已接管且已加载完成的标签页

返回 Promise<AudioStream>：

字段	类型	说明
tabId · url · documentId		这个标签页，与 adoptTab 相同
streamId	string	这次采集
frames	AsyncIterable<{ streamId, sequence, timestamp, sampleRate, channels, pcm: Float32Array }>	声音，一块一块地送达
ended	Promise	采集结束时 settle
stop()	() => Promise<void>	停止采集

每个标签页同一时间只能有一个采集。

const stream = await ctx.browser.captureAudio(tabId);
for await (const chunk of stream.frames) handle(chunk.pcm, chunk.sampleRate);

ctx.browser.stopAudio(tabId)

停止这个标签页的采集。

名称	类型	必填	说明
tabId	string	是	正在采集的标签页

返回 Promise<void>。

await ctx.browser.stopAudio(tabId);

ctx.browser.onEvent(listener)

名称	类型	必填	说明
listener	(event) => void	是	Extension 的标签页每发生一个事件都会调用

返回 () => void，调用即停止监听。每个事件都带 tabId、url 和 documentId，以及一个 type：

type	附加字段	何时
url-changed · navigation-start · ready	—	页面跳转或加载完成
closed · crashed	—	标签页没了
injected	injectionId	安装了一个脚本
message	injectionId、data	注入的脚本调用了 emit(data)
error	code	标签页里有操作失败
audio-ended	streamId、lastSequence	一次采集结束

const off = ctx.browser.onEvent((event) => {
  if (event.type === 'message') ctx.emit({ text: String(event.data.count) });
  if (event.type === 'closed') off();
});

错误

这些函数以下列代码之一 reject：

代码	含义
capability_denied	没有声明 browser（或 audio）
invalid_tab · tab_not_granted · tab_not_owned	标签页 id 无效、Cowork 没有交出这个标签页，或它已被交还
origin_not_allowed	页面所在网站不在 dozin.origins 里
tab_limit · injection_limit	超过 8 个标签页或 16 个脚本
tab_unavailable · document_not_ready · stale_document	标签页已关闭、还在加载，或已加载了另一个页面
invalid_script · invalid_injection_id · injection_exists · invalid_json · result_too_large	输入或输出无效
audio_already_started · audio_transport_unavailable · invalid_audio_request	无法开始音频采集
session_closed · browser_operation_failed	Extension 正在停止，或 Cowork 无法完成这次调用

相关

• Injection 网页里的脚本
• Connector 最常使用 ctx.browser 的地方