nocobase-ui-builder

目標

• エージェント向けの書き込みパスは、未加工のビジネスペイロードを指定する nb api flow-surfaces <action> です。
• バックエンドの flow-surfaces は作成コンパイラーです。互換性のあるペイロードを正規化し、重大な検証エラーを集約した errors[] を返します。
• 作成時に集約された errors[] は、修正すべき問題の全件をまとめたものです。バックエンドが提供する errorCount、各エラーの path／ruleId／details、および agentInstruction を使って、列挙されたすべての問題を1つのペイロード改訂で修正し、同じ書き込みを再試行してください。必須の Portal 事前確認 にある Portal のナビゲーションエラーは、対象または実装パスの失敗であり、ペイロード修正の一括処理ではありません。
• 公開トランスポートとして nb のみを使用してください。nb が見つからない、または古い場合は、別のトランスポートに切り替えず、ブロックされているコマンド／環境の状態を報告してください。
• ルーティングは意図を優先してください。ディレクトリ全体ではなく、最初に一致するクイックルートのドキュメントを1つ開いてください。
• すでに一致するクイックルートがある場合は、そのルートを使い続けてください。ドキュメントを再発見するためだけにスキルディレクトリを列挙しないでください。
• リクエストが部分一致、または引き継ぎのみの場合は、このスキルの対象範囲の境界に沿って直接回答してください。引き継ぎの根拠を示すためだけに、ランタイム、スクリプト、ヘルパードキュメントを調べないでください。
• 1つのユーザーリクエストが複数のページにまたがる場合は、ページごとに順番に処理してください。同じ navigation.group.title を共有する複数のページは直列化します。最初のページでタイトルを解決して routeId を取得し、後続のページではその routeId を使用してください。タイトルのみでの作成は行わず、共有グループをタイトルのみで同時に作成することは禁止されています。
• ページ全体のナビゲーション対象のルールは navigation-targets.md に記載されています。解決済みの no-code Portal には、正確な kind: "portal" と routeName の検出、および navigation.portalUid が必要です。Admin／Mobile レイアウトを直接対象とする方法は、capabilities.multiPortal === false の場合に限り、レガシー方式として使用できます。同じタイトルを持つ重複した非モバイルグループには、明示的な routeId が必要です。共有グループのタイトルのみでの作成は、直列化してください。

必須の Portal Manager エントリーポイント

このスキル内の他の指示を適用する前に、同じユーザーリクエストに対して nocobase-portal-manage を読み込み、実行し、その通常の UI 構築ワークフローに従ってください。最初にクイックルートを開始したり、UI Builder のナビゲーション対象を調べたり、flow-surfaces を呼び出したりしないでください。

• 現在のリクエストに Portal Manager のルーティング結果がすでに含まれている場合は、それを使用し、Portal Manager を再度呼び出さないでください。これにより、no-code の UI Builder へのディスパッチがループするのを防ぎます。
• 有効な結果は、選択済みの有効な Portal 1件とその正確な name および portalType、capabilities.multiPortal === false を示す明示的なレガシーの証拠、または Portal Manager によって検証済みのレガシー Flow Surfaces シグネチャ（Portal の対象検出がなく、コアの apply-blueprint と構造化読み取り機能がある）のいずれかに限られます。引き継がれた isDefault マーカーは、表示／読み戻し用の情報にすぎず、選択の代わりにしてはなりません。
• portalType === "no-code"：選択済みの Portal コンテキストを使って、このスキルを続行してください。
• portalType === "ai"：このスキルを終了し、同じリクエストを Portal Manager の AI Portal ソースコードパスで続行してください。選択されたレコード／情報にローカルの開発パスがない場合、Portal Manager は最初に Portal を取得する必要があります。
• 有効な Portal が0件、未選択の Portal が複数件、またはタイプがない／サポートされていない場合は、Portal Manager の結果として扱ってください。UI Builder 内でこれらを回避しないでください。

ルーター

