# ローカル生成メディア・ハブ 設計書（共有用）

> この文書は、GPU を搭載した自宅 PC とスマートフォンを連携させ、画像・動画・音声の生成とローカル LLM チャットを1つの個人用アプリから扱うための再現可能な設計書である。特定の個人・環境に依存する固有名詞や個人情報は含まない。前提環境の差（GPU の性能、PC の OS、スマホが Android か iPhone か）に応じた読み替え箇所を各所に明記した。
>
> 想定読者：この設計書を受け取って実装する AI エージェント、およびそのユーザー。

---

## 0. 実装を始める前に（必須の工程：機能選択）

**実装に着手する前に、必ずユーザーに「全部入りで作るか、一部の機能だけにするか」を確認すること。** このシステムは機能単位で独立性が高く、部分実装でも破綻しないように設計されている。確認せずに全部入りで進めてはいけない。

### 0.1 機能グループ一覧

| # | 機能グループ | 依存 | 概要 |
|---|---|---|---|
| F1 | 画像生成 | なし（基盤） | テキスト→画像。モデル/LoRA 管理、Civitai からの導入、バッチ生成 |
| F2 | 画像編集 | F1 | img2img / inpaint / outpaint / タグ付け / モザイク等の後処理 |
| F3 | ギャラリー＆ロック | F1 | 生成物の閲覧・整理。生体認証/PIN で開くロックフォルダ |
| F4 | ローカル LLM チャット | なし（基盤のみ） | PC 上の LLM とのチャット、会話履歴は端末内のみ |
| F5 | 動画生成 | F1（画像→動画チェーン時） | テキスト→動画 / 画像→動画 / 画像生成→動画のチェーン |
| F6 | 音声制作 | F4（台本の LLM 制作時） | 依頼→台本→チェック→承認→TTS 合成→納品のパイプライン |
| F7 | エージェント提案 | F4 + 対象機能 | LLM が生成系操作を「提案カード」として出し、実行はユーザーのタップのみ |

### 0.2 確認の進め方

1. 上表をユーザーに提示し、欲しい機能グループを選んでもらう（例：「画像だけ」「画像＋チャット」「全部」など）。
2. 選ばれなかった機能については、**API の口と DB の受け皿だけ先に用意し、実装はしない**（後から追加できる形を保つ）。タブや画面も作らない。
3. 選択結果を実装計画の冒頭に記録し、フェーズ計画（§11）を選択に合わせて削る。
4. 環境確認も同時に行う：GPU の型番と VRAM、PC の OS、スマホの OS とバージョン、PC の常時起動可否。これらで §2.3 の分岐が決まる。

---

## 1. 目的と原則

### 1.1 目的

- 自宅 PC の GPU を、スマホから安全に使える「個人専用の生成メディア・ハブ」にする。
- 生成物（画像・動画・音声）は原則 PC 側に保存し、スマホは操作と閲覧に徹する。
- ローカル LLM によるチャットも同じハブ経由で提供し、会話履歴は端末から出さない。

### 1.2 設計原則（全機能共通）

1. **ヘルパー経由主義**：スマホアプリは生成エンジン（ComfyUI 等）に直接触らない。PC 側に常駐する小さな API サーバー（以下「ヘルパー」）が唯一の入口となり、認証・検証・キュー管理・ファイル配置を担う。
2. **内容の不干渉**：ヘルパーおよびエージェントは、ユーザーのプロンプトや生成物の「内容」を審査・拒否・書き換え・削除しない。行うのは形式検証（型・範囲・必須項目）のみ。これはユーザーの自宅・自分の PC・自分のデータに対する当然の前提として設計に組み込む。
3. **任意 JSON を受けない**：ワークフロー JSON のような自由形式のリクエストは受け付けない。パラメータは型付きフィールドで受け、ワークフロー構築はヘルパー側のテンプレートだけが行う。
4. **秘密情報の所在を固定**：外部サービスの API キー等は PC 側にのみ置き、スマホや LLM のコンテキストには決して渡さない。
5. **ロックはフォルダモデル**：秘匿は「保存先フォルダの選択」で実現する。通常フォルダとロックフォルダを物理的に分け、ロック側のデータは認証が済むまで一切取得しない。
6. **GPU は単一資源として調停**：画像・動画・音声・LLM は同じ GPU を取り合う。調停ルールを一箇所（ヘルパー）に集約し、「実行中ジョブを勝手に止めない」を絶対規則とする（停止はユーザー操作のみ）。

