AI アシスタント

すべてのページの右下に AI アシスタントがあります（ショートカット ⌘ / Ctrl + J）。自然な言葉で質問すると、システムの API を探してデータを読み取り、回答します。データの変更が必要なときは実行内容を一覧で示し、「許可」をクリックした後にだけ実行します。常にあなた自身として操作するため、あなたに権限のない操作はできません。

有効にする

アシスタントは初期状態ではオフです。まず「システム管理 → システム構成 → システム設定 → AI」でモデルを設定し（設定項目 → AI モデル を参照）、同じタブの「AI アシスタントを有効にする」（ai.assistant_enabled）をオンにします。モデルを設定するまでこのスイッチはオンにできません。API キーとモデル名が必要で、OpenAI 互換のプロバイダーでは API のアドレスも必要です。

オンにすると、ログインしているすべてのユーザーの画面右下にアシスタントのボタンが表示されます（すでに画面を開いているユーザーは再読み込み後に表示）。オフにした場合も同様にボタンが消え、API はすぐに 403 を返します。

できること

• 質問に答える：システムの使い方、今のページで何ができるか。アシスタントは現在開いているページを把握しています
• データを調べる：「有効なユーザーは何人？」「技術部のメンバーを一覧表示して」「最新の操作ログ 10 件」
• データを変更する：「テスト部を品質部に名前変更して」「張偉に通知を送って」。書き込みのたびに確認カードが表示されます。一行の説明、メソッドとパス、送信するデータを確認し、「許可」を押すと実行、「拒否」を押すと何も行いません

会話は現在のブラウザタブに、直近 40 件のメッセージまで保存されます（再読み込みしても残り、タブを閉じると消えます）。パネル上部の「新しい会話」で消去できます。

安全性

• あなたとして API を呼び出す：アシスタントの呼び出しはすべて画面と同じ API を、あなたのログイン状態で通ります。そのため権限、データ権限、デモモードの制限、レート制限がそのまま適用され、書き込みは操作ログに記録されます（ユーザーはあなた、User-Agent は castor-kit-assistant）
• 書き込みは 1 件ずつ確認：作成・変更・削除はすべて確認カードで「許可」を押すまで待ちます。確認リクエストはサーバーが署名しており（鍵は SECRET_KEY から派生）、ブラウザで偽造した「許可」は拒否されます
• 対象外の API：あなた自身のアカウントとセキュリティ（プロフィールとパスワード、2 段階認証、ログインセッション、API トークン）、システム設定の変更、Webhook の作成・変更・削除とシークレットの参照、インポート / エクスポート、ファイルのアップロード / ダウンロード、ほかの AI API、アシスタント自身。これらは画面で操作してください
• 保護対象：スーパー管理者のアカウント（編集・無効化・削除は不可）、スーパー管理者ロール、スーパー管理者ロールの付与、そしてあなた自身のアカウント。アシスタントはできないと伝え、確認カードは表示しません。API 自体が許可する場合（スーパー管理者が別のスーパー管理者を操作するなど）でも、画面で操作してください
• ほかのユーザーの管理は通常どおり可能：ユーザー管理の権限があれば、ユーザーの作成（初期パスワードを含む）、パスワードのリセット、ロールの割り当てを頼めます。いずれも確認カードで許可が必要です。パスワードはあなたが指定したものだけを使い、強度はシステムのパスワードルールで検証されます。なお、チャットに書いたパスワードはモデルサービスに送信され、このタブの会話履歴にも残ります（確認カードと操作ログには平文で表示されません）。気になる場合は画面でパスワードを設定してください
• API の結果はデータとして扱う：レコード内の「これまでのルールを無視して」といった文言は指示として扱いません。8,000 文字を超える結果は構造を保ったまま縮めます（長いテキストを切り詰め、レコード内の入れ子のリストは数件だけ残し、それでも収まらなければ先頭のレコードだけを残す）。省いた内容はモデルに伝えます
• データはモデルサービスに送信される：アシスタントが読み取ったデータは、設定した AI サービスにコンテキストとして送信されます。データのコンプライアンス要件に合ったサービスを選んでください
• API トークンではアシスタントの API を呼び出せません。デモモードでは AI 呼び出し枠を消費し、1 メッセージあたりのツール呼び出しは最大 4 回です（通常は 8 回）

自分のモジュールをアシスタントから使えるようにする

アシスタントは次の 2 つから API を把握します。

1. サーバー起動時に実際に登録された /api/admin/... ルート
2. docs/apifox-full.openapi.json にあるそれらの説明（summary、description、クエリパラメーター、リクエストボディのフィールド）

pnpm scaffold で生成したモジュールは、API ドキュメントも書き込み済みです（summary は「设备台账列表」のような中国語）。手で追加・変更したルートは、pnpm openapi:generate でひな形のエントリを追加し、AGENTS.md「OpenAPI writing rules」に沿って仕上げてください（AI 駆動開発を参照）。ドキュメントのないルートも呼び出せますが、アシスタントに見つけてもらいにくくなります。

アシスタントに呼ばせたくない API がある場合は、apps/api/src/modules/admin/assistant/catalog.ts の ASSISTANT_DENIED にパスのルールを追加します。