• ポータルを最優先する境界：必須の Portal Manager エントリが、このルーターへの唯一の入口です。有効な Portal が1つだけの場合は自動選択できますが、件数やデフォルト状態だけでは受け入れ条件を満たしません。選択されたレコードの portalType が厳密に no-code であると Portal Manager が報告した場合、または capabilities.multiPortal === false であることを示す明示的な根拠がある場合に限り、ここから処理を続行してください。AI Portal が1つだけの場合は、flow-surfaces への書き込みを行わずにこのスキルを終了し、同じリクエストの処理を Portal Manager のソースコード実装パスですぐに続けてください。開発パスが存在しない場合は、Portal Manager が先に Portal を取得します。AI Portal を使用するか、no-code Portal を作成するかを尋ねないでください。portalType がない、またはサポートされていない場合は、Admin にフォールバックせず、解決のため Portal Manager に戻してください。
• ページ全体の作成には、バックエンドの applyBlueprint、nb api flow-surfaces apply-blueprint、および ページ全体のクイックガイドを使用します。
• AI 社員／AI アシスタントのアクション作成は、ページ全体の書き込み、または flow-surfaces の局所的な書き込みの範囲内で行います。リクエストに AI 社員の配置、AI 分析ボタン、AI アシスタント、または AI タスクの再設定が含まれる場合は、ai-employee-actions.mdを読んでください。既存の表示ユーザー名のバインドを超えて、社員の検索、マッチング、作成、プロンプト／モデル／スキル／ツールの設定、またはライフサイクルの判断が必要な場合に限り、最初に nocobase-ai-employee を使用します。
• ダッシュボード／KPI／概要のルーティング：ダッシュボードのルーティング
• コメントとレコード履歴は、公開されている Flow Surfaces のブロックタイプを通じてルーティングします。リクエストにコメント、ディスカッションスレッド、履歴、監査履歴、または変更履歴が含まれる場合は、comments.mdまたはrecord-history.mdを読んでください。
• カレンダー／スケジュール／イベントビューの作成には CalendarBlockModel を使用します。リクエストに 日历、calendar、排期、日程、事件视图、または 排班 が含まれる場合は、calendar.mdを読んでください。
• メニュー、ページエントリ、routeId、pageSchemaUid、レイアウト／ワークスペースのスコープ、およびページ重複時の識別に関する判断には、navigation-targets.mdを使用します。表示可能なデスクトップメニューの検索には nb api resource list --resource 'desktopRoutes:listAccessible' --no-paginate -j を使用してください。メニュー項目を探すためだけに、利用できない desktop-routes 系 CLI、menus、catalog、または describe-surface を試さないでください。
• 既存のサーフェスへの局所的な編集には、compose、configure、update-settings、add-*、move-*、remove-* などのバックエンドアクションと、局所編集のクイックガイドを使用します。
• 既存のサーフェスへの局所的なリアクション作業は、get-reaction-meta から始め、set*Rules で書き込み、reaction-quick.mdを参照します。初回のページ全体のリアクションは、実行時の get-reaction-meta を使わずに reaction.items[] 内で処理します。成果物のみの局所的なリアクション草案では、予定している get-reaction-meta の確認を記録してください。
• 部分一致または境界のみを扱うリクエストは、まず境界のクイックガイドを使用します。
• ルートが明確になった後、テンプレート／参照／copy のルーティングが実際に対象となる場合は、まずテンプレートのクイックガイドを読み、次に全体の判断マトリクスとして templates.mdを読んでください。
• 実際の nb body を準備するまで、tool-shapes.mdを開かないでください。
• タスクに JS の code、renderer: "js"、jsBlock、jsColumn、jsItem、JS アクション、チャート、または ctx.* API に関する質問が含まれる場合は、まず js.md、次に js-surfaces/index.md、その次に js-snippets/index.md、最後に js-reference-index.mdを読んでください。その意図にポップアップ／ドロワー／ダイアログ／ドリルダウンを開く処理が含まれる場合は、popup-openview.mdも読んでください。JS を書き込む前に、テンプレート優先で、ポップアップに対応した FlowModel を解決してください。
• ペイロードまたは RunJS body で defaultFilter、dataScope.filter、resource.setFilter()、リクエストの params.filter、または { path, operator, value } 形式の条件を明示的に作成する場合は、必ず最初に filter トピックで nocobase-utils スキルを読み込み、次に Filter Condition Formatを読み、末端フィールドのライブメタデータを確認してください。ホストが求める UI Builder の形式は維持しつつ、演算子には末端フィールドのフロントエンド許可リストにあるものだけを選んでください。日付の比較には $dateBefore、$dateAfter、$dateNotBefore、または $dateNotAfter を使用し、$lt、$lte、$gt、$gte は使用しないでください。
• 現在のタスクでまだ使用していない flow-surfaces アクションを使う前に、利用可能な場合は nb api flow-surfaces <action> --help を実行してください。
• このスキルで保持されている唯一のローカルヘルパー CLI は nb-template-decision です。このリポジトリのルートから node skills/nocobase-ui-builder/runtime/bin/nb-template-decision.mjs を使って呼び出すか、このスキルの同等の絶対パスを使ってください。最初にヘルパー名だけで試さないでください。

必須の Portal 事前確認

ページ全体への書き込みと部分的な書き込みを含め、flow-surfaces を変更する前に、このゲートを完了してください。

1. Mandatory Portal Manager Entry が生成した現在のリクエストの結果を確認します。それがない場合は、UI Builder で何かを行う前に、エントリーに戻って Portal Manager を実行してください。
2. 現在のリクエストに Portal の解決結果がない場合、または複数の Portal が未選択のままの場合は、書き込みを行わずに停止し、リクエストを nocobase-portal-manage にとどめてください。
3. 有効な Portal が 1 つだけ選択されている場合、Portal Manager が選択されたレコードの portalType を報告することを必須とします。Portal が 1 つしか存在しないことや、Portal に isDefault のマークが付いていることだけでは、決して十分ではありません。
4. portalType === "no-code" の場合に限り、UI Builder を続行してください。portalType === "ai" の Portal が 1 つだけ選択されている場合は、UI Builder を終了し、同じビルドリクエストを Portal Manager のソースコード経路ですぐに続行します。選択された Portal のプロジェクトを特定し、選択されたレコード／情報に開発パスがない場合は、まず nb portal pull <portal> を実行してから、実装とテストを行ってください。元のビルドリクエストはこの引き継ぎをすでに許可しているため、AI Portal と no-code Portal の作成のどちらかをユーザーに選ばせないでください。また、UI Builder を終了したことだけを理由に、タスク全体を停止しないでください。タイプがない場合、または未対応のタイプの場合は、書き込みを行わずに終了し、互換性のあるスキルまたは実装経路を選択するため Portal Manager に戻ってください。Admin にフォールバックすることは決してありません。
5. no-code Portal が確認されたら、選択された Portal の空でない name を必須とし、navigation-targets.md の説明に従って、空でない navigation.portalUid を解決してください。マッピングが存在しないか曖昧な場合は、書き込みを行わずに停止してください。
6. 従来の Admin／Mobile レイアウト経路には、capabilities.multiPortal === false の明示的な証拠、または Portal Manager による検証済みの従来の Flow Surfaces シグネチャのいずれかが必要です。単に欠落している、true である、失敗した、認可されていない、サーバーエラーである、または不明瞭な機能結果は、従来型である証拠にはなりません。
7. マルチポータルのページ全体の作成では、解決済みの navigation.portalUid を含め、navigation.layoutUid を省略し、admin-layout-model への再試行を決して行わないでください。モバイルバックエンドの no-code Portal も navigation.portalUid 経由で開始し、その後、バックエンドのモバイルルート規則に従います。

バックエンドの Portal ナビゲーションエラーは停止／引き継ぎのシグナルであり、一括作成ペイロードの修復対象ではありません。

