unity-yaml-editing

**调用此模块中的任何技能之前：**如果你准备根据技能名称或描述猜测参数后调用该技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获得参数定义，则可直接执行 dryRun。

触发条件

• REST 无法触达时，手动编辑 YAML
• 修复 m_Script GUID 或断裂的 fileID 引用
• 修复 .meta 文件或合并冲突
• REST 无法触达时手动编辑 YAML、修复 m_Script GUID 或断裂的 fileID 引用、修复 .meta 文件或合并冲突

YAML 编辑 - 安全手动编辑规则

建议性模块。当 REST 技能（以及 Editor 本身）无法完成操作时，本模块提供直接编辑 Unity 序列化 YAML 文本的操作指南。手动编辑 YAML 是最后手段，而非捷径。

模式：仅文档——没有需要限制使用的 REST 技能；在任何操作模式（Approval / Auto / Bypass）下均可自由加载。

何时加载 / 何时不加载

优先使用 REST。 对于常规对象/资源操作，请使用 REST 技能——它们会帮你确保序列化有效：

• GameObjects / 组件 → gameobject_*
• Prefab → prefab_*
• ScriptableObjects → scriptableobject_*
• 场景 → scene_*
• 导入器 → importer_*
• 图形 / 渲染 → graphics_*

仅在 REST 无法触达时手动编辑 YAML，即符合以下任一情况：

1. 编译失败——脚本编译失败，导致 Editor 无法反序列化组件。Editor/REST API 不可用；此时只剩 YAML 文本这一层。
2. .meta 文件——没有 REST 技能会处理 .meta；GUID 和导入器字段仅存在于文本中。
3. 隐藏的 ProjectSettings 字段——许多 ProjectSettings/*.asset 字段没有公共 API 或 REST 接口。
4. 合并冲突——REST 按顺序运行，无法对 .unity / .prefab 执行 3 路合并。

如果以上情况都不适用，请停止并使用 REST。不要为了方便而手动编辑 YAML。

核心概念

• 对象块 / 锚点：每个序列化对象都是一个以 --- !u!<classID> &<fileID> 开头的块。<classID> 是 Unity 类型 ID（例如，1 = GameObject，4 = Transform，114 = MonoBehaviour）。<fileID> 是对象的锚点，在当前文件内唯一。
• GUID 与 fileID：
  • GUID = 资源级标识，是一个 32 位十六进制字符串，存储在资源的 .meta 中，用于标识整个资源（脚本、Prefab、纹理等）。
  • fileID = 文件内子对象的标识（某个特定组件、某个特定的 MonoBehaviour 脚本类等）。
• 序列化引用：跨对象/资源引用的格式为 {fileID: N, guid: H, type: T}。同一文件内的引用会省略 guid（{fileID: N}）。
• m_Script：MonoBehaviour 通过 m_Script: {fileID: 11500000, guid: <scriptGUID>, type: 3} 指向其脚本。fileID: 11500000 是约定俗成的 MonoScript fileID；guid 是 .cs 文件的 .meta 中的 GUID；type: 3 表示该引用指向磁盘上的资源。此处的 guid/fileID 不正确，正是导致“缺少脚本 / 缺少组件”的原因。

覆盖场景

1. 引用 / fileID 修复

适用情况：脚本被重命名或移动，导致 prefab/scene 的 m_Script guid/fileID 无法解析；或者编译失败导致组件变成 Missing，而你必须在 YAML 层级定位、删除或重新指定该组件（Editor 无法反序列化损坏的组件，因此无法使用 REST/Editor API）。

方法：从脚本的 .cs.meta 中读取其当前 GUID。在 prefab/scene 中找到有问题的 m_Script: {fileID: 11500000, guid: ..., type: 3}，并将 guid 设置为正确的值（保留 fileID: 11500000、type: 3）。若要删除 Missing 组件，请移除其完整的 --- !u!114 &<fileID> 块，并且移除所属 GameObject 的 m_Component 列表中对应的 {component: {fileID: <fileID>}} 条目——只移除其中一项会损坏文件。

危险：删除对象块但未删除其 m_Component 引用（或反过来）会损坏 GameObject；更改被其他对象引用的 fileID 会导致这些引用失效。

2. .meta / GUID 安全

适用情况：.meta GUID 看起来像伪随机 GUID，可能与第三方冲突；或者你必须编辑 REST 未公开的导入器字段。

方法：如需检测伪 GUID 和执行 uuid4 修复流程，请复用 /metacheck——其中记录了 5 种伪 GUID 启发式检测方法（连续的十六进制字符、交错递增、重复字符、字面值 abcdef、长度错误）、uuid4 重新生成步骤，以及 ValidationSkills.cs.meta 冲突案例的经验教训。此处不再重复推导。使用 python -c "import uuid; print(uuid.uuid4().hex)" 生成替换 GUID，切勿手动生成。

危险：更改 GUID 却未更新所有引用。更改任何 GUID 前，请先在整个项目中 grep 该 GUID（.asset / .prefab / .unity / .meta），并在同一次更改中更新所有引用位置。更改前后都运行 /metacheck，进行完整的 GUID 健康检查。

3. ProjectSettings 补丁

适用情况：你需要修改 REST 未公开的 ProjectSettings/*.asset 字段（YAML）——例如特定的物理层 / 碰撞矩阵条目，或隐藏的 QualitySettings 值。

方法：先备份到 git（或确认工作区干净），按键定位确切字段，只修改其值，然后让 Unity 重新加载并重新序列化以进行验证。确认更改能够往返还原（Unity 以相同方式重写文件），而不是还原或重新格式化文件。

危险：猜测编码方式来编辑碰撞矩阵或基于枚举的字段可能会悄然破坏设置；务必确认 Unity 在重新加载时接受该值。

4. 合并冲突辅助

适用情况：.unity / .prefab 中存在 Git 冲突标记，且你必须解决冲突。

方法：Unity YAML 可以按行合并，因为每个对象都是独立的 --- !u!<classID> &<fileID> 块。按块解决：若某个块只在一侧发生更改，则采用该侧；若同一块在两侧都发生了更改，则对冲突字段进行真正的三方合并。解决后，确保每个被引用的 fileID/guid 都有对应的定义块。

危险：盲目接受一侧（--theirs/--ours）会丢弃另一侧新增的对象，或留下悬空引用。切勿在未检查其中的 fileID 引用前，就通过删除整个冲突区域来解决冲突。

硬性规则

• 先备份：编辑任何 YAML 之前，确认 Git 工作区干净（或先提交／暂存），以便进行差异对比和回退。
• 除修复引用外，不要改动结构：只修改值；除非任务明确要求修复引用，否则不要重新编号或调整 anchor／fileID 的顺序。
• 重新导入以验证：编辑后，触发 Unity 重新导入／重新加载，并确认没有新增错误，且文件可以正常往返处理。
• GUID 必须是 uuid4，不要手动编写：python -c "import uuid; print(uuid.uuid4().hex)"。
• 批量编辑前先试运行：先用 grep 查看影响范围；修改前明确变更会涉及多少个引用。
• 更改 GUID → 更改所有引用：只有在同一变更中更新了所有引用该 GUID 的文件，才算完成 GUID 修改。

路由

• 如果 REST 技能可以完成任务，就使用 REST — gameobject_* / prefab_* / scriptableobject_* / scene_* / importer_* / graphics_* — 不要手动编辑。
• GUID 健康审计／伪 GUID 检测／uuid4 修复 → /metacheck。
• 编辑技能文档后，或检查文档与代码的一致性 → /skillcheck。