title: Umaru 全機能・全仕様書（実コード準拠） version: 1.3.0 date: 2026-06-10 project: Umaru

Umaru 全機能・全仕様書（実コード準拠）

本書は、リポジトリの実装コード（src/ / backend/ / src-tauri/）を読み取って作成した、Umaru v1.3.0 の全機能・全仕様のリファレンスである。既存の仕様書（docs/spec/、docs/end/）が「これから作るものの定義」であるのに対し、本書は「現在のコードが実際に何をするか」を記述する。

1. アプリ概要

項目	内容
製品名	Umaru（うまる）
一言説明	祈璃（いのり）と作る、ローカル PC 完結の画像生成・LoRA 学習デスクトップアプリ
バージョン	1.3.0（`package.json` / `tauri.conf.json`）
識別子	`app.umaru.inori`
対象 OS	Windows（NSIS インストーラ、perMachine、日本語）
対象ユーザー	「自分のキャラクター（この子）」を育てたい創作者。専門用語を知らない初心者を主対象とし、専門モードも用意
設計思想	ローカル完結（クラウド送信なし）・モデル/LoRA/外部辞書/学習スクリプトは同梱しない（ユーザーが用意 or アプリ内で同意の上ダウンロード）・LLM による自動評価をせずユーザーの選択を主体にする

1.1 中核コンセプト

キャラクター中心: すべての生成・学習・整理は「キャラクター（この子）」に紐づく。
創作者向け語彙: Prompt→「描いてほしいこと」、Seed→「雰囲気の種」、Negative→「避けたい描写」、ガチャ的比較生成→「お祈り」、LoRA 学習→「この子を学習する」等、UI 用語を独自の優しい言葉に統一（ui_mode=expert で専門用語を併記）。
失敗の可視化: 生成エラーを 4 分類（設定 / 環境 / リソース / 不具合）して、ユーザーが次に取るべき行動をボタンで提示する。

2. 技術スタックとアーキテクチャ

2.1 技術スタック

レイヤ	技術
デスクトップシェル	Tauri 2（Rust）。スプラッシュ＋メインの 2 ウィンドウ、`decorations:false` のカスタムタイトルバー
フロントエンド	React 19 + TypeScript 5.9 + Vite 7（本番ビルドは esbuild 直叩きの `build.mjs`）、TanStack React Query 5、Zustand 5（ポーズエディタ）、three.js + @react-three/fiber + drei（3D ポーズ）、lucide-react（アイコン）
バックエンド（サイドカー）	Python（同梱 embedded Python）+ FastAPI + uvicorn。`backend.main:app`
DB	SQLite（aiosqlite）。`%APPDATA%/Umaru/data/umaru.db`
画像生成	diffusers（SD1.x / SDXL / ControlNet）、torch（CUDA cu126・Blackwell は cu128・CPU フォールバック）、bitsandbytes（NF4 量子化）、compel（LPW=長文プロンプト）、TAESD / TAESDXL（軽量 VAE）
LoRA 学習	kohya-ss/sd-scripts（`sdxl_train_network.py`）+ accelerate。専用 venv に分離
テスト	vitest + Testing Library + fast-check（フロント）、pytest（バックエンド unit / integration）

2.2 プロセス構成図

graph TB
    subgraph TauriProc["Tauri プロセス (Rust)"]
        SPLASH["スプラッシュウィンドウ<br/>(alwaysOnTop / 480x280)"]
        MAIN["メインウィンドウ<br/>(1280x820 / visible:false で起動)"]
        CMD["Tauri コマンド<br/>start_backend / get_backend_config /<br/>open_folder / select_folder /<br/>save_bytes ほか"]
    end

    subgraph WebView["WebView (React 19)"]
        UI["AppContent<br/>(タブ切替・ジョブ監視・接続監視)"]
        RQ["React Query<br/>(settings / characters / album ...)"]
        POSE["ポーズエディタ<br/>(three.js / Zustand)"]
    end

    subgraph Sidecar["Python サイドカー (FastAPI)"]
        ROUTERS["routers<br/>workflows / settings / jobs /<br/>dictionaries / prompts / release /<br/>training_runtime / diagnostics"]
        SERVICES["services<br/>generation / controlnet / dictionary /<br/>training / settings / vram_queue"]
        DB[("SQLite<br/>umaru.db")]
        FS[("ファイル<br/>outputs / characters /<br/>models / loras / logs")]
    end

    subgraph External["外部プロセス / 外部取得（任意・同意制）"]
        KOHYA["sd-scripts (kohya)<br/>専用 venv で subprocess 実行"]
        HF["Hugging Face<br/>(ControlNet モデル / 軽量VAE)"]
        PYPI["PyPI / PyTorch wheel index<br/>(依存インストール)"]
    end

    MAIN --> UI
    UI --> RQ
    UI --> POSE
    UI -- "Tauri invoke" --> CMD
    CMD -- "spawn + token(stdin) + UMARU_PARENT_PID" --> Sidecar
    RQ -- "HTTP 127.0.0.1:<port><br/>X-Umaru-Token" --> ROUTERS
    UI -- "WebSocket ?token=" --> ROUTERS
    ROUTERS --> SERVICES
    SERVICES --> DB
    SERVICES --> FS
    SERVICES -- "subprocess" --> KOHYA
    SERVICES -- "httpx / pip" --> HF
    SERVICES -- "pip" --> PYPI

2.3 起動シーケンス

sequenceDiagram
    participant T as Tauri (Rust)
    participant S as スプラッシュ画面
    participant P as Python サイドカー
    participant M as メイン画面 (React)

    T->>S: 表示（alwaysOnTop）
    T->>T: Python 環境セットアップ<br/>(embedded python 展開・依存確認)
    T->>P: spawn（token を stdin、親PID を環境変数で渡す）
    P->>P: startup: ディレクトリ作成 → DB migrate →<br/>親プロセス監視開始 → ジョブ掃除タスク →<br/>同梱辞書の取り込み / 既存辞書の正規化（非同期）
    T->>P: /healthz と /api ready をポーリング
    P-->>T: ready
    M->>T: get_backend_config（リトライ 400ms 間隔）
    T-->>M: { baseUrl, token }
    M->>P: settings / characters / album を取得
    Note over M: baseDataReady 成立
    M->>T: show_main_window（スプラッシュは手前に残る）
    M->>M: 2フレーム + 120ms 待ち（初回描画コミット）
    M->>T: close_splashscreen
    Note over M: 以後 15 秒間隔で /api/heartbeat

サイドカーは親プロセス（Tauri）の死活を 2 秒間隔で監視し、親が消えたら自分も終了する（孤児プロセス防止）。ハートビート切れ単独では停止しない（重い処理によるイベントループ停止を「親の死」と誤認しないため）。
終了時は Tauri 側 stop_backend でも停止。サイドカーの標準出力は logs/sidecar.log へ。

2.4 通信・認証

項目	仕様
HTTP	`http://127.0.0.1:<port>`（dev 既定 17891）。全 API は `X-Umaru-Token` ヘッダ必須（`/healthz`、画像系 GET を除く）
トークン	起動時に Tauri が生成し stdin でサイドカーへ渡す。dev は `UMARU_DEV_TOKEN=dev-token`。比較は `secrets.compare_digest`
WebSocket	`/ws/jobs/{job_id}`・`/ws/setup/progress`・`/ws/remembering/{session_id}`。`?token=` クエリで認証、不一致は code 4401 で close
画像 GET	`<img>` タグから参照するため `?token=` クエリ方式（album image / thumbnail / memory thumbnail / download）
CORS	`tauri://localhost`・`http(s)://tauri.localhost`・`http://127.0.0.1:5173`・`http://localhost:5173` のみ許可
CSP	`default-src 'self'`、画像は `self + 127.0.0.1 + data: + blob:`、接続は `ipc: + 127.0.0.1(ws含む)` のみ

3. 画面構成とナビゲーション

3.1 タブ一覧

左ドロワー（ハンバーガーメニューで開閉、Escape で閉じる）に表示される 11 項目＋非表示 3 タブ。

