编码修复 Lostforest7/dsh-encoding

dsh-encoding

为 DeepSeek Harness 提供的正确编码命令运行器与乱码恢复工具。

让 DeepSeek Harness 在 Windows 上不再乱码。

English / 中文

dsh-encoding 是 DeepSeek Harness (dsh) 的一个轻量工具插件。在中文 Windows 上，旧版 CLI、Git Bash/MSYS2 和 PowerShell 5.1 常常输出 GBK (cp936) 或 UTF-16LE 字节，而 dsh 内置的 bash/pwsh 工具会将其按 UTF-8 解码，从而显示为乱码。解码发生在不可插拔的核心服务（dsh-subprocess-local）内部，因此本插件不会尝试修补它。相反，它新增了两个互补的工具：

| 工具 | 功能 |
| encoding_run | 启动自己的子进程，捕获 stdout/stderr 的原始字节，自动检测 UTF-8 / UTF-16LE / GBK 并正确解码。 |
| encoding_decode | 将已经乱码的文本（例如被误读为 latin1 的 GBK 字节）恢复为正确的中文。 |

0.2.0 破坏性变更： 工具名称已从 run/decode_text 重命名为 encoding_run/encoding_decode（防冲突前缀）。0.1.0 在 npm 上已弃用。

与官方内置工具的关系（已在 dsh 0.2.0-rc.2 上验证）

- dsh 0.2.0 不内置 run / decode_text 工具。已通过一个干净、无插件的配置（dsh --profile pmaudit --dump-config）验证：基础配置中不包含此类工具行（内置工具为 tool-bash、tool-pwsh、tool-fs 等），官方工具参考文档中也未提及。
- 内置的 bash/pwsh 工具仍然没有编码配置——shell 接缝的 ShellExecRequest 没有编码字段——并且在此环境中，通过内置 pwsh 工具执行产生 GBK 的命令仍然返回乱码。因此本插件的前提依然成立。
- 工具名称带有前缀，因此不会与内置或未来的 dsh 工具冲突：注册表会拒绝同一层内的重复项以及保留的 run_code 名称（官方 tools.md）。

安装

从 npm 安装：

dsh plugin --profile add dsh-encoding

从本地检出（本仓库）安装：

dsh plugin --profile add ./dsh-encoding

从 GitHub 安装（无需构建授权即可使用，因为该包是纯 ESM JavaScript，没有构建步骤）：

dsh plugin --profile add github:Lostforest7/dsh-encoding

验证该层已激活，然后启动：

dsh --profile --dump-config # 显示 "# == dsh-encoding" 层
dsh --profile

工具：encoding_run

| 参数 | 类型 | 必填 | 默认值 | 描述 |
| command | string | 是 | — | 要执行的命令行（Windows：cmd /d /s /c，POSIX：/bin/bash -c）。 |
| workdir | string | 否 | — | 子进程的工作目录。 |
| timeoutMs | number | 否 | 120000 | 超时时间；到期时会终止整个进程树。 |
| encoding | string | 否 | auto | auto（检测）或强制指定 utf-8 / utf-16le / gbk。 |
Windows 上的 GBK 输出示例：

[stderr]
... (if any stderr)
[encoding: gbk/utf-8 (auto-detected)]
[exit code: 0]

最后一行始终是 [exit code: N]。当输出包含 U+FFFD（�）时，会追加一条明确的警告行，而不是默默假装解码是正确的。

定位，直白地说： encoding_run 是一个独立的新工具。它没有内置 bash 工具的沙箱、审批或后台任务支持，并且以与 harness 进程相同的权限执行。

工具：encoding_decode

| 参数 | 类型 | 必需 | 默认值 | 描述 |
| text | string | 是 | — | 要恢复的乱码文本。 |
| from | string | 否 | auto | 如何将字符转回字节：latin1 / utf-16le / auto。 |
| to | string | 否 | auto | 目标解码：gbk / utf-16le / auto。 |

经典的乱码路径是 from=latin1, to=gbk：GBK 字节被误读为 latin1（每个字节对应一个字符），因此该工具将每个字符重新编码为一个字节，再将这些字节按 GBK 解码。

