encoding-vfs
skyispainted/encoding-vfs
Converte codificações legadas para UTF-8 via VFS — zero config para ferramentas de IA
Ver no GitHubPlugin que monta projetos com codificação legada (GBK, Shift_JIS, Big5) como unidades virtuais UTF-8, permitindo que ferramentas de IA como Claude Code leiam texto limpo sem configuração. Funciona transparentemente no nível do sistema operacional, convertendo automaticamente na leitura e escrita.
Instalação
npx convez-ai skyispainted/encoding-vfs1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Trabalhar com projetos antigos em GBK/Shift_JIS/Big5 em Claude Code ou VS Code
- Integrar arquivos legados com ferramentas modernas que esperam UTF-8
- Eliminar garbled text ao usar terminais e AI CLI tools com projetos asiáticos
Veredito

Solução técnica sólida para um problema real em projetos legados asiáticos. Implementação em Rust garante performance; suporte multi-plataforma (Windows/Linux) e detecção automática de encoding são pontos fortes. Ideal para times que mantêm bases de código antigas.
README
A tradução para o português deste README ainda está na fila.
encoding-vfs
现代开发工具默认使用 UTF-8,但老项目中的文件常使用 GBK、Shift_JIS、Big5 等编码,在 IDE、终端和 AI 编码工具中显示为乱码或无法解析。encoding-vfs 通过挂载虚拟驱动器在系统层面透明解决此问题:
- 读取自动转换 — 将遗留编码文件自动转为 UTF-8,应用看到干净的文本
- 写入自动还原 — 将 UTF-8 内容转回文件原始编码写入磁盘
- 零侵入 — 无需修改文件、无需 IDE 插件、无需手动配置
- 任意应用可用 — 挂载后 Claude Code、VS Code、
cat等均可直接使用
Modern tools default to UTF-8, but legacy project files often use GBK, Shift_JIS, Big5, or other encodings that render as garbled text or fail to parse in IDEs, terminals, and AI coding tools. encoding-vfs solves this transparently by mounting a virtual drive at the system level:
- Automatic read conversion — legacy-encoded files appear as clean UTF-8 to any application
- Automatic write restore — UTF-8 content is converted back to the file's original encoding on disk
- Zero intrusion — no file modification, no IDE plugins, no manual configuration needed
- Works with any app — Claude Code, VS Code,
cat, and any other tool works directly on the mounted drive
Quick Start
Windows
# 1. Install WinFsp runtime (one-time)
winget install WinFsp.WinFsp
# 2. Download encoding-vfs-Windows-x64.exe from Releases
# 3. Copy winfsp-x64.dll next to the exe:
Copy-Item "C:\Program Files (x86)\WinFsp\bin\winfsp-x64.dll" .\
# 4. Mount and go
.\encoding-vfs.exe -b C:\legacy-project -d X
Any read/write to X:\ is now transparently converted between the source encoding and UTF-8.
Linux
# 1. Install FUSE3 runtime
sudo apt-get install -y libfuse3-2 fuse3
# 2. Download encoding-vfs-Linux-x64 from Releases
# 3. Mount and go
./encoding-vfs -b /home/user/legacy-project -m /mnt/vfs
Prerequisites
Windows — WinFsp 2.1
Required for virtual drive mount. Install via:
winget install WinFsp.WinFsp
Verify the service is running:
Get-Service WinFsp.Launcher
# Should show Status: Running
Linux — FUSE3
Ubuntu/Debian:
sudo apt-get install -y libfuse3-2 fuse3
Fedora:
sudo dnf install -y fuse3
Arch:
sudo pacman -S fuse3
Build from Source
Windows
cargo build --release
# Copy WinFsp DLL next to the binary:
Copy-Item "C:\Program Files (x86)\WinFsp\bin\winfsp-x64.dll" target\release\
Linux
# Install build deps
sudo apt-get install -y libfuse3-dev pkg-config
cargo build --release
CLI Usage
encoding-vfs --help
| Flag | Description | Default |
|---|---|---|
-b, --backend <DIR> | Backend directory with original files | — |
-d, --drive <LETTER> | Windows drive letter to mount | X |
-m, --mount <PATH> | Linux FUSE mount point | /mnt/vfs |
-s, --source-encoding <ENC> | Source encoding: auto, GBK, Shift_JIS, Big5 | auto |
-t, --target-encoding <ENC> | Encoding presented to applications | UTF-8 |
-L, --log-level <LEVEL> | Log level: trace, debug, info, warn, error | info |
-c, --config <FILE> | Optional TOML config file | — |
Examples
# Auto-detect all files, mount as UTF-8
encoding-vfs.exe -b C:\legacy-project -d X
# Fixed source encoding (faster, skips per-file detection)
encoding-vfs.exe -b C:\sjis-project -d X -s Shift_JIS
# Big5 → UTF-8
encoding-vfs.exe -b C:\big5-project -d X -s Big5
# With config file (CLI overrides config values)
encoding-vfs.exe -b C:\legacy-project -d X -c encoding-vfs.toml
# CLI overrides config file
encoding-vfs.exe -b C:\legacy-project -d X -c config.toml -s Big5
Unmount
# Windows: Ctrl+C in terminal, or
net use X: /delete /y
# Linux: Ctrl+C in terminal, or
fusermount3 -u /mnt/vfs
Configuration File
Create encoding-vfs.toml (pass via -c):
[backend]
backend_dir = "C:\\legacy-project" # Windows
# backend_dir = "/home/user/legacy" # Linux
[mount]
drive_letter = "X"
# mount_point = "/mnt/vfs" # Linux only
[encoding]
source_encoding = "auto"
target_encoding = "UTF-8"
default_encoding = "GBK"
detect_sample_bytes = 8192
cache_max_entries = 10000
cache_ttl_seconds = 3600
[encoding.filter]
rules = ["@passthrough *.dll", "@passthrough *.exe"]
[log]
level = "info"
All Options
| Section | Key | Description | Default |
|---|---|---|---|
backend | backend_dir | Directory containing original files | . |
mount | drive_letter | Windows drive letter | X |
mount | mount_point | Linux FUSE mount point | /mnt/vfs |
encoding | source_encoding | Backend file encoding: "auto" per-file or fixed ("GBK", "Shift_JIS", etc.) | auto |
encoding | target_encoding | Encoding presented to applications | UTF-8 |
encoding | default_encoding | Fallback when auto-detect fails | GBK |
encoding | detect_sample_bytes | Bytes read for encoding detection | 8192 |
encoding | cache_max_entries | Max encoding cache entries (LRU) | 10000 |
encoding | cache_ttl_seconds | Cache entry TTL in seconds | 3600 |
encoding.filter | rules | Inline rules for @passthrough patterns | [] |
log | level | Log verbosity | info |
Encoding Presets
Auto-detect → UTF-8 (most common):
[encoding]
source_encoding = "auto"
target_encoding = "UTF-8"
default_encoding = "GBK"
Fixed source (faster, no detection):
[encoding]
source_encoding = "Shift_JIS"
target_encoding = "UTF-8"
Mount as GBK for apps that expect it:
[encoding]
source_encoding = "auto"
target_encoding = "GBK"
default_encoding = "GBK"
Priority
CLI flags override config file, which overrides defaults.
# config.toml says Big5, but CLI overrides to GBK
encoding-vfs.exe -b C:\legacy -d X -c config.toml -s GBK
Filter
Control which files bypass encoding conversion in the mounted drive. All files are always visible — the only distinction is whether encoding conversion applies.
Rules follow .gitignore format and semantics.
Sources (merged)
.evfsignore— place in backend directory root[encoding.filter] rules— inline in TOML config
File rules load first, config rules append.
Rule Syntax
| Rule | Effect | Example |
|---|---|---|
*.ext | Skip encoding, return raw bytes | *.png, *.exe |
dir/ | Skip encoding for directory tree | assets/, lib/ |
**/*.tmp | Recursive glob | all .tmp files recursively |
!pattern | Negation: restore encoding for matching files | !logo.png |
Evaluation
- Rules are evaluated in order; the last matching pattern wins.
- Default (no match): normal encoding conversion.
!patternnegates a previous match — restores encoding for that file.
Config Example
Skip binary assets, convert everything else:
# .evfsignore
*.png
*.jpg
*.exe
Only convert .h/.cpp, return raw bytes for everything else:
# .evfsignore
**
!*.h
!*.cpp
Or in TOML:
[encoding.filter]
rules = ["*.png", "!logo.png"]
How It Works
Read (source encoding → target encoding)
Application reads mounted file
│
▼
Platform callback → vfs.read_file()
│
├── Read raw bytes from backend (e.g. GBK)
├── Detect encoding (BOM + heuristic, cached)
│ └─ "auto": per-file detection
│ └─ fixed: skip detection
├── Convert via encoding_rs
└── Return converted bytes to application
Write (target encoding → source encoding)
Application writes mounted file (UTF-8)
│
▼
Platform callback → vfs.write_file()
│
├── Detect existing file encoding (cached)
├── Convert target → source encoding
└── Write encoded bytes to backend
Encoding Detection
- BOM check — UTF-8 (
EF BB BF), UTF-16 LE/BE - Content heuristic —
encoding_rs_iostyle validation - Cache — per-file encoding cached with TTL
- Fallback —
default_encodingwhen undetectable
Supported Encodings
GBK, CP936, GB2312, GB18030, UTF-8, UTF-16LE, UTF-16BE, Big5, EUC-JP, EUC-KR, Shift_JIS, KOI8-R, Windows-1252, ISO-8859-x, IBM866, Macintosh, and more (full list from encoding_rs).
Project Structure
encoding-vfs/
├── Cargo.toml
├── encoding-vfs-core/ # Cross-platform core
│ ├── config.rs # TOML config
│ ├── encoding.rs # Encoding conversion
│ ├── detector.rs # BOM + heuristic detection
│ ├── cache.rs # LRU cache with TTL
│ ├── vfs.rs # Core read/write/dir
│ └── filter.rs # Glob-based path filter
├── encoding-vfs-windows/ # WinFsp adapter
│ └── winfsp_host.rs # FileSystemContext impl
├── encoding-vfs-linux/ # FUSE adapter
│ └── fuse_host.rs # fuser Filesystem impl
├── encoding-vfs-cli/ # Unified CLI binary
│ └── main.rs
└── .github/workflows/
└── release.yml # CI build + release
Build Details
| Crate | Role | Key Dependencies |
|---|---|---|
encoding-vfs-core | Detection, conversion, cache, VFS | encoding_rs, dashmap, globset, toml, serde |
encoding-vfs-windows | WinFsp 2.1 drive mount | winfsp 0.12, windows 0.61, encoding-vfs-core |
encoding-vfs-linux | FUSE filesystem mount | fuser 0.14, libc, encoding-vfs-core |
encoding-vfs-cli | CLI binary, platform dispatch | clap 4.4, tracing-subscriber |
WinFsp Notes
- Uses
winfspcrate (v0.12.6+winfsp-2.1) withFileSystemContexttrait - Standard install:
winget install WinFsp.WinFsp - SxS installation supported for custom builds
- Security: returns null security descriptor, WinFsp applies defaults
FUSE Notes
- Uses
fusercrate (v0.14) withFilesystemtrait - Build requires
libfuse3-dev+pkg-config - Runtime requires
/dev/fuseandfusermount/fusermount3 - For multi-user access, uncomment
user_allow_otherin/etc/fuse.conf