タブ key	表示名	概要	ナビ表示
`home`	ホーム	主要画面への入口カード・統計・キャラ切替・権利注意	✓
`setup`	初回セットアップ → ステータス	環境診断とライブラリ自動インストール	✓（接続成功後は「ステータス」へ改名）
`characters`	キャラクター	キャラの作成・編集・削除・Prompt 雛形・カード画像	✓
`generate`	つくる	画像生成（txt2img / img2img / ControlNet）	✓
`pose`	ポーズ	3D 骨格ポーズエディタ（β）。i2i 下絵 / OpenPose 制御画像を出力	✓
`album`	アルバム	生成履歴の閲覧・復元再生成・整理	✓
`memory`	学習素材	キャラの見本画像（学習データ候補）一覧	✓
`prayer`	お祈り	A〜D 組の比較生成 → ランク付け → 決勝候補保存	✓
`remember`	この子を学習する	学習素材から SDXL LoRA を学習	✓
`dictionaries`	辞書	タグ辞書（日本語訳付き）の取り込みと閲覧	✓
`settings`	設定	フォルダー・NSFW・EXIF・用語モード・法的通知	✓
`growth`	この子の成長アルバム	段階を積み重ねるプロンプト育成（ナビ非表示の機能タブ）	✕
`experiment`	プロンプト実験室	日本語→タグ解決 API の確認用	✕
`release`	配布準備	プロフィール JSON エクスポートと配布ゲート確認	✕

3.2 生成中のタブブロック

生成ジョブ実行中は、重い処理の衝突を避けるため移動可能タブを制限する。ブロック時は理由バナーを表示する。

区分	タブ
生成中も開ける	home / setup / album / characters / memory / growth / dictionaries / pose
生成中ブロック（理由メッセージ付き）	generate（新規生成不可）/ prayer / remember / experiment / release / settings
セットアップのインストール中	setup 以外すべてブロック

ポーズ画面はローカル完結のため生成中も編集可。ただし i2i / ControlNet への投入ボタンだけ抑止。
ブロック対象を開こうとした場合、サイドバー項目に「生成中」「準備中」バッジを表示し、押下時に理由バナーを出す。

3.3 共通 UI

カスタムタイトルバー: 最小化 / 最大化切替 / 閉じる / ドラッグ移動をフロントから Tauri API で実行。
接続ピル: connected / checking / unstable / disconnected / restarting の 5 状態。詳細パネルから再取得可能。15 秒間隔のハートビートで監視。
トップバー: ホーム以外では「ホームに戻る」ボタン常設。生成最小化中は「生成中の処理があります」バッジ（クリックで進捗オーバーレイ復帰）。
起動失敗画面: 基礎データ取得失敗かつ切断状態なら StartupFailureScreen（再試行ボタン）へフォールバック。
エラーバウンダリ: フロントの未処理例外 / unhandledrejection は Tauri 経由で logs/frontend.log 相当に記録（log_frontend_error）。

4. 機能仕様（画面別）

4.1 ホーム

統計メトリクス: キャラクター数 / アルバム枚数 / 用語モード（取得失敗時は「確認不能」表示）。
「今のキャラ」セレクタ: ドロワーを開かずにメインのキャラクター選択を切替（選択は localStorage:umaru_selected_character_id に永続化し、つくる画面と双方向連動）。
主要画面への入口カード（10 枚）。生成中 / インストール中のブロック状態をカード上にもバッジ表示。
外部素材の権利についての注意書き（モデル・LoRA・辞書は同梱しない旨と、取得元ライセンス確認の案内）。

4.2 初回セットアップ／ステータス

環境を診断し、不足分をボタン一つでインストールする画面。タブ名は状態で変化する（未訪問:「初回セットアップ」→ 訪問済み未接続:「未セットアップ」→ 一度でも接続成功:「ステータス」）。

4.2.1 診断項目（GET /api/setup/status）

項目	判定内容
Python 実行環境	同梱 python（`python/python.exe`）または venv の存在
基本ライブラリ	fastapi / aiosqlite の import 可否
SDXL ライブラリ	diffusers / torch / peft / bitsandbytes の import ＋ GPU 機では torch の CUDA 対応（profile: cuda / cpu / missing）
GPU	CUDA GPU の検出（生成は CPU でも可・LoRA 学習は CUDA 必須と文言を分離）
モデルフォルダー	存在＋モデル検出（`.safetensors` / `.ckpt` / `.pt` / `.pth` / `model_index.json` を含むフォルダ）
LoRA フォルダー	任意。存在すれば一覧
学習ツール（sd-scripts）	`train_network.py` だけでなく SDXL 用 `sdxl_train_network.py`・networks/・library/・requirements.txt が揃った一式かを検査
辞書	取り込み済みエントリ数
出力フォルダー	存在＋書き込みテスト（`.umaru_write_test` の書き込み/削除）

各診断行は status（ready / needs_action / warning / checking / failed_check ほか）、necessity（生成に必須 / 学習に必須 / 任意 / 情報）、初心者向け 3 段説明（cause 原因 / next 次の操作 / beginner かみ砕き説明）、実行アクション（インストールボタン等）を持つ。

4.2.2 インストール導線

アクション	API	内容
基本ライブラリ	POST /api/setup/install-dependencies	requirements.txt を pip install
SDXL ライブラリ（GPU 版 / CPU 版）	POST /api/setup/install-sdxl	requirements-sdxl.txt。profile=auto/cuda/cpu。GPU 世代判定で wheel index を自動選択（Ampere〜Hopper: cu126、Blackwell(RTX50 等 compute capability major≥10): cu128、CPU: cpu）
同梱 Python	POST /api/setup/install-python	Python 環境の存在確認のみ（実際の展開は Tauri 起動時の setup_python_environment が担当。無ければ再インストール案内エラー）
辞書ダウンロード	POST /api/setup/download-dictionary	同意必須の外部辞書取り込み

進捗は WS /ws/setup/progress で配信。インストール中は他タブへの移動を全ブロック。
補足: 生成中はインストール系ボタンを抑止。

4.3 キャラクター

「今育てている子」の管理画面。

一覧: 集計付きサマリー（/api/characters/summaries。失敗時は素のキャラ一覧で縮退表示）。カード画像は「固定したカード画像（cover）＞最新生成画像」の優先で表示。
作成: 名前（必須 1〜80 字）・よみがな・コンセプト・性格・世界観メモ。
編集: 上記に加え、LoRA 紐付け（linked_lora_path / linked_lora_trigger_word）。
Prompt 雛形（IA-13）: キャラ固有の default_positive_prompt / default_negative_prompt と適用モード prepend（既定。入力の前に置く）/ append / replace。つくる画面・お祈りで自動適用される。
特徴パネル状態: つくる画面の「キャラクターの特徴」ビルダー選択を JSON 文字列（builder_state）でキャラごとに保存。
カード画像: アルバム詳細から「カード画像として固定」（PUT /characters/{id}/cover）・解除。
削除（IA-02）: ソフトデリート（status='deleted'）。生成中は危険操作を抑止。削除キャラが選択中だった場合は残りの先頭キャラへ自動切替。

4.4 つくる（画像生成）

メインの生成画面。フォームは localStorage:umaru_generate_form_v1 に永続化される。

4.4.1 生成モード

モード	入口	仕様
txt2img	既定	プロンプトから生成
img2img	アルバム「書き直し」/ ポーズ「i2i に送る」	`source_generation_id` の画像を元に再描画。「元画像の残し具合」denoise 0.1〜0.95（既定 0.55）。解除ボタンで txt2img へ戻る
ControlNet (OpenPose)	ポーズ「ControlNet に送る」	OpenPose 制御画像（base64 data URL）で構図転写。効き具合スライダー 0.1〜1.5（既定 0.9）。SDXL 系モデル専用

3 モードは同一フォームを共有し、ControlNet ＞ img2img ＞ txt2img の優先で送信先 API を切り替える（/api/pose/controlnet / /api/img2img / /api/generate）。

4.4.2 フォーム項目

