Worktree
Entiende el aislamiento, las revisiones base, la fusión OT y la conexión de AI SDK con agentes y revisión humana.
Worktree proporciona borradores aislados de contenido de Office que las personas y los agentes todavía pueden editar juntos. Un agente puede revisar un presupuesto, reorganizar datos, o reescribir un breve mientras la gente continúa editando el documento principal, que se llama el tronco. El borrador es validado y revisado antes de que sus cambios lleguen al tronco.
El aislamiento se aplica al contenido de documentos y sus cambios, no a un directorio de trabajo de Git. Una sola tarea puede abarcar varios Unidades, por ejemplo un libro de trabajo, un documento y una presentación.
Aislamiento: evolucionar desde una base común
Cuando se crea un Worktree para una unidad existente, el servicio registra que la revisión del tronco actual de la unidad como el Base de referencia. El borrador comienza desde esa revisión y tiene sus propias instantáneas, cambios, revisiones, presencia y colaboración Habitaciones. Editas hechas en el borrador no afectan al tronco.
| Concepto | Función |
|---|---|
| Baseline | La versión del maletero desde la que comenzó el borrador, se utiliza para la comparación y fusión. |
| Draft head | El nuevo proyecto de revisión confirmado, los proyectos de presentación lo impulsan. |
| Ready head | El proyecto de revisión congelado que define lo que se revisa y fusiona. |
El tronco y el proyecto de avance independientemente. Revisiones en cada lado forman una secuencia de presentación separada, por lo que un número mayor no indica qué contenido es más nuevo. Tirar un borrador sincroniza los propios cambios del borrador. Nuevas ediciones del tronco no entran en la versión bajo revisión por su cuenta; la vista previa de fusión y la fusión se reconcilian los dos.
Cómo AI SDK conecta el mismo borrador
AI SDK's Collaboration Runtime gestiona las instantáneas, los cambios y las revisiones de una unidad. En el lado Server SDK, el servicio Worktree posee creación, ciclo de vida y fusión. La Runtime no requiere un segundo motor de edición para trabajar con Worktrees.
La aplicación resuelve worktreeID + unitID en la instantánea del borrador, enviar, WebSocket y Session Ticket URLs, luego los pasa al Runtime. Las mismas herramientas de inspección y edición pueden entonces apuntar el tronco o un borrador.
Un ID de unidad puede existir en el maletero y en varios Worktrees a la vez. El objetivo debe incluir el Worktree en el que vive, e inspección, ejecución, capturas de pantalla y la vista previa web debe utilizar ese mismo objetivo. De lo contrario una herramienta puede leer de un borrador y escribir al tronco. El cliente Web carga el mismo borrador con la configuración de colaboración que lo concuerda.
| Componente | Responsabilidad |
|---|---|
| Web SDK | El motor de contenido compartido, para operaciones de agente sin cabeza y para la edición en el navegador. |
| Server SDK | Aislamiento, persistencia de cambios y revisiones, estado y OT. |
| AI SDK | El tiempo de ejecución composible, inspección, revisión de API, ejecución de Facade y controles visuales. |
| Tu aplicación | Selección de modelos, mapeo de objetivos, identidad, autorización, tareas, y la revisión UI. |
De la edición del agente a la entrega
La aplicación puede ejecutar tareas paralelamente dando a cada agente su propio Worktree. Cada agente edita su borrador, comprueba el resultado y lo marca Listo. Una persona entonces revisa los borradores uno a la vez, vuelve a abrir el borrador que necesita más trabajo, y fusiona los borradores aceptados en el tronco actual.
- Cree el Worktree y carguelo. Seleccione las Unidades que cubre la tarea, conecte el objetivo Worktree, y tire de su último contenido.
- Inspeccione la estructura con la Inspección, busque APIs según sea necesario, y haga cambios a través de Facades.
- Presentar al borrador, leer los datos y los resultados del cálculo, y capturar capturas de pantalla cuando sea necesario. Las diapositivas también pueden ejecutar Layout Lint. Si los cheques reportan un problema, edita el borrador de nuevo.
- Marca Listo. Esto congela el proyecto de revisión de cada Unidad, y la edición se detiene hasta que la revisión esté completa.
- Reabrir un borrador de nuevo a Borrador antes de que una persona o un agente vuelva a editar. Descartar los borradores que no son necesarios.
| Operación | Efecto |
|---|---|
runtime.commit() | Sólo se presenta al proyecto y se avanza el proyecto de revisión. |
markReady() | Congela la versión de revisión sin fusionar nada en el maletero. |
reopenWorktree() | Toma un borrador de List back to Draft, por lo que la edición puede continuar. |
mergeWorktree() | Mete el borrador congelado cambios en el tronco, Unidad por Unidad. |
Commitir, Listo y Combinado son tres operaciones separadas. Una vez que un borrador está listo, ni una persona ni un agente puede editarlo hasta que haya sido reabierto. Para la relación entre el Runtime y el CLI, vea el Flujo de trabajo AI SDK.
Fusionar cambios con el trunk actual
Para una Unidad que viene del tronco, el servicio lee los borradores de los cambios de la Base de referencia para la cabeza lista, recoge sus mutaciones, y los presenta a través del Servicio de Colaboración del tronco. Si el tronco ha avanzado desde la base, OT transforma esas mutaciones contra las ediciones posteriores del tronco antes de que el servicio confirme una nueva revisión.
Por lo tanto, la fusión se aplica a las ediciones; no reemplaza el último documento con una fotografía antigua. Los cambios simultáneos que se pueden transformar se concilian. Los cambios que no pueden ser transformados, o que ya no se aplican, se devuelven como conflictos para la aplicación a manejar. OT no resuelve cada desacuerdo comercial.
Una unidad creada dentro de un Worktree no tiene base de referencia para fusionarse. Merging lo crea en el maletero sin copiar el borrador completo de historia de cambios.
Revisar cambios y resultado de fusión
- Para ver qué cambió, compare el estado de referencia completo con el estado de borrador Listo utilizando Compare.
- Para ver lo que la fusión haría en un momento dado, llame a
evaluateUnitMerge()después de List. Cuando el tronco ha avanzado, un tiempo de ejecución aislado aplica un candidato OT-transformed al tronco actual y produce una vista previa de sólo lectura. No presenta ningún cambio y no modifica ni el tronco ni el borrador.
Una vista previa describe el estado en el momento en que se solicita. El tronco puede cambiar después, y el Merge real funciona del estado que encuentra cuando se ejecuta. La fusión de varias Unidades no es una transacción atómica tampoco, así que si una Unidad falla, las Unidades que ya se fusionaron permanecen fusionadas. Muestra el resultado para cada Unidad y manejar fallos individualmente.
Integración y alcance
Combine los adaptadores Worktree Client, Service, Endpoint y base de datos con el núcleo de colaboración. Mantenga el borrador de almacenamiento separado, y comparta una tienda de entradas de sesión con el maletero. La aplicación autoriza el proyecto de acceso y el maletero escribe por separado; el aislamiento no otorga acceso por sí mismo.
Hoja, Doc, Slide, Canvases y Tabla Relacional son compatibles. PDF no está incluido. El ejemplo, el módulos de extensión y el guía de integración de agentes proporcionan puntos de partida.
¿Cómo es esta guía?