Offscreen Document 剪贴板兼容层

本文引用的源码文件

本文引用的文件

引言

本文件聚焦于 MV3 扩展中的 Offscreen Document 剪贴板兼容层，解释为什么在 Manifest V3 下需要借助 Offscreen Document 来读写系统剪贴板，并给出该兼容层的生命周期、消息协议、错误处理、性能策略和常见问题解决方案。

MV3 的 Background Service Worker 被设计为按需启动、空闲回收，且对部分浏览器 API（如剪贴板）的支持受限；因此，本项目将“复制”和“粘贴”等剪贴板操作下沉到独立的 Offscreen Document 中执行，Background Service Worker 仅负责协调、复用文档实例并通过 chrome.runtime.sendMessage 进行跨上下文通信。

项目结构定位

Offscreen Document 兼容层位于 src/offscreen/，由一个最小 HTML 页面和一个 JS 模块组成：

offscreen.html：提供隐藏的 <textarea> 作为剪贴板操作的 DOM 回退载体。
offscreen.js：监听来自 Background 的消息，调用 navigator.clipboard 完成复制/粘贴，并在失败时回退到 document.execCommand。

Background 侧通过 tool-executor.js 暴露统一的剪贴板工具入口，对外以 clipboard 工具的形式向 ReAct 执行循环暴露能力。

graph TB
subgraph "Background Service Worker"
BE["tool-executor.js<br/>ensureOffscreenDocument()<br/>executeCopyToClipboard()<br/>executePasteFromClipboard()"]
MT["media-tools.js<br/>clipboard 工具定义"]
end
subgraph "Offscreen Document"
OH["offscreen.html<br/>隐藏 textarea"]
OJ["offscreen.js<br/>COPY_TO_CLIPBOARD<br/>PASTE_FROM_CLIPBOARD"]
end
MT --> BE
BE --> |chrome.offscreen.createDocument| OH
BE --> |chrome.runtime.sendMessage| OJ
OJ --> |navigator.clipboard / execCommand| System["系统剪贴板"]

图表来源

章节来源

docs/en/DOCUMENTATION.md#L86-L89

核心组件

Offscreen Document 页面与脚本：承载剪贴板 API 调用与回退逻辑。
Background 剪贴板工具：统一入口、文档创建与复用、消息路由。
构建脚本：确保 offscreen 资源正确打包并复制到发布产物。

章节来源

架构总览

下图展示从模型调用剪贴板工具到最终写入系统剪贴板的完整流程。

sequenceDiagram
participant Model as "ReAct 执行器"
participant BG as "Background tool-executor.js"
participant OS as "Offscreen Document"
participant CL as "系统剪贴板"
Model->>BG : 调用 clipboard(action, text/format)
BG->>BG : ensureOffscreenDocument()
BG->>OS : sendMessage({type : COPY/PASTE})
OS->>CL : navigator.clipboard.writeText/readText
alt 成功
CL-->>OS : 成功
OS-->>BG : {success : true,...}
BG-->>Model : 工具结果
else 失败
OS->>OS : 回退到 textarea + execCommand
OS-->>BG : {success : false,error}
BG-->>Model : 工具错误
end

图表来源

详细组件分析

Offscreen Document 页面与脚本

offscreen.html 提供一个不可见的 <textarea id="clipboard-textarea">，用于在 navigator.clipboard 不可用或权限不足时，通过 document.execCommand('copy'|'paste') 实现回退。
offscreen.js 注册 i18n 文案，监听 chrome.runtime.onMessage，处理两类消息：
- COPY_TO_CLIPBOARD：优先调用 navigator.clipboard.writeText，失败则尝试 textarea 回退。
- PASTE_FROM_CLIPBOARD：优先调用 navigator.clipboard.readText，失败则尝试 textarea 回退。
所有返回均包含 success 字段，必要时附带 message 或 error，便于 Background 侧统一处理。

