实现txt词典注释语法和排序规则

.bazelversion

@@ -1 +1 @@
-7.2.1
+8.5.0

.claude/hooks/session_start.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# OpenCC 專案啟動 Hook
+# 此腳本在 Claude Code 會話開始時自動執行
+
+cat << 'EOF'
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🔄 OpenCC - 開放中文轉換 (Open Chinese Convert)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📚 快速參考文件：
+  • AGENTS.md          - 專案架構與模組速覽
+  • CONTRIBUTING.md    - 貢獻指南（詞典、測試、開發流程）
+  • doc/ALGORITHM_AND_LIMITATIONS.md - 演算法與理論局限性
+
+🛠️  常用指令：
+  • bazel test //test/...           - 執行所有測試
+  • bazel test //data/dictionary:dictionary_test - 測試詞典
+  • python3 data/scripts/sort_all.py data/dictionary - 排序所有詞典
+
+📖 詞典位置：data/dictionary/*.txt
+   設定檔案：data/config/*.json
+   測試案例：test/testcases/testcases.json
+
+💡 提示：修改詞典後務必執行排序腳本，否則測試會失敗
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF

.claude/skills/opencc-algorithm-explain.md

@@ -0,0 +1,178 @@
+---
+name: opencc-algorithm-explain
+description: 解釋 OpenCC 的核心演算法、架構設計與理論局限性
+tags: [algorithm, architecture, theory, opencc]
+---
+
+# OpenCC 演算法解釋技能
+
+此技能協助解釋 OpenCC 的內部運作原理、設計決策與局限性。
+
+## 使用時機
+
+當用戶詢問：
+- OpenCC 如何運作？
+- 為什麼某些轉換會出錯？
+- OpenCC 與其他轉換工具的差異？
+- 如何改進轉換準確度？
+
+## 核心概念
+
+### 1. 最大正向匹配分詞（MaxMatch）
+
+**原理**：從左到右掃描，每次匹配最長的詞條。
+
+**範例**：
+
+詞典：`一`, `一個`, `一個人`
+輸入：`一個人去`
+
+```
+位置 0: 嘗試 "一個人去" (4) → ✗
+位置 0: 嘗試 "一個人" (3) → ✓
+位置 3: 嘗試 "去" (1) → 保留
+結果: [一個人] [去]
+```
+
+**優點**：
+- 快速（O(n)，n 為文本長度）
+- 確定性（相同輸入必定相同輸出）
+- 無需訓練
+
+**缺點**：
+- 不考慮上下文
+- 貪婪策略可能非最優解
+- 依賴詞典完整性
+
+### 2. 轉換鏈機制
+
+**流程**：配置 → 分詞 → 多階段轉換 → 輸出
+
+**範例**（`s2twp.json`）：
+
+```
+簡體文字
+  ↓ 階段 1: STPhrases + STCharacters
+繁體文字
+  ↓ 階段 2: TWPhrases
+臺灣慣用詞
+  ↓ 階段 3: TWVariants
+臺灣標準繁體
+```
+
+每階段的輸出成為下一階段的輸入。
+
+### 3. 詞典優先級
+
+在 `DictGroup` 中，詞典依序查詢：
+
+```
+查詢 "干燥" → STPhrases (命中) → "乾燥" ✓
+查詢 "干"   → STPhrases (未中) → STCharacters (命中) → "乾"
+```
+
+這實現「詞組優先，單字後備」策略。
+
+## 理論局限性
+
+### 1. 一對多歧義問題
+
+**根本原因**：缺乏語義理解和上下文分析。
+
+| 簡體 | 可能的繁體 | 語境範例 |
+|------|-----------|---------|
+| 干 | 乾、幹、干 | 乾燥、幹活、干擾 |
+| 后 | 後、后 | 後天、皇后 |
+| 面 | 麵、面 | 麵條、面孔 |
+
+**OpenCC 解法**：窮舉詞組
+
+```
+# STPhrases.txt
+干燥	乾燥
+干扰	干擾
+干活	幹活
+```
+
+**局限**：
+- 詞典會無限膨脹
+- 無法處理未登錄詞
+- 新詞、網路用語需要人工新增
+
+### 2. 缺乏上下文理解
+
+**問題案例**：
+
+```
+輸入: "后天就是星期一"
+理想: "後天就是星期一" ✓
+
+輸入: "皇后天生麗質"
+可能: "皇後天生麗質" ✗ (應為 "皇后")
+```
+
+如果詞典有 `后天 → 後天`，第二句可能被錯誤分詞。
+
+**根本原因**：
+- MaxMatch 只看局部，不看全局
+- 不理解「皇后」是一個完整詞彙
+- 需要將「皇后」也加入詞典
+
+### 3. 不使用語言模型
+
+**對比**：
+
+| 方法 | 上下文 | 概率 | 新詞 | 速度 | 維護 |
+|------|-------|------|------|------|------|
+| OpenCC（規則） | ✗ | ✗ | ✗ | 極快 | 高 |
+| 統計模型（N-gram） | 有限 | ✓ | 有限 | 中 | 中 |
+| 神經網路（Transformer） | ✓ | ✓ | ✓ | 慢 | 低 |
+
+**OpenCC 的權衡**：
+- 選擇速度、確定性、輕量級
+- 犧牲了語義理解和自動學習能力
+
+### 4. 維護負擔
+
+**數據規模**：
+- `STPhrases.txt`：~60,000 詞條
+- `TWPhrases*.txt`：~50,000 詞條
+
+**挑戰**：
+- 每個錯誤案例可能需要新增多個詞條
+- 詞條衝突需要人工仲裁
+- 地區差異（大陸、臺灣、香港）需分別處理
+- 專業領域術語需專家審核
+
+## 何時使用 OpenCC？
+
+**適合場景**：
+- ✓ 通用文本轉換
+- ✓ 需要高效能（即時轉換）
+- ✓ 需要確定性（相同輸入必定相同輸出）
+- ✓ 輕量級部署（瀏覽器、移動端）
+
+**不適合場景**：
+- ✗ 大量未登錄詞（新詞、網路用語）
+- ✗ 高度專業化領域（需要語境理解）
+- ✗ 需要自動學習新模式
+
+## 改進建議
+
+**短期**（在現有框架內）：
+1. 持續豐富詞典
+2. 社群回報問題並提交 PR
+3. 針對特定領域建立自訂詞典
+
+**長期**（架構升級）：
+1. 引入統計語言模型輔助歧義消解
+2. 使用深度學習處理未登錄詞
+3. 提供混合模式（規則 + 模型）
+
+但這會增加複雜度和計算成本，需要仔細權衡。
+
+## 參考資料
+
+- **[doc/ALGORITHM_AND_LIMITATIONS.md](../doc/ALGORITHM_AND_LIMITATIONS.md)** - 完整的演算法與局限性分析
+- **[AGENTS.md](../AGENTS.md)** - 專案架構速覽
+- **[src/README.md](../src/README.md)** - 核心模組技術文件

.claude/skills/opencc-dict-edit.md

@@ -0,0 +1,134 @@
+---
+name: opencc-dict-edit
+description: 編輯 OpenCC 詞典並執行相關的測試流程
+tags: [dictionary, testing, opencc]
+---
+
+# OpenCC 詞典編輯技能
+
+此技能協助編輯 OpenCC 詞典檔案，並確保正確執行測試驅動開發流程。
+
+## 使用時機
+
+當用戶要求：
+- 新增或修改詞典條目
+- 修正轉換錯誤
+- 新增地區用詞
+
+## 執行步驟
+
+### 1. 確認詞典檔案
+
+根據轉換類型選擇正確的詞典：
+
+**簡繁轉換基礎：**
+- `data/dictionary/STCharacters.txt` - 簡→繁（單字）
+- `data/dictionary/STPhrases.txt` - 簡→繁（詞組）
+- `data/dictionary/TSCharacters.txt` - 繁→簡（單字）
+- `data/dictionary/TSPhrases.txt` - 繁→簡（詞組）
+
+**臺灣地區用詞：**
+- `data/dictionary/TWVariants.txt` - 臺灣異體字
+- `data/dictionary/TWPhrasesIT.txt` - 資訊科技用語
+- `data/dictionary/TWPhrasesName.txt` - 人名地名
+- `data/dictionary/TWPhrasesOther.txt` - 其他用語
+
+**香港地區用詞：**
+- `data/dictionary/HKVariants.txt`
+
+**日文：**
+- `data/dictionary/JPShinjitaiCharacters.txt`
+- `data/dictionary/JPShinjitaiPhrases.txt`
+
+### 2. 撰寫測試案例（TDD）
+
+**重要**：先寫測試，確保修改前測試會失敗。
+
+編輯 `test/testcases/testcases.json`：
+
+```json
+{
+  "id": "case_XXX",
+  "input": "輸入文字",
+  "expected": {
+    "s2t": "預期輸出",
+    "s2tw": "預期輸出（臺灣）",
+    "s2twp": "預期輸出（臺灣含慣用詞）"
+  }
+}
+```
+
+**配置選擇**：
+- 修改 `STPhrases.txt` → 測試 `s2t`, `s2tw`, `s2twp`, `s2hk`
+- 修改 `TWPhrases*.txt` → 測試 `s2tw`, `s2twp`
+- 修改 `HKVariants.txt` → 測試 `s2hk`
+
+### 3. 執行測試（確認失敗）
+
+```bash
+bazel test //test:opencc_test
+```
+
+應該看到新測試案例失敗。
+
+### 4. 編輯詞典
+
+**格式**：`來源<TAB>目標`
+
+**注意事項**：
+- 使用 Tab 字元（`\t`），不是空格
+- 一行一個條目
+- UTF-8 編碼
+
+範例：
+```
+虚伪叹息	虛偽嘆息
+```
+
+### 5. 排序詞典
+
+**重要**：詞典必須排序，否則測試會失敗。
+
+單一檔案：
+```bash
+python3 data/scripts/sort.py data/dictionary/STPhrases.txt
+```
+
+所有檔案：
+```bash
+python3 data/scripts/sort_all.py data/dictionary
+```
+
+### 6. 執行測試（確認成功）
+
+```bash
+bazel test //test:bazel_opencc_test \
+    //data/dictionary:dictionary_test \
+    //data/config:config_dict_validation_test
+```
+
+所有測試應該通過。
+
+### 7. 提交變更
+
+```bash
+git add data/dictionary/*.txt test/testcases/testcases.json
+git commit -m "新增詞典條目：[簡要描述]"
+```
+
+## 常見陷阱
+
+- ❌ 使用空格而非 Tab → 格式錯誤
+- ❌ 忘記排序 → `DictionaryTest` 失敗
+- ❌ 未先寫測試 → 無法驗證修改效果
+- ❌ 測試配置不完整 → 遺漏某些轉換場景
+
+## 檢查清單
+
+- [ ] 選擇了正確的詞典檔案
+- [ ] 在 `testcases.json` 新增測試案例
+- [ ] 執行測試確認失敗
+- [ ] 編輯詞典（使用 Tab 分隔）
+- [ ] 執行排序腳本
+- [ ] 執行測試確認成功
+- [ ] 提交變更