unity/AGENTS.md

项目协作约定

本文件适用于仓库及其子目录。默认用中文交流，按现有方案完成常规实现；涉及玩法方向、平台、存档格式等重大决策时向用户确认。用户已经授权的操作持续有效。

工程与工作入口

• 项目为 IRONSPORE：Windows PC 键鼠机甲搜打撤原型，含越肩和第一人称、配装、局内改装及中英双语。
• 使用 ProjectSettings/ProjectVersion.txt 指定的 Unity 版本，当前为 6000.6.8f1。依赖版本以 Packages/manifest.json 和锁定文件为准。
• 开始相关工作前按需阅读 README、玩法设计、实施计划 和 文件规范。沿用现有结构，避免无关重构。

Unity 与 Blender

• 引擎操作使用 Unity MCP。场景、组件、预制体、导入设置和构建修改前，回读目标工程的完整路径、活动场景与编辑器状态；操作后检查保存结果及 Console。
• 多实例操作明确绑定准确的 Name@hash，逐次核对完整工程路径，不以项目名或路径前缀推断目标。不同目录分别维护缓存和 MCP 会话。
• C#、USS、JSON、工具脚本和文档可以通过文件工具修改。运行时代码修改后，通过 Unity MCP 刷新并等到编译与域重载结束，再测试或构建。现有桥接入口为 Tools/Unity/McpClient.py。
• 3D 建模、修整、导出使用 Blender MCP。先读当前文件、场景和对象；在任务自己的场景或集合中操作，保留已有未参与任务的内容。
• Blender 源文件保存在 SourceAssets/Blender/，导出模型进入 Assets/Game/Art/Models/。尺寸以米为单位，核对朝向、碰撞和武器/驾驶舱挂点。
• 不通过重建全部原型场景来完成局部修改；编辑器生成工具只在任务明确需要时运行。

文件、资源与数据

• 源码按功能放入 Assets/Game/Scripts/，配置放入 Assets/Game/Data/，场景放入 Assets/Scenes/，UI 和本地化沿用各自现有目录。
• Unity 资产与对应 .meta 一起维护，保留 GUID。已导入资产的移动或重命名通过 Unity MCP 完成并检查引用。
• 允许从公开网站下载免费的模型、声音、字体或代码。核实具体许可，保留原件、作者、版本/日期及 SHA-256，在 素材台账 登记；许可原文放入 Docs/Production/Licenses/，发布包附必要署名。
• 下载原件放入 SourceAssets/ThirdParty/<发行方>/<资源包>/，Unity 导入物放入 Assets/ThirdParty/ 对应目录；项目适配代码和派生资源使用项目自身目录。
• 翻译使用稳定文本键和完整句式参数，保留物品 ID、蓝图 ID、存档字段及回收事件编号。已有通知和结算也应随语言切换刷新。
• 存档、回收去重与写入失败处理属于核心行为；修改时保留现有版本兼容，并验证状态没有重复结算。

本地资源目录与版本控制

• workTree/、worktrees/、.worktrees/ 和 tree1/、tree2/、tree3/ 是本地工作区或资源副本目录，排除在主仓库提交及云端推送之外。不要使用强制添加将其纳入 Git。
• 已初始化的 tree 资源副本尚无独立分支或 worktree 注册。运行前核对目录内的 WorkspaceInfo.json 和实际路径；移动后的旧清单不能作为正确连接目标的依据。
• 并行运行前分别隔离测试存档与 PlayerPrefs，并为各目录完成 Unity 导入和 MCP 实例绑定。资源复制通过不等于编译、运行或性能验收通过。
• 分支、worktree 的创建和合并按用户明确要求执行。推送前检查暂存区、完整待推送路径及远程状态，使用正常推送，不擅自强制覆盖远程历史。
• 维护忽略规则：不提交 Library、Temp、Logs、Builds、UserSettings、IDE 缓存、生成的工程文件或凭据。已整理的 Docs/QA 验收摘要、测试结果及截图可以提交。
• 仓库地址通过 Git remote 管理。密码、令牌和带凭据的 URL 不写入本文件、源码、提交说明或可上传的日志。

验证与交付

• 根据实际修改选择必要检查。纯文档或 Git 配置变更检查链接、暂存范围与忽略规则；玩法、存档和本地化修改运行相关测试，修复失败后再继续。
• 当前自动化测试在 Assets/Tests/EditMode/，Unity MCP 测试命令在 Tools/Unity/Commands/Tests.json，结果通过对应 job 查询到完成。
• UI 变更核对实际分辨率、文本溢出、中文字符和鼠标/键盘交互。Windows 构建通过 MCP 发起并轮询到结束，启动完整产物目录验证实际行为。
• QA 记录放入 Docs/QA/<阶段>/，构建产物放入 Builds/Windows/x64/。明确区分静态检查、编辑器测试和独立程序实测，仅记录实际完成的验证。
• 60 FPS 与完整出击节奏为验收目标，不以未测量的推断代替结果。并行开发后的性能采样在单独运行的测试实例中进行。