Worktree
Узнайте об изоляции, базовой ревизии, OT-объединении и работе AI SDK с агентами и рецензентами.
Worktree изолирует совместно редактируемый черновик Office-контента. Агент меняет бюджет, данные или документ, пока люди продолжают работу с основным документом (trunk). Изменения объединяют после проверки и рецензирования.
Это изоляция содержимого и изменений, а не каталог Git. Задача может включать несколько Unit, например книгу, документ и презентацию.
Изоляция: развитие от общей базы
При создании Worktree для существующего Unit сервер фиксирует текущую revision trunk как baseline. Черновик получает отдельные Snapshot, changeset, revision, Presence и Room. Промежуточные правки не попадают в trunk.
| Понятие | Роль |
|---|---|
| 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 или черновиком.
Unit ID может существовать в trunk и нескольких Worktree. Проверки, выполнение, скриншоты и Web-просмотр должны использовать одну цель, чтобы не прочитать черновик и записать в trunk. Web подключается с соответствующей конфигурацией совместной работы.
| Компонент | Задача |
|---|---|
| Web SDK | Общий движок для Headless и браузерного редактора. |
| Server SDK | Изоляция, хранение изменений и ревизий, состояния, OT. |
| AI SDK | Runtime, Inspection, поиск API, выполнение Facade, визуальные проверки. |
| Приложение | Модель, цели, идентификация, права, задачи и UI рецензирования. |
От работы агента к передаче результата
Приложение может организовать параллельные задачи, выделив каждому агенту отдельный Worktree. Агенты редактируют, проверяют и отмечают черновики Ready. Человек проверяет их по отдельности, выполняет Reopen нужного черновика для доработки и объединяет одобренные правки с актуальным trunk.
- Создайте черновик, выберите Unit задачи, подключите Worktree target и выполните
pull. - Изучите структуру и данные через Inspection, уточните API и измените через Facade.
- Отправьте правки в черновик, перечитайте данные и расчёты. При необходимости сделайте скриншоты, для Slides — Layout Lint. Исправьте найденное и повторите.
- Установите Ready: зафиксируйте ревизии и остановите редактирование для проверки.
- После одобрения выполните Merge. Перед новыми правками человека или агента нужен Reopen; ненужный черновик можно отбросить через Discard.
| Операция | Результат |
|---|---|
runtime.commit() | Отправка только в черновик с продвижением его revision. |
markReady() | Фиксация версии для проверки, без объединения. |
reopenWorktree() | Возврат Ready в Draft с разрешением правок. |
mergeWorktree() | Объединение зафиксированных изменений по Unit. |
Commit, Ready и Merge различаются. И человек, и агент должны выполнить Reopen перед редактированием Ready. См. руководство AI SDK.
Объединение с актуальным trunk
Для Unit из trunk сервер читает changeset от baseline до Ready head, собирает mutation и отправляет их в основной Collaboration Service. Если trunk продвинулся, OT преобразует правки относительно последующих изменений и подтверждает новую ревизию.
Применяются изменения, а не полная замена документа старым снимком. Невозможность преобразования или применения возвращает конфликт для обработки приложением. OT не решает все бизнес-разногласия.
Новый Unit черновика не имеет baseline в trunk. При объединении он создаётся там без копирования всей черновой истории changeset.
Проверка изменений и результата объединения
- Что изменилось? Сравните полные baseline и Ready через Compare.
- Что получится сейчас? После 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. См. пример, модули и руководство агента.
Насколько полезно это руководство?