跳到主要内容

Unity Insight

Unity Insight 是 Codely CLI 内置的 只读 Unity 项目分析专家。它基于虚拟文件系统（VFS）和 SQLite 索引，能够对 Unity 项目的场景、预制体、脚本、材质、纹理、着色器等资产进行快速的结构化查询和引用追踪。

核心定位与设计理念​

它是什么​

Unity Insight 是一个 基于索引的静态分析工具，而非实时编辑器控制。它通过预构建的 SQLite 索引对 Unity 项目资产建立图谱（Graph），支持快速查询资产间的引用、依赖、调用关系。

它不是什么​

  • 不是 实时 Unity Editor 控制器 — 那是 unity_editor、unity_scene 等内置 TCP 工具的职责。
  • 不是 文件系统浏览器 — 它查询的是索引快照，而非实时磁盘文件。
  • 不是 可写工具 — 不支持任何修改操作。

安装与配置​

安装 Unity Insight CLI​

Unity Insight CLI 与 Codely CLI 一起安装。如果缺失，可手动安装：

# 从 lsp 仓库根目录安装（开发模式）
./scripts/install.sh --dev

# 或仅构建 unity-insight
cd unity-insight && npm install && npm run build

安装后重启 Codely CLI。

启用 Unity Insight​

默认 禁用，需要在 settings.json 中启用：

{
  "unityInsight": {
    "enabled": true,
    "devEnabled": true,
    "cliPath": "/custom/path/to/unity-insight-cli"
  }
}
配置项类型默认说明
enabledbooleanfalse启用 Unity Insight 子代理及 VFS 工具注入
devEnabledbooleanfalse启用 /unity-insight 调试命令和会话导出遥测摘要
cliPathstring自动发现手动指定 Unity Insight CLI 二进制路径

提示： cliPath 也可通过环境变量 CODELY_UNITY_INSIGHT_CLI 设置。

VFS 工具详解​

Unity Insight 拥有 5 个只读 VFS 工具，每个工具针对不同的查询模式优化：

vfs_ls — 结构发现​

vfs_ls(path: string, depth?: number)
  • 用途：浏览目录结构和容器节点。
  • 参数：
    • path：VFS 路径（目录以 / 结尾，文件和叶子节点不以 / 结尾）
    • depth：读取后代内容的深度
  • 典型场景：不了解项目结构时，先 ls 探索。

vfs_glob — 路径/节点发现​

vfs_glob(
  pattern: string,      // glob 模式
  type: string,         // 必填：Scene, Prefab, Script, GameObject, Component 等
  path?: string,        // 限定搜索范围
  ignore_case: boolean, // 必填：是否大小写不敏感
  limit?: number        // 结果数量上限
)
  • 用途：按名称模式查找 GameObject、资产文件、层级节点。
  • 类型参数 type：必填，直接进入图谱查询条件。推荐使用精确类型，避免使用 ALL（会禁用类型过滤，可能很慢）。
  • 常用类型：Scene、Prefab、Script、GameObject、Component 等（系统提示中为 vfs_glob 列举的示例类型）。

vfs_grep — 内容搜索​

vfs_grep(
  pattern: string,       // 正则表达式
  type: string,          // 必填：Class, Method, Property, Material 等
  path?: string,         // 限定搜索范围
  include?: string,      // 文件名过滤
  ignore_case: boolean,  // 必填
  limit?: number
)
  • 用途：在索引内容中搜索正则表达式。
  • 注意：grep 搜索的是索引节点内容，不是 材质纹理槽位。查找纹理引用请用 vfs_refs(in)。
  • 类型参数 type：必填，推荐精确类型，ALL 仅作为后备。
  • 常用类型：Class、Method、Property、GameObject、Component、Script、Scene、Prefab、Material、Texture、Mesh、Model、AnimationClip、AnimatorController 等（系统提示中为 vfs_grep 列举的示例类型）。

vfs_read — 读取内容​

vfs_read(path: string, depth?: number)
  • 用途：读取资产/文件夹的 .meta、节点索引片段、或完整文本内容。
  • 路径格式：
    • Assets/Scripts/Foo.cs → 文件的 .meta 信息
    • Assets/Scripts/Foo.cs:/Foo/Bar → Foo 类中 Bar 成员的索引片段
    • Assets/Scripts/Foo.cs:/.content → 完整文本内容（脚本、着色器、.hlsl 等）
  • depth 参数：在节点路径上使用，一次性读取后代内容。
  • 建议：对于需要读取大部分成员的小型 .cs 文件，直接使用 vfs_read(...:/.content) 一次读取。

vfs_refs — 引用图谱查询（核心）​

