encoding-aware-fs

encoding-aware-fs

面向 AI 编码工具（Claude Code、OpenCode 等）的编码感知文件操作 MCP 服务器，专为处理 GB18030/GBK/GB2312 编码项目而设计。

问题背景

AI 编码助手默认所有文件都是 UTF-8 编码，在读写 GB18030/GBK/GB2312 编码的文件时会导致静默乱码——这在中文遗留项目中非常常见。本 MCP 服务器透明地处理编码检测与转换，让 AI 工具能正确操作非 UTF-8 文件。

功能特性

• 自动编码检测 — 读取文件时自动识别原始编码（GB18030/GBK/GB2312），返回 UTF-8 给 AI 工具
• 透明回写 — 写入时自动将 UTF-8 内容转换回文件的原始编码
• 行尾保持 — 检测并保持文件原有的 CRLF/LF 行尾格式，编辑后不会改变
• 目录级编码规则 — 通过 glob 模式为不同目录指定不同编码（如 openspec/** 用 UTF-8，legacy/** 用 GBK）
• 三个 MCP 工具：read_file、write_file、edit_file — 替代内置文件操作工具
• 一键安装/卸载 — 支持 Claude Code 和 OpenCode，交互式配置编码规则

安装

npx encoding-aware-fs install

该命令会在项目的 .mcp.json（Claude Code）、.opencode.json（OpenCode）或 .codex/config.toml（Codex）中注册 MCP 服务器，并添加规则文件指示 AI 使用 MCP 工具进行所有文件操作。

卸载

npx encoding-aware-fs uninstall

MCP 工具

工具	说明
read_file	读取文件，自动检测编码并返回 UTF-8 内容
write_file	写入 UTF-8 内容，自动转换为文件原始编码
edit_file	查找替换编辑，保持编码和行尾格式
grep	搜索文件，自动处理编码转换，支持中文 GB18030 搜索

工作原理

1. 读取时：通过 BOM 和启发式算法检测文件编码，解码为 UTF-8 返回
2. 写入/编辑时：先读取原文件检测编码和行尾风格，在 UTF-8 下完成操作，写入前转回原编码并还原行尾格式

项目配置

项目根目录的 .encoding-converter.json 控制编码行为：

{
  "sourceEncoding": "GB18030",
  "confidenceThreshold": 0.8,
  "overrides": [
    { "pattern": "openspec/**", "sourceEncoding": "UTF-8" },
    { "pattern": "legacy/**", "sourceEncoding": "GBK" }
  ]
}

• sourceEncoding：检测不确定时的默认编码，也用于新建文件
• confidenceThreshold：自动检测的最小置信度（0-1）
• overrides：可选的目录级编码规则数组，每条规则包含 pattern（glob 模式）和 sourceEncoding；多个规则匹配时，最具体的模式优先

开发

npm install
npm run build
npm test

许可证

MIT