lhh010/dsh-bash-encoding

dsh-bash-encoding

简体中文 | English

DSH bash 输出编码自动识别插件：替换 ctx.bash，自管 spawn 收集原始字节，自动检测
UTF-16LE / UTF-8 / GBK 等编码并正确解码，修复 Windows/WSL 下 bash 工具的中文乱码。

版本兼容 / Version compatibility

兼容 DSH snapshot0808（snapshots/20260808T121140Z）与 snapshot0809（snapshots/20260809T140917Z）：宿主侧插件，替换 ctx.bash 执行器，只依赖 bash 缝合线与 ctx.sandbox/ctx.sandboxPolicy 探测面——这些在 0808/0809 上均未变化，typecheck 与实机加载已验证。

npm 发版兼容：兼容 DSH npm 发版 @deepseek-ai/dsh@0.1.1-rc.1（v0.2.0 实机 typecheck/构建/测试通过，适配要点见下节）；旧 0.1.x 版本兼容 @deepseek-ai/dsh@0.0.1-rc.1（即 snapshot0810 的 npm 发版；npx -p @deepseek-ai/dsh@0.0.1-rc.1 dsh web 可访问指定版本并启动，lib 生产模式）。实测（同源本地基线）：npm 基线安装后运行时加载通过，单元测试 26 例中 25 通过（唯一失败为本机 WSL localhost 代理警告混入 stderr 的环境噪音，解码行为本身正确）。

0.1.x 兼容要点（ctx.bash → ctx.shell 缝合线迁移，v0.2.0）

- 缝合线改名：0.1.0 npm 线将 bash 能力从 ctx.bash/@deepseek-ai/dsh-bash 整体迁移到 ctx.shell/@deepseek-ai/dsh-shell——dsh-tool-bash 现在消费 ctx.shell（resolve/run/start/sandboxMode），旧的 @deepseek-ai/dsh-bash 包不再发布，dsh-bash-local 成为 ctx.shell 的本地 provider（LocalBashExecutor extends ShellExecutor）。本插件 v0.2.0 同步迁移：EncodingBashExecutor 改继承 @deepseek-ai/dsh-shell 的 ShellExecutor（super(ctx, "shell") 注册 ctx.shell），spawn/解码/超时/后台生命周期逻辑不变，仍自管 spawn 保留原始字节
- 依赖改名：peer/devDependencies 由 cordis/schemastery/@deepseek-ai/dsh-bash 迁移为 @deepseek-ai/cordis/@deepseek-ai/schemastery/@deepseek-ai/dsh-shell（与官方 0.1.x 包名一致，纯 npm install 不再有 ERESOLVE peer 冲突，无需 --legacy-peer-deps）
- 接入方式变化：同一 context 只允许一个 ctx.shell provider。POSIX/WSL profile 下需替换 @deepseek-ai/dsh-bash-local（而不是旧版的停用 bash-sandbox）；Windows 原生 profile 的 provider 是 pwsh-sandbox（SandboxPwshExecutor 同样注册 ctx.shell），本插件仍按下方「Windows 原生 profile 停用说明」保持停用
- 验证：DSH npm 0.1.1-rc.1 基线 typecheck、构建、26 例单元测试（25 通过 + 1 例本机 WSL 代理警告环境噪音）与 0.1.0-rc.8 之前基线一致；运行加载验证见下节

0809 兼容要点（实机验证）

- 0809 运行中的 dsh web 下，本插件正常替换 ctx.bash（patch 停用 bash-sandbox + 插入本插件的接入方式不变）：每次 bash 调用 stderr 里的 WSL UTF-16LE 代理警告均被正确解码为中文，无乱码——核心修复路径实测有效。
- 0809 保留 bash 缝合线（服务名 ctx.bash 与 BashExecutor 继承面）与 ctx.sandbox/ctx.sandboxPolicy 探测面，插件无需改动、沿用既有 lib/ 构建即可。
- 本插件无客户端 bundle，不受 0809 客户端插件机制（dshClient 声明/ClientPackageCompositionError 启动校验）影响。