• navigation-portal-type-unsupported：同じ書き込みでの再試行を停止し、Admin に切り替えず、選択された AI Portal のソース経路に引き継いでください。
• navigation-portal-selection-required：すべての書き込みを停止し、Portal Manage を通じて Portal を選択するようユーザーに依頼してください。
• navigation-portal-not-found：停止し、Portal Manage を通じて要求された Portal を作成または確認するようユーザーに依頼してください。
• navigation-admin-layout-not-portal-target：Portal の解決をやり直してください。Admin への書き込みを続けるためにペイロードを変更しないでください。

必須ブロックタイプのエラーからの復旧

• ユーザー要件またはセマンティックルーティングによって jsBlock が選択された場合、作成エラーが発生しても、そのセクションは jsBlock のままにしてください。ペイロードの形式（settings.code または assets.scripts.<key>.code と block.script）を修正し、同じブロックタイプで再試行してください。エラーを回避するためだけに、table、list、chart、actionPanel、gridCard、markdown、または後回しにする旨の注記に置き換えてはいけません。
• ユーザー要件またはセマンティックルーティングによって chart が選択された場合、作成エラーが発生しても、そのセクションは chart のままにしてください。ペイロードの形式（ページ全体のブループリントでは assets.charts.<key>.query、assets.charts.<key>.visual、および block.chart、またはローカライズされた settings.query/settings.visual）を修正し、同じブロックタイプで再試行してください。エラーを回避するためだけに、table、list、jsBlock、actionPanel、gridCard、markdown、または後回しにする旨の注記に置き換えてはいけません。
• 必須の jsBlock または chart に対する集約された errors[] の応答は、現在のペイロードが無効であることを意味します。必須のブロックタイプを変更してよいという許可ではありません。ユーザーが要件を変更した場合、またはバックエンドが現在のコンテナーではそのブロックタイプをサポートしていないと明示した場合に限り、ブロックタイプを変更してください。
• 必須の jsBlock または chart が、ドキュメントに記載された修正を試みても作成できない場合は、代替ブロックで完了したと主張するのではなく、最新のエラーの証拠を添えて、その特定のセクションが未完了であると報告してください。

厳守事項

