@cloudflare/computer — долговечная файловая система и среды исполнения для ИИ-агента

@cloudflare/computer даёт ИИ-агенту долговечную рабочую папку, инструменты для изменения файлов и несколько сред исполнения. Если разработчик зарегистрировал нужные backend и открыл инструмент exec, модель может выбирать среду для каждой команды. Пакет направляет этот выбор описаниями backend, но не гарантирует правильную маршрутизацию автоматически.

Как устроен компьютер агента

Обычный агент состоит из цикла рассуждений и набора инструментов. Для работы с кодом этого мало: нужны файлы, Git, команды терминала, зависимости и тестовый раннер.

@cloudflare/computer добавляет рабочую среду между агентом и вычислительной инфраструктурой:

graph TD
    A["ИИ-агент"] --> B["Инструменты read, write, edit, ls, exec"]
    B --> C["Workspace в Durable Object"]
    C --> D["SQLite-файловая система"]
    C --> E["Worker shell"]
    C --> F["Worker JavaScript"]
    C --> G["Linux-контейнер"]
    G <-->|"FUSE и синхронизация"| D

Главным источником состояния остаётся файловая система Workspace. Worker shell и Worker JavaScript обращаются к ней через Durable Object. Контейнер получает проекцию файлов через FUSE и синхронизирует изменения по RPC.

Поэтому разные backend могут работать с одним деревом проекта. Для контейнера синхронизация является отдельным механизмом, а не прямым доступом к SQLite Durable Object.

Кому подходит пакет

• Командам, которые прототипируют собственную среду для coding-агента.
• Сценариям с небольшим рабочим деревом, долговечными файлами и несколькими исполнителями.
• Экспериментам, где нужно сравнить быстрый изолят с полноценным Linux-контейнером.

Пакет пока не подходит для production-систем с SLA, больших монорепозиториев и тяжёлых I/O-нагрузок.

Среды исполнения и три backend

В анонсе 3 августа Cloudflare описывала два класса исполнения: быстрый изолят и полноценный Linux-контейнер. Текущий репозиторий предоставляет три backend. Cloudflare называет эту модель «one execution surface, several backends»; деление на изоляты и контейнеры здесь используется только для удобства объяснения.

Практическое правило выбора:

• Файловые инструменты read, write, edit, ls, find и grep используйте без shell-команд, когда это возможно.
• Worker shell подходит для Git, поиска и лёгкой обработки текста.
• Worker JavaScript подходит для структурированных вычислений в ECMAScript-модуле.
• Контейнер нужен для пакетных менеджеров, тестовых раннеров и нативных зависимостей.

Описание каждого backend передаётся модели вместе с exec. Модель может выбрать значение параметра backend, но приложение должно проверить выбор и технически ограничить недопустимые команды.

Какие инструменты получает агент

Пакет предоставляет готовый набор инструментов, совместимый с AI SDK.

README текущего пакета также перечисляет find, grep и delete. Специализированные страницы документации preview-проекта могут отставать от README, поэтому проверяйте фактически возвращаемый ToolSet в закреплённой версии. Инструмент exec подключается отдельно, поскольку он разрешает модели выполнять произвольные команды.

Для агента, который должен только изучать проект, включите режим чтения:

const tools = createAITools({
  workspace,
  readonly: true,
});

По текущему README такой агент получает инструменты чтения и поиска без мутаций и exec. Точный состав набора сверяйте с установленной версией пакета.

Что нужно подготовить

• Node.js и npm для установки монорепозитория.
• Docker для локального запуска примера с контейнером.
• Wrangler и проект Workers с Durable Object.
• Флаг nodejs_compat; Worker shell и Worker JavaScript дополнительно требуют experimental и Worker Loader binding.
• Для деплоя примера think нужен аккаунт Cloudflare с доступными Workers AI и Worker Loaders.
• Закреплённый release или commit SHA, поскольку preview API меняется.

Быстрый старт на готовом примере

Для первого эксперимента удобнее взять официальный пример think. В нём уже настроены агент, Workspace, Worker shell и Linux-контейнер.

git clone https://github.com/cloudflare/computer
cd computer
npm install

cd examples/think
npm run dev

Во втором терминале запустите клиент:

cd examples/think
npm run chat