---

## 2. 全体アーキテクチャ

### 2.1 構成図

```
[スマホアプリ] --(VPN/テイルネット越し HTTPS or HTTP+トークン)--> [ヘルパー (PC常駐)]
                                                                    |
        +-----------------------------------------------------------+
        |                    |                    |                 |
   [生成エンジン]        [LLM ランタイム]      [TTS エンジン]   [ファイル保存]
   ComfyUI 専用          Ollama 等             TTS バッチ       生成物フォルダ群
   インスタンス                               ラッパー          (通常/ロック × 媒体別)
```

- スマホと PC の接続は、Tailscale 等のプライベート VPN（テイルネット）を前提とする。公衆インターネットへの直接公開はしない。
- ヘルパーは VPN インターフェースにのみバインドするか、ファイアウォールで接続元を「自分のスマホと自分の他デバイス」に限定する。

### 2.2 コンポーネント

| コンポーネント | 役割 | 実装の目安 |
|---|---|---|
| スマホアプリ | 操作 UI、会話履歴の保持、ロック認証、再生 | Android: Kotlin + Jetpack Compose（参照実装）。iPhone: §2.3 参照 |
| ヘルパー | API、認証、ジョブ管理、ワークフロー構築、GPU 調停、ファイル管理 | Python + FastAPI + SQLite (WAL) |
| 生成エンジン | 画像・動画生成 | ComfyUI をアプリ専用ポートで別インスタンス起動 |
| LLM ランタイム | チャット推論 | Ollama 等（OpenAI 互換でも可） |
| TTS ラッパー | 音声合成のバッチ実行 | TTS エンジンを「モデルを1回読み、全行を連続合成」するラッパー経由で呼ぶ（§8.4） |

### 2.3 環境差の読み替え

**GPU（VRAM）**：
- 24GB 級（例：RTX 4090/3090）：本書の実測値がそのまま目安になる。動画 14B 級モデルも（オフロード併用で）動作する。
- 16GB 級：画像生成と 5B 級動画は快適。14B 級動画はオフロード過多で実用外になりやすいので、モデル選択肢から外すか「超低速」明記にする。TTS 大モデルは精度を下げた設定（bf16）を既定にする。
- 12GB 級：画像生成中心。動画は短尺・低解像度のみ。LLM は量子化モデル前提で、生成との同時常駐を避ける調停を強める。
- AMD GPU / Apple Silicon：生成エンジン側の対応状況に依存する。本書のワークフロー構築の考え方（テンプレート化・パラメータ検証）はそのまま使えるが、ノード構成と実測値は環境ごとに取り直すこと。

**PC の OS**：
- Windows / Linux どちらでもよい。ヘルパーは OS 非依存に書く。差が出るのは「自動起動の仕組み」（Windows：ログオンタスク / Linux：systemd ユーザーサービス）と「ファイアウォール設定」の手順だけ。
- PC がスリープすると全機能が止まる。前提としてスリープ無効化＋「再起動後はユーザーが一度ログインすれば全サービスが自動で揃う」状態を作る。

**スマホ**：
- Android（参照実装）：サイドロード前提の個人アプリ。署名キーは**必ず固定のキーストアをプロジェクト内に保持**すること（開発環境の既定デバッグ鍵は環境が変わると再生成され、上書きインストールが壊れる。実際に踏むと再登録からやり直しになる）。
- iPhone：同一設計で実装可能だが、(1) 配布は TestFlight か開発者署名に限られる、(2) バックグラウンド再生は AVAudioSession + MediaSession 相当の枠組みを使う、(3) ファイル共有まわりは Android の MediaStore と作法が違う、という差がある。代替として「Web アプリ（PWA）＋同じヘルパー API」でも大半の機能は実現できる（ロック認証はパスコード＋WebAuthn 等で代替）。

---

## 3. データと保存

### 3.1 保存レイアウト（PC 側、1ルート配下に集約）

```
<ROOT>/
  helper/            ヘルパー本体と設定・DB
  outputs/           画像（通常）YYYY/MM/DD/
  outputs_locked/    画像（ロック）
  outputs_video/     動画（通常）
  outputs_video_locked/
  outputs_audio/     音声（通常、wav + mp3 サイドカー）
  outputs_audio_locked/
  staging/           アップロード・中間ファイル（期限付きで掃除）
  models_staging/    モデル導入時の一時置き場
  models_trash/      削除したモデルの退避（復旧可能に）
  audio/profiles/    音声プロファイル正本（§8.2）
  audio/se/          SE ライブラリ（カテゴリ別フォルダ）
  audio/work/        音声制作の作業領域
  logs/              エラーログ（会話本文やプロンプト本文は記録しない）
```

