ステータス: 確定（Issue #14、Track #20）
更新するときは、設計文書の更新ルールに従うこと。
改訂: 2026-09-21、Issue #14の設計検討により、期待される構成を「運用者が登録する常駐監視対象」へ改め、原則5を「プロセス操作をしない」に絞った（検討結果）。同日、CODEXレビューを受けて、UC-D06（常駐監視対象の管理）を追加し、UC-R07を改訂した（反映結果）。2026-09-24、運用者の判断により、UC-D06から常駐監視対象の「一時無効化」を削除し、計画的な長期停止は解除・再登録で扱うことにした（検討結果）。同日、CODEXレビューを受けて、§1.1とアクター表の「登録・変更」を、UC-D06に合わせて「登録・変更・解除」に揃えた（文言の整合のみ。反映結果）。同日、運用者の判断により、UC-D06から「事前登録」を削除し、新規導入したUIは一覧に現れたことを確認してから登録することにした（検討結果）。同日、運用者の依頼により、UC-D07（登録情報の破損・消失からの復帰）と、その想定シナリオ（4.5）を追加した（検討経過）。同日、CODEXレビューを受けて、4.5を仕組み（保存・復元の方式）に踏み込まない、観測できる結果の記述に改め、UC-D07の期待結果に「確認済みにするまで確認できる」「壊れた情報が残っていればその場所」を反映した（反映結果）。同日、CODEXレビューを受けて、§10「次の設計作業」を「設計作業の実施状況」に改めた（記述の更新のみ。反映結果）。
改訂: 2026-09-26、Issue #25で、運用者の方針により、ダッシュボードをBrainから切り離し、Brainの起動・停止とUIへの終了の通知を行えるようにした。UIの起動・停止は、各UIが自分の実行ホストに持つ手段で行う（#6659、#6674）。§1.1、§1.2、§2、§5、§6、§7の原則5、UC-D02、§9の確定事項2・3を改め、UC-B05・UC-R08・UC-R09を追加した（§9の2・3は、CODEXレビュー#6679の指摘で、置き換え漏れを直した）。運用者が合意した（Brainの再起動の操作は設けない）
改訂: 2026-10-05、Issue #17で、運用者の判断により、UC-D08（Brainが使うOllamaのモデルをGPUから下ろす）を追加し、§1.1、§2、§6、§7の原則5に、その操作を加えた（#6942）。運用者が合意した
本書は、Brain と UI をどのように運用できる世界を目指すかを、実現方式を決める前にユースケースとして定義する。既存の UI層-Brain層間 インタフェース仕様書 は会話要求と会話の継続に関する契約を扱う。本書は、それだけでは扱えないプロセスの稼働、版、起動数制約、運用上の可視性を対象にする。
本書では、利用者から見た状況と期待結果を記述する。識別子、API、通知方式、データ構造、保存方式、OS機能等の具体的な仕組みは、本書のユースケースが合意された後に検討する。
ユースケースと後続の設計は、次を前提にする。
利用者は端末を巡回したり、ps、pkill、ログファイルを組み合わせたりしなくても、少なくとも次を判断できる。
| アクター | 責務・関心 |
|---|---|
| 利用者／運用者 | 日常利用を開始し、稼働状態を確認し、必要ならBrainやUIを起動・停止する |
| Brain | 会話処理を提供し、UIの稼働状況を確認できる状態を提供する |
| UI | 利用者との入出力を担当し、Brainを利用する。音声UI、テキストUI等、複数の種類がある。UIごとに、自分の実行ホストで起動・停止する手段を持つ。ダッシュボードから終了を求められたら、正常に終了する |
| 実行環境 | 各実行ホスト（Windows、WSL2等）上で、必要なプロセスの自動起動、終了、二重起動防止を担う |
| ダッシュボード | Brainとは別に動き、BrainとUIの実際の状態を表示する（Brainが止まっていても使える）。別の実行ホストのブラウザからも開ける。Brainの起動・停止、UIへの終了の要求、Brainが使うOllamaのモデルをGPUから下ろす操作を受け付ける。UIの起動は行わない。運用者による常駐監視対象の登録・変更・解除を受け付ける |
| 開発者／保守者 | 更新後に新しいコードが実際に動作していることを確認する |
利用者、運用者、開発者は現在は同一人物であっても、達成したい目的が異なるため別の役割として扱う。
具体的なデータモデルは後続の設計で決めるが、利用者が次の3種類を混同せずに把握できる必要がある。
運用者が登録した、常駐して動いているべきUIの一覧を表す。「どの実行ホストで、どの種類のUIが、どの枠で動いているべきか」を1件ずつ登録したもので、特定のUIに限定しない。登録はBrainが永続的に保持する。登録されていないUIは、動いていれば観測されるが、停止していても異常とはみなされない。
登録は、プロセスの自動起動や常駐化を行う操作ではない。「動いているべき」という監視上の期待を記録する操作である。
期待する版までは管理せず、版の更新漏れは実際の起動時刻と版を見て判断する。
現在または直近に動作していた Brain や UI を表す。二重起動や再起動が起きた場合に、現在のプロセスと以前のプロセスを取り違えない必要がある。
稼働状態を自ら伝えるUIは、この単位で把握される。稼働状態を伝えないUI（リクエスト単位で完結するもの等）は、プロセスとしては把握されず、3.3の会話としてのみ現れる。
会話履歴と一連のやり取りを表す。プロセスが動作していることと、会話が存在することは同じではない。会話していないUIも稼働中であり得る。逆に、会話が残っていることは、そのUIが今も動いていることを意味しない。
利用者が「ずっと接続している」と感じる状態は、UIの種類によって、プロセスの稼働（3.2）か会話の継続（3.3）のどちらか、または両方に対応する。
実行ホスト
└─ UIプロセス（稼働状態を自ら伝える）
└─ 0個以上の会話
リクエスト単位で完結するUI: 会話のみ（プロセスとしては把握されない）
| ID | 状況 | 期待する結果 |
|---|---|---|
| UC-B01 | Brainを動かす実行ホストが起動する、またはBrainの自動起動が失敗する | Brainが自動的に利用可能になる。失敗した場合は未稼働であることと正式な回復方法が分かる |
| UC-B02 | Brainが既に動いている状態で、誤ってもう1個起動する | 2個目は処理を開始せず、起動できなかった理由が分かる |
| UC-B03 | 運用者がBrainを停止する | 新しい処理の受付を終え、実行中の処理と保持資源を適切に扱って正常終了する |
| UC-B04 | Brain自体は動いているが、依存するサービスが不調である | プロセスの生存と、会話サービスとして利用可能かどうかを区別して確認できる |
| UC-B05 | 運用者が、ダッシュボードからBrainを起動・停止する | Brainが止まっていても、ダッシュボードで停止中（または起動失敗）と分かり、起動できる。停止はUC-B03の正常終了で行われ、停止処理中であることが分かる。起動に失敗した場合は、失敗したことと確認先が分かる。起動・停止できるのは許可された運用者だけで、権限のない利用者の操作は拒否される |
| ID | 状況 | 期待する結果 |
|---|---|---|
| UC-R01 | UIを動かす実行ホストが起動する、または常駐UIの自動起動が失敗する | 常駐UIが自動的に利用可能になる。失敗した場合は、常駐監視対象として登録されたUIであれば未稼働であることと、正式な回復方法が分かる |
| UC-R02 | UIが会話していない間も動き続ける | 会話の有無にかかわらず、UIが稼働中であることと、その実行ホスト・起動時刻・版を確認できる |
| UC-R03 | UIが正常終了、クラッシュ、またはBrainと通信できない状態になる（ブラウザのタブが黙って閉じられる場合を含む） | 終了通知が届かなくても、終了したUIを稼働中と誤認し続けず、最後に確認できた時刻と現在利用できないことが分かる |
| UC-R04 | UIが再起動する | 現在動いているプロセスと、それ以前に動いていたプロセスを取り違えない |
| UC-R05 | Brainが再起動し、UIは動き続けている | Brainは動作中のUIを再び認識でき、利用者から見た状態が正常へ戻る |
| UC-R06 | 稼働状態を自ら伝えるUIと、伝えないUI（リクエスト単位で完結するもの等）が混在する | 前者はUIプロセスとして、後者は会話としてのみ、それぞれ確認できる。後者について、未稼働や応答なしとは判定されない |
| UC-R07 | 常駐が期待されないUI（単発のスクリプトや、随時開閉するテキストUI等）が起動・終了する | 動いている間だけ一覧に現れ、停止しても異常として扱われない。ただし、終了通知なしで途絶した場合は、UC-R03のとおり、一定時間は「応答なし」として最終確認時刻とともに残り、その後一覧から消える。常駐監視対象として登録されたUIだけが、停止時に未稼働として扱われる |
| UC-R08 | 運用者が、ダッシュボードから、動いているUIに終了を求める | UIは求めに応じて正常に終了し（UC-R03の正常終了）、一覧に終了が反映される。求めに応じないUI（稼働状態を伝えないUI、終了の求めに対応していない版のUI等）は、求めた後も稼働中であることが分かる。ダッシュボードからUIを起動することはできない。終了を求められるのは許可された運用者だけである |
| UC-R09 | 利用者が、UIを動かす実行ホストで、そのUIを起動・停止する | UIごとに用意された手段で起動・停止できる。停止は正常終了として扱われ、ダッシュボードの一覧に反映される。起動数制約（UC-M02）は、この手段で起動した場合も守られる |
| ID | 状況 | 期待する結果 |
|---|---|---|
| UC-M01 | 多重起動を許可されたUIを複数起動する | すべて正常に利用でき、意図した複数起動として表示される |
| UC-M02 | 実行ホストごとに1つだけ許可されたUIを、同じ実行ホストで二重起動する、またはそのUIが異常終了後に再起動する | Brainが停止中でも2個目の起動を拒否する。一方、既存プロセスが終了していれば正常に再起動できる |
| UC-M03 | 実行ホストごとに1つだけ許可されたUIを、異なる実行ホストでそれぞれ起動する | 各実行ホストで1個ずつ起動でき、互いに拒否されない |
| ID | 状況 | 期待する結果 |
|---|---|---|
| UC-D01 | 利用者が管理ダッシュボードを開く | BrainとUIの稼働状態、実行ホスト、利用可能性、最終確認時刻を一画面で確認できる。会話内容や認証情報は表示しない |
| UC-D02 | 常駐監視対象として登録された常駐UI、またはBrainが確認できない | 常駐UIは、一覧から消えるのではなく「未稼働」または「応答なし」として表示される。登録されていないUIは、この対象にならない。Brainが停止している、または起動に失敗している場合は、ダッシュボードでそのことを確認できる（UC-B05）。ダッシュボード自体が動いていない場合は、実行環境の正式な管理手段で状態を確認できる（UC-B01） |
| UC-D03 | BrainまたはUIを更新した、あるいは更新前のプロセスが残っている | 起動時刻と実行中の版を確認し、更新後のプロセスへの切替と古いプロセスの残存を判別できる |
| UC-D04 | 利用者がBrainの利用状況を確認する | UIプロセスとは別に、会話セッション数と処理中件数だけを確認できる |
| UC-D05 | 利用者が、Brainとは別の実行ホストから管理ダッシュボードを開く | 同じ実行ホストから開いた場合と同じ状態を確認できる。ただし、閲覧を許可された利用者だけが見られ、認証情報は画面へ表示されない |
| UC-D06 | 運用者が、常駐監視対象を管理する（観測中のUIの登録、登録の変更・解除） | 観測中のUIを常駐監視対象に登録できる。新規に導入したUIは、一度起動して一覧に現れたことを確認してから登録する（一度も現れていないUIは登録しない）。登録の変更・解除ができ、解除した対象は、停止しても未稼働として扱われない。修理等で計画的に長期間止める場合は、登録を解除し、再開後に登録し直す。同じキーの重複登録は拒否され、理由が分かる。登録・変更・解除ができるのは許可された運用者だけで、権限のない利用者の変更は拒否される。これらの操作は、プロセスの起動・停止を伴わない |
| UC-D07 | Brainの起動時に、保持している常駐監視対象の登録情報が壊れている、または失われている | Brainは起動し、会話サービスを通常どおり提供する。登録情報は、正常だった直近の状態へ自動で戻る。戻したこと（いつ起きたか、いつの状態へ戻したか、壊れた情報が残っていればその場所）を、運用者が確認済みにするまでダッシュボードで確認できる。UIは影響を受けず、何もしなくてよい。戻せる正常な状態が無い場合も、Brainは登録0件として起動し、そのことが分かる。失われた登録は、運用者が動いているUIを一覧から選んで登録し直せる |
| UC-D08 | 運用者が、Brainが使うOllamaのモデルが載ったままのGPUを空けたい（しばらくBrainを使わない、GPUをほかの用途に使う等） | ダッシュボードで、GPUに載っているモデルと、自動で下りる予定の時刻を確認できる。WSL・Ollama・Brainを止めずに、モデルをGPUから下ろせる。回答の途中で下ろしても、その回答は最後まで返る。下ろした後の最初の質問は、読み込みの分だけ遅れるが、何もしなくても答えられる。Brainが止まっていても確認・操作できる。操作できるのは許可された運用者だけである |
登録情報の破損・消失から、正常に復帰するまでを、Brain・UI・運用者のそれぞれから見た結果として示す。どのように保存・復元するかは、設計で定める。
シナリオ1: 登録情報が壊れている、または失われているが、正常だった直近の状態へ戻せる（主なケース）
| 段階 | Brain | UI | 運用者 |
|---|---|---|---|
| 起動 | 登録情報を読み込めないことに気づく | Brainの停止中は、接続できない状態が続く（UIごとの再試行） | 気づかない |
| 自動復帰 | 登録情報を、正常だった直近の状態へ戻す。壊れた情報がある場合は、原因を調べられるよう残す | 何も知らない | 気づかない |
| 起動完了 | 通常どおり会話サービスを提供する。登録情報の破損は会話サービスの利用可能性に影響しない | Brainと通信できるようになり、通常どおり稼働状態を伝える。振る舞いは何も変わらない | 気づかない（能動的な通知はしない） |
| 確認 | 戻したことを、運用者が確認済みにするまで示し続ける。Brainを再起動しても消えない | — | ダッシュボードを開くと、いつ起きたか、いつの状態へ戻したか、壊れた情報が残っていればその場所が分かる。登録一覧が想定どおりかを確認し、原因を調べ、確認済みにする |
シナリオ2: 直近の正常な状態へは戻せないが、それより前の正常な状態へは戻せる
シナリオ1と同じ流れで、戻せる中で最も新しい正常な状態へ戻る。その後に行った登録・変更・解除は失われている可能性がある。運用者は、足りない対象のうち動いているUIを「未登録のUI」の一覧から選んで登録し直す。止まっているUIは、次に起動して一覧に現れた時点で登録する。
シナリオ3: 戻せる正常な状態が無い
Brainは登録0件として起動し、登録情報を戻せなかったことを示す。運用者は、シナリオ2と同じ手順で登録し直す。なお、初めて導入した直後で登録情報がまだ存在しない場合は異常ではなく、何も示さずに登録0件で起動する。
いずれのシナリオでも、UIは影響を受けず、何もしなくてよい。登録情報はBrainの中だけで使う監視設定であり、UIの稼働や会話には関係しないためである。
次は本書のユースケースの対象外とする。必要になった時点で、別のIssueとして扱う。
ここでは実現手段を決めず、ユースケースを満たすために必要となる能力だけを整理する。
| 必要能力 | 対応するユースケース |
|---|---|
| 各実行ホストの起動後にBrainと常駐UIを利用可能にし、失敗時に回復できる | UC-B01、UC-R01 |
| Brainをダッシュボードから起動・停止し、Brainが止まっていても状態を確認する | UC-B05、UC-D02 |
| ダッシュボードからUIに終了を求め、UIが正常に終了する。UIは自分の実行ホストで起動・停止できる | UC-R08、UC-R09 |
| Brainを正常に終了し、二重起動を防ぐ | UC-B02、UC-B03 |
| Brainの生存と会話サービスとしての利用可能性を区別する | UC-B04 |
| UIの稼働・終了・途絶・再起動を、終了通知に依存せず把握する | UC-R02〜UC-R05 |
| 稼働状態を伝えるUIと伝えないUI、常駐が期待されるUIと期待されないUIを区別して扱う | UC-R06、UC-R07 |
| UIごと・実行ホストごとの多重起動可否を守る | UC-M01〜UC-M03 |
| 常駐監視対象を運用者が管理し（登録・変更・解除）、登録されたUIの未稼働・応答なしを判別する | UC-R01、UC-R07、UC-D02、UC-D06 |
| BrainとUIの状態を、別の実行ホストからも一画面で確認する（ダッシュボード自身が動いていない場合は、実行環境の管理手段で確認する） | UC-D01、UC-D02、UC-D05 |
| 起動時刻と版から更新結果・古いプロセスを確認する | UC-D03 |
| 常駐監視対象の登録情報を保全し、破損・消失時も正常だった状態へ自動で戻して、そのことを運用者が確認できる | UC-D07 |
| Brainが使うOllamaのモデルを、WSL・Ollama・Brainを止めずにGPUから下ろす | UC-D08 |
| 会話の利用状況をプロセス状態と分けて把握する | UC-D04 |
現行の docs/ui-brain-protocol.md は、UIからBrainへの会話依頼、会話履歴、再送時の二重処理防止、Brainの利用可能性、BrainからUIへの応答を扱っている。
一方、本書のユースケースは次の要求を追加する。
これらのうち、自動起動とローカルな二重起動防止は、UIとBrainの通信プロトコルだけでは完結しない。どの要求をプロトコルへ追加し、どの要求を実行環境の責務とするかは、次の設計段階で分ける。
管理画面は認証情報を画面へ表示しない。別の実行ホストからのBrainへの接続・管理画面の閲覧に必要な認証と権限は、後続の設計で定める（ui-brain-protocol.mdの認証節も同様）。
本書の合意時点で「次の設計作業」として挙げた項目は、次のとおり実施した（2026-09-24時点）。設計の詳細はランタイム管理 設計を参照する。
docs/ui-brain-protocol.md へ統合するか、管理プロトコルを別文書として参照させるか決める → 実施済み（別文書として参照させる。設計書§10）