使用 auto 时，方向会被猜测：内嵌 NUL → latin1 → utf-16le；宽字符 → utf-16le → gbk；其他所有情况 → 经典的 latin1 → gbk。

不可逆的情况会被报告，绝不伪造： 如果输入已包含 U+FFFD（�）——即 shell 已因先前的错误解码而破坏了字节——结果为 ok: false 并附有明确说明。

注意：from=gbk 会被拒绝并给出清晰解释。Node.js 自带 GBK 解码器（TextDecoder），但没有 GBK 编码器，而此插件是零依赖的，因此无法将字符重新编码回 GBK 字节。to=gbk 完全受支持。

30 秒示例

内置 bash 在期望 中文 的地方显示 ÖÐÎÄ（GBK 字节被当作 latin1 读取）：

1. 让 agent 使用 encoding_decode 并传入 {"text": "ÖÐÎÄ"} → 中文 —— 完成。
2. 或者用正确的解码重新运行命令：使用 encoding_run 并传入 {"command": "chcp 936 >nul & echo 中文"} → 输出 中文 以及 [encoding: gbk (auto-detected)] [exit code: 0]。

CLI 冒烟测试（无需 DSH）

CLI 子命令保留其短名称（run / decode_text）——它们是开发用冒烟运行器，而非注册的工具名称：

node src/cli.js decode_text "ÖÐÎÄ" # -> 中文
node src/cli.js run "chcp 936 >nul & echo 中文" # GBK output, auto-decoded
node src/cli.js run "echo hello"
node src/cli.js detect D6D0CEC4 # -> detected: gbk / decoded: 中文

开发

零依赖——运行时没有，开发时也没有；测试仅使用 Node 内置模块（node:test、node:assert）。无需 npm install，无需 DSH，无需构建步骤：

node --test test/

架构：

dsh-encoding/
├── package.json # type: module, dsh.bundle.patch -> cordis.patch.yml
├── cordis.patch.yml # inserts one loader row: id "encoding", name "dsh-encoding"
├── src/index.js # Cordis 入口（无依赖），注册 encoding_run + encoding_decode ├── src/encoding.js # 纯函数：detect / decode / mojibake 恢复 ├── src/exec.js # spawn 包装器 + 运行格式化（spawnImpl 可注入） ├── src/cli.js # 手动冒烟运行器（无需 DSH） └── test/ # node:test 测试套件，模拟 child_process.spawn

src/encoding.js 和 src/exec.js 不从 @deepseek-ai/ 导入任何内容。src/index.js 同样无依赖：它直接生成注册表就绪的工具形态（与官方 defineTool 编译成的 {type:'object', properties, required} + output.schema/render 形式相同——由 test/index.test.js 中的字面 schema 断言锁定，并被实时的 0.2.0-rc.2 注册表接受）。这是有意为之——当插件作为本地检出安装时（dsh plugin add ./path，即 pnpm link），包位于 profile 树之外，Node 的 ESM 解析器无法从检出目录访问宿主的 @deepseek-ai/ 包（导入会以 ERR_MODULE_NOT_FOUND 失败，已在 0.2.0-rc.2 上验证）。直接生成注册表形态可让插件在 npm、git 和本地链接安装下都能正常工作。

已知限制

- 不替换也不修复内置的 bash/pwsh 工具、ctx.shell 或 dsh-subprocess-local——这些按设计不在范围内（版本脆弱的核心工作）。本插件是一种补充，并且明确说明这一点。
- encoding_run 没有沙箱 / 审批 / 后台任务集成。
- 编码检测是启发式的（UTF-8 有效性、UTF-16LE NUL 模式、GBK 高字节比例、BOM）。存在歧义情况——例如无 BOM 的纯 CJK UTF-16LE 与 GBK——所以当你知道答案时请强制指定 encoding。
- 输入中的 U+FFFD 是已被破坏的信息；恢复是不可能的，并会如实报告。
- 每个流的输出上限为 8 MiB；超时时会杀死进程树（Windows：taskkill /T /F，POSIX：进程组 SIGKILL）。

发布清单

