前言¶
DeepSeek Harness (DSH) 的原生文件工具（read / write / edit）只认 UTF-8。在处理中文 GBK、日文 Shift-JIS、韩文 EUC-KR，或带 BOM 的文件时，AI 往往直接报错无法读取，或者在修改后导致文件编码损坏、BOM 被丢失。本插件接管这些工具，在保留原有沙箱围栏、读后写保护等机制的前提下，按原编码读写文件，解决 AI 读写多字节编码文件时的静默损坏问题。
这是什么¶
这是 mrweicodes/dsh-fs-encoding，由 MrWeiCodes 维护的 DSH 插件，属于模型推理工具类。
它的核心价值是：让 AI 读写 GBK 等非 UTF-8 文件和带 BOM 的文件时不会弄坏编码。插件通过字节级保真、BOM 保真和换行符保真，确保文件在读写过程中保持原有的编码特征。
核心功能¶
- 字节级保真：按原编码读写文件，不转 UTF-8。
- BOM 保真：精确还原或绝不添加 BOM。
- 换行符保真：CRLF / LF / CR 识别与还原。
- 绝不静默损坏：无法表示的字符拒绝写入。
- 智能识别：读不了时会列出候选编码供选择，而不是直接报错。
- 广泛支持：支持 GBK、Big5、Shift-JIS、EUC-KR、Windows-125x 等 19 种编码。
- 零学习成本：直接替换原生
read/write/edit工具，参数和返回格式与原版一致。 - 指定编码新建：
write支持encoding参数，用于新建指定编码的文件。 - 额外工具：提供
insert、undo_last_edit和str_replace_editor三个工具。
安装与启用¶
使用官方提供的安装命令即可完成启用：
dsh plugin --profile web add dsh-fs-encoding
安装完成后，插件会自动覆盖原生工具，无需额外配置。
典型用法¶
插件接管了原生工具，调用方式与原版基本一致，主要区别在于显式指定编码。
读取非 UTF-8 文件¶
对于 GBK 等非 UTF-8 文件，需要显式传入 encoding 参数：
read({ file_path: "legacy.txt", encoding: "gbk" })
写入指定编码的文件¶
新建文件时，使用 encoding 参数指定编码（如 GBK）：
write({ file_path: "run.bat", content: "echo 中文\r\n", encoding: "gbk" })
新增工具¶
插件额外提供了三个工具：
insert：按行号插入字符串（原生不支持）。
insert({ file_path: "config.ini", insert_line: 0, new_string: "[core]" })
undo_last_edit：撤销上一次编辑，内容与编码一并还原。
undo_last_edit({ file_path: "config.ini" })
str_replace_editor：兼容层工具，支持view、create、str_replace、insert、undo_edit等子命令。
注意事项¶
- 工具冲突：与在同一层注册同名工具的插件互斥（如
read/write/edit/insert/str_replace_editor/undo_last_edit）。 - encoding 参数限制：
encoding只对新建文件有效。文件已存在时，直接传入encoding会报错，插件不会转换已有文件的编码。 - Windows 跨盘符问题：在 Windows 上，若插件目录与 profile 不在同一盘符，安装会失败。
- 撤销限制：
undo_last_edit只保留最近一次编辑，不写磁盘，DSH 重启后无法撤销。 - 许可证：MIT License。
总结¶
dsh-fs-encoding 通过精确控制文件读写过程，解决了 DSH 在处理多字节编码文件时的痛点。它适合需要维护遗留系统、处理国际化文件或保证代码库编码一致性的场景。
