AIハヤト風の音声アシスタント制作方法│プログラミング初心者でもできたので共有します

````text
声で対話できるAIアシスタントを作ってください。
私はプログラミングができません。コードは全部お任せします。
専門用語を使わず、日本語で、何をしているか都度説明しながら進めてください。

════════════════════════════════════════
■ 作るもの
════════════════════════════════════════
音声対話モデルが「耳と口」、Claude Code CLI が「手」になるアシスタント。
・私が話しかけると音声で返事をする
・作業を頼むと Claude Code を別プロセスで起動して実行させる
・実行中もそのまま会話を続けられる
・終わったら向こうから口頭で報告してくる

════════════════════════════════════════
■ 技術的な前提
════════════════════════════════════════
・Python で作る
・音声モデルは Google の Gemini Live API（音声のまま入力し、音声のまま出力する
  ネイティブ音声モデル）を使う
・APIキーは環境変数から読む。絶対にコードに直接書かない
・設定は config.json にまとめ、私が後から書き換えられるようにする

【モデルの選び方 — 推測で書かないこと】
使えるモデル名は頻繁に変わります。必ず次の手順で実際に確かめてください。
 1. APIのモデル一覧を取得する
 2. bidiGenerateContent（双方向の音声対話）に対応しているものだけに絞る
 3. 翻訳専用・文字起こし専用・ロボット用などを除き、会話用の候補を2〜3個選ぶ
 4. 実際に接続し、同じ質問を投げて応答を比べる
 5. 結果を私に報告し、推奨を1つ挙げる
新しい世代のモデルの方が、指示の守り方・受け答えの自然さ・事実の正確さで
優れていることが多いです。ただし preview 版は仕様変更の可能性があるとも伝えてください。

（参考：OpenAI の Realtime API でも作れますが、日本語の固有名詞の発音が崩れやすく、
 音声の単価も数倍高いという実測結果があります。まず Gemini 側で作ってください。
 あとで切り替えられるよう、config.json の provider 一つで両対応にしておいてください。）

════════════════════════════════════════
■ 一番大事な要件：待たされないこと
════════════════════════════════════════
・タスクを投げる関数は即座に返り、すぐ会話に戻れること
・Claude Code はバックグラウンドで動き続けること
・完了したらアシスタントの方から自発的に報告してくること
・「今どうなってる?」と聞いたら状況を答えられること
・「やめて」と言ったら中断できること

実装のヒント：Claude Code CLI は次の形で非対話実行できます。
  claude -p "指示文" --output-format stream-json
これを子プロセスとして起動し、出力を読みながら進捗を拾ってください。

注意：Claude Code の中からこのアシスタントを起動すると環境変数が干渉して
認証に失敗します。子プロセスに渡す環境変数から CLAUDE_CODE_ 系を取り除いてください。

════════════════════════════════════════
■ 既知の落とし穴（実機で判明したもの。先回りで潰すこと）
════════════════════════════════════════
どれもコードを読むだけでは気づけず、動かして初めて出るものです。

【1】発話の終わりが判定できず永久に待つ
 節約のため無音を送らない作りにすると、サーバからは「まだ喋っている途中」に見えて
 永遠に応答が始まりません。
 → サーバ側の発話区切り判定を無効にし、こちらから「話し始め」「話し終わり」を
   明示的に通知する方式にする。
 → 何秒黙ったら終わりとみなすかは config.json で変更可能に（既定3秒）。

【2】ツール呼び出し後に固まる
 Gemini はツールを呼んだあと「ターン完了」を送らず、こちらの結果を待ちます。
 こちらも「ターン完了」を待つ作りだと、互いに待ち合って停止します。
 → ツール呼び出しを受け取った時点で、こちら側で区切りを立てる。

【3】画面描画が音声を殺す
 画面表示と音声受信を同じ流れで動かすと、描画が重いとき音が途切れます。
 実測で1フレーム254ミリ秒かかっていました（許容は33ミリ秒）。
 → 固定サイズの内部キャンバスに描いてから拡大する方式にし、
   ウィンドウの大きさと描画コストを切り離す。
 → フレーム時間を実測し、重いときは自動でコマ数を落として音声を優先する。

