#opencc.mbt

#安装

moon add Ljh684/opencc              # 已在 mooncakes 发布：https://mooncakes.io/docs/Ljh684/opencc

// 按名字调用（会链入全部词典）
let out = @config.convert("s2twp", "内存泄漏与软件优化")   // Some("記憶體洩漏與軟體最佳化")

// 只要一个方向、体积最小：import "Ljh684/opencc/config/s2twp"
let chain = @s2twp.chain()

状态：开发中（WIP）。已完成：仓库骨架与 Apache-2.0 许可、上游 OpenCC 数据快照 （19 个词典 / 19 个配置 / 官方 golden 语料 + 官方 testcases 语料）、转换引擎（首字索引、 嵌套词典组、归一化 → 分词 → 逐段转换）、词典生成器（tools/gen_dict：把 26 个词典共 89817 条数据编译成内嵌文本块，其中 6 个是复刻 OpenCC 构建期生成的派生词典；SHA-256 校验与 --verify 幂等检查）、CLI 与库 API。

官方一致性：golden 语料 5/5 逐字节通过；官方 testcases 语料覆盖全部 19 个配置、 262 例 / 583 条期望值全部逐字节复现（含 t2s、tw2s、tw2sp、hk2s、seal2t 等反方向与地区方向）。moon check 无警告，50 个测试通过 （含覆盖 89817 条词典条目的全量属性测试，以及 19 个配置的回归基线）。 见下方路线图。

#为什么做这个

#范围

#支持

• OpenCC 全部 19 个官方转换配置（见下表）。
• 词典组合语义：union 与 short_circuit。
• 词组优先于单字的多段转换链（归一化 → 词组/单字 → 地区变体短语 → 变体字）。
• 最大匹配分词驱动的词组替换，避免逐字转换造成的错译。
• 非中文内容（数字、标点、拉丁字母、emoji、空白）原样保留。
• 基本平面以外的字符（罕见汉字、小篆）按字符整体处理，不会被代理对拆开。

#19 个内置配置

#明确的非目标

• 不做分词 / 词性 / 命名实体识别（见 colmugx/jieba、moonnlp）。
• 不做拼音与输入法。
• 暂不覆盖 OpenCC 的 staging/ 实验字典与 jieba 分词变体配置。
• 不提供 GUI。

#使用

# 列出全部 19 个配置（会标出任何引用但解析不到的词典，当前为空）
opencc list-configs

# 文本 / 文件转换；不给 -o 时结果写到 stdout
opencc -c s2twp --text "内存泄漏与软件优化"        # => 記憶體洩漏與軟體最佳化
opencc convert -c s2t --input in.txt --output out.txt

# 多个 -c 按顺序串联（同上游 CLI），以及整目录批量转换
opencc -c s2t -c t2s --text "内存泄漏与软件优化"
opencc convert -c s2twp --input-dir corpus --output-dir converted --ext .txt

# 与 OpenCC 官方语料逐字节比对：golden（5 条链）+ testcases（19 个配置）
opencc verify --golden test/fixtures/golden

# 同一批结果落成报告（Markdown 或 JSON），并附代码规模与数据快照
opencc verify --report docs/verification-report.md
opencc verify --report docs/verification-report.json

// 库：一次转换
let out = @opencc.convert("s2twp", "内存泄漏与软件优化")

// 库：复用链（构建词典索引一次，多次转换）
let chain = @opencc.chain("s2twp")

#与现有方案的区别

• 生态里没有替代品：mooncakes 2648 个包中，opencc、简繁、简体、繁体、 traditional chinese、s2t、t2s 的命中数全部为 0；已有的是分词（jieba、moonnlp）、 拼音、中文数字，都不做字形与地区用词转换。
• 与 OpenCC 语义一致且可验证：官方 golden 语料 5/5 逐字节通过，官方 testcases 语料 262 例 / 583 条期望全部复现（覆盖全部 19 个配置，含反方向与地区方向）；而 OpenCC 是 C++ + 运行时二进制词典，本项目是纯 MoonBit、零 FFI、数据编译期内联，可编到 wasm / js / native。
• 数据可审计：上游 revision、逐文件 SHA-256、gen_dict --verify 幂等校验， 连 OpenCC 构建期生成的派生词典都按上游规则复刻并留下可读文本。

#演示

