Агенты и автоматизация
Объединяйте проверку, редактирование и валидацию в инструменты существующего агента.
AI SDK предоставляет модели Univer, Facade и совместную работу как составные TypeScript-возможности для существующего Agent. Он может изучать, изменять, проверять и передавать содержимое на проверку. Модель, протокол инструментов и управление задачами выбирает приложение.
Подключение возможностей к Agent
Пакеты возможностей возвращают структурированные результаты для инструментов, сервисов или CLI. Необязательные пакеты -command предоставляют команды Commander. Agent использует ту же модель содержимого и систему команд, что и Web-редактор.
| Возможность | Ответственность |
|---|---|
| Inspection | Чтение структуры, диапазонов, абзацев и объектов для уточнения цели. |
| API Reference | Локальный поиск включённых объявлений Facade, перегрузок, типов и примеров. |
| Content Execution | Привязка workbook, doc, presentation, base или board к явной Unit. |
| Collaboration Runtime | Загрузка, захват mutations, согласование удалённых изменений и отправка changesets. |
Как Runtime восстанавливает редактируемое состояние
Collaboration Runtime связан с одной Unit всю свою жизнь. Он открывает backend приложения, читает checkpoint UnitData или Snapshot, воспроизводит changesets и заполняет непрерывный диапазон revision до удалённой вершины. При установленном модуле формул ожидается применение последнего расчёта.
fetch() получает и проверяет изменения. pull() согласует их с локальными pending/awaiting через OT, затем применяет. baseRevision, knownHeadRevision, pendingMutationCount и awaitingChangeset позволяют отслеживать состояние.
Выбор содержимого перед выполнением
Начните с overview, затем читайте по стабильным ID или точным селекторам, не отправляя модели весь Snapshot. Поддерживаются диапазоны Sheet, абзацы Doc, страницы Slide, обзор структуры Relational Table и объекты Canvases. Обзор Relational Table включает настройки полей, но не значения записей и View projection; их при необходимости читают через Facade.
prepareContentExecutionProgram() получает корневую Facade по Unit ID независимо от выбора в браузере и запрещает повторное объявление внедрённых переменных. Режим read блокирует сохраняемые бизнес-операции до выполнения, write захватывает mutations целевой Unit. Создание и уничтожение Units относятся к отдельным операциям жизненного цикла.
Используйте find() для поиска кандидатов и show() для точных объявлений и связанных типов. Встроенный индекс работает без движка и онлайн-документации. См. операции с содержимым и пакеты.
Выполнение и подтверждённое сохранение
execute({ mode: 'write' }) меняет Unit в памяти и накапливает pending. Это не подтверждение сохранения на сервере. commit() отправляет идентифицированный changeset и проверяет идентификатор, содержимое и revision ACK до подтверждения.
| Статус | Действие приложения |
|---|---|
confirmed / nothing-to-commit | Изменения подтверждены либо отправлять нечего. |
pull-required | Удалённая версия продвинулась: выполните pull(), затем commit(). |
retry / unknown | Сохраните awaiting в том же Runtime и повторите commit(), а не программу редактирования. |
conflict | Остановите запись и выберите восстановление или перезагрузку. |
При неопределённом результате сохраняется sid + reqId, чтобы backend идемпотентно подтвердил тот же changeset без дублирования правок. Backend обязан поддерживать этот контракт. Исключение в программе может оставить уже выполненные mutations: проверьте pending перед восстановлением. execute() не является транзакцией с автоматическим откатом.
Пример получает загруженный Sheet Runtime и возвращает результат выполнения и статус отправки. Вызывающий код обрабатывает статусы и закрывает Runtime по завершении владения.
import { prepareContentExecutionProgram } from '@univer-cli/content-execution'import type { UniverCollaborationRuntime } from '@univer-cli/univer-collaboration-runtime'async function updateSales(runtime: UniverCollaborationRuntime) { const pulled = await runtime.pull() if (pulled.status === 'conflict') return pulled const code = prepareContentExecutionProgram({ unitId: runtime.unitId, unitType: 'sheet', code: ` const sheet = workbook.getSheetByName('Data'); if (!sheet) throw new Error('Worksheet Data not found'); sheet.getRange('A2:B2').setValues([ [{ v: 'East', t: 1 }, { v: 128000, t: 2 }] ]); return sheet.getRange('A2:B2').getRawValues(); `, }) const execution = await runtime.execute({ mode: 'write', code }) const commit = await runtime.commit() return { execution, commit }}Повторное использование Runtime
Пул эксклюзивно выдаёт Worker Runtime по key приложения. Холодное создание использует single-flight, leases ожидают в FIFO; разные keys могут обрабатываться разными Workers. release() возвращает экземпляр, TTL/LRU освобождает простаивающие ресурсы, invalidate() выводит ненадёжный экземпляр из использования.
Key должен различать backend, Unit и Worktree. Пул не проверяет смысловую совместимость init. Daemon может удерживать пул между короткими CLI-вызовами, но синхронизация и подтверждение всё равно нужны. Учитывайте запуск, резидентную память и число Workers; см. повторное использование и daemon.
От автоматизации к проверке человеком
Составляйте отчёты, очистку данных, заполнение шаблонов и генерацию: найдите цель, запишите через Facade, дождитесь расчётов, перечитайте значения, текст и свойства, затем добавьте визуальную проверку.
Для согласования используйте Worktree: Agent редактирует и проверяет, отмечает Ready, а человек решает Merge. Отслеживайте результаты каждой Unit отдельно: несколько Runtimes не образуют атомарную транзакцию между документами.
Приложение отвечает за идентификацию, права, модель и задачи. Ограничения read/write защищают бизнес-операции; изоляция процессов и права файлов/сети для недоверенного JavaScript также настраиваются приложением. Попробуйте быстрый старт и пример CLI.
Насколько полезно это руководство?