convez.ai
PluginDevOps & InfraestruturaIntermediário
skyispainted

encoding-vfs

skyispainted/encoding-vfs

Converte codificações legadas para UTF-8 via VFS — zero config para ferramentas de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin 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-vfs

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
0
Contribuidores
1

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

English | 中文

现代开发工具默认使用 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
FlagDescriptionDefault
-b, --backend <DIR>Backend directory with original files—
-d, --drive <LETTER>Windows drive letter to mountX
-m, --mount <PATH>Linux FUSE mount point/mnt/vfs
-s, --source-encoding <ENC>Source encoding: auto, GBK, Shift_JIS, Big5auto
-t, --target-encoding <ENC>Encoding presented to applicationsUTF-8
-L, --log-level <LEVEL>Log level: trace, debug, info, warn, errorinfo
-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

SectionKeyDescriptionDefault
backendbackend_dirDirectory containing original files.
mountdrive_letterWindows drive letterX
mountmount_pointLinux FUSE mount point/mnt/vfs
encodingsource_encodingBackend file encoding: "auto" per-file or fixed ("GBK", "Shift_JIS", etc.)auto
encodingtarget_encodingEncoding presented to applicationsUTF-8
encodingdefault_encodingFallback when auto-detect failsGBK
encodingdetect_sample_bytesBytes read for encoding detection8192
encodingcache_max_entriesMax encoding cache entries (LRU)10000
encodingcache_ttl_secondsCache entry TTL in seconds3600
encoding.filterrulesInline rules for @passthrough patterns[]
loglevelLog verbosityinfo

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)

  1. .evfsignore — place in backend directory root
  2. [encoding.filter] rules — inline in TOML config

File rules load first, config rules append.

Rule Syntax

RuleEffectExample
*.extSkip encoding, return raw bytes*.png, *.exe
dir/Skip encoding for directory treeassets/, lib/
**/*.tmpRecursive globall .tmp files recursively
!patternNegation: restore encoding for matching files!logo.png

Evaluation

  • Rules are evaluated in order; the last matching pattern wins.
  • Default (no match): normal encoding conversion.
  • !pattern negates 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

  1. BOM check — UTF-8 (EF BB BF), UTF-16 LE/BE
  2. Content heuristic — encoding_rs_io style validation
  3. Cache — per-file encoding cached with TTL
  4. Fallback — default_encoding when 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

CrateRoleKey Dependencies
encoding-vfs-coreDetection, conversion, cache, VFSencoding_rs, dashmap, globset, toml, serde
encoding-vfs-windowsWinFsp 2.1 drive mountwinfsp 0.12, windows 0.61, encoding-vfs-core
encoding-vfs-linuxFUSE filesystem mountfuser 0.14, libc, encoding-vfs-core
encoding-vfs-cliCLI binary, platform dispatchclap 4.4, tracing-subscriber

WinFsp Notes

  • Uses winfsp crate (v0.12.6+winfsp-2.1) with FileSystemContext trait
  • Standard install: winget install WinFsp.WinFsp
  • SxS installation supported for custom builds
  • Security: returns null security descriptor, WinFsp applies defaults

FUSE Notes

  • Uses fuser crate (v0.14) with Filesystem trait
  • Build requires libfuse3-dev + pkg-config
  • Runtime requires /dev/fuse and fusermount/fusermount3
  • For multi-user access, uncomment user_allow_other in /etc/fuse.conf
Ver o original no GitHub

Bom para

Relacionados