# Worktree

> Узнайте об изоляции, базовой ревизии, OT-объединении и работе AI SDK с агентами и рецензентами.

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.3.0`

- Source: [features/shared/worktree.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/worktree.ru-RU.mdx)

---

Worktree изолирует совместно редактируемый черновик Office-контента. Агент меняет бюджет, данные или документ, пока люди продолжают работу с основным документом (trunk). Изменения объединяют после проверки и рецензирования.

Это изоляция содержимого и изменений, а не каталог Git. Задача может включать несколько [Unit](https://docs.univer.ai/ru-RU/guides/sheets/getting-started/quickstart.md#unit), например книгу, документ и презентацию.

## Изоляция: развитие от общей базы

При создании Worktree для существующего Unit сервер фиксирует текущую revision trunk как **baseline**. Черновик получает отдельные Snapshot, changeset, revision, Presence и Room. Промежуточные правки не попадают в trunk.

```mermaid
flowchart LR
    A["Trunk при создании<br/>Baseline"]
    B["Trunk развивается"]
    C["Черновик Worktree"]
    D["Ready · Проверка"]
    E["OT-объединение"]
    F["Новая версия trunk"]
    A --> B
    A --> C --> D
    B --> E
    D --> E --> F
```

| Понятие | Роль |
| --- | --- |
| Baseline | Исходная ревизия trunk для сравнения и объединения. |
| Draft head | Последняя подтверждённая ревизия черновика. |
| Ready head | Зафиксированная ревизия, определяющая объём проверки и объединения. |

Trunk и черновик развиваются отдельно. Номера описывают разные последовательности и сами по себе не определяют актуальность контента. Синхронизация черновика не добавляет новые правки trunk автоматически; они согласуются при предпросмотре или объединении.

## Как AI SDK подключает тот же черновик

Collaboration Runtime AI SDK работает со снимками, изменениями и ревизиями одного Unit. Сервис Worktree в Server SDK управляет созданием, состояниями и объединением. Другой движок редактирования не нужен.

Приложение преобразует `worktreeID + unitID` в адреса Snapshot, Submit, WebSocket и Session Ticket черновика и передаёт Runtime. Одни инструменты могут работать с trunk или черновиком.

```mermaid
flowchart LR
    A["Агент / бизнес-CLI"]
    B["Проверка в Web"]
    C["Адаптер цели приложения"]
    D["Worktree Endpoint"]
    E["Тот же черновой Unit"]
    A --> C
    B --> C
    C --> D --> E
```

Unit ID может существовать в trunk и нескольких Worktree. Проверки, выполнение, скриншоты и Web-просмотр должны использовать одну цель, чтобы не прочитать черновик и записать в trunk. Web подключается с соответствующей конфигурацией совместной работы.

| Компонент | Задача |
| --- | --- |
| Web SDK | Общий движок для Headless и браузерного редактора. |
| Server SDK | Изоляция, хранение изменений и ревизий, состояния, OT. |
| AI SDK | Runtime, Inspection, поиск API, выполнение Facade, визуальные проверки. |
| Приложение | Модель, цели, идентификация, права, задачи и UI рецензирования. |

## От работы агента к передаче результата

Приложение может организовать параллельные задачи, выделив каждому агенту отдельный Worktree. Агенты редактируют, проверяют и отмечают черновики Ready. Человек проверяет их по отдельности, выполняет Reopen нужного черновика для доработки и объединяет одобренные правки с актуальным trunk.

```mermaid
flowchart TB
    TRUNK["Основной документ · Trunk"]
    subgraph PARALLEL["Параллельная работа агентов"]
        direction LR
        AGENT_A["Agent A<br/>Worktree A<br/>Изменить и проверить"]
        AGENT_B["Agent B<br/>Worktree B<br/>Изменить и проверить"]
        AGENT_C["Agent C<br/>Worktree C<br/>Изменить и проверить"]
    end
    REVIEW["Проверка человеком<br/>Черновик<br/>Предпросмотр"]
    MERGE["Merge по отдельности<br/>С актуальным trunk"]
    RESULT["Новая версия trunk"]
    TRUNK --> AGENT_A
    AGENT_A -->|"Ready"| REVIEW
    TRUNK --> AGENT_B
    AGENT_B -->|"Ready"| REVIEW
    TRUNK --> AGENT_C
    AGENT_C -->|"Ready"| REVIEW
    REVIEW -->|"Одобрить"| MERGE
    REVIEW -.->|"Reopen нужного черновика"| PARALLEL
    MERGE --> RESULT
