nocobase-ai-employee

目標

NocoBase のビジネス画面に適した AI 従業員を設定し、サポート対象のライフサイクルを安全に管理します。要件に応じて、標準の UI アクション、JS アクション、ワークフロー、AI 従業員のどれを使用するかを判断し、最終的な UI 配置を再利用、作成、保守、検証したうえで nocobase-ui-builder に引き継ぎます。

対象範囲

• 要件に AI 従業員が必要かを判断し、適切な非開発者向け従業員を選択または作成します。
• サポート対象の AI 従業員レコードを調査、作成、更新、有効化、無効化、検証し、安全に削除します。
• サポート対象のプロフィールフィールドと、専用チャットモデルの制限を設定します。
• 公開 AI 従業員アクションの契約を準備し、UI 配置を nocobase-ui-builder に引き継ぎます。

対象外

• LLM プロバイダーや保存済みサービスは設定しません。nocobase-ai-manager を使用してください。
• ナレッジベースの利用資格を判断したり、ベクトルデータベース、ナレッジベース、ドキュメントを作成したりしません。nocobase-ai-knowledge-base-manager を使用してください。
• Flow Model やデータベースの行を直接記述してアクションを配置しません。nocobase-ui-builder を使用してください。
• ビジネス画面や AI Portal 画面で開発者向け従業員を公開しません。

必須の引き継ぎスキル

• Modern ページ／ブロック／アクションの作成と AI 従業員アクションの配置には、nocobase-ui-builder を使用してください。
• AI アクションを機能させる前にコレクション、フィールド、リレーションの追加が必要な場合は、nocobase-data-modeling を使用してください。
• AI 従業員がワークフローツールを呼び出す、または起動する場合や、タスクの大半が決定的なバックエンド自動化である場合は、nocobase-workflow-manage を使用してください。
• 専用の modelSettings を作成または変更する前に、nocobase-ai-manager を使用してください。
• ナレッジベース機能、リソース、バインドの準備が必要な場合は、nocobase-ai-knowledge-base-manager を使用してください。

入力契約

入力	必須	デフォルト	検証	確認の質問
action	はい	decide	decide/inspect/create/update/delete/verify/place のいずれか	「どの AI 従業員アクションを実行しますか？」
env	いいえ	nb env list の現在の環境	設定済み、到達可能、認証済み	「対象にする NocoBase 環境を指定してください。」
username	レコード変更時：はい、判断／調査時：任意	なし	一意に特定できる、正確で安定したユーザー名	「従業員の正確なユーザー名を指定してください。」
targetSurface	配置時：はい	なし	正確なページ／ブロック／アクションのコンテキスト	「どの UI 画面に従業員を表示しますか？」
changes	作成／更新時：はい	指定されていない値を保持	サポート対象の書き込み可能なフィールド、または検証済みの専門スキルへの引き継ぎ	「どの従業員フィールドを変更しますか？」
confirmation	高リスクのアクション時：はい	なし	影響を提示した後の、対象を明示した最新の確認	「この有効状態、モデル、ID、または削除の変更を確認しますか？」

ルール：

• 必須入力または依存関係の準備が不足している場合は、変更を中止して確認を求めてください。
• ユーザーが「お任せします」と言った場合は、調査して再利用候補を提案するだけにしてください。レコードの作成や変更は行わないでください。
• 重複した作成を更新に黙って置き換えたり、サポート対象外のフィールドを黙って破棄したりしないでください。

必須の確認ゲート

• 確認ラウンドの上限：2。1 ラウンドあたりの質問数の上限：3。
• 変更前に、環境、正確なユーザー名、変更する書き込み可能なフィールド、有効状態、モデル参照、専門スキルへの引き継ぎの有無を確認してください。
• モデルの変更には、nocobase-ai-manager による最新の準備状況の確認結果が必要です。
• 無効化、モデル変更、ID の変更、削除には、安全性確認ゲートに定められた影響の説明と追加確認のルールが適用されます。

判断ゲート

何かを書く前に、ユーザーのリクエストを分類してください。

ニーズ	優先するもの
固定的な CRUD、ナビゲーション、表示、フィルター、フィールドへの値の設定、または単純なボタンの動作	nocobase-ui-builder による組み込み UI アクション／リアクション
決定論的なクライアント側の計算、書式設定、検証、またはデータ変換	nocobase-ui-builder による JS アクション／JS サーフェス
決定論的な複数ステップのサーバー自動化、承認、通知、スケジュール実行	nocobase-workflow-manage によるワークフロー
自然言語の解釈、曖昧な意図、整理されていないテキストからの抽出、要約、分類、下書き、推奨、データ分析の説明、ツールの選択、またはモデルによる判断	AI 従業員アクション