Для локального запуска нужен Docker: Wrangler собирает контейнер с computerd, Node.js, npm, Git и библиотеками FUSE. Каждое имя, переданное клиенту через --name, адресует отдельный экземпляр агента с собственным Workspace и историей. Worker shell используется по умолчанию, а контейнер вызывается, когда задаче нужен полный Linux.

После запуска отправьте минимальную проверку:

Создай файл /hello.txt со строкой hello.
Прочитай его через read и покажи каталог через ls.
Выполни cat /hello.txt в backend shell.
Выполни node --version в backend container.
Для обеих команд верни backend, exitCode, stdout и stderr.

Признаки успеха:

• read возвращает hello.
• Worker shell читает тот же файл.
• Контейнер видит файл через FUSE.
• node --version завершается с exitCode: 0.
• После повторного обращения к тому же экземпляру файл остаётся в Workspace.

Практический сценарий: исправить ошибку в репозитории

Центральный сценарий состоит из пяти этапов:

1. Клонировать репозиторий.
2. Изучить задачу и инструкции проекта.
3. Внести минимальную правку.
4. Запустить проверки в подходящем рантайме.
5. Сохранить доказательства выполнения.

Передайте агенту такой рабочий контракт:

Работай только внутри /workspace.

Если репозиторий ещё не загружен:
1. Клонируй его по HTTPS в /workspace/repo.
2. Прочитай AGENTS.md, README, манифесты и документы,
   относящиеся к задаче.
3. Определи стек и package manager по lock-файлу.
4. Не придумывай команды проверки: используй только существующие
   скрипты проекта, Makefile или команды из документации.

До изменения файлов:
1. Зафиксируй исходный git status.
2. Найди код, связанный с ошибкой.
3. Запиши краткий план в /workspace/ACTION_LOG.md.

Во время работы:
1. Используй read, ls, find и grep для анализа.
2. Вноси точечные изменения через edit.
3. Используй быстрый shell для поиска, Git и проверки диффа.
4. Используй container для установки зависимостей, сборки и тестов.
5. Не открывай и не изменяй секреты, .env и файлы учётных данных.
6. Не выполняй push и не создавай pull request.

После каждого шага обновляй ACTION_LOG.md:
- действие;
- использованный инструмент;
- выбранный backend;
- выполненная команда;
- exit code;
- краткий результат.

В конце:
1. Выполни git diff --check.
2. Запусти относящиеся к задаче тесты.
3. Покажи git status и итоговый diff.
4. Создай /workspace/REPORT.md с описанием правки,
   списком проверок и известными ограничениями.

Клонирование репозитория

Git-клиент можно подключить к Workspace отдельно от shell:

import { Workspace } from "@cloudflare/computer";
import { createGitClient } from "@cloudflare/computer/git";

const workspace = new Workspace({
  storage: ctx.storage,
  git: createGitClient(),
  defaultGitIdentity: {
    name: "Agent",
    email: "agent@example.test",
  },
});

await workspace.git.clone({
  url: "https://github.com/example/project.git",
  dir: "/workspace/repo",
});

Git работает непосредственно с SQLite-файловой системой. Для клонирования через встроенную команду Worker shell поддерживаются HTTPS-адреса.

Анализ задачи

На этом этапе контейнер обычно не нужен. Агент может прочитать инструкции и найти связанные участки кода через файловые инструменты:

ls /workspace/repo
read /workspace/repo/AGENTS.md
grep "calculateTotal" /workspace/repo/src
read /workspace/repo/src/billing.ts

Использование read и grep вместо cat и рекурсивных shell-команд уменьшает объём вывода, который возвращается модели.

Внесение правки

Инструмент edit выполняет точные замены и возвращает unified diff. Если ожидаемый фрагмент отсутствует или несколько замен пересекаются, операция завершается ошибкой.

Это позволяет проверить конкретный патч до запуска тестов и не перезаписывать большой файл целиком.

Запуск проверок

Быстрые проверки можно оставить в Worker shell:

git status --short
git diff --check
git diff --stat

Сначала определите package manager и доступные проверки по lock-файлу, манифесту и документации проекта. Для npm-проекта можно начать так:

npm run
npm ci
npm test

Запускайте lint, typecheck, сборку и другие проверки только в том случае, если соответствующие команды определены в проекте. Для pnpm, Yarn, Bun, Python, Go или Rust используйте нативные команды выбранного стека.

