# 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) · Community: [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) DSH-Plugin (DeepSeek Harness): ein `shell`-Werkzeug, das unter Windows die Befehle **vierer** Terminals – **PowerShell / Git Bash / MSYS2 / WSL** – einheitlich ausfĂŒhrt. > **Dieses Repository ist die TypeScript-Neuschreibung von `MAXeaglet/dsh-bash-terminal`** mit funktionsfĂ€higer MSYS2/MINGW64-UnterstĂŒtzung. Die KompatibilitĂ€tslinien werden pro DSH-Host-Segment geschnitten; alle Linien teilen sich den Paketnamen `dsh-bash-terminal-ts` und werden ĂŒber npm-dist-tags unterschieden: > > | DSH-Segment | Branch | Plugin-Version | npm-dist-tag | > |--------|------|----------|--------------| > | `>=0.2.0-rc.1 <0.2.1-0` | `compat/0.2.0` (dieser Branch) | 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` (historisch, eingefroren) | ≀ 0.5.2 | `dsh-0.1.5` | > | 0.1.2-alpha.1 – 0.1.2-rc.x | `main` (historisch, eingefroren) | ≀ 0.4.2 | `dsh-0.1.2` | > > WĂ€hlen Sie die Linie passend zu Ihrer DSH-Version; die Versionsserien ĂŒberlappen nicht, daher kann eine `^`-Installation nie ĂŒber Linien hinweg auflösen. | Backend | TatsĂ€chliche AusfĂŒhrung | Syntax / Pfade | Umgebungsvariablen | |------|----------|-------------|----------| | `powershell` (Standard) | `pwsh -NoLogo -NoProfile -NonInteractive -Command ` | PowerShell; `C:\...` | `$env:NAME` | | `gitbash` | `bash -lc ` aus Git for Windows | POSIX; `/d/workspace`; PATH enthĂ€lt `/usr/bin` und `/mingw64/bin` | `$NAME` | | `msys2` | MSYS2 `bash -lc ` (`C:\msys64\usr\bin\bash.exe`) | POSIX; `/c/...`; PATH enthĂ€lt `/usr/bin` und `/mingw64/bin` (gcc / make) | `$NAME` (`MSYSTEM=MINGW64` wird automatisch injiziert) | | `wsl` | `wsl [-d ] -e bash -lc ` | Linux; `/mnt/d/...` | `$NAME` (ĂŒber WSLENV) | Jeder Aufruf startet eine komplett neue Shell: **Es wird kein Zustand bewahrt** (cwd / Variablen / Aliasse) – ĂŒbergeben Sie `workdir`, statt `cd` zu verwenden. ## Vorschau der OberflĂ€che Die Zeile „Standardterminal" in Einstellungen → Allgemein: Der Nutzer wĂ€hlt zwischen PowerShell / Git Bash / MSYS2 / WSL, und das `shell`-Werkzeug fĂŒhrt ausschließlich gemĂ€ĂŸ dieser Einstellung aus – das Modell kann sie nicht ĂŒberschreiben: ![Zeile fĂŒr die Standardterminal-Einstellung](assets/shells.png) ## Entwurfsprinzipien - **Das Terminal bestimmt der Nutzer, die KI kann es nicht Ă€ndern**: Die Einstellungsseite der Web-UI (Einstellungen → Allgemein) bietet ein Dropdown „Standardterminal" (PowerShell / Git Bash / MSYS2 / WSL); das `shell`-Werkzeug folgt stets ausschließlich dieser Einstellung und legt dem Modell keine Terminal-Parameter offen. Die Einstellung wird ĂŒber das DSH-Settings-System persistiert (settings.yaml). - **Belegt die FĂ€higkeitsschnittstelle `ctx.shell` nicht**: Das sandboxierte `pwsh`-Werkzeug von DSH bleibt unverĂ€ndert nutzbar; das `shell`-Werkzeug dieses Plugins ist ein **zusĂ€tzlicher** Multi-Terminal-Einstiegspunkt. - Prozesse werden ĂŒber die gemeinsame `ctx.subprocess`-Naht erzeugt: Beendigung des Prozessbaums (unter Windows `taskkill /T`), SIGTERM → Gnistenfrist → SIGKILL, Ausgabe-Spill-Dateien – Verhalten identisch zu den offiziellen Werkzeugen `dsh-tool-bash` / `dsh-tool-pwsh`. - Hintergrundaufgaben werden im generischen `jobs`-Registry registriert, mit UnterstĂŒtzung fĂŒr `run_in_background` / `job_output` / `job_kill`. - Die Zeile „Standardterminal" der Frontend-Einstellungsseite ist eine Enumeration (von der UI automatisch als Dropdown gerendert); das Modell fĂŒhrt bei jedem Aufruf gemĂ€ĂŸ dieser Einstellung aus und kann das Terminal nicht eigenmĂ€chtig wechseln. ## Installation (Web-Profil) ### Standardinstallation (nach der npm-Veröffentlichung, offizieller Bundle-Mechanismus) Das Plugin bringt das offizielle `dsh.bundle`-Manifest mit (eigene `cordis.patch.yml` im Paket); sobald ein Profil dieses Paket auffĂŒhrt, **wendet DSH den Mount automatisch an** – eine manuelle Anpassung der Profil-Konfiguration ist nicht nötig: ```powershell # 1. Plugin-Paket installieren npm install -g dsh-bash-terminal-ts dsh plugin --profile web add dsh-bash-terminal-ts # automatisch in die Profile-Bundles aufnehmen und Patch anwenden # 2. Settings-Allowlist von DSH patchen (DSH-EinschrĂ€nkung, siehe ErlĂ€uterung unten) powershell -ExecutionPolicy Bypass -File install.ps1 install # 3. dsh web neu starten ``` > Mit einem temporĂ€ren Profil praktisch erprobt: `bundles: [dsh-bash-terminal-ts]` → der Eintrag `tool-bash-terminal` erscheint automatisch im dump-config. ### Installation fĂŒr die lokale Entwicklung (Junction, Quellcode-Änderungen wirken sofort) ```powershell # 1. Plugin-Paket in die node_modules des Profils linken (Junction, Quellcode-Änderungen wirken sofort) $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. Dem Plugin die Auflösung der @deepseek-ai/*-AbhĂ€ngigkeiten ermöglichen (Junction in den AbhĂ€ngigkeitsbaum des Profils; Plugin und Host teilen sich dieselben Modulinstanzen) 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. Das Profil das Plugin ĂŒber das offizielle Bundle mounten lassen (install.ps1 install erledigt das automatisch; entspricht dem Eintrag "dsh-bash-terminal-ts" in dsh.profile.bundles) # 4. (nur nach Änderungen am Frontend-Quellcode) Client-Bundle neu bauen: # cd D:\workspace\projects\dsh-bash-terminal-ts && node scripts/build-client.mjs # 5. dsh web neu starten ``` > ⚠ **FĂŒhren Sie in diesem Projekt kein `npm install` aus**: Es wĂŒrde die Junction aus Schritt 2 oben löschen und stattdessen eine **eigenstĂ€ndige** Kopie von > `@deepseek-ai/*` fĂŒr das Plugin installieren – Plugin und Host teilten sich dann keine Modulinstanzen mehr, und nach einem Host-Upgrade bliebe das Plugin auf der alten API hĂ€ngen > (dieses Projekt hing dadurch einmal auf 0.1.0-rc.6 fest). Nur zum Aktualisieren des Locks `npm install --package-lock-only` verwenden. > **KompatibilitĂ€t**: Erfordert DSH ≄ **0.1.7-rc.1** (Linie `compat/0.1.7`) oder ≄ **0.2.0-rc.1** (Linie `compat/0.2.0`, dieser Branch). > Historischer Hintergrund: In 0.1.5 wurde `@deepseek-ai/dsh-client-runtime` in der Client-Modultabelle in `@deepseek-ai/dsh-client-store` umbenannt und wird nur ĂŒber exakte Treffer des nackten Namens aufgelöst; alte Bundles schlagen auf dem neuen Host fehl mit > `Failed to load plugins` / `require(...) missed the module table`. > > Hinweis: Seit 0.1.5 nutzt die Web-Settings-OberflĂ€che die dynamische Enumeration `settings.describe()` und hat **keine Namespace-Allowlist mehr** > (`settings-not-exposed` existiert nicht mehr); der Allowlist-Patch in `install.ps1` ist nur noch ein historisches Überbleibsel und kann ignoriert werden. > Eine manuelle Anpassung der `cordis.patch.yml` des Profils ist nicht mehr erforderlich: Das Plugin-Paket bringt sein eigenes `dsh.bundle.patch` mit (`cordis.patch.yml` im Paket); sobald `dsh-bash-terminal-ts` im `dsh.profile.bundles` des Profils steht, mountet DSH das Plugin automatisch. Kombinierten Baum verifizieren (ohne Neustart): ```powershell node "$env:APPDATA\nvm\\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal-ts ``` ## Verwendung **Der Nutzer wĂ€hlt das Standardterminal in der Web-UI**: Einstellungen (Zahnrad) öffnen → Allgemein → Dropdown „Standardterminal" und eines der Terminals PowerShell / Git Bash / MSYS2 / WSL wĂ€hlen. Änderungen wirken sofort und werden persistiert. Sobald das Modell das `shell`-Werkzeug sieht, verwendet es automatisch das von Ihnen gewĂ€hlte Terminal (das Werkzeug legt keinen Terminal-Parameter offen; das Modell kann Ihre Wahl nicht Ă€ndern): - Standardterminal = Git Bash: `shell(command: "git status")` lĂ€uft ĂŒber Git Bash - Standardterminal = MSYS2: `shell(command: "gcc --version")` lĂ€uft ĂŒber MSYS2 (MINGW64-Umgebung, gcc und make aus `/mingw64/bin` verfĂŒgbar) - Standardterminal = WSL: `shell(command: "ls -la /mnt/d/workspace")` lĂ€uft ĂŒber WSL; mit `distro: "Ubuntu"` lĂ€sst sich die Distribution angeben - Standardterminal = PowerShell: `shell(command: "Get-Process node")` lĂ€uft ĂŒber PowerShell ## Beispiele zur Modellnutzung - Einmalbefehl (Standardterminal): `shell(command: "git status", description: "Git-Status prĂŒfen")` - Zustand ĂŒber Runden hinweg bewahren (interaktiv): `terminal(action: "open")` → `sessionId` notieren → `terminal(action: "send", sessionId, input: "cd /d/project\n")` → `terminal(action: "send", sessionId, input: "npm run dev\n")` → `terminal(action: "close", sessionId)` - Laufendes Programm unterbrechen: `terminal(action: "signal", sessionId, signal: "SIGINT")` - Aktive Sitzungen einsehen: `terminal(action: "list")` - Eskalation nach Sandbox-Ablehnung: `shell(command: ..., sandbox_permissions: "workspace-write", justification: "...")` ## Konfiguration **Web-UI-Einstellungen** (empfohlen): Einstellungen → Allgemein → „Standardterminal". `config` der Plugin-Zeile (ĂŒberschreibt die Standardwerte und dient als Kompositionsgrundlage der Einstellungen): | SchlĂŒssel | Standard | Beschreibung | |----|------|------| | `defaultShell` | `powershell` | Backend, sofern die Einstellungen nichts anderes festlegen | | `timeoutMs` | 120000 | Standard-Timeout | | `maxTimeoutMs` | 600000 | Obergrenze fĂŒr das timeoutMs des Aufrufers | | `pwshPath` | automatische Erkennung | Fester Pfad zu pwsh.exe | | `gitBashPath` | automatische Erkennung | Fester Pfad zu git bash.exe | | `msys2Path` | automatische Erkennung (`C:\msys64\usr\bin\bash.exe` bevorzugt, Fallback `msys2.exe`) | Fester Pfad zu MSYS2 bash.exe | | `wslPath` | automatische Erkennung | Fester Pfad zu wsl.exe | ## Veröffentlichung (npm) Das npm-Konto hat die 2FA-Verifizierung fĂŒr Veröffentlichungen aktiviert; ein Einmalcode ist erforderlich: ```powershell cd D:\workspace\projects\dsh-bash-terminal-ts npm publish --otp # der Code stammt von Ihrem Authentifikator ``` Vor der Veröffentlichung mit `npm pack --dry-run` den Inhalt prĂŒfen und `npm run build` ausfĂŒhren, um alles neu zu bauen (tsc-Serverkompilierung + Client-Bundle + Testkompilierung). ## Deinstallation Einfach ausfĂŒhren: ```powershell powershell -ExecutionPolicy Bypass -File install.ps1 uninstall ``` Der Befehl entfernt die Junctions, stellt die Settings-Allowlist wieder her, rĂ€umt die veralteten `cordis.patch.yml`-Mount-Blöcke frĂŒherer Versionen auf und entfernt `dsh-bash-terminal-ts` aus dem `dsh.profile.bundles`. Anschließend dsh web neu starten. Bei manueller Deinstallation ist – neben dem Entfernen von `node_modules\dsh-bash-terminal-ts` – auch daran zu denken, `dsh-bash-terminal-ts` aus dem `dsh.profile.bundles` der Profil-`package.json` zu entfernen. ## Interaktives Terminal (Werkzeug `terminal`) Das Werkzeug `terminal` stellt **persistente interaktive Sitzungen** ĂŒber die PTY-Naht bereit (node-pty; unter Windows direkt ĂŒber node-pty, weil der Process Inspector des upstream `spawnTerminal` nur POSIX unterstĂŒtzt – `lib/terminal.js` verbindet sich daher direkt mit node-pty; unter Nicht-Windows wird weiterhin das offizielle `ctx.subprocess.spawnTerminal` verwendet): - `action: open` startet eine echte Terminal-Sitzung (gemĂ€ĂŸ Ihrer Standardterminal-Einstellung; bei wsl kann `distro` angegeben werden) und liefert eine `sessionId` - `action: send` schreibt die Eingabe und liest die neue Ausgabe; `action: read` liest nur, ohne zu schreiben; `action: signal` sendet ein Signal an die Vordergrund-Prozessgruppe (SIGINT = Ctrl+C) - `action: close` beendet die Sitzung - **Der Sitzungszustand bleibt ĂŒber Aufrufe hinweg erhalten** (cwd / Variablen / Aliasse), geeignet fĂŒr REPL, ssh und interaktive CLIs - `send` wartet, bis sich die Ausgabe stabilisiert hat (300 ms Stille, Obergrenze 5 s), und liefert die **vollstĂ€ndige Antwort**; bei mehr als 1 MB Ausgabe folgt der Hinweis `truncated` - Die Eingabe endet mit `\\n` (oder \\r), um die Eingabetaste zu signalisieren ## Sandbox (Anbindung an den offiziellen Mechanismus) Das `shell`-Werkzeug nutzt die offizielle Sandbox-Naht von DSH (`ctx.sandboxPolicy` + `ctx.sandbox`): - Bei jedem Aufruf wird die aktuelle Sandbox-Richtlinie aufgelöst; `danger-full-access`-Sitzungen werden direkt ausgefĂŒhrt (ohne Ummantelung). - Das PowerShell-Backend umhĂŒllt argv ĂŒber `ctx.sandbox.confine` – dieselbe **Fail-closed**-Semantik wie bei den offiziellen Executoren: Wird der eingeschrĂ€nkte Modus angefordert, aber kein Backend gefunden, fliegt eine `SandboxUnavailableError`; ein ungeschĂŒtzter Lauf wird verweigert. - Das Git-Bash-Backend wird nicht umhĂŒllt: Der Windows-ACL-Restricted-Token-Runner von DSH ist inkompatibel mit Cygwin/MSYS2 (bash bricht beim Start mit `CreateFileMapping` Win32-Fehler 5 ab); daher lĂ€uft Git Bash auch im eingeschrĂ€nkten Modus ohne Sandbox-Ummantelung; das Ergebnis meldet `enforcement: gitbash-unconfined`. - Das MSYS2-Backend wird ebenfalls nicht umhĂŒllt (dieselbe Cygwin/MSYS2-LaufzeitinkompatibilitĂ€t); das Ergebnis meldet `enforcement: msys2-unconfined`. - Das WSL-Backend wird nicht umhĂŒllt: Die eigenstĂ€ndige Linux-VM von WSL ist selbst die Isolation (das Ergebnis meldet `enforcement: wsl-isolation`). - Wird ein Aufruf im eingeschrĂ€nkten Modus von der Sandbox abgelehnt, trĂ€gt das Ergebnis das offizielle Kennzeichen `[sandbox: file access denied under mode]` samt Eskalationshinweis fĂŒr dieselbe Runde; das Modell kann mit `sandbox_permissions` + `justification` eine Eskalation anstoßen (Nutzerfreigabe ĂŒber `ctx.approval`) – exakt wie bei den offiziellen bash/pwsh-Werkzeugen. - Hinweis: Wenn der Windows-ACL-Runner von DSH verfĂŒgbar ist, wird der eingeschrĂ€nkte Modus von PowerShell ĂŒber ihn umhĂŒllt; Git Bash und MSYS2 bleiben wegen der Cygwin/MSYS2-InkompatibilitĂ€t unumhĂŒllt. ## ⚠ Sicherheitshinweis Das `shell`-Werkzeug im eingeschrĂ€nkten Modus: PowerShell wird ĂŒber `ctx.sandbox.confine` umhĂŒllt (fail-closed); Git Bash und MSYS2 bleiben wegen der InkompatibilitĂ€t von Cygwin/MSYS2 mit dem Windows-ACL-Restricted-Token **unumhĂŒllt** (gleiche Berechtigungen wie der dsh-Prozess); WSL bleibt dank seiner eigenstĂ€ndigen Linux-VM unumhĂŒllt. Es ist ein **zusĂ€tzlicher Multi-Terminal-Einstiegspunkt** und genießt nicht die ConstrainedLanguage-EinschrĂ€nkungen des offiziellen `pwsh`-Werkzeugs. Die Datei-Werkzeuge von DSH (read/write/edit) unterliegen weiterhin der Datei-Sandbox. Nur in Sitzungen verwenden, denen Sie vertrauen; fĂŒr sandboxgeschĂŒtztes PowerShell weiterhin das offizielle `pwsh`-Werkzeug nutzen. ## Bekannte EinschrĂ€nkungen des interaktiven Terminals (ConPTY) - **PowerShell 5.1 kann in einem ConPTY nicht starten** (0x8009001d) – fĂŒr interaktives PowerShell [PowerShell 7](https://github.com/PowerShell/PowerShell/releases) installieren (Einmalbefehle sind nicht betroffen). - **Der interaktive Modus von wsl.exe kann unter ConPTY einen RPC-Fehler des WSL-Dienstes auslösen** (0x8007072c, sporadisch) – Einmalbefehle `wsl -e bash -lc ...` funktionieren normal; fĂŒr interaktive Sitzungen besser Windows Terminal / ein WSL-Terminal verwenden oder es erneut versuchen. - **node-pty akzeptiert unter Windows keine benannten Signale**: `SIGINT` von `signal` wird auf Ctrl+C (`\x03`) abgebildet; andere Signale (`SIGTERM` / `SIGKILL` / `SIGTSTP` / `SIGHUP`) degradieren zur Beendigung der Sitzung. - Interaktive Git-Bash-Sitzungen funktionieren vollumfĂ€nglich. ## Bekannte EinschrĂ€nkungen - WSL-Hintergrundprozesse können nach Timeout/Abbruch noch kurz in der Distribution weiterlaufen (die WSL-Instanz schaltet sich nach dem Ende des letzten Prozesses automatisch ab). - Git Bash ist eine msys2-Umgebung und weicht vom Linux-Verhalten von WSL ab (Pfad-Mapping, PaketverfĂŒgbarkeit). - Das MSYS2-Backend erfordert eine lokal installierte MSYS2 (Standard `C:\msys64`); ohne Installation meldet `shell` den Fehler `backend unavailable`, mit `msys2Path` lĂ€sst sich ein benutzerdefinierter Ort angeben. Die Kandidatenreihenfolge bleibt immer: `bash.exe` zuerst, `msys2.exe` als Fallback – bei weitergeleitetem stdio liefert `msys2.exe` stumm null Byte und dient nur als letzte Rettung. - Dieses Plugin registriert seine Werkzeuge nur auf der Plattform `win32`. ## Tests ```powershell cd D:\workspace\projects\dsh-bash-terminal-ts npm install # AbhĂ€ngigkeiten installieren (typescript inklusive) npm run build # tsc-Kompilierung 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 ``` Der Quellcode ist TypeScript (`strict` + `noUncheckedIndexedAccess`); die Build-Artefakte `lib/` und `dist/` werden mit dem Repository eingecheckt, DSH lĂ€dt direkt `lib/index.js` – ohne Installation einsatzbereit.