項目	範囲 / 選択肢	既定値
モデル	model_dir のスキャン結果から選択	先頭モデル
キャラクター	登録キャラから選択（メイン選択と双方向連動）	選択中キャラ
解像度プリセット	正方形 1024² / 縦長 832x1216 / 横長 1216x832 / 正方形・小 768² / 縦長・大 1024x1536 / 横長・大 1536x1024 ＋カスタム（64〜2048）	1024x1024
描いてほしいこと（positive）	自由入力＋タグ支援	`1girl, smile, long hair`
避けたい描写（negative）	自由入力＋お守り	`lowres, bad anatomy`
LoRA	最大 5 件。各行 = LoRA 選択＋強度 0.0〜2.0（既定 0.8）	なし
描き込み量（steps）	1〜150	25
指示への忠実度（CFG）	1.0〜30.0	7.0
雰囲気の種（seed）	0=自動（毎回ランダム）	0
スケジューラ	default / ddim / pndm / lms / euler_ancestral / euler / dpm	default
NF4 量子化	ON/OFF（CUDA 必須）	OFF
長いお祈り（LPW）	ON/OFF（compel による 75 トークン超え対応）	OFF
軽量 VAE	ON/OFF（TAESDXL / TAESD。失敗時フル VAE に自動フォールバック）	ON

4.4.3 プロンプト支援機能

機能	仕様
タグ検索	辞書 API（`/api/dictionaries/search`）で日本語・英語の両方から検索し、日本語ラベル付き候補を挿入。NSFW レベル設定でフィルタ
キャラクターの特徴パネル	髪（長さ/型/質感/アホ毛/色）・目（色/形/特徴）・表情・身体（身長/体型/胸/その他）・服装（カテゴリ/系統）をプルダウンで選び実在 Danbooru タグへ変換。選択状態はキャラごとに保存・復元
カラーピッカー	HEX → HSL 変換で最近傍の髪色 / 目色 / 服色タグを決定（`/api/tags/color-to-tag`。例: `#FFD700`→`blonde_hair`）。日本語ラベルも返す
お守りチェック（negative charms）	5 種のプリセット negative 集（絵の崩れ☑既定 / 手の崩れ☑既定 / 余計な文字 / 低解像感 / 服や体の破綻）。送信直前にユーザー negative とマージし、重複は正規化のうえ除去。最終 negative はプレビュー表示
言葉の整頓	完全一致タグの重複除去＋矛盾検出（smile↔expressionless、open mouth↔closed mouth、looking at viewer↔looking away、standing↔sitting、day↔night）。矛盾は自動削除せず通知のみ
ボリューム目安	単語数×1.2＋カンマ×0.3 の概算トークン。≤60: 届きやすい / ≤75: 少し長め / >75: 後ろの言葉が届きにくい（LPW 有効時は文言変化）。「目安」と明記
雰囲気の種ピッカー	お気に入り seed（favorite_seeds）一覧から seed を呼び出して固定
NSFW 警告	`nsfw_filter` 有効時、positive に nsfw/nude/explicit/成人向け/裸/露骨を含むと生成前警告
辞書未取込通知	辞書 0 件のとき辞書画面への導線を表示

4.4.4 キャラ雛形の適用と重複除去

positive: 雛形を適用モード（prepend / append / replace）に従って合成。
negative: ユーザー入力＋キャラ専用 negative をマージ。
いずれも合成後に大文字小文字・空白差を無視した完全一致タグ重複を 1 件に正規化（重み付き (tag:1.2) は別タグ扱い）。

4.4.5 生成ブロック条件

生成ボタンは以下のとき無効（理由をツールチップ表示）。

生成リクエスト送信中
モデル未選択（名前と実パスの両方が必要。アルバム復元でモデルファイル消失時は名前だけ残して path 空= 未選択扱い、勝手に別モデルへ差し替えない）
モデル一覧チェックが ready でない
img2img なのに元画像未指定

4.5 ポーズエディタ（β）

three.js による 3D 骨格ポーズ作成。すべてローカル完結で、生成中も編集可能。

4.5.1 骨格仕様

COCO-18 キーポイント（id 0〜17: nose / neck / 両肩肘手首 / 両腰膝足首 / 両目耳）＋ Umaru 独自の体幹リグ（id 18〜20: pelvis / spine / chest。書き出し時は除外）。
ジョイントは左=赤系 / 右=青系 / 中央=緑系の色分け。ドラッグで移動（FK: 子ジョイント追従）。
カメラ（軌道 / ズーム）と書き出し解像度は Zustand ストアで管理。

4.5.2 プリセット（11 種）

T-Pose / A-Pose / Stand / Sit / Walk / Wave / Cheer / ArmsCrossed / Run / Crouch / SitTurn

4.5.3 エクスポート（ExportPanel）

出力	内容
PNG 保存	WebGL キャンバスを PNG 化しネイティブ保存ダイアログへ（非 Tauri 環境はブラウザダウンロード）
OpenPose JSON	OpenPose 1.3 互換（`pose_keypoints_2d` = COCO-18×3）＋独自拡張 `pose_keypoints_3d`（再編集用。標準コンシューマは無視）
OpenPose 制御画像	棒人間（OpenPose 配色）をレンダリングした PNG。ControlNet 入力用
i2i に送る	ポーズ PNG を `POST /api/pose/to-i2i` でアルバムに取り込み、その generation を元画像とした img2img 復元経路で「つくる」へ遷移（denoise 値も引き継ぐ）
ControlNet に送る	制御画像 data URL を AppContent の state 経由（localStorage に残さない）で「つくる」の ControlNet モードへ

生成中は i2i / ControlNet 投入のみ抑止（編集・保存は可能）。

4.5.4 ControlNet モデルの取得

同梱せず、アプリ内レジストリからユーザー操作でダウンロードする（ライセンス同意チェック必須）。
現行レジストリ: xinsir/controlnet-openpose-sdxl-1.0（約 2.5GB、Apache-2.0）。
Hugging Face resolve URL を httpx でストリーミングし、models/controlnet/xinsir-openpose-sdxl/ に diffusers 形式（config.json + safetensors）で保存。進捗はポーリング（GET /api/pose/controlnet/download/status）。同時実行は 1 件。
設定の controlnet_openpose_path で手動配置モデルの指定も可能。

4.6 アルバム

生成履歴（generations テーブル）の閲覧・整理・再生成のハブ。

4.6.1 一覧

キャラ絞り込み: すべて / キャラ未紐付け / キャラ別。件数サマリー表示、ページング。
キャラタグ一括変更（v1.3 新機能）: 複数画像を選択して別キャラ（または「キャラ未紐付け」= NULL）へ付け替え（POST /api/album/reassign-character）。絞り込み表示へ即反映。
画像ファイルが消えている行は一覧取得時に検出して DB から自動削除（reconcile）。

4.6.2 詳細モーダル

画像表示（クリックで実寸）・生成情報（プロンプト / negative / モデル / seed / サイズ / LoRA / スナップショット）。
タグチップ表示: resolved_positive をタグ分解し、辞書の日本語ラベルを併記。タグ単位で「つくる」への追記が可能。
操作（生成中は全て抑止）:

ボタン	動作
同じ設定で再現	復元 API でフォームを完全復元し「つくる」へ（自動生成はしない）
種を固定して再現	同上＋seed を保存値に固定
書き直し（img2img）	この画像を元画像に img2img モードで「つくる」へ
タグを追記	選択タグを現在のフォーム positive へ追記
学習素材へ保存	character_memory_images へコピー（role 指定）
カード画像に固定 / 解除	キャラの cover_image_id を設定 / クリア
1 枚だけキャラ変更	詳細画面からの単体キャラタグ付け替え（v1.3）
保存先を開く	画像のあるフォルダをエクスプローラで開く（ID のみ受け取り、shell=True 不使用）
ダウンロード	PNG / JPG 形式選択。EXIF 削除設定に従って再保存
削除	DB 行と画像ファイルを削除

※「PNG で保存 / JPG で保存」の旧 2 ボタンは HF-07 で削除済み（元ファイルは「保存先を開く」から）。

4.6.3 復元（再生成）仕様

GET /api/album/{id}/restore は settings_snapshot からフォームを再構築し、警告リストを添えて返す。

