DeepSeek Harness Worktrees: Guía de Primer Uso
DeepSeek-V4 Team · 14 de octubre de 2026 · 7 min read
Un checkout separado es útil cuando desea que un agente intente un cambio sin mover los archivos que ya está editando. DeepSeek Harness dsh-v0.2.1-alpha.2, lanzado el 9 de octubre de 2026, añade un complemento experimental de Git Worktrees para esa tarea. Crea una rama y un checkout, luego cambia el directorio de trabajo de la sesión que llama.
Este tutorial usa la guía de complementos con versión fijada para definir un pequeño ejercicio de aceptación: crear un worktree, hacer un cambio de documentación, inspeccionarlo y regresar. Es un flujo de trabajo basado en documentación, no una afirmación de que probamos la aplicación de escritorio Harness. Los ejemplos de herramientas con forma de código describen llamadas de agente; no son comandos para pegar en su shell.
Verifique el repositorio antes de habilitar el complemento
Use un repositorio desechable o un proyecto donde entienda los cambios actuales. Los requisitos de runtime de worktree especifican Git 2.45 o más nuevo y Node en el entorno de ejecución utilizado por el proveedor del sistema de archivos. Con un entorno remoto, las versiones de su portátil no bastan para comprobar ese requisito.
Comience pidiendo la raíz del repositorio, la rama actual, el commit actual y el estado corto de Git. Estos comandos de shell de solo lectura proporcionan las verificaciones subyacentes:
git --version
node --version
git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status --shortUn nombre de rama vacío puede significar un HEAD desvinculado; registre eso en lugar de inventar una rama. Un estado no vacío no es automáticamente un fallo, pero significa que existe algún trabajo fuera de el estado de referencia confirmado en Git. Decida si la nueva tarea necesita esos cambios. Si es así, prepare un commit apropiado primero en lugar de asumir que el worktree los copiará.
El complemento no copia archivos preparados, no preparados, no rastreados o ignorados. Las dependencias, los archivos de entorno local y la salida generada pueden estar ausentes incluso cuando el checkout de origen se ejecuta correctamente.
El diagrama representa el límite de copia documentado, no una captura de pantalla de la aplicación. Ambos checkouts usan administración de Git compartida; los archivos separados no hacen que sus historiales sean independientes.
Habilite Git Worktrees y elija una tarea pequeña
Abra Plugins → Official → Git Worktrees y active el interruptor. Según la guía de complementos fijada, el paquete opcional está desactivado en cada perfil incluido. Carga el runtime de worktree y la herramienta de creación juntos.
Para la primera tarea, use una solicitud de alcance limitado: cree un worktree para una corrección de documentación, muestre su directorio y línea base, y espere antes de editar. Pida un nombre de rama nuevo y no usado como docs-worktree-trial. El mismo nombre se usa para el directorio de checkout relativo, por lo que un nombre descriptivo corto facilita la inspección posterior.
La llamada de creación tiene esta forma:
create_worktree({ name: "docs-worktree-trial", from: "HEAD" })from debe resolverse localmente. Un nombre de rama remoto visible en un sitio web de alojamiento no es suficiente si sus objetos no están disponibles en este repositorio. La operación no descarga objetos faltantes, no inicializa submódulos ni instala paquetes. Resuelva esos prerrequisitos deliberadamente antes de reintentar una creación fallida.
Verifique el directorio devuelto antes de hacer cambios
Una llamada exitosa devuelve path, branch, baseCommit y repositoryRoot. Mantenga esos cuatro valores juntos. La referencia del subsistema especifica que la configuración de Git se completa antes de que la sesión cambie de directorio.
El destino predeterminado está debajo del checkout actual en .agents/worktrees/<name>. Si la sesión comienza en un checkout vinculado, ese checkout es la raíz de origen para el nuevo pool. No sustituya una ruta recordada de otra sesión por la ruta canónica devuelta.
| Campo devuelto | Qué verificar |
|---|---|
path |
La sesión está ahora en este checkout |
branch |
Es la nueva rama que solicitó |
baseCommit |
Es la revisión de inicio local prevista |
repositoryRoot |
Identifica el checkout desde el que comenzó |
Pida al agente que ejecute las verificaciones de raíz, rama y commit nuevamente desde su directorio actual. Compárelas con el resultado de creación. Los repositorios ordinarios deberían tener el contenido de inicio previsto, pero el runtime señala que las referencias de reemplazo locales del repositorio pueden afectar el contenido extraído; un identificador de commit por sí solo no es un sustituto para inspeccionar los archivos que planea cambiar.
Haga una edición e inspeccione el diff
Elija un párrafo existente del README y pida una aclaración factual. Evite comenzar con actualizaciones de dependencias o un formateador de todo el repositorio: esos producen diffs grandes que hacen que los errores de directorio sean más difíciles de detectar.
Después de la edición, inspeccione la rama actual y los cambios:
git branch --show-current
git status --short
git diff --check
git diff -- README.mdUse su nombre de archivo real si la tarea cambia un archivo diferente. El último comando muestra cambios no preparados; si el agente preparó la edición, inspeccione también el diff preparado. Un git diff --check limpio solo verifica errores de espacio en blanco. No establece que el párrafo sea correcto o que el proyecto se compile.
Ejecute la verificación de proyecto más pequeña relevante cuando el cambio necesite una. Registre el comando, el directorio y el resultado. Para un cambio solo de documentación, leer el texto renderizado puede ser más útil que ejecutar una suite de pruebas no relacionada.
La ruta numerada sigue el ejercicio: crear, verificar, editar, inspeccionar, salir. La rama y el directorio retenidos aún necesitan una decisión posterior sobre integración o limpieza.
Salga deliberadamente y conserve el contexto de revisión
Para regresar, pida al agente que llame a working_directory con la ruta de checkout absoluta original. Por ejemplo, reemplazando la ruta de muestra con su repositoryRoot registrado:
working_directory({ cd: "/absolute/path/to/original-checkout" })Verifique el directorio actual nuevamente. Salir no fusiona el cambio, no elimina el checkout ni borra su rama. Deshabilitar el complemento de Git Worktrees también deja los worktrees existentes en su lugar, mientras que la herramienta integrada working-directory permanece disponible.
Revise el diff antes de decidir cómo integrarlo. Haga commit y fusione o cherry-pick según su flujo de trabajo normal del repositorio. Cuando el checkout ya no sea necesario, inspeccione su estado y use el proceso normal de eliminación de worktree de Git después de preservar cualquier cambio. Evite la eliminación forzada como respuesta predeterminada a un checkout con cambios sin confirmar.
Diagnostique fallos sin crear ramas repetidamente
Una rama o ruta de checkout existente causa un error. Inspeccione lo que ya existe antes de probar otro nombre, especialmente después de una cancelación: los fallos de configuración pueden dejar artefactos parciales e informar su ubicación. Generar nombres repetidamente puede ocultar qué checkout contiene el trabajo que pretendía mantener.
Un error de permiso es diferente. La creación necesita que la política de sandbox existente permita escrituras en el destino y metadatos de Git compartidos. El complemento no amplía esos permisos. Identifique la ubicación denegada antes de cambiar la configuración.
Finalmente, los punteros Git LFS almacenados o los blobs cifrados pueden permanecer sin expandir porque el checkout omite los filtros clean, smudge y process configurados. Trate la descarga de los archivos reales o el descifrado como una operación separada. Un checkout puede ser válido mientras aún carece del entorno ejecutable que su tarea necesita.
Mantenga el registro devuelto de cuatro campos con el diff revisado y el resultado de la verificación. Eso es suficiente contexto para reanudar el ejercicio sin adivinar qué directorio o línea base usó el agente. Para los cambios más amplios de lanzamiento y SDK, consulte la guía de actualización alpha.2.