モデルによる判断が曖昧さを実質的に軽減する場合、またはユーザーに自然言語でタスクを依頼できる環境を提供する場合に限り、AI 従業員を選択してください。一般的な決定論的 UI 設定の代替として AI 従業員を使わないでください。

ワークフロー

1. リクエストを分解する

   • 対象ページ／ブロック／アクションのスロット、対象コレクション、現在のレコードとブロック全体のどちらがコンテキストか、想定されるユーザー操作を特定します。
   • 決定論的なセットアップと、非決定論的なモデルの作業を分けます。
   • 対象となる UI サーフェスが一意に特定できない場合は、まず nocobase-ui-builder の検査ルートを使います。

2. AI 従業員が適切か判断する

   • Decision Gate を適用します。
   • AI が適切でない場合は、関連するスキルに引き継ぎ、より限定的な手順を説明します。
   • AI が適切な場合は、簡潔なタスク契約を作成します。従業員の役割、入力コンテキスト、期待する出力、自動送信するかどうか、ウェブ検索を使うかどうか、必要なツール／スキルを記載します。

3. 既存の AI 従業員を見つける

   • ユーザーに表示される従業員を確認するには、aiEmployees:listByUser を優先します。
   • ビジネスおよび AI Portal のサーフェスでは、enabled=true、deprecated=false、役割に応じて表示される行に絞り込み、category!="developer" を指定します。カテゴリのメタデータが欠落または古い場合でも、既知の開発者ユーザー名 nathan、dara、lina、orin は除外します。
   • 役割、役職、プロフィール、既存のツール、modelSettings を基に照合します。
   • 具体的なリソース名、フィールド、ペイロードの形式が必要な場合に限り、references/ai-employee-api.md を読みます。

4. 再利用または作成する

   • 互換性のあるツールとモデルの制限があり、役割を明確に担える既存の従業員がいる場合は再利用します。
   • 既存の従業員が約70％以上適合しない場合、またはユーザーが専任の従業員を明示的に希望する場合に限り、新しい従業員を作成します。
   • 新しい従業員では、ユーザー向けの説明を bio に記述し、運用上の動作は about に記述します。
   • 新しい従業員を作成する際は、aiEmployees:create の呼び出し前に、作成ペイロードの avatar にサポートされているアバターシードが設定されていることを確認します。
   • avatar が欠落、空、null、または未サポートの場合は、デフォルトのサポート対象シード nocobase-015-male を設定します。
   • ビジネスまたは AI Portal での操作には、developer カテゴリの従業員を決して作成しないでください。
   • 操作で nb api ai employees を使う場合は、従業員レコード管理に従います。この、より限定的な安全なフィールド契約がレコードの書き込みを規定します。

5. 従業員をブロックにバインドする

   • バインドする前に、選択した従業員を読み込み、category="developer" の従業員または既知の開発者ユーザー名の場合は拒否します。開発者従業員は専用の NocoBase ビルダー／エディターのサーフェスでのみ使用します。ユーザー向けの Portal 操作では、追加、公開、選択しないでください。
   • nocobase-ui-builder とその AI 従業員アクションのリファレンスを使います。
   • 公開アクションの形式のみを使います。type: "aiEmployee" に settings.username、settings.auto、settings.workContext、settings.tasks、settings.style を指定します。
   • 生の props、stepParams、flowModels、データベース行を書き込まないでください。
   • ブロック／フォーム／レコードのコンテキストでは、workContext: [{ "type": "flow-model", "target": "self" }] をデフォルトにします。

6. 検証する

   • 書き込みを行った場合は、nocobase-ui-builder を使って対象のサーフェスを読み戻すか、検査します。
   • AI アクションが意図した開発者以外のユーザー名を参照し、意図したタスクメッセージを設定していることを確認します。
   • 新しい従業員を作成した場合は、意図した役割で aiEmployees:listByUser に表示されることを確認し、avatar が空でなく、サポート対象のアバターシードのいずれかであることも確認します。表示されない場合は、役割／ACL に関する追加対応を説明します。

従業員のマッチングルール

適切な場合は、ビジネス向けの組み込み従業員を優先してください。