seed: 列 → snapshot の順で参照。無し / 0 →「自動に戻しました」警告。
モデル: snapshot の model_path が消えていれば「モデル名だけ復元」警告＋path 空（自動で別モデルへ差し替えない。ユーザーの明示選択が必要）。
LoRA: snapshot の {path, name, weight} 配列を全件復元（複数 LoRA 対応）。1 件でも消えていれば警告。旧形式（文字列）にもフォールバック。
denoise_strength / scheduler / NF4 / LPW / サイズ / steps / CFG も復元。
復元時は復元元のキャラへメイン選択も同期する。

4.6.4 お気に入りの種（favorite_seeds）

「この雰囲気を呼び出したい」seed のメモ帳。

保存項目: seed・名前（〜120 字）・メモ・rank（1〜999）・モデル名 / ハッシュ・sampler・CFG・steps・プロンプト / 設定スナップショット・参照画像。
キャラ / モデルで絞り込み一覧、削除。つくる画面の種ピッカーから呼び出し。

4.7 学習素材（memory）

キャラ別の見本画像一覧（サムネイル＋役割ラベル＋説明メモ）。
役割（role）: identity / outfit / expression / pose / style / background / training_candidate / rejected。
入口はアルバム詳細「学習素材へ保存」とお祈りの決勝候補保存。保存時に画像を characters/<id>/memories/ へ物理コピーし、プロンプト / 設定スナップショットも保持。
POST /api/memory-images/{id}/mark-training-candidate で学習候補マーク。PATCH で役割・キャプション等を編集、DELETE で削除。

4.8 お祈り（比較生成）

「願い事」を 4 つの組（A〜D）で同時に試し、勝ち残りを選ぶ比較生成ワークフロー。

flowchart LR
    CREATE["① 願い事を書く<br/>モデル選択・候補数 3〜10<br/>（お祈りラボのテーマ選択）"]
    GEN["② A〜D 組の候補生成<br/>（組ごとにジョブ・進捗・ログ）"]
    RANK["③ ランク付け<br/>各組で 1〜3 位を選ぶ"]
    SAVE["④ 決勝候補を確定<br/>学習素材へ保存（最大 4×3=12 枚）"]
    DONE["⑤ 完了"]
    CREATE --> GEN --> RANK --> SAVE --> DONE
    GEN -- "部分失敗" --> FILL["不足分だけ補う<br/>fill_missing"]
    FILL --> GEN
    GEN -- "作り直し" --> REGEN["既存候補を破棄して<br/>regenerate"]
    REGEN --> GEN

4.8.1 セッション作成

キャラ必須・願い事（wish）必須・使用モデル必須（未指定ならモデルフォルダ先頭を自動選択。モデル 0 件なら開始不可）。
A〜D の 4 組を requested_count=5 で自動作成。
キャラ雛形 / LoRA の引き継ぎ: つくる画面と同じ雛形適用・LoRA リストを引き継ぐ（v1.2 系修正で雛形の二重適用を解消、lora_list を反映）。

4.8.2 お祈りラボ（compare_theme）

組ごとに条件を変えて比較する実験モード。テーマは後から変更も可能（PATCH compare-theme）。

テーマ	A 組	B 組	C 組	D 組
`none`（いつものお祈り）	差なし	差なし	差なし	差なし
`cfg`	CFG 3.5	CFG 5.5	CFG 7	CFG 9
`sampler`	Euler	Euler Ancestral	DPM-Solver	DDIM（ホワイトリスト外指定は default に丸め）
`prompt_tag`	追加なし	`smile`	`looking at viewer`	`simple background`

値・ラベルは compare_config でカスタム可能。各組には variation_label と generation_overrides（cfg_scale / scheduler / positive_append）が保存され、候補生成時に適用される。

4.8.3 組の候補生成

1 組 = 1 ジョブ。組内で候補を順次生成し、current_index / generated_count / failed_count / last_error を進捗配信。
seed 重複回避: 同一セッション内で使用済み seed を集合管理し、意図しない重複を避ける（IA-10）。
生成モード: generate（追加）/ fill_missing(requested_count への不足分のみ) / regenerate（既存破棄）。
部分失敗時はジョブが partial / partial_failed で終わり、UI は「不足分だけ補う」「作り直す」を提示。生成ログ表示・キャンセル可。

4.8.4 ランク付けと保存

候補に 1〜3 位を付与（PATCH rank）。finalize-groups で決勝候補化。
save-winners で各組 1〜3 位（最大 12 枚）を学習素材（character_memory_images）へ保存し、保存数を可視化。
実際に使われた seed は候補に保存され、UI に表示される。

4.9 この子の成長アルバム（growth）

プロンプトを段階的に積み上げ、各段階の「正解画像」を選んで育てる記録機能。LLM 自動評価や自動プロンプト書き換えは行わない。

セッション: キャラ・タイトル・base_prompt。
段階（step）: 種別（base / identity / outfit / scene / lighting / style）・ラベル・prompt_append・メモ。段階ごとにアルバムから採用画像（selected_generation_id）を選ぶ（同キャラの画像を優先表示）。
分岐（branch）: 「段階 N までを元に別ルートを作る」。from_step_index までの段階を新セッションへコピーし、parent_session_id / parent_step_index で系譜を保持。
削除可。一覧はキャラ絞り込み対応。

4.10 この子を学習する（LoRA 学習）

4.10.1 学習ランタイムの自動オンボーディング（TrainingRuntimePanel）

sd-scripts を GitHub から同意の上で自動取得し、専用 venv を構築する。

stateDiagram-v2
    [*] --> not_installed: 初期状態
    not_installed --> consent_required: 同意して有効化<br/>(consent.json 保存)
    consent_required --> downloading: セットアップ開始
    downloading --> extracting: ZIP 取得完了<br/>(sha256 検証)
    extracting --> creating_venv
    creating_venv --> installing_dependencies: torch ほか<br/>(profile: cuda/cpu)
    installing_dependencies --> verifying
    verifying --> ready
    downloading --> error: 失敗
    extracting --> error
    creating_venv --> error
    installing_dependencies --> error
    verifying --> error
    error --> downloading: 再実行
    ready --> downloading: 更新(update)
    ready --> not_installed: リセット(reset)

manifest（training_runtime_manifest.json）に取得元 URL・commit・sha256 を固定。未固定だと配布ゲートが pending になる（開発時のみ「未固定でも進める」チェックで回避可）。
配置: %APPDATA%/Umaru/training/（sd-scripts/current・venv・cache）。ログは logs/kohya/。
状態 API はインストール済み判定を実ファイル観測（sdxl_train_network.py の存在・venv の torch / accelerate import・CUDA 可否）で行い、進行中状態を優先表示。キャンセル / リセット / ログ閲覧あり。
GPU 判定: 学習は CUDA 必須。システム CUDA 検出から推奨プロファイルを提示（Blackwell は cu128 wheel）。

4.10.2 学習セッション

sequenceDiagram
    participant U as UI (RememberView)
    participant B as バックエンド
    participant K as sd-scripts (accelerate)

    U->>B: POST /characters/{id}/remember/prepare<br/>(名前・トリガーワード・学習素材 ID 群)
    B->>B: データセット作成<br/>characters/<id>/lora_training/<session>/dataset<br/>画像コピー + キャプション .txt
    U->>B: POST /remembering-sessions/{id}/start
    B->>B: config.toml + dataset.toml 生成
    B->>K: accelerate launch sdxl_train_network.py<br/>--config_file --dataset_config
    loop 進捗
        K-->>B: stdout（step / loss をパース）
        U->>B: GET progress または WS /ws/remembering/{id}
        B-->>U: steps_completed / total_steps / loss / ETA
    end
    K-->>B: 完了
    B->>B: characters/<id>/loras/<name>.safetensors
    U->>B: キャラへ LoRA 紐付け（linked_lora_path / trigger_word）

学習設定（8GB VRAM = RTX 3070 級でも回る前提の固定プロファイル）:

