# dsh-bash-terminal-ts > 🌐 [简体中文](README.md) | [English](README.en.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Italiano](README.it.md) | [Русский](README.ru.md) | [Español](README.es.md) | [Português](README.pt.md) · Comunidad: [LINUX DO](https://linux.do) · [GitHub](https://github.com/drscrewdriver/dsh-bash-terminal-ts) ![test](https://github.com/drscrewdriver/dsh-bash-terminal-ts/actions/workflows/test.yml/badge.svg) Plugin de DSH (DeepSeek Harness): una herramienta `shell` que ejecuta de forma unificada en Windows los comandos de **cuatro** terminales — **PowerShell / Git Bash / MSYS2 / WSL**. > **Este repositorio es la reescritura en TypeScript de `MAXeaglet/dsh-bash-terminal`**, con soporte MSYS2/MINGW64 funcional. Las líneas de compatibilidad se cortan por segmento de versión del host DSH; todas las líneas comparten el nombre de paquete `dsh-bash-terminal-ts` y se distinguen mediante dist-tags de npm: > > | Segmento DSH | Rama | Versión del plugin | dist-tag npm | > |--------|------|----------|--------------| > | `>=0.1.0-rc.2 <0.3.0-0` (rango acotado) | `main` (esta rama, troncal entre versiones) | 0.8.x | `latest` | > | `>=0.2.0-rc.1 <0.2.1-0` | `compat/0.2.0` (histórica, congelada) | 0.7.x | `dsh-0.2.0` | > | 0.1.7-rc.1 – 0.1.7.x | `compat/0.1.7` | 0.6.x | `dsh-0.1.7` | > | 0.1.5-alpha.1 – 0.1.5-rc.x | `ts/0.1.5` (histórica, congelada) | ≤ 0.5.2 | `dsh-0.1.5` | > | 0.1.2-alpha.1 – 0.1.2-rc.x | commits iniciales de `main` (congelados por tag) | ≤ 0.4.2 | `dsh-0.1.2` | > > Elige la línea que cubra tu versión de DSH; las series de versiones nunca se solapan, por lo que una instalación con `^` no puede resolverse entre líneas. | Backend | Ejecución real | Sintaxis / rutas | Variables de entorno | |------|----------|-------------|----------| | `powershell` (predeterminado) | `pwsh -NoLogo -NoProfile -NonInteractive -Command ` | PowerShell; `C:\...` | `$env:NAME` | | `gitbash` | `bash -lc ` de Git for Windows | POSIX; `/d/workspace`; PATH con `/usr/bin` y `/mingw64/bin` | `$NAME` | | `msys2` | `bash -lc ` de MSYS2 (`C:\msys64\usr\bin\bash.exe`) | POSIX; `/c/...`; PATH con `/usr/bin` y `/mingw64/bin` (gcc / make) | `$NAME` (inyección automática de `MSYSTEM=MINGW64`) | | `wsl` | `wsl [-d ] -e bash -lc ` | Linux; `/mnt/d/...` | `$NAME` (vía WSLENV) | Cada llamada arranca una shell totalmente nueva: **no se conserva estado alguno** (cwd / variables / alias) — pasa `workdir` en lugar de usar `cd`. ## Vista previa de la interfaz La fila «Terminal predeterminado» en Ajustes → General: el usuario elige entre PowerShell / Git Bash / MSYS2 / WSL, y la herramienta `shell` ejecuta solo conforme a ese ajuste, sin que el modelo pueda saltárselo: ![Fila del ajuste del terminal predeterminado](assets/shells.png) ## Puntos de diseño - **El terminal lo decide el usuario, la IA no puede cambiarlo**: la página de ajustes de la UI web (Ajustes → General) muestra un desplegable de «Terminal predeterminado» (PowerShell / Git Bash / MSYS2 / WSL); la herramienta `shell` usa siempre únicamente ese ajuste y no expone ningún parámetro de terminal al modelo. El ajuste se persiste mediante el sistema de settings de DSH (settings.yaml). - **No ocupa la costura de capacidades `ctx.shell`**: la herramienta `pwsh` sandboxizada que trae DSH sigue disponible tal cual; la herramienta `shell` de este plugin es una **entrada adicional** multi-terminal. - Los procesos se derivan mediante la costura compartida `ctx.subprocess`: terminación del árbol de procesos (`taskkill /T` en Windows), SIGTERM → gracia → SIGKILL, archivos de spill de salida — comportamiento idéntico al de las herramientas oficiales `dsh-tool-bash` / `dsh-tool-pwsh`. - Las tareas en segundo plano se registran en el registro genérico de `jobs`, con soporte de `run_in_background` / `job_output` / `job_kill`. - La fila «Terminal predeterminado» de la página de ajustes del frontend es una enumeración (la UI la renderiza automáticamente como desplegable); en cada llamada el modelo ejecuta solo conforme a ese ajuste y no puede cambiar de terminal por su cuenta. ## Instalación (perfil web) ### Instalación estándar (tras la publicación en npm, mecanismo oficial de bundle) El plugin trae el manifiesto oficial `dsh.bundle` (`cordis.patch.yml` dentro del paquete); en cuanto un perfil lista este paquete, DSH **aplica el montaje automáticamente**, sin necesidad de editar a mano la configuración del perfil: ```powershell # 1. Instalar el paquete del plugin npm install -g dsh-bash-terminal-ts dsh plugin --profile web add dsh-bash-terminal-ts # se añade automáticamente a los bundles del perfil y aplica el parche # 2. Parchear la allowlist de ajustes de DSH (limitación de DSH, ver explicación abajo) powershell -ExecutionPolicy Bypass -File install.ps1 install # 3. Reiniciar dsh web ``` > Probado en la práctica con un perfil temporal: `bundles: [dsh-bash-terminal-ts]` → la entrada `tool-bash-terminal` aparece automáticamente en el dump-config. ### Instalación para desarrollo local (junction, los cambios de código fuente surten efecto al instante) ```powershell # 1. Enlazar el paquete del plugin a los node_modules del perfil (junction, los cambios de fuente surten efecto al instante) $profile = "$env:USERPROFILE\.dsh\profiles\web" New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal-ts" -Target "D:\workspace\projects\dsh-bash-terminal-ts" | Out-Null # 2. Permitir que el plugin resuelva las dependencias @deepseek-ai/* (junction hacia el árbol de dependencias del perfil; plugin y host comparten las mismas instancias de módulos) New-Item -ItemType Junction -Path "D:\workspace\projects\dsh-bash-terminal-ts\node_modules\@deepseek-ai" -Target "$profile\..\node_modules\@deepseek-ai" | Out-Null # 3. Dejar que el perfil monte el plugin mediante el bundle oficial (install.ps1 install lo hace automáticamente; equivale a añadir "dsh-bash-terminal-ts" a dsh.profile.bundles) # 4. (solo tras modificar el código del frontend) recompilar el bundle del cliente: # cd D:\workspace\projects\dsh-bash-terminal-ts && node scripts/build-client.mjs # 5. Reiniciar dsh web ``` > ⚠️ **No ejecutes `npm install` en este proyecto**: borraría la junction del paso 2 de arriba e instalaría para el plugin una copia **independiente** de > `@deepseek-ai/*` — plugin y host dejarían de compartir instancias de módulos y, tras una actualización del host, el plugin se quedaría en la API antigua > (este proyecto llegó a quedarse atascado en 0.1.0-rc.6 por esa razón). Para refrescar solo el lock, usa `npm install --package-lock-only`. > **Compatibilidad**: requiere DSH ≥ **0.1.7-rc.1** (línea `compat/0.1.7`) o ≥ **0.2.0-rc.1** (línea `compat/0.2.0`, esta rama). > Contexto histórico: en 0.1.5, `@deepseek-ai/dsh-client-runtime` en la tabla de módulos del cliente pasó a llamarse `@deepseek-ai/dsh-client-store` y solo se resuelve por coincidencia exacta del nombre desnudo; los bundles antiguos fallan en el host nuevo con > `Failed to load plugins` / `require(...) missed the module table`. > > Además: desde 0.1.5 la superficie de ajustes web usa la enumeración dinámica `settings.describe()` y **ya no tiene una allowlist de namespaces** > (`settings-not-exposed` ya no existe); el parche de allowlist presente en `install.ps1` es solo un residuo histórico y puede ignorarse. > Ya no hace falta editar manualmente el `cordis.patch.yml` del perfil: el paquete del plugin trae su propio `dsh.bundle.patch` (`cordis.patch.yml` dentro del paquete); basta con que `dsh-bash-terminal-ts` figure en el `dsh.profile.bundles` del perfil para que DSH monte el plugin automáticamente. Verificar el árbol combinado (sin reiniciar): ```powershell node "$env:APPDATA\nvm\\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal-ts ``` ## Uso **El usuario establece el terminal predeterminado en la UI web**: abre los ajustes (engranaje) → General → desplegable «Terminal predeterminado» y elige uno entre PowerShell / Git Bash / MSYS2 / WSL. El cambio surte efecto de inmediato y se persiste. Cuando el modelo ve la herramienta `shell`, ejecuta automáticamente con el terminal que elegiste (la herramienta no expone parámetros de terminal; el modelo no puede cambiar tu elección): - Terminal predeterminado = Git Bash: `shell(command: "git status")` va por Git Bash - Terminal predeterminado = MSYS2: `shell(command: "gcc --version")` va por MSYS2 (entorno MINGW64, disponibles gcc y make de `/mingw64/bin`) - Terminal predeterminado = WSL: `shell(command: "ls -la /mnt/d/workspace")` va por WSL; `distro: "Ubuntu"` permite indicar la distribución - Terminal predeterminado = PowerShell: `shell(command: "Get-Process node")` va por PowerShell ## Ejemplos de uso para el modelo - Comando puntual (terminal predeterminado): `shell(command: "git status", description: "ver el estado de git")` - Estado preservado entre turnos (interactivo): `terminal(action: "open")` → anota el `sessionId` → `terminal(action: "send", sessionId, input: "cd /d/project\n")` → `terminal(action: "send", sessionId, input: "npm run dev\n")` → `terminal(action: "close", sessionId)` - Interrumpir un programa en ejecución: `terminal(action: "signal", sessionId, signal: "SIGINT")` - Consultar las sesiones activas: `terminal(action: "list")` - Escalada tras un rechazo de la sandbox: `shell(command: ..., sandbox_permissions: "workspace-write", justification: "...")` ## Configuración **Ajustes de la UI web** (recomendado): Ajustes → General → «Terminal predeterminado». El `config` de la fila del plugin (sobrescribe los predeterminados y sirve de base de composición para los ajustes): | Clave | Predeterminado | Descripción | |----|------|------| | `defaultShell` | `powershell` | Backend usado cuando los ajustes no sobrescriben | | `timeoutMs` | 120000 | Tiempo de espera predeterminado | | `maxTimeoutMs` | 600000 | Límite superior del timeoutMs del llamante | | `pwshPath` | detección automática | Ruta fija de pwsh.exe | | `gitBashPath` | detección automática | Ruta fija de git bash.exe | | `msys2Path` | detección automática (primero `C:\msys64\usr\bin\bash.exe`, reserva en `msys2.exe`) | Ruta fija de MSYS2 bash.exe | | `wslPath` | detección automática | Ruta fija de wsl.exe | ## Publicación (npm) La cuenta de npm tiene activada la verificación 2FA para publicar; hace falta un código de un solo uso: ```powershell cd D:\workspace\projects\dsh-bash-terminal-ts npm publish --otp # el código lo da tu autenticador ``` Antes de publicar, haz un `npm pack --dry-run` para revisar el contenido y ejecuta `npm run build` para recompilar todo (compilación de servidor con tsc + bundle del cliente + compilación de los tests). ## Desinstalación Basta con ejecutar: ```powershell powershell -ExecutionPolicy Bypass -File install.ps1 uninstall ``` Elimina las junction, restaura la allowlist de ajustes, limpia los bloques de montaje `cordis.patch.yml` heredados de versiones antiguas y retira `dsh-bash-terminal-ts` del `dsh.profile.bundles`. Después reinicia dsh web. En una desinstalación manual, además de borrar `node_modules\dsh-bash-terminal-ts`, recuerda también retirar `dsh-bash-terminal-ts` del `dsh.profile.bundles` del `package.json` del perfil. ## Terminal interactivo (herramienta `terminal`) La herramienta `terminal` ofrece **sesiones interactivas persistentes** sobre la costura PTY (node-pty; en Windows, como el process inspector del `spawnTerminal` upstream solo admite POSIX, `lib/terminal.js` se conecta directamente a node-pty; fuera de Windows se sigue usando el `ctx.subprocess.spawnTerminal` oficial): - `action: open` inicia una sesión de terminal real (según tu terminal predeterminado configurado; en wsl se puede pasar `distro`) y devuelve un `sessionId` - `action: send` escribe la entrada y lee la nueva salida; `action: read` solo lee, sin escribir; `action: signal` envía una señal al grupo de procesos en primer plano (SIGINT = Ctrl+C) - `action: close` termina la sesión - **El estado de la sesión se conserva entre llamadas** (cwd / variables / alias), ideal para REPL, ssh y CLIs interactivos - `send` espera a que la salida se estabilice (300 ms de silencio, tope de 5 s) y devuelve la **respuesta completa**; con más de 1 MB de salida emite el aviso `truncated` - La entrada termina en `\\n` (o \\r) para representar la tecla Enter ## Sandbox (conexión con el mecanismo oficial) La herramienta `shell` pasa por la costura oficial de sandbox de DSH (`ctx.sandboxPolicy` + `ctx.sandbox`): - En cada llamada se resuelve la política de sandbox vigente; las sesiones `danger-full-access` se ejecutan directamente (sin envoltura). - El backend PowerShell envuelve el argv mediante `ctx.sandbox.confine` — la misma semántica **fail-closed** que los ejecutores oficiales: si se pide el modo restringido y no hay backend disponible, se lanza `SandboxUnavailableError`, rechazando la ejecución desnuda. - El backend Git Bash no se envuelve: el runner de token restringido con ACL de Windows de DSH es incompatible con Cygwin/MSYS2 (bash aborta al arrancar con el error Win32 5 de `CreateFileMapping`); por eso Git Bash tampoco pasa por envoltura de sandbox en modo restringido; el resultado informa `enforcement: gitbash-unconfined`. - El backend MSYS2 tampoco se envuelve (la misma incompatibilidad de runtime Cygwin/MSYS2); el resultado informa `enforcement: msys2-unconfined`. - El backend WSL no se envuelve: la máquina virtual Linux independiente de WSL es por sí misma el aislamiento (el resultado informa `enforcement: wsl-isolation`). - Cuando la sandbox rechaza en modo restringido, el resultado lleva el marcador oficial `[sandbox: file access denied under mode]` y la pista de escalada del mismo turno; el modelo puede iniciar una escalada con `sandbox_permissions` + `justification` (aprobación del usuario vía `ctx.approval`), exactamente igual que las herramientas oficiales bash/pwsh. - Nota: cuando el runner de ACL de Windows de DSH está disponible, el modo restringido de PowerShell se envuelve a través de él; Git Bash y MSYS2 siguen sin envolver por la incompatibilidad Cygwin/MSYS2. ## ⚠️ Notas de seguridad La herramienta `shell` en modo restringido: PowerShell se envuelve vía `ctx.sandbox.confine` (fail-closed); Git Bash y MSYS2 **no se envuelven** por la incompatibilidad entre Cygwin/MSYS2 y los tokens restringidos de ACL de Windows (mismos permisos que el proceso dsh); WSL no se envuelve gracias a su VM Linux independiente. Es una **entrada adicional multi-terminal** y no disfruta de las restricciones ConstrainedLanguage de la herramienta oficial `pwsh`. Las herramientas de manejo de archivos de DSH (read/write/edit) siguen sujetas a la sandbox de archivos. Úsala solo en sesiones de confianza; para un PowerShell protegido por la sandbox sigue usando la herramienta oficial `pwsh`. ## Limitaciones conocidas del terminal interactivo (ConPTY) - **PowerShell 5.1 no puede arrancar en un ConPTY** (0x8009001d) — para PowerShell interactivo instala [PowerShell 7](https://github.com/PowerShell/PowerShell/releases) (los comandos puntuales no se ven afectados). - **El modo interactivo de wsl.exe puede desencadenar un error RPC del servicio WSL bajo ConPTY** (0x8007072c, intermitente) — los comandos puntuales `wsl -e bash -lc ...` funcionan con normalidad; para sesiones interactivas conviene usar directamente Windows Terminal / un terminal de WSL, o reintentar. - **node-pty no acepta señales con nombre en Windows**: el `SIGINT` de `signal` se mapea a Ctrl+C (`\x03`); las demás señales (`SIGTERM` / `SIGKILL` / `SIGTSTP` / `SIGHUP`) degradan a terminar la sesión. - Las sesiones interactivas de Git Bash funcionan por completo. ## Limitaciones conocidas - Los procesos en segundo plano de WSL pueden sobrevivir brevemente dentro de la distribución tras un timeout/interrupción (la instancia de WSL se apaga sola tras la salida del último proceso). - Git Bash es un entorno msys2, con diferencias respecto al comportamiento Linux de WSL (mapeo de rutas, disponibilidad de paquetes). - El backend MSYS2 requiere MSYS2 instalado localmente (por defecto `C:\msys64`); sin instalación `shell` informa `backend unavailable`, y con `msys2Path` se puede indicar una ubicación personalizada. El orden de candidatos siempre es `bash.exe` primero y `msys2.exe` de reserva — con stdio por tubería `msys2.exe` devuelve silenciosamente cero bytes y solo sirve como último recurso. - Este plugin registra sus herramientas únicamente en la plataforma `win32`. ## Pruebas ```powershell cd D:\workspace\projects\dsh-bash-terminal-ts npm install # instalar las dependencias (typescript incluido) npm run build # compilación tsc de src/*.ts → lib/*.js; client.tsx → lib/client.js + dist/client.js; test/*.ts → test-dist/ npm test # node test-dist/unit.js → apply.js → client.js → terminal.js ``` El código fuente está en TypeScript (`strict` + `noUncheckedIndexedAccess`); los artefactos de compilación `lib/` y `dist/` se suben al repositorio y DSH carga directamente `lib/index.js`, listo para usar sin instalación.