ewderna/Beyond-KLE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初期検討段階のドキュメントと運用ルールを取り込む

Browse Source 
ルール策定前に書かれた設計ドキュメント7点を、以降の基準点として
そのままの状態で記録する。CLAUDE.md のルール1〜4は未適用。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MdLT5x5ka5y6CaWLeE3EKb
This commit is contained in:
ewderna
2026-09-18 08:43:01 +09:00
co-authored by Claude Opus 5
commit 55243f626d
12 changed files with 2395 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
phase1-json-schema.md
+483
View File
@@ -0,0 +1,483 @@
# Phase 1: JSON Schema仕様策定
## レイヤー間データフロー
```
PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キーマップ)
↓ ↓
ファームウェア生成 VIA/Remap出力
```
## 1. PHYレイヤー JSON Schema
### 基本構造
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://beyond-kle.org/schemas/phy-layer.json",
"title": "PHY Layer - Physical Key Layout",
"description": "Physical positioning and sizing of keys",
"type": "object",
"required": ["version", "metadata", "profiles", "elements"],
"properties": {
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+$",
"description": "Schema version (semver)"
},
"metadata": {
"type": "object",
"properties": {
"name": { "type": "string" },
"author": { "type": "string" },
"description": { "type": "string" },
"created": { "type": "string", "format": "date-time" },
"modified": { "type": "string", "format": "date-time" }
}
},
"compatibility": {
"type": "object",
"description": "Information for external tool compatibility",
"properties": {
"kleJson": {
"type": "object",
"properties": {
"source": { "type": "string" },
"checksum": { "type": "string" },
"preservedFields": { "type": "array", "items": { "type": "string" } }
}
},
"originalFormat": {
"type": "string",
"enum": ["kle", "via", "qmk", "native"]
}
}
},
"profiles": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/profile"
}
},
"elements": {
"type": "array",
"items": {
"oneOf": [
{ "$ref": "#/$defs/key" },
{ "$ref": "#/$defs/cluster" }
]
}
}
},
"$defs": {
"profile": {
"type": "object",
"required": ["id", "name", "unitSize"],
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"unitSize": {
"type": "object",
"required": ["x", "y"],
"properties": {
"x": { "type": "number", "minimum": 0 },
"y": { "type": "number", "minimum": 0 }
}
},
"visualOffset": {
"type": "object",
"properties": {
"x": { "type": "number" },
"y": { "type": "number" },
"radius": { "type": "number", "minimum": 0 }
}
}
}
},
"key": {
"type": "object",
"required": ["type", "id", "profile", "position", "size"],
"properties": {
"type": {
"type": "string",
"const": "key"
},
"id": {
"type": "string",
"description": "Unique key identifier"
},
"profile": {
"type": "string",
"description": "Reference to profile ID"
},
"position": {
"type": "object",
"required": ["x", "y"],
"properties": {
"x": { "type": "number" },
"y": { "type": "number" },
"rotation": { "type": "number" },
"rotationOrigin": {
"type": "object",
"properties": {
"x": { "type": "number" },
"y": { "type": "number" }
}
}
}
},
"size": {
"type": "object",
"required": ["width", "height"],
"properties": {
"width": { "type": "number", "minimum": 0 },
"height": { "type": "number", "minimum": 0 }
}
},
"metadata": {
"type": "object",
"properties": {
"label": { "type": "string" },
"color": { "type": "string" },
"textColor": { "type": "string" },
"kleCompatibility": {
"type": "object",
"description": "Original KLE fields for round-trip compatibility",
"properties": {
"originalIndex": { "type": "integer" },
"labels": { "type": "array", "items": { "type": "string" } },
"textSizes": { "type": "array", "items": { "type": "number" } },
"decalData": { "type": "object" }
}
}
}
}
}
},
"cluster": {
"type": "object",
"required": ["type", "id", "name", "elements"],
"properties": {
"type": {
"type": "string",
"const": "cluster"
},
"id": { "type": "string" },
"name": { "type": "string" },
"position": {
"type": "object",
"properties": {
"x": { "type": "number" },
"y": { "type": "number" },
"rotation": { "type": "number" },
"rotationOrigin": {
"type": "object",
"properties": {
"x": { "type": "number" },
"y": { "type": "number" }
}
}
}
},
"elements": {
"type": "array",
"items": {
"oneOf": [
{ "$ref": "#/$defs/key" },
{ "$ref": "#/$defs/cluster" }
]
}
}
}
}
}
}
```
### 使用例
```json
{
"version": "1.0.0",
"metadata": {
"name": "Split Keyboard Layout",
"author": "John Doe",
"description": "Ergonomic split keyboard with rotated thumb clusters",
"created": "2025-01-01T00:00:00Z"
},
"profiles": [
{
"id": "standard",
"name": "Standard Cherry MX",
"unitSize": { "x": 19.05, "y": 19.05 },
"visualOffset": { "x": 1, "y": 1, "radius": 1 }
}
],
"elements": [
{
"type": "cluster",
"id": "left_main",
"name": "Left Main Block",
"position": {
"x": 0, "y": 0,
"rotation": 0,
"rotationOrigin": { "x": 3, "y": 2 }
},
"elements": [
{
"type": "key",
"id": "k00",
"profile": "standard",
"position": { "x": 0, "y": 0 },
"size": { "width": 1, "height": 1 },
"metadata": { "label": "Q" }
},
{
"type": "key",
"id": "k01",
"profile": "standard",
"position": { "x": 1, "y": 0 },
"size": { "width": 1, "height": 1 },
"metadata": { "label": "W" }
}
]
},
{
"type": "cluster",
"id": "left_thumb",
"name": "Left Thumb Cluster",
"position": {
"x": 2, "y": 3,
"rotation": 15,
"rotationOrigin": { "x": 1, "y": 0.5 }
},
"elements": [
{
"type": "key",
"id": "k30",
"profile": "standard",
"position": { "x": 0, "y": 0 },
"size": { "width": 1.25, "height": 1 },
"metadata": { "label": "Space" }
},
{
"type": "key",
"id": "k31",
"profile": "standard",
"position": { "x": 1.25, "y": 0 },
"size": { "width": 1, "height": 1 },
"metadata": { "label": "Enter" }
}
]
}
]
}
```
## 2. IDXレイヤー JSON Schema
### 基本構造
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://beyond-kle.org/schemas/idx-layer.json",
"title": "IDX Layer - Key Identification",
"description": "Mapping between physical keys and logical identifiers",
"type": "object",
"required": ["version", "phyReference", "keyMap"],
"properties": {
"version": { "type": "string" },
"phyReference": {
"type": "object",
"required": ["source", "checksum"],
"properties": {
"source": { "type": "string" },
"checksum": { "type": "string" }
}
},
"keyMap": {
"type": "array",
"items": {
"$ref": "#/$defs/keyMapping"
}
}
},
"$defs": {
"keyMapping": {
"type": "object",
"required": ["physicalId", "logicalId"],
"properties": {
"physicalId": {
"type": "string",
"description": "Reference to PHY layer key ID"
},
"logicalId": {
"type": "object",
"required": ["index"],
"properties": {
"index": { "type": "integer", "minimum": 0 },
"matrix": {
"type": "object",
"properties": {
"row": { "type": "integer", "minimum": 0 },
"col": { "type": "integer", "minimum": 0 }
}
},
"label": { "type": "string" }
}
}
}
}
}
}
```
## 3. ELCレイヤー JSON Schema
### 基本構造
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://beyond-kle.org/schemas/elc-layer.json",
"title": "ELC Layer - Electrical Configuration",
"description": "Electrical wiring and pin mapping",
"type": "object",
"required": ["version", "idxReference", "microcontroller", "matrix"],
"properties": {
"version": { "type": "string" },
"idxReference": {
"type": "object",
"required": ["source", "checksum"],
"properties": {
"source": { "type": "string" },
"checksum": { "type": "string" }
}
},
"microcontroller": {
"type": "object",
"required": ["type", "pinMapping"],
"properties": {
"type": { "type": "string" },
"pinMapping": {
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": { "type": "string" }
},
"cols": {
"type": "array",
"items": { "type": "string" }
}
}
}
}
},
"matrix": {
"type": "object",
"required": ["type", "dimensions"],
"properties": {
"type": {
"type": "string",
"enum": ["standard", "charlieplexing", "direct"]
},
"dimensions": {
"type": "object",
"required": ["rows", "cols"],
"properties": {
"rows": { "type": "integer", "minimum": 1 },
"cols": { "type": "integer", "minimum": 1 }
}
}
}
}
}
}
```
## 4. MAPレイヤー JSON Schema
### 基本構造
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://beyond-kle.org/schemas/map-layer.json",
"title": "MAP Layer - Keymap Configuration",
"description": "Key code assignments and layers",
"type": "object",
"required": ["version", "idxReference", "layers"],
"properties": {
"version": { "type": "string" },
"idxReference": {
"type": "object",
"required": ["source", "checksum"],
"properties": {
"source": { "type": "string" },
"checksum": { "type": "string" }
}
},
"layers": {
"type": "array",
"items": {
"$ref": "#/$defs/layer"
}
}
},
"$defs": {
"layer": {
"type": "object",
"required": ["id", "name", "keymap"],
"properties": {
"id": { "type": "integer", "minimum": 0 },
"name": { "type": "string" },
"keymap": {
"type": "array",
"items": {
"$ref": "#/$defs/keyAssignment"
}
}
}
},
"keyAssignment": {
"type": "object",
"required": ["keyIndex", "keycode"],
"properties": {
"keyIndex": { "type": "integer" },
"keycode": { "type": "string" }
}
}
}
}
```
## 変換フロー設計
### PHY → IDX変換
1. PHYレイヤーから物理キーリストを取得
2. 各キーに論理IDを割り当て
3. マトリックス座標の自動生成（行列最適化）
### IDX → ELC変換
1. マトリックス次元を算出
2. ピン配置の最適化提案
3. 配線効率の検証
### IDX + ELC → MAP変換
1. キーインデックス配列の生成
2. デフォルトキーマップの提案
3. VIA/QMK形式への出力
## 次のステップ
1. **TypeScriptでの型定義作成**
2. **変換ロジックのプロトタイプ実装**
3. **テストケース（60%、Split等）での検証**
4. **既存KLE JSONからの変換機能**