vfs_refs(
  path: string,
  direction?: "in" | "out",
  filter?: "File" | "Component" | "GameObject" | "ALL"
)

  • 用途：查询资产间的引用关系。这是 Unity Insight 最强大的工具。

  • 推理模式（根据路径自动推断）：

    • .cs 文件 → 脚本绑定引用（incoming）
    • :/Class 或 :/Method → 代码调用引用（CALL refs）
    • 其他路径 → 资产引用

  • direction 参数：

    • in：谁引用了此资产（incoming / who uses this）
    • out：此资产引用了什么（outgoing / what this uses）
    • 默认推断

  • filter 参数（推荐使用精确过滤器）：

    • File：仅返回场景/资产文件路径
    • Component：仅返回渲染器/组件路径
    • GameObject：仅返回实例根节点
    • ALL：禁用结果过滤（不推荐）

  • incoming 查询的并集逻辑： 对于普通资产的 direction: in，自动并集以下关系：

    • Component DEPENDS_ON 链
    • 直接 DEPENDS_ON
    • 模型额外包含 INSTANCE_OF、RENDERS_MESH、PREFAB_INSTANCE_GUID

典型使用场景与示例​

场景 1：查找哪些场景/预制体使用了某个材质​

"哪些场景引用了 Assets/Materials/Enemy.mat？"

查询路径：glob → refs(in) → 完成

Unity Insight 会：

  1. 通过 vfs_glob 确认材质路径。
  2. 执行 vfs_refs({ path: "Assets/Materials/Enemy.mat", direction: "in" })。
  3. 返回引用该材质的所有场景和预制体文件路径。

场景 2：纹理 → 材质查找​

"哪些材质使用了 marioeye_alb.png 和 marioeye_nrm.png？"

查询路径：并行 refs(in) → 交集 → 完成

Unity Insight 会：

  1. 并行执行 vfs_refs(in) 在两个纹理上。
  2. 取两个纹理的 incoming .mat 路径的 交集。
  3. 按文件夹前缀过滤，返回同时引用两个纹理的材质。

场景 3：纹理 → 场景追踪​

"哪个场景使用了 HeroFace.png？"

查询路径：refs(in) on .png → 如结果只有 .mat → refs(in) on .mat filter:File

Unity Insight 会：

  1. 先查 HeroFace.png 的 incoming 引用。
  2. 如果只返回 .mat 材质文件，再对每个 .mat 执行 refs(in, filter: File) 查场景路径。

场景 4：GameObject/组件依赖分析​

"预制体 Enemy.prefab 中 AI GameObject 上的组件是否依赖 Health 组件？"

查询路径：glob 找路径 → refs(in, filter: Component)

Unity Insight 会：

  1. 用 vfs_glob 定位 AI 和 Health 的组件路径。
  2. 执行 vfs_refs({ path: "AI组件路径", direction: "in", filter: "Component" })。
  3. 非空结果表示返回的组件依赖查询的组件。

场景 5：着色器子图 → HLSL 引用​

"GetMainLight.shadersubgraph 引用了哪个 .hlsl 文件？"

查询路径：glob → refs(out) → 完成

Unity Insight 会：

  1. 用 vfs_glob 找到着色器子图路径。
  2. 执行 vfs_refs({ direction: "out" }) 获取外向依赖。
  3. 返回引用的 .hlsl 文件路径。

场景 6：代码结构查询​

"找到 SaveGame 类，哪个方法检查指定路径下是否存在某个标识符？"

查询路径：grep → grep → read 精确重载

Unity Insight 会：

  1. vfs_grep("class SaveGame", type: Class) 定位类。
  2. 在该文件上 vfs_grep("Exists(.*SaveGamePath", type: Method) 定位方法。
  3. vfs_read 精确重载路径，返回方法签名和文件位置。

场景 7：动画控制器 → 动画片段映射​

"动画控制器 'Window' 的哪个片段控制窗口关闭？"

Unity Insight 会：

  1. vfs_glob("**/*Window*.controller") 定位控制器。
  2. vfs_refs(out, filter: File) 获取所有引用的动画片段。
  3. 从结果中挑选匹配 "close" 语义的片段（如 Close.anim vs Open.anim）。

开发者调试命令​

当 unityInsight.devEnabled 为 true 时，CLI 中可使用 /unity-insight 斜杠命令：

/unity-insight status                          # 查看索引和服务状态
/unity-insight build                           # 同步构建索引
/unity-insight vfs_ls --path <vfs-path> [--depth N]
/unity-insight vfs_glob --pattern <glob> [--path <base>] [--type <kind>]
/unity-insight vfs_read --path <vfs-path> [--depth N]
/unity-insight vfs_grep --pattern <regex> [--path <base>]
/unity-insight vfs_refs --path <vfs-path> [--direction in|out]

status 输出示例​

Unity Insight Manager: success
  Project: F:/MyUnityProject
  CLI: /usr/local/bin/unity-insight-cli
  Server state: running
  tool schemas: 5

Index status:
  indexReady: true
  indexBuilding: false
  indexPath: F:/MyUnityProject/Library/UnityInsight/index.db
  schemaVersion: 1

注意： 这些命令仅供调试使用。正常使用时，Unity Insight 由主代理自动通过 Task 委托调用，无需手动执行 VFS 命令。

委托规则 — 如何正确向 Unity Insight 下达任务​

