# Worktree

> Entiende el aislamiento, las revisiones base, la fusión OT y la conexión de AI SDK con agentes y revisión humana.

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

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

- Requested language: `es-ES`

- Content language: `es-ES`

- Documentation version: `1.3.0`

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

---

Worktree ofrece borradores aislados y colaborativos del contenido Office. Un agente puede revisar presupuestos, datos o documentos mientras otras personas editan el documento principal (trunk). Los cambios se fusionan tras validación y revisión.

Aísla contenido y cambios, no directorios Git. Una tarea puede incluir varias [Units](https://docs.univer.ai/es-ES/guides/sheets/getting-started/quickstart.md#unit), por ejemplo un libro, un documento y una presentación.

## Aislamiento: evolucionar desde una base común

Al crear un Worktree para una Unit existente, el servidor registra su revisión actual de trunk como **baseline**. El borrador usa snapshots, changesets, revisiones, Presence y Rooms independientes. Las ediciones intermedias no llegan a trunk.

```mermaid
flowchart LR
    A["Trunk al crear<br/>Baseline"]
    B["Trunk sigue editándose"]
    C["Borrador Worktree"]
    D["Ready · Revisión"]
    E["Fusión OT"]
    F["Nueva revisión trunk"]
    A --> B
    A --> C --> D
    B --> E
    D --> E --> F
```

| Concepto | Función |
| --- | --- |
| Baseline | Revisión de origen en trunk, referencia para comparar y fusionar. |
| Draft head | Última revisión confirmada del borrador. |
| Ready head | Revisión fijada que delimita revisión y fusión. |

Trunk y borrador avanzan por separado. Sus números representan secuencias distintas, no una comparación directa de actualidad. Sincronizar el borrador no incorpora automáticamente cambios nuevos de trunk; se reconcilian en la vista previa o la fusión.

## Cómo AI SDK conecta el mismo borrador

Collaboration Runtime de AI SDK gestiona snapshots, cambios y revisiones de una Unit. El servicio Worktree de Server SDK controla creación, estado y fusión; no se necesita otro motor de edición.

La aplicación convierte `worktreeID + unitID` en URLs de snapshot, envío, WebSocket y Session Ticket del borrador y las entrega al Runtime. Así reutiliza herramientas entre trunk y borradores.

```mermaid
flowchart LR
    A["Agente / CLI propia"]
    B["Revisión humana Web"]
    C["Adaptador de destino"]
    D["Worktree Endpoint"]
    E["Misma Unit borrador"]
    A --> C
    B --> C
    C --> D --> E
```

Una Unit ID puede existir en trunk y varios Worktrees. Inspección, ejecución, capturas y vista Web deben usar el mismo destino para evitar leer el borrador y escribir en trunk. Web utiliza la configuración colaborativa correspondiente.

| Componente | Responsabilidad |
| --- | --- |
| Web SDK | Motor común para operaciones Headless y edición en navegador. |
| Server SDK | Aislamiento, persistencia de cambios y revisiones, estado y OT. |
| AI SDK | Runtime, Inspection, consulta API, ejecución Facade y validación visual. |
| Tu aplicación | Modelo, destinos, identidad, autorización, tareas e interfaz de revisión. |

## De la edición del agente a la entrega

La aplicación puede organizar tareas paralelas con un Worktree independiente por agente. Cada agente edita, valida y marca su borrador Ready. Una persona revisa cada uno, usa Reopen si necesita cambios y fusiona lo aprobado con el trunk actual.

```mermaid
flowchart TB
    TRUNK["Documento principal · Trunk"]
    subgraph PARALLEL["Agentes en paralelo"]
        direction LR
        AGENT_A["Agent A<br/>Worktree A<br/>Editar y validar"]
        AGENT_B["Agent B<br/>Worktree B<br/>Editar y validar"]
        AGENT_C["Agent C<br/>Worktree C<br/>Editar y validar"]
    end
    REVIEW["Revisión humana<br/>Borrador y vista previa"]
    MERGE["Merge individual<br/>Con el trunk actual"]
    RESULT["Nueva revisión trunk"]
    TRUNK --> AGENT_A
    AGENT_A -->|"Ready"| REVIEW
    TRUNK --> AGENT_B
    AGENT_B -->|"Ready"| REVIEW
    TRUNK --> AGENT_C
    AGENT_C -->|"Ready"| REVIEW
    REVIEW -->|"Aprobar"| MERGE
    REVIEW -.->|"Reopen del borrador correspondiente"| PARALLEL
    MERGE --> RESULT
```

1. Crea el borrador, elige Units, conecta el destino Worktree y ejecuta `pull`.
2. Inspecciona estructura y datos, consulta APIs si hace falta y edita con Facade.
3. Envía al borrador y relee datos y cálculos. Añade capturas cuando proceda y Layout Lint para Slides. Repite si aparecen problemas.
4. Marca Ready: fija las revisiones y detiene la edición para revisión humana.
5. Fusiona lo aprobado; usa Reopen antes de nuevas ediciones humanas o del agente, o Discard para abandonar.

| Operación | Efecto |
| --- | --- |
| `runtime.commit()` | Envía solo al borrador y avanza su revisión. |
| `markReady()` | Fija la versión revisable sin fusionar. |
| `reopenWorktree()` | Vuelve de Ready a Draft y permite editar. |
| `mergeWorktree()` | Fusiona cambios fijados por Unit. |

Commit, Ready y Merge son distintos. Tanto personas como agentes deben reabrir un borrador Ready antes de editar. Véase la [guía AI SDK](https://docs.univer.ai/es-ES/ai/worktree.md).

## Fusionar cambios con el trunk actual

Para una Unit procedente de trunk, el servidor lee changesets entre **baseline y Ready head**, reúne sus mutations y los envía al Collaboration Service principal. Si trunk avanzó, [OT](https://docs.univer.ai/es-ES/overview/features/shared/collaboration.md) transforma los cambios frente a las ediciones posteriores y confirma una revisión nueva.

Se aplican cambios, no se reemplaza el documento actual con un snapshot antiguo. Si no pueden transformarse o aplicarse, se devuelve un conflicto. La aplicación lo gestiona: OT no resuelve todos los desacuerdos de negocio.

Una Unit nueva del borrador no tiene baseline en trunk. La fusión la crea allí sin copiar todo el historial de changesets del borrador.

## Revisar cambios y resultado de fusión

- **¿Qué cambió?** Compara los estados completos baseline y Ready con [Compare](https://docs.univer.ai/es-ES/overview/features/shared/compare.md).
- **¿Qué pasaría al fusionar ahora?** Tras Ready, llama a `evaluateUnitMerge()`. Si trunk avanzó, un Runtime aislado aplica el candidato transformado por OT al trunk actual y genera una vista de solo lectura. No envía changesets ni modifica ninguno de los lados.

La vista previa refleja el instante de la petición; Merge usa el estado al ejecutarse. Una fusión multi-Unit no es atómica: las Units correctas permanecen fusionadas si otra falla. Presenta resultados individuales y gestiona los errores.

## Integración y alcance

Combina Worktree Client, Service, Endpoint y adaptadores con el núcleo colaborativo. Separa el almacenamiento y comparte Session Ticket Store con trunk. Autoriza por separado acceso al borrador y escritura en trunk; el aislamiento no concede permisos.

Admite Sheet, Doc, Slide, Canvases y Relational Table, no PDF. Consulta el [ejemplo](https://docs.univer.ai/es-ES/server/collaboration/examples.md#worktree), los [módulos](https://docs.univer.ai/es-ES/server/collaboration/packages.md#worktree) y la [integración del agente](https://docs.univer.ai/es-ES/ai/worktree.md).

[Volver a todas las funciones](https://docs.univer.ai/es-ES/overview/features.md)