|
| 1 | +--- |
| 2 | +sort: 9 |
| 3 | +--- |
| 4 | +# Homa vs. MegrezNT vs. Gramambular2 Whitepaper |
| 5 | + |
| 6 | +## Executive Summary |
| 7 | +Homa 是 vChewing 生態系的次世代 Swift 組字引擎，在 API 整合與輸入法場景支援度上大幅超越前一代的 MegrezNT（C#）實作，同時與第三方開源專案 Gramambular2（C++）在授權、設計目標與功能性上有明顯區隔。本白皮書： |
| 8 | + |
| 9 | +- 彙整三個專案的公開 API、內部架構與測試覆蓋範圍。 |
| 10 | +- 明確列出 Homa 相對 MegrezNT 的新增對外 API 與功能，指出 C# 版本尚未覆蓋的差異。 |
| 11 | +- 對照 Homa 與 Gramambular2 的核心實作差異，提供未來因應抄襲疑慮時可引用的證據。 |
| 12 | + |
| 13 | +## 專案概觀 |
| 14 | + |
| 15 | +| 專案 | 語言／平台 | 授權 | 主要定位 | |
| 16 | +|------|------------|------|-----------| |
| 17 | +| **Homa** | Swift 5+，SwiftPM 模組化 | LGPL-3.0-or-later（含自訂例外） | 次世代輸入法組字引擎，提供游標、覆寫、輪替等上層整合 API | |
| 18 | +| **MegrezNT** | .NET 6+（C#），NuGet 套件 | LGPL-3.0-or-later | 前一代輸入法組字引擎，提供核心 lattice 與候選覆寫能力 | |
| 19 | +| **Gramambular2** | C++11，CMake | MIT | 通用 lattice／語詞分段引擎，重心在讀音插入與最短路徑運算 | |
| 20 | + |
| 21 | +## Homa 公開 API 與能力摘要 |
| 22 | + |
| 23 | +- `Homa.Assembler` 建構子支援 `gramQuerier`、`gramAvailabilityChecker` 以及可選的 `BehaviorPerceptor`，同時保留 `Config` 深拷貝建構子。 |
| 24 | +- 公開屬性：`assembledSentence`、`keys`、`segments`、`cursor`、`marker`、`maxSegLength`、`length`、`isEmpty`、`actualKeys`、`copy`。 |
| 25 | +- 游標／節點操作：`insertKey`、`insertKeys`、`dropKey`、`clear`、`currentMarkedRange`、`isCursorCuttingChar`、`isCursorAtEdge`、`moveCursorStepwise`、`jumpCursorBySegment`、`assignNodes(updateExisting:)`。 |
| 26 | +- 候選操作：`fetchCandidates(filter:)`、`overrideCandidate`、`overrideCandidateLiteral`、`revolveCandidate`、`consolidateCandidateCursorContext`、`getLogicalCandidateCursorPosition`。 |
| 27 | +- 覆寫鏡像與診斷：`generateNodeOverrideStatusMirror`、`restoreNodeOverrideStatusFromMirror`、`dumpDOT(verticalGraph:)`、`assemble()`。 |
| 28 | +- `perceptor` 提供最近 3 個 `GramInPath` 內容給外部學習模組，`FIUUID` 識別節點，GraphViz dump 支援 LR／TB 兩種方向。 |
| 29 | + |
| 30 | +## MegrezNT 公開 API 與能力摘要 |
| 31 | + |
| 32 | +- `Megrez.Compositor` 透過 `LangModelProtocol` 介面與語言模型互動，提供 `InsertKey`、`DropKey`、`JumpCursorBySegment`、`Update(updateExisting)`、`Clear` 等核心方法。 |
| 33 | +- 公開屬性：`Keys`、`Segments`、`Cursor`、`Marker`、`MaxSegLength`、`Length`、`IsEmpty`、`AssembledSentence`、`Separator`。 |
| 34 | +- 候選操作：`FetchCandidatesAt`、`OverrideCandidate`、`OverrideCandidateLiteral`、`CreateNodeOverrideStatusMirror`、`RestoreFromNodeOverrideStatusMirror`。 |
| 35 | +- 無游標輪替與上下文鞏固 API，診斷功能僅有橫向 `DumpDOT()`。 |
| 36 | + |
| 37 | +## Gramambular2 公開 API 與能力摘要 |
| 38 | + |
| 39 | +- `Formosa::Gramambular2::ReadingGrid` 接受 `LanguageModel`，提供 `insertReading`、`deleteReadingBeforeCursor`／`AfterCursor`、`setCursor`、`walk()`、`candidatesAt`、`overrideCandidate`。 |
| 40 | +- `Node` 僅含 `OverrideType`（`kNone`、`kOverrideValueWithHighScore`、`kOverrideValueWithScoreFromTopUnigram`）與 `kOverridingScore = 42` 常數，無節點鏡像或使用者學習回呼。 |
| 41 | +- `Span` 使用 `std::array` 管理節點；`ScoreRankedLanguageModel` 將語言模型回傳結果排序。 |
| 42 | +- 無游標／標記器概念，GraphViz dump 需自行實作，`walk()` 回傳 `WalkResult`（附計時與節點統計）。 |
| 43 | + |
| 44 | +## Homa 相較於 MegrezNT 的新增／缺失 API 對照 |
| 45 | +下表列出 Homa 已提供但 MegrezNT 尚未覆蓋的公開能力，可作為後續移植或功能評估依據： |
| 46 | + |
| 47 | +| Homa API／功能 | Homa 位置 | MegrezNT 是否具備 | 說明 | |
| 48 | +|----------------|-----------|--------------------|------| |
| 49 | +| `insertKeys(_:)` | `Homa_Assembler.swift` | ✗ | MegrezNT 僅提供單鍵 `InsertKey`，Homa 支援批次插入與原子回復。 | |
| 50 | +| `actualKeys` | `Homa_Assembler.swift` | ✗ | Homa 暴露組句結果對應的真實鍵序，利於部分匹配與 UI 顯示。 | |
| 51 | +| `currentMarkedRange()` | `Homa_Assembler.swift` | ✗ | Swift 版提供標記範圍運算，C# 版需自行計算。 | |
| 52 | +| `isCursorCuttingChar(isMarker:)` | `Homa_Assembler.swift` | ✗ | 用於偵測游標切割節點的情境，MegrezNT 無對應 API。 | |
| 53 | +| `isCursorAtEdge(direction:isMarker:)` | `Homa_Assembler.swift` | ✗ | Swift 版封裝游標邊界判斷，C# 需外部計算。 | |
| 54 | +| `moveCursorStepwise(to:isMarker:)` | `Homa_Assembler.swift` | ✗ | Homa 支援逐字游標移動並自動跳過斷字，MegrezNT 僅有幅節跳轉。 | |
| 55 | +| `getLogicalCandidateCursorPosition(forCursor:isMarker:)` | `Homa_CandidateAPIs_Revolver.swift` | ✗ | 為前置／後置游標模式換算邏輯位置；C# 版缺少此封裝。 | |
| 56 | +| `revolveCandidate(cursorType:counterClockwise:)` | `Homa_CandidateAPIs_Revolver.swift` | ✗ | Homa 內建候選輪替機制，MegrezNT 尚未提供。 | |
| 57 | +| `consolidateCandidateCursorContext(for:cursorType:)` | `Homa_ConsolidatorAPIs.swift` | ✗ | Swift 版提供上下文鞏固 API，確保覆寫時不破壞臨近詞；C# 版無對應功能。 | |
| 58 | +| `perceptor`／`BehaviorPerceptor` | `Homa_Assembler.swift` | ✗ | Homa 可在覆寫後回報最近三個 `GramInPath`，MegrezNT 無內建學習回呼。 | |
| 59 | +| `dumpDOT(verticalGraph:)` | `Homa_Assembler.swift` | 部分 | C# 版僅有橫向輸出，Homa 支援 LR／TB 切換。 | |
| 60 | +| `FIUUID` 節點識別 | `Homa_Node.swift` | ✗（使用 `Guid`） | Swift 版以自訂 UUID 精簡 Foundation 依賴。 | |
| 61 | +| `assignNodes(updateExisting:)` 例外處理 | `Homa_Assembler.swift` | ✗（`Update` 不拋錯） | Homa 當無節點更新時拋出 `.noNodesAssigned`，MegrezNT 以 `int` 回傳數量。 | |
| 62 | +| `Homa.Exception` 類別化錯誤枚舉 | `Homa_Exception.swift` | ✗ | Swift 版以型別化錯誤表示各種場景，C# 以 `bool` 為主。 | |
| 63 | + |
| 64 | +> 其餘核心函式（例如 `insertKey`、`dropKey`、`jumpCursorBySegment`、`fetchCandidates`、`overrideCandidate`、`generateNodeOverrideStatusMirror`）兩者皆具備，但命名遵循各語言習慣。 |
| 65 | +
|
| 66 | +## Homa 與 Gramambular2 差異重點 |
| 67 | + |
| 68 | +1. **設計與語言層級**：Homa 將輸入法游標、標記器、候選輪替、上下文鞏固納入核心 API；Gramambular2 僅提供 lattice 建構與覆寫，游標邏輯交由呼叫端自行維護。 |
| 69 | +2. **覆寫機制**：Homa 透過 `Homa.Node.OverrideType` 與鏡像 API 管理覆寫狀態，並可回報 `BehaviorPerceptor`；Gramambular2 僅提供高分值與 top unigram 兩種覆寫模式，無鏡像或學習回呼。 |
| 70 | +3. **資料識別**：Homa 使用自訂 `FIUUID`，MegrezNT 以 `Guid`，Gramambular2 無持久節點 ID，改以 lattice 位置辨識。 |
| 71 | +4. **候選篩選**：Homa 預設過濾跨游標候選（`CandidateFetchFilter`），Gramambular2 `candidatesAt()` 產出的結果需外部過濾。 |
| 72 | +5. **GraphViz 支援**：Homa 內建 LR／TB 選項；Gramambular2 僅在測試中印出計時資訊，GraphViz 需自行實作。 |
| 73 | +6. **語言模型依賴**：Homa 與 MegrezNT 支援 bigram provider；Gramambular2 的 `LanguageModel` 僅定義 unigram 介面，bigram 需外部擴充。 |
| 74 | +7. **授權與註解風格**：Homa／MegrezNT 為繁中文註解與 LGPL，Gramambular2 為英文註解與 MIT，顯示來源與設計風格迥異。 |
| 75 | + |
| 76 | +## 單元測試對照 |
| 77 | + |
| 78 | +| 專案 | 測試框架 | 測試覆蓋亮點 | |
| 79 | +|------|-----------|----------------| |
| 80 | +| **Homa** | Swift `Testing` | `HomaTests_Basic`（鍵入／刪除／游標）、`HomaTests_Advanced`（候選輪替、鞏固、部分匹配）、`HomaTests_NodeOverrideStatus`（鏡像）、`HomaTests_Performance`（長句壓力）。 | |
| 81 | +| **MegrezNT** | NUnit | `MegrezTests`（基本行為）、`NodeOverrideStatusTests`（覆寫鏡像）、`SimpleLM` 驗證語料。缺少游標輪替／鞏固測試。 | |
| 82 | +| **Gramambular2** | GoogleTest | `reading_grid_test.cpp` 覆蓋 Span 操作、覆寫 reset、分詞、壓力測試；無游標與鏡像相關案例。 | |
| 83 | + |
| 84 | +## 結論 |
| 85 | + |
| 86 | +- **Homa 對 MegrezNT 的演進**：Swift 版本不僅復刻前代核心功能，更補足輸入法常見的游標微調、候選輪替、上下文鞏固與學習回呼等需求。MegrezNT 若要達到同等使用體驗，需補齊列出的缺失 API。 |
| 87 | +- **Homa 與 Gramambular2 的顯著差異**：兩者在語言、授權、API 命名、功能重點與測試策略皆迥異。Homa 更貼近實際輸入法產品需求；Gramambular2 則定位於通用 lattice。這些差異提供充分證據，證明 Homa 並非 Gramambular2 的衍生抄錄。 |
| 88 | +- **後續建議**： |
| 89 | + - 若需對外溝通，可將本白皮書附於法務或部落格文章，並引用對應檔案位置。 |
| 90 | + - 若計畫讓 MegrezNT 追上 Swift 版 API，可依表格逐項評估移植成本。 |
| 91 | + - 可補強自動化 API 對照（Swift `symbolgraph`, .NET Reflection, C++ `nm`）以利長期追蹤差異。 |
| 92 | + |
| 93 | +> 本白皮書彙整自倉庫當前版本：`vChewing-LibVanguard/Sources/_Modules/Homa`、`MegrezNT/Megrez/src`、`!LABS/mcbopomofo/Source/Engine/gramambular2`。如後續版本有重大更新，建議重新驗證。 |
0 commit comments