```

1. Создайте черновик, выберите Unit задачи, подключите Worktree target и выполните `pull`.
2. Изучите структуру и данные через Inspection, уточните API и измените через Facade.
3. Отправьте правки в черновик, перечитайте данные и расчёты. При необходимости сделайте скриншоты, для Slides — Layout Lint. Исправьте найденное и повторите.
4. Установите Ready: зафиксируйте ревизии и остановите редактирование для проверки.
5. После одобрения выполните Merge. Перед новыми правками человека или агента нужен Reopen; ненужный черновик можно отбросить через Discard.

| Операция | Результат |
| --- | --- |
| `runtime.commit()` | Отправка только в черновик с продвижением его revision. |
| `markReady()` | Фиксация версии для проверки, без объединения. |
| `reopenWorktree()` | Возврат Ready в Draft с разрешением правок. |
| `mergeWorktree()` | Объединение зафиксированных изменений по Unit. |

Commit, Ready и Merge различаются. И человек, и агент должны выполнить Reopen перед редактированием Ready. См. [руководство AI SDK](https://docs.univer.ai/ru-RU/ai/worktree.md).

## Объединение с актуальным trunk

Для Unit из trunk сервер читает changeset **от baseline до Ready head**, собирает mutation и отправляет их в основной Collaboration Service. Если trunk продвинулся, [OT](https://docs.univer.ai/ru-RU/overview/features/shared/collaboration.md) преобразует правки относительно последующих изменений и подтверждает новую ревизию.

Применяются изменения, а не полная замена документа старым снимком. Невозможность преобразования или применения возвращает конфликт для обработки приложением. OT не решает все бизнес-разногласия.

Новый Unit черновика не имеет baseline в trunk. При объединении он создаётся там без копирования всей черновой истории changeset.

## Проверка изменений и результата объединения

- **Что изменилось?** Сравните полные baseline и Ready через [Compare](https://docs.univer.ai/ru-RU/overview/features/shared/compare.md).
- **Что получится сейчас?** После Ready вызовите `evaluateUnitMerge()`. Если trunk продвинулся, изолированный Runtime применяет OT-кандидат к актуальному trunk и формирует предпросмотр только для чтения. Ничего не сохраняется и changeset не отправляется.

Предпросмотр относится к моменту запроса; Merge использует состояние во время выполнения. Несколько Unit не образуют одну атомарную транзакцию: успехи сохраняются при ошибке другого Unit. Показывайте результаты и обрабатывайте ошибки отдельно.

## Подключение и охват

Подключите Worktree Client, Service, Endpoint и адаптеры к ядру совместной работы. Храните черновики отдельно, разделяя Session Ticket Store с trunk. Доступ к черновику и запись в trunk авторизуются отдельно: изоляция не выдаёт прав.

Поддерживаются Sheet, Doc, Slide, Canvases и Relational Table, не PDF. См. [пример](https://docs.univer.ai/ru-RU/server/collaboration/examples.md#worktree), [модули](https://docs.univer.ai/ru-RU/server/collaboration/packages.md#worktree) и [руководство агента](https://docs.univer.ai/ru-RU/ai/worktree.md).

[Ко всем возможностям](https://docs.univer.ai/ru-RU/overview/features.md)