unity-perception

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターでスキルを呼び出そうとしている場合は、いったん停止し、このファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend/schema からパラメーター定義をすでに取得している場合は、そのまま dryRun に進めます。

トリガー

• 編集前のコンテキスト収集
• 不慣れなシーン／プロジェクトの理解
• 変更を加えずに構造を監査する

Unity Perception Skills

このモジュールは、読み取り専用のシーンおよびプロジェクト分析に使用します。

動作モード

• Approval／Auto／Bypass：このモジュールの 18 個のスキルのうち 17 個は Mode = SkillMode.SemiAuto に設定されており、3 つのモードすべてで grant 不要で直接実行できます。そのうち 16 個は純粋な読み取り専用（ReadOnly = true）です：scene_analyze / scene_summarize / scene_health_check / scene_component_stats / scene_find_hotspots / scene_tag_layer_stats / scene_performance_hints / scene_diff / hierarchy_describe / scene_context / scene_spatial_query / scene_materials / scene_contract_validate / project_stack_detect / script_analyze / script_dependency_graph。
• scene_dependency_analyze は 17 個目の SemiAuto ですが、純粋な読み取り専用ではありません：savePath を渡すと Directory.CreateDirectory + File.WriteAllText + ImportAsset によって新しいプロジェクトアセットを作成するため、MutatesAssets = true に設定され、ReadOnly は設定されません。引き続き grant は不要ですが、router の diff キャプチャ対象となり、schema/flags にも mutatesAssets が含まれます。savePath を渡さない場合に限り、実際に何も書き込みません。
• 特記事項：scene_export_report は Markdown ファイルをディスクに書き込みます（Operation = Analyze | Execute、MutatesAssets = true に設定）。そのため SemiAuto ではなく、デフォルトの SkillMode.FullAuto で動作し、Approval モードでは実行に grant が必要です。
• このモジュールには Delete／PlayMode／Reload／RiskLevel=high に該当するスキルはありません —— IsForbiddenInSemi によるブロックはありません。

禁止事項（よくある誤認）：

• perception_analyze、perception_scan、perception_describe は存在しません
• scene_context は editor_get_context ではありません。階層／コンポーネント／参照をエクスポートする一方、editor context は現在のエディター状態に焦点を当てています
• scene_analyze、scene_health_check、scene_contract_validate、scene_component_stats、scene_find_hotspots、project_stack_detect は、プレフィックスが scene_* や project_* のように見えても、このモジュールに属します

ルーティング：

• 現在の選択対象／PlayMode／エディターの状態 → editor_get_context
• 名前／パスによるオブジェクト検索 → scene_find_objects または gameobject_find
• スクリプトの依存関係の推移的な閉包 → script_dependency_graph

スキル

シーンのヘルスと概要

スキル	用途	主なパラメーター
scene_analyze	シーンとプロジェクトの複合分析	topComponentsLimit?、issueLimit?、deepHierarchyThreshold?、largeChildCountThreshold?
scene_health_check	読み取り専用のヘルスレポート	issueLimit?、deepHierarchyThreshold?、largeChildCountThreshold?
scene_summarize	構造化されたシーン概要	includeComponentStats?、topComponentsLimit?
scene_component_stats	コンポーネントと施設の統計	topComponentsLimit?
scene_find_hotspots	深い階層／大規模グループ／空のノードのホットスポット	しきい値 + maxResults?
scene_tag_layer_stats	タグ／レイヤーの使用状況	なし
scene_performance_hints	優先順位付きの最適化ヒント	なし

シーンのスナップショットとエクスポート

スキル	用途	主なパラメーター
scene_diff	軽量なスナップショットを取得または比較します	snapshotJson?
hierarchy_describe	テキスト形式の階層ツリーを返します	maxDepth?、includeInactive?、maxItemsPerLevel?
scene_context	階層、コンポーネント、参照をエクスポートします	maxDepth?、maxObjects?、rootPath?、includeValues?、includeReferences?、includeCodeDeps?
scene_export_report	Markdown 形式のシーンレポートを保存します	savePath?、maxDepth?、maxObjects?
scene_dependency_analyze	シーン内の影響／依存関係グラフを分析します	targetPath?、savePath? — 書き込みを行います

scene_dependency_analyze の savePath は出力オプションではなく、書き込みを行います。 これを指定すると、ディレクトリを作成し、Markdown レポートを書き込み、プロジェクトアセットとしてインポートします。そのため、このスキルには ReadOnly ではなく mutatesAssets のフラグが付いています。savePath を省略すると、ディスク上のファイルには何も変更を加えず、同じ分析結果がレスポンス（analysis、markdown）に返されます。単に「これに依存しているものは何か」と尋ねる場合は、この方法を使用してください。ファイルを求められた場合にのみ savePath を渡し、レスポンスにファイル名を示す savedTo が含まれることを想定してください。