1. 必須の Portal Preflight が成功した後は、nb への書き込みに nb api flow-surfaces <action> を直接使用します。生のビジネスペイロードを一度だけ送信し、事前にラッパーエンベロープ、cliBody、ローカルヘルパーの出力を作成しないでください。
2. 通常の単一ページリクエストでは、実際のタブを正確に1つだけ使用することをデフォルトとします。ユーザーから求められていない限り、空のタブやプレースホルダーの markdown／メモ／バナーブロックを追加しないでください。
3. ブループリントの fields[] エントリーは、デフォルトで単純な文字列にします。popup、target、renderer、フィールド固有の type、またはライブフィールドの description から推測される明確なフォーム動作が必要な場合に限り、フィールドエントリーをオブジェクトにします。
4. ページ作成では、フィールドの正確な情報はライブコレクションメタデータから取得します。nb api data-modeling collections get --filter-by-tk <collection> --appends fields -j を優先します。このコマンド群を利用できない場合は、nb api resource list --resource collections --filter '{"name":"<collection>"}' --appends fields -j を使用します。作成時の正確な情報として data-modeling fields list／nb api data-modeling collections fields list を使用しないでください。ブループリントの fields[] で使用するフィールドには、空でない interface が必要です。コレクションフィールドの description は、フォーム作成時に使う入力情報として扱います。任意の言語からの意味抽出にはエージェント／LLM を使用し、構造化された公開動作のみを出力してください。必要に応じて、prepare の前に正規化済みフィールドメタデータ descriptionBehavior.{settings,linkage} として出力できます。明確な静的必須ヒントは settings.required に、低リスクの長さ／範囲／正規表現／件数制約は settings.rules または settings.maxCount にします。同一フォーム内の条件付き必須／無効／非表示のヒントが明確な場合は、安定したローカルフォームターゲットを対象に reaction.items[] として出力し、生成されたローカルキーは必要な場合にのみ実体化します。バックエンド生成の追加／編集ポップアップでは、同じ動作をターゲットスコープの defaults.collections.<collection>.formBehavior.addNew/edit に指定します。条件の説明でフィールド名ではなくローカライズ済みの UI ラベル／タイトル（たとえば status の代わりに 状态、highlights の代わりに 重点变化）が使われている場合は、ライブメタデータを通じてラベルを解決し、明示的なリンケージルールを出力してください。バックエンドのフォールバック解析に頼らないでください。利用可能な場合は、ライブのオプション value／ローカライズ済み label メタデータを使って条件値をマッピングします。settings.extra などの補助テキストだけでは、条件付き必須／無効／非表示の動作を網羅したことになりません。実際のリンケージルールがフィールドを対象にしていない限り、そのフィールドを implemented としてマークしないでください。曖昧な説明は推測せず、補助テキストとして残します。NocoBase バックエンドに生の説明を解析させたり、任意の言語を網羅するために決定論的なキーワードリストに頼ったりしないでください。ページ全体の applyBlueprint では、すべてのドラフトでライブメタデータから関係するコレクション全体を再計算し、古い断片を再利用せずに defaults.collections を一から再構築します。関係するすべての直接コレクションについて、popups.view／popups.addNew／popups.edit を安定した { name, description } ディスクリプターとして出力するか、バックエンドに実体化させてください。また、ブループリントで addNew を開く設定を明示していなくても、table ブロックがそのコレクションを addNew 閾値評価の対象にするようにします。fieldGroups と formBehavior はターゲットコレクションだけに指定します。固定の生成ポップアップシーンの1つで、シーンフィルタリング後も有効なフィールド数が10を超える場合に限り、defaults.collections.<collection>.fieldGroups を追加します。それ以外は、互換性のあるデフォルトをバックエンドに実体化させてください。生成したデフォルトの fieldGroups を確定する前に、コンパクトなセルフレビュー判定（approve または regenerate）を一度行い、実用上もっとも低い推論／no-think モードを使って最大1回だけ再生成します。バックエンドから集約されたフィールドグループエラーが返された場合は、ライブメタデータから意味的なグループを再生成して、一度だけ再試行します。関連フィールドでは、すべての関係スコープを、defaults.collections.<sourceCollection>.popups.associations.<associationField>.<action> の固定 view／addNew／edit の3種類に統一し、同じ { name, description } コントラクトを使用します。キーには最初の関係セグメントだけを使います。関連ごとまたは関係スコープごとの fieldGroups／formBehavior は作成しないでください。defaults.blocks は生成しないでください。また、defaults.collections.*.popups の下に blocks、fields、fieldGroups、レイアウトを配置しないでください。 バックエンド生成の追加／編集候補フィールドに空でない description がある場合、説明のある生成フィールドごとに、構造化された defaults.collections.<collection>.formBehavior.addNew/edit の出力、または兄弟プロパティ defaults.collections.<collection>.formBehaviorDescriptionReview.fields.<field> = { decision, reasonCode? } のいずれかで対応してください。実際のカバレッジが構造化された formBehavior または適用可能な reaction.items[] によって存在する場合に限り、decision: "implemented" を使用します。それ以外は、有効な reasonCode とともに decision: "noUiBehavior" または "unsupported" を使用してください。何もしないための逃げ道として、旧形式の fields: string[]、hasTried、formBehavior: {}、null を送信しないでください。null のレビュー項目は、生成候補の description が空の場合に限り使用できます。
5. layout を指定できるのは tabs[] またはインライン popup のみであり、ブロックオブジェクトには指定できません。createForm、editForm、details では、デフォルトで fieldsLayout を省略し、バックエンド作成処理に内部グリッドを生成させます。通常のフィールドは1行に2つ、divider、richText、vditor フィールドはライブコレクションメタデータに基づいて全幅の行になります。filterForm では、prepare により引き続き1行に3つのコンパクトな fieldsLayout が生成される場合があります。ブループリントで内部フィールドグリッドを直接制御する必要がある場合に限り、明示的な fieldsLayout を使用します。そのタブ／ポップアップにフィルター以外のブロックが1つ以下の場合に限り、ページ／ポップアップの layout を省略できます。それ以外は明示的なレイアウトが必須です。同じタブ／ポップアップにフィルター以外のブロックが複数ある場合、テンプレートに裏付けられていない各データブロックにはタイトルが必要です。テンプレートに裏付けられたブロックは対象外です。フィルター以外のブロックが1つだけなら、ユーザーが明示的に求めない限りタイトルは省略できます。単一スコープのデータブロックに冗長なタイトルを指定した場合、バックエンド作成処理は保存されるブロックのタイトル表示を削除します。低レベルの set-layout では、公開形式の { rows: [[{ key, span }]] } 構文を再利用しないでください。実行時の rows は Record<string, string[][]> であり、各セル配列にはライブの子 uid が積み重ねられます。[[uidA], [uidB]] は2列、[[uidA, uidB]] は縦積みの1列を意味します。
6. createForm、editForm、details では、ブロックに実フィールドが10個を超えて含まれる場合、フラットな fields[] リストではなく、明示的な fieldGroups を使用します。手動の divider 項目を代用として扱わないでください。また、fieldGroups と fieldsLayout を併用しないでください。
7. 表示されたレコードまたは関連レコードをクリックすると詳細が開くべき場合は、フィールドポップアップを優先します。ボタンまたはアクション列を使用するのは、リクエストで明示的に求められた場合に限ります。
8. ページ全体の navigation の判断は、navigation-targets.md に従ってください。同じタイトルの重複する非モバイルグループでは、navigation.group.routeId を明示する必要があります。モバイルターゲットではルートナビゲーションを使用し、グループを指定しません。非モバイルページの識別情報は、ターゲット、メニューグループの routeId、ページタイトルの組み合わせです。同じグループで同じタイトルの場合は置き換えられることがありますが、同じタイトルでもグループ、レイアウト、Portal が異なれば、別のページと統合、再利用、自動置換されることはありません。選択されたノーコード Portal では、必ず厳密にマッピングされた navigation.portalUid を使用し、navigation.layoutUid は省略します。ナビゲーションターゲットのデフォルト、レイアウトターゲット、バックエンドの layoutUid 値は無視します。Admin／Mobile レイアウトへの直接ナビゲーションは、レガシーレーンであることが確認できている場合に限り許可されます。
9. 非モバイルの applyBlueprint create では、新たに作成する navigation.group と、トップレベルまたは第2階層のすべての navigation.item に、有効な Ant Design アイコン名を1つ含める必要があります。モバイルで作成する場合、navigation.item.icon にはページエントリーのアイコンが必要で、グループアイコンは不要です。
10. タイトルだけを指定する共有グループの作成は、順番に行います。非モバイルの最初のページでは navigation.group.title による解決／作成が可能ですが、同じターゲットレイアウト内の後続ページでは、取得済みの navigation.group.routeId を使用する必要があります。
11. navigation.group.routeId とデスクトップルートの id はナビゲーションロケーター専用です。create／init またはページ全体の applyBlueprint 成功後に、後続のローカライズ作業や明示的な調査が必要な場合は、ページレベルの flow-surfaces get 用に pageSchemaUid に正規化します。catalog、context、get-reaction-meta、compose、configure、add*、remove* には、get／describe-surface／作成レスポンスから返されたライブの uid 値だけを使用してください。デスクトップルートの id を target.uid として渡さないでください。アーティファクトのみのロケーター引き継ぎでは、機械可読フィールド navigation.routeId、page.pageSchemaUid、liveTargets[].uid を直接保持します。ライブ uid がまだ存在しない場合は、null ではなく空でないプレースホルダー文字列を使用してください。
12. 最初の実際のページ全体 applyBlueprint を実行する前に、必須の Portal Preflight を完了し、計画に使うライブコレクション／ページ／メニューのメタデータが最新であることを確認したうえで、nb api flow-surfaces apply-blueprint --body-file <payload>.json -j を呼び出します。バックエンドは、ソートエイリアス、高さモード、ポップアップのデフォルト、フィールドグループ、タイトルフィールド、ナビゲーショングループのタイトル一致、テンプレートに関する判断、直接データサーフェスで省略された defaultFilter グループなど、互換性のあるデフォルトを解決します。明示的な無効なデフォルトフィルターは、集約 errors[] を返します。バックエンドから集約された作成エラー errors[] が返された場合は、問題をすべてまとめて修正してから生のペイロードを再試行します。最初のエラーだけを修正してすぐに applyBlueprint を再度呼び出さないでください。前述の4つの Portal ナビゲーションエラーが発生した場合は、このループを停止します。
13. 更新アクションのフィールド割り当てには、公開 API の settings.assignValues のみを使用します。bulkUpdate はブロックの actions に属するコレクションアクションです。updateRecord は recordActions に属するレコードアクションです。assignValues はホストコレクションのメタデータにあるフィールドをキーとする単純なオブジェクトでなければなりません。{} は有効で、割り当て値をクリアします。求められたアクションが 图标按钮／仅图标／アイコンボタンと説明されている場合は、公開設定 settings.icon と settings.iconOnly: true を設定して、その視覚的な意図を維持します。submit／update-record のワークフローバインディングには、公開 API の settings.triggerWorkflows または configure.changes.triggerWorkflows のみを使用します。各行は { workflowKey, context? } で、[] はバインディングをクリアし、null は無効です。これらのアクション設定に add-fields、生の flowModels、AssignFormGridModel、AssignFormItemModel、内部の stepParams を使用しないでください。 AI 従業員アクションには、公開 API の type: "aiEmployee" と settings.username、settings.auto、settings.workContext、settings.tasks、settings.style のみを使用します。既存の AI 従業員アクションも、configure.changes または update-settings の同じキーを使って再設定します。applyBlueprint／compose におけるワークコンテキストの参照には、target: "self" または同じ実行内のブロックキーを使用できます。ローカライズ編集では self またはライブ Flow Model の uid を使用します。バックエンドがデフォルトで flow-model を設定するため、type は省略可能です。タスクのプロンプトは tasks[].message.user または tasks[].prompt エイリアスに指定し、両方には指定しないでください。ショートカットのために生の AI props、stepParams、flowModels、データベース行を書き込まないでください。
14. 正規化されて保存された書き込み形式の正確な情報源は、バックエンドレスポンスです。ページ全体の作業には、ページ全体の作成／置換、1つのルートに基づくタブの完全な構築、複雑な複数ブロックページ、ネストされたポップアップを含むページ、複数のリアクションファミリーを持つページが含まれます。書き込み前の読み取りとメタデータの取得は許可されますが、そのルートで最初に行う変更書き込みはバックエンドの applyBlueprint でなければなりません。applyBlueprint の成功レスポンスをデフォルトの停止地点とします。後続のローカライズ作業または明示的な調査でライブ構造が必要な場合に限り、追加の get を実行します。この追加の読み戻しを行わない場合は、正規化された保存済みサブツリーとしてではなく、成功レスポンスとリクエスト意図に基づいて書き込み内容を報告してください。
15. デフォルト値、計算値、フィールド／ブロック／アクションの状態、表示／非表示は、まずリアクション作業として扱います。生の configure キーを推測しないでください。
16. JS／RunJS の書き込みペイロードでは、複数行の読みやすいソースを維持してください。value.source: "runjs"、jsBlock／jsItem／JS アクション、チャートの生コード、その他の code フィールドでは、書き込み前に、実際の改行文字と2スペースのインデントを使って、簡潔でないコードを作成します。周囲のペイロードが JSON だからといって、複数の文、ローカル変数の設定、条件分岐、文字列の組み立てを1行に圧縮しないでください。JSON 文字列内では改行を \n としてエンコードします。設定や分岐がない短い return／式1つだけなら、1行のままでも構いません。 jsBlock の公開ペイロードには厳密なルールがあります。新しいインラインブロックには type: "jsBlock" と必須の settings.code、任意の settings.version を使用します。既存の JSBlock の configure には changes.code／changes.version を使用します。ページ全体でアセットを再利用する場合は、ブロックの script: "<key>" とともに assets.scripts.<key>.code を使用します。デフォルトのテンプレートコードに依存するタイトルだけの JSBlock は作成しないでください。jsBlock では、ブロック直下の code、ブロック直下の version、手書きの stepParams、内部の props／decoratorProps／flowRegistry を作成しないでください。また、script とインラインのコード／バージョンを併用しないでください。 ポップアップを開く JS／RunJS／チャートコードでは、コードを書く前に、テンプレートを優先するポップアップ／openView の経路を使用します。コードから ctx.openView(triggerUid, ...) を呼び出すことはできますが、triggerUid は既存のポップアップ対応 FlowModel の uid でなければなりません。通常は、openView.uid の targetUid が popupTemplateUid／popupTemplateMode="reference" を持つテンプレートターゲットを指すポップアップホストです。デフォルトのトリガーターゲットとして、ChildPageModel、ページ、タブ、ポップアップサブツリー、一時的な uid を使用しないでください。 ポップアップブロック／設定が消費する実行時値（たとえばテーブルの dataScope 用チャートドリルダウンフィルター）は、meta を含む defineProperties を通じて渡し、{{ctx.drilldownValue}} のようなトップレベル変数として読み取ります。ポップアップブロック設定に {{ctx.view.inputArgs.params.*}} を生成しないでください。保存されるアクションがこれらの変数用のチャート ctx.openView() ホストだけである場合は、actionLinkage でそのホストを非表示にします。チャート専用の defineProperties に依存するポップアップを、表示される行アクションとして残さないでください。
17. ライブ読み戻しで既存のテンプレート参照が確認され、変更対象がテンプレート所有コンテンツである場合は、テンプレートソースをデフォルトとします。ホスト／openView の設定変更はローカルのままにします。ページ単位の文言はローカル限定の意図を意味しないため、自動的に copy に切り離さないでください。スコープが明確でない場合は、書き込む前に確認してください。判断アーティファクトでは、テンプレート所有コンテンツの経路とホスト／openView 設定の経路を、それぞれ templateOwnedContentRoute と hostOpenViewConfigRoute として別々に記録します。
18. インラインポップアップのオープナーを popup.template に結び付ける applyBlueprint の成功レスポンスは、テンプレート再利用に成功した結果であり、構造上の欠落ではありません。送信されたブループリント内のインライン popup.blocks は、テンプレートが見つからない場合のフォールバックコンテンツです。バックエンドが互換性のあるポップアップテンプレートを選択した場合、これらが保存される必要はありません。正規化レスポンスに展開済みのローカルポップアップブロックではなくテンプレート参照が表示されるという理由だけで、テンプレート再利用の確認を削除したり、replace に切り替えたり、copy に変換したり、ページ全体を再実行したりしないでください。ユーザーが「不要模板」「只改当前」、copy、detach、「本地独立」のようにローカル限定の動作を明示的に求めた場合に限り、インライン／ローカルのポップアップコンテンツを強制します。ポップアップテンプレートの厳密なフラグについては、template-quick.md と templates.md に従ってください。
19. テストまたはマルチエージェント実行では、ユーザーが削除を明示的に依頼した場合を除き、破壊的なクリーンアップを実行しないでください。
20. ユーザーまたはローカルヘルパーアーティファクト向けに、実際に保存済みの読み戻し内容を要約する場合は、table、details、editForm、filterForm、createForm など、正規化された型ラベルを使用する安定した公開サマリーを優先します。生のモデル名だけに頼らないでください。ページレベルの作成／置換では、サマリーに page.pageSchemaUid、page.pageTitle、page.menuGroupTitle を明示します。複数のページにまたがるシナリオでは、同じ正規ページ識別キーを pages.* の下で使用し、tables.*、lists.*、forms.* などの具体的なサマリーノードには type を使用します。blockTypes は、root.blockTypes や popups.*.blockTypes などの集約配列に限って使用します。ルートアクションは root.actionTitles に配置し、証拠として recordActionTitles だけを残さないでください。
21. リアクション作業では、get-reaction-meta によってそのシーンで必要なソースパスが利用可能であることを確認した後に限り、最終的なブロック／アクションターゲットを選択します。複数の機能を公開するターゲットでは、まず kind を照合して書き込みスロットを選び、その正確な機能フィンガープリントを再利用します。別の kind から近いフィンガープリントをコピーしないでください。現在のターゲットが必要なパスを公開できない場合は、サポートされないホストに推測したルールを書き込むのではなく、ターゲットを変更するか、ページ／ポップアップの構造を先に組み直します。
22. 構造を選ぶ前に、フィルターに関する文言を判別してください。テーブル／リスト／gridCard／カレンダー／カンバン系データサーフェスで、曖昧な「筛选／filter」リクエストがある場合は、別のフィルターブロックではなく、同じホストのブロックレベルの filter アクション／ボタンをデフォルトとします。テーブル／リスト／gridCard／カレンダー／カンバン／カード系のホストに検索を明示的に追加するリクエストの場合に限り、「搜索／search」も同様に扱います。「搜索页／搜索结果页／搜索门户／搜索列表页」のようにページを表す語が含まれる場合は、フィルターの意図ではなくページの意図として扱います。树筛选／树状筛选／tree filter／tree filter block／树形筛选区块 は FilterFormBlockModel ではなく、TreeBlockModel に直接割り当てます。書き込み前に references/blocks/tree.md を読んでください。「分析看板／dashboard／trend／概览」は、デフォルトでチャート／JSBlock のインサイト経路に割り当てます。トレンド、分布、ランキング、割合／占比、ビジュアル分析にはチャートを使用します。KPI／指標カード／数値統計／未読数形式の件数指標には JSBlockModel を使用します。レコードカードを表す文言には GridCardBlockModel を使用します。KanbanBlockModel に割り当てるのは、「看板区块／kanban／pipeline／status columns／拖拽／泳道／backlog」など、カンバンを示す手がかりがある場合に限ります。「看板」だけでは分析意図より優先されません。デフォルトで新しい filterForm を作成しないでください。まず references/aliases.md を読んでください。ユーザーがフィルター／検索ブロック、フォーム、またはクエリエリアを明示的に求めており、その表現がツリーフィルターのリクエストではない場合に限り、references/blocks/filter-form.md を開き、最初のブループリントに実際の filterForm を含めてください。その場合は、安定したフィルター項目、submit／reset アクション、低レベルの defaultTargetUid や生のブロック設定ペイロードではなく、同じブループリント内の文字列 target ブロックキーを含めます。 ダッシュボード指標に関する厳格なルール：

