mcpField
H
hz-unity-project-analyzer

hz-unity-project-analyzer

github.com/meta-quest开发241229 次安装5 周前更新
代码仓库

关于 hz-unity-project-analyzer

面向 AI Agent 的 Unity 项目分析技能，可生成并维护存放于 `.agent-docs/` 的项目文档。支持全量扫描、增量更新和只读文档检索，覆盖场景、系统、预制件、资源与脚本。

主要功能

  1. 01生成项目结构与系统文档
  2. 02记录场景流程和依赖关系
  3. 03整理预制件、资源及脚本用途
  4. 04按变更增量更新文档
  5. 05基于现有文档只读检索

适用场景

  1. 01首次为 Unity 项目建立文档
  2. 02代码或资源变更后同步文档
  3. 03根据文档了解场景与系统

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/meta-quest/agentic-tools --skill hz-unity-project-analyzer

安装后在 Claude Code 中输入/hz-unity-project-analyzer确认已加载。

详细介绍

Unity 项目分析器

分析、记录并维护 Unity 项目结构的动态知识库，以便 AI Agent 理解。输出内容存放在 .agent-docs/ 中，采用适合纳入源代码管理的 Markdown 文件。

运行模式

此技能有四种运行模式。根据上下文判断应使用哪种模式：

模式 1：首次完整扫描

触发条件： .agent-docs/ 目录不存在，或 .agent-docs/index.md 不存在。

模式 2：增量更新

触发条件： 用户要求更新文档，或 AI Agent 已进行结构性更改（新增场景、脚本、预制件或系统）。默认使用此更新模式。

重要提示： 增量更新是实现过程的一部分，而非单独的步骤。创建或修改脚本、预制件或资源时，应在同一轮操作中更新对应的 .agent-docs/ 文件，然后再继续下一项任务。

模式 3：完整重新扫描

触发条件： 用户明确要求完整重新扫描（例如“重新扫描项目”“完整项目分析”）。

模式 4：内容导入

触发条件： 用户询问项目结构，或系统／功能的工作方式（例如“这个项目是做什么的”“球体系统如何工作”“项目结构”“加载项目分析”）。仅当 .agent-docs/ 存在时使用此模式。此模式为只读模式，不要修改文档。

完整扫描（模式 1）和完整重新扫描（模式 3）的说明

第 1 步：收集项目概览
  1. 阅读 README.md、CHANGELOG.md 以及 Documentation/ 文件夹中的所有文档
  2. 阅读 Packages/manifest.json，了解所有已包含的软件包
  3. 列出所有场景：Assets/**/*.unity
  4. 列出所有脚本文件夹和程序集定义：Assets/**/*.asmdef
  5. 列出所有预制件文件夹：查找包含 .prefab 文件的目录
  6. 从 ProjectSettings/ProjectVersion.txt 确认项目使用的 Unity 版本
  7. 如果可以连接到 Editor（unity status --format json 显示状态为 ready），请实时检查，以获取仅凭文件无法获得的更多信息 — 使用 unity command get_scene_hierarchy、find_assets、package_list --scope installed 和 get_*_settings 命令（get_player_settings、get_quality_settings、get_graphics_settings）。请参阅 unity-cli 技能。
  8. 如果连接了头显，记录测试设备基准信息 — 使用 metavr device list 和 metavr device info <id>（操作系统版本、设备形态），以便后续发现结果注明观察所用的硬件。
第 2 步：提出澄清问题

记录文档之前，询问用户任何仅凭代码或文档无法明确判断的内容。例如：

  • “我看到场景名为 X、Y、Z — 哪个是主入口？”
  • “我看到一个名为 [name] 的文件夹，其中的资源用途不明 — 它是做什么的？”
  • “我看到有多种网络方案 — 哪一种是主要方案？”

仅针对确实含糊的内容提问。如果从命名、文件夹结构或代码检查中可以明确判断，就直接记录。

第 3 步：分析并记录

对于以下每个类别，创建或更新相应的子文档：

3a. 项目概览（.agent-docs/project-overview.md）
  • 项目名称、描述、Unity 版本
  • 目标平台
  • 高层架构概述
  • 关键第三方软件包及其在此项目中的用途（仅作概述，不涉及内部细节）
3b. 场景流程（.agent-docs/scenes/）

为每个场景创建一个文件（例如 .agent-docs/scenes/startup.md）。

每份场景文档应包含：

  • 场景在项目中的用途和作用
  • 关键 GameObject 及其用途
  • 使用了哪些脚本／预制件
  • 场景切换（什么内容会加载此场景，此场景会加载什么内容）
  • 场景是否属于主运行流程、测试场景或示例

使用 mermaid 在 .agent-docs/scenes/_flow.md 中创建场景流程图：

graph LR
    Startup --> MainMenu --> Gameplay
3c. 系统（.agent-docs/systems/）

识别逻辑系统（网络、UI、音频、输入、游戏玩法等），并为每个系统创建一个文件。

对于每份系统文档：

  • 用途和职责
  • 关键脚本（包含文件路径）及其作用——重点说明如何使用，而不是实现方式
  • 系统使用的关键预制件
  • 对其他系统的依赖
  • 使用相对链接交叉引用相关场景和其他系统文档
3d. 预制件（.agent-docs/prefabs/）