- 生成物の索引は DB（outputs テーブル）が持ち、実ファイルは日付階層に置く。コレクション（論理フォルダ）は DB 上の分類のみで、ファイルは移動しない。
- 削除は即消去ではなくゴミ箱方式（7日後に自動消去）。

### 3.2 主要テーブル

- `devices`：登録デバイス（トークンの SHA256 ハッシュのみ保存、失効フラグ）
- `jobs`：全ジョブ共通（kind、状態、進捗、パラメータ JSON、冪等キー、エラー）
- `outputs`：生成物索引（media_type: image/video/audio、保存先ルート、日時、長さ、生成パラメータ）
- `audio_requests`：音声依頼（§8）
- `kv`：ロック用 PIN ハッシュ、制作用トークンのハッシュ等の単発値

### 3.3 端末側にだけ置くもの

- LLM チャットの会話履歴と要約（端末内 DB。ロック会話は暗号化）
- デバイストークン（端末の安全なストレージに暗号化保存）
- モーションプリセット等の小さな辞書類

会話本文を PC 側に保存しないのが原則。例外は音声依頼の台本のみ（制作のために PC 側 DB に置く。§8.1）。

---

## 4. 認証とセキュリティ

### 4.1 デバイス登録

1. PC 側で管理 CLI がワンタイム登録コードを発行する（有効期限10分、保存はハッシュのみ、発行時に旧コードを無効化）。
2. アプリがコード＋デバイス公開鍵を送り、ヘルパーがデバイストークンを返す。以後すべての API は `Authorization: Bearer <token>`。
3. トークン自体に有効期限は設けない（個人運用）。失効は PC 側 CLI でいつでも可能。アプリ側はトークンを端末の鍵ストアで暗号化して保存し、**上書きインストールでは保持される**（アンインストールやデータ消去でのみ再登録が必要、という運用をユーザーに明示する）。

### 4.2 接続元の限定

- ヘルパーの待ち受けは VPN インターフェースに限定し、ファイアウォールでも「自分のスマホ＋自分の他デバイス」のアドレスだけを許可する二重化が望ましい。
- スマホの VPN アドレスが変わる（再登録等）と接続できなくなる。その場合はファイアウォール規則のアドレスを更新する運用手順を用意しておく。

### 4.3 ロック（秘匿フォルダ）

- PIN は Argon2id 等でハッシュ保存。生体認証は端末の鍵で署名し、ヘルパーが検証する方式（ECDSA 署名＋ノンス）。
- ロック解除はサーバー側セッション（TTL 15分程度、無操作で再ロック）。
- ロック側の生成物は、未認証の間はサムネイルすら返さない。
- アプリ側の画面保護（スクリーンショット禁止等）はユーザーの好みで選べる設計にする（強制しない）。

### 4.4 制作用トークン（音声の外部制作を使う場合のみ）

- 外部の制作エージェントに音声依頼だけを触らせるための、権限を列挙型で絞った専用トークンを別途用意する。
- 読めるのは「自分が担当する種別の依頼」だけ。画像・チャット・他種別の依頼・ロック閲覧・診断情報にはアクセスできない。
- 納品はステージング経由のドロップボックス方式（置いた物は読み戻せない）。
- 承認操作をこのトークンに許可するかどうかは設計上の分岐点。許可する場合は監査ログに経路を残す。

### 4.5 メンテナンス経路の分離

- 運用保守用のリモートアクセス（SSH 等）は、アプリの通常経路とは分離し、診断コマンドだけを実行できる強制コマンド方式にする（状態・ディスク・キューの確認のみ。任意コマンド不可）。
- ヘルパー本体の更新（コード差し替え）はユーザーの明示承認を必須とし、勝手に差し替えない。

---

## 5. ヘルパー API の骨格

機能グループ単位でエンドポイントを分ける。部分実装では、選んだグループの分だけ実装すればよい。共通事項：