Windows 原生 profile 停用说明

在 Windows 原生（无 WSL）profile 下，本插件默认停用（cordis.patch.yml 注释段），原因：

- 平台层 windows.cordis.patch.yml 已插入 pwsh-sandbox（SandboxPwshExecutor），与本插件一样会注册 ctx.shell；同一 context 只允许一个 ctx.shell provider，同时启用会启动失败（重复服务注册）。
- 本插件以 bash -c 方式 spawn，面向 POSIX bash 组合（替换 dsh-bash-local）；Windows 原生 profile 走 pwsh 栈、无 bash runner，本就不适用。

需要时（POSIX/WSL profile，或显式替换 dsh-bash-local）按下方「安装」节接入即可——这是 profile 配置层的停用决定，不是代码弃用。

使用环境（重点）

本插件解决的是 Windows + WSL 组合下的中文乱码，典型触发条件：

| 条件 | 说明 |
|---|---|
| 操作系统 | Windows（DSH 运行在 Windows 侧，bash 经 WSL 执行） |
| WSL 网络模式 | NAT 模式（%UserProfile%\.wslconfig 未设置 networkingMode=mirrored） |
| 代理配置 | 环境变量 HTTP_PROXY / HTTPS_PROXY 指向 localhost |
当以上条件同时满足时，每次执行 bash 命令，wsl.exe 启动器都会向 stderr 输出一条
UTF-16LE 编码的代理警告，而 DSH 核心以 UTF-8 有损解码 → 必现乱码（见下方对比 1）。

附带修复的场景：任何输出非 UTF-8 字节的程序（GBK 中文工具、UTF-16 输出等），
以及 UTF-16LE 警告与命令自身 UTF-8 输出混合在同一管道的情况（最棘手，见对比 2/3）。

问题根因

DSH 核心的 subprocess 层对所有输出执行 Buffer.toString('utf8') 有损解码
（readFrom() 只暴露解码后的文本，原始字节在转换中丢失），于是 UTF-16LE 字节变成
不可恢复的乱码。任何包在 ctx.subprocess 之上的包装都无法修复——因为看到的已经是
乱码文本。本插件绕过该层：自己 spawn 子进程、自己收集原始 Buffer、检测后解码。

效果对比（前后）

对比 1：WSL 代理警告（最典型，每次命令必现）

❌ 修复前（DSH 核心 exec）:
w s l: �hKm0R localhost �NtM�nFOg\��P0R WSL0NAT !j_N�v WSL \rN/e c localhost �Nt

✅ 修复后（本插件）:
wsl: 检测到 localhost 代理配置，但未镜像到 WSL。NAT 模式下的 WSL 不支持 localhost 代理。

对比 2：UTF-16LE 警告 + 命令自身 UTF-8 输出（同一 stderr 管道）

❌ 修复前:
wsl: 检测到 localhost 代理配置
釥戒护鑷: 涓枃鏄剧ず姝ｅ父 hello        ← 命令输出被当作 UTF-16 解

✅ 修复后:
wsl: 检测到 localhost 代理配置
命令自身输出: 中文显示正常 hello

对比 3：ASCII 前缀 + 中文（STDERR: ... 形态）

❌ 修复前:
STDERR: 呓䕄剒›命令自己的错误信息       ← ASCII 前缀被 UTF-16 吞并

✅ 修复后:
STDERR: 命令自己的错误信息

对比 4：GBK 输出（Windows 中文代码页工具）

❌ 修复前（核心 exec 按 UTF-8 解 GBK 字节）:  乱码
✅ 修复后:  GBK编码测试输出

对比 5：长 UTF-16 流跨管道 chunk（8KB 以上必现）

