# ローカル GPU PC 連携アプリ 設計書（共有版）

**「自分の GPU 搭載 PC で動く ComfyUI と Ollama を、自分のスマホから使う」ための専用アプリ**を、ゼロから構築するための設計書。本文書だけを渡せば、別の環境でもだいたい同じアプリ・同じ処理を再現できることを目指す。

- 想定読者: このアプリを自分の環境で作りたいユーザーと、その構築を担う AI エージェント
- 前提: 個人専用（自分 1 人・自分の端末・自分の PC）。アプリストア公開、多人数利用、クラウド同期は対象外
- 固有環境への依存を避けるため、値が環境で変わるものは `<プレースホルダ>` で示し、§0.5 の「環境差分ガイド」で埋め方を説明する

---

## 0. スコープと前提

### 0.1 作るもの

自分のスマホ 1 台から、VPN 経由で自宅 PC 上の ComfyUI（画像生成）と Ollama（ローカル LLM）に接続し、次を行う専用アプリ。

- 画像生成（txt2img / img2img / インペイント / アウトペイント / アップスケール）
- LoRA の管理と、Civitai からの検索・ワンタッチ導入
- 生成物の閲覧・検索・ダウンロード・整理（ギャラリー）
- ローカル LLM とのチャット（会話の保存・再開・要約圧縮・横断メモリ付き）
- LLM の提案を画像生成へ受け渡す仕組み（確認シート経由。自動生成はしない）
- 生成物の一部を認証なしでは開けない「ロックフォルダ」

### 0.2 作らないもの

- アプリストア配布、複数ユーザー、アカウント登録、クラウド同期、広告、解析・クラッシュレポート等の外部テレメトリ一切
- 任意ワークフロー JSON の編集・送信（ノードグラフエディタは作らない。生成はサーバ側テンプレート＋パラメータのみ）
- LLM モデルの追加（pull）・削除（PC 側の明示操作に限る。1 件で数 GB〜十数 GB のため）
- 会話のクラウドバックアップ

### 0.3 設計原則（重要。実装で覆さないこと）

1. **入口の一本化**: スマホアプリは ComfyUI / Ollama に直接つながない。認証と入力検証を持つ小さな「ヘルパー」プログラムを PC 側に置き、アプリの全リクエストはヘルパーだけを通す。ComfyUI は認証を持たないため、たとえ VPN 内でも直接晒さない。
2. **生成内容の非検閲・非干渉**: ヘルパー・AI エージェント・保守経路は、ユーザーのプロンプトや会話本文を独自の基準で審査・拒否・削除・書き換えしない。入力検証はパラメータの形式・範囲のみ。生成画像への内容判定・分類・ぼかし・削除も自動実行しない。内容に関わる操作はユーザーの明示指示がある場合に限る。
3. **会話データは端末内にのみ置く**: チャット履歴は PC 側に保存しない。ヘルパーはリクエストのたびに履歴ごと中継するだけのステートレスな中継とする。これにより、保守アクセスの対象になる会話データ自体が PC に存在しない。
4. **秘密は PC から出さない**: Civitai API キーは PC 内のみ。スマホへ送らない。ヘルパーも値そのものをログ・応答に出さない。
5. **ログに本文を残さない**: プロンプト本文、会話本文、トークン、画像データをログに記録しない。記録するのは日時・送信元・エンドポイント・成否・機械的な ID と数値のみ。
6. **実行中ジョブは途中で殺さない**: GPU 調停（§6.7）も中断操作も、この原則に従う。中断はユーザーの明示操作だけ。
7. **提案と実行の分離**: LLM は提案だけをする（§6.9）。実行は常にユーザーのタップを起点とし、タイマーやバックグラウンドで静かに実行されるものは存在しない。

### 0.4 全体構成

```
[スマホアプリ]
   │  全リクエスト（デバイストークン認証付き）
   │     ── VPN（WireGuard 等の暗号化トンネル）──
   ▼
[PC: ヘルパー  <PCのVPNアドレス>:<HELPER_PORT>]  ← 外部に開くのはこの 1 ポートだけ
   │  認証・入力検証のうえで中継/実行
   ├─→ [ComfyUI 専用インスタンス 127.0.0.1:<COMFY_PORT>]  生成実行（外から見えない）
   ├─→ [Ollama 127.0.0.1:11434]  LLM 実行（ヘルパーがストリーミング中継）
   ├─→ [Civitai API]  LoRA 検索・DL（キーは PC 内のみ）
   └─→ [<APP_ROOT>\]  LoRA・成果物・索引 DB・ログ（専用フォルダ配下のみ）
```

- ヘルパーは PC の通常ユーザー権限で常駐する小さなプログラム（実装言語は問わない。参照実装は Python + FastAPI 相当の薄い構成）。OS の自動起動に登録し、PC 再起動後も自動で戻る構成にする。
- ComfyUI は本アプリ専用インスタンスを分ける（普段使いのインスタンスと止め合わない）。出力先は専用の staging 領域に向け、ヘルパーが検証後に保存先へ移動して初めてアプリから見えるようにする。

### 0.5 環境差分ガイド（環境ごとに決める値）