- すべての変更系 POST は冪等キー必須（同じキーの再送は同じジョブを返す）。
- エラーは `{error: コード, error_id: 短いID}` の形で返し、詳細は PC 側ログへ。ユーザー向け表示には error_id を添える（問い合わせ・ログ照合用）。
- 生成系はすべて非同期ジョブ（投入→ポーリング or 進捗ストリーム）。

| グループ | 主なエンドポイント |
|---|---|
| 基盤 | `GET /api/health`（状態＋GPU情報）、`POST /api/register`、管理 CLI（コード発行/失効/状態） |
| F1 画像 | `POST /api/gen`、`GET /api/gen/{id}`、`GET /api/models`、`DELETE /api/models/{id}`、Civitai 検索/導入 |
| F2 編集 | `POST /api/upload`（端末画像の取り込み、24時間で失効）、生成と同じジョブ基盤に kind を変えて投入 |
| F3 ギャラリー | `GET /api/outputs?media=image|video|audio`、サムネイル、原本（Range 対応）、移動/ゴミ箱/復元、コレクション |
| F4 チャット | `GET /api/llm/models`、チャット（ストリーミング中継）、GPU 解放 |
| F5 動画 | `GET /api/video/models`、`POST /api/video`（§7） |
| F6 音声 | プロファイル、依頼 CRUD、台本保存、チェック、承認、制作、SE 一覧/配信、制作用トークンの各エンドポイント（§8） |
| GPU | `GET /api/gpu`（常駐エンジン、VRAM、実行中ジョブ種別）、`POST /api/gpu/unload` |

---

## 6. 画像生成（F1/F2/F3）

### 6.1 生成テンプレート

- モデルごとに「実証済みの生成チェーン」をテンプレートとしてヘルパーに持つ（基本生成＋任意で高解像度化・顔補正・LoRA 等）。アプリはパラメータだけを送る。
- モデルによって使えない工程がある場合は、**アプリ側で該当 UI を無効化し、送信時にも自動で取り除く**（サーバー側エラーに頼らない）。
- バッチは2概念に分ける：「バッチサイズ（1回の生成枚数）」と「バッチ回数（投入の繰り返し）」。シード固定時は回ごとにバッチサイズ分ずらす（一般的な画像生成ツールの慣習に合わせる）。上限は VRAM 実測で決める（24GB 級で 832×1216＋高解像度化＋顔補正のチェーンならバッチ8でも余裕があった、という実測が目安）。

### 6.2 モデル/LoRA の導入

- 外部配布サイト（Civitai 等）の検索→詳細→導入をアプリから行えるようにする。API キーは PC 側にのみ置く。
- 導入フローは「容量確認→ステージングへダウンロード→形式検証（safetensors ヘッダ）とハッシュ照合→正式配置→台帳登録」を厳密に踏む。検証に失敗したファイルは隔離フォルダへ。
- 導入したモデルは台帳ファイル（JSON）に記録し、ヘルパー再起動なしで一覧へ反映する。削除は台帳から外し、ファイルをゴミ箱フォルダへ（復旧可能）。
- 対応ファミリーは段階的に広げる（最初は最も需要のある1系統のみ、等）。

### 6.3 画像編集（F2）

- img2img / inpaint / outpaint / タグ付け（画像→タグ推定）は、生成と同じジョブ基盤に kind を分けて実装する。
- 端末画像の取り込みは専用アップロード口から（upload_id を返し、24時間で失効）。
- モザイク/ぼかし/黒塗りのような単純な後処理は**端末側で完結**させる（PC に送らない）。範囲指定はブラシと矩形の両対応、効果の粗さはピクセル単位で指定できる形が使いやすい。

### 6.4 ギャラリー（F3）

- 媒体別フォルダ（画像/動画/音声）×通常/ロックの構造。画像はフル機能（検索、コレクション、ドラッグ範囲選択、高速スクロールバー、再生成＝生成パラメータの復元）。
- 「再生成」は生成時のパラメータを生成物に保存しておき、復元して編集画面に渡す（自動投入はしない）。
- 動画・音声は一覧＋その場再生＋通常ファイル操作（移動/ゴミ箱/端末へ保存）。

---

## 7. 動画生成（F5）

### 7.1 モードとモデル