• atlas：幅広いリクエストを他の従業員に振り分けたり、サブエージェントを調整したりします。
• dex：整理されていないテキストから情報を抽出、整形、構造化したり、フォームに入力したりします。
• viz：データを分析して、インサイトやレポートを作成します。
• ellis：メールを理解、要約し、返信の下書きを作成します。
• lexi：ビジネスユーザー向けの翻訳とローカライズを行います。

ビジネス向けまたは AI Portal の画面では、開発者向け従業員を決して使用しないでください。これには、category="developer" を持つ従業員と、既知のユーザー名 nathan、dara、lina、orin が含まれます。タスクにドメイン固有の動作、制約されたモデルセット、専用のカスタムワークフローツール、またはビジネスユーザーに公開すべき役割やペルソナが必要な場合は、専用のビジネス従業員を作成してください。

アバターのペイロードルール

• avatar はプリセットのシード文字列であり、アップロードされたファイルオブジェクトや外部画像 URL ではありません。
• デフォルトのシード：nocobase-015-male。
• 新しい aiEmployees:create ペイロードには、必ず avatar を含めてください。
• 作成前に、以下のサポート対象シードに照らして avatar を検証してください。値がない、空、null、またはサポート対象外の場合は、nocobase-015-male に置き換えてください。
• 作成後、aiEmployees:list または aiEmployees:listByUser を通じて従業員を読み戻し、avatar が存在することを確認してください。

サポート対象のアバターシード：

nocobase-001-male
nocobase-002-male
nocobase-003-female
nocobase-004-male
nocobase-005-female
nocobase-006-male
nocobase-007-male
nocobase-008-female
nocobase-009-female
nocobase-010-male
nocobase-011-male
nocobase-012-male
nocobase-013-female
nocobase-014-female
nocobase-015-male
nocobase-016-female
nocobase-017-female
nocobase-018-female
nocobase-019-female
nocobase-020-female
nocobase-021-male
nocobase-022-male
nocobase-023-female
nocobase-024-male
nocobase-025-male
nocobase-026-male
nocobase-027-female
nocobase-028-male
nocobase-029-male
nocobase-030-male
nocobase-031-female
nocobase-032-male
nocobase-033-male
nocobase-034-female
nocobase-035-male
nocobase-036-female
nocobase-037-male
nocobase-038-female
nocobase-039-female
nocobase-040-female
nocobase-041-male
nocobase-042-male
nocobase-043-male
nocobase-044-male
nocobase-045-female
nocobase-046-female
nocobase-047-male
nocobase-048-female
nocobase-049-male
nocobase-050-female
nocobase-051-female
nocobase-052-female
nocobase-053-male
nocobase-054-female
nocobase-055-male
nocobase-056-female
nocobase-057-female
nocobase-058-female
nocobase-059-male
nocobase-060-female

タスク契約テンプレート

配置の前に、以下の内部テンプレートを使用してください。

{
  "intent": "what the user wants",
  "targetSurface": "page/block/action slot",
  "decision": "builtin|js|workflow|ai-employee",
  "employee": {
    "mode": "reuse|create",
    "username": "candidate-or-new-username",
    "role": "short business role",
    "reason": "why this employee fits"
  },
  "aiAction": {
    "auto": false,
    "autoSend": false,
    "context": "self|named block|record",
    "taskTitle": "short button/task title",
    "systemMessage": "stable operational constraints",
    "userMessage": "what the employee should do with the block context",
    "webSearch": false
  }
}

従業員レコードの管理

重要

旧 nocobase-ai-employee-manager スキルは削除され、非推奨となりました。サポート対象の従業員レコード操作はすべて、現在 nocobase-ai-employee を使用します。

この章は、上記の判断、従業員のマッチング、アバター、アクション契約、および UI 配置のワークフローを補足するものであり、置き換えるものではありません。運用上の詳細は、このメインファイルに記載を増やさず、バンドルされたリファレンスに記載してください。

レコード管理ルール

• nb api ai employees を使用する前に、employee-command-map.md、employee-record-fields.md、employee-record-workflows.md を読んでください。
• 正確で一意な username を1つ特定してください。作成前に存在しないことを確認し、作成後は ID を変更しないでください。
• 選択した API サーフェスでサポートされているフィールドのみを書き込み、指定されていないフィールドは保持してください。保護対象のフィールドは黙って破棄せず、拒否してください。
• 専用の modelSettings を作成または変更する場合に限り、nocobase-ai-manager を実行してください。
• ナレッジベースに関する意図がある場合は、機能、リソース、バインディングの準備に nocobase-ai-knowledge-base-manager を使用してください。このスキルは、検証済みの従業員フィールドの引き継ぎのみを適用し、KB のルールを重複して扱いません。
• 作成や更新のたびに読み戻してください。組み込み従業員を削除してはいけません。また、カスタム従業員を削除する前に、対象を正確に指定した最新の確認を必須としてください。
• 実行順序、冪等性、確認、ロールバック、失敗時の処理については、employee-record-workflows.md に従ってください。