• リクエストされたサーフェスに KPI／指標カード／数値統計／統計カード／追踪产品数／未読数／今週の新規数／サマリー数値が含まれる場合、デフォルトで JSBlockModel を使用します。
• パッシブな指標カードを actionPanel と js アクションで実装しないでください。
• 集約数値指標に GridCardBlockModel を使用しないでください。
• ユーザー操作、ショートカット、アクションのエントリーポイントには ActionPanelBlockModel のみを使用します。ただし、ユーザーがクリック可能なアクションカードを主要 UI として明示的に求めている場合は除きます。
• ダッシュボードのドラフトで純粋な数値サマリーが actionPanel 内に配置されている場合は、書き込む前にドラフトを再生成します。
• バックエンドから jsBlock 作成エラーが返された場合、最終再試行の指示では同じ jsBlock ペイロード（settings.code または assets.scripts と block.script）を修正し、そのブロックタイプで再試行します。KPI エリアを table、chart、actionPanel、gridCard に切り替えないでください。
• バックエンドからチャート作成エラーが返された場合、details.repairHint に基づいて現在のチャートペイロードを修正し、chart として再試行します。エラーを回避するためだけにブロックタイプを変更しないでください。コンテンツが KPI／サマリー数値であるというエラーの場合は、そのセクションを jsBlock として再構築します。
• ダッシュボードのチャートゲート：リクエストでチャート／图表／Charts が明示的に求められている場合、またはトレンド／趋势、分布／分布、ランキング／排行、割合／占比が求められている場合、最初のダッシュボードドラフトには該当セクション向けの type: "chart" ブロックを含める必要があります。チャート数が指定されている場合、applyBlueprint の前にペイロードに少なくともその数のチャートブロックを含める必要があります。
• jsBlock の KPI カードとテーブル／リストのサマリーは、チャート要件の充足数に含めません。必須のチャートセクションがドラフトまたは読み戻しにない場合は、chart として再生成または修正します。ダッシュボードが完成したと報告しないでください。
• チャートが必須のページ全体を作成する場合、applyBlueprint の成功だけでは不十分です。返された pageSchemaUid を使って flow-surfaces get を実行し、完了を報告する前にチャートブロックの存在を確認します。
• 調査やペイロードの検証にはプローブページを使用できますが、最終成果物には含めません。最終引き継ぎにプローブページを含めず、クリーンアップが安全な場合は、ユーザーの納品用メニューに残ったプローブページを削除してください。 テンプレートを使用しない直接のテーブル／リスト／gridCard／カレンダー／カンバンデータサーフェスでは、defaultFilter を省略できます。バックエンド作成処理がライブコレクションメタデータから、スカラー／フィルター可能なフィールドを最大4つまで使って生成し、同じホストの filter アクションに割り当てます。これらのフィールドを意図的に上書きする場合に限り、ブロックレベルの defaultFilter または actions[].settings.defaultFilter を指定します。明示的なデフォルトフィルターには、コレクション内の直接対象となるインターフェースフィールド数と3のいずれか小さい方の数だけフィールドを含める必要があります。空、無効、関連フィールド、未知のパスを明示的に指定すると、バックエンドの集約 errors[] によって拒否されます。テーブルブロックの設定には、settings.pageSize、settings.sorting、settings.dataScope、settings.density、settings.showRowNumbers、settings.treeTable、settings.dragSort、settings.dragSortBy などの公開キーを使用します。ブロック直下または settings の下に、保存／内部キーの tableSettings、defaultSorting、stepParams を書き込まないでください。直接の公開データサーフェスでは、部分指定の actions はそのホストのデフォルト（filter／refresh／addNew と、テーブルでは bulkDelete）とマージされます。通常のテーブル recordActions は view／edit／delete とマージされますが、settings.treeTable=true のツリーコレクションテーブルでは view／edit／delete は補完されません。ユーザーから明示的に求められない限り、ツリーテーブルでは recordActions を省略し、デフォルトでバックエンドが addChild だけを挿入するようにします。fields[] を明示するツリーテーブルでは、リスト内で必要なフィールドをすべて指定します。fields[0] は、ライブメタデータにある、直接読み取り可能で関連ではないフィールドでなければなりません。既存の後続フィールドが読み取り可能であれば、それを先頭に移動できます。明示的な fields に title／name のフォールバックを挿入しないでください。また、読み取り可能な直接フィールドを含まない明示的なリストは拒否します。fields[] を省略した場合に限り、デフォルトの先頭フィールドは、メタデータの優先順位に従って titleField、次に name、code、title、その後に空でない interface を持つ別の直接フィールドから選択されます。id、uid、uuid、parentId、主キー／外部キー、xxxId／xxxUid、_id、_uid を先頭にしないでください。ユーザーが別のフィルターブロックを明示的に求めていない限り、フィルター／検索の意図は同じホストのブロックレベル filter アクションに割り当てます。 テンプレートを使用しないページ全体の applyBlueprint では、カンバンのメインブロックに明示できるカード fields[] は最大2つです。フィールドを省略すると、ライブメタデータから表示に適したフィールドが最大2つまで実体化されます。明示的に上限を超えた場合は、切り詰めずに kanban-main-fields-too-many が返されます。同じ applyBlueprint 経路では settings.dragEnabled=true がデフォルトになります。互換性のあるソートフィールドがある場合に限り settings.dragSortBy を送信し、それ以外は書き込み可能なメインデータソースコレクションに隠しソートフィールドをバックエンドに作成させます。明示的に dragEnabled=false を指定すると無効になり、明示的に互換性のない dragSortBy を指定すると拒否されます。

