# dsh-bash-persist-windows

**Repository Path**: DaFei_93/dsh-bash-persist-windows

## Basic Information

- **Project Name**: dsh-bash-persist-windows
- **Description**: Persistent bash for DSH (DeepSeek Harness) on Windows: state-file persistence (cd/export/functions/umask across calls) where the official PTY chain is unavailable. Zero native modules.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dsh-bash-persist-windows

**DSH (DeepSeek Harness) Windows 上的持久 bash 方案**：状态文件持久化，`cd` / `export` / 函数跨调用保留，零原生模块，全官方栈消费。

## 为什么需要它

官方持久化 bash 工具链（`dsh-tool-bash-persistent` → `dsh-terminal-bash` → `dsh-subprocess-local`）在 **Windows 上不可用**：`dsh-subprocess-local` 的 `createProcessInspector()` 只实现 linux/darwin，对 win32 直接 throw（`lib/index.js:295-298`），`spawnTerminal()` 必经此路（998 行），官方 README 自认「终端进程检查仅支持 Linux/macOS」。

非持久化的 `dsh-tool-bash`（`bash -c` 每次新 shell）在 win32 可用，但 `cd`/环境变量跨调用全丢。

**本方案**：不改官方代码，用**状态文件**让每次新 shell 恢复/保存状态——`source <state>; <cmd>; trap EXIT 保存`。零原生模块（仅 `node:fs/path/os`），沙箱门控、审计、退出码、截断/spill 全走官方栈。

## 组成

| 文件 | 作用 |
|---|---|
| `gitbash-executor-persist.mjs` | 提供 `ctx.shell` 的 resolve/run/start 协议，官方 `dsh-tool-bash` 原样消费；每次调用经状态文件恢复/保存 cwd/变量/函数/umask |
| `bash-desc-patch.mjs` | 修正模型看到的 bash 工具描述——官方描述硬编码「每次全新 shell、无状态、请用 workdir」，与事实相反，会让模型不必要合并命令/自我怀疑；本模块在 assemble 时替换为持久化版描述 |
| `agent.cordis.yml.example` | 组合行示例（`bash-persist-shell` 组 + `bash-desc-patch` 行） |
| `test/` | 单元测试（描述补丁 + 状态路径解析） |

## 安装

1. 把 `gitbash-executor-persist.mjs`、`bash-desc-patch.mjs` 复制到你的 preset 目录（如 `.agent-presets/<你的preset>/`）；
2. 按 `agent.cordis.yml.example` 在你的 `agent.cordis.yml` 加入 `bash-persist-shell` 组与 `bash-desc-patch` 行（`shellPath` 填你的 Git Bash 路径）；
3. 重启 DSH，新建会话（沙箱需**完全访问** danger-full-access——MSYS 无法在受限令牌沙箱启动）。

## 配置

| 配置 | 默认 | 说明 |
|---|---|---|
| `shellPath` | 自动探测（GIT_BASH → 常见安装目录 → PATH） | Git Bash 的 `bash.exe` 路径，如 `C:\Program Files\Git\bin\bash.exe` |
| `timeoutMs` / `maxTimeoutMs` | 120000 / 600000 | 单次/上限超时 |
| `maxOutputBytes` / `maxSpillBytes` | 64000 / 67108864 | 输出截断与溢出文件 |
| `graceMs` | 3000 | 终止宽限 |

## 持久化语义

- 每次调用仍是**新进程**（非 PTY），状态经 `<DSH_HOME>/.dsh-bash-state/session-<id>.sh` 恢复/保存；
- 状态文件按 `DSH_SESSION_ID` 会话级隔离（子代理各自独立文件）；
- 安全位：`readonly __DSP_STATE` 防自毒化、`mktemp` 原子写 + `bash -n` 语法校验、24h 懒清扫、路径穿越防护；
- 工具描述补丁让模型直接放心用 `cd`（不再合并命令）。

## 测试

```bash
node --test test/*.test.mjs
# 或显式列出（某些 node 版本目录参数不可靠）：
node --test test/bash-desc-patch.test.mjs test/resolve-state-path.test.mjs
```

覆盖：描述补丁替换语义、状态路径解析（带 `session-` 前缀的真实 id / 裸 UUID / 路径穿越拒绝 / 缺省安全降级）。

## 已知限制与上游

- **每次调用新进程**——真 PTY 持久会话需等官方 win32 终端检查器（P0 建议已提交，见 docs/分析报告）。
- 官方 win32 支持就绪后，移除本 workaround 成本极低：删 `bash-persist-shell` 组 + 描述补丁行 + 两个 mjs 文件，换官方 `dsh-terminal` 组即可（工具名同为 `bash` 无缝衔接）。

## License

MIT。`gitbash-executor-persist.mjs` 改编自 [liceses/dsh-gitbash-preset](https://github.com/liceses/dsh-gitbash-preset)（MIT）；实施与双引擎评审由 Claude（WorkBuddy）+ Codex 完成；`SESSION_ID_RE` 正则修复（`session-` 前缀兼容）与 `bash-desc-patch.mjs` 由 DSH agent 补充。详见 [NOTICE](./NOTICE)。