根据内容是否清晰，选择分组记录或逐个记录：

  • 如果某个预制件文件夹的用途可通过命名一目了然 → 创建分组文档（例如，.agent-docs/prefabs/ui-elements.md）
  • 如果某些预制件的具体用途不明显 → 分别记录（例如，.agent-docs/prefabs/player-rig.md）

对于每个预制件或分组：

  • 用途以及适用场景
  • 嵌套预制件层级（记录嵌套预制件和变体）
  • 附加的关键组件
  • 使用该预制件的场景
  • 配置说明（重要的 Inspector 值、必需引用）
3e. 资源（.agent-docs/assets/）

根据实际情况记录非脚本、非预制件资源：

  • 材质、着色器、纹理、音频、动画、脚本化对象
  • 文件夹命名清晰时进行分组；用途不明显时逐个记录
  • 重点说明：资源是什么、用途是什么、使用方式和位置
3f. 脚本参考（.agent-docs/scripts/）

脚本通过代码自我说明。在此仅记录使用情境：

  • 按系统或功能领域整理
  • 对于每个脚本：说明用途、使用方法，以及所属的预制件或场景
  • 不要重复代码或描述实现细节
第 4 步：构建索引

创建或更新 .agent-docs/index.md 作为主入口：

# [Project Name] — Agent Documentation

> Auto-generated project knowledge base for AI agent comprehension.
> Last updated: YYYY-MM-DD

## Quick Context
[2-3 sentence project summary]

## Document Map
- [Project Overview](project-overview.md)
- Scenes
  - [Scene Flow](<scenes/_flow.md>)
  - [SceneName](<scenes/scene-name.md>)
  - ...
- Systems
  - [SystemName](<systems/system-name.md>)
  - ...
- Prefabs
  - [PrefabGroup](<prefabs/group-name.md>)
  - ...
- Assets
  - [AssetGroup](<assets/group-name.md>)
  - ...
- Scripts
  - [ScriptArea](<scripts/area-name.md>)
  - ...

## Runtime Flow
[Brief description of app lifecycle from launch to gameplay]
第 5 步：创建配置

创建 .agent-docs/_config.md：

---
last_full_scan: YYYY-MM-DD
last_update: YYYY-MM-DD
documented_systems:
  - system-name-1
  - system-name-2
documented_scenes:
  - scene-name-1
  - scene-name-2
documented_prefab_groups:
  - group-name-1
  - group-name-2
---

增量更新说明（模式 2）

  1. 阅读 .agent-docs/_config.md 和 .agent-docs/index.md
  2. 确定发生了哪些变化：
    • 如果 AI Agent 刚刚进行了更改：只更新受这些更改影响的文档
    • 如果用户要求更新：将当前项目状态与文档中记录的状态进行比较
      • 检查新增、删除或重命名的场景、脚本和预制件
      • 检查 Packages/manifest.json 中是否有新增的软件包
      • 如有帮助，检查 git status，查看近期修改的文件
  3. 只更新受影响的子文档
  4. 清理过时引用： 如果某个脚本、预制件或资源已删除或重命名，请在受影响的文档中删除或更新相关引用。不要留下失效引用。
  5. 如果新增或删除了文档，请更新 .agent-docs/index.md
  6. 更新 .agent-docs/_config.md 中的 last_update 和已记录列表

不要重写未发生变化的文档。

导入说明（模式 4）

  1. 检查 .agent-docs/index.md 是否存在——如果不存在，则跳过（没有文档可导入）
  2. 阅读 .agent-docs/index.md，获取文档映射和快速上下文
  3. 根据用户的问题，只阅读与问题相关的子文档。例如：
    • “这个项目是做什么的？” → 阅读 project-overview.md
    • “球体系统是如何运作的？” → 阅读 systems/balls.md
    • “有哪些场景？” → 阅读 scenes/_flow.md
    • 一般项目问题 → 阅读 project-overview.md 和 scenes/_flow.md
  4. 不要急于阅读所有子文档——按需阅读，保持上下文聚焦

文档编写指南

  • **受众：**优先面向 AI Agent。内容应明确、结构化且无歧义。
  • **篇幅：**每份子文档应简洁。优先使用结构化列表，而非段落。每份文档控制在 200 行以内。
  • **交叉引用：**仅在文档之间存在实际依赖或关联时，使用相对 Markdown 链接。
  • **图示：**如果 Mermaid 图比文字更能清晰说明流程或架构，则使用 Mermaid。文字更清晰时不必使用。
  • **第三方包：**记录项目如何使用这些包。不要介绍其内部实现。
  • **脚本：**记录用途和用法，而非实现方式。代码本身会说明实现。
  • **预制体：**记录嵌套层级。注明重要的 Inspector 配置。
  • **源代码管理：**每个文件聚焦一个概念。使用描述性文件名。避免使用大型的单体文档。
  • **过时内容：**在每份子文档顶部添加 Last updated: YYYY-MM-DD。这有助于识别可能需要更新的文档。
  • 日期：Last updated 字段中仅使用日期，不添加括号注释。

文件命名约定

  • 所有文件名均使用小写 kebab-case：player-controller.md、main-menu.md
  • 流程／索引文件名前加下划线：_flow.md、_config.md
  • 场景／系统名称改用 kebab-case：Startup.unity → startup.md

评论

支持 Markdown