API файлов OPFS

@grant CAT.agent.opfs

API файлов OPFS (Origin Private File System) позволяет скрипту читать и записывать файлы в рабочем пространстве 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	Размер файла в байтах

// Write a text file
await CAT.agent.opfs.write("data/config.json", JSON.stringify({ key: "value" }));

// Write a binary file (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-тип

Два режима чтения:

// Text mode — good for JSON and text files
const config = await CAT.agent.opfs.read("data/config.json");
const data = JSON.parse(config.content);

// Blob URL mode — good for images and binary files
const image = await CAT.agent.opfs.read("images/chart.png", "bloburl");
// image.blobUrl = "blob:chrome-extension://xxx/yyy"
// This URL can be used inside an executeScript call in the ISOLATED world

Автоматически распознаваемые 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-тип

// Read an image attachment generated by the AI in a conversation
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.size}, type: ${attachment.mimeType}`);
}

Замечания по использованию Blob URL

• Blob URL имеют вид blob:chrome-extension://xxx/yyy
• Можно использовать только в мире ISOLATED (окружение executeScript по умолчанию)
• Blob URL расширения недоступны из мира MAIN (окружение страницы)
• Время жизни blob URL привязано к сессии расширения

// Correct: use the blob URL in the ISOLATED world
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" });

// Wrong: not accessible from the MAIN world
await CAT.agent.dom.executeScript(`
  fetch("${img.blobUrl}") // this will fail!
`, { world: "MAIN" });