- モードは3つ：**A** テキスト→動画、**B** 画像→動画、**C** 画像生成→動画のチェーン（既定は C が便利）。
- プロンプトは「画像用」と「モーション用」の2欄に分ける。モーション側には端末内で編集できるプリセット辞書を用意する。
- 入口は動画画面そのものに加え、画像の詳細画面からの「動画にする」（元画像をセットするだけ。自動投入しない）。
- モデルは複数登録できるようにし、各モデルに「対応モード・対応秒数・所要時間の目安テキスト」を持たせる。実測（24GB 級 GPU、704×1280、24fps）の目安：
  - 軽量モデル（5B 級、TI2V）：5秒で約3分、10秒で約9分。VRAM はほぼ全量を使う。
  - 大型モデル（14B 級、デュアル構成の I2V）：5秒で約52分（VRAM に収まらず部分オフロードになるため極端に遅い）。10秒は実用外として選択肢に出さない。TI2V 形態は存在せず I2V/T2V 形態のみ、というような「モデルファミリーの実在確認」をダウンロード前に必ず行うこと（存在しないファイル名は小さなエラーファイルとして落ちてくることがある）。
- 対応サイズは縦/横/正方形の数種に固定し、秒数はモデルごとの上限で制限する（例：軽量は10秒まで、大型は5秒固定）。

### 7.2 ジョブの扱い

- 動画ジョブは割り込み不可（途中で止めると成果が残らない）前提で、後続はキューで待つ。ただしユーザーだけが押せる停止ボタンを用意し、押せば現行が止まって後続が進む。
- 進捗はジョブセンター（§9.2）で他媒体と一緒に見せる。完了物は動画フォルダへ索引付けし、サムネイルは先頭フレームから作る。配信は Range リクエスト対応（シーク可能に）。

---

## 8. 音声制作（F6）

### 8.1 パイプライン

```
依頼作成 →（サイコロで未選択項目を決定）→ 台本作成 → 二重チェック → 承認 → 制作（TTS合成＋整音＋SE混合）→ 納品
```

- 依頼は「プロファイル」（§8.2）＋選択項目（構造化された選択肢群）で作る。未選択の項目はサーバー側でサイコロ（ランダム）を振って決め、結果は依頼に表示される（振り直し可）。
- 台本の作り方は2方式を依頼ごとに選べる：**A** 外部の制作エージェント（§4.4 の制作用トークン使用）、**B** アプリ内からローカル LLM に書かせる。承認後は共通の制作パイプラインに入る。
- 二重チェックは決定的なチェッカーで行う（例：用語ルールによる表記チェック、似すぎた隣接行の検出）。候補を返すだけにし、本文の自動書き換えはしない。チェックの有無や B の既定モデルは設定で選べるようにする（固定しない）。
- 依頼と台本は制作のため PC 側 DB に置く（チャット履歴の「端末のみ」原則の、明示された例外）。

### 8.2 プロファイル

- キャラ単位のプロファイルを持つ：選択肢グループ（行為・衣装・場所・展開・締め・体勢など）、強さ定義、長さ、サイコロ表（複数軸×複数面）、用語ルール、バイノーラルの左右対応表、シーンテンプレート等を1つの JSON にまとめる。
- 正本は PC 側に置き、端末は写しを持つ。
- 声は「短い参照音声によるゼロショット・クローン」が基本。参照音声の登録経路は2つ：（1）PC 側へ直接渡す、（2）スマホで選んだ音声ファイルをアップロード（形式変換して 48kHz モノラル化、合計尺に上限）。声が固まったら話者埋め込みに焼く操作も用意できる。

### 8.3 TTS エンジンの実測上の注意（24GB 級での実測）

- 大モデル TTS はモデル読み込みコストが支配的（1行あたり数十秒の内訳の大半が起動）。**必ずバッチラッパー化**する：1プロセスがモデルを1回だけ読み、台本全行を連続合成して終了する。ワンショット終了で VRAM は完全に解放される。
- 大モデルは専有スロット扱い（画像生成と同時実行しない）。実測では画像エンジン常駐下でピーク 22GB 超に達した。
- 精度（fp32/bf16）：参照なし合成では両者はほぼ同一（波形相関 0.98 級）。参照クローンでは「声の同一性は保たれるが、読みのテイクが変わる」程度の差が出た。既定は bf16（高速・省 VRAM）、fp32 は設定で選択可能にするのが落としどころ。最終判断はユーザーの試聴に委ねる設計にする（サンプルを聴き比べられるようにする）。

### 8.4 制作（合成後処理）

