# uid

> 文件 UID 管理(Godot 4.4+)。scan: 扫描缺 .uid 资源与孤儿 .uid。get: 查文件 UID(批量)。set: 写 .uid(指定 uid/generate 单文件/fix_missing 批量修复)。check_refs: 检测 uid:// 悬空引用(仅对照项目 .uid 集合;uid 悬空但 ext_resource 另有 path fallback 的引用引擎可正常加载,计入 dangling 属诊断提示,非断链)。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

| 属性 | 值 |
|------|-----|
| 所属层 | headless |
| 安全级别 | guarded |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 否 |
| 长耗时 | 否 |

## Actions

- `uid_scan`
- `uid_get`
- `uid_set`
- `uid_check_refs`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (4 项) | ✓ | 操作类型 |
| `project_path` | string |  | Godot 项目目录路径（可选，默认使用 GODOT_PROJECT_PATH 环境变量或当前目录） |
| `paths` | array |  | get: 文件路径列表(res:// 相对,支持批量) |
| `path` | string |  | set: 单文件路径(res:// 相对) |
| `uid` | string |  | set: 指定 UID 文本(uid://xxxx);省略则按路径确定性生成(与编辑器一致) |
| `fix_missing` | boolean |  | set: 批量修复全部缺 .uid 的资源 |
| `extensions` | array |  | scan/set 参与的资源扩展(小写,默认 26 个常见类型) |
| `limit` | number |  | scan/check_refs 明细截断上限(默认 100,最大 500) |

## 风险分布

读 3 / 写 1

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->