リファレンスの読み込みマップ

リファレンス	使用する場面	備考
AI 従業員 API	従業員を選択する場合、または限定的な CLI レコード操作の範囲外で、確認済みのリソース操作を使用する場合。	主要なフィールド、プロンプトの意味、作成時のガイダンス。
ブロックアクションのペイロード	モダン UI の AI 従業員アクションを準備する場合。	公開されているアクションの形式と配置の引き継ぎ。
例	AI による動作と決定論的な動作を分類する場合、またはタスクのテキストを作成する場合。	再利用できる判断とペイロード。
従業員コマンドマップ	nb api ai employees を使ってレコードを調査または変更する場合。	対応する CRUD、前提条件、対象外の操作。
従業員レコードのフィールド	従業員レコードのペイロードを作成する場合。	書き込み可能なフィールド、デフォルト値、保護されたフィールド。
従業員レコードのワークフロー	作成、更新、無効化、削除、検証、ロールバックを行う場合。	冪等性と安全な手順。

安全性の確認

影響の大きい操作には、ID の変更、業務用従業員の無効化、専用モデル設定の変更、カスタム従業員の削除があります。保護された内部フィールドへの書き込みや、組み込み従業員の削除は決して行わないでください。

二次確認のテンプレート：

• 「実行を確認してください：<env> の AI 従業員 <username> に対する <action>。想定される影響：<availability/model/identity impact>。続行するには confirm と入力してください。」

ロールバックのガイダンスは employee-record-workflows.md にあります。検証に失敗しても、新しい従業員を自動削除しないでください。また、書き込みがタイムアウトまたは 5xx になった場合は、読み戻しを行うまで状態不明として扱ってください。

検証チェックリスト

• 対象環境と従業員のコマンド／リソース操作の範囲を確認済みです。
• 作成時はユーザー名が未使用であり、それ以外の操作ではユーザー名が一意に特定されています。
• 業務向けまたは AI ポータルへの配置では、選択した従業員が開発者以外であることを確認済みです。
• 作成ペイロードに、対応しているアバターが含まれています。
• ペイロードには、選択した操作範囲で書き込み可能なフィールドのみが含まれています。
• すべての作成／更新について、安全なフィールドを個別に読み戻して確認しています。
• 組み込み従業員の削除や ID の変更は決して行いません。
• 必要な確認、許可されるケース、拒否されるケース、エラー、部分的な成功を個別に報告しています。

最小テストシナリオ

1. 正常系：不要な前提作業を行わず、既存の従業員を調査して再利用する。
2. 正常系：カスタム従業員を作成または更新し、読み戻して検証する。
3. 必須入力の不足、または保護されたフィールドの無効な指定がある場合は、変更を中止する。
4. 認証または権限のエラーが発生した場合は、復旧手順を案内して実行を停止する。
5. 拒否ケース：組み込み従業員の削除を拒否する。カスタム従業員の削除には、改めて確認を取り、削除されていないことを検証する。

出力契約

最終回答では、環境、操作、正確なユーザー名、実行した安全なコマンド、適用したデフォルト値、使用した前提条件または専門家への引き継ぎ、読み戻しの証拠、確認事項、ロールバックの制限、部分的な成功、残っている UI 作業を明示する必要があります。

リファレンス

• NocoBase AI 従業員のドキュメント: 現在の製品動作を確認するときに使用します。［確認済み：2026-08-04］
• AI 従業員 API：従業員のフィールド、プロンプトの意味、確認済みのリソース操作に使用します。
• ブロックアクションのペイロード：公開 UI アクションの契約に使用します。
• 例：分類とタスクの例に使用します。
• 従業員コマンドマップ：対応している nb api ai employees コマンドと対象外の操作に使用します。
• 従業員レコードのフィールド：安全なフィールドのスキーマ、モデルの制約、デフォルト値、保護されたフィールドに使用します。
• 従業員レコードのワークフロー：CRUD、検証、ロールバック、削除の安全性に使用します。