- 各行：無音トリム→音量正規化（目標ラウドネス目安つき）→任意でバイノーラル処理（HRTF の SOFA ファイル＋ffmpeg の sofalizer。ffmpeg のビルドによっては当該フィルタが無いので、対応ビルドを用意すること。回転角の符号と左右の対応は使用する素材の仕様に合わせ実測で確認）→行間ギャップを挟んで連結。
- SE 混合：台本行に付いた SE キューに合わせ、カテゴリ別ライブラリから音を敷く。ボイスを優先するダッキング（サイドチェイン圧縮）を入れる。カテゴリ未登録なら無理に作らず、納品メモに「未登録のためスキップ」と明記する（失敗を隠さない）。
- 出力は wav（正本）＋ mp3（持ち出し用サイドカー）。シーン画像（任意）は通常の画像生成ジョブとして別途投入し、依頼に紐付ける（制作の成否には影響させない）。
- バックグラウンド再生：端末側はメディアセッション付きのフォアグラウンドサービスで再生し、通知・ロック画面から操作できるようにする。各アイテムごとに独立した再生状態を持つ（1つのプレイヤー状態を全アイテムで共有しない）。

---

## 9. ローカル LLM チャット（F4/F7）と GPU 調停

### 9.1 チャット

- 推論は PC 側 LLM ランタイムをヘルパーが中継（ストリーミング）。会話履歴・要約は端末内のみ。
- 会話は「続きから再開」できる形にし、文脈が上限に近づいたら古い部分を要約に圧縮する（要約にもローカル LLM を使う）。
- システムメッセージの扱いに注意：モデル（テンプレート）によっては「システムメッセージが複数ある／先頭にない」と推論エンジンがエラーを返すものがある。送信前に**先頭のシステムメッセージは1つに統合**する正規化を必ず入れる。
- エラーは握りつぶさず、推論エンジンが返したエラー文字列をそのままユーザーに見せ、コピー可能にする（「upstream error」のような汎用文言だけにしない）。文脈使用量の表示は、システムプロンプトやプリセットも含めて数える。
- モデル切り替え時は、前のモデルの常駐を解放してから送る（VRAM 競合防止）。ただし要約等の裏方呼び出しでも同じ口を使う場合、表のモデルの再読み込みが発生するトレードオフをユーザーに伝える。

### 9.2 ジョブセンターと GPU 調停

- アプリ側に全ジョブ横断の「ジョブセンター」を持ち、投入したジョブの進捗をタブを跨いで追えるようにする。アプリ再起動後はヘルパーの「実行中ジョブ一覧」から復元する。
- ヘルパー側の調停ルール：
  - 専有スロット：動画ジョブ、TTS 大モデル。これらと画像生成は同時実行しない。
  - 優先モード（画像優先/LLM 優先/その都度聞く）をユーザーが選べる。競合時は「どちらを先に・両方やめる」の選択肢だけを出し、**実行中ジョブを止める選択肢は出さない**。
  - 音声制作は「他ジョブが無く、LLM の常駐 VRAM が小さい」状態になるまで待ってから始める（ポーリングで待機、上限時間つき）。
- 上部バーに GPU 状態チップ（空き/画像実行中/動画実行中/音声制作中/LLM 常駐）を出し、タップで詳細シート（VRAM、常駐モデル、優先モード、常駐解放ボタン）を開く。

### 9.3 エージェント提案（F7）

- チャット内の LLM は、生成系の操作を直接実行できない。「提案ブロック」（画像プロンプト提案、タグ付け、Civitai 検索、LoRA/モデル導入、ギャラリー検索など）として提示し、ユーザーがタップしたものだけが既存の API 経由で実行される。
- LLM にはトークン類・PIN・パス・IP・URL を渡さない。外部サイトへのアクセスもヘルパーが対象ドメインを限定して代行する。
- 会話をまたぐ記憶は、ユーザーが明示保存したものと、承認した抽出候補だけを対象にする。

### 9.4 ハンドオーバー（会話の引っ越し）

- 他の環境で育てた会話設定を引っ越せるよう、Markdown 形式の「ハンドオーバー文書」のインポートを用意する：ファイル選択または貼り付け→内容プレビュー→確認して保存。初回メッセージは送信済みにせず下書きとして置く。ロック先への引っ越しはロック解除済みのボールトがある場合のみ。

---

## 10. アプリ画面構成（参照実装）

下部5タブ：**画像 / 音声 / 動画 / ギャラリー / チャット**。設定はタブにせず、上部バー右端の歯車から開く。

