Агенты и автоматизация

Объединяйте проверку, редактирование и валидацию в инструменты существующего агента.

AI SDK раскрывает модели контента Univer, Facades и коллаборацию в качестве композитных возможностей TypeScript. Существующий Агент может читать контент, изменять его, проверять результат и передавать его для обзора. Приложение выбирает модель, протокол инструмента и метод оркестровки.

Подключение возможностей к Agent

Пакеты возможностей возвращают структурированные результаты, которые приложение может передать своим собственным инструментам, службам или CLI. Дополнительные пакеты -command открывают те же возможности, что и собственные команды Commander. Обе формы работают на модели контента и системе команд, совместно используемой с веб-редактором.

ВозможностьОтветственность
InspectionСчитывает структуру, диапазоны, абзацы и детали объекта, чтобы сузить задачу.
API ReferenceЗапросите вложенные объявления Фасада, перегрузки, типы и примеры в автономном режиме.
Content ExecutionСоединяет workbook, doc, presentation, base или board с конкретным блоком и подготавливает код для выполнения.
Collaboration RuntimeЗагружает контент, фиксирует мутации, согласовывает удаленные изменения и явно фиксирует изменения.

Как Runtime восстанавливает редактируемое состояние

Collaboration Runtime остается привязанным к одному блоку в течение всего срока его службы. Во время загрузки он открывает бэкэнд, предоставляемый приложением, считывает контрольную точку UnitData или Snapshot, и переигрывает заменители поверх этой контрольной точки. Затем он закрывает непрерывный разрыв доработки к удаленной головке и, когда модуль формулы установлен, ждет последних результатов расчета.

100%

fetch() извлекает изменения и проверяет их. pull() примиряет удаленные изменения с локальным ожидающим и ожидающим состоянием через OT, затем применяет результат. Время выполнения раскрывает baseRevision, knownHeadRevision, pendingMutationCount и awaitingChangeset, чтобы приложение могло оценить прогресс.

Выбор содержимого перед выполнением

Сначала предоставьте модель с обзором, затем запросите стабильный идентификатор или точный селектор вместо отправки полного Снимка. Инспекция охватывает диапазоны листов, абзацы документов, страницы слайдов, обзоры схем реляционной таблицы и объекты Canvases. Обзор реляционной таблички включает конфигурацию поля, но не записывает значения или проекции просмотра; прочитайте их через Фасады, когда это необходимо.

prepareContentExecutionProgram() устраняет корень Facade из идентификатора Unit, независимо от текущего выбора браузера, и он отвергает повторное декларирование вводимого связывания. В режиме чтения Runtime блокирует бизнес-действия, которые будут сохраняться до их запуска; в режиме записи он захватывает мутации целевого блока. Создание и удаление блока являются отдельными операциями жизненного цикла и лежат за пределами этой записи выполнения одного блока.

Когда API незнаком, find() перечисляет кандидатов, а show() печатает точную декларацию вместе с соответствующими типами. Ссылка распространяется с SDK, поэтому не требует ни движка контента, ни онлайн-документации. См. контент-операции и обзор пакета.

Выполнение и подтверждённое сохранение

execute({ mode: 'write' }) модифицирует живой блок и накапливает ожидающие мутации. Это не означает, что сервер сохранил изменения. commit() создает набор изменений с прикрепленной идентичностью; ACK должен соответствовать этой идентичности, полезной нагрузке и пересмотру, прежде чем изменение будет считаться подтвержденным.

СтатусДействие приложения
confirmed / nothing-to-commitИзменения либо подтверждены, либо нечего было предъявить.
pull-requiredУдаленный пересмотр продвинулся. Позвоните pull(), чтобы помириться, а затем снова позвоните commit().
retry / unknownСохраняйте состояние ожидания в том же времени выполнения и повторите commit(). Не перезапускайте программу редактирования.
conflictОстановите запись и выберите восстановление или перезагрузку.

Когда результат представления неясен, Runtime сохраняет sid + reqId, поэтому бэкэнд может подтвердить те же изменения, вместо того, чтобы дублировать правки. Бэкэнд должен реализовать этот контракт идемпотентности. Программа, которая бросает, может оставить мутации, которые она уже сделала на месте, поэтому проверьте ожидающее состояние и решите, как восстановить. execute() не является транзакцией, которая автоматически откатывается назад.

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

TypeScript
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

Частые задачи могут арендовать Рабочее время выполнения исключительно под ключ, принадлежащий приложению. Холодное создание - это один полет на ключ, аренда стоит в очереди в FIFO, и разные ключи могут использовать разных Рабочих. release() возвращает экземпляр, TTL/LRU выселение возвращает неработающие ресурсы, а invalidate() удаляет экземпляр, который больше не заслуживает доверия.

Ключ должен различать бэкэнд, блок и Worktree. Бассейн не проверяет, совместимы ли два набора входов инициализации. Демон может удерживать пул при коротких вызовах CLI, но повторно используемое время выполнения по-прежнему требует синхронизации и подтверждения выполнения. Приложение должно сбалансировать стоимость запуска с резидентной памятью и количеством рабочих; см. Повторное использование Runtime и демон .

От автоматизации к проверке человеком

Возможности могут быть объединены для отчетности, очистки данных, заполнения шаблонов или генерации контента. Поток определяет местоположение цели, записывает через Facades, ждет любого расчета, от которого зависит результат, и считывает значения, текст и свойства объекта. Добавьте визуальный осмотр, когда задача требует этого.

Для согласования рабочих процессов Агент работает в Worktree. Он редактирует и проверяет в раундах, а затем человек просматривает готовый контент и решает, следует ли сливаться. Отслеживать выполнение и фиксировать результаты на единицу, потому что несколько Runtimes вместе не образуют перекрестную документную атомную транзакцию.

Приложение владеет идентичностью, авторизацией, интеграцией моделей и жизненным циклом задач. Ограничения чтения и записи обеспечивают соблюдение границы вокруг бизнес-операций, в то время как изоляция процессов и разрешения файлов или сетей для ненадежных JavaScript остаются ответственностью приложения. См. Начинать и Пример Univer CLI.

Создание и редактирование содержимого с помощью Skills

Чтобы существующий агент работал непосредственно с контентом Office, начните с приложения, которое соответствует местоположению файлов:

  • Навыки CLI: Создавайте, редактируйте и проверяйте локальные файлы Office, а затем откройте Viewer для просмотра.
  • Навыки рабочего пространства: работа над файлами в подключенном пространстве, создание контента Office и веб-приложений, а также внесение изменений для совместной работы и просмотра.

К списку возможностей

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.