【4】音が途切れる・音割れする
 再生バッファが一瞬でも空になるたびに溜め直すと、音声はまとめて届くので
 発話の途中で普通に空になり、そのたび無音が入ってブツ切れになります。
 → 0.35秒以上空いたときだけ「発話の切れ目」とみなす。

【5】思考テキストが字幕に漏れる
 → 思考の出力をオフにし、思考フラグが付いたパートは読み飛ばす。

【6】無音を送って課金がかさむ
 → ローカルで音の大きさを見て、黙っている間は送信しない仕組みを入れる。
   暗騒音を自動学習し、それより一定以上大きいときだけ送る。
   どれだけ削減できたか表示できるようにする。

【7】しばらく放置すると勝手に終了する
 リアルタイム音声接続にはセッション時間制限があり、サーバから切断されます。
 切断でアプリごと終了する作りだと「ターミナルは残っているのに本体だけ落ちる」
 という状態になります。
 → 私が終了を選んでいない限りアプリを終了せず、自動で繋ぎ直す。
 → サーバから切断予告が来たら、切れる前に先回りして繋ぎ直す。
 → 再接続時はセッション設定を送り直し、接続をまたぐ状態はリセットする。
 → ただし繋いだ直後にまた切れる異常時に無限再接続しないよう、
   再試行の間隔を空ける（最大30秒程度まで広げる）。

【8】装飾記号で音声が壊れる ★見つけにくい
 設定ファイルや資料に ** などの装飾記号があると、モデルが書式ごと真似て
 発話テキストに記号を混ぜ、音声合成が壊れます。
 実際に、特定の質問で音声が一切返らなくなりました（無音のままターン終了）。
 → 渡す資料には装飾記号を使わない。
 → システムプロンプトにも「装飾記号を文章に混ぜない」と明記する。

════════════════════════════════════════
■ 起動まわり（プログラミングを知らない人でも使える形に）
════════════════════════════════════════
・すべてエクスプローラーからダブルクリックで完結すること
・.ps1（PowerShell）は使わない。Windowsの実行ポリシーで既定ブロックされ、
  初心者が必ず詰まります。起動用はすべて .cmd にする
・.cmd の中身は ASCII のみ。バッチファイルに日本語を書くと文字コードの
  食い違いで if ブロックごと壊れます（実際に壊れました）
・日本語メッセージはすべて Python 側で出す
・.cmd の先頭で chcp 65001 し、Python は UTF-8 で出力する

作ってほしいファイル：
 setup.cmd   … 仮想環境を作り、必要なパッケージを入れ、最後に環境チェック
 run.cmd     … 起動
 set-key.cmd … APIキーを貼り付けて保存。保存前に本当に使えるキーか実際に
               問い合わせて検証し、駄目なら保存せず理由を教える。
               コピー時に紛れ込む余計な空白や見えない文字は自動除去する
 doctor.py   … 何が足りないかを日本語で一覧表示する環境チェック

════════════════════════════════════════
■ 権限とコスト表示
════════════════════════════════════════
【権限】
Claude Code の権限モードを acceptEdits にすると、自動許可されるのは
「ファイルの作成・編集」だけです。ウェブ検索やシェルコマンドは拒否されます。
→ 必要なものだけ --allowedTools で個別に許可する形にする。
→ 全部通す bypassPermissions は使わない。
  声の聞き間違いがそのまま実行されると危険なため。

【コスト表示】
・起動してからの累計料金を画面に常時表示（円とドル）
・音声モデルと Claude Code の合計で
・コンソールに /cost と打つと内訳が見られるように
・終了時にも表示

════════════════════════════════════════
■ 記憶させる仕組み（memory.md）
════════════════════════════════════════
・memory.md というテキストファイル1枚にする
・起動のたびに、その内容をシステムプロンプトに差し込む
・メモ帳で直接編集できること
・声で「これ覚えておいて」と言ったら追記されること