- 画像タブ：アコーディオン3節（生成 / LoRA / 画像編集）。生成節はモデル選択・プロンプト・バッチ（サイズと回数）・保存先。LoRA 節は一覧と Civitai 導入（種別切替でモデル導入も）。画像編集節は img2img/inpaint/outpaint/タガー/モザイク。
- 音声タブ：プロファイル選択→依頼フォーム（選択肢はプロファイルから動的生成）→依頼一覧（台本編集・チェック・承認・制作）→SE ライブラリ試聴→参照音声の登録。
- 動画タブ：モード/モデル/サイズ/秒数、画像用とモーション用の2欄、モーションプリセット、「音声と合成（未実装）」のような将来機能の導線は無効化した見た目で置く。
- ギャラリータブ：媒体別フォルダの入口画面→各フォルダ。
- チャットタブ：会話一覧（通常/ロック）、ストリーミング表示、エージェント提案カード、GPU 競合シート、メモリ候補の承認 UI。
- 設定：登録、接続、PC の状態表示、GPU 優先モード、LLM 既定モデル、音声の既定（制作方式・保存先・精度・SE 音量）、動画の既定（モデル・長さ・保存先）、ロック設定。**画面再編の際は旧設定項目を全て引き継ぐ**（再編で項目が消える事故が起きやすいので、移行チェックリストを作って照合すること）。

---

## 11. 実装フェーズと検証

### 11.1 フェーズ（機能選択に応じて削る）

0. **計測**：使うモデルの生成時間・VRAM・品質を自分の環境で実測し、設計値（上限・既定・所要時間表示）を決める。推測で上限を決めない。
1. **基盤**：ヘルパー（認証・登録・health・ジョブ基盤・GPU 情報）、アプリの殻（タブ・設定・登録）。
2. **画像**（F1/F3 の画像分）：生成テンプレート、ギャラリー、ロック。
3. **編集とモデル導入**（F2、§6.2）。
4. **チャット**（F4/F7）。
5. **動画**（F5）。
6. **音声**（F6）。

### 11.2 検証の型

- 各フェーズでヘルパーのスモークテスト（使い捨てデバイスを登録し、実 API を一通り叩く自動スクリプト）を用意し、全部通ってから次へ進む。
- 実機確認項目はチェックリスト化する（登録、ロック解除の経路、上書きインストールでトークンが保持されること、等）。
- ヘルパーの更新は「ファイル差し替え」と「プロセス再起動」が別物である点に注意。再起動のタイミング（PC 再起動＋ログイン等）を運用として決め、**「新コードは置いたが未起動」な状態をユーザーに明示**する。
- 自動起動の証明は「再起動後に実際に一巡り動くか」で行う（タスク登録だけでは証明にならない）。

### 11.3 既知の落とし穴

- 署名キーの喪失（§2.3）：プロジェクト内に固定キーストアを置き、ビルド設定で明示参照する。
- 「存在しないモデルファイル」のダウンロード：配布元のファイル一覧 API で実在確認してから落とす。サイズが極端に小さいファイルはエラー応答の可能性があるので弾く。
- LLM テンプレート差異：システムメッセージの数や位置で落ちるモデルがある（§9.1）。複数モデル対応時は正規化を共通化する。
- 文脈超過：トークン見積もりにシステムプロンプト等を含め忘れると、表示は余裕でも実際は超過してエラーになる。
- TTS/動画の VRAM：常駐物（生成エンジン等）込みでピークを見る。単体測定の数字だけで上限を決めない。
- ヘルパーのテストインスタンスを立てる場合は、本番と別のポート・別のルートで（本番 DB を汚さない）。終了できないプロセスが残る環境では、次回は新しいポートを使う。

---

## 12. 運用メモ

- 生成物とモデルの置き場は1ルートに集約し、容量監視（残量が少ないドライブへの配置は避ける。モデル導入時の容量確認は「実際にファイルが落ちるドライブ」を見ること——保存先ルートとモデル置き場が別ドライブの構成がありうる）。
- ログには会話本文・プロンプト本文を残さない。エラー詳細と error_id の対応だけを残す。
- バックアップ：設計文書・台帳・DB を対象にし、生成物そのものは対象外でよい（再生成可能）。ただし「プロジェクトの正本はファイルに置き、チャットの記憶だけに頼らない」こと。
