- Home
- Plugins
- Tools & Capabilities
- dsh-encoding-guard
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-guardREADME
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 时依次尝试的编码,按常用字频率打分选最可信的 |
registerTools | true | 是否注册 3 个 encoded_* 工具 |
hintOnUtf8Failure | true | 官方文件工具报非 UTF-8 错误时追加编码提示 |
shellHint | true | shell 输出含 � 时提示(每会话一次) |
shellToolNames | [bash] | 检查 � 的工具名 |
preserveBom | true | 补回被删掉的 UTF-8 BOM |
preserveCrlfOnWrite | true | write 覆盖 CRLF 文件时保持 CRLF |
mojibakeGuard | deny | 新引入乱码时:deny 拒绝,ask 走审批,off 关闭 |
restrictWritesToWorkspace | true | encoded_edit / encoded_write 只改会话工作目录内的文件 |
maxFileBytes | 8388608 | 读取 / 改写的最大文件大小 |
readLineLimit | 2000 | encoded_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
archify (deepseek-harness)
tt-a1i/archify
WeKnora (dsh-weknora)
tencent/weknora
next-ai-draw-io (dsh-plugin)
dayuanjiang/next-ai-draw-io
weknora
tencent/weknora