項目	値
スクリプト	`sdxl_train_network.py`（SDXL 専用。train_network.py 単体では ready 扱いしない）
network	networks.lora、dim 32 / alpha 16、U-Net のみ学習（TE 出力キャッシュと併用）
バッチ / エポック	batch 1、max 10 epochs、1 epoch ごとに保存
最適化	AdamW8bit、lr 1e-4、cosine_with_restarts、warmup 100、bf16（保存も bf16）、seed 42
VRAM 最適化	gradient_checkpointing、latents / TE 出力をディスクキャッシュ、SDPA（xformers 非同梱）、workers 2
データセット	`--dataset_config` 方式（`N_name` サブフォルダ不要のベタ置き）。1024² バケット（256〜1024、no_upscale）、num_repeats 10、caption 拡張子 .txt、keep_tokens 1、shuffle なし（TE キャッシュと排他のため）

停止（stop）で subprocess を terminate。学習で増えた LoRA ファイルは差分検出。
進捗 ETA は「あと N 分程度」の日本語表現で表示。

4.11 辞書

タグ辞書（英語タグ＋日本語ラベル＋カテゴリ＋NSFW レベル）の管理。

機能	仕様
同梱辞書の自動取り込み	起動時に `resources/tags/tags_ja.csv`（自作・Unlicense）を冪等インポート（CSV 署名で再取込判定）。起動を妨げない非同期実行
フォルダ取り込み	`%APPDATA%/Umaru/dictionaries/` 直下の CSV を一括インポート（`POST /api/dictionaries/import-folder`）。失敗ファイルは個別レポート
自作 / 外部辞書の登録	ファイル名・出典名・出典 URL・ライセンス名・日本語訳列の有無を指定。外部辞書は利用条件への同意チェック必須（未同意は 400 consent_required）
タグ正規化	`_`（アンダースコア）を含むタグの正規化を起動時に既存エントリへも非同期適用
検索	英語前方・部分一致＋日本語ラベル検索。NSFW レベル（safe / sensitive / explicit）で絞り込み。つくる画面のタグ候補・色タグの日本語ラベル付与にも利用
反映済み一覧	カテゴリタブ（Danbooru type 由来）＋検索＋ページングで DB 内エントリを閲覧
その他	件数表示（`/api/dictionaries/count`）、辞書フォルダをエクスプローラで開く

4.12 プロンプト実験室（experiment）

日本語の「描いてほしいこと / 避けたい描写」を POST /api/prompt/resolve に渡し、辞書ベースのタグ解決結果（JSON）を確認する開発・検証用画面。NSFW レベルは設定値を使用。

4.13 配布準備（release）

エクスポート: キャラのプロフィール JSON を生成（Yurari 向け / Suzuna 向け）。モデル・音声素材は同梱せず、プロフィール情報と参照画像情報のみ書き出し、exports テーブルに記録。
リリース確認: GET /api/release/status の配布前ゲート一覧を表示。

配布前ゲート（全 ready で配布可）

ゲート	判定
licenses	`LICENSES/third-party-licenses.json` の blocked / needs_review / runtime_missing がすべて 0
real_model	直近の実モデル推論診断（`logs/inference-check-*.json`）で real_gpu / real_cpu 実績あり＆placeholder のみでない
training	sd-scripts manifest の commit / sha256 固定＋セットアップ状態
eula / notice	EULA.txt / NOTICE.txt の同梱確認
checksums	`checksums.sha256` 生成済み
installer	`src-tauri/target/release/bundle` に NSIS インストーラあり
signing / defender / smartscreen	`docs/RELEASE_CHECK_YYYY-MM-DD.md` による人手確認記録（機械判定はせず存在確認のみ）

4.14 設定

区分	項目
フォルダー	model_dir / lora_dir / kohya_dir / output_dir（それぞれネイティブのフォルダ選択ダイアログ、既定値取得、存在・書込・スクリプト有無の状態表示付き）。controlnet_openpose_path（ファイル選択）
表示	ui_mode: creator（通常モード）/ expert（専門モード）。用語ラベルの言い換えのみで生成ロジックは不変
安全	nsfw_filter（生成前警告）、danbooru_nsfw_level（safe / sensitive / explicit。辞書検索・候補の表示範囲）
プライバシー	remove_exif_by_default（PNG への Umaru メタデータ保存とダウンロード時の再保存に作用。既定 ON）
法的通知	NOTICE.txt / EULA.txt / 第三者ライセンス一覧 / モデル・LoRA・辞書の注意 / 要確認ライセンスの所在と存在チェック表示

設定は app_settings（key-value）に保存され、PATCH 後に全クエリを再取得する。

5. 生成エンジン内部仕様

5.1 生成パイプライン全体

flowchart TD
    REQ["生成リクエスト受付<br/>(job 作成・受付ログ)"] --> VQ["VRAM キュー獲得<br/>(asyncio.Lock で生成/学習を直列化)"]
    VQ --> CHK{"モデル選択<br/>・実在チェック"}
    CHK -- "未選択/消失" --> ERRC["typed error<br/>(model_not_selected / model_not_found)"]
    CHK -- OK --> ROUTE{"control_image_path<br/>あり?"}
    ROUTE -- なし --> FAM["モデル系統判定<br/>名前 → model_index.json →<br/>safetensors キー → 拡張子"]
    ROUTE -- あり --> CN["ControlNet 経路<br/>(隔離レンダラ)"]
    FAM --> TVAE{"軽量VAE ON?"}
    TVAE -- はい --> TLOAD["TAESDXL / TAESD を先行ロード<br/>失敗時はフル VAE へフォールバック"]
    TVAE -- いいえ --> CACHE
    TLOAD --> CACHE{"パイプライン<br/>キャッシュ命中?"}
    CACHE -- hit --> LORA
    CACHE -- miss --> LOAD["キャッシュ全解放<br/>(ControlNet 側常駐も解放)<br/>from_single_file / from_pretrained"]
    LOAD --> NF4{"NF4 量子化 ON?"}
    NF4 -- はい --> Q["bitsandbytes Linear4bit へ<br/>UNet / TE を置換 (CUDA必須)"]
    NF4 -- いいえ --> GPU
    Q --> GPU["device 配置 +<br/>CUDA 最適化<br/>(xFormers or attention slicing /<br/>VAE slicing / channels_last)"]
    GPU --> LORA{"LoRA 指定あり?"}
    LORA -- はい --> LAPPLY["各 LoRA を adapter としてロード<br/>set_adapters で個別強度適用<br/>(fuse しない)"]
    LORA -- いいえ --> SCHED
    LAPPLY -- 失敗 --> ERRL["lora_load_failed<br/>(キャッシュ破棄)"]
    LAPPLY --> SCHED["スケジューラ差し替え<br/>(default 以外)"]
    SCHED --> SEEDX["seed 確定<br/>(0/None → random 1〜2^31-1)"]
    SEEDX --> LPW{"LPW ON?"}
    LPW -- はい --> COMPEL["compel で埋め込み生成<br/>(SDXL: pooled 付き)"]
    LPW -- いいえ --> INFER
    COMPEL --> INFER["推論実行<br/>callback_on_step_end で<br/>進捗 55→89% (s/step 表示)"]
    CN --> INFER
    INFER --> DECODE["VAE 復号"]
    DECODE --> SAVEIMG["PNG 保存<br/>outputs/YYYY-MM-DD/<br/>メタデータ付与 (EXIF 設定準拠)<br/>output_dir へコピー"]
    SAVEIMG --> DBINS["generations へ INSERT<br/>(snapshot + engine 情報)"]
    DBINS --> DONE["job completed<br/>(generation_id / seed / engine)"]

5.2 モデル系統判定

優先	判定	結果
1	名前に illustrious / pony / sdxl 等	illustrious / pony / sdxl
1	名前に anything v3 / sd1.5 系表記	sd1
2	diffusers ディレクトリの `model_index.json` `_class_name`	XL を含む→sdxl、StableDiffusionPipeline→sd1
3	safetensors のメタデータ / キー（`text_encoder_2` や `conditioner.embedders.1.`→sdxl、`cond_stage_model.`→sd1）	sdxl / sd1
4	フォールバック	単一ファイル→sd1、フォルダ→sdxl

パイプラインは sdxl / illustrious / pony → StableDiffusionXLPipeline、その他 → StableDiffusionPipeline。

5.3 パイプラインキャッシュ