23. ローカライズされた compose／add-block／add-blocks／configure の本文を作成する場合は、nb api flow-surfaces <action> に直接送信します。バックエンド作成パイプラインは、書き込みの副作用が発生する前に互換性の正規化と厳格な検証を実行します。集約された errors[] が返された場合は、最初のエラーだけではなく、リスト全体を修正します。 comments と recordHistory には公開ブロックキーのみを使用し、ローカライズされた追加を行う前に catalog を確認します。ページブロックの comments にはコメントテンプレートコレクションが必要です。ポップアップのコメントには、コメントテンプレートコレクションへの hasMany または belongsToMany の関連を持つ resource.binding: "associatedRecords" が必要です。recordHistory ブロックには、実際の filterTargetKey を持つコレクションが必要です。現在のレコードの履歴は、1レコードのみのポップアップ／詳細シーンでしか有効ではありません。関連履歴リソースは無効です。これらのチェックを回避するために、生の CommentsBlockModel、RecordHistoryBlockModel、CommentItemModel、props、stepParams、生のスキーマを書き込まないでください。
24. ページ全体の最初の書き込みが成功した applyBlueprint の後も filterForm が空の枠のままの場合は、明示的なローカル／ライブの欠落として扱い、低レベルの addBlock／addAction／addField による修正は狭い範囲に限定します。最初の applyBlueprint が、filterForm 固有の形状／実行時エラーで失敗したことが確認できている場合は、バックエンドの集約エラーに基づいてブループリントを修正し、ブループリントのみで最大5ラウンド再試行します。成功前の再試行中に低レベルの書き込みへ切り替えないでください。5ラウンド失敗した後は、最新のブループリント／エラーの証拠を報告します。
25. 作成／編集フォームのヘルパーまたは参照が formValues.* に依存する場合は、ホストを選ぶ前に catalog／get-reaction-meta を調べます。そのライブシーンで fields／actions／node が公開されていても blocks が公開されていない場合は、独立したブロックではなく、同じフォームシーン内の jsItem または他のフィールド系ヘルパーとしてモデル化します。現在の JSItem ターゲットでは、setFieldState が JSItem を対象にできると仮定せず、フォーム値が存在するまで null をレンダリングして非表示／表示を実装します。この render-null パターンの使用に成功した場合は、読み戻し／証拠では設定済みのヘルパー切り替えとして扱います。fieldLinkage が JSItem 自体を対象にできないという理由だけで、ヘルパーの結果を未実装として扱わないでください。
26. 複数の作業領域、フィルター／検索ブロック、ネストされたポップアップ、または複数のリアクションファミリーがあるページは、別のルーター経路ではなく、複雑なページ全体のリクエストとして扱います。引き続き whole-page-quick.md に従い、applyBlueprint を1回だけ使う方法を優先します。
27. これらの複雑なページ全体のリクエストでは、最初のブループリント生成時に、構造ブロック、インラインポップアップ、トップレベルの reaction.items[] をまとめて含める必要があります。ページが大規模だからといって、ルートシェル／ポップアップ／リアクションのフェーズに分割しないでください。
28. 低レベルの get-reaction-meta と set*Rules または add* による修正は、既存のライブページに対するローカライズ編集、またはページ全体の applyBlueprint 成功後に明示的なローカル／ライブの欠落があり、狭い範囲での修正が必要な場合に限り使用します。ページ全体の applyBlueprint が一度成功する前に、createMenu、createPage、compose、configure、update-settings、add*、move*、remove*、set*Rules を使用しないでください。ページ全体の applyBlueprint が初回成功前に失敗した場合は、バックエンドの集約エラーに基づいてブループリントを修正し、ブループリントのみで最大5ラウンド再試行します。成功前の再試行中に低レベルの書き込みへ切り替えないでください。5ラウンド失敗した後は、最新のブループリント／エラーの証拠を報告します。
29. 一般的なスキルコントラクトでは、環境に依存しない状態を保ってください。ローカルのエイリアスや固定 URL をハードコードせず、現在設定されている CLI 環境または明示的なランタイムフラグを使用します。