| 項目 | 決め方 |
|---|---|
| `<HELPER_PORT>` / `<COMFY_PORT>` | 空いているポートを 1 つずつ。ヘルパーは VPN インターフェースのアドレスにだけバインドする（0.0.0.0 で全 IF に開かない） |
| `<APP_ROOT>` | PC 上の専用フォルダ（例: Windows なら `D:\LocalGenApp\`、Linux/macOS なら `~/LocalGenApp/`）。アプリ関連はこの中だけ。他のデータには触らない。撤収はこのフォルダ削除＋設定 2 点（後述）の除去で完了する形にする |
| VPN | Tailscale が手軽で推奨（WireGuard ベース、到達元を端末単位で絞れる）。代替は WireGuard 自前構築や、自宅 LAN 内のみ＋TLS。いずれでも「VPN 外からはヘルパーに到達できない」「ファイアウォールで到達元を自分の端末に限定」が必須要件 |
| GPU / VRAM | §6.7 の安全予算は VRAM 総量から決める。24GB 級なら目安 22GB、16GB 級なら LLM は小〜中モデルとの排他運用が中心、12GB 級なら画像生成と LLM は基本的に排他（同時常駐は小モデル時のみ）。フェーズ 0 で実測して確定する |
| GPU ベンダー | 参照実装は NVIDIA + CUDA 前提。AMD（ROCm）でも ComfyUI / Ollama は動作するが、モデル常駐量と解放手段の実測をやり直すこと。複数 GPU 環境では、アプリ用に 1 枚を割り当てるのが単純 |
| PC の OS | Windows / Linux / macOS いずれでもよい。差分は「自動起動の登録方法」「ファイアウォール設定」「パス形式」だけ。ヘルパー本体は OS 非依存に保つ |
| スマホ OS | 参照実装は **Android（Kotlin + Jetpack Compose）**。iOS 版を作る場合の差分は §10.2 を参照（言語・配布方法・バックグラウンド実行・鍵ストアの考え方が変わる） |
| 画像生成モデル | テンプレート方式（§5.2）なのでモデルファミリ追加は「モデル定義＋テンプレート」の追加で対応する。初期候補の例: アニメ系チェックポイント（SDXL 系、Pony 系、その他独自アーキテクチャ系）。モデルごとに「使える機能」が違う点に注意（§3.2 の機能可否マトリクス） |
| ローカル LLM | Ollama に導入済みのモデルから選ぶ。役割の例: 高品質な本命モデル（27B 級）、高速な下書き・要約用（MoE 等）、小モデル（雑用・タグ整形）。実モデル名は環境ごとに自由 |

---

## 1. ポートとプロセス

| プロセス | 待ち受け | 到達元 | 用途 |
|---|---|---|---|
| ヘルパー | VPN アドレス:<HELPER_PORT> のみ | 自分のスマホ（＋任意で保守用端末）。FW とヘルパー側の送信元検証で二重に制限 | アプリの全機能の入口 |
| ComfyUI 専用インスタンス | 127.0.0.1:<COMFY_PORT> のみ | PC 自身（ヘルパー）だけ | 生成実行 |
| Ollama | 127.0.0.1:11434 | PC 自身だけ（アプリは直接使わず、ヘルパーが中継） | LLM 実行 |

- 専用 ComfyUI には、使う追加ノード（例: 顔の自動修正を行う Detailer 系ノードパック）を読み込んだ状態で起動する。
- LoRA の追加読み込みは ComfyUI の `extra_model_paths.yaml` に `<APP_ROOT>` 配下の loras ルートを登録して行う（ComfyUI 本体フォルダへアプリ用 LoRA を置かない）。

---

## 2. 保存設計（PC 側）

```
<APP_ROOT>\
├─ loras\
│  ├─ <ベース種別>\<種別>\   分類フォルダ（例: sdxl\character、pony\style 等。ベース×用途で分ける）
│  ├─ _preview\      LoRA プレビュー画像と .civitai.json サイドカー（DL 元 ID・version・トリガーワード・SHA256）
│  ├─ _staging\      DL 中の一時置き。検証中は ComfyUI から読み込まれない
│  └─ _quarantine\   検証失敗ファイルの隔離先（7 日後に自動削除）
├─ staging\           生成直後の専用領域（通常/ロックどちらでもない。API からは参照不可）
├─ outputs\           通常フォルダの生成 PNG（日付別サブフォルダ）
├─ outputs_locked\    ロックフォルダの生成 PNG（アプリでは認証しないと開けない。§7）
├─ input\uploads\     端末から受け取った入力画像（24 時間で自動削除）
├─ index\outputs.db   成果物索引（SQLite。§5.3）
├─ helper\            ヘルパー本体・設定（トークンはハッシュのみ）・ワークフローテンプレート
├─ logs\              ヘルパーのアクセスログ（30 日ローテーション。本文は残さない）
└─ trash\             アプリから削除した画像の退避先（7 日後に完全削除）
```

容量管理:
- 設定画面とヘルパー応答にディスク空き容量を常時表示する
- 空きが閾値を割ったら段階的に制限する（目安: 警告 → LoRA 導入停止 → 生成停止。閾値は総容量と実測で決める）
- 自動削除はしない。削減はユーザーの手動判断（ギャラリー削除 → trash 経由）のみ
- LoRA 1 件のサイズ上限、1 回の生成の出力枚数上限をヘルパー側でも検証する

---

## 3. アプリ画面設計

### 3.1 デザイン方針

- ダークテーマ単一。余白は 4dp グリッド、色・角丸・影はデザイントークンで定義した値だけを使う。安易なグラデーションや装飾過多を禁止
- タップ領域 48dp 以上、本文コントラスト比 4.5:1 以上、状態を色だけに依存しない（接続状態はドット＋文字併記）
- 連続値パラメータは A1111（AUTOMATIC1111）式の「スライダー＋数値欄＋±微調整」の一体部品にする。スライダー単独で精密な値を入れさせる設計にしない。操作中は現在値を大きく表示し、指を離した時点で確定する
- UI 言語は日本語/英語を選べる（設定で切替）。パラメータ名（Sampler / CFG / Steps 等）は両言語とも英語表記の慣例に従う
- 進捗表示は数値と細バー中心。重いブラー・常時アニメーションは使わない
- 画面遷移と状態（生成中/キュー待ち/オフライン/ロック中）は全画面で一貫した部品で表示する

### 3.2 画面構成（下部タブ 6 つ: 生成 / 画像 / LoRA / ギャラリー / チャット / 設定）

上部バーには接続状態（PC 到達可否・キュー数）、GPU 状態（常駐エンジンと優先モード。§6.7）、ロック状態アイコンを常時表示する。

1. **生成タブ**（A1111 txt2img の縦画面移植）
   - モデル選択（タブ最上部に常時表示。選択肢はヘルパーがテンプレートを持つモデルのみ。切替時にモデル既定レシピを反映）
   - **モデルごとの機能可否**: モデルファミリによっては Hires / FaceDetailer / LoRA が生成チェーンに存在せず、ヘルパーが検証エラー（400）を返す。アプリ側は、非対応モデル選択時に該当スイッチと LoRA 追加をグレーアウト＋注意文表示し、送信時にも該当項目を自動で外すこと（保存済みの設定値自体は保持し、対応モデルに戻せば再び効く）。対応表はモデル定義に持たせる
   - プロンプト欄（タグチップ表示対応。§6.2）／ネガティブ欄
   - Generate ボタン（画面下部固定。生成中は「中断」に切替＋進捗）
   - 折りたたみセクション: Sampling（Sampler / Steps / CFG / Seed＋ランダム・固定トグル）、Size（幅・高さプリセット＋Batch size＋Batch count）、Hires fix（ON/OFF、倍率、Denoise）、FaceDetailer、Extras（アップスケール連結）、LoRA（スロット最大 5、各 ON/OFF と強さスライダー）
   - **Batch count は繰り返し投入**として実装する（1 回の投入＝Batch size 枚、を N 回繰り返し、seed はバッチサイズ分ずつ進める A1111 準拠の意味論）。上限は大きめに取る（例: 100 回）。全体の進捗はジョブセンター（§3.7）が束ねる
   - 結果プレビュー（保存先がロックフォルダのジョブでは出さない。§7）
   - 「前回の設定を復元」を標準搭載（起動時は前回値を保持）
2. **画像タブ**（画像起点の集約）: img2img / インペイント / アウトペイント / Tagger（WD14 等のタグ推論）
   - 入力画像の取り込み: 端末の写真ピッカー、他アプリからの共有インテント、ギャラリー生成物の流用、チャット添付
   - インペイントのマスクは指で塗る。**モザイク／ぼかし／黒塗り**（指で塗った範囲への端末内加工。粗さは数段階から選択）もこのタブに置く（加工は端末内で完結させる）
3. **LoRA タブ**
   - 導入済み一覧（分類別、プレビュー・トリガーワード表示、タップで生成タブのスロットへ追加。ベース不一致は警告表示）
   - Civitai 検索（キーワード、ベースモデル絞り込み、NSFW 含む、プレビュー、導入ボタン。§6.3）
   - **検索結果の保持**: 検索 → 詳細 → 戻る、で検索条件・結果・読み込み済みページが消えないこと（詳細は一覧の上に重ねて表示する等、検索画面の状態を破棄しない実装にする）
4. **ギャラリータブ**
   - PC 上の成果物を日付別に一覧（本体は PC に置いたまま。サムネイル→フルの順に都度取得し、アプリ内に恒常キャッシュを持たない）
   - 検索（プロンプト文字列・LoRA 名・日付・コレクション）。コレクションは物理移動を伴わない論理フォルダ（索引 DB 上の分類。§5.3）
   - 複数選択（ドラッグ選択＋自動スクロール対応。高速スクロール用のスクロールバーを付け、スクロール操作と選択操作が競合しないようにする）
   - 詳細表示: フル画像＋メタデータ全文。**画像部分を横フリックすると一覧の前後の画像へ移動できる**（ページャー実装。お気に入り・メタ情報も移動先に追随させる）。ダウンロード（原本バイトのまま）、ゴミ箱移動、お気に入り、フォルダ間移動（通常⇔ロック。PC 側の実ファイル移動と同期）
   - 「この設定で再生成」: ジョブごとに保存された生成パラメータ（§5.3 の gen_params）から、生成タブ（txt2img 系）または画像タブ（画像起点系）へ設定を復元して遷移する。自動生成はしない。パラメータが保存されていない古い生成物では再生成を無効化する
5. **チャットタブ**（§6.6）
   - モデル選択、会話一覧（通常/ロック。ロック会話は一覧の最下部に目立たなく置き、認証前は内容を復号しない）、ストリーミング表示、停止/再生成
   - 折りたたみセクション: System prompt（プリセット選択＋編集。プリセットは端末内にのみ保存）、Sampling（Temperature / Top P / Num ctx / Repeat penalty）
   - エージェントモード（§6.9）のトグル、添付画像（Tagger 連携）
   - GPU 優先モードのクイック切替（生成タブと共通の値）
6. **設定タブ**
   - 画像ロック設定（§7）、UI 言語、接続情報（表示のみ）、ディスク残量とフォルダ使用量
   - **PC 状態スナップショット**: ボタンを押した時だけ CPU / GPU / メモリ / 主要プロセス（ComfyUI・Ollama・ヘルパー。待ち受けポートで識別）/ ジョブ状態を取得して表示する（常時監視はしない。オンデマンド方式）
   - GPU 優先モードの既定値、LLM の既定モデルと system prompt プリセットの管理、横断メモリの管理（通常/ロック）、要約に使うモデルの選択
   - トークン再登録、バージョン表示、直近のエラー一覧と診断パッケージ出力（§8）

### 3.3 スライダー仕様（対象と範囲の例）

| パラメータ | 範囲 | 刻み |
|---|---|---|
| Steps | 1–150 | 1 |
| CFG Scale | 1.0–30.0 | 0.1 |
| Hires Denoise | 0.00–1.00 | 0.01 |
| Hires 倍率 | 1.00–2.00 | 0.05 |
| LoRA 強さ | 0.00–2.00 | 0.05 |
| Temperature（LLM） | 0.00–2.00 | 0.05 |
| Top P（LLM） | 0.00–1.00 | 0.01 |
| Repeat penalty（LLM） | 1.00–2.00 | 0.01 |

- Seed と寸法はスライダーにせず数値入力＋プリセット選択。Num ctx もプリセット（2048 / 4096 / 8192 / 16384 / 32768）＋数値入力
- 値の範囲はヘルパー側の検証範囲（§6.4）と一致させる

### 3.4 ジョブセンター（進捗の一元管理）

- 生成ジョブの進捗は「全体バー＋ジョブ別バー」の 2 層で表示する。後から投入したジョブが先のジョブの表示を上書きしない
- ジョブ状態はアプリ全体で保持し、タブを切り替えても消えない。アプリ再起動後は `GET /api/gen?active=1` で実行中ジョブと再同期する

---

## 4. 生成フロー

1. アプリが `POST /api/gen` にモデル ID＋パラメータ＋保存先フォルダ＋冪等キーを送る（任意ワークフロー JSON は送れない設計。§6.4）
2. ヘルパーがパラメータを検証し、サーバ側テンプレートに差し込んで ComfyUI `POST /prompt` へ投入し、ジョブ ID を返す。投入前に GPU アービタ（§6.7）が調停する
3. 進捗はヘルパーが ComfyUI のイベントを変換して中継する（WebSocket またはポーリング）。中継するイベント型は許可リスト（progress / preview / completed / error）だけに限定し、ComfyUI の生イベントをそのまま通さない。プレビュー画像は保存先が通常フォルダのジョブで、アプリが明示要求した場合のみ送る
4. 生成物はまず staging に生まれる。完了後、ヘルパーが成果 PNG にメタデータ（§5.4）を確定・検証し、保存先フォルダへ移動してから索引 DB に登録し、最後にアプリへ完了通知する（この順序により、ロック保存の画像が通常フォルダ側から見える瞬間が存在しない）
5. アプリの通知は「生成が完了しました」の文言のみ。画像・プロンプト・保存先は通知に出さない
6. 中断は `POST /api/gen/{id}/interrupt`。キューはヘルパーが一元表示する

---

## 5. データ設計

### 5.1 アプリ内設定（端末内ストレージ。キーと既定の例）

| キー | 既定 | 備考 |
|---|---|---|
| ui_language | 端末言語 | ja / en |
| default_output_folder / last_output_folder | normal | 生成の保存先（§7） |
| lock_relock_minutes | 3 | 自動再ロック（1/3/5 分から選択） |
| gpu_priority_mode | ask | image / llm / ask（§6.7）。生成・チャット・設定で共用 |
| default_llm_model | （一覧の先頭） | 新規会話の既定 |
| system_prompt_presets | 初期プリセット集 | 端末内のみ。内容はヘルパーへ送らない（送信時に会話の system としてだけ使う） |
| llm_params_by_model | モデル別既定 | Temperature 等のモデル別保持 |
| last_gen_params | 既定レシピ | 前回設定の復元用 |
| device_token_enc | なし | OS の鍵ストアで暗号化した値のみ保存 |
| lock_session | なし | メモリ保持が原則。プロセス再起動で破棄し再認証を求める |

### 5.2 ワークフローテンプレートとパラメータ対応

ヘルパーは、モデル定義が指すテンプレート（ComfyUI API 形式ワークフロー）に、検証済みパラメータだけを差し込んで `POST /prompt` する。差し込み箇所はノード ID で固定する。

- モデル定義に持たせるもの: モデル ID、表示名、ベース種別、テンプレート、実ファイル名、既定レシピ（Steps / CFG / Sampler / ネガティブ既定文 等）、**機能可否**（Hires / FaceDetailer / LoRA の可否。§3.2）
- アプリからは model_id（許可リスト）のみを送り、実ファイル名やテンプレートはヘルパーが解決する
- パラメータの差し込み先（代表）: Prompt→CLIPTextEncode(positive)、Negative→CLIPTextEncode(negative)、Width/Height/Batch→EmptyLatentImage、Seed/Steps/CFG/Sampler/Scheduler→KSampler、LoRA は LoraLoader を直列に挿入（strength_model / strength_clip に同じ値。詳細設定でのみ分離可）
- LoRA の `<lora:...>` プロンプト記法は使わない（プロンプト文字列と LoRA 適用を分離し、二重適用を構造的に防ぐ）
- Seed は文字列で扱い上限は 2^53−1。「ランダム」の場合はヘルパー側で実値を決め、応答とメタデータに実 seed を返す
- テンプレートの種類: txt2img（モデルファミリ別）、img2img / inpaint / outpaint（ファミリ別）、extras_upscale（LoadImage→UpscaleModelLoader→ImageUpscaleWithModel→SaveImage。生成への連結時は最終段へ同じノード列を差し込む）
- Sampler 名は A1111 表記との対応表を持ち、メタデータには A1111 表記で出す

### 5.3 索引 DB（PC 側 SQLite）

テーブル `outputs`: id / file_path / folder（normal / locked）/ collection（論理フォルダ名。物理配置とは独立）/ status（active / trashed / deleting / error）/ created_at / prompt / negative / seed / size / model / loras_json（名前・強さ・ハッシュ）/ has_workflow / has_parameters / trashed_at / prompt_id / batch_index / sha256 / template_id / scheduler / hires_json / facedetailer_on / favorite / **gen_params（投入時のリクエスト全体。再生成の正）**

- 登録はヘルパーの生成完了処理でのみ行い、PNG メタデータから抽出して埋める（ファイル名や推測で埋めない）
- ギャラリー検索はこの DB に対して行う（ファイル走査はしない）
- ファイル操作と DB 更新は同一トランザクションにできないため、順序を「ファイル移動→DB 更新」に固定し、ヘルパー起動時に不整合（status が deleting のまま、staging 残留等）を検出して実ファイル側に合わせて修復する。修復できないものは status=error として表面化させる
- テーブル `jobs`: prompt_id / idempotency_key / params_hash（パラメータ＋保存先のハッシュ）/ output_folder / template_id / status / created_at / output_ids。**保存先はジョブ生成時に確定し以後変更できない**。同一の冪等キーで異なるパラメータまたは保存先が来たら、不一致として E_VALIDATION で拒否する
- テーブル `loras`: 導入済み LoRA のファイル名 / 分類 / サイズ / sha256（生成時の存在確認と導入後の改変検知に使う）
- テーブル `devices`: デバイストークンのハッシュ / ラベル / ロック解除用公開鍵 / 作成日時。テーブル `reg_codes`: 登録コードのハッシュ / 有効期限 / 使用済みフラグ / 試行回数

### 5.4 生成 PNG のメタデータ

生成 PNG には次の 2 系統を必ず入れる（ピクセルの再エンコードなし、チャンク追加のみ）:

1. ComfyUI 標準の workflow / prompt チャンク（再現用）
2. A1111 形式 `parameters` テキスト（プロンプト、ネガティブ、Steps / Sampler / CFG / Seed / Size / Model / 使用 LoRA 名とハッシュ）

- チャンク挿入は画像ライブラリの再保存（ピクセル再圧縮を伴う）ではなく、PNG チャンクを直接挿入する実装にする。単一チャンク長と全体量に上限を設け、CRC を検証し、同名チャンクは重複させず置換する
- ヘルパーが完了処理で埋め込みの有無を検証してから索引登録する。検証に失敗した画像は「メタデータ不完全」と表示する
- アプリからダウンロードしたファイルでも両系統が保持されることを受け入れ条件に含める

### 5.5 端末内会話 DB とロック会話の暗号化

- テーブル `conversations`: id / folder（normal / locked。作成時に確定し変更不可）/ title / model / system_prompt / params_json / created_at / updated_at / status（active / trashed）/ trashed_at / summary（要約文）/ summary_upto_message_id / summary_updated_at
- テーブル `messages`: id / conversation_id / role（user / assistant。system は会話側に保持）/ content / created_at / eval_count 等の機械情報
- テーブル `memories`（横断メモリ。§6.8）: id / folder / content / source_conversation_id / enabled / created_at / updated_at
- 通常会話は端末のアプリ専用領域に保存し、OS バックアップから除外する（Android: `allowBackup=false`＋dataExtractionRules。iOS: バックアップ除外属性）
- ロック会話は title / system_prompt / 各メッセージ content / summary / ロック側メモリを、会話ごとの AES-GCM 鍵で暗号化して保存する。その鍵は 2 系統でラップする: ①生体必須の OS 鍵ストア鍵（認証操作でのみ開封） ②PIN から Argon2id で導出した KEK（salt は端末内保存、PIN 自体は保存しない）。認証前は DB に平文が存在せず、一覧にも内容を出さない
- 全文検索は端末内 FTS を使う（通常会話のみ索引化。ロック会話は復号後にメモリ上でのみ検索し、平文索引を作らない）
- 再ロック時は復号済みの会話状態（画面状態・入力欄・一時値）を破棄する。画像側の再ロックと同時に実行し、片方だけ開いたままにしない

### 5.6 GPU アービタの状態（ヘルパー内）

- アービタはヘルパー内の単一コンポーネントとし、開始可否の判定を直列化する（判定と開始の間に他ジョブが割り込まない）
- 保持する状態: 各エンジンの状態（idle-resident / running / unmanaged-external）、直近に観測した VRAM（Ollama は `/api/ps`、ComfyUI は `/system_stats` から）、待機キュー（engine / ジョブ参照 / 優先モードのスナップショット / 待機理由 / 投入時刻）
- LLM のストリームはアービタのメモリ内レジストリで管理する（プロセス再起動で消えてよい情報）。画像ジョブは `jobs` テーブルに記録する

### 5.7 送信コンテキストの組み立て（端末内処理）

送信時のメッセージ列は端末内で次の順に組み立てる（ヘルパーは関与しない）:

1. system: 会話の system prompt
2. system（メモリブロック）: 有効な横断メモリを区切り付きで列挙（ロック会話の場合のみロック側メモリも含む）
3. system（要約）: 要約がある場合は summary を置く
4. summary_upto_message_id より後の生メッセージ

- **system メッセージの正規化**: 一部のモデルのチャットテンプレートは system メッセージが複数あるとエラーになる（HTTP 500）。送信前に、先頭の連続する system を 1 つに結合し、途中に現れた system は user 側へ降格させる正規化を必ず行うこと（エージェントプリセットを差し込む設計では特に踏みやすい）
- トークン数の見積もりは端末内で文字数ベースの近似（日本語は約 1.5 文字/トークン、英数字は約 4 文字/トークンの初期値）を使い、応答の eval_count 実績で補正する。見積もりには system prompt とプリセット分も含める
- 要約圧縮: 見積もりが Num ctx の約 80%（設定可）に達したら、直近分（予算の約 40%）を残し、それより前を要約対象とする。要約は専用プリセット＋対象メッセージ列を通常のチャット中継で要約用モデル（設定で選択。高速枠が既定）へ送る通常ジョブとし、GPU 調停の対象になる。結果を summary に保存し、summary_upto_message_id を進める。既存の summary がある場合はそれも入力に含めて再要約する
- 圧縮に失敗した場合は、要約なしで直近分だけを送るスライディングウィンドウに倒し、その旨を会話画面に表示する。**DB の生履歴は圧縮の成否に関わらず一切削除しない**
- メモリ候補の抽出: 会話本文を抽出用プリセットで要約用モデルへ送り、候補を JSON 配列で返させる。アプリは形式だけを検証し、ユーザーが承認したものだけを保存する。抽出は明示操作でのみ行い、バックグラウンドで自動実行しない

---

## 6. 機能仕様

### 6.1 パラメータと既定レシピ

- 既定値は、使うモデルファミリで実績のあるレシピを初期値にする（例: Hires 1.5 倍 / Denoise 0.35、Detailer 系 LoRA の既定強さ、ネガティブ既定文）。実値はフェーズ 0 で実機生成して確定する
- LoRA 強さはスロットごとに調整する。標準は単一値とし、ComfyUI 側の strength_model / strength_clip の両方へ同じ値を渡す

### 6.2 Danbooru タグ検索

- 補完: Danbooru `/autocomplete.json?type=tag_query`（正規タグ・カテゴリ・投稿数、エイリアス解決、日本語別名検索に対応）
- 入力中 300ms デバウンスで候補表示 → タップでプロンプトへ挿入（カーソル位置、アンダースコア表記のまま）
- タグはチップ化し、チップ単位で削除できる。**重み構文が効くかどうかはモデルファミリ依存**なので、フェーズ 0 で実測し、効かないファミリでは重み UI を作らない
- カテゴリ色分け（general / character / copyright / artist / meta）。投稿数が極端に少ないタグは淡色表示
- お気に入りタグと履歴は端末内にのみ保存。Danbooru へは読み取りのみ、認証情報は持たない。通信はアプリから直接（公開読み取り）

### 6.3 Civitai LoRA 検索・導入

- 検索はヘルパー経由（NSFW 結果の取得には API キーが必要で、そのキーは PC から出さないため）。条件: キーワード、`types=LORA`、ベースモデル、ソート
- 結果表示: プレビュー画像（**必ずヘルパー中継で取得し、アプリから Civitai の CDN へ直接取りに行かない**）、名前、ベースモデル、DL 数、トリガーワード
- 導入の内部動作は全部 PC 側:
  1. ヘルパーがダウンロード URL から `_staging` へ DL（URL は versionId / fileId からヘルパーが組み立てる。API キーは Authorization ヘッダで送り、クエリパラメータに載せない。リダイレクトは https かつ許可ドメインのみ、プライベート IP 宛ては拒否）
  2. 形式検証（§6.5）と SHA256 照合。不一致・検証失敗は `_quarantine` へ移し、理由をログに残す
  3. ファイル名は Civitai 提供名を使わずヘルパーが自前で生成し（OS の予約名・経路脱出対策を含む）、ベース×種別の分類フォルダへ移動。プレビューと `.civitai.json`（modelId / versionId / trainedWords / SHA256 / 導入日）を `_preview` に保存
  4. ComfyUI 側の LoRA 一覧へ反映し、アプリの導入済み一覧に即時反映する。ベース不一致の LoRA は生成時に警告を出す
- 拡張子は `.safetensors` のみ許可。Civitai 以外の URL からの導入機能は作らない

### 6.4 ギャラリー

- 本体データは常に PC。アプリは索引 DB 検索→サムネイル→フルの順に都度取得する
- ダウンロード: 原本バイトのまま（再圧縮禁止、メタデータ保持）保存する。保存先は選択式で既定は「アプリ内専用領域」、明示操作でのみ端末の共有写真領域へ書き出す（その画像は OS 標準ギャラリーに見える＝ロック管理外である旨をその場で警告する）
- 複数選択の一括ダウンロード/移動/ゴミ箱、メタデータ全文表示、「この設定で再生成」（§3.2）
- 削除は即時削除ではなく trash へ移動（7 日間は復元可能）。完全削除は trash の自動掃除のみ

### 6.5 メタデータ埋め込み

§5.4 の通り。生成完了処理でヘルパーが埋め込みと検証を行う。

### 6.6 LLM チャット

- 接続はヘルパー経由のみ（`POST /api/llm/chat`）。ヘルパーは Ollama `/api/chat` へストリーミングをそのまま中継し、本文の保存・変換・フィルタリングをしない。アプリから Ollama へ直接は繋がない
- モデルは PC に導入済みの一覧（Ollama `/api/tags` と常駐状態 `/api/ps` をヘルパーが統合）から選ぶ
- パラメータは Temperature / Top P / Num ctx / Repeat penalty / Seed を §3.3 の部品で調整する。ヘルパーの検証は形式・範囲のみで、system prompt と会話本文は内容を見ずにそのまま渡す
- モデル自体の応答傾向（公式モデルが断る等）はモデルの挙動であり、システム側の検閲とは切り分ける。アプリはモデル選択肢を制限せず、追加のフィルタ層を一切挟まない
- 会話履歴は端末内にのみ保存する（§5.5）。すべての会話は自動保存され、履歴ビュー（日付別一覧・検索・閲覧・再開・ゴミ箱）から扱える
- **ストリームの継続性（重要）**: ストリーム受信は画面のライフサイクルに紐付けない。アプリ全体のスコープで実行し、進捗をアプリ全体の状態として公開して画面はそれを映すだけにする。タブ切替や他アプリへの移動で生成が止まらないこと。OS にプロセスを保持させる仕組み（Android: フォアグラウンドサービス＋通知。iOS: §10.2 の制約参照）を併用する。同時に流せるストリームは 1 つまでとする
- 停止ボタン: アプリ側の接続を閉じ、ヘルパーは上流の Ollama 接続も即時に閉じる。途中まで流れた文は会話に保存する（自動保存）
- モデル切替時の常駐整理: 別のモデルへ切り替えたら、前のモデルの常駐をヘルパー側で解放し、VRAM の取り合いによるエラーを防ぐ。エラー時は Ollama 自身のエラー文をアプリで読める形で返す（汎用文に潰さない）。エラー表示はコピー・選択可能にする

### 6.7 GPU 優先と調停（ComfyUI × Ollama）

画像生成と LLM が 1 枚の GPU を分け合うための仕組み。大きな LLM（例: 27B 級の量子化モデルで約 17〜19GB）と画像生成側の常駐は、VRAM によっては同時常駐できないため、ヘルパー内の GPU アービタが両エンジンの常駐と実行順を一元管理する。

- **優先モード（ユーザーが選択できる）**: 「画像優先」「LLM 優先」「都度確認」の 3 つ。設定で既定値を決め、生成タブとチャットタブの両方に同じ値のクイック切替を置く。投入したジョブには投入時点のモードを記録し、後から変えても実行中ジョブの扱いは変えない
- **調停ルール**:
  1. VRAM 予算で判定する。相手エンジンの常駐分と合算して安全予算（フェーズ 0 で実測。目安は総 VRAM − 2GB）に収まる場合は競合なしとして同時実行する
  2. 収まらない場合、優先側のジョブを先に通し、非優先側はキューで待機させる（待機理由を明示する）
  3. **実行中のジョブは途中で殺さない**。調停が効くのは「次の単位から」: 画像は現バッチの完了まで、LLM は現応答のストリーム完了までを 1 単位とし、終わった時点で優先側へ譲る。アイドル常駐の解放は即時行う（Ollama は keep_alive=0 でアンロード、ComfyUI は /free 相当でモデル解放。手段と所要時間はフェーズ 0 で実測し、効かない場合は待機に倒す。勝手にプロセスを殺さない）
  4. 「都度確認」モードで競合が発生したら、アプリに「画像を先に / LLM を先に / キャンセル」のシートを出す。応答がない間はどちらも開始しない（409 応答＋詳細でアプリ側に伝える実装でもよい）
  5. 解放と再常駐の短時間の往復を抑えるヒステリシスを入れる（例: 解放したエンジンは最低 60 秒は再常駐の優先対象にしない）
- 上部バーに GPU 状態（どちらのエンジンが常駐/実行中か、VRAM 使用量の概数、優先モード）を常時表示する
- アービタ管理外の使用（ユーザーが PC で直接使う ComfyUI や Ollama）は external として VRAM を差し引くだけで、勝手に解放しない

### 6.8 会話の再開・要約圧縮・横断メモリ・ローカル保存

- **再開**: 会話を開けばそのまま続きを話せる。Ollama はステートレスであり、継続はアプリが履歴を送り直すことで成立する。モデル・system prompt・パラメータは会話ごとに復元され、途中でモデルを切り替えても文脈は引き継がれる
- **要約圧縮**: §5.7 の通り。要約文はユーザーが閲覧・編集できる
- **横断メモリ**: 新しい会話にも引き継ぐメモを端末内に持つ。保存経路は 2 つだけ: ①会話中の文を長押しして「メモリに保存」 ②会話の区切りでローカル LLM が候補を抽出し、**ユーザーの承認後にだけ**保存する（自動で覚えることはしない）。新規会話の開始時に system 側へ差し込み、設定で一覧・編集・削除・無効化ができる
- **ロックとの分離**: 横断メモリも通常/ロックに分ける。ロック側は暗号化し、認証後のロック会話でだけ使う。通常会話へロック側メモリを差し込むことはしない（応答経由の漏れを防ぐ）。通常側メモリは通常/ロック両方の会話で使える
- 要約とメモリ候補の抽出は、内容を外部や AI エージェントへ送らずに行う。ヘルパーにとっては通常のチャット中継と区別がつかない（専用エンドポイントを作らない）

### 6.9 LLM → 画像生成への受け渡し／エージェント的チャット

**受け渡し（2 方式）**。処理はすべて端末内で行い、ヘルパーや AI エージェントは関与しない。

- **テキスト受け渡し**: チャットの応答について、全文または選択範囲を「画像生成に送る」で生成タブのポジティブプロンプトへ入れる（置換/追記を選べる）
- **構造化受け渡し**: 応答内に `imgprompt` ブロック（キー=値形式または JSON）があれば、アプリが機械的に解析して設定ごと受け渡す。項目は positive / negative / size / steps / cfg / seed / lora（名前:強さ、複数可）/ folder（normal|locked）。解析は形式の検証のみで、内容の審査はしない
- 受け渡し時は確認シートを出す: 変更される項目をハイライトし、未指定の項目は生成タブの現在値を維持する。導入されていない LoRA 名は黙って落とさず「未導入」として明示し、その項目だけ外して続行できる
- LLM にこの形式で提案させるための system prompt プリセット（例:「画像プロンプト提案」）を初期プリセットとして用意する。文面は端末側で自由に編集でき、アプリやヘルパーが文面を審査・固定することはない
- 逆方向（現在の画像生成設定を LLM に相談する）は、生成タブからの明示操作でのみ行う。自動で会話に混ぜることはしない

**エージェント的チャット（提案プロトコル）**: チャット内 LLM を「相談相手」から「提案者」に格上げする。ただし実行権は LLM に渡さない。

- 原則: **LLM は提案だけをする**。返答に含まれる定型ブロック（提案）がカードとして描画され、ユーザーがカードをタップした時だけ、アプリが既存のヘルパー API を実行する
- 提案の種類: `imgprompt`（生成条件の提示。Danbooru 実在チェックで未知タグに警告を付けられる）、`tagger`（添付画像のタグ読み取り）、`civitai_search`（LoRA 候補の検索）、`lora_install`（導入）、`gallery_search`（生成物の検索。結果はギャラリーへ受け渡す）
- 実行と結果はすべて会話内にシステムノートとして残り、LLM への文脈にも含まれる。会話を閉じた/ロックした後の古い提案は実行できない
- 安全境界: LLM の到達範囲はヘルパーの既存エンドポイント集合に限られ、汎用 HTTP・ファイル操作・シェルの道具はチェーンのどこにも存在しない。Civitai への通信はヘルパー中継で civitai.com のみに限定される。LLM 自体は Ollama の中でテキストを返すだけで、ネットワークやファイルへの経路を持たない
- LLM へ決して渡さないもの: デバイストークン、PIN、ロックセッション、Civitai API キー、ファイルパス、IP アドレス/ホスト名、その他の認証情報。提案ブロックが運ぶのは検索語・数値 ID・生成パラメータのみとし、URL や認証情報はアプリ側が保持する
- モード: 会話ごとのトグル（通常/エージェント）。エージェントモードでは提案書式を教える system prompt プリセット（編集可）を先頭に差し込む。このとき system が複数になるため、§5.7 の正規化が前提になる

### 6.10 引き継ぎインポート／テキスト書き出し

他のチャット環境からローカル LLM へ会話を引き継ぐための、ユーザー起点の取り込み。

- 入力経路は 2 つだけ: ①ファイル（OS のファイル選択でユーザーが選んだ `.md` / `.txt`。ストレージ権限は要求しない） ②テキスト貼り付け。ネットワーク・ヘルパー・AI エージェントは関与しない。処理は端末内で完結する
- 形式（引き継ぎ Markdown v1）: 先頭の `# 見出し` をタイトルとし、`## 見出し` で節を分ける。見出しはキーワード一致で判定する（番号・日英は不問）: System Prompt、横断メモリ、要約、最初のメッセージ、会話履歴、設定（`key: value` 形式で model / num_ctx / temperature / top_p / repeat_penalty / folder）。節全体が 1 つのフェンスブロックの場合はその内側を本文とする。会話履歴は `### User / Assistant` 見出し等で分割する。未知の節は無視し、警告として数だけをプレビューに出す
- **プレビュー確認が必須**: 選んだ/貼った時点では何も保存しない。プレビュー（タイトル、保存先、モデル、system prompt 文字数、メモリ件数、要約の有無、履歴件数、警告）を確認し、ユーザーが「インポートする」を押した時だけ保存する
- 保存の内訳: ①System prompt は同名プリセットとして保存し、新規会話の system prompt にする ②会話を 1 件作成する ③横断メモリを 1 件ずつ保存する ④履歴があれば順に追記し、要約があれば履歴の最終メッセージまでを要約対象範囲として保存する ⑤**最初のメッセージは履歴に入れず、会話を開いた時の入力欄の下書きとしてだけ置く（自動送信は絶対にしない）**
- ロックの扱い: 保存先がロックの場合、作成・保存はボールト解除必須チェックに従う。インポート画面でボールトは作らない（先に通常のロック会話フローで作るよう案内する）
- 上限: ファイルは 100 万字まで、履歴は 500 件まで（超過分は切り捨てて警告）
- 書き出し: 通常会話のテキスト書き出しのみ用意する（明示操作で OS の共有シートへ。ロック会話は書き出し対象にしない）。自アプリの書き出し形式はインポート形式と互換にしておくと、端末入れ替え時の引き継ぎに使える

