GameUnity/AGENTS.md

本文件补充仓库根目录 AGENTS.md，只适用于 GameUnity/ Unity 工程及其子目录。仓库级规则、用户优先级和通用编码准则继续有效。

工程事实

• Unity 工程根目录是当前目录 GameUnity/。
• 主启动场景是 Assets/Scenes/GameStart/GameStart.unity。
• 项目解决方案是 GameUnity.sln。
• 项目级 Unity CLI 是工程目录的 GameUnity/Tools/unity.exe。
• 配置源文件位于仓库根目录 ../GameConfig/，不是 GameUnity/Configs/。
• Unity 版本取 ProjectSettings/ProjectVersion.txt；直接 CLI 路径和版本首次使用时核对，doctor 可用于环境报告。Pipeline 能力以本项目注册命令及包内 Documentation~ 为准。
• Unity 查询、对象操作、编译和测试使用原生工具；已加载 MCP 通过 editor_status 核对当前工程，CLI 使用显式工程路径。调用、版本核对和接入规则统一见 unity-cli 技能。

DGame 任务分级与技能路由

涉及 DGame API 名称、程序集边界、资源地址、UI 节点前缀、事件接口、热更流程或 Luban 表结构时，不按 L1 处理。

处理 DGame 代码时优先使用 dgame-dev；内容以当前源码、目录和 API 为准。配置表结构、Excel、导表脚本和 GameConfig/ 数据优先使用 luban-dev，再使用 dgame-dev 处理运行时消费。

核心约束

1. 分层落位：框架运行时放 Assets/DGame/Runtime；编辑器工具放 Assets/DGame/Editor；热更业务放 Assets/Scripts/HotFix/GameLogic；配置生成代码放 Assets/Scripts/HotFix/GameProto。
2. 优先复用 DGame 封装：新增服务前先确认 GameModule、DGame/Runtime/Module 和 GameLogic/Module 是否已有封装。
3. 模块访问：业务层通过 GameLogic.GameModule.XXX 访问模块，不在业务层散落 ModuleSystem.GetModule<T>()。
4. 异步优先：IO、资源、场景等耗时操作优先使用 UniTask，不要新增 Coroutine 工作流。
5. 资源必须释放：普通资源加载与 UnloadAsset 成对；实例化 GameObject 由实例销毁触发资源引用回收。
6. 事件解耦：UI 内监听用 AddUIEvent；跨模块事件用 GameEvent 或 [EventInterface(EEventGroup...)]。
7. 生成产物不手改：Luban 的 GameProto/LubanConfig、事件和模块 Source Generator 产物应修改源定义后重新生成。
8. 资源文件边界：不直接编辑 Scene/Prefab YAML、GUID 或 .meta 文件来替代 Unity 资源数据库操作；新增源文件的 .meta 由 Unity 生成。
9. 工程绑定：Unity CLI、Editor、Player 和资源验证必须绑定当前 DGame/GameUnity 的规范化绝对路径，不使用其他 Unity 工程结果替代。
10. 敏感信息：Pipeline 实例描述文件和运行时响应中的鉴权信息不得写入日志、报告或提交内容。

验证入口

日常验证使用 Pipeline 0.10 分组命令：CLI 为 editor status、script recompile / script recompile_status、test list、test run / test status；MCP 对应 editor_status、script_recompile / script_recompile_status、test_list、test_run / test_status。具体参数见 操作规程。源码与程序集变更取得当前 Editor 编译证据；测试按影响范围选择模式和筛选器。

需要离线检查、组合验证或 CI 报告时，从仓库根目录执行以下可选入口：

python .agents/scripts/workflow.py doctor
python .agents/scripts/workflow.py check
python .agents/scripts/workflow.py verify --profile docs
python .agents/scripts/workflow.py verify --profile code
python .agents/scripts/workflow.py verify --profile unity --test-filter GameLogic
python .agents/scripts/workflow.py verify --profile full

MCP、直接 CLI 与 Workflow 的 Unity 操作串行执行；新操作前核对本工程状态，状态轮询允许观察忙操作。Workflow 内的 Editor 阶段使用工程锁，直接工具调用不经过该锁；不得并行启动另一条导入、编译、测试或写入。docs/code 离线检查和解决方案构建是否纳入锁范围，以 .agents/scripts/workflow.py 的实现为准。 Editor 断开、目标不唯一、筛选器没有可运行用例或测试结果不完整时，必须保持 blocked/failed；Editor 忙时等待并查询对应状态，不重发起始命令，不能使用旧结果或其他工程结果替代。

冲突与文档维护

满足以下任一条件时，应在本次回答中反馈问题：

• reference 文档与当前源码 API、路径或签名不一致。
• 生成代码失败的根因来自过期文档或错误模式。
• 用户明确指出 DGame skill 或 AGENTS.md 描述不准确。

当 reference 与源码 API、路径或签名冲突时：

1. 用 rg 搜索实际实现和调用点。
2. 优先信任当前源码。
3. 在回复中记录问题现象、文档位置、正确事实和修正建议；维护 skill 时直接修正 ../.agents/skills/dgame-dev/references/ 对应文档。

只改与任务直接相关的文件；生成或修改 UI、资源、事件和配置消费代码前，先确认当前 DGame API；能验证就验证，不能验证时说明限制。