Back to Details

hz-unity-project-analyzer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unity Project Analyzer

Unity项目分析器

Analyze, document, and maintain a living knowledge base of a Unity project's structure, optimized for AI agent comprehension. Output lives in 
.agent-docs/
as source-control-friendly markdown files.
分析、记录并维护Unity项目结构的动态知识库，专为AI Agent理解优化。输出内容存储在
.agent-docs/
目录下，为适合版本控制的markdown文件。

Modes of Operation

操作模式

This skill operates in four modes. Determine which mode to use based on context:
本技能包含四种操作模式，需根据上下文选择合适的模式：

Mode 1: First-Time Full Scan

模式1：首次完整扫描

Trigger: 
.agent-docs/
directory does not exist or 
.agent-docs/index.md
does not exist.
触发条件：
.agent-docs/
目录不存在，或
.agent-docs/index.md
不存在。

Mode 2: Incremental Update

模式2：增量更新

Trigger: User asks to update docs, or AI agent has made structural changes (new scenes, scripts, prefabs, systems). Default update mode.
Important: Incremental updates are part of implementation, not a separate step. When creating or modifying scripts, prefabs, or assets, update the corresponding .agent-docs/ files in the same pass before moving on to the next task.
触发条件：用户要求更新文档，或AI Agent对项目结构进行了变更（新增场景、脚本、预制件、系统）。默认更新模式。
重要提示：增量更新是实现流程的一部分，而非独立步骤。在创建或修改脚本、预制件或资源时，需在进入下一项任务前同步更新对应的.agent-docs/文件。

Mode 3: Full Rescan

模式3：重新完整扫描

Trigger: User explicitly requests a full rescan (e.g., "rescan project", "full project analysis").
触发条件：用户明确要求重新完整扫描（例如："rescan project"、"full project analysis"）。

Mode 4: Ingestion

模式4：文档查阅

Trigger: User asks about the project structure or how a system/feature works (e.g., "what does this project do", "how does the ball system work", "project structure", "load project analysis"). Only use this mode when 
.agent-docs/
exists. This mode is read-only — do not modify docs.
触发条件：用户询问项目结构或某系统/功能的工作原理（例如："what does this project do"、"how does the ball system work"、"project structure"、"load project analysis"）。仅当
.agent-docs/
目录存在时使用此模式。该模式为只读模式——请勿修改文档。

Instructions for Full Scan (Mode 1) and Full Rescan (Mode 3)

完整扫描（模式1）与重新完整扫描（模式3）操作说明

Step 1: Gather Project Overview

步骤1：收集项目概述

  1. Read 
    README.md
    , 
    CHANGELOG.md
    , and any docs in 
    Documentation/
    folder
  2. Read 
    Packages/manifest.json
    to understand all included packages
  3. List all scenes: 
    Assets/**/*.unity
  4. List all script folders and assembly definitions: 
    Assets/**/*.asmdef
  5. List all prefab folders: find directories containing 
    .prefab
    files
  6. Identify the project's Unity version from 
    ProjectSettings/ProjectVersion.txt
  7. If Unity MCP is connected, optionally inspect scene hierarchies, prefab components, and project settings programmatically for richer data
  1. 读取
    README.md
    、
    CHANGELOG.md
    以及
    Documentation/
    文件夹中的所有文档
  2. 读取
    Packages/manifest.json
    以了解所有已包含的包
  3. 列出所有场景：
    Assets/**/*.unity
  4. 列出所有脚本文件夹和程序集定义：
    Assets/**/*.asmdef
  5. 列出所有预制件文件夹：查找包含
    .prefab
    文件的目录
  6. 从
    ProjectSettings/ProjectVersion.txt
    中识别项目的Unity版本
  7. 如果连接了Unity MCP，可选择性地通过编程方式检查场景层级、预制件组件和项目设置，以获取更丰富的数据

Step 2: Ask Clarifying Questions

步骤2：提出澄清问题

Before documenting, ask the user about anything that is not clear from the code or docs alone. Examples:
  • "I see scenes named X, Y, Z — which is the main entry point?"
  • "There's a folder called [name] with assets I can't determine the purpose of — what is it for?"
  • "I see multiple networking approaches — which is the primary one?"
