アバターボード仕様書（汎用版）

アシスタントのアバター候補を台帳として管理する、サーバー保存型Webアプリの仕様。
この文書だけで、別のAIエージェントが同じものを実装できることを目的とする。
特定の利用者・特定のアバター・特定のペルソナに依存する内容は、本仕様の対象外とし、付録Aに「環境固有の事例」として分離した。

1. 目的と設計原則

- ボードは「台帳と、選択を保存する場所」である。ボード自体はアバターを直接切り替えない。
- 実際の切り替えは、利用者のアシスタント（ホストエージェント）がボードの状態を読んで、各プラットフォームの手順で適用する。
- 使用中（アクティブ）なアバターは常にちょうど1つ。
- ボード側の状態変更は「利用者の意思表示」であり、適用の確定ではない。ボードと実物の間にずれが生じうることを前提に、ずれの検出と解消の手順（6章）を仕様に含む。

2. 用語

- カード: アバター候補1件分のレコード。
- デフォルトカード: プラットフォーム標準のアバターを表す固定カード。削除・アーカイブ・名前変更は不可。ただし 画像のみ自由に登録・差し替えできる（無関係な画像や生成画像でも可とし、内容は問わない。あくまで表示用の目印である）。
- ボード使用中: ボード上で「使用中」と記録されているカード。
- 適用済み: ホストエージェントが実際に適用したと記録したカード。通常はボード使用中と一致するが、ボード側の操作直後などは一致しないことがある（この不一致を内部概念として「ずれ」と呼ぶ）。
- 使用予約: 利用者向けの表示用語。ボード側で選ばれたが未適用の状態は「予約中」と表示する。「ずれ」という語は利用者向け文言には使わない。

3. データモデル

カード
| 項目 | 内容 |
|---|---|
| id | 一意な識別子 |
| 画像 | そのアバターの絵（カードに紐づけて保存する） |
| 名前 | 呼び名。全カードで重複不可（会話で名前指定するため） |
| メモ | 自由記述（由来、気に入っている点、再生成に必要な情報など） |
| 状態 | 使用中／手持ち／アーカイブ のいずれか |
| 次に使いたい順位 | キューに入っている場合のみ、1始まりの順位（5章） |
| 並び順 | 全カード通しの表示順（整数） |
| デフォルト区分 | デフォルトカードかどうか |

ボード全体の状態
- ボード使用中のカードID
- 適用済みのカードID（ホストエージェントだけが書き換える）。現在のアバターがどのカードにも対応しない場合は「未登録」を取りうる。その場合も、現在のアバターの画像と識別情報はボード側に保持し、後述の登録判定と登録時の画像に使う
- 次に使いたいキューの選択順を決める連番カウンタ

初期状態ではデフォルトカードが使用中かつ適用済みで、両者は一致している。
作成時の初期データはデフォルトカード1件のみとし、サンプルカードなど他のカードは登録しない。利用者のカードは、利用者またはエージェントが後から追加する。

4. 画面構成

- 上部：「いまのアバター」を大きく表示するエリア。原則として適用済みのカードを大きく見せる。
- ずれがある間は、上部に予約バナーを表示する。文言の基準は、見出し「『（カード名）』の使用が予約されています」、補足「まだ実際のアバターには反映されていません」とし、ボード使用中のカードのサムネイルを添える。補足には確認の結果も添える（「『はい』でアバター変更を実行、『いいえ』でこのアバター変更をキャンセルします」を基準とする）。バナーには予約の取り消しボタンを置き、文言は「予約を取り消して手持ちに戻す」を基準とする。
- カードには状態バッジを付ける：使用中（実際に適用中）、予約中（ボード側で選択済み・未適用）、アーカイブ、次に使いたい順位など。
- 下部：カード一覧。画像は切り抜かず全体が見える表示（contain）を基本とする。
- スマホでも見やすいレイアウトにする。

5. 操作仕様

- カードの新規登録は「現在のアバターを登録」ボタンからのみ行う（次項）。カードの編集・削除は従来通り。

カードの登録（現在のアバターを登録）
- 自由なカード追加は行わない。新規登録できるのは「今使っているアバター」だけである。
- 現在のアバターが既にカードとして登録済みの場合は、このボタンは押せない（無効化する）。現在のアバターがデフォルトアバターの場合はデフォルトカードが常に登録済みのため、ボタンは常に無効になる。
- 登録すると、そのアバターの画像を持つカードが作られ、使用中かつ適用済みとして記録される（登録の時点ではずれは生じない）。名前は登録時に入力する（重複不可）。
- アーカイブ（消さずにしまう）と、手持ちへの戻し。
- 削除はアーカイブ済みのカードからのみ可能とし、確認ダイアログを必須とする。デフォルトカードは削除・アーカイブ不可。
- 使用中または適用済みのカードをアーカイブした場合、使用中はデフォルトカードに戻る。
- 並び替え：全体で1本の順序を保持する。ドラッグに加え、上下ボタンを用意する（モバイル配慮）。
- 名前で検索（メモも対象に含める、部分一致）。
- 状態で絞り込み（使用中だけ／手持ちだけ／アーカイブだけ、など）。検索と絞り込みは併用できる。
- 「次に使いたい」の選択（複数可、次章）。