moon build examples/web --target js --release   # 产出可被 JS 调用的模块
node examples/web/demo.mjs                      # 命令行演示
python -m http.server                           # 再打开 examples/web/index.html 看网页 demo

$ node examples/web/demo.mjs
内存泄漏与软件优化
  → TW  記憶體洩漏與軟體最佳化
  → 简  记忆体泄漏与软体最佳化
较低级别的官员由总统任命。
  → TW  較低級別的官員由總統任命。
  → 简  较低级别的官员由总统任命。

#测试与验证

#数据来源与许可

• 本仓库的 MoonBit 代码以 Apache-2.0 发布，见 LICENSE。
• 词典、转换配置与一致性语料派生自 OpenCC（Apache-2.0）， 来源、固定 revision 与归档哈希记录在 NOTICE 与 data/opencc/REVISION。
• 上游数据随仓库提交，项目与 CI 全流程离线可跑；data/opencc/SHA256SUMS 记录每个文件的 SHA-256，生成器与 CI 在生成代码前先校验。

data/opencc/dictionary/   19 个词典（单字、词组、地区变体、兼容汉字、篆书）
data/opencc/config/       19 个转换配置 + schema
data/opencc/testcases/    官方 testcases 语料（262 例，覆盖全部 19 个配置）
data/opencc/SHA256SUMS    逐文件校验和
data/opencc/REVISION      上游仓库、revision、归档哈希与选择理由
data/derived/             6 个派生词典的可审计文本（由 tools/gen_dict 复刻）
test/fixtures/golden/     官方一致性语料（1 份输入 + 10 份期望输出）

pwsh -File scripts/fetch-opencc-data.ps1 -Revision <新 revision>

#开发

# 1. 安装 MoonBit 工具链（Windows）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://cli.moonbitlang.cn/install/powershell.ps1 | iex

# 2. 安装 Git 并完成仓库初始化（写入本仓库的 user.name / user.email 并首次提交）
winget install --id Git.Git -e
pwsh -File scripts/setup-git.ps1

# 3. 编译与测试
moon check
moon test

# 4. 可选：刷新上游 OpenCC 数据快照（已在仓库内，仅升级 revision 时执行）
#    pwsh -File scripts/fetch-opencc-data.ps1 -Revision <新 revision>

#仓库结构

moon.mod               模块清单
data/opencc/           上游词典与配置快照（含 REVISION / SHA256SUMS）
core/                  词典、最长匹配、转换链（引擎核心）
config/                19 个内置配置的定义与其转换链
dict/                  编译期词典数据模块（由 tools/gen_dict 产出）
cmd/opencc/            CLI 入口
tools/gen_dict/        词典 → MoonBit 数据 生成器
scripts/               环境与数据准备的 PowerShell 脚本
test/fixtures/golden/  OpenCC 官方一致性语料（验收基准）
docs/                  设计文档与验收标准

#发布新版本

#路线图

#已知限制

• 引擎按 UTF-16 码元切分与比较字符串；因为词典 key 与文本走同一套码元比较，匹配是一致的。 复制文本时按字符前进（core::char_width），不切开代理对——MoonBit 的字符串切片在起点 落在低代理项时会返回空视图，这点由官方 testcases（seal2t、t2s）覆盖。
• 往返（s2twp → tw2sp、s2hkp → hk2sp）不是逐字节恒等：TWPhrasesRev 并非 TWPhrases 的精确逆（它把台湾说法映射回正向从未产生的繁体写法）。这是上游数据的性质，verify 只把 它作为观察打印；正确性由官方 testcases 判定。
• CLI 还不支持标准输入：MoonBit 的 core 与 moonbitlang/x 目前没有标准输入 API， 加 FFI 会破坏「零 FFI」，因此先用文件与 --text；stdout 输出在以换行结尾的文本上 与输入等价，否则会补一个换行（-o 输出文件是逐字节精确的路径）。
• cmd/opencc 需要按名字查找配置，因此会链入全部词典（wasm-gc 1622 KB）。只想做单一方向 的程序请用 config/<name> 包，例如 examples/t2s 只有 259 KB（见 docs/performance.md）。
• docs/verification-report.* 是生成物：改动任何 .mbt 后重新跑一次 moon run cmd/opencc --target native -- verify --report <path> 即可；忘了重跑时 CI 会在 diff 这一步直接失败，因此报告不会与代码不一致。

#许可证