Only ask about genuinely ambiguous items. If something is clear from naming, folder structure, or code inspection, document it directly.
在记录文档前，询问用户仅从代码或文档中无法明确的内容。示例：
  • "我看到名为X、Y、Z的场景——哪一个是主入口点？"
  • "有一个名为[name]的文件夹，其中的资源用途无法确定——它的作用是什么？"
  • "我看到多种网络实现方式——哪一种是主要使用的？"
仅对真正模糊的内容提问。如果通过命名、文件夹结构或代码检查可明确内容，直接记录即可。

Step 3: Analyze and Document

步骤3：分析与记录

For each category below, create or update the corresponding sub-document:
针对以下每个类别，创建或更新对应的子文档：

3a. Project Overview (
.agent-docs/project-overview.md
)

3a. 项目概述（
.agent-docs/project-overview.md
）

  • Project name, description, Unity version
  • Target platform(s)
  • High-level architecture summary
  • Key third-party packages and how they are used in this project (surface-level only — no internals)
  • 项目名称、描述、Unity版本
  • 目标平台
  • 高层架构概述
  • 关键第三方包及其在本项目中的使用方式（仅表面层级——不涉及内部实现）

3b. Scene Flow (
.agent-docs/scenes/
)

3b. 场景流程（
.agent-docs/scenes/
）

Create one file per scene (e.g., 
.agent-docs/scenes/startup.md
).
For each scene document:
  • Purpose and role in the project
  • Key GameObjects and their purpose
  • Which scripts/prefabs are used
  • Scene transitions (what loads this scene, what does this scene load)
  • Whether it's part of the main runtime flow, a test scene, or an example
Create a scene flow diagram in 
.agent-docs/scenes/_flow.md
using mermaid:
mermaid
graph LR
    Startup --> MainMenu --> Gameplay
为每个场景创建一个文件（例如：
.agent-docs/scenes/startup.md
）。
每个场景文档需包含：
  • 场景的用途及其在项目中的角色
  • 关键GameObject及其用途
  • 使用的脚本/预制件
  • 场景切换逻辑（哪些场景会加载此场景，此场景会加载哪些场景）
  • 它属于主运行流程、测试场景还是示例场景
在
.agent-docs/scenes/_flow.md
中使用mermaid创建场景流程图：
mermaid
graph LR
    Startup --> MainMenu --> Gameplay

3c. Systems (
.agent-docs/systems/
)

3c. 系统（
.agent-docs/systems/
）

Identify logical systems (networking, UI, audio, input, gameplay, etc.) and create one file per system.
For each system document:
  • Purpose and responsibility
  • Key scripts (with file paths) and their roles — focus on how to use them, not implementation
  • Key prefabs the system uses
  • Dependencies on other systems
  • Cross-reference related scenes and other system docs with relative links
识别逻辑系统（网络、UI、音频、输入、游戏玩法等），为每个系统创建一个文件。
每个系统文档需包含：
  • 系统的用途与职责
  • 关键脚本（含文件路径）及其角色——重点关注如何使用，而非实现细节
  • 系统使用的关键预制件
  • 对其他系统的依赖
  • 使用相对链接关联相关场景和其他系统文档

3d. Prefabs (
.agent-docs/prefabs/
)

3d. 预制件（
.agent-docs/prefabs/
）

Group or document individually based on clarity:
  • If a folder of prefabs is self-explanatory by naming → group doc (e.g., 
    .agent-docs/prefabs/ui-elements.md
    )
  • If individual prefabs have non-obvious purpose → document individually (e.g., 
    .agent-docs/prefabs/player-rig.md
    )
For each prefab/group:
  • Purpose and when to use it
  • Nested prefab hierarchy (document nested prefabs and variants)
  • Key components attached
  • Which scenes use it
  • Configuration notes (important inspector values, required references)