---

## 7. 画像表示ロック仕様

生成物の保存先をフォルダで分ける方式。

| フォルダ | 保存先 | アプリでの表示 |
|---|---|---|
| 通常フォルダ | `<APP_ROOT>\outputs\` | 常時表示（ギャラリーの主グリッド） |
| ロックフォルダ | `<APP_ROOT>\outputs_locked\` | 認証しないと開けない。ギャラリーの一番下に小さな 1 行として目立たなく置く（件数・中身の抜粋は出さない） |

- 保存先は生成時に生成タブで選ぶ（通常 / ロック）。選択は保持され、既定値は設定で変更できる
- 保存先がロックの生成では、完了後も結果プレビューを出さない（文言のみ）

認証と再ロック:
- 開く方法: 生体認証（強い生体認証クラス）を第一とし、失敗時はアプリ専用 PIN（端末ロックとは別）
- 認証はアプリ側だけで完結させない: 生体認証は OS 鍵ストアの署名鍵によるチャレンジ署名としてヘルパーが検証し、PIN もヘルパー側（Argon2id ハッシュ、試行制限・バックオフもサーバ側）で検証する。通ればヘルパーが短命の**ロックセッション**（TTL の目安 15 分）を発行し、ロックフォルダ系 API はデバイストークン＋ロックセッションの両方を必須とする。デバイストークンだけでは locked の中身は取れない
- 開いている状態はセッション限り。次のいずれかで閉じる: バックグラウンド遷移、画面オフ（いずれも猶予なし即時）、無操作数分（設定で変更可）、ロックフォルダ画面を離れる（短い猶予つき）。再ロック時はサーバ側セッションも失効させる
- 閉じている間は、ロックフォルダの画像データをネットワークから取得しない（見た目を隠すだけでなく、端末内に画像を存在させない）
- ロック会話（§5.5）も同じ認証を共用する。再ロックは画像側と会話側を同時に実行する

漏れ経路の封鎖:
- 通知: 保存先を問わず画像・プロンプト・保存先を含めない（文言のみ）
- タスクスイッチャーのサムネイル/スクリーンショット抑止（FLAG_SECURE 等）をロック内容の表示画面に付ける。ただし利便性とのトレードオフがあるため設定で解除可にする（既定は運用しながら決める）
- アプリ名とアイコンは中立的なものにする
- 通常フォルダの検索にロックフォルダの内容が混ざらないようにする（ロック側の検索はロックフォルダ画面内でのみ）
- LoRA プレビュー（Civitai 由来）は生成物ではないためロック対象にしない

守る範囲の明記: ロックが防ぐのはアプリ/API 経由のアクセスと誤表示。PC に OS ログインできる人がディスクを直接見ることと、端末の完全な侵害は対象外（ディスク暗号化はしない）。

---

## 8. エラー・オフライン時の振る舞いと診断

- PC 到達不可: 原因の切り分け表示（VPN 状態→ヘルパー→ComfyUI の順に点検結果を出す）。「障害」と決めつけず、OS アップデート再起動後の未ログイン停止など既知の様式も候補に出す
- 生成失敗: ComfyUI のノードエラーをそのまま出さず、パラメータ起因/モデル起因/リソース起因に分類して表示する
- Danbooru / Civitai 到達不可: 該当タブだけ縮退し、生成機能は継続可能にする
- すべてのエラーにエラー ID（日時＋短い連番）を付け、アプリ内ログとヘルパー側ログの双方に同じ ID で記録する。エラー応答形式は `{"error":"E_*","message":"...","error_id":"...","retryable":false}` に統一し、`message` は技術情報（原文）として扱い、アプリの表示文言は分類表からアプリ側で引く（サーバ文言をそのまま UI に出さない）
- 主なエラーコード: E_CONN（到達不可）、E_AUTH（認証）、E_VALIDATION（パラメータ不正）、E_MODEL_MISSING、E_GPU_CONFLICT（調停競合。詳細に gen_active / vram_free_mb 等を含める）、E_REG_CODE（登録コード）、E_LOCK（ロックセッション）、E_LLM_UPSTREAM、E_CONN（外部 API）

診断パッケージ:
- 出力導線: ①エラー画面の「ログを出力して共有」ボタン ②設定の「ログ/サポート」から直近エラー一覧→個別出力
- 含めるもの: エラー ID、日時、アプリのバージョン、端末モデルと OS バージョン、接続点検の結果、リクエストの要約（テンプレート ID とパラメータ値、使用 LoRA 名と強さ、ジョブ ID）、ヘルパーのエラー応答（サニタイズ済みのサーバ側ログ抜粋。`GET /api/diag/{error_id}` で取得）、アプリ内操作ログの直近分（画面遷移と API 成否のみ）
- 含めないもの（既定）: 生成画像、デバイストークン、Civitai API キー（そもそもアプリは持たない）、プロンプト本文・会話本文（切り分けに必要な場合のみ、ユーザーが明示的にチェックを入れた場合だけ含める）
- アプリが自動で外部へ送信する機能は作らない。共有は常にユーザーの手動操作を起点とする
- アプリ内ログは端末内に数日分（容量上限つき）だけ保持し、設定から手動消去も可能にする

---

## 9. 情報セキュリティ設計

### 9.1 脅威モデル（個人専用として現実的な範囲）

- 自宅 LAN 上の他機器・来客端末からの到達 → VPN 外は全遮断、LAN からは一切聞かない
- VPN アカウント侵害・無関係デバイスの混入 → ヘルパーのトークン＋送信元検証の二重化。トークンのないリクエストはログに残して拒否
- スマホ紛失 → 画像ロック（生体/PIN）、トークンは OS の鍵ストア保護領域に保存、失効手順で PC 側から即無効化。アプリに画像の恒常保存がないため端末内からの流出量は最小
- 悪意ある LoRA ファイル → Civitai 公式経路のみ、`.safetensors` 限定、SHA256 照合、隔離フォルダ経由、pickle 形式は受け付けない
- 想定しない: 国家レベルの攻撃、PC 自体の物理的侵害

### 9.2 秘密情報の管理

| 秘密 | 置き場所 | ルール |
|---|---|---|
| Civitai API キー | PC 内のみ（OS の ACL で制限したファイル） | スマホへ送らない。ヘルパーも値そのものをログ/応答に出さない。AI エージェントのメモリにも記録しない |
| デバイストークン | PC: ハッシュのみ保存 / スマホ: OS 鍵ストア | 登録フロー（§9.3）で発行。平文のトークンをチャット等に残す運用はしない |
| アプリ PIN | PC 側ヘルパー内に Argon2id ハッシュのみ | 検証と試行制限はヘルパーが行う。端末 PIN との使い回しをしない前提で UI に明記。忘失時のリセットは PC 上の管理コマンドのみ |
| APK 署名鍵 | **プロジェクト内の永続領域**（§11 の鉄則参照） | ビルドマシンの揮発領域に置かない |

トークンはクライアント別に分ける: スマホ用（全 API）と保守用（`/api/health` と `/api/diag` のみ許可するスコープ付き。保守経路から画像・プロンプト系に到達できないようにする）。

### 9.3 デバイス登録・失効フロー

- 初回登録: ヘルパーの管理コマンド（PC 上で実行）が**ワンタイム登録コード**を発行する。仕様: 有効期限 10 分、1 回限り、推測困難な乱数、登録成功で即時無効化、登録失敗 5 回でそのコードを無効化。アプリ初回画面でコードを入力（または QR 読取）すると、恒常トークンと引き換える（`POST /api/register`）
- 登録時にロック解除用の鍵ペアも作る: アプリが OS 鍵ストアに生体必須の署名鍵ペアを生成し、公開鍵を登録コードの交換と同時にヘルパーへ登録する。デバイストークンの暗号化鍵は生体必須にしない（通常動作に必要なため。ロック署名鍵とは別鍵として分離する）
- 定期ローテーションは必須としない（個人専用では受け渡し自体が漏洩経路になるため）。正とするのは失効・再発行: 紛失・疑いがある場合はヘルパー側で当該トークンのハッシュを削除（即時失効）し、登録フローで再発行する。管理コマンドに全トークン＋全ロックセッションの非常用一括失効（revoke-all）を用意する
- スマホ紛失時の手順: ① VPN 管理画面でスマホをネットワークから除去 ② トークン失効 ③ 必要なら Civitai キーの再発行

### 9.4 ヘルパー側の入力検証（ComfyUI を守る要）

本節の検証はすべて形式・範囲の機械的検証であり、内容審査は行わない（§0.3）。

- アプリから任意のワークフロー JSON を受け付けない。受け付けるのは「モデル ID＋型と範囲が決まったパラメータ」だけ（範囲の例: Steps 1–150、CFG 1.0–30.0、寸法は各辺 64–2048、Batch 1–4 かつ 1 回の出力上限 20 枚、LoRA は導入済み一覧にあるものだけ、強さ 0.00–2.00）
- ジョブコスト上限: 「総ピクセル × Steps × Batch × Hires 倍率の二乗」で見積もる上限を設け、超える投入は E_VALIDATION で拒否する。ジョブの最大実行時間（watchdog、目安 30 分）を超えたら自動で interrupt する
- 文字列: プロンプト/ネガティブは長さ上限（例: 各 8000 文字）を設け、制御文字を除去する
- ファイル系 API はすべて `<APP_ROOT>` 配下に正規化して検証し、`..` 等の経路脱出を拒否する。シンボリックリンク等を解決した実体パスが許可ディレクトリ配下にあることも確認する
- レート制限: 生成投入はキュー長上限、LoRA 導入は同時 1 件、API 全体に短時間の過剰リクエスト遮断
- LLM: model は導入済み一覧に存在するものだけ。options の範囲は Temperature 0.00–2.00、Top P 0.00–1.00、Repeat penalty 1.00–2.00、Num ctx 512–65536。履歴はメッセージ数 200・合計 200,000 文字を上限とし、超過は E_VALIDATION（アプリ側で要約圧縮・間引きを先に行う前提）
- ヘルパーに管理系エンドポイント（設定変更・ファイルの完全削除など）は置かない。削除は trash 移動まで。例外はロック系（セッション発行・失効・PIN 設定）のみで、いずれもデバイストークン認証の内側にある
- ヘルパーから ComfyUI へ呼ぶ先は固定の許可リスト（`/prompt`、`/history`、`/queue`、`/interrupt`、`/free`、`/system_stats` 等、必要最小限）に限る。クライアント指定のパスやエンドポイントは一切受け付けない
- 容量ガード: ディスク空きが閾値を割ったら LoRA 導入・生成を段階的に止め、理由をアプリに明示する。LoRA 導入は加えて「対象ファイルサイズ ×1.5 ＋ 余裕分」の空きを導入前に確認する

### 9.5 Civitai 導入時の追加検証

- 配置フローは §6.3 の通り（staging → 検証 → 分類フォルダ。失敗は quarantine）
- safetensors ヘッダを検証する（ヘッダ長上限、JSON の妥当性、テンソルのオフセット範囲がファイル内に収まること）
- SHA256 照合は破損・改ざんの検出であり、ハッシュ自体が Civitai 由来である以上「安全なファイル」の保証ではない、という位置づけを明記する（形式検証と併せて対策とする）
- トリガーワード等のメタデータは非信頼テキストとして扱い、長さ上限をかけ、アプリではプレーン表示する（整形・リンク化しない）

### 9.6 ログと監査

- 記録する: 日時、送信元、エンドポイント、結果（成功/拒否）、ジョブ ID、ファイルのハッシュ
- 記録しない: プロンプト本文、会話本文、Civitai キー、トークン、画像データ
- 30 日ローテーション。認証失敗の連続はログ上で目立つ形式にし、定期確認の運用にする

### 9.7 保守アクセスの分離（AI エージェントに保守させる場合）

AI エージェント（例: Muse）にこのアプリの保守をさせる場合の分離モデル。エージェントの能力を「診断」と「更新パッケージ作成」までに絞り、適用はユーザーの承認を必須とする。

- OS アカウント分離は行わず、分離は保守用アクセスの入口で担保する。エージェントの保守用アクセスは専用鍵＋強制コマンドで「結果だけを返す診断コマンド」の許可リスト方式に限定し、通常シェルを与えない。同一 OS ユーザーへの ACL ではセッションを区別できないため、ACL のみで生成物を保護する案は採用しない
- 診断コマンドの例（返すのは機械情報のみ）: status（プロセス状態・ポート・バージョン）、disk（空き容量・フォルダ別使用量）、queue（キュー長・経過時間）、file-check（存在・サイズ・ハッシュ一致）、db-check（整合性・件数・不整合 ID）、staging-report（残留数・経過日数）、log-tail / diag（エラー ID 指定のサニタイズ済み抜粋）、llm-status（常駐モデル名・VRAM・ストリーム数・直近エラーコード）、gpu-status（アービタ状態・待機理由コード）
- **診断は outputs / outputs_locked / 索引 DB の内容列 / プロンプト本文 / 画像本体へ直接アクセスできない**形にし、存在確認・整合性・ハッシュ等の結果だけを返す
- 更新手順: エージェントは更新パッケージ（変更ファイル一式＋マニフェスト＋SHA256）を作成して受付場所へ預けることまではできる。**適用はユーザーの明示承認がある場合に限る**（ユーザーが自分の経路から適用を実行する形とし、制限付きアクセス経由では適用できない）
- ブレークグラス: ヘルパーや診断系自体が壊れた場合に備え、ユーザーが明示的に保守権限を一時解除できる手順を用意する（有効期限つき・自動復帰・全ログ記録。有効化は制限付きアクセスからは行えない）
- 適用範囲は本アプリの保守経路だけに限定し、ユーザーの他の作業用アクセスは対象外とする

### 9.8 スマホ側の堅牢化

- OS バックアップ除外（トークンや設定をバックアップ経路で外に出さない）、広告・解析 SDK なし
- 通信先はコード上で許可リスト化する: ヘルパー、Danbooru、Civitai（表示用に必要な場合のみ）。それ以外の外向き通信をしない
- 配布はサイドロード（Android）等の直接配布のみ。署名検証で正規の更新だけを上書きインストールできる形にする

---

## 10. ヘルパー API 仕様

全エンドポイント共通: `Authorization: Bearer <デバイストークン>` 必須、送信元検証、応答は JSON（画像取得のみバイナリ）。ロックフォルダ系は追加で `X-Lock-Session: <ロックセッション>` 必須とし、毎回「対象レコードの folder 属性 × セッション有無」を検証する。全応答にリクエスト ID（エラー ID と対応）を含める。トークン照合はハッシュ同士の定数時間比較とし、認証失敗が続く場合はバックオフを入れる。

| メソッド/パス | 用途 |
|---|---|
| GET /api/health | 到達確認、ComfyUI 状態、キュー長、ディスク空き、バージョン |
| POST /api/register | ワンタイム登録コードと恒常トークンの交換（§9.3。コード提示が認証） |
| POST /api/gen | 生成投入（モデル ID＋パラメータ＋冪等キー＋保存先フォルダ）→ ジョブ ID。画像起点ジョブは入力参照（`source`: upload_id または output_id。inpaint はマスクの upload_id も）を併せて送る |
| POST /api/upload | 入力画像のアップロード → upload_id、寸法（24 時間で自動削除） |
| POST /api/tagger | 画像（upload_id または output_id）からタグ推論 → スコア付きタグ列（推論は PC 上でのみ行う） |
| GET /api/gen?active=1 | 実行中・キュー中のジョブ一覧（再同期用。ジョブの種別・保存先・進捗を含む） |
| GET /api/gen/{id} | 状態・進捗（ポーリング予備） |
| WS /api/gen/{id}/events | 進捗イベント中継（§4） |
| POST /api/gen/{id}/interrupt | 生成中断（対象が実行中ジョブと一致することをヘルパーが確認） |
| POST /api/lock/challenge | ロック解除用のワンタイム nonce 発行（短時間有効・1 回限り） |
| POST /api/lock/unlock | nonce への署名または PIN を検証し、ロックセッションを発行 |
| POST /api/lock/lock | ロックセッションを即時失効 |
| POST /api/lock/pin | PIN の設定・変更（ロックセッション有効中のみ） |
| GET /api/loras | 導入済み LoRA 一覧（分類・プレビュー参照・トリガーワード・ハッシュ・既定強さ） |
| GET /api/civitai/search | Civitai 検索（キーワード、ベース、NSFW、ソート、ページング）。プレビューは中継 URL のみ返す |
| GET /api/civitai/model/{id} | モデル詳細（バージョン・ファイル・トリガーワード） |
| GET /api/civitai/preview | 検索結果プレビューの中継取得（対象は civitai.com 配下のみに限定） |
| POST /api/civitai/install | ワンタッチ導入（version_id＋file_id。処理は §6.3） |
| GET /api/outputs | 成果物一覧（検索・コレクション・日付・ページング。folder で通常/ロックを分ける） |
| GET /api/outputs/{id}/thumb /full | サムネイル（サーバ側生成・キャッシュ）/ 原本。画像系応答には `Cache-Control: no-store` |
| GET /api/outputs/{id}/meta | メタデータ全文＋再生成用 gen_params |
| POST /api/outputs/{id}/trash / restore | ゴミ箱へ移動 / 復元 |
| POST /api/outputs/{id}/move | フォルダ間移動（通常⇔ロック。実ファイル移動と DB を同期） |
| POST /api/outputs/batch | 複数選択の一括操作（移動・コレクション付け・ゴミ箱） |
| GET/POST/DELETE /api/collections | コレクション（論理フォルダ）の一覧・作成・削除 |
| POST /api/outputs/{id}/favorite | お気に入り切替 |
| GET /api/diag/system | PC 状態スナップショット（CPU / GPU / メモリ / 主要プロセス / ジョブ状態。本文・パス等の秘匿情報は含めない） |
| GET /api/diag/{error_id} | そのエラーのサーバ側ログ抜粋（サニタイズ済み。error_id は厳格に検証し、ファイル名や検索キーに直接使わない） |
| GET /api/llm/models | 導入済み LLM 一覧＋常駐状態 |
| POST /api/llm/chat | チャット送信（model＋履歴＋options）。応答は NDJSON ストリーム中継。待機時は先頭にアービタ待機フレーム `{"type":"arbiter_wait",...}` を出す場合がある |
| GET /api/gpu/status | アービタ状態（常駐/実行中エンジン、VRAM 概数、優先モード、待機ジョブと理由） |
| POST /api/gpu/unload | アイドル常駐の解放（実行中ジョブがある側は E_VALIDATION で拒否。ユーザーの明示操作専用） |

LLM 中継の詳細:
- ヘルパーはストリーミング応答で Ollama `POST /api/chat` を中継する。本文はバイト列のまま流し、保存・変換・フィルタリングをしない。ログ用の集計は最終フレームの eval_count 等の機械フィールドだけを読む
- アプリ側が接続を切ったら上流の Ollama 接続も即時に閉じる。タイムアウトは「トークンが流れ続ける限り無制限、無通信 120 秒で E_LLM_UPSTREAM」とする
- モデル切替時は、他の常駐モデルを解放してから読み込む（VRAM 競合の予防）。上流のエラーは Ollama 自身のエラー文をそのままアプリへ返す

---

## 11. 開発・ビルド・配布

### 11.1 技術スタック（参照実装）

- Android: Kotlin + Jetpack Compose、単一 APK。minSdk / targetSdk は対象端末の到達バージョンに合わせ、無理に広げない。ローカル DB は Room（SQLite）、設定は DataStore 相当
- ヘルパー: Python（FastAPI 等の薄い Web フレームワーク）＋ SQLite。追加ランタイムを増やさない。PC の通常ユーザーで常駐し、OS の自動起動に登録する
- ビルド: JDK 17 系。成果 APK の SHA256 を都度記録する

### 11.2 鉄則: 署名キーを永続化する

**APK の署名キーは、必ずプロジェクト内（または確実に永続化される場所）に置き、ビルド設定で明示的に指定すること。** ビルドマシンの既定デバッグ鍵置き場（例: ビルドユーザーのホーム配下）は、環境のリセットやマシン交換で消えることがある。鍵が変わると、既存アプリへの上書きインストールが OS に拒否され（「パッケージが既存のパッケージと競合」）、アンインストール＝端末内データ（会話 DB・トークン）の喪失を伴う入れ直しになる。初回ビルドの前に鍵の置き場所を決めること。

その他のビルド上の注意:
- Android でネットワーク処理を UI スレッドで同期実行すると即座に例外になる（例外メッセージが空で、画面に「null」とだけ出るような分かりにくい壊れ方をする）。通信は必ずバックグラウンドディスパッチャに載せる
- 依存ライブラリの取得が制限される環境では、ローカルリポジトリへの事前配置＋オフライン構築の経路を用意しておくと安定する

### 11.3 テスト観点（実機で実施）

- 到達確認（VPN 内/外、機内モード等のオフライン表示）
- ロック動作（認証前にロックフォルダの画像が端末のどこにも見えないこと。タスク一覧・通知含む。通常/ロックの API が相互にアクセスできないこと）
- 生成中の着信・バックグラウンド遷移、チャット生成中のタブ切替・他アプリへの移動でも応答が完走すること
- PC 再起動後に全プロセスが自動復帰すること

---

## 12. 実装フェーズと受け入れ基準

| フェーズ | 内容 | 受け入れ基準 |
|---|---|---|
| 0. 基盤・実測 | 環境確定（GPU/VRAM 実測、各 LLM の常駐量とアンロード所要時間、画像生成側の常駐見積もり、安全予算の確定、同時常駐できる組み合わせ）、使うモデルファミリのタグ規則・重み構文の実測、PNG メタデータ方針の実測、ヘルパー雛形＋認証＋登録フロー、専用 ComfyUI の起動、ロックのサーバ側アクセス制御（チャレンジ署名＋ロックセッション）の技術検証、ストリーミング中継の試作 | スマホ実機から /api/health がトークン付きで通り、トークンなし/VPN 外から通らないこと。テンプレート生成が完走し PNG メタデータが実測できること。デバイストークンのみで locked が取得できないこと |
| 1. 生成 MVP | 生成タブ＋進捗＋中断＋キュー＋結果表示＋メタデータ埋め込み、保存先フォルダ（通常/ロック）とロックの認証ゲート（サーバ側セッション込み）、漏れ経路の封鎖、staging→保存先への移動と索引登録、LoRA スロット、エラー分類と診断出力、冪等キー、容量ガード、trash 自動削除、GPU 調停の基礎（常駐確認とアイドル解放） | 既定レシピで生成でき、PNG に 2 系統メタが入り、再生成復元ができること。認証前にロックフォルダの画像が端末のどこにも見えないことを実機確認 |
| 2. ギャラリー | 一覧・検索・コレクション・DL・trash・お気に入り・詳細ページャー・再生成 | ロック中の一覧性と解除後の通常表示が両立すること。横フリックで前後へ移動できること |
| 2.5. 画像タブ | img2img / inpaint / outpaint / Tagger、取り込み（写真ピッカー・共有・ギャラリー流用）、モザイク等の端末内加工 | 各種テンプレートが実機で完走すること |
| 2L. LLM 統合 | チャットタブ（モデル選択、ストリーミング、停止/再生成、通常/ロック会話、会話の自動保存と履歴、再開、要約圧縮）、GPU 優先モードと調停、LLM→画像受け渡し、ストリームの継続性（アプリスコープ＋OS 保持） | 優先モード通りに待機/先行が切り替わり、実行中ジョブが途中で殺されないこと。構造化ブロックの設定が確認シート経由で正しく反映され、未導入 LoRA が明示されること。ロック会話が認証前に復号・送信されないこと。生成中にタブを離れても応答が完走すること |
| 3. LoRA | Civitai 検索/プレビュー（ヘルパー中継）/ワンタッチ導入＋分類反映 | 形式検証＋SHA 照合付きで導入でき、生成スロットで即使えること。検索結果が詳細往復で保持されること |
| 3L. 横断メモリ＋エージェント | 横断メモリ（長押し保存＋候補抽出→承認制、通常/ロック分離）、エージェント的チャット（提案プロトコル）、引き継ぎインポート | ロック側メモリが通常会話に差し込まれないこと。承認なしにメモリが増えないこと。提案がタップなしに実行されないこと |
| 4. タグ | Danbooru 補完＋チップ列＋お気に入り | 補完から挿入まで体感遅延なく動くこと |
| 5. 堅牢化 | ログ運用、トークン失効手順の実演、自動復帰の実施確認、診断パッケージ | 再起動後に全プロセスが自動復帰すること。失効したトークンが即時に通らなくなること |

---

## 13. iOS 版を作る場合の差分（§0.5 の補足）

参照実装は Android。iOS では次が変わる:

- **言語・UI**: Swift + SwiftUI（またはクロスプラットフォーム基盤。ただし鍵ストア・生体認証・バックグラウンド周りは結局ネイティブ実装が必要になる）
- **配布**: ストア外配布の自由度が低い。個人用なら Xcode からの直接インストール（無料証明書は有効期限あり）、開発者登録＋TestFlight、または AltStore 等のサイドロード手段から選ぶ。**署名証明書の期限切れ＝起動不可**に直結するため、更新運用まで含めて設計すること
- **鍵ストア・生体認証**: Keychain＋Secure Enclave 鍵、Face ID / Touch ID（LocalAuthentication）。チャレンジ署名の考え方は Android と共通にできる
- **バックグラウンド実行**: Android のフォアグラウンドサービス相当がない。長時間ストリームの継続は URLSession のバックグラウンド構成や BGTask では完全には代替できないため、「画面を離れたら接続を張り直して続きを取得する」再開方式（サーバ側でストリームを保持し、再接続で追いつく）をヘルパー側に用意する設計に寄せる
- **ファイル・共有**: 写真への書き出しやファイル選択は Photos / Files フレームワーク経由。アプリ間共有は Share Extension
- **ネットワーク**: VPN（Tailscale 等の iOS クライアント）経由は Android と同様に可能。平文 HTTP の許可は ATS の例外設定が必要

---

## 14. 既製品との関係（自作する理由）

「スマホから自宅 ComfyUI に繋いで生成する」部分は既製品アプリでも概ね解けている。本設計だけの要素は主に次の点で、ここに価値を見出す場合に自作する意味がある。

1. Civitai 検索→プレビュー→PC へワンタッチ導入までが 1 アプリで完結する（SHA 照合・分類・トリガー連携込み）
2. 画像表示ロック（フォルダ方式＋サーバ側セッション）
3. A1111 形式メタデータの付与と、PC 側の分類保存・索引検索
4. ローカル LLM チャットとの統合（GPU 調停、受け渡し、エージェント提案、会話の要約圧縮・横断メモリ）
5. ヘルパーによる認証・検証で ComfyUI を直接晒さない構成と、内容に干渉しない保守分離

逆に、保守の担い手が自分（と自分の AI エージェント）に集中する点は自作の弱点として残る。緩和策として、ソースコード・本設計書・ログ形式をすべて手元に残し、他の AI/人間でも引き継げる形にしておくこと。