【注意1】見出しを探すとき、# の数（見出しレベル）を決め打ちにしないこと。
決め打ちにすると既存の見出しを見つけられず、同じ名前の見出しを新しく作り、
矛盾した情報が2箇所に残ります。実際にこれで誤作動しました。

【注意2】memory.md の中で ** による装飾を使わないこと（落とし穴8）。

【注意3】memory.md の内容は、システムプロンプトの一番最後に置くこと。
長い指示文の途中に埋もれると、モデルが参照し損ねます。

════════════════════════════════════════
■ 固有名詞を正しく読ませる ★意外な落とし穴
════════════════════════════════════════
人名・社名・作品名を高い確率で誤読します。
しかも「読み方の一覧表」を渡すだけでは直りません。

【原因】
モデルが出力した「文字」が、そのまま音になります。
漢字のまま出力されると、音声合成がその漢字を勝手に読み、読み方の表は無視されます。
表は「読み方を聞かれたら答える」のには効きますが、
「会話の中で名前を口にするとき」には使われません。

【対策】
memory.md の読み方の表に「話すときの書き方」という列を作り、カタカナを書く。
そのうえでシステムプロンプトに
「表にある固有名詞は、漢字で書かず、そのカタカナをそのまま書く」と指示する。

例：
 表記     | 話すときの書き方 | 読み
 東海林   | ショウジ         | しょうじ
 一色     | イッシキ         | いっしき

【もうひとつ】
固有名詞の直後に助詞の「と」が来ると、音が繋がって別の語に聞こえます。
（「〇〇とお読みします」→「〇〇ト」に聞こえる）
確認するときは「読み方は〇〇で合っていますか」のように、
固有名詞の直後に「と」が来ない言い方にさせてください。

════════════════════════════════════════
■ 話し方
════════════════════════════════════════
システムプロンプトに以下を入れてください。

・常に日本語。テンポよく、1〜2文で短く。長い前置きはしない
・「〜ですね」「説明します」「承知しました」のような前置きを置かず、
  いきなり本題から話す
・知っている内容の出どころを口に出さない。
  「メモリに登録されている情報では」「資料によると」は言わない。
  自分が元から知っていることとして答える
・知らないことは言い訳を並べず「そこまでは分かりません」と短く言う。
  知ったかぶりで作り話をしない
・記号やURLをそのまま読み上げない。装飾記号を文章に混ぜない
・パスは「〇〇フォルダ」のように言い換える
・相手が考え中のときは黙って待つ。相槌を連発しない
・破壊的な操作（大量削除、上書き、git push）を含む依頼は、
  実行前に必ず口頭で確認を取る

════════════════════════════════════════
■ 検証のしかた ★ここを省略しないこと
════════════════════════════════════════
「読み方を答えて」と聞くテストでは正しく答えるので、直った気になります。
実際の使用条件と違うためです。必ず次の条件で確かめてください。

・毎回まっさらな接続を張る（起動直後の1問目と同じ条件）
・読み方を聞かず、普通の質問をする
・出てきた音声をファイルに書き出し、文字起こしして実際の音を確認する
 （faster-whisper などを使う。字幕テキストが正しくても実音が違うことがあります）

この方法で測ったところ、対策前は5問中0問しか正しく読めていませんでした。

作ってほしい検証ツール：
 smoke_test.py … マイクを使わず、接続・音声生成・ツール呼び出し・完了報告を検証
 doctor.py     … 環境チェック（キー・パッケージ・Claude Code のログイン状態）
 音声デバイスの一覧を表示するコマンド

════════════════════════════════════════
■ 進め方
════════════════════════════════════════
1. まず全体の構成を、専門用語なしで説明してください。私が納得してから実装に入ること
2. モデルの候補を実際に接続して比較し、推奨を報告すること
3. 実装は段階的に進め、区切りごとに「今どこまでできたか」を教えてください
4. 未検証のものは「未検証」と必ず明示してください
5. 完成報告には、途中で何を失敗してどう直したかも書いてください
6. 最後に、実機で分かった落とし穴を README にまとめてください

作業を始める前に、分からない点があれば質問してください。
````