技術仕様・設計

開発者向けセットアップ・開発手順書 (Developer Guide)

fjFlow のソースコードを変更、テスト検証、およびビルドする開発者向けの技術手順書です。...

開発環境の構築からテスト実行、ビルド、コーディング規約までの完全開発手順ガイド

fjFlow のソースコードを変更、テスト検証、およびビルドする開発者向けの技術手順書です。

目次

1. 開発環境のセットアップ手順

  1. AutoHotkey v2 公式サイト から AutoHotkey v2（v2.0.0 以降）をダウンロードしてインストールします。
  2. Git ターミナルを開き、リポジトリをクローンします： 
    git clone https://github.com/vojodeespero-wq/fjFlow.git
cd fjFlow
  3. エディタ（VS Code 推奨、拡張機能: AutoHotkey v2 Language Support）でプロジェクトフォルダを開きます。

2. ソースコードからスクリプトを実行・デバッグする手順

  1. PowerShell ターミナルを開きます。
  2. 以下のコマンドでプロ版スクリプトを直接実行します： 
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; & "fjFlow.ahk"
  3. タスクトレイに fjFlow アイコンが表示され、即座にキャレット追従およびキー拡張が開始されます。
  4. コードを変更した後は、トレイメニューから 再起動 (Restart) をクリックするか、Ctrl + Shift + F5 等でリロードして変更を反映します。

3. 自動サニティテストスイートを実行する手順 (test.ps1)

コードの修正完了時は、必ずサニティテストを実行して全項目の合格を確認します。

  1. PowerShell で以下のテストコマンドを実行します： 
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\test.ps1
  2. 以下のテストが直列実行されます：
    • AHK 構文検証（全スクリプトのパースチェック）
    • ユニット / ロジックテスト（キーパース、FSMバイパス判定、バリデーション、設定整合性等）
    • 実プロセス起動スモークテスト（PID 監視による実機ランタイム安定性確認）
  3. 画面に ALL SANITY TESTS PASSED! (Ready to ship / commit) と表示され、エラーがゼロであることを確認します。

4. 配布用スタンドアロン実行ファイルをビルドする手順 (build.ps1)

配布用の実行ファイル（.exe）を生成する手順です。

  1. PowerShell で以下のビルドスクリプトを実行します： 
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\build.ps1
  2. build\ ディレクトリに fjFlow_Pro.exe（プロ版）および fjFlow_Free.exe（フリー版）がコンパイル出力されます。

5. 重要な実装規約とバグ回避ルール

5.1 キーボードレイアウト（JIS/US）判定規約

  • 物理キーボード判定（GetKeyboardType）は使用しません（OS上で論理的に配列を切り替えている環境で誤判定するため）。
  • 必ず GetForegroundWindow ➔ GetWindowThreadProcessId ➔ GetKeyboardLayout の順で取得し、取得失敗時は SPI_GETDEFAULTINPUTLANG (0x0059) でフォールバック判定を行います。

5.2 レイヤードウィンドウ (WS_EX_LAYERED) の実体化規約

  • WS_EX_LAYERED（0x80000）スタイルを持つウィンドウを作成した際は、初回 UpdateLayeredWindow を呼ぶ前に、必ず Show("NA x0 y0 w1 h1") ➔ Hide() を実行してOS上でウィンドウを実体化させます（描画領域が確保されず透明になるバグを回避するため）。

5.3 InputHook とキー送信の競合回避規約

  • InputHook 動作中に修飾キーを伴う合成キーを送信する際は、SendInput ではなく SendEvent を使用し、SetKeyDelay(-1, -1) を設定して、送信直前にフックを一時停止（Stop()）させます。

5.4 #Include モジュール内での静的ホットキー配置の禁止

  • #Include されたファイル内に静的ホットキー構文（key::）を記述すると、Auto-Execute セクションが強制終了されます。モジュール側では必ず動的登録関数（HotIf + Hotkey()）を作成し、メインスクリプトから呼び出します。