Skip to main content
Q

dsh-encoding-guard

qinghuidaqzp/dsh-encoding-guard

Reads and edits GBK/GB18030, Big5, Shift_JIS, EUC-KR and UTF-16 files in their own encoding with encoded_read, encoded_edit and encoded_write; restores the UTF-8 BOM that edit, write and apply_patch drop and keeps CRLF files CRLF on write; appends the detected encoding to invalid-UTF-8 errors; and denies writes that introduce mojibake (U+FFFD, 锟斤拷, UTF-8 read as GBK or Latin-1).

Install

dsh plugin --profile web add github:qinghuidaqzp/dsh-encoding-guard

README

dsh-encoding-guard · 编码守卫

English | 中文

DeepSeek Harness(dsh)插件:让 Agent 改文件时不再弄坏文件编码。

解决什么问题

在 dsh 0.2.2-rc.1 上实测,官方文件工具有三处会伤到非 UTF-8 / Windows 项目:

场景官方工具的行为装了本插件之后
读写 GBK / Big5 / Shift_JIS / EUC-KR / UTF-16 文件read 只报 invalid UTF-8 text,Agent 往往改用 shell 处理,文件被转成 UTF-8 或写进乱码报错里直接写明检测到的编码;encoded_read / encoded_edit / encoded_write 按原编码读写,字节级保持
编辑带 UTF-8 BOM 的文件(C#、VS 的 C++ 源码、PowerShell 5 脚本、给 Excel 的 CSV)edit / write / apply_patch 会把 BOM 删掉修改后自动补回 BOM
用 write 整体覆盖 CRLF 文件文件被改成 LF,git diff 显示每一行都变了自动保持 CRLF

另外它会拦截写入乱码:如果要写入的新内容里出现 �(U+FFFD)、锟斤拷/烫烫烫、UTF-8 被当成 GBK 解出来的 涓枃娉ㄩ噴、或 UTF-8 被当成 Latin-1 的 é/’,并且这些内容是这次修改新引入的,就拒绝写入(可改成弹审批或关闭)。

功能

3 个工具(模型可调用)

  • encoded_read:读取非 UTF-8 或带 BOM 的文本文件,返回带行号的内容,并报告编码、BOM、换行符。可用 encoding 参数强制指定编码。
  • encoded_edit:在 encoded_read 读过的文件上做字面替换,按原编码、原 BOM、原换行符写回。文件在读取之后被改动过、old_string 找不到或匹配多处时会拒绝。新内容里有目标编码存不下的字符(比如往 GBK 文件里写 emoji)时报错,不会写成 ?。
  • encoded_write:整文件创建或覆盖。已有文件默认沿用原编码 / BOM / 换行符;新文件需要指定 encoding。

4 项自动行为(通过 tools/pre-execute、tools/post-execute 钩子实现,不需要模型配合)

  • read / edit / write / apply_patch 因非 UTF-8 失败时,在错误后附一行提示,写明编码(例如 GBK, CRLF line endings)并指向 encoded_* 工具。
  • edit / write / apply_patch 成功后补回被删掉的 UTF-8 BOM;write 覆盖 CRLF 文件时保持 CRLF。修复后会把新的文件版本登记给官方的“先读后写”策略,下一次 edit 不会因为版本变化而失败。
  • 乱码拦截,覆盖 edit / write / apply_patch / encoded_edit / encoded_write。
  • bash 输出里出现 3 个以上 � 时,每个会话提示一次“这多半是 GBK/Big5 文本,请用 encoded_read”。

支持的编码:UTF-8(含 BOM)、GBK、GB18030、Big5、Shift_JIS、EUC-JP、EUC-KR、UTF-16LE/BE(含无 BOM 的检测)。

安装

需要 dsh ≥ 0.2.0。

从 GitHub 安装(本插件是纯 JavaScript,不需要构建,也不需要 allowBuilds 授权):

dsh plugin --profile web add github:qinghuidaqzp/dsh-encoding-guard

或从 npm 安装(发布到 npm 之后):

dsh plugin --profile web add dsh-encoding-guard

headless、tui 等其他 profile 把 web 换掉即可。确认已加载:

dsh --profile web --dump-config | grep -A3 encoding-guard

配置

在 profile 的 cordis.patch.yml($DSH_HOME/profiles/<名字>/cordis.patch.yml)里覆盖。patch 会整体替换 config,没写的键回到下表的默认值:

- id: encoding-guard
  config:
    candidates: [big5, gbk, shift_jis, euc-kr]   # 繁体项目把 big5 放前面
    mojibakeGuard: ask                           # deny | ask | off
键默认值说明
candidates[gbk, big5, shift_jis, euc-kr]文件不是 UTF-8 时依次尝试的编码,按常用字频率打分选最可信的
registerToolstrue是否注册 3 个 encoded_* 工具
hintOnUtf8Failuretrue官方文件工具报非 UTF-8 错误时追加编码提示
shellHinttrueshell 输出含 � 时提示(每会话一次)
shellToolNames[bash]检查 � 的工具名
preserveBomtrue补回被删掉的 UTF-8 BOM
preserveCrlfOnWritetruewrite 覆盖 CRLF 文件时保持 CRLF
mojibakeGuarddeny新引入乱码时:deny 拒绝,ask 走审批,off 关闭
restrictWritesToWorkspacetrueencoded_edit / encoded_write 只改会话工作目录内的文件
maxFileBytes8388608读取 / 改写的最大文件大小
readLineLimit2000encoded_read 默认返回行数

限制

  • 编码检测是启发式的:对很短、或几乎没有中日韩文字的文件,可能给出低置信度结果(输出里会标明 low confidence),这时用 encoding 参数指定。
  • encoded_edit / encoded_write 直接写本机磁盘(dsh 的文件接口只支持 UTF-8 文本写入),所以只支持本地文件系统,不支持 SSH 等远程后端;写入前会确认文件和 encoded_read 读到的字节一致。它们不经过 dsh 的沙箱后端,因此默认只允许写会话工作目录内的文件。
  • BOM / CRLF 的修复只针对官方 dsh-tool-fs 的 edit / write / apply_patch;shell 命令(sed -i、重定向等)造成的改动不在范围内。
  • 乱码拦截只看“这次修改新增的”信号;文件里本来就有的乱码不会导致拦截。

开发与测试

npm install
npm test

集成测试使用真实的 dsh 工具管线(官方 dsh-tools、dsh-fs-local、dsh-tool-fs、dsh-fs-observation-policy):

mkdir dsh-it && cd dsh-it && npm init -y && npm i @deepseek-ai/dsh
cp -R ../dsh-encoding-guard node_modules/dsh-encoding-guard
cd node_modules/dsh-encoding-guard && npm run test:integration

许可证

MIT

Related plugins