flowchart TD
Start(["收到 onMessage"]) --> Type{"消息类型"}
Type --> |COPY_TO_CLIPBOARD| Write["navigator.clipboard.writeText(text)"]
Write --> WOk{"写入成功?"}
WOk --> |是| WResp["sendResponse({success:true,message})"]
WOk --> |否| FallbackW["textarea.value=text<br/>select()<br/>execCommand('copy')"]
FallbackW --> FWok{"execCommand 成功?"}
FWok --> |是| FWResp["sendResponse({success:true,message})"]
FWok --> |否| FWErr["sendResponse({success:false,error})"]
Type --> |PASTE_FROM_CLIPBOARD| Read["navigator.clipboard.readText()"]
Read --> ROk{"读取成功?"}
ROk --> |是| RResp["sendResponse({success:true,text})"]
ROk --> |否| FallbackR["textarea.focus()<br/>execCommand('paste')<br/>读取 value"]
FallbackR --> FRok{"成功且有文本?"}
FRok --> |是| FRResp["sendResponse({success:true,text})"]
FRok --> |否| FRerr["sendResponse({success:false,error})"]

图表来源

章节来源

Background 剪贴板工具与文档生命周期

ensureOffscreenDocument()：
- 先通过 chrome.runtime.getContexts 检查是否已有目标 URL 的 Offscreen Document。
- 若不存在，则调用 chrome.offscreen.createDocument，传入 reasons: ['CLIPBOARD'] 与说明文本。
- 使用 creatingOffscreenDocument 变量避免并发重复创建。
executeCopyToClipboard(args, toolCallId)：
- 校验 text 参数。
- 确保 Offscreen Document 存在后，发送 COPY_TO_CLIPBOARD 消息。
- 根据响应封装工具结果。
executePasteFromClipboard(args, toolCallId)：
- 确保 Offscreen Document 存在后，发送 PASTE_FROM_CLIPBOARD 消息。
- 根据响应封装工具结果。
executeClipboard(args, toolCallId)：
- 统一入口，按 action 分发到 copy/paste/get_selected。
- get_selected 走 Content Script 路径，不经过 Offscreen Document。

classDiagram
class ToolExecutor {
+ensureOffscreenDocument()
+executeClipboard(args, toolCallId)
+executeCopyToClipboard(args, toolCallId)
+executePasteFromClipboard(args, toolCallId)
}
class MediaTools {
+clipboard 工具定义
}
class OffscreenDoc {
+onMessage(COPY_TO_CLIPBOARD)
+onMessage(PASTE_FROM_CLIPBOARD)
}
ToolExecutor --> OffscreenDoc : "sendMessage"
MediaTools --> ToolExecutor : "声明工具"

图表来源

章节来源

构建与打包注意事项

scripts/fix-build.js 中的 copyOffscreenDocument() 会将 src/offscreen 复制到 dist 目录。
对于 .js 文件，使用 esbuild 打包为 IIFE，以避免在普通 script 标签加载 ES module 时报错。
非 JS 文件直接复制。

章节来源

scripts/fix-build.js#L354-L397

依赖关系分析

Background 侧：
- tool-executor.js 依赖 chrome.offscreen、chrome.runtime API。
- media-tools.js 声明 clipboard 工具，供上层 ReAct 调度。
Offscreen 侧：
- offscreen.js 依赖 navigator.clipboard 与 document.execCommand。
- offscreen.html 提供 DOM 回退元素。
构建侧：
- fix-build.js 保证 offscreen 资源可被扩展加载。

graph LR
MT["media-tools.js"] --> TE["tool-executor.js"]
TE --> OD["offscreen.html"]
TE --> OJ["offscreen.js"]
OJ --> NB["navigator.clipboard"]
OJ --> DC["document.execCommand"]
FB["fix-build.js"] --> OD
FB --> OJ

图表来源

章节来源

性能与资源管理

文档复用：
- 通过 chrome.runtime.getContexts 检测已存在的 Offscreen Document，避免重复创建。
- 使用 creatingOffscreenDocument Promise 防止并发多次创建。
资源清理：
- 当前实现未显式销毁 Offscreen Document；Chrome 会在不再需要时回收。
- 建议在扩展卸载或明确关闭相关功能时，考虑主动销毁（如需）。
消息开销：
- 每次剪贴板操作都会触发一次 Background ↔ Offscreen 消息往返。
- 批量操作建议合并为单次请求，减少消息次数。
回退路径成本：
- 当 navigator.clipboard 失败时，会触发 DOM 操作与 execCommand，可能带来额外开销。
- 应尽量避免频繁触发回退路径，优先保证主路径可用。

