OPFS 文件 API

@grant CAT.agent.opfs

OPFS（Origin Private File System）文件 API 允许脚本在 Agent 工作区中读写文件。所有路径相对于 agents/workspace/ 目录。

write — 写入文件

const result = await CAT.agent.opfs.write(path, content);

参数：

参数	类型	说明
path	string	文件路径（必填），支持多级目录
content	string | Blob	文件内容

content 支持的格式：

格式	说明
普通字符串	保存为 UTF-8 文本文件
data URL 字符串	自动解码为二进制保存（如 data:image/png;base64,...）
Blob 对象	直接保存二进制数据

返回值 WriteResult：

字段	类型	说明
path	string	文件保存路径
size	number	文件大小（字节）

// 写入文本文件
await CAT.agent.opfs.write("data/config.json", JSON.stringify({ key: "value" }));

// 写入二进制文件（data URL）
const canvas = document.createElement("canvas");
const dataUrl = canvas.toDataURL("image/png");
await CAT.agent.opfs.write("images/chart.png", dataUrl);

如果路径中的父目录不存在，会自动创建。如果文件已存在，内容会被覆盖。

read — 读取文件

const result = await CAT.agent.opfs.read(path, format?);

参数：

参数	类型	默认值	说明
path	string	—	文件路径（必填）
format	"text" | "bloburl"	"text"	读取格式

返回值 ReadResult：

字段	类型	条件	说明
path	string	始终	文件路径
size	number	始终	文件大小
content	string	format="text"	文件文本内容
blobUrl	string	format="bloburl"	blob URL
mimeType	string	format="bloburl"	MIME 类型

两种读取模式：

// 文本模式 — 适合 JSON、文本文件
const config = await CAT.agent.opfs.read("data/config.json");
const data = JSON.parse(config.content);

// Blob URL 模式 — 适合图片、二进制文件
const image = await CAT.agent.opfs.read("images/chart.png", "bloburl");
// image.blobUrl = "blob:chrome-extension://xxx/yyy"
// 可以在 ISOLATED world 的 executeScript 中使用这个 URL

支持的 MIME 类型自动识别：

扩展名	MIME 类型
.jpg / .jpeg	image/jpeg
.png	image/png
.gif	image/gif
.webp	image/webp
.svg	image/svg+xml
.mp3	audio/mpeg
.wav	audio/wav
.mp4	video/mp4
.pdf	application/pdf
.json	application/json
.txt	text/plain
.html	text/html
.css	text/css
.js	application/javascript
其他	application/octet-stream

list — 列出目录

const entries = await CAT.agent.opfs.list(path?);

参数：

参数	类型	默认值	说明
path	string	""	目录路径，空字符串为根目录

返回值 FileEntry[]：

字段	类型	说明
name	string	文件/目录名
type	"file" | "directory"	类型
size	number	文件大小（仅 file 类型）

const entries = await CAT.agent.opfs.list("data/");
for (const entry of entries) {
  if (entry.type === "file") {
    console.log(`${entry.name} (${entry.size} bytes)`);
  } else {
    console.log(`${entry.name}/`);
  }
}

delete — 删除文件或目录

const result = await CAT.agent.opfs.delete(path);

支持递归删除目录及其所有内容。

返回值：

{ success: true }

readAttachment — 读取附件

const result = await CAT.agent.opfs.readAttachment(attachmentId);

读取对话中的附件数据（图片、文件等）。附件 ID 来自消息中的 ContentBlock.attachmentId。

参数：

参数	类型	说明
attachmentId	string	附件 ID（必填）

返回值：

字段	类型	说明
id	string	附件 ID
data	Blob	附件二进制数据
size	number	文件大小（字节）
mimeType	string	MIME 类型

// 读取对话中 AI 生成的图片附件
const messages = await conv.getMessages();
const lastMsg = messages[messages.length - 1];
const imageBlock = lastMsg.content.find(b => b.type === "image");
if (imageBlock) {
  const attachment = await CAT.agent.opfs.readAttachment(imageBlock.attachmentId);
  console.log(`附件大小: ${attachment.size}, 类型: ${attachment.mimeType}`);
}

Blob URL 使用注意事项

• Blob URL 格式为 blob:chrome-extension://xxx/yyy
• 只能在 ISOLATED world 中使用（executeScript 的默认环境）
• 在 MAIN world（页面环境）中无法访问扩展的 blob URL
• Blob URL 的生命周期与扩展 session 绑定

// 正确：在 ISOLATED world 中使用 blob URL
const img = await CAT.agent.opfs.read("images/photo.png", "bloburl");
await CAT.agent.dom.executeScript(`
  const img = document.createElement("img");
  img.src = "${img.blobUrl}";
  document.body.appendChild(img);
`, { world: "ISOLATED" });

// 错误：MAIN world 无法访问
await CAT.agent.dom.executeScript(`
  fetch("${img.blobUrl}") // 会失败！
`, { world: "MAIN" });