|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
1 | 5 | - ユーザーへは日本語で応答してください |
| 6 | + |
| 7 | +## プロジェクト概要 |
| 8 | + |
| 9 | +MacTcodeは、macOS用のT-Code日本語入力メソッド（IME）です。T-Codeは2ストロークで日本語文字を入力する効率的な入力方式で、部首変換や交ぜ書き変換などの機能を提供します。 |
| 10 | + |
| 11 | +## ビルドとテスト |
| 12 | + |
| 13 | +### 開発サイクル |
| 14 | +```bash |
| 15 | +make reload # デバッグビルド→インストール→入力メソッド再起動 |
| 16 | +make releaseBuild # リリースビルド |
| 17 | +make test # テスト実行 |
| 18 | +``` |
| 19 | + |
| 20 | +### ログの確認 |
| 21 | +設定ファイルで`"logEnabled": true`を設定後、以下で確認: |
| 22 | +```bash |
| 23 | +log stream --predicate 'process == "MacTcode"' |
| 24 | +``` |
| 25 | + |
| 26 | +### 設定ファイルの場所 |
| 27 | +``` |
| 28 | +~/Library/Containers/jp.mad-p.inputmethod.MacTcode/Data/Library/Application Support/MacTcode/config.json |
| 29 | +``` |
| 30 | + |
| 31 | +## コアアーキテクチャ |
| 32 | + |
| 33 | +### 三角関係: Mode - Controller - Client |
| 34 | + |
| 35 | +**Mode** (入力状態): |
| 36 | +- `handle()`: 入力イベントを処理 |
| 37 | +- 例: `TcodeMode`, `ZenkakuMode`, `MazegakiSelectionMode` |
| 38 | + |
| 39 | +**Controller** (モード管理): |
| 40 | +- `TcodeInputController`が`IMKInputController`を継承 |
| 41 | +- モードスタックで状態遷移を管理 |
| 42 | +- `pushMode()`/`popMode()`で一時的なモード切替 |
| 43 | + |
| 44 | +**Client** (テキスト入出力): |
| 45 | +- `ContextClient`: カーソル周辺のテキスト取得（複雑なロジック） |
| 46 | +- `RecentTextClient`: クライアントが文脈を提供できない場合のフォールバック |
| 47 | +- 読み取得の順序: 選択範囲 → クライアント → ミラー |
| 48 | + |
| 49 | +### キーマップシステム |
| 50 | + |
| 51 | +入力フロー: `キーイベント → KeymapResolver → Command → Action` |
| 52 | + |
| 53 | +- **KeymapResolver**: キーシーケンスを解決し、Commandに変換 |
| 54 | +- **Command**: `.passthrough`, `.processed`, `.pending`, `.text(String)`, `.action(Action)`, `.keymap(Keymap)` |
| 55 | +- **Action**: 実際の処理（部首変換、交ぜ書き変換など） |
| 56 | + |
| 57 | +### 変換エンジン |
| 58 | + |
| 59 | +**部首変換 (Bushu)**: |
| 60 | +- `Bushu.swift`: tc-bushu.elアルゴリズムの再実装、自動学習データ管理 |
| 61 | +- 2文字の組み合わせから1文字を合成 |
| 62 | +- 部品単位の合成、引き算（部品の削除）をサポート |
| 63 | +- `autoDict`: 自動部首変換学習データ（受容された変換結果を記録） |
| 64 | +- `tryAutoBushu()`: 文字入力後に自動変換を試行 |
| 65 | + |
| 66 | +**交ぜ書き変換 (Mazegaki)**: |
| 67 | +- `MazegakiDict.swift`: 辞書ファイル読み込み、LRU学習データ管理 |
| 68 | +- `Mazegaki.swift`: 読み取得と変換候補の検索 |
| 69 | +- `MazegakiSelectionMode.swift`: 候補選択UI |
| 70 | +- `MazegakiHit.swift`: 変換候補、LRU学習優先の候補取得 |
| 71 | + |
| 72 | +### 学習機能とキャンセル期間 |
| 73 | + |
| 74 | +**PendingKakutei** (変換キャンセル機構): |
| 75 | +- 変換確定後、`cancelPeriod`秒間（デフォルト1.5秒）キャンセル可能 |
| 76 | +- Delete、Control-g、Escapeキーでキャンセルして読みに戻せる |
| 77 | +- キャンセルされなかった変換は「受容」され、学習データに反映 |
| 78 | +- `Controller`プロトコルの`pendingKakutei`プロパティで管理 |
| 79 | + |
| 80 | +**交ぜ書き候補LRU学習**: |
| 81 | +- 選択された候補を先頭に移動（LRU: Least Recently Used） |
| 82 | +- `MazegakiDict.lruDict`で学習データを管理（元辞書は不変） |
| 83 | +- `MazegakiHit.candidates()`はLRU辞書を優先的に参照 |
| 84 | +- `mazegaki_user.dic`に自動保存（統計データと同じタイミング） |
| 85 | +- 設定: `mazegaki.lruEnabled`, `mazegaki.lruFile` |
| 86 | + |
| 87 | +**自動部首変換**: |
| 88 | +- 手動部首変換で受容された結果を学習し、次回から自動的に変換 |
| 89 | +- `Bushu.autoDict`で学習データを管理（キー: 合成元2文字、値: 合成結果1文字） |
| 90 | +- `TcodeMode.handle()`で文字入力後に`tryAutoBushu()`を実行 |
| 91 | +- 順序厳密: "木林"で学習したものは"林木"では自動変換されない |
| 92 | +- 自動変換もキャンセル可能（受容時は学習データ更新なし） |
| 93 | +- `bushu_auto.dic`に自動保存（統計データと同じタイミング） |
| 94 | +- 設定: `bushu.autoEnabled`, `bushu.autoFile` |
| 95 | + |
| 96 | +### 設定管理 |
| 97 | + |
| 98 | +`UserConfigs.shared`（シングルトン）が5つの設定カテゴリを管理: |
| 99 | +1. **MazegakiConfig**: 交ぜ書き変換設定、LRU学習設定 |
| 100 | +2. **BushuConfig**: 部首変換設定、自動部首変換学習設定 |
| 101 | +3. **KeyBindingsConfig**: キーバインド、基本文字配列（40x40） |
| 102 | +4. **UIConfig**: 候補選択キー、記号セット |
| 103 | +5. **SystemConfig**: 除外アプリ、ログ、統計同期間隔、キャンセル期間 |
| 104 | + |
| 105 | +設定変更は`UserConfigsDelegate`プロトコルで通知。 |
| 106 | + |
| 107 | +### 統計管理 |
| 108 | + |
| 109 | +`InputStats.shared`（シングルトン）: |
| 110 | +- スレッドセーフ（DispatchQueueで排他制御） |
| 111 | +- 基本文字、部首変換、交ぜ書き変換、機能実行をカウント |
| 112 | +- 定期的に`tc-record.txt`に出力（デフォルト1200秒間隔） |
| 113 | + |
| 114 | +## 重要なパターン |
| 115 | + |
| 116 | +1. **プロトコル指向**: `Mode`, `Controller`, `Client`などで責務を明確化 |
| 117 | +2. **シングルトン**: `UserConfigs.shared`, `InputStats.shared`, `MazegakiDict.i`, `Bushu.i` |
| 118 | +3. **モードスタック**: 候補選択などのサブモードを一時的にプッシュ |
| 119 | +4. **フォールバック**: クライアント → ミラーの順で読み取得、設定不正時はデフォルトで動作 |
| 120 | + |
| 121 | +## 主要ファイル |
| 122 | + |
| 123 | +| ファイル | 役割 | |
| 124 | +|---------|------| |
| 125 | +| `AppDelegate.swift` | IMKServer初期化、シグナルハンドラ、統計保存 | |
| 126 | +| `TcodeInputController.swift` | 入力制御の中核、モードスタック管理 | |
| 127 | +| `TcodeMode.swift` | 基本T-Code入力モード | |
| 128 | +| `KeymapResolver.swift` | キーシーケンス解決エンジン | |
| 129 | +| `ContextClient.swift` | テキスト読み取りの複雑なロジック | |
| 130 | +| `UserConfigs.swift` | 設定管理システム | |
| 131 | +| `Bushu.swift` | 部首変換アルゴリズム | |
| 132 | +| `MazegakiDict.swift` | 交ぜ書き辞書、LRU学習データ | |
| 133 | +| `PendingKakutei.swift` | 変換キャンセル機構 | |
| 134 | +| `InputStats.swift` | 統計管理 | |
| 135 | + |
| 136 | +## テスト |
| 137 | + |
| 138 | +テストは`MacTcodeTests/`に配置。最大規模のテストは`ContextClientTests.swift`（19253行）。 |
| 139 | + |
| 140 | +```bash |
| 141 | +make test # すべてのテストを実行 |
| 142 | +``` |
| 143 | + |
| 144 | +## 開発状況 |
| 145 | + |
| 146 | +完了した機能: |
| 147 | +- ✅ キャンセル期間機能（PendingKakutei） |
| 148 | +- ✅ 交ぜ書き候補LRU学習 |
| 149 | +- ✅ 自動部首変換機能 |
| 150 | + |
| 151 | +学習機能の実装はすべて完了。詳細は`TODO.md`を参照。 |
0 commit comments