既存アバターの取り込み（エージェント経由）
- 前提：利用者は、過去に作ったアバターの生成元画像を手元に保持していることがある。それを取り込めるようにする。
- エージェントの振る舞い：ボードの導入時や、利用者の手元に過去アバターの素材があると分かった時に、エージェントから「前に作ったアバターを取り込めるみたいだけど、どうする？」と利用者に確認する。勝手に取り込まない。
- 利用者が了承したら、エージェントが画像を読み取り、手持ちカードとして一括登録する。名前はファイル名などから仮付けし、メモに取り込み元を記録する。
- 既に同名または同一画像のカードがある場合は二重登録しない。
- 補助として、新規にアバターを生成した時は、その生成元をボードに登録するかエージェントが確認するのが望ましい（ストックがボード外に散らからないようにするため）。

次に使いたいキュー
- フラグを付けた順序を記録し、その順序を優先度とする（選んだ番号順）。
- カード上に順位（1, 2, 3…）を表示する。
- 切り替えの対象は順位1（最初に選んだもの）。
- 適用されたカードはキューから抜け、残りが繰り上がる。
- フラグを外して付け直したカードはキューの最後尾に入る。
- 使用中・アーカイブのカードはキューに入れられない。

6. ずれと同期のプロトコル（中核仕様）

1. ボード側で「このアバターを使う」が押されても、変更作業は行わない。 ボード使用中の記録だけが変わり、実物のアバターには触らない。この時点で「ずれ」が発生する。
2. ホストエージェントは、ボード使用中と適用済みを比較してずれを検出できる（7章の getSyncStatus）。
3. ずれがある状態で利用者がチャットでホストエージェントに アバターボードの確認を依頼したら、ホストエージェントは 本人の言葉で（その時に使っているペルソナ・口調で）、対象カードのサムネイルを添えて（可能な場合）、選択肢形式で確認を出す。
   - はい: 現在のアバターを、ボード使用中のアバターに同期する。エージェントはプラットフォームの切り替え手順を実行し、完了後に「適用済み」をボード使用中に合わせる。
   - いいえ: ボード使用中を、現在のアバター（適用済み）に同期して戻す。
4. チャット側から直接切り替えを行った場合は、ボード使用中と適用済みを同時に更新するため、ずれは生じない。

注：確認の起点は、利用者がチャットでエージェントにボードの確認を依頼すること。エージェントが利用者の「戻り」を自動で検出して割り込むことはしない（作業依頼など無関係な入力に確認を被せないため）。定期チェックによる能動通知は任意の拡張とする。

7. ホストエージェント向けインターフェース（推奨アクション）

エージェントがボードを読み書きするための操作群。実装はAPIでもツールでもよいが、意味は以下に揃える。

| アクション | 意味 |
|---|---|
| listCards | 全カードを並び順で返す（状態・順位・画像参照を含む） |
| getSyncStatus | ずれの有無、ボード使用中のカード、適用済みのカードを返す |
| setCurrentAvatar | エージェントが「現在のアバター」のスナップショット（画像と識別情報）をボードに報告する。登録判定と未登録表示はこれに基づく |
| registerCurrentAvatar | 現在適用中で未登録のアバターをカードとして登録する。登録と同時に使用中・適用済みに揃える |
| importCards | エージェント専用（UIには出さない）。既存の生成元画像から手持ちカードを一括登録する。同名・同一画像はスキップする |
| updateCard | カードの編集（名前の重複は拒否） |
| archiveCard / restoreCard | アーカイブ／手持ちへの戻し |
| deleteCard | アーカイブ済みのみ削除可 |
| reorderCards | 全体の並び順を設定 |
| toggleQueue | 次に使いたいフラグの付け外し（順位は自動で振り直す） |
| requestActive | ボード側の「このアバターを使う」。ボード使用中だけを変え、適用済みは変えない（ずれを作る操作） |
| requestApplyNext | キュー順位1について requestActive と同じことをする |
| setActive | チャット側で実際に切り替えた後に使う。ボード使用中と適用済みを同時にそのカードへ揃える |
| applyNext | チャット側でキュー順位1を実際に適用した後に使う（setActive のキュー版） |
| syncAppliedToBoard | 確認で「はい」の後始末：適用済みをボード使用中に合わせる |
| syncBoardToApplied | 確認で「いいえ」の後始末：ボード使用中を適用済みに戻す |
| seedBoard | 初期投入（デフォルトカードの作成など）。繰り返し呼んでも既存データを壊さない |

8. 実装メモ

- データはサーバー側に保存され、開き直しても残ること。
- 画像はカードのデータとして保存し、一覧・バナー・サムネイルで再利用できること。
- 見た目（色・余白など）は後から調整できる前提で、まずは動作を優先してよい。
- 初期データはデフォルトカードのみ（3章）。サンプルカードは入れない。

付録A. 環境固有の事例（汎用仕様ではない）

以下は、ある特定環境での運用例であり、他環境では読み替えること。

- デフォルトカードの名前が「Jolly」なのは、そのプラットフォームのデフォルトアバター名に由来する固有名である。
- 確認文の例「この衣装に着替えるんだね？」は、メイドのペルソナ使用時の一例。6章の通り、文面はエージェントの現在のペルソナ・口調に従う。
- その環境では、アバターの過去分は同一バンドルとして保持できず、デザイン原画の画像ファイルから候補を再生成して切り替える。そのためカードのメモ欄に「再生成ソースのファイル名」を記録する運用をしている。再生成方式かどうかはプラットフォーム依存であり、本仕様の範囲外。
- 切り替え時に「番号付き確認シートを先に提示し、利用者が明示的に決定するまで有効化しない」という運用ルールも、その環境の利用者とエージェントの間の取り決めであり、本仕様には含めない（6章の「プラットフォームの切り替え手順」に委ねる）。
- 初期投入された実カード（特定のキャラクターデザイン数件）は利用者の所有データであり、仕様の一部ではない。