- [x] 带有 dsh-plugin 主题的 GitHub 仓库——Lostforest7/dsh-encoding
- [x] npm 名称 dsh-encoding（当时未被占用；已发布 0.1.0 → 0.2.0）
- [x] npm publish --registry=https://registry.npmjs.org（中国镜像为只读；始终针对官方注册表发布）
- [ ] 提交到 awesome-dsh-plugin 列表和 dsh-plugin.org 市场（可选，尚未完成）

dsh-encoding 是 DeepSeek Harness（dsh）的一个薄工具插件。在中文 Windows 上，老式 CLI、Git Bash/MSYS2、PowerShell 5.1 经常输出 GBK（cp936）或 UTF-16LE 字节，被 dsh 内置的 bash/pwsh 工具按 UTF-8 解码后变成乱码；而解码发生在不可插拔的核心服务（dsh-subprocess-local）里。本插件不去修补内置 bash，而是新增两个补充工具：

| 工具 | 作用 |
| encoding_run | 自己 spawn 子进程、按原始字节收 stdout/stderr，自动识别 UTF-8 / UTF-16LE / GBK 并正确解码。 |
| encoding_decode | 把已经乱码的文本（如 GBK 字节被当 latin1 误读）还原成正确中文。 |
0.2.0 破坏性变更：工具名由 run/decode_text 改为 encoding_run/encoding_decode（防撞名前缀）。0.1.0 已在 npm 标记废弃。

与官方内置工具的关系（在 dsh 0.2.0-rc.2 上实测）

- dsh 0.2.0 没有内置 run / decode_text 工具。用干净的、未装插件的临时 profile（dsh --profile pmaudit --dump-config）验证：base 配置中没有任何同名工具行（内置工具是 tool-bash、tool-pwsh、tool-fs 等），官方 tools 参考文档也没有这两个工具。
- 内置 bash/pwsh 依然没有编码配置（shell 接口的 ShellExecRequest 无编码字段）；在本环境用内置 pwsh 工具跑 GBK 输出命令，结果仍是乱码。本插件的立论前提成立。
- 工具名加了 encoding_ 前缀，避免与内置或未来 dsh 工具撞名——注册表会拒绝同层重复名与保留名 run_code（官方 tools.md）。

安装

从 npm：

dsh plugin --profile add dsh-encoding

从本地目录（本仓库）：

dsh plugin --profile add ./dsh-encoding

从 GitHub（纯 ESM JavaScript、无构建步骤，不需要 prepare 构建授权）：

dsh plugin --profile add github:Lostforest7/dsh-encoding

验证配置层已生效，然后启动：

dsh --profile --dump-config # 能看到 "# == dsh-encoding" 层
dsh --profile

工具 encoding_run

| 参数 | 类型 | 必填 | 默认 | 说明 |
| command | string | 是 | — | 要执行的命令（Windows：cmd /d /s /c；POSIX：/bin/bash -c）。 |
| workdir | string | 否 | — | 子进程工作目录。 |
| timeoutMs | number | 否 | 120000 | 超时毫秒数，到期后杀掉整个进程树。 |
| encoding | string | 否 | auto | auto 自动检测，或强制 utf-8 / utf-16le / gbk。 |

输出示例（Windows 上的 GBK 输出）：

[stderr]
...（如有 stderr） [encoding: gbk/utf-8 (auto-detected)] [exit code: 0]

最后一行固定是 [exit code: N]。当输出含 U+FFFD（�）时，会附加明确的警告行，而不是假装解码正确。

定位如实说明：encoding_run 是一个独立的新工具，不带内置 bash 工具的沙箱、审批与后台任务能力，并以 dsh 进程自身的权限执行命令。

工具 encoding_decode

| 参数 | 类型 | 必填 | 默认 | 说明 |
| text | string | 是 | — | 要还原的乱码文本。 |
| from | string | 否 | auto | 字符还原成字节的方式：latin1 / utf-16le / auto。 |
| to | string | 否 | auto | 目标解码：gbk / utf-16le / auto。 |

经典"乱码还原"路径是 from=latin1, to=gbk：GBK 字节被当 latin1 误读（一个字符一个字节），工具把每个字符还原成一个字节，再按 GBK 解码。

auto 模式下自动判断误读方向：文本含 NUL → latin1 → utf-16le；含宽字符 → utf-16le → gbk；其余 → 经典 latin1 → gbk。