プロジェクトとスクリプトの分析

スキル	用途	主なパラメーター
project_stack_detect	パイプライン、入力、UI、パッケージ、テスト、フォルダーを検出します	なし
script_analyze	クラス名を指定して、1 つの MonoBehaviour／ScriptableObject／ユーザークラスを分析します	scriptName、includePrivate?
script_dependency_graph	1 つのスクリプトクラス名を起点に、N ホップの依存関係の推移閉包を取得します	scriptName、maxHops?、includeDetails?

空間およびマテリアルのクエリ

スキル	用途	主なパラメーター
scene_spatial_query	点またはオブジェクトの近くにあるオブジェクトを検索します	x/y/z?、radius?、nearObject?、componentFilter?、maxResults?
scene_materials	シーンのマテリアルとシェーダーの概要を返します	includeProperties?
scene_contract_validate	デフォルトのルート／タグ／レイヤー／UI EventSystem の規約を検証します	requiredRootsJson?、requiredTagsJson?、requiredLayersJson?、requireEventSystemForUi?

使用頻度の高いスキルの違い

scene_summarize と scene_analyze と scene_health_check

スキル	最適な用途	主な出力内容
scene_summarize	手早い概要	オブジェクト数、階層の深さ、主要なコンポーネント
scene_analyze	幅広い診断	概要 + 検出結果 + 警告 + 推奨事項 + 次に使うスキルのヒント
scene_health_check	整理状態／危険信号の確認	スクリプトの欠落、名前の重複、深い階層、空のノード、ホットスポット形式の検出結果

scene_context と hierarchy_describe

スキル	最適な用途	出力形式
hierarchy_describe	人が読みやすいツリー	テキストツリー、軽量
scene_context	AI コーディングのコンテキスト	構造化された階層 + コンポーネント + 参照 + オプションのコード依存関係

scene_dependency_analyze と script_dependency_graph

スキル	範囲	使用する場面
scene_dependency_analyze	シーンオブジェクトの参照	「このオブジェクトを削除または無効化した場合、何が依存しているか」と尋ねる場合
script_dependency_graph	スクリプトクラスの依存関係の推移閉包	「この機能を変更するには、どのスクリプトに手を加える必要があるか」と尋ねる場合

主な戻り値の形式

scene_summarize

sceneName、stats、およびオプションの topComponents を返します。

scene_analyze

summary、stats、findings、warnings、recommendations、および suggestedNextSkills を返します。

scene_health_check

summary、findings、hotspots、および suggestedNextSkills を返します。

scene_context

objects、references、および任意のcodeDependenciesを含む構造化エクスポートを返します。人間向けの要約だけでなく、別の AI ステップでシーン全体のコンテキストが必要な場合に使用します。

使用頻度の高いオプション：

• rootPathを指定すると、1 つのサブツリーのみをエクスポートします
• シリアライズされたフィールド値が必要な場合は、includeValues=trueを指定します
• AI にシーンとコードの依存関係の概要が必要な場合は、includeCodeDeps=trueを指定します

scene_export_report

Markdown 形式の成果物をディスクに書き込み、savedTo、オブジェクト／スクリプト／参照の数、成功状態を返します。ユーザーが永続的なレポートファイルを求めている場合に使用してください。

デフォルト：

• savePath = "Assets/Docs/SceneReport.md"
• maxDepth = 10
• maxObjects = 500

スキルの使い分け

必要なこと	最初に使うのに最適なスキル
シーンの概要をすばやく把握	scene_summarize
詳細な診断	scene_analyze
不審な階層構造や煩雑さの特定	scene_find_hotspots
削除しても安全か／影響に関する確認	scene_dependency_analyze
AI コーディング用コンテキストのエクスポート	scene_context
スクリプトを読む順序	script_dependency_graph
レンダリング／入力／UI スタックの検出	project_stack_detect

最小限の例

import unity_skills

summary = unity_skills.call_skill("scene_summarize", includeComponentStats=True)
health = unity_skills.call_skill("scene_health_check", issueLimit=50)
context = unity_skills.call_skill("scene_context", maxDepth=6, maxObjects=120)
report = unity_skills.call_skill("scene_export_report", savePath="Assets/Docs/SceneReport.md")

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値は、このファイルではなく、GET /skills/schemaまたはunity_skills.get_skill_schema()で定義されています。