読み取りパス

• ルートが不明な場合：references/index.md
• 業務上の意図に基づくページ全体の下書き作成／作成／置き換え：whole-page-quick.md
• ページ全体のナビゲーションレイアウト、グループ、ルート、および重複ページの識別ルール：navigation-targets.md
• ダッシュボード／KPI／概要のルーティング：dashboard-routing.md
• 既存画面の局所編集：local-edit-quick.md
• AI 従業員のアクション配置またはタスク編集：ai-employee-actions.md
• カレンダー／スケジュール／イベント表示ブロック：calendar.md
• コメントまたはレコード履歴ブロック：comments.md、record-history.md
• ページ全体または局所的なリアクション変更：reaction-quick.md
• 部分一致への対応と範囲を絞った引き継ぎレポート：boundary-quick.md
• 再利用、テンプレート選択、または既存テンプレート参照の編集：template-quick.md
• JS またはチャート関連の作業：js.md または chart.md

対象範囲と引き継ぎ

• portalType === "no-code" であることを明示的に確認した選択済み Portal が 1 つある場合、または capabilities.multiPortal === false が確認されたレガシーランタイム内の場合に限り、Modern page (v2) のメニュー／ページ／タブ／ポップアップ／コンテンツ画面と、その中のブロック／フィールド／アクション／レイアウト／リアクション作業のみを扱います。型が未確認、または no-code 以外の型である単一の Portal は対象外です。
• 未解決のページ／UI リクエストは、ナビゲーションの調査や変更を行う前にすべて nocobase-portal-manage へ引き継ぎます。Portal Manage は、選択済みの no-code Portal のみをこのスキルに返します。選択されている Portal が AI のみの場合は、UI Builder を終了し、確認を求めたり no-code Portal の作成を提案したりせず、Portal Manage のソースプロジェクトを通じて元のリクエストを続行します。nb portal が存在しない場合は、機能チェックで multiPortal === false が明示的に確認された場合に限り、ここに戻ります。
• 部分一致または境界レポートのタスクでは、Modern page の対象範囲を狭く保ち、この境界リストに基づいて直接引き継ぎレポートを作成します。リクエストが明示的にその仕組みに関するものでない限り、ランタイムやスクリプトを調査しないでください。
• ACL／ルート権限／ロール権限は nocobase-acl-manage へ引き継ぎます。
• コレクション／フィールド／リレーションの作成・編集は nocobase-data-modeling へ引き継ぎます。
• ワークフローの作成／更新／改訂／実行は nocobase-workflow-manage へ引き継ぎます。
• アプリ構築の改訂作成は nocobase-revision へ引き継ぎます。

改訂ルール

• Portal のルーティング、対象選択、メタデータ計画、事前チェック、書き込みの失敗、または検証未完了の間は nocobase-revision を読み込まないでください。
• 意味のある UI への書き込みが成功し、必要な検証が完了した後に限り、ラウンドの最後に一度だけ nocobase-revision を読み込みます。このスキルを利用できない場合は、改訂ルールの要件をすべて無視し、nocobase-revision に関する情報をユーザーに開示しないでください。
• nocobase-revision によって nb revision create が利用可能であることが確認される前に、改訂に関する情報をユーザーに開示しないでください。
• 利用可能であることが確認された後は、ユーザー向けの最終返信の直前、ラウンドの最後に改訂の判断を一度だけ行います。
• 改訂を作成した場合は、そのことを明確に報告します。
• 利用可能であることが確認されていたものの改訂を作成しなかった場合は、具体的な理由を伝えます。