根据清晰度选择分组或单独记录：
  • 如果预制件文件夹的命名可自解释，则分组记录（例如：
    .agent-docs/prefabs/ui-elements.md
    ）
  • 如果单个预制件的用途不明显，则单独记录（例如：
    .agent-docs/prefabs/player-rig.md
    ）
每个预制件/组需包含：
  • 用途及使用场景
  • 嵌套预制件层级（记录嵌套预制件及其变体）
  • 附加的关键组件
  • 使用该预制件的场景
  • 配置说明（重要的检视面板值、所需引用）

3e. Assets (
.agent-docs/assets/
)

3e. 资源（
.agent-docs/assets/
）

Document non-script, non-prefab assets adaptively:
  • Materials, shaders, textures, audio, animations, scriptable objects
  • Group when folder naming is clear; document individually when purpose is non-obvious
  • Focus on: what is it, what is it for, how/where is it used
灵活记录非脚本、非预制件的资源：
  • 材质、着色器、纹理、音频、动画、可脚本化对象
  • 文件夹命名清晰时分组记录；用途不明显时单独记录
  • 重点记录：是什么、用途是什么、如何/在哪里使用

3f. Scripts Reference (
.agent-docs/scripts/
)

3f. 脚本参考（
.agent-docs/scripts/
）

Scripts are self-documenting through code. Here, document usage context only:
  • Organize by system or feature area
  • For each script: purpose, how to use it, which prefab/scene it belongs to
  • Do NOT duplicate code or describe implementation details
脚本通过代码实现自解释。此处仅记录使用上下文：
  • 按系统或功能区域组织
  • 每个脚本：用途、使用方式、所属的预制件/场景
  • 请勿重复代码或描述实现细节

Step 4: Build the Index

步骤4：构建索引

Create or update 
.agent-docs/index.md
as the main entry point:
markdown
undefined
创建或更新
.agent-docs/index.md
作为主入口：
markdown
undefined

[Project Name] — Agent Documentation

[项目名称] — Agent 文档

Auto-generated project knowledge base for AI agent comprehension. Last updated: YYYY-MM-DD
为AI Agent理解自动生成的项目知识库。 最后更新：YYYY-MM-DD

Quick Context

快速上下文

[2-3 sentence project summary]
[2-3句话的项目摘要]

Document Map

文档地图

  • Project Overview
  • Scenes
    • Scene Flow
    • SceneName
    • ...
  • Systems
    • SystemName
    • ...
  • Prefabs
    • PrefabGroup
    • ...
  • Assets
    • AssetGroup
    • ...
  • Scripts
    • ScriptArea
    • ...
  • 项目概述
  • 场景
    • 场景流程
    • 场景名称
    • ...
  • 系统
    • 系统名称
    • ...
  • 预制件
    • 预制件组
    • ...
  • 资源
    • 资源组
    • ...
  • 脚本
    • 脚本区域
    • ...

Runtime Flow

运行时流程

[Brief description of app lifecycle from launch to gameplay]
undefined
[从启动到游戏玩法的应用生命周期简要描述]
undefined

Step 5: Create Config

步骤5：创建配置文件

Create 
.agent-docs/_config.md
:
markdown
---
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
---
创建
.agent-docs/_config.md
：
markdown
---
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
---

Instructions for Incremental Update (Mode 2)

增量更新（模式2）操作说明

  1. Read 
    .agent-docs/_config.md
    and 
    .agent-docs/index.md
  2. Identify what changed:
    • If the AI agent just made changes: update only the docs affected by those changes
    • If the user asks to update: compare current project state against documented state
      • Check for new/removed/renamed scenes, scripts, prefabs
      • Check for new packages in 
        Packages/manifest.json
      • Check git status for recently modified files if helpful
  3. Update only the affected sub-documents
  4. Clean up stale references: If a script, prefab, or asset was deleted or renamed, remove or update references to it in the affected docs. Do not leave broken references.
  5. Update 
    .agent-docs/index.md
    if new docs were added or removed
  6. Update 
    last_update
    and the documented lists in 
    .agent-docs/_config.md
