device-check

name	device-check
description	実機をシリアル越しに操作して挙動を確認する。tools/deck.py で JSON Lines を投げ、人間にしかできない確認は手順書にして渡す。ビルドが通ったあと、動いたと言い切る前に使う。

実機チェック

ビルドが通っただけでは何も確認していない。実機に触る。 エージェントが自分でできることと、人間に頼むことを最初に切り分ける。

エージェントが自分でできること

tools/deck.py でシリアルプロトコルを直接叩ける。これで仕様 §6 のコマンドは 全部確認できる。

uv run python tools/deck.py list                     # ポート確認
uv run python tools/deck.py hello                    # 疎通と状態（sd / ble）
uv run python tools/deck.py get                      # 現在の設定
uv run python tools/deck.py set config.example.json  # RAM に反映（保存はしない）
uv run python tools/deck.py preview 0 3              # ボタンのアクションを実際に送出
uv run python tools/deck.py icons
uv run python tools/deck.py raw '{"cmd":"bogus"}'    # 異常系

必ず異常系も試す。仕様の受け入れ基準はほとんどが異常系:

• 壊れた JSON を送る → エラー行が返り、接続は維持される
• 未知のキー名を含む設定を送る → 拒否され、既存の設定が壊れていない （送った後に get して確認する。ここまでやって初めて確認したと言える）
• 16KB を超える行を送る → エラー
• SD を抜いた状態での save → NVS にフォールバック

save は連打しない。 フラッシュの消去回数には上限がある（仕様 §7）。 deck.py save は --yes を付けないと実行されないようにしてある。

人間に頼むこと

物理操作と目視は代われない。頼むときは具体的な手順と、何を見てほしいかの 期待値を書く。曖昧な「動作確認お願いします」は返ってくる情報が少ない。

書式の例:

以下を確認してください。

1. 画面のボタン「Copy」をタップ → メモ帳にフォーカスした状態で Ctrl+C が 効くこと（何かを選択してからタップ）
2. 3 分放置 → 画面が消えること。そこから 1 回タップ → キーは送出されず 画面だけ復帰すること
3. 画面下の左右のドットをタップ → レイヤーが前後に切り替わり、 ステータスバーの名前が変わること

BLE のペアリング、キー入力が実際に届くか、電池表示、タッチの取りこぼしは すべてこちら側。

触覚フィードバック（振動）は実装していない。実機で駆動できなかったため 仕様から意図的に外してある（README「仕様との差分」）。確認項目に入れないこと。

設定ページ（web/）の確認

file:// では Web Serial が動かない。ローカルサーバー経由で開く:

uv run python -m http.server 8000 --directory web

ブラウザ自動化で http://localhost:8000 を開き、スクリーンショットを撮って 実際に目で見る（レイアウト崩れは HTML を読んでも分からない）。 ただし navigator.serial.requestPort() のポート選択ダイアログはブラウザの ネイティブ UI なので自動化では越えられない。そこから先は人間に頼む。

記録

確認したら notes/ に残す。コマンドとその実際の出力を貼る（手打ちしない）。 スクリーンショットがあれば一緒に。これが PR に添える証拠になる。

見つけたバグ

/red-green-tdd で直す。実機でしか気づけなかったバグこそ、ホスト側のテストに 落とし込む価値がある。落とし込めない形なら、それは層の切り分けが甘いサイン。