不可逆情况明确说明、不伪造结果：若输入里已经含 U+FFFD（�）——即字节早已在上游误解码中被毁掉——返回 ok: false 并附说明。

注意：from=gbk 会被明确拒绝并解释原因——Node.js 内置了 GBK 解码器（TextDecoder）但没有 GBK 编码器，本插件又坚持零依赖，因此无法把字符重新编码回 GBK 字节。to=gbk 完全支持。

30 秒示例

内置 bash 把 中文 显示成了 ÖÐÎÄ（GBK 字节被当 latin1 读）：

1. 让 agent 调用 encoding_decode，参数 {"text": "ÖÐÎÄ"} → 得到 中文，完成。
2. 或者重新执行命令并按正确编码解码：调用 encoding_run，参数 {"command": "chcp 936 >nul & echo 中文"} → 输出 中文，并附 [encoding: gbk (auto-detected)] [exit code: 0]。

CLI 手动冒烟（无需 DSH）

CLI 子命令保留短名（run / decode_text）——它们只是开发冒烟入口，不是注册的工具名：

node src/cli.js decode_text "ÖÐÎÄ" # -> 中文
node src/cli.js run "chcp 936 >nul & echo 中文" # GBK 输出自动解码
node src/cli.js run "echo hello"
node src/cli.js detect D6D0CEC4 # -> detected: gbk / decoded: 中文

本地测试

零依赖——运行时与开发时都没有任何依赖；测试只用 Node 内置的 node:test / node:assert，无需 npm install、无需 DSH、无需构建：

node --test test/

结构：

dsh-encoding/
├── package.json # type: module，dsh.bundle.patch -> cordis.patch.yml ├── cordis.patch.yml # 插入一行 loader：id "encoding"，name "dsh-encoding" ├── src/index.js # Cordis 入口（零依赖），注册 encoding_run 与 encoding_decode ├── src/encoding.js # 纯函数：检测 / 解码 / 乱码还原 ├── src/exec.js # spawn 封装 + run 输出组装（spawnImpl 可注入） ├── src/cli.js # 手动冒烟（无需 DSH） └── test/ # node:test 套件，mock child_process.spawn

src/encoding.js 与 src/exec.js 不 import 任何 @deepseek-ai/；src/index.js 同样零依赖：它直接输出注册表形态的工具定义（与官方 defineTool 编译产物一致的 {type:'object', properties, required} + output.schema/render，由 test/index.test.js 的字面 schema 断言锁定，并已被 0.2.0-rc.2 真实注册表接受）。这是刻意的——当插件以本地目录方式安装（dsh plugin add ./path，即 pnpm link）时，包位于 profile 树之外，Node 的 ESM 解析无法从插件目录找到宿主的 @deepseek-ai/ 包（会以 ERR_MODULE_NOT_FOUND 失败，已在 0.2.0-rc.2 实测）。直接输出注册形态让插件在 npm、git、本地 link 三种安装方式下都能工作。

已知限制

- 不替换、不修复内置 bash/pwsh、ctx.shell、dsh-subprocess-local——刻意超出范围（核心层改动版本脆弱）。本插件定位为"补充工具"。
- encoding_run 无沙箱集成、无审批、无后台任务。
- 编码检测是启发式的（UTF-8 合法性、UTF-16LE NUL 模式、GBK 高位字节占比、BOM）。存在歧义场景——例如无 BOM 的纯中文 UTF-16LE 与 GBK 难以区分——已知编码时请用 encoding 参数强制指定。
- 输入中已有的 U+FFFD 属于已丢失的信息，无法还原，并会如实报告。
- 每路输出上限 8 MiB；超时杀进程树（Windows：taskkill /T /F；POSIX：进程组 SIGKILL）。

发布清单

- [x] GitHub 仓库已建并带 topic dsh-plugin：Lostforest7/dsh-encoding
- [x] npm 名 dsh-encoding（确认未占用；已发布 0.1.0 → 0.2.0）
- [x] npm publish --registry=https://registry.npmjs.org（国内镜像只读，务必用官方 registry 发布）
- [ ] 提交到 awesome-dsh-plugin 列表与 dsh-plugin.org 市场（可选，尚未完成）

许可证

MIT — 见 LICENSE。