dsh-minimal-win

Readme

# minimal-win：Windows 持久 shell 极简预设

本目录是一个 **DSH agent preset**（`minimal-win`），让「极简模式」
（持久 bash + str_replace_editor）在 Windows 上真正可用。

## 安装与使用

### 环境要求

- Windows 10/11
- 已安装 [Git for Windows](https://git-scm.com/download/win)（Git Bash）
- 已安装 DSH（Agent 客户端）

### 安装

把本仓库克隆到 DSH 的 agent presets 目录，目录名必须是预设 id
`minimal-win`：

```bash
mkdir -p ~/.dsh/.agent-presets
cd ~/.dsh/.agent-presets
git clone https://github.com/judgeou/dsh-minimal-win.git minimal-win
```

> 已经装过旧版本时，直接 `cd ~/.dsh/.agent-presets/minimal-win && git pull` 更新即可。
> 也可以下载 ZIP 解压，但请把解压出来的文件夹改名为 `minimal-win`。

纯 JS 插件，**无需 `npm install`**。

### 启用

在 DSH 中选择预设 **`minimal-win`** 即可。预设会提供两个工具：

- `bash`：Windows 持久 Git Bash（状态跨命令保持）
- `str_replace_editor`：文件编辑

### 日常使用

- 和普通 bash 一样使用即可；`cd` / `export` / 环境变量会跨命令保持。
- 编辑文件请用 `str_replace_editor`，不要用 bash 写文件。
- 需要编译 Windows C/C++ 或 D3D12 时，在 `bash` 里执行：

```bash
source <本预设目录>/msvc-env.sh
```

`bash` 工具描述里已经自动填好当前安装目录的绝对路径，模型会直接执行；
手动执行时请把 `<本预设目录>` 换成实际路径。

### 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `BASH_PATH` | `C:\Program Files\Git\bin\bash.exe` | Git Bash 路径（装在非默认位置时设置） |
| `MSVC_ENV_SH` | 插件同目录下的 `msvc-env.sh` | 手动指定 msvc-env.sh 位置 |
| `MSVC_VSVARS` | 自动查找 | 手动指定 `vcvars64.bat` 完整 Windows 路径 |

## 为什么需要这一套

DSH 自带的持久 shell（`dsh-terminal-bash`）在 Windows 上不可用：
`dsh-subprocess-local` 的 `createProcessInspector()` 只在 Linux/macOS 实现，
`spawnTerminal()` 在 win32 上直接抛
`subprocess-local: terminal inspection is unsupported on platform win32`。

这是「PTY 前台进程组检测」这个 POSIX 概念在 Windows 上没有对应物导致的，
改 shellPath / 换 shell 都绕不开。

## 方案：纯 JS 直接持有 Git Bash

```
DSH 插件(bash-persistent-win.mjs)
  --ctx.subprocess.spawn(pipe)-->  bash.exe -s
                                     |
                                  持有子进程：cwd/env 跨命令保持
```

- `bash-persistent-win.mjs`（DSH 插件，纯 JS）：直接 spawn Git Bash，用自插标记
  `__DSH_BEGIN_<token>_<n>__` / `__DSH_END_<token>_<n>:<code>` 判断命令边界，
  不依赖 PTY、不依赖 C++ 转接层。
- 内层 bash 用 `exec bash --noprofile --norc -s 2>&1` 启动：stderr 在 FD 层
  合并进 stdout，标记协议只读一条管道，`cl`/`link` 的报错不会漏。
- 对外接口仍是「bash + 持久」，模型训练红利 100% 保留。
- **按会话隔离**：preset 是 standing mount，插件实例跨会话共享，所以每个
  sessionId 各起一个 bash，避免 cwd/环境变量/目录状态串台；会话销毁
  （`session/disposed`）或空闲 30 分钟都会回收，进程数有界（硬上限 64）。

## 文件

| 文件 | 作用 |
|---|---|
| `agent.cordis.yml` | 预设组合（persona + 本地 bash 插件 + filesystem） |
| `preset.yml` | 预设元数据 |
| `bash-persistent-win.mjs` | DSH 插件（spawn bash + 注册 bash 工具，纯 JS） |
| `msvc-env.sh` | 导入 MSVC x64 工具链（cl/link/rc/dxc/cmake）的脚本，`source` 使用 |

## 协议

**DSH 插件 ↔ bash（标记协议，单条 stdout 管道）**

每条命令写成一行喂给 bash stdin：

```
printf '%s\n' '<BEGIN>'; eval -- $'<转义命令>'; __rc=$?; printf '%s%s\n' '<END>' "$__rc"
```

读 stdout 直到看到 `<END>:<code>`，取 BEGIN 与 END 之间为命令输出。

- 命令用 `$'...'` 转义（`\\` `\'` `\n` `\r`），与旧实现逐字符一致。
- 单条命令超时（5 分钟）→ 杀掉 bash 并提示 `[shell_server: command timed out; state was reset]`，下一条命令自动重起。

## MSVC / D3D12 环境

Git Bash 里 `cl.exe`、`dxc`、`cmake` 默认不在 PATH（需先过 vcvars64.bat）。
模型在 `bash` 工具里只需执行：

```bash
source <本预设目录>/msvc-env.sh
```

> `bash` 工具描述里会自动填入当前预设目录的绝对路径；本地手动执行时请把
> `<本预设目录>` 换成实际安装位置。

`msvc-env.sh` 会按以下顺序查找 `vcvars64.bat`：

1. 环境变量 `MSVC_VSVARS`（可直接指定完整 Windows 路径）
2. `vswhere.exe`（VS Installer 自带，能定位装在其他盘符的 VS）
3. 常见安装位置兜底

如果仍然找不到，在 `source` 前先设置：

```bash
export MSVC_VSVARS='C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvars64.bat'
source <本预设目录>/msvc-env.sh
```

导入后可用：`cl`、`link`、`rc`、`dxc`（HLSL 着色器编译器）、`cmake`，以及 Windows
SDK 的 `INCLUDE`/`LIB` 路径。

实现要点（都已实测验证）：

- 用 `cmd //c <临时bat>` 跑 `vcvars64.bat && set`，抓取环境变量——避免
  MSYS 给 `cmd.exe` 传参时把 `"` 转成 `\"` 的引号坑。
- `PATH` 从 Windows 形式（分号/反斜杠）转成 MSYS POSIX 形式（`cygpath -u`），
  前缀合并到现有 PATH；`INCLUDE`/`LIB` 保持 Windows 原生形式给 cl/link 吃。
- `cl`/`link`/`rc`/`dxc` 包装成函数，调用时局部 `MSYS2_ARG_CONV_EXCL='*'`，
  否则 `/EHsc`、`/nologo` 会被 MSYS 误转成 `C:/Program Files/Git/EHsc` 导致链接失败。
- 给 `cl` 传源文件请用**相对路径或 Windows 形式路径**（`/c/...` POSIX 路径不认）。

## 已验证

- 协议端到端（bash spawn + 标记）：基本命令、export/cd 跨调用持久、非零
  退出码、多行命令、转义与中文、stderr 合并（`ls` 不存在路径报错可见）全部通过。
- MSVC 编译 + 链接 + 运行（`cl` / `dxc`）通过。
- 按会话隔离：不同工作区的会话各自 `pwd` 正确，不再串台。

## 已知边界

- `exit` 命令会让 bash 退出 → 插件自动重启（状态重置），提示
  `[shell_server: bash exited; state was reset]`。
- 单条命令超时（5 分钟）→ 同上重置。
- 底层是 Git Bash（MSYS2），`pwd` 显示 `/c/...` 形式；`cl.exe` 需先
  `source msvc-env.sh` 导入 MSVC 环境（见上节）。若 VS 装在非默认位置，
  请设置 `MSVC_VSVARS` 后再 `source`。
- 本插件经 `ctx.subprocess.spawn`（普通管道）持有 bash，不走 `spawnTerminal`，
  因此不受 PTY 缺口影响。
- bash 路径默认 `C:\Program Files\Git\bin\bash.exe`，可用环境变量
  `BASH_PATH` 覆盖。