メインコンテンツへ
AstarDocs

AIチャット

一言でいうと

Astar 内蔵の AI チャット。単なるメッセージ送受信ではなく、マルチプロバイダー（Vertex AI / OpenAI Direct / Claude Code local / Codex local）に対応した agent ループを持ち、MCP tool を呼び出しながら会話を進め、破壊的な操作は承認ゲートを通してから実行する。UI への進捗表示はすべて SSE（Server-Sent Events）のイベントストリームで駆動される。

主要ドメイン概念

概念役割
Run1回の AI 実行（1メッセージ〜完了までのセッション単位）。AiRunController が公開する
RunEventRun の進行を表すイベント（text delta / thinking / tool_call_proposed / tool_result / ui_action / done 等）の discriminated union
ToolGatetool 呼び出しの承認ゲート。破壊的操作は自動実行せずユーザー承認を待つ
Plan Mode実行前に計画を提示し、承認を得てから実際の tool 実行に進むモード（AiPlanController）
LOCAL_CLI プロバイダユーザー自身のサブスクリプション（Claude Code / Codex）を Go Agent 経由でブリッジするプロバイダ

Backend 構造

core/ai/ は core/ 配下で最大規模のモジュールの一つ。

  • api/controller/: AIChatController / AIChatSessionController（チャット送受信・セッション）、AiRunController（Run の開始・SSE ストリーム配信）、AiPlanController（Plan Mode）、AiHandoffProposalController（人間へのハンドオフ提案）、AiMemoryController（AI メモリ）、SkillCatalogController（スキル一覧）、CodeRunToolController（コード実行 tool）、AICreditController / AdminCreditController（AI クレジット、課金は billing と連携）、AIConfigurationController（プロバイダ設定）、VoiceTranscriptionController
  • domain/service/AgentOrchestrator → AgentLoopRunner → AgentLoopStateMachine: agent ループの中核。プロンプト構築 (AgentSystemPromptBuilder)・LLM 呼び出し・tool 呼び出しの反復を状態機械として管理する
  • domain/service/ToolGate: tool 呼び出しごとに自動実行可否を判定する承認ゲート。破壊的操作はここで止まり、UI 側の承認 UI（3コンポーネント: 単発 Dialog / バッチ Card / 精読 ReviewDialog）を経て再開する
  • domain/service/LocalCliOrchestrator: LOCAL_CLI プロバイダ（Claude Code/Codex）向けの実行経路。AgentOrchestrator とは別の配線を持つため、新しい ui_action 系イベントを追加するときは両方に配線が要る
  • infrastructure/provider/: プロバイダごとのアダプタ（Vertex AI / OpenAI / CLI 系）
  • infrastructure/sandbox/: AI が生成したコードを実行するサンドボックス（GraalJsScriptExecutorAdapter 等）
  • domain/model/RunEvent.kt + api/dto/RunEventSerializer.kt: Run イベントのモデルとシリアライズ
  • SSE 配信は AiRunController が SseEmitter で行う（ライブ配信）。加えて infrastructure/persistence/RunEvent* がイベントを DB へ永続化し、再接続時のリプレイに使う

Frontend 構造

app/modules/ai/ は規約の4分類に加え stores・services・validators・utils を持つ。

  • types/run-event.schema.ts と types/run-event.schemas.ts: Run イベントの Zod スキーマ（下記コールアウト参照）
  • composables/useEventTransport.ts: SSE 接続の確立・再接続・イベントの型検証
  • composables/useExecutionTimeline.ts: Run イベント列を UI 用のタイムライン（ツールコール・思考・テキスト）に投影する
  • components/: surface/（メッセージ・ツールコール表示面）、proposal/（承認 UI）、atlas/（AI が参照するスキーマ・データ構造の可視化）、learning/（学習・フィードバック UI）、settings/、admin/、preview/

他モジュールとの辺

  • mcp: agent が呼び出す tool 定義（250+ 個）は core/mcp が提供する
  • organize: AI 抽出パイプラインは AIChatServiceAdapter（organize/extraction/infrastructure/adapter/）経由でこのモジュールの AI 呼び出し基盤を再利用する
  • billing: AI クレジット消費・利用量トラッキングは AICreditService → billing 連携
  • automation: 自動化ルールから起動される AI メンバー実行も同じ agent ループを通る
  • agent（Go Agent）: LOCAL_CLI プロバイダのブリッジ先

SSE イベント契約と承認ゲート

Run の進行はすべて RunEvent の discriminated union として SSE で流れる。UI はこれを useEventTransport → useExecutionTimeline の順で受け取り、実行タイムラインとして描画する。破壊的な tool 呼び出しは ToolGate が一旦止め、承認 UI（単発 Dialog / バッチ Card / 精読 ReviewDialog）でユーザーの承認を得てから再開する。

RunEvent の Zod スキーマは frontend に2ファイルある：types/run-event.schema.ts（SSE ライブ配信のバリデーション）と types/run-event.schemas.ts（eventProjection.ts が使う、DB 永続化ペイロードのリプレイ用バリデーション）。新しいイベント種別を追加するときはこの2ファイルを両方更新しないと、ライブ配信は動くのに再接続後のリプレイだけ壊れる、あるいはその逆という非対称バグになる。同様に backend 側も AgentOrchestrator 経路と LocalCliOrchestrator 経路の両方に新イベントを配線する必要がある。