Успешный результат должен содержать:

• Backend container.
• exitCode: 0.
• Ожидаемый вывод тестового раннера.
• Отсутствие ошибок в stderr.
• Итоговый diff только по файлам задачи.

Если проекту не нужны Node.js, нативные зависимости или полноценный shell, проверку можно оставить в изоляте.

Человеко-читаемая сводка и проверяемый журнал

Cloudflare описывает операции Workspace как gated, audited and observed. Структурированный результат exec содержит команду, backend, exitCode, stdout и stderr.

ACTION_LOG.md, который пишет сама модель, остаётся только человеко-читаемой сводкой: агент может пропустить действие, ошибиться или переписать файл. Для проверяемого журнала приложение должно записывать вызовы инструментов и фактические результаты в append-only хранилище, недоступное агенту для изменения.

Условный пример сводки ACTION_LOG.md:

# Action log

## 2026-08-15T08:20:00Z — Repository prepared
- Tool: exec
- Backend: shell
- Command: git clone https://github.com/example/project.git /workspace/repo
- Exit code: 0
- Evidence: repository cloned, branch main

## 2026-08-15T08:22:00Z — Relevant code located
- Tools: read, grep
- Files: src/billing.ts, tests/billing.test.ts
- Finding: empty cart reaches calculateDiscount without validation

## 2026-08-15T08:25:00Z — Patch applied
- Tool: edit
- Files changed: src/billing.ts, tests/billing.test.ts
- Evidence: unified diff saved in tool result

## 2026-08-15T08:29:00Z — Verification
- Tool: exec
- Backend: container
- Command: npm test
- Exit code: 0
- Evidence: <количество> tests passed

REPORT.md должен содержать итог, а не пересказ всего процесса:

# Result

## Changed
Добавлена проверка пустой корзины и тест на возврат нулевой скидки.

## Verification
- <команда тестов проекта>: passed
- <дополнительная проверка проекта>: passed
- git diff --check: passed

## Files
- src/billing.ts
- tests/billing.test.ts

## Remaining risks
Проверка выполнена только на поддерживаемой версии Node.js из проекта.

Другие практические сценарии

Ограничения и безопасность

• Один Workspace рассчитан примерно на 10 ГБ и делит хранилище с Durable Object.
• Контейнерная сторона держит файловое дерево в памяти. Большие монорепозитории для такой схемы не подходят.
• FUSE добавляет накладные расходы при больших установках зависимостей, распаковке архивов и интенсивном последовательном вводе-выводе.
• Worker shell реализует ограниченный набор команд. Дополнительные группы вроде curl, jq, python и sqlite подключаются явно.
• exec выполняет произвольные команды. Для обзорных и индексирующих агентов используйте readonly: true или не подключайте exec.
• Не передавайте агенту секреты, которые не нужны для задачи. Право push и другие опасные действия блокируйте разрешениями.
• Задавайте egress-политику отдельно для каждого backend: none, all или собственный allowlist.
• Считайте вывод команд недоверенным текстом, прежде чем возвращать его модели.
• API пакета и состав инструментов меняются. Закрепляйте версию и сверяйте README, примеры и release notes.
• Спецификация в docs/ может описывать будущий замысел, а не текущее поведение кода.

Официальные ссылки

• Анонс Cloudflare
• Запись в changelog
• Репозиторий cloudflare/computer
• Документация пакета
• Интерфейс инструментов для агентов
• Готовый пример с Worker shell и контейнером

По теме

Продолжение темы показывает, как рабочая среда соединяется с жизненным циклом и инфраструктурой агента.

Следующий шаг

• Cloudflare Agents SDK — stateful AI-агенты на Durable Objects

Связанные материалы

• Статья: Cloudflare OS: как компания собрала внутренний ИИ-воркспейс и раздала его всем сотрудникам
• Блог: Agent Plugins: переносимые компетенции для ИИ-агентов
• База знаний: OpenAI Codex — облачный coding-агент для параллельной разработки

Если вы проектируете рабочую среду для coding-агента, заранее определите границы файлов, команд, сетевого доступа и доказательств выполнения. Такая схема особенно полезна командам, которые хотят запускать агентов в собственном инфраструктурном контуре.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov