# Repository: studyzy/imewlconverter
# Stars: 9843

## CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

IME WL Converter (深蓝词库转换) is a cross-platform dictionary converter for Input Method Editors (IMEs). It converts dictionary files between 20+ different IME formats including Sougou Pinyin, QQ Pinyin, Rime, Google Pinyin, Baidu Pinyin, and many others.

**Language**: C# (.NET 10.0)
**License**: GPL-3.0
**Platforms**: Windows, Linux, macOS

## Common Commands

### Build Commands

```bash
# Restore NuGet packages
make restore

# Build all projects (Debug mode)
make build

# Build Release configuration
make build-release

# Build command-line tool only
make build-cmd

# Build macOS GUI version
make build-mac
```

### Testing

```bash
# Run unit tests
make test

# Run unit tests with verbose output
make test-verbose

# Run integration tests (requires CLI built first)
make integration-test

# Run integration tests with debug output
cd tests/integration
./run-tests.sh --all -v
```

### Running the Application

```bash
# Run CLI tool
make run-cmd

# Run macOS GUI
make run-mac

# Run CLI directly with dotnet
dotnet run --project src/ImeWlConverterCmd
```

### CLI Usage Examples

```bash
# Convert Sougou .scel to Google Pinyin text format
dotnet run --project src/ImeWlConverterCmd -- \
  -i scel -o ggpy -O output.txt input.scel

# Convert multiple files
dotnet run --project src/ImeWlConverterCmd -- \
  -i scel -o ggpy -O ./output/ file1.scel file2.scel

# Apply filters (length, rank, remove English/numbers)
dotnet run --project src/ImeWlConverterCmd -- \
  -i scel -o ggpy -O output.txt \
  -f "len:1-100|rank:2-9999|rm:eng|rm:num" \
  input.scel
```

### Code Quality

```bash
# Format code
make format

# Check code formatting (CI)
make lint
```

### Publishing and Packaging

```bash
# Publish macOS versions (ARM64 + x64)
make publish-mac

# Create macOS .app bundles
make app-mac

# Create distributable .zip packages
make package-mac
```

## High-Level Architecture

### Core Components

The codebase follows a plugin-style architecture with clear separation of concerns:

1. **ImeWlConverterCore** - Core library containing all conversion logic
2. **ImeWlConverterCmd** - Command-line interface
3. **ImeWlConverterMac** - macOS GUI application (Avalonia UI)
4. **IME WL Converter Win** - Windows GUI application (WinForms/WPF)
5. **ImeWlConverterCoreTest** - Unit tests

### Conversion Pipeline

The conversion process follows a pipeline architecture:

```
Input File → Import → Filters → Code Generation → Export → Output File
```

**Key Classes:**

- `MainBody` - Orchestrates the entire conversion pipeline
- `ConsoleRun` - Handles CLI argument parsing and execution
- `IWordLibraryImport` - Interface for all input format parsers
- `IWordLibraryExport` - Interface for all output format generators
- `WordLibrary` - Core data structure representing a dictionary entry (word + code + rank)
- `WordLibraryList` - Collection of WordLibrary entries

### Directory Structure

```
src/ImeWlConverterCore/
├── IME/              # Input format parsers (20+ formats)
│   ├── SougouPinyin.cs
│   ├── QQPinyin.cs
│   ├── Rime.cs
│   └── ...
├── Generaters/       # Output format generators
│   ├── PinyinGenerater.cs
│   ├── Wubi86Generater.cs
│   └── ...
├── Filters/          # Word filtering logic
│   ├── LengthFilter.cs
│   ├── RankFilter.cs
│   ├── EnglishFilter.cs
│   └── ...
├── Helpers/          # Utility functions
│   ├── PinyinHelper.cs
│   ├── BinFileHelper.cs
│   └── ...
├── Entities/         # Data models (WordLibrary, CodeType, etc.)
├── MainBody.cs       # Core orchestration logic
└── ConsoleRun.cs     # CLI argument handling
```

### Adding New Format Support

To add support for a new IME format:

1. **For Import**: Create a new class in `src/ImeWlConverterCore/IME/` that implements `IWordLibraryImport`
   - Inherit from `BaseImport` or `BaseTextImport` for common functionality
   - Implement `Import(string path)` to parse the file format
   - Add the format to the import registry in `ConsoleRun.LoadImeList()`

2. **For Export**: Create a new class that implements `IWordLibraryExport`
   - Implement `Export(WordLibraryList)` to generate output
   - Implement `ExportLine(WordLibrary)` for line-by-line export
   - Add the format to the export registry in `ConsoleRun.LoadImeList()`

3. Add the format constant to `ConstantString.cs` with a short code (e.g., `SOUGOU_XIBAO_SCEL_C = "scel"`)

### Code Generation System

The codebase supports multiple encoding methods (Pinyin, Wubi, Cangjie, etc.) through the `IWordCodeGenerater` interface:

- `PinyinGenerater` - Full Pinyin and Shuangpin (double Pinyin)
- `Wubi86Generater`, `Wubi98Generater` - Wubi input methods
- `SelfDefiningCodeGenerater` - Custom user-defined encoding

Generators can read encoding tables from resource files or user-provided files.

### Filter System

Filters are applied after import but before export:

- **Single Filters** (`ISingleFilter`): Process individual entries (e.g., `LengthFilter`, `RankFilter`)
- **Batch Filters** (`IBatchFilter`): Process the entire word list (e.g., deduplication)
- Filters are configured via CLI with `-f` or `--filter` parameter

### Chinese Character Conversion

Built-in support for simplified/traditional Chinese conversion through the `IChineseConverter` interface.

## Integration Tests

The project uses a shell-based integration test framework located in `tests/integration/`.

### Test Structure

- `test-cases/` - Test case definitions organized by format or feature
  - `1-imports/` - Tests for importing various formats to CSV
  - `2-exports/` - Tests for exporting CSV to various formats
  - `3-advanced/` - Advanced features (filters, encoding, large files)
- Each test suite has a `test-config.yaml` defining test cases
- Test data is sourced from `src/ImeWlConverterCoreTest/Test/` (shared with unit tests)

### Running Integration Tests

```bash
# Run all tests
cd tests/integration
./run-tests.sh --all

# Run specific suite
./run-tests.sh -s 1-imports

# Run with verbose output
./run-tests.sh -s 1-imports -v

# Keep output files for debugging
./run-tests.sh -s 1-imports --keep-output

# Generate JUnit XML report (for CI)
./run-tests.sh --all --xml
```

### Adding Integration Tests

1. Choose or create a test suite directory under `tests/integration/test-cases/`
2. Create or update `test-config.yaml` with your test case
3. Reference existing test files from `src/ImeWlConverterCoreTest/Test/` using relative paths
4. Generate expected output by running the converter manually
5. Run `./run-tests.sh -s <suite-name>` to verify

See `tests/integration/README.md` for detailed documentation.

## Version Management

Version numbers are automatically generated from Git tags using MinVer:

- Tags follow semantic versioning (e.g., `v2.9.0`)
- Version is embedded in assemblies at build time
- Check version: `make version`

## Build Configuration

- **Debug**: Default, includes debugging symbols
- **Release**: Optimized builds with:
  - Code trimming (`PublishTrimmed=true`)
  - Single-file publishing (`PublishSingleFile=true`)
  - ReadyToRun compilation for faster startup
  - No PDB files

## CI/CD Workflow

GitHub Actions workflow (`.github/workflows/ci.yml`):

1. **Lint** - Code formatting check (fast-fail)
2. **Build and Test** - Build + unit tests on Ubuntu
3. **Platform Builds** - Parallel builds for Windows (x64/x86), Linux (x64/arm64), macOS (x64/arm64)
4. **Integration Tests** - Run on Linux and macOS builds
5. Artifacts retained for 7-30 days

## OpenSpec Integration

This project uses OpenSpec workflow for specification-driven development:

- Specs located in `specs/` directory
- Integration test specification in `specs/001-integration-tests/`
- Uses YAML contracts for test case schemas
- OpenSpec configuration in `.specify/` and `openspec/` directories

## Important Notes

### Character Encoding

The codebase handles multiple encodings (UTF-8, GBK, GB2312, Big5). Always register the CodePagesEncodingProvider:

```csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
```

This is done in `Program.cs` and `MainBody.cs` constructors.

### Binary File Formats

Several IME formats use proprietary binary formats (e.g., `.scel`, `.bdict`, `.qpyd`). Parsers for these are in:

- `BinFileHelper.cs` - Binary reading utilities
- Individual format classes (e.g., `SougouPinyin.cs` for .scel files)

Reverse engineering documentation for these formats is not provided in the codebase but can be found in related Chinese forums.

### Resource Files

Encoding tables and dictionaries are embedded as resources:

- `src/ImeWlConverterCore/Resources/` - Contains .txt files for various encoding tables
- Access via `DictionaryHelper.GetResourceContent(filename)`

### Cross-Platform Considerations

- Use `Path.Combine()` for file paths, never hardcode separators
- The CLI tool is framework-dependent (requires .NET runtime)
- macOS app bundles include the full .NET runtime (self-contained)
- Integration tests work on Linux, macOS, and Windows (Git Bash)

## Debugging Tips

### Integration Test Failures

```bash
# Keep test output for inspection
cd tests/integration
./run-tests.sh -s <suite> --keep-output

# Manually run conversion to debug
dotnet run --project ../../src/ImeWlConverterCmd -- \
  -i <format> -o <format> -O <output-file> <input-file>

# Compare output
diff -u expected.txt test-output/actual.txt
```

### Unit Test Debugging

Test data is in `src/ImeWlConverterCoreTest/Test/` with real dictionary files from various IME formats. Tests cover:

- Format parsing (import)
- Format generation (export)
- Filters
- Helpers (Pinyin, Wubi, etc.)


## README.md

<div align="center">

# 深蓝词库转换