当主代理需要委托 Unity Insight 分析时，应遵循以下规则：

✅ 应该做的​

  • 只说目标：说明要找什么、要回答什么，而非怎么调查。
  • 说清范围：限定文件夹、场景、预制体等范围。
  • 说清交付物：明确期望返回什么（文件路径、组件名、方法签名等）。
  • 可选指定彻底程度：quick（快速）、medium（中等）、very thorough（非常彻底）。

❌ 不应该做的​

  • 不要规定步骤/工作流：不要说"先用 vfs_ls 再用 vfs_grep"。
  • 不要指定工具名称：不要提及 vfs_ls、vfs_grep 等。
  • 对于"哪个场景/预制体使用了此资产"的任务：不要要求读取场景 YAML 或引用 m_Materials 字段 — vfs_refs 路径就是充分证据。

委托示例​

✅ 好的委托：

"查找项目中所有引用了 Assets/Materials/Enemy.mat 的场景和预制体，返回文件路径。"

✅ 好的委托：

"在 Assets/Prefabs/Characters/ 目录下，找到同时挂载了 SpriteRenderer 和 AudioSource 组件的 GameObject，返回预制体路径和 GameObject 名称。彻底程度：medium。"

❌ 不好的委托：

"先用 vfs_glob 搜索 Enemy.mat，然后用 vfs_refs 查 incoming 引用，再 vfs_read 每个场景文件确认 m_Materials 字段包含该材质 GUID。"

限制与注意事项​

功能限制​

限制说明
默认禁用需在 settings.json 中设置 unityInsight.enabled = true
需要 CLI 二进制需安装 Unity Insight CLI；缺失时工具返回安装指引而非数据
索引必须存在首次分析可能需要等待后台索引构建完成
索引快照分析基于索引快照，可能与实时文件系统状态有延迟
无实时编辑器控制不能控制 Unity Editor（那是 Unity 内置 TCP 工具的职责）
轮次/超时上限最多 15 轮、10 分钟超时
grep 不搜索材质纹理槽vfs_grep 搜索索引节点内容，不是材质的纹理引用 — 请用 vfs_refs(in)

系统提示的硬性规则​

Unity Insight 的系统提示包含 5 条硬性规则（HARD RULES A–E），确保查询效率：

规则场景核心策略
A资产 → 场景/预制体引用glob → refs(in) → 完成，不并行 glob+grep
B纹理 → 材质查找并行 refs(in) → 取交集 → 完成
C纹理 → 场景追踪refs(in) on .png → 如只有 .mat → refs(in) on .mat filter:File
D组件依赖（同一预制体/场景内）glob → refs(in, filter: Component)
E外向依赖（着色器图等）glob → refs(out) → 完成

VFS 路径约定​

  • 目录和容器节点以 / 结尾：Assets/Enemy.prefab:/Root/
  • 文件和叶子节点不以 / 结尾：Assets/Scripts/Foo.cs:/Foo/Bar
  • 节点路径用 :/ 连接（不是另一个 /）：Assets/A.prefab:/Root，不是 Assets/A.prefab/Root
  • 方法重载用 #paramTypes：Foo.cs:/Foo/Save#string,int
  • 同名兄弟节点带 #siblingIndex
  • 预制体实例可能暴露 .SourcePrefab 和 .PrefabOverrides

故障排查​

Unity Insight CLI 未安装​

症状：VFS 工具返回安装指引而非查询结果。

解决方案：

# 从 lsp 仓库根目录
./scripts/install.sh --dev

# 或单独构建
cd unity-insight && npm install && npm run build

安装后重启 Codely CLI。

索引未就绪​

症状：CLI 启动时显示 [UnityInsight] Index missing at ...; started background index build.

解决方案：等待后台索引构建完成。可通过 /unity-insight status（需 devEnabled）查看索引状态。大型项目首次构建可能需要几分钟。

Serve 进程未启动​

症状：/unity-insight status 显示 No Unity Insight server instance。

可能原因：

  • unityInsight.enabled 未设为 true
  • 工作区未被识别为 Unity 项目
  • CLI 二进制路径不正确

解决方案：

  1. 检查 settings.json 中 enabled: true。
  2. 确认工作区包含 Assets/ 目录、ProjectSettings/ProjectVersion.txt 文件和 Packages/manifest.json 文件（三者均须存在，getUnityProjectStatus 据此判断是否为 Unity 项目）。
  3. 通过 cliPath 或 CODELY_UNITY_INSIGHT_CLI 手动指定 CLI 路径。

查询结果为空或不准确​

可能原因：索引过时，未同步最新文件变更。

解决方案：

/unity-insight build    # 同步重新构建索引（需 devEnabled）

或重启 CLI 触发自动 index sync。

Windows 上的控制台窗口弹出​

说明：在 Windows 上，后台索引进程使用 CREATE_NO_WINDOW 标志隐藏控制台窗口（而非 detached 模式），因为两者在 Windows 上冲突。这是已知行为，不影响功能。