プロセス内に 1 つだけ保持（キー: モデルパス＋更新時刻 / LoRA 構成＋強度 / 種別 / device / NF4 / スケジューラ / 軽量 VAE 使用）。
同一キーの連続生成はロード時間ゼロ（「前回読み込んだモデルを使っています」）。
通常生成キャッシュと ControlNet キャッシュは相互排他で、ミス時に他方も解放する（8GB 機での二重常駐 → 共有 GPU メモリ落ち対策。v1.3）。

5.4 CUDA / 性能オプション

機能	内容
CUDA プリフライト	生成前に簡易カーネル実行で「GPU と torch ビルドの不整合」（例: Blackwell + cu126）を早期検出 → `cuda_kernel_incompatible`（環境カテゴリ）として SDXL 再インストールを案内
NF4 量子化	bitsandbytes の Linear4bit へ UNet / TE を置換。8GB 級 VRAM で SDXL 常駐を約 4.5GB に圧縮。CUDA 必須（`nf4_requires_cuda`）
軽量 VAE	SDXL: `madebyollin/taesdxl`、SD1: `madebyollin/taesd`。初回 VAE 復号の遅さ対策で既定 ON。DL 失敗時はフル VAE へ自動フォールバックしキャッシュキーも合わせる
LPW	compel による 75 トークン超プロンプト。SDXL は tokenizer/text_encoder 2 系統＋pooled embeddings。compel 未導入なら警告ログを出し通常処理へ
CPU フォールバック	CUDA 不可なら CPU 生成（engine_mode=real_cpu、所要時間警告を表示）

5.5 ControlNet（OpenPose）経路の VRAM 配置戦略

_place_controlnet_pipeline が総 VRAM と NF4 有無から自動選択する。

条件	戦略	説明
CUDA なし	cpu	CPU 実行
VRAM < 6GB	sequential	逐次 CPU オフロード。確実だが非常に低速（4GB 機向け）
NF4 有効かつ VRAM ≥ 6GB	none（フル GPU）	8GB 高速化の本命。量子化済み常駐をフル GPU 配置し、bnb と accelerate オフロードの競合を回避するため enable_*_cpu_offload を呼ばない
VRAM < 12GB	model	モデル単位 CPU オフロード。やや低速
VRAM ≥ 12GB	none（フル GPU）	通常生成と同じ最適化を適用

オフロード時は device 配置を乱さない attention / VAE slicing のみ追加。オフロード使用時に pipe.to("cuda") は呼ばない（二重配置で破損するため）。
control_guidance_start / end（0.0〜1.0、start ≤ end をバリデーション）で ControlNet を効かせる denoise 区間を制御。end < 1.0 で後半の ControlNet forward をスキップして高速化（8GB 推奨 0.5〜0.6 は UI / プリセット側で付与）。
制御画像 base64 はジョブ受付時にファイル保存し、スナップショットには app 相対パスのみ残す（巨大 base64 を DB に残さない）。

5.6 画像保存

保存先: %APPDATA%/Umaru/outputs/YYYY-MM-DD/。設定の output_dir が別途有効ならそこへコピー。
PNG メタデータ: prompt / negative / モデル / seed 等を tEXt で埋め込み。remove_exif_by_default=true なら個人情報になり得るメタデータを除去して保存（ダウンロード API の再保存も同じ設定に従う）。

5.7 エラー分類（4 カテゴリ）

未分類例外も classify_exception でシグネチャ解析して必ずいずれかに落とす。未知のコードは bug（要報告）扱い。

カテゴリ	表示	代表コード	UI アクション
config	設定・入力を見直してください	model_not_selected / model_not_found / controlnet_requires_sdxl / controlnet_model_incompatible（meta tensor・size mismatch 検出含む）/ invalid_image / lora_not_found / lora_load_failed	「設定を確認する」
environment	環境・セットアップの問題です	deps_not_ready / nf4_dependency_missing / nf4_requires_cuda / cuda_kernel_incompatible（no kernel image 検出）	「セットアップを確認する」
resource	リソース不足です	vram_insufficient（CUDA OOM）/ ram_insufficient（MemoryError / bad_alloc）	「設定を確認する」（サイズ・steps を下げる案内）
bug	想定外の不具合です（開発者へ報告）	generation_error ほか未知コード全部	エラー詳細（traceback 末尾 4000 字）を整形コピーして報告する導線

5.8 生成進捗とオーバーレイ

進捗の目安: 10% 受付 → 25% モデルロード（NF4 は専用文言）→ 45% LoRA / LPW 準備 → 55〜89% denoise（完了step/全step, 秒/step を毎ステップ更新）→ 89% VAE 復号・書き出し → 90% DB 保存 → 100% 完了。
オーバーレイ機能: 最小化（安全タブへ移動すると自動最小化、完了 / 失敗で自動復帰）・キャンセル・ログ表示（直近 200 件、レベル付き）・待ち時間 Tips 表示・エラー時はカテゴリ別の対処ボタン＋報告用コピー・完了時はサムネイル＋「同じ設定でもう一度描く」「つくるへ」「アルバムを確認する」。

6. ジョブ管理

stateDiagram-v2
    [*] --> queued: create_job
    queued --> running
    running --> completed: 生成成功
    running --> error: 例外 (4分類付き)
    running --> cancelled: ユーザーキャンセル
    running --> partial: お祈り組で一部成功+不足
    running --> failed: お祈り組で全滅
    running --> partial_failed: お祈り組で一部成功+失敗終了
    note right of completed
        terminal 状態:
        completed / cancelled / error /
        failed / partial / partial_failed
        ・terminal 後の status 上書きは無視
          (遅延 completed が来ても維持)
        ・終了 30 分後に 5 分間隔の掃除で削除
        ・terminal でログ/WS/poll が停止
    end note

ジョブはプロセス内 dict（job_store.jobs）で管理（再起動で消える揮発設計。成果物は DB / ファイルに保存済み）。
フロントは 1 秒間隔のポーリング（GET /api/jobs/{id}）を基本とし、WS も提供。poll 失敗時は status_unknown 化（接続不安定の可視化）。
terminal 状態集合はバックエンド JOB_TERMINAL_STATUSES とフロント src/app/types.ts で手動同期。

7. データモデル（SQLite）

7.1 ER 図

