Simplifier / OpenCC 測試計劃提案 #1189

事件背景

OpenCC ver.1.3.2 引入了一系列破壞性的 C++ ABI 變更，導致 librime 在運行期載入新版 libopencc 時直接 crash。

技術上，1.3.2 將 Converter 重構為純虛擬介面（abstract class），並引入 PipelineConverter 作為新的具體實作。librime 的 simplifier.cc 直接呼叫：

converter_->GetConversionChain()->GetConversions()

而 PipelineConverter::GetConversionChain() 在有 normalization 設定時會回傳 nullptr，立即導致 null pointer dereference。OpenCC 為此在 ver.1.4.0 中：

1. 修復了 GetConversionChain() 回傳 nullptr 的 bug（PR #1380）
2. 將 SOVERSION 從 1.x 改為 1.4，專門用來阻止 librime 誤載入 ABI 不相容的 1.3.2（PR #1377，PR 標題明確寫道 "to prevent librime loading ABI-incompatible v1.3.2 builds"）

這次事件暴露的根本問題是：librime 沒有任何自動化測試可以在 OpenCC 升級後驗證繁簡轉換是否仍然正確運作。 問題只能在使用者端被察覺，修復也只能由 OpenCC 上游完成。

現有程式碼的層次結構

simplifier.cc 內部有兩個職責不同的層次：

第一層：rime::Opencc（私有適配器類別）

這是 librime 與 OpenCC C++ API 之間唯一的接觸點，封裝了三個操作：

其中 ConvertWord 的邏輯完全由 librime 自己維護：它逐層遍歷 ConversionChain，在每個 Dict 上做精確匹配與前綴最長匹配，並在多個 dict 之間累積展開結果。這段邏輯並非對 OpenCC 的直接封裝，而是 librime 基於 OpenCC 底層 dict / conversion chain 介面自行實作的——也正是本次 ABI 破壞直接衝擊到的地方。

若有測試覆蓋這個邊界，GetConversionChain() 回傳 nullptr 就會在 CI 中以 crash 或測試失敗的方式立即暴露，而不是等到使用者回報。

第二層：Simplifier（RIME 過濾器）

使用 rime::Opencc，負責：

• 路由決策：Convert() 先嘗試 ConvertWord，失敗再 fallback 到 ConvertText；random_ 模式走 RandomConvertText
• 顯示格式化：PushBack() 處理 tips 顯示級別（無 / 單字 / 全部）、注釋位置（show_in_comment）、comment_formatter 投影
• 類型過濾：excluded_types_ 讓特定類型的候選詞跳過轉換

這一層深度依賴 RIME 引擎（Engine、Ticket、Candidate、Translation）。

目前的可測試性問題

rime::Opencc 被定義為 simplifier.cc 的內部私有類別，外部無法直接引用，導致：

• 無法在不啟動完整 RIME Engine 的前提下驗證轉換邏輯
• 任何對 simplifier.cc 的修改，或對 OpenCC 的版本升級，都缺乏自動化驗證手段
• ConvertWord 中的鏈式轉換邊界行為（如注釋所說的「s2t 展開 里 為 里 和 裏，再由 t2tw 將 裏 轉為 裡」）完全沒有被測試保護

測試計劃

第一步：提取 rime::Opencc 至獨立標頭

將 rime::Opencc 從 simplifier.cc 移出，建立：

• src/rime/gear/opencc.h：類別宣告（對外可見）
• src/rime/gear/opencc.cc：實作

simplifier.cc 改為 #include 這個新標頭。此步驟不改變任何對外行為，是純粹的內部重構，同時讓未來其他模組也能複用這個適配器。

第二步：新增 test/simplifier_test.cc

分兩組測試案例：

組一：OpenccTest（整合測試）

直接測試 rime::Opencc，使用真實的 OpenCC 詞典檔案（t2s.json、s2t.json、s2twp.json）。這組測試是未來再次升級 OpenCC 時的安全網。

最後一個案例直接對應本次事件的根因：rime::Opencc 的初始化錯誤處理必須健壯。

組二：SimplifierConvertTest（單元測試）

以 mock 的 rime::Opencc 測試 Simplifier 的路由與格式化邏輯，不依賴 OpenCC 詞典，也不需要啟動 RIME Engine。

第三步：在 CI 中確認測試可跑

確認 make test 涵蓋新增的測試案例，在 GitHub Actions 現有 workflow 中通過。

工作量估計

不在本次範圍內

• SimplifierComponent::Create() 的路徑解析邏輯（需要 deployer 基礎設施，建議另立提案）
• SimplifiedTranslation 的翻譯包裝層（依賴完整的 Translation 物件，同上）
• OpenCC 詞典資料本身的正確性（屬於 OpenCC 專案的責任範圍）