Do NOT rewrite docs that haven't changed.
  1. 读取
    .agent-docs/_config.md
    和
    .agent-docs/index.md
  2. 识别变更内容：
    • 如果AI Agent刚完成变更：仅更新受变更影响的文档
    • 如果用户要求更新：对比当前项目状态与已记录状态
      • 检查新增/移除/重命名的场景、脚本、预制件
      • 检查
        Packages/manifest.json
        中的新包
      • 如有帮助，可查看git状态获取最近修改的文件
  3. 仅更新受影响的子文档
  4. 清理失效引用：如果脚本、预制件或资源被删除或重命名，需在受影响的文档中移除或更新相关引用。请勿保留失效链接。
  5. 如果新增或移除了文档，更新
    .agent-docs/index.md
  6. 更新
    .agent-docs/_config.md
    中的
    last_update
    字段和已记录列表
请勿重写未变更的文档。

Instructions for Ingestion (Mode 4)

文档查阅（模式4）操作说明

  1. Check if 
    .agent-docs/index.md
    exists — if not, skip (no docs to ingest)
  2. Read 
    .agent-docs/index.md
    to get the document map and quick context
  3. Based on the user's question, read only the sub-docs relevant to what they are asking about. For example:
    • "What does this project do?" → read 
      project-overview.md
    • "How does the ball system work?" → read 
      systems/balls.md
    • "What scenes are there?" → read 
      scenes/_flow.md
    • General project questions → read 
      project-overview.md
      and 
      scenes/_flow.md
  4. Do NOT eagerly read all sub-docs — read on-demand to keep context focused
  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. 请勿主动读取所有子文档——按需读取以保持上下文聚焦

Document Writing Guidelines

文档撰写指南

  • Audience: AI agents first. Be explicit, structured, and unambiguous.
  • Size: Keep each sub-doc concise. Prefer structured lists over paragraphs. Target under 200 lines per doc.
  • Cross-references: Use relative markdown links between docs when there's an actual dependency or relationship.
  • Diagrams: Use mermaid when it clarifies flow or architecture better than prose. Skip when prose is clearer.
  • Third-party packages: Document how the project uses them. Do not document their internals.
  • Scripts: Document purpose and usage, not implementation. The code is self-documenting.
  • Prefabs: Document nested hierarchies. Note important inspector configuration.
  • Source control: One concept per file. Use descriptive filenames. Avoid large monolithic docs.
  • Staleness: Include 
    Last updated: YYYY-MM-DD
    at the top of each sub-doc. This helps identify docs that may need refresh.
  • Dates: Use only the date in 
    Last updated
    fields — no parenthetical annotations.
  • 受众：优先面向AI Agent。内容需明确、结构化且无歧义。
  • 篇幅：保持每个子文档简洁。优先使用结构化列表而非段落。目标是每个文档不超过200行。
  • 交叉引用：当存在实际依赖或关联时，使用markdown相对链接在文档间跳转。
  • 图表：当图表比文字更清晰地说明流程或架构时，使用mermaid。如果文字更清晰则跳过。
  • 第三方包：记录项目如何使用它们，而非其内部实现。
  • 脚本：记录用途和使用方式，而非实现细节。代码本身已自解释。
  • 预制件：记录嵌套层级。标注重要的检视面板配置。
  • 版本控制：每个文件对应一个概念。使用描述性文件名。避免大型单体文档。
  • 时效性：在每个子文档顶部添加
    最后更新：YYYY-MM-DD
    。这有助于识别可能需要更新的文档。
  • 日期：
    最后更新
    字段仅使用日期——无需括号注释。

File Naming Convention

文件命名规范

  • Use lowercase kebab-case for all filenames: 
    player-controller.md
    , 
    main-menu.md
  • Prefix flow/index files with underscore: 
    _flow.md
    , 
    _config.md
  • Match scene/system names but in kebab-case: 
    Startup.unity
    → 
    startup.md
  • 所有文件名使用小写短横线命名法：
    player-controller.md
    、
    main-menu.md
  • 流程/索引文件以下划线开头：
    _flow.md
    、
    _config.md
  • 场景/系统名称转换为短横线命名法：
    Startup.unity
    → 
    startup.md