From 1c99f6071938211314f9dccd04268091f42c3f4c Mon Sep 17 00:00:00 2001 From: EwdErna Date: Thu, 24 Sep 2026 22:39:50 +0900 Subject: [PATCH] =?UTF-8?q?hst:=20IME=E3=83=AC=E3=82=A4=E3=83=A4=E3=83=BC?= =?UTF-8?q?=E3=82=92HST=E3=83=AC=E3=82=A4=E3=83=A4=E3=83=BC=E3=81=A8?= =?UTF-8?q?=E3=81=97=E3=80=81=E3=83=9B=E3=82=B9=E3=83=88=E3=81=AB=E3=82=88?= =?UTF-8?q?=E3=82=8B=E3=82=AD=E3=83=BC=E3=82=B3=E3=83=BC=E3=83=89=E3=81=AE?= =?UTF-8?q?=E8=A7=A3=E9=87=88=E3=81=AE=E8=A8=98=E8=BF=B0=E3=81=AB=E7=AF=84?= =?UTF-8?q?=E5=9B=B2=E3=82=92=E7=B5=9E=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 役割はホスト(OS×ホスト配列)がキーコードをどう解釈するかの記述。IMEの変換はOSの責務で対象外 - データはキーボードに依存しないプロファイルの共有カタログ。識別はOS×ホスト配列(+入力方式) - プロファイルは順方向の表・成立の前提・対応可否(3値)だけを持つ。逆引きと実現可否の判断は使う側(P-1で要確認) - MAPはキーコードを保存し、逆引きは一方向の入力補助とする - 複数ホストの扱いをP-2とし、MAP-P-5の参照をHSTへ向ける Journal: journal/2026-09-24-hst-layer-scope.md Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017W6AsoJYTiN3bnxvSMS87f --- CLAUDE.md | 3 +- HSTレイヤー.md | 97 +++++++++++++++++++++++++++ MAPレイヤー.md | 2 +- PHYレイヤー.md | 2 +- backlog/README.md | 8 +-- journal/2026-09-24-hst-layer-scope.md | 35 ++++++++++ keyboard-design-layers.md | 11 +-- 7 files changed, 147 insertions(+), 11 deletions(-) create mode 100644 HSTレイヤー.md create mode 100644 journal/2026-09-24-hst-layer-scope.md diff --git a/CLAUDE.md b/CLAUDE.md index 7f0ea4b..7f83092 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # Beyond KLE キーボード設計のデータモデルとワークフローを再設計するプロジェクト。 -PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / IME(入力変換) の5層に分離する。 +PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / HST(ホスト) の5層に分離する。 - 応答・ドキュメントは日本語。 - 現状はコード未着手、設計ドキュメントのみ。 @@ -15,6 +15,7 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) | `ELCレイヤー.md` | ELC層の仕様 | | `IDXレイヤー.md` | IDX層の仕様 | | `MAPレイヤー.md` | MAP層とエディタの責務・実機との読み書き方針 | +| `HSTレイヤー.md` | HST層(ホストによるキーコードの解釈)の仕様 | | `phase1-json-schema.md` | 各層のJSON Schema | | `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 | | `implementation-plan.md` | 実装方針の決定事項・検証用サンプル | diff --git a/HSTレイヤー.md b/HSTレイヤー.md new file mode 100644 index 0000000..54d7854 --- /dev/null +++ b/HSTレイヤー.md @@ -0,0 +1,97 @@ +# HSTレイヤー + +## 概要 + +HST(ホスト)レイヤーは、接続先のホストがキーボードから受け取ったキーコードをどう解釈するかを記述する。 +MAPが出力するのはHIDのキーコードであり、画面上の文字や動作は、ホストのOSとキーボード配列の設定で決まる。 +HSTはこの対応を持ち、MAPエディタとFirmware Generatorが参照する。入力がHSTを通過するわけではない。 + +名前は、HIDでキーボード(device)の接続相手をhostと呼ぶことに合わせる。 +IMEのかな漢字変換はOSの仕事であり、HSTの対象外とする。 + +## プロファイル + +HSTのデータは、ホスト環境ごとのプロファイルの集まりとする。 +プロファイルはキーボードに依存しないため、プロジェクトの外にある共有カタログとして版を管理する。 +プロジェクトは、参照するプロファイルのIDと、利用者ごとの差分(XKBのオプションなど)だけを持つ。 + +### 識別 + +プロファイルは、OSとホスト配列の組で識別する。必要な場合だけ、入力方式やその設定を加える。 + +- ホスト配列は、OSがキーコードを解釈するための配列の設定である。キーキャップの刻印やOSの表示言語とは独立に決まる + (日本語のWindowsで英語配列を設定する、など)。 +- Linux(XKB)では、配列(layout)・変種(variant)・オプション(options)の組になる。 +- `win-jp` のような短い名前は、人が選ぶためのプリセット名として付ける。 +- 各OSの識別子(WindowsのKLID、XKBの名前、macOSの入力ソースID)と対応付けられるようにする。 + +```json +{ "os": "windows", "layout": "jp106" } +{ "os": "macos", "layout": "us" } +{ "os": "linux", "layout": "jp", "options": ["ctrl:nocaps"] } +``` + +「日本語入力を使う環境」のような設定は、プロファイルの識別に含める。 +IMEが今ONか、のような実行時の状態は識別に含めない(次節の引数として扱う)。 + +### 記述する内容 + +プロファイルは、順方向の対応だけを記述する。 + +```txt +(キーコード, 修飾キー, ホスト状態) → 文字 / 動作 / 未定義 / 不明 +``` + +- ホスト状態: CapsLock、かなロック、IMEのON/OFFなど、同じキーコードの結果を変える状態。 + HSTは状態の種類を引数として記述するだけで、実行時の状態を観測しない。 +- OS固有のキーの意味: `LANG1`/`LANG2`(Macのかな/英数)、変換/無変換、Cmd/Ctrlの役割など。 +- 成立の前提: 動作に必要なOS側の設定(Unicode入力の方式など)。HSTは設定を変更する機能を持たない。 +- 対応可否: 対応済み・未対応・不明の3値とする。カタログに載っていない動作を「使えない」と扱わない。 + +## 使う側の責務 + +HSTは逆引き(文字から、それを入力するキー操作を求めること)を持たない。 +逆引きは、使う側が順方向の表から求める[推測:P-1]。 + +- 順方向の表から導けるので、両方を持つと二重管理になる。 +- 逆引きの候補には、ファームウェアの機能に依存するものがある。 + 例えば、US刻印のキーキャップをJIS配列のホストで使う場合、Shiftの有無で文字の組が合わないキーには、 + Shift時に別のキーコードを送る機能(QMKのKey Override)が必要になる。 + これはホストの知識ではないため、HSTに持たせない。 + +使う側の担当は次のとおり。 + +- MAPエディタ: キーコードの表示、逆引きによる入力補助、対象ホストで意味を持たないキーコードの警告 +- Firmware Generator: `send_string` が前提にする配列、Unicode入力の方式など、ホストに依存する生成設定 + +## MAPとの境界 + +- MAPは具体的なキーコードを保存する。逆引きは編集時の入力補助であり、選んだ候補のキーコードをMAPへ書く一方向の変換とする。 + 実機に残るのはキーコードだけなので、この形なら実機との往復を単純に保てる。 +- HSTは割り当てを所有・変更しない。PHYのキーIDも参照しない。 + +## 対象外 + +- 実行時の状態の観測・同期(今どのOSに接続しているか、IMEがONか) +- OS設定の変更、IMEの変換処理 +- ホスト側での再割り当て(AutoHotkey、Karabiner、IMEのローマ字テーブルなど) +- アプリごとのショートカット(「コピー」のような操作の汎用的な辞書) + +## 検討済み・非採用 + +- 名前をSYSとする (journal/2026-09-24-hst-layer-scope.md) +- 逆引きの候補をプロファイルが持つ (journal/2026-09-24-hst-layer-scope.md) + +## 未確認事項 + +### P-1 使う側が逆引きの候補と実現可否を判断できる + +- 位置づけ: 本文「使う側の責務」が前提にしている。HSTにファームウェアの知識を持たせない線引きは、これが成り立つことに依存する。 +- 格上げ条件: US刻印のキーキャップをJIS配列のホストで使う構成で、Shiftの有無で文字の組が合わないキーについて、 + HSTの順方向の表と、Generatorのビルド設定(有効な機能)だけから、MAPエディタがKey Overrideを含む候補を作れることを試作で確認する。 + +### P-2 対象ホストを複数持つか + +- 位置づけ: 未解決の問い。Win/Mac両用のキーボードでは、表示と検証を複数のホストに対して行う必要がある。 + OSの切り替えをMAPのレイヤーで表す既存の慣習と、どう対応付けるかも関わる。 +- 完了条件: プロジェクトが参照するプロファイルの数と、MAPのレイヤーとの対応付けの有無をユーザーが決める。 diff --git a/MAPレイヤー.md b/MAPレイヤー.md index 1f07f6b..0a6edc0 100644 --- a/MAPレイヤー.md +++ b/MAPレイヤー.md @@ -120,7 +120,7 @@ VIAプロトコル0x000Dのコマンドのうち、MAPエディタが扱うも ## 持たないもの 物理配置、配線、キーの出力番号は、それぞれPHY・ELC・IDXで扱う。 -OS配列やIMEの入力変換はIME側の責務とし、外部ツールで編集できる照明等の設定も、 +ホストによるキーコードの解釈は[HSTレイヤー](HSTレイヤー.md)、IMEの入力変換はOSの責務とし、外部ツールで編集できる照明等の設定も、 VIAで通信できるという理由だけでMAPの所有データには含めない。 MAPエディタは、キーコードを当面US配列の文字で表示する。 diff --git a/PHYレイヤー.md b/PHYレイヤー.md index 4ffeb10..918f713 100644 --- a/PHYレイヤー.md +++ b/PHYレイヤー.md @@ -3,7 +3,7 @@ ## 概要 PHYレイヤーは、キースイッチやキーキャップ、その他周辺部品の物理的な配置に関する情報を提供する。 -付加的な情報として、matrix情報(ELCレイヤー)や入力キー情報(MAP/IMEレイヤー)を含ませることができるが、必須ではない。 +付加的な情報として、matrix情報(ELCレイヤー)や入力キー情報(MAP/HSTレイヤー)を含ませることができるが、必須ではない。 ## 構造 diff --git a/backlog/README.md b/backlog/README.md index 7ad159c..76a068b 100644 --- a/backlog/README.md +++ b/backlog/README.md @@ -114,12 +114,12 @@ ### MAP-P-5 キーコードを表示するOS配列 -- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「持たないもの」、[全体方針のIMEレイヤー](../keyboard-design-layers.md#5-imeレイヤー-入力変換) -- 未決事項: MAPエディタがキーコードをどのOS配列の文字で表示するか。IMEレイヤーの情報を使うか。 +- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「持たないもの」、[HSTレイヤー](../HSTレイヤー.md) +- 未決事項: MAPエディタがキーコードをどのOS配列の文字で表示するか。HSTのどのプロファイルを使うか。 少なくともUS/JISの切り替えは欲しい。利用者が増えれば他言語への対応も求められる。 - 保留できる理由: キーコードの割り当てと実機との読み書きは、表示に使うOS配列と独立して実装できる。 -- 再開条件: MAPエディタの表示を実装するとき、またはIMEレイヤーの仕様を検討するとき。 -- 完了条件: 表示に使うOS配列の指定方法と置き場所、IMEレイヤーとの関係をユーザーが決める。 +- 再開条件: MAPエディタの表示を実装するとき、またはHSTの[P-2](../HSTレイヤー.md#p-2-対象ホストを複数持つか)を決めるとき。 +- 完了条件: 表示に使うHSTプロファイルの指定方法と置き場所をユーザーが決める。 ### MAP-P-6 QMKのdevelopブランチ・Community Modulesへの対応 diff --git a/journal/2026-09-24-hst-layer-scope.md b/journal/2026-09-24-hst-layer-scope.md new file mode 100644 index 0000000..2a3b9ff --- /dev/null +++ b/journal/2026-09-24-hst-layer-scope.md @@ -0,0 +1,35 @@ +# IMEレイヤーの再定義(HST)と線引き + +## 結論 + +- IMEレイヤーをHST(ホスト)レイヤーに改める。役割は、ホストがキーコードをどう解釈するかの記述。IMEの変換はOSの仕事で対象外。 +- データは、ホスト環境ごとのプロファイルを集めた共有カタログ。キーボードに依存しない。プロジェクトはプロファイルのIDと差分だけを持つ。 +- 識別はOS×ホスト配列(+必要なら入力方式)。`win-jp` などはプリセット名。 +- プロファイルは順方向の表 f(キーコード, 修飾キー, ホスト状態) → 文字/動作/未定義/不明、成立の前提、対応可否(3値)だけを持つ。 +- 逆引き・候補の生成・ファームウェアでの実現はMAPエディタとGeneratorが行う。ユーザーは、これが実現できるかに不安がある → HSTのP-1。 +- MAPはキーコードを保存する。逆引きは入力補助で、一方向の変換。 +- 複数ホストの扱いは未決 → HSTのP-2。 + +## 案の比較 + +| 論点 | 当初の提案(人との議論) | Claude | Codex | 採用 | +|---|---|---|---|---| +| 名前 | SYS | HOST/HST | SYS → 最終的にHOST/HSTに同意 | HST | +| 識別子 | WIN-JAP (OS×言語) | OS×配列の構造 | OS×配列×入力方式+プロファイル名 | OS×配列(+入力方式) | +| 範囲 | OS・言語ごとのキーの振る舞い・表示 | ホストの解釈の記述 | 意図を環境ごとの出力に変換、まで候補 → 最終的に「対応関係を提供、変更はしない」 | 記述のみ | +| 逆引き | - | 使う側で順方向の表から求める | 候補と成立条件をプロファイルが持つ | 使う側 | +| ホスト状態 | - | 関数の引数として記述 | 設定と実行時の状態を分ける | 両方(矛盾しない) | + +## 根拠・経緯 + +- SYSは、HIDのSystem Control用途ページ(電源・スリープ)や「システム設定全般」と紛らわしい。hostはHIDでキーボードの接続相手を指す用語で、QMKも「host keyboard layout」と呼ぶ。 +- 言語は軸として誤り: 日本語Windowsで英語配列を使える。MacではUS/JISが入力ソースとキーボード種別で決まる。XKBはlayout/variant/optionsの3要素。 + 「英語」にもUS・UKがある。`JAP` はISOコードでもない(ja/jpn)。 +- 逆引きをプロファイルに持たせない理由: (1) 順方向の表から導けるので二重管理になる。 + (2) 候補がファームウェアの機能に依存する。例: US刻印+JISホストでShiftの組が合わないキーにはKey Overrideが要る。HSTにQMKの知識が混ざる。 +- Codexの指摘で採用したもの: 表示の切り替えと送信内容の変更を混ぜない。知らない動作を「使えない」と扱わない(対応可否を3値にする)。OS設定への依存は記述する。 +- MAPの正本をキーコードにする理由の修正: Claudeは当初「VIAでは実機にキーコードしか残らず、意図を復元できないので、キーコードでなければならない」とした。 + Codexが、意図をプロジェクト側に残す設計も可能で、難しくなるのは実機で変更された値の取り込みだけだと反論し、これが正しい。 + 採用する理由は「実機との往復を単純に保てるから」とする。 +- 「コピー」のような操作の辞書は、アプリやユーザー設定まで相手が広がるので対象外。 +- 未採用のアイデア: キートップの刻印生成にHSTを使う(PHYのラベルへ流す)。検討していないので仕様には書かない。 diff --git a/keyboard-design-layers.md b/keyboard-design-layers.md index 24dff69..aa30166 100644 --- a/keyboard-design-layers.md +++ b/keyboard-design-layers.md @@ -57,11 +57,14 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し - **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う - **詳細**: [MAPレイヤー](MAPレイヤー.md)。動作定義とキーごとの設定の保存形式は、[MAPのP-1](MAPレイヤー.md#p-1-動作定義とキーごとの設定の保存形式)で扱う -### 5. IMEレイヤー (入力変換) +### 5. HSTレイヤー (ホスト) -- **役割**: キーコードと実際の入力文字の対応 -- **対応ツール**: OS -- **備考**: MAPレイヤー設計時に考慮が必要 +- **役割**: 接続先のホスト(OSとキーボード配列の設定)が、キーコードをどう解釈するかの記述 +- **入力**: なし。どの層も参照せず、MAPエディタとFirmware Generatorから参照される +- **対応ツール**: OSのキーボード配列、QMKの言語別キーコード(`keymap_japanese.h` など) +- **出力**: ホスト環境ごとのプロファイル。キーボードに依存しない共有カタログとする +- **備考**: IMEのかな漢字変換はOSの責務で、HSTの対象外 +- **詳細**: [HSTレイヤー](HSTレイヤー.md) ## ツール設計方針