❌ 修复前:  这是一段非常长的UTF-16中文输úQ(uNKm...   ← 管道 chunk 边界处错位
✅ 修复后:  这是一段非常长的UTF-16中文输出用于测试跨chunk解码（完整）

测试场景表（全部通过，26/26）

| # | 场景 | 说明 | 结果 |
|---|---|---|---|
| 1 | WSL 代理警告（stderr，UTF-16LE） | 每次命令必现，最典型场景 | ✅ |
| 2 | 警告 + UTF-8 输出混合流（同管道） | wsl.exe 警告与命令输出合并进同一 buffer | ✅ |
| 3 | ASCII 前缀 + 中文（STDERR: ...） | 大写字母前缀不再被 UTF-16 吞并 | ✅ |
| 4 | GBK 输出 | Windows 中文代码页工具 | ✅ |
| 5 | 长 UTF-16 流跨管道 chunk | 8KB+ 含 ASCII 子串（UTF-16），1024B chunk 切割 | ✅ |
| 6 | 11 字节小 chunk 分片 | 纯中文 UTF-16 流被切成奇数长度小块 | ✅ |
| 7 | 后台任务混合编码 | run_in_background + UTF-16LE/UTF-8 混合 | ✅ |
| 8 | 多段写入混合流 | 警告 + 多次 UTF-8 写入 + 跨 chunk 中文 | ✅ |
| 9 | 纯 ASCII 输出 | hello world 不被误判 UTF-16 | ✅ |
| 10 | 纯 UTF-8 中文长输出 | 50 行中文无回归 | ✅ |
| 11 | 中英混排输出 | hello world 你好世界 | ✅ |
| 12 | UTF-16 尾字节跨 chunk | 半个 code unit 正确配对 | ✅ |
| 13 | 单元测试 | 解码内核：BOM/NUL 启发式/严格 UTF-8/GBK/GB18030 | ✅ |
| 14 | 执行器端到端 | 真实 spawn：exit code/stdin/超时/后台/spawn 失败 | ✅ |

安装

在插件目录安装依赖（DSH 需要 Node ^22.19 || >=24）
cd /path/to/dsh-bash-encoding && pnpm install && pnpm build

将插件接入 DSH web profile（与 dsh-shell-windows 等外部插件同样的方式）：

cd "${DSH_HOME:-$HOME/.dsh}/profiles/web"
pnpm add -w link:/path/to/dsh-bash-encoding

配置

在 profile 的 cordis.yml（或 cordis.patch.yml）中替换 shell 条目
（@deepseek-ai/dsh-bash-local 被本插件替代——v0.2.0 起本插件与
dsh-bash-local 都注册 ctx.shell，同一 context 只能有一个 provider）：

... 原有其他条目不变 ...
- id: bash
name: '@dsh-external/dsh-bash-encoding'
config:
cwd: null            # 默认工作目录（默认 process.cwd()）
timeoutMs: 120000    # 前台命令默认超时
maxTimeoutMs: 600000 # 单次超时上限
maxOutputBytes: 65536  # 每流输出上限（超限截断并标记 lossy）
graceMs: 3000        # SIGTERM→SIGKILL 宽限期

注意（patch 文件）：patch 的 name 字段只做校验、不能替换插件。若通过
cordis.patch.yml 接入，需先 disabled: true 停用原 bash 条目，再 insert 本插件。
重启 dsh web 后生效。bash 工具、后台任务、hooks 桥的所有输出都自动经过编码检测。

编码检测顺序

1. 纯 ASCII 快速路径（无高字节 → UTF-8，避免 ASCII 字母误判 UTF-16）
2. BOM：UTF-8 (EF BB BF) / UTF-16LE (FF FE) / UTF-16BE (FE FF)
3. UTF-16 段检测（流式、chunk 内分段）：
- NUL 奇偶位锚定（ASCII 子段，如 wsl: ）
- CJK 高字节优势锚定（纯中文段）
- 段内信任延伸 + 连续 4 个可打印 ASCII code unit 回退断段（区分 STDERR 与 个/片）
- UTF-8 三字节签名硬断（lead + 双续字节）
4. 严格 UTF-8 校验（fatal decoder）通过 → UTF-8
5. GBK，再 GB18030（Windows 中文 OEM 代码页 936/54936 的兜底）
6. Latin-1 最后兜底（永不失败）

验证

pnpm test   # 26 个用例：解码内核 + 真实 spawn 端到端（UTF-16LE/GBK/混合流/超时/后台/失败路径）

范围与限制

| 面 | 状态 | 说明 |
|---|---|---|
| bash 工具输出（Web/TUI/hooks/后台） | ✅ 修复 | 替换 ctx.bash 后所有下游自动受益 |
| 沙箱兼容 | ✅ 支持 | 运行时探测 ctx.sandbox/ctx.sandboxPolicy，非 full-access 走 confine 路径，sandboxMode 惰性读取 |
| read 工具读 GBK/UTF-16 文件 | ⏳ 路线图 v2 | FileSystem 是抽象 seam；需包装 readText 且保留沙箱链 |
| node-pty 交互终端（tool-pty / dsh-web-terminal） | ❌ 不可修复 | node-pty 内部已按 UTF-8 有损解码，插件层拿不到原始字节 |
| subprocess 核心层 | ❌ 不改动 | 基础服务替换风险大，不做 |

其他说明：

- 环境净化：继承环境中 DSH_ 前缀与名称含 KEY/PASSWORD/SECRET/TOKEN 的变量会被
清除（对齐 subprocess seam 的 hygiene），托管变量经 dshEnv 显式传入。
- 大输出：超过 maxOutputBytes 保留头部并标记 lossy（不做 spill 文件）。
- 治本建议（可选，与插件互补）：将 .wslconfig 的 networkingMode 改为 mirrored，
或设置 WSL_UTF8=1，可从源头消除 WSL 警告本身的输出。
- run_code / pwsh 路径不在插件覆盖范围：本插件只替换 bash 工具背后的 ctx.shell provider。
Windows 原生 profile 下经由 pwsh（含 run_code 的 pwsh 执行器）调用 wsl.exe 产生的同款 UTF-16LE
警告乱码，插件无法拦截（那是 code-runtime/pwsh 栈的输出解码）。实测有效做法：在命令里前置
WSL_UTF8=1（如 WSL_UTF8=1 wsl -e bash -c '...'，wsl.exe 官方支持，警告改以 UTF-8 输出，
pwsh 捕获后即为正常中文），或改用 .wslconfig 镜像模式从根上消除该警告。

结构

src/decode-core.ts   # 编码检测内核（ChunkDecoder 流式分段解码）：纯函数、零依赖、可独立测试
src/executor.ts      # EncodingBashExecutor（extends ShellExecutor）：自管 spawn + 原始字节 + 检测解码
src/index.ts         # 插件入口（schemastery Config）
tests/               # node:test 单元 + 端到端

更新记录 / Changelog

2026-08-20 · v0.2.0 — 迁移到 ctx.shell 缝合线（DSH 0.1.x）

- 迁移：EncodingBashExecutor 由继承 @deepseek-ai/dsh-bash 的 BashExecutor（注册 ctx.bash）改为继承 @deepseek-ai/dsh-shell 的 ShellExecutor（注册 ctx.shell）——0.1.0 npm 线把 bash 能力整体迁移到 ctx.shell，dsh-tool-bash 只消费新缝合线；spawn/编码解码/超时/后台生命周期逻辑不变
- 依赖：peer/devDependencies 迁移为 @deepseek-ai/dsh-shell + @deepseek-ai/cordis + @deepseek-ai/schemastery（官方 0.1.x 包名，纯 npm install 无 ERESOLVE）
- 接入：POSIX/WSL profile 下改为替换 @deepseek-ai/dsh-bash-local（同为 ctx.shell provider）；Windows 原生 profile 保持停用
- 验证：DSH npm 0.1.1-rc.1 基线 typecheck、构建、26 例单测（25 通过 + 1 例本机 WSL 代理警告环境噪音，解码行为正确）

许可

BSD-3-Clause