# AI SDK

> Как AI SDK добавляет CLI Node.js и точку входа AI Agent в приложение Univer.

- Human documentation: [https://docs.univer.ai/ru-RU/ai](https://docs.univer.ai/ru-RU/ai)

- Agent Markdown: [https://docs.univer.ai/ru-RU/ai.md](https://docs.univer.ai/ru-RU/ai.md)

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [index.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/ai/index.ru-RU.mdx)

---

Univer Office SDK включает [Web SDK](https://docs.univer.ai/ru-RU/guides/sheets.md) для встроенных редакторов и обработки контента без интерфейса, [Server SDK](https://docs.univer.ai/ru-RU/server.md) для совместной работы и импорта и экспорта файлов, а также [AI SDK](https://docs.univer.ai/ru-RU/ai.md) для рабочих процессов агентов.

**AI SDK** — TypeScript SDK для создания CLI Office. Он предоставляет AI Agent и автоматизации точку входа Node.js для загрузки, понимания, изменения и проверки Units[^document-unit] Univer.

AI SDK — набор сочетаемых возможностей, а не фиксированная продуктовая CLI. Имена команд, аргументы, цели, идентификацию и авторизацию, вывод и развёртывание определяет бизнес-приложение.

## Рекомендуемая структура приложения

Руководство использует схему `CLI + Web + Server`:

```mermaid
flowchart LR
    Agent(["AI Agent / пользователь CLI"]) --> CLI["<b>AI SDK</b><br/>Бизнес-CLI"]
    Human(["Пользователь"]) --> Web["<b>Web SDK</b><br/>Web"]
    CLI --> Server["<b>Server SDK</b><br/>Совместная работа · Преобразование файлов"]
    Web --> Server
    Server --> Storage["Хранилище"]
    classDef default rx:8,ry:8,stroke-width:1px
    classDef actor fill:transparent,stroke:none
    class Agent,Human actor
```

* CLI — точка входа для AI Agent или пользователя, работающего с Unit.
* Web показывает настоящую страницу для интерактивного редактирования и проверки человеком.
* Server хранит Units, ревизии и состояние совместной работы, общие для CLI и Web.

Компоненты можно развернуть отдельно или полностью локально. Создание Web + Server с Collaboration SDK до добавления CLI — рекомендуемый порядок обучения, не ограничение развёртывания.

> [!NOTE: Поддерживаются и приложения только с CLI]
> AI SDK может напрямую обрабатывать локальные Units. Результат проверяется структурированным выводом, визуальной проверкой AI Agent или экспортированными файлами Office. Живые Web-страницы, общие ревизии, History и Worktree требуют соответствующих Web- и совместных возможностей.

## Организация CLI через Commander

Базовые пакеты предоставляют структурированные TypeScript API. Пресеты превращают общие возможности в нативные объекты Commander `Command`. Корневой программой всегда владеет бизнес-приложение:

```ts
import { Command } from "commander";

const program = new Command("my-cli");

program.addCommand(presetCommand);
program.addCommand(applicationCommand);

await program.parseAsync();
```

* **Пресет команды** задаёт стандартные аргументы, справку и текстовый или JSON-вывод.
* **Команда приложения** сочетает Runtime[^live-runtime], бизнес-цели, личность, политику фиксации или файлов.
* Оба варианта — обычные Commander `Command`, их можно смешивать в одной корневой программе.

Каждая следующая тема сначала описывает базовую возможность, затем подключение к Commander.

## Постепенное добавление возможностей

Руководство начинает с основных операций Unit, затем добавляет файлы, визуальную проверку, совместную работу и процессы:

```text
загрузка и редактирование Unit
→ импорт и экспорт файлов Office
→ визуальная проверка
→ изолированное редактирование и проверка Worktree
→ повторное использование Runtime и Daemon
```

### 1. Загрузка и редактирование Unit

Создайте минимальный цикл AI Agent: загрузите Unit через Collaboration Runtime, изучите через Inspection, выполните код Univer Facade и при необходимости найдите API Facade.

### 2. Подключение границы файлов Office

Используйте Exchange для преобразования между файлами Office и UnitData. Импортированные Units остаются в Collaboration Server; экспорт сначала получает актуальные UnitData через Collaboration Runtime.

### 3. Визуальная проверка

Структурированный вывод не описывает макет полностью. Screenshot даёт AI Agent отрисованные изображения, а Layout Lint — структурированную диагностику расположения.

### 4. Изоляция изменений через Worktree

AI Agent может несколько раз редактировать и проверять черновик Worktree. Когда он готов, человек проверяет его в Web и выбирает Merge или Reopen.

### 5. Повторное использование дорогих сред

Начните с краткоживущих Runtime. Добавляйте пул, workers или daemon только когда важны стоимость запуска, параллелизм или повторное использование между процессами CLI.

## Рекомендуемый порядок чтения

1. [Загрузка документов и операции с содержимым](https://docs.univer.ai/ru-RU/ai/content-operations.md)
2. [Импорт и экспорт Office](https://docs.univer.ai/ru-RU/server/import-export/node.md)
3. [Визуальная проверка](https://docs.univer.ai/ru-RU/ai/visual-inspection.md)
4. [Worktree: редактирование AI Agent и проверка человеком](https://docs.univer.ai/ru-RU/ai/worktree.md)
5. [Повторное использование Runtime и Daemon](https://docs.univer.ai/ru-RU/ai/runtime-architecture.md)
6. [Каталог пакетов](https://docs.univer.ai/ru-RU/ai/packages.md)
7. [Примеры](https://docs.univer.ai/ru-RU/ai/examples.md)

[^document-unit]: Unit — экземпляр документа, например рабочая книга или текстовый документ. Лист является частью книги, а не отдельной Unit.

[^live-runtime]: Здесь Runtime — работающий экземпляр Univer и ресурсы для операций с загруженной Unit, а не исполняемый файл Node.js или сохранённый снимок документа.