[![Stars](https://img.shields.io/github/stars/studyzy/imewlconverter)](https://github.com/studyzy/imewlconverter/stargazers)
![Actions Check](https://github.com/studyzy/imewlconverter/actions/workflows/commit.yml/badge.svg)
![Integration Tests](https://github.com/studyzy/imewlconverter/actions/workflows/integration-tests.yml/badge.svg)
![License](https://img.shields.io/github/license/studyzy/imewlconverter)
![Repo size](https://img.shields.io/github/repo-size/studyzy/imewlconverter)
[![Code Count](https://tokei.rs/b1/github/studyzy/imewlconverter)](https://github.com/studyzy/imewlconverter)

[![Join the chat](https://badges.gitter.im/studyzy/imewlconverter.svg)](https://gitter.im/studyzy/imewlconverter?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Release](https://badgen.net/github/release/studyzy/imewlconverter)](https://github.com/studyzy/imewlconverter/releases)
![Downloads](https://badgen.net/github/assets-dl/studyzy/imewlconverter)

一款输入法词库转换软件，支持以下超过 20 种的输入法工具和词库

</div>

本程序支持批量转换（一次拖拽多个词库文件，或者按住 Ctrl 选择多个文件），支持命令行模式（在命令行下使用-h命令查看帮助），支持 Windows、Linux、MacOS。

### 支持列表

PC 端：

- Chinese-pyim(Linux)
- [FIT 输入法(Mac)](https://github.com/studyzy/imewlconverter/wiki/FIT)
- libpinyin(Linux)
- [MacOS 自带简体拼音](https://github.com/studyzy/imewlconverter/wiki/MacPlist)
- [QQ 拼音（文本词库和 qpyd 格式分类词库）](https://github.com/studyzy/imewlconverter/wiki/QQ_Pinyin_Win)
- [QQ 五笔](https://github.com/studyzy/imewlconverter/wiki/QQ_Wubi)
- [Rime 输入法(Linux 中州韻、Windows 小狼毫、Mac OS 鼠鬚管)](https://github.com/studyzy/imewlconverter/wiki/Rime)
- [Win10 微软拼音](https://github.com/studyzy/imewlconverter/wiki/Win10Ms_Pinyin)
- [Win10 微软五笔](https://github.com/studyzy/imewlconverter/wiki/Win10Ms_Wubi)
- [百度拼音 PC（文本词库、bdict 格式）](https://github.com/studyzy/imewlconverter/wiki/Baidu_PC)
- [必应输入法](https://github.com/studyzy/imewlconverter/wiki/Engkoo)
- 仓颉平台
- [谷歌拼音](https://github.com/studyzy/imewlconverter/wiki/Google_Pinyin)
- [极点五笔](https://github.com/studyzy/imewlconverter/wiki/Jidian)
- [极点郑码](https://github.com/studyzy/imewlconverter/wiki/Jidian)
- [灵格斯词库 ld2](https://github.com/studyzy/imewlconverter/wiki/Lingoes_Ld2)
- [拼音加加](https://github.com/studyzy/imewlconverter/wiki/Pinyin_Jiajia)
- 手心输入法
- [搜狗拼音（文本词库、Bin 格式备份词库和 scel 格式细胞词库）](https://github.com/studyzy/imewlconverter/wiki/Sougou_Pinyin)
- [搜狗五笔](https://github.com/studyzy/imewlconverter/wiki/Sougou_Wubi)
- [微软拼音 2010](https://github.com/studyzy/imewlconverter/wiki/Ms_Pinyin)
- [小小输入法（拼音、五笔、郑码、二笔）](https://github.com/studyzy/imewlconverter/wiki/Xiaoxiao)
- [小鸭五笔](https://github.com/studyzy/imewlconverter/wiki/Xiaoya_Wubi)
- [新浪拼音](https://github.com/studyzy/imewlconverter/wiki/Sina_Pinyin)
- [雅虎奇摩输入法（注音）](https://github.com/studyzy/imewlconverter/wiki/Yahoo)
- [紫光拼音（文本词库和 uwl 格式分类词库）](https://github.com/studyzy/imewlconverter/wiki/Ziguang_Pinyin)
- 自定义格式

手机端：

- QQ 手机拼音
- 百度手机拼音（文本词库和 bcd 格式）
- 谷歌拼音输入法

该软件支持 6 种以上的输入法编码方法：

- 仓颉
- 二笔（超强二笔，青松二笔等）
- 拼音（全拼、双拼）
- 五笔（五笔 86、五笔 98、新世纪五笔）
- 郑码
- 注音
- 自定义

## 命令行使用

### 基本语法

```bash
imewlconverter --input-format <格式> --output-format <格式> --output <输出路径> <输入文件>...
```

或使用短选项：

```bash
imewlconverter -i <格式> -o <格式> -O <输出路径> <输入文件>...
```

### 常用示例

**单文件转换**：
```bash
imewlconverter -i scel -o ggpy -O output.txt input.scel
```

**多文件转换**：
```bash
imewlconverter -i scel -o ggpy -O output.txt file1.scel file2.scel file3.scel
```

**批量转换到目录**（输出目录以 `/` 结尾）：
```bash
imewlconverter -i scel -o ggpy -O ./output/ *.scel
```

**使用过滤器**：
```bash
imewlconverter -i scel -o ggpy -O output.txt -f "len:1-100|rm:eng|rm:num" input.scel
```

**查看帮助**：
```bash
imewlconverter --help
imewlconverter --list-formats  # 查看支持的格式列表
```

### 重要说明

从 v3.0.0 开始，命令行参数格式已更新为 GNU 风格。如果您使用的是旧格式（如 `-i:scel`），请参阅 [MIGRATION.md](MIGRATION.md) 进行迁移。

## 集成测试

本项目包含完整的集成测试框架，确保各种输入法格式之间的转换正确性。

### 快速运行测试

```bash
# 1. 编译CLI工具
cd src/ImeWlConverterCmd
dotnet build -c Release

# 2. 运行集成测试
cd ../../tests/integration
./run-tests.sh --all
```

### 测试覆盖范围

当前已实现：
- ✅ 导入测试（多种输入格式 → 统一CSV格式）
- ✅ 导出测试（统一CSV格式 → 多种输出格式）
- ✅ 高级功能测试（过滤、编码、大文件性能）

详细的测试矩阵与数据来源见 `tests/integration/TEST-MATRIX.md`。

### 更多信息

- [集成测试完整文档](tests/integration/README.md)
- [测试用例配置规范](specs/001-integration-tests/contracts/test-case-schema.yaml)
- [测试数据来源](src/ImeWlConverterCoreTest/Test/)

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=studyzy/imewlconverter&type=Date)](https://star-history.com/#studyzy/imewlconverter&Date)