[本节为通用性能建议，不直接分析具体代码行]

故障排查指南

Offscreen Document 无法创建：
- 检查 manifest 是否允许 offscreen 能力，并确保 reasons 包含 CLIPBOARD。
- 确认 chrome.offscreen.createDocument 调用未被阻塞（例如并发创建）。
- 查看 Background 日志中 ensureOffscreenDocument 是否抛出异常。
复制/粘贴失败：
- 优先检查 navigator.clipboard 是否可用及权限是否授予。
- 若进入回退路径，确认 offscreen.html 中的 clipboard-textarea 是否存在且可聚焦。
- 检查 offscreen.js 中 sendResponse 是否正确返回 {success, message|error}。
通信失败：
- 确认 Background 与 Offscreen 之间的 chrome.runtime.sendMessage 能正常建立通道。
- 检查构建产物中 offscreen/offscreen.html 与 offscreen/offscreen.js 是否存在且可加载。
- 关注 fix-build.js 是否成功将 offscreen 资源打包为 IIFE。
工具无响应：
- 确认 clipboard 工具已启用，且 action 参数合法。
- 检查 executeClipboard 的分发逻辑是否命中预期分支。

章节来源

结论

Offscreen Document 剪贴板兼容层在本项目中承担了 MV3 环境下剪贴板能力的关键职责：Background 负责文档生命周期管理与消息路由，Offscreen 负责实际剪贴板 API 调用与回退实现。该方案在保证安全性的同时，提供了稳定的复制/粘贴能力，并通过统一的工具接口向上层 ReAct 执行循环暴露。

附录：使用示例与最佳实践

在扩展中调用剪贴板复制：
- 通过 Background 的 clipboard 工具，传入 action: 'copy' 与 text。
- Background 会自动确保 Offscreen Document 存在并向其发送 COPY_TO_CLIPBOARD。
在扩展中调用剪贴板粘贴：
- 通过 Background 的 clipboard 工具，传入 action: 'paste'。
- Background 自动发送 PASTE_FROM_CLIPBOARD，并将结果返回给调用方。
获取页面选中内容：
- 使用 action: 'get_selected'，该路径走 Content Script，不走 Offscreen Document。
最佳实践：
- 避免频繁创建 Offscreen Document，复用现有实例。
- 对大文本复制/粘贴做长度限制与错误提示。
- 在 UI 层区分成功与失败状态，并展示用户友好的提示信息。
- 保持 i18n 文案一致，避免硬编码字符串。

章节来源

消息流与工具调用

RAG 数据处理管道

工具面板集成

聊天管理系统

主题与国际化系统

UI 组件库

Markdown 渲染引擎

Offscreen Document 剪贴板兼容层

目录

引言

项目结构定位

核心组件

架构总览

详细组件分析

Offscreen Document 页面与脚本

Background 剪贴板工具与文档生命周期

构建与打包注意事项

依赖关系分析

性能与资源管理

故障排查指南

结论

附录：使用示例与最佳实践

Markdown 渲染引擎

Offscreen Document 剪贴板兼容层 ​

目录 ​

引言 ​

项目结构定位 ​

核心组件 ​

架构总览 ​

详细组件分析 ​

Offscreen Document 页面与脚本 ​

Background 剪贴板工具与文档生命周期 ​

构建与打包注意事项 ​

依赖关系分析 ​

性能与资源管理 ​

故障排查指南 ​

结论 ​

附录：使用示例与最佳实践 ​

Offscreen Document 剪贴板兼容层

目录

引言

项目结构定位

核心组件

架构总览

详细组件分析

Offscreen Document 页面与脚本

Background 剪贴板工具与文档生命周期

构建与打包注意事项

依赖关系分析

性能与资源管理

故障排查指南

结论

附录：使用示例与最佳实践