erDiagram
    characters ||--o{ generations : "character_id (任意)"
    characters ||--o{ character_memory_images : ""
    characters ||--o{ prayer_sessions : ""
    characters ||--o{ remembering_sessions : ""
    characters ||--o{ growth_album_sessions : ""
    characters ||--o{ favorite_seeds : "任意"
    characters ||--o{ exports : ""
    generations ||--o{ character_memory_images : "SET NULL"
    generations ||--o{ prayer_candidates : "SET NULL"
    generations ||--o{ favorite_seeds : "SET NULL"
    generations ||--o{ growth_album_steps : "selected (SET NULL)"
    prayer_sessions ||--o{ prayer_groups : "CASCADE"
    prayer_sessions ||--o{ prayer_candidates : "CASCADE"
    prayer_groups ||--o{ prayer_candidates : "CASCADE"
    growth_album_sessions ||--o{ growth_album_steps : "CASCADE"
    growth_album_sessions ||--o{ growth_album_sessions : "branch (parent)"

    characters {
        int id PK
        text name
        text reading
        text concept
        text personality
        text world_note
        int cover_image_id
        text linked_lora_path
        text linked_lora_trigger_word
        text default_prompt_layers "雛形(positive/negative/apply_mode)"
        text builder_state "特徴パネル JSON"
        text status "active/deleted"
    }
    generations {
        int id PK
        text created_at
        int character_id FK
        text source_type "txt2img/img2img/pose_import等"
        text resolved_positive
        text resolved_negative
        text model_name
        text loras "path配列JSON"
        text settings_snapshot "復元用フルJSON"
        int seed
        text image_rel_path
        int width
        int height
        text metadata_json "job_id/engine情報"
    }
    character_memory_images {
        int id PK
        int character_id FK
        int generation_id FK
        int prayer_candidate_id
        text image_rel_path
        text role "identity/outfit/expression/pose/style/background/training_candidate/rejected"
        int rank
        int is_training_candidate
        text caption
        text creator_note
        text prompt_snapshot
        text settings_snapshot
    }
    prayer_sessions {
        int id PK
        int character_id FK
        text wish
        text status "draft/..."
        text model_path
        text model_name
        text compare_theme "none/cfg/sampler/prompt_tag"
        text compare_config "JSON"
    }
    prayer_groups {
        int id PK
        int session_id FK
        text group_key "A/B/C/D"
        text strategy_note
        int requested_count
        text last_error
        text variation_label
        text generation_overrides "JSON"
    }
    prayer_candidates {
        int id PK
        int group_id FK
        int session_id FK
        int generation_id FK
        text image_rel_path
        int rank "1-3"
        int is_finalist
        int seed
    }
    remembering_sessions {
        int id PK
        int character_id FK
        text status
        text name "LoRA出力名"
        text trigger_word
        text memory_image_ids "JSON配列"
        text dataset_rel_path
        text config_snapshot
        text output_lora_rel_path
        int steps_completed
        int total_steps
        text loss_history
    }
    favorite_seeds {
        int id PK
        int character_id FK
        int generation_id FK
        int seed
        int rank
        text name
        text model_name
        text model_hash
        text sampler
        real cfg_scale
        int steps
        text prompt_snapshot
        text settings_snapshot
        text image_rel_path
        text memo
    }
    growth_album_sessions {
        int id PK
        int character_id FK
        text title
        text status "active/completed/archived"
        text base_prompt
        int current_step
        int parent_session_id FK
        int parent_step_index
    }
    growth_album_steps {
        int id PK
        int session_id FK
        int step_index
        text step_kind "base/identity/outfit/scene/lighting/style"
        text label
        text prompt_append
        int selected_generation_id FK
        text note
    }

7.2 独立テーブル

テーブル	用途
schema_migrations	適用済みマイグレーションバージョン（1〜7）
app_settings	key-value 設定（bool は “true”/“false” 文字列）
prompt_dictionaries	辞書エントリ（出典・ライセンス・同意日時・entry_json・nsfw_level）
model_adapters	モデルアダプタ登録（表示名・系統・パス・ライセンスメモ・可用フラグ）
exports	プロフィールエクスポート記録（種別・出力パス）
audit_events	監査ログ（イベント種別・メッセージ・詳細 JSON。エラー・自爆理由・同意等を記録）

7.3 マイグレーション履歴

ver	内容
1	初期スキーマ一式
2	prayer_sessions に model_path / model_name、prayer_groups に requested_count / last_error
3	favorite_seeds（雰囲気の種メモ）
4	お祈りラボ（compare_theme / compare_config / variation_label / generation_overrides）＋種の name
5	成長アルバム（growth_album_sessions / growth_album_steps）
6	prayer_candidates.seed（実 seed の保存・可視化）
7	characters.builder_state（特徴パネル選択状態）

起動ごとに CREATE TABLE IF NOT EXISTS＋ALTER TABLE ADD COLUMN IF MISSING 方式で冪等適用。

8. API リファレンス（全エンドポイント）

すべて X-Umaru-Token 必須（※印は ?token= クエリ可、/healthz のみ認証なし）。

8.1 基盤・設定・診断

メソッド / パス	内容
GET /healthz	死活確認（認証なし）
POST /api/heartbeat	ハートビート
GET /api/setup/status	環境診断一式（DiagItem 配列付き）
GET /api/folder-status	5 フォルダの存在・書込・スクリプト有無
POST /api/setup/install-python	同梱 Python 展開
POST /api/setup/install-dependencies	基本ライブラリ導入
POST /api/setup/install-sdxl	SDXL ライブラリ導入（profile: auto/cpu/cuda）
POST /api/setup/download-dictionary	外部辞書取り込み（同意必須）
WS /ws/setup/progress	インストール進捗
GET/PATCH /api/settings	アプリ設定
GET /api/models	モデル一覧（状態・アクション付き）
GET /api/loras	LoRA 一覧（状態・アクション付き）
GET /api/legal-notices	法的文書の所在一覧
GET /api/release/status	配布前ゲート
GET/POST /api/diagnostics/inference-check	実モデル推論実績の照会 / 集計記録

8.2 キャラクター

メソッド / パス	内容
GET/POST /api/characters	一覧（active のみ）/ 作成
GET /api/characters/summaries	集計付き一覧（カード表示用）
GET/PATCH/DELETE /api/characters/{id}	取得 / 部分更新 / ソフトデリート
PUT/DELETE /api/characters/{id}/cover	カード画像の固定 / 解除

8.3 生成・ジョブ

メソッド / パス	内容
POST /api/generate	txt2img 生成（非同期 job_id 返却）
POST /api/img2img	img2img（source_generation_id + denoise_strength）
POST /api/pose/to-i2i	ポーズ PNG をアルバムへ取り込み
POST /api/pose/controlnet	ControlNet 生成（制御画像 base64・scale・guidance start/end）
GET /api/pose/controlnet/models	ControlNet モデルレジストリ＋導入状況
GET/POST /api/pose/controlnet/download(/status)	モデルダウンロード開始 / 進捗
GET /api/jobs/{job_id}	ジョブ状態
POST /api/jobs/{job_id}/cancel	キャンセル
WS /ws/jobs/{job_id}	1 秒間隔のジョブ配信（terminal で close）

8.4 アルバム・種

メソッド / パス	内容
GET /api/album	ページング一覧（character_id / limit / offset。limit=0 で全件）
GET /api/album/{id}	詳細
GET /api/album/{id}/image ※	原画像
GET /api/album/{id}/thumbnail ※	サムネイル
GET /api/album/{id}/download?format=png\|jpg ※	再保存ダウンロード（EXIF 設定準拠）
GET /api/album/{id}/restore	復元フォーム＋警告
POST /api/album/{id}/open-folder	保存先フォルダを開く
POST /api/album/reassign-character	キャラタグ一括変更（v1.3）
DELETE /api/album/{id}	削除
GET/POST /api/favorite-seeds、DELETE /api/favorite-seeds/{id}	お気に入り seed の一覧（character/model 絞り込み）/ 保存 / 削除

8.5 学習素材・お祈り・成長アルバム

メソッド / パス	内容
GET/POST /api/characters/{id}/memory-images	学習素材一覧 / 保存
GET /api/memory-images/{id}/thumbnail ※	サムネイル
PATCH/DELETE /api/memory-images/{id}	編集 / 削除
POST /api/memory-images/{id}/mark-training-candidate	学習候補マーク
GET/POST /api/prayer-sessions	お祈り一覧 / 作成（A〜D 組を自動生成）
GET/DELETE /api/prayer-sessions/{id}	詳細（groups+candidates 同梱）/ 削除
PATCH /api/prayer-sessions/{id}/compare-theme	ラボテーマ変更
POST /api/prayer-sessions/{id}/groups	組の整備（冪等）
POST /api/prayer-groups/{id}/generate	候補生成（count 3-10、mode: generate/fill_missing/regenerate）
POST /api/prayer-groups/{id}/regenerate	作り直し
PATCH /api/prayer-candidates/{id}/rank	ランク付け（1-3 / 解除）
POST /api/prayer-sessions/{id}/finalize-groups	決勝候補確定
POST /api/prayer-sessions/{id}/final	最終生成
POST /api/prayer-sessions/{id}/save-winners	1〜3 位を学習素材へ保存
GET/POST /api/growth-albums	成長アルバム一覧 / 作成
GET/DELETE /api/growth-albums/{id}	詳細（steps 同梱）/ 削除
POST /api/growth-albums/{id}/steps	段階追加
POST /api/growth-album-steps/{id}/select-generation	段階の採用画像選択
POST /api/growth-albums/{id}/branch	分岐作成

8.6 学習・エクスポート

メソッド / パス	内容
POST /api/characters/{id}/remember/prepare	データセット準備
GET /api/remembering-sessions/{id}(/config \| /progress)	セッション / 設定 / 進捗
POST /api/remembering-sessions/{id}/start \| /stop	学習開始 / 停止
WS /ws/remembering/{id}	学習進捗配信
GET/POST /api/training-runtime/status \| consent \| install \| cancel \| update \| reset \| logs	sd-scripts ランタイム管理
POST /api/characters/{id}/exports/yurari \| suzuna-profile	プロフィール JSON 出力
GET /api/exports/{id}	エクスポートファイル取得

8.7 辞書・プロンプト

メソッド / パス	内容
GET /api/dictionaries	生エントリ一覧（直近 200）
GET /api/dictionaries/entries	カテゴリ / 検索 / ページング付き一覧
GET /api/dictionaries/search	タグ検索（日英、NSFW レベル）
GET /api/dictionaries/count	件数
POST /api/dictionaries/import	エントリ直接取り込み（同意必須）
POST /api/dictionaries/import-folder	dictionaries/ の CSV 一括取り込み
POST /api/dictionaries/import-custom	自作 / 外部 CSV 取り込み（同意必須）
POST /api/tags/color-to-tag	HEX → 髪/目/服色タグ＋日本語ラベル
GET /api/negative-charms	お守り定義一覧
POST /api/prompt/cleanup	重複除去＋矛盾検出
POST /api/prompt/estimate-volume	トークン概算
POST /api/prompt/resolve	日本語 → タグ解決

8.8 Tauri コマンド（フロント → Rust）

start_backend / stop_backend / show_main_window / close_splashscreen / get_backend_config / log_frontend_error / open_dictionary_folder / open_folder / open_external_url / select_folder / select_file / save_bytes / get_default_folders

9. セキュリティ仕様

領域	実装
API 認証	ランダムトークン（`secrets.token_urlsafe(32)`）を stdin 経由でサイドカーに注入。タイミング攻撃耐性のある比較。WS は close code 4401
孤児プロセス防止	`UMARU_PARENT_PID` の死活を 2 秒間隔監視（Windows は OpenProcess + GetExitCodeProcess）。親死亡で自爆し、理由を sidecar.log と audit_events に記録
パストラバーサル防止	app 相対パスは `resolve_under` で正規化検証。NUL とバックスラッシュは解決前に一律 400 拒否
コマンドインジェクション防止	フォルダを開く操作は generation_id だけ受け取りサーバ側でパス解決。shell=True 不使用
ネットワーク境界	127.0.0.1 バインドのみ。CORS は Tauri origin と dev origin のみ。CSP で外部接続を遮断
入力検証	Pydantic による全リクエスト検証（HEX 色の正規表現、数値範囲、guidance start≤end など 422）
プライバシー	EXIF / メタデータ削除既定 ON。ControlNet 制御画像 / ポーズ画像の base64 を localStorage・DB スナップショットに残さない
同意ゲート	外部辞書取り込み・ControlNet モデル DL・sd-scripts 取得はすべて明示同意が必要（consent_required）
取得物検証	sd-scripts ZIP は manifest の sha256 / commit 固定（配布ゲート連動）。配布物は checksums.sha256
エラー隠蔽	未処理例外はユーザー向けには丸め（internal_error）、詳細は audit_events / ログへ
監査	audit_events に生成失敗・自爆・辞書取込失敗・LLM 停止等を記録

10. ファイルシステムレイアウト

%APPDATA%/Umaru/            (UMARU_DATA_DIR で変更可)
├── config/
├── data/umaru.db            … SQLite 本体
├── outputs/YYYY-MM-DD/      … 生成画像（日付別）
├── characters/<id>/
│   ├── memories/            … 学習素材コピー
│   ├── lora_training/<sid>/ … config.toml / dataset.toml / dataset/
│   └── loras/               … 学習済み LoRA 出力
├── models/                  … 既定モデルフォルダ
│   └── controlnet/<model>/  … DL した ControlNet（diffusers 形式）
├── loras/                   … 既定 LoRA フォルダ
├── kohya/                   … 既定 sd-scripts 手動配置先
├── training/                … 自動オンボーディング (sd-scripts/current・venv・cache・consent.json)
├── dictionaries/            … 辞書 CSV 置き場
├── logs/
│   ├── sidecar.log          … サイドカー標準出力
│   ├── kohya/               … 学習ログ
│   └── inference-check-*.json … 実モデル推論診断
├── cache/
├── python/ または venv/     … 同梱 Python 実行環境

11. ビルド・配布・品質ゲート

コマンド	内容
`npm run dev` / `npm run backend`	Vite dev サーバ / uvicorn（dev-token）
`npm run tauri dev`	dev-start.ps1 経由で両者起動
`npm run build`	`tsc` + esbuild 直叩き build.mjs（Node24 × Rollup4 クラッシュ回避）
`npm run test`	vitest（フロント単体・コンポーネント・プロパティテスト）
`npm run check`	build + npm audit(high) + cargo check + Python compileall + security_smoke + 同梱 Danbooru 不在チェック
`npm run licenses`	npm / Rust / Python 依存のライセンス収集 → LICENSES/ 生成
`npm run release-gate`	配布前ゲートの一括判定スクリプト
`npm run checksums`	checksums.sha256 生成
`npm run tauri build`	NSIS インストーラ（perMachine・日本語・backend / assets / resources / LICENSES / EULA / NOTICE を同梱）

バックエンドテスト: pytest（unit: 色変換・辞書・seed・ジョブ・エラー分類・GPU 判定・パス検証・親監視判定 / integration: API 認証カバレッジ・各 API・ControlNet 系統・DB ファイル）。
フロントテスト: 各 feature の __tests__/（フォーム永続化・復元モード・ポーズ系の射影 / FK / OpenPose 変換 / PNG 出力・スプラッシュ引き継ぎ自己キャンセル回帰など）。

12. 用語対応表（ui_mode）

内部概念	creator（通常モード）	expert（専門モード）
Prompt	描いてほしいこと	Prompt（描いてほしいこと）
Negative Prompt	避けたい描写	Negative Prompt（避けたい描写）
Seed	雰囲気の種（0 で自動）	Seed（雰囲気の種、0 で自動）
Sampling Steps	描き込み量	Sampling Steps（描き込み量）
CFG Scale	指示への忠実度	CFG Scale（指示への忠実度）
Model	モデル	Model（モデル）
Denoise Strength	元画像の残し具合	Denoise Strength（元画像の残し具合）
比較生成セッション	お祈り	（同名）
Negative プリセット	お守り	（同名）
LoRA 学習	この子を学習する	（同名）
学習データ候補	学習素材	（同名）

13. バージョン履歴（直近）

v1.3.0（2026-06-08）

新機能: アルバムのキャラタグ一括変更（複数選択 → 別キャラ / 未紐付けへ。詳細画面から単体変更も可）。つくる画面とメインページのキャラ選択連動。
改善: お祈りでのキャラ雛形二重適用を解消し LoRA リストを正しく反映。ControlNet 経路の NF4 対応・control_guidance_end 対応・通常生成との二重常駐解消（少 VRAM 安定化）。アルバム画面の内部分割（保守性）。

v1.2.0

ControlNet OpenPose（ポーズ → 構図転写）系の導入、8GB VRAM 最適化（NF4 / 軽量 VAE / 配置戦略）ほか。

14. 既知の制約・注意事項

ポーズエディタは β 版（顔・手指キーポイントは未対応。OpenPose JSON にフィールド枠のみ確保）。
ControlNet は SDXL 系モデル専用。SSD-1B 等の蒸留 / 非標準 SDXL は非互換（meta tensor 検出で config エラー化）。
LoRA 学習は SDXL 専用・CUDA 必須（v1 時点）。生成は CPU フォールバック可。
ジョブ状態はプロセス内メモリ管理のため、アプリ再起動で進行中表示は消える（成果物は保存済み）。
1 プロセスにつきパイプラインキャッシュは 1 つ（モデル切替時はロードし直し）。
terminal ステータス集合・お守り定義はフロント / バックエンドで手動同期している（変更時は両方更新）。
モデル・LoRA・外部辞書・sd-scripts は同梱しない。ユーザー取得物のライセンス遵守はユーザー責任（アプリ内で注意喚起・同意取得）。

本書は 2026-06-10 時点の main ブランチ（9ec07b1）の実装を基に作成。