PHY/AGENTS.md

PHY Codex 工作协议

项目原则

• 项目以 C++ 和配置文件为主要实现手段，优先级固定为：C++ > 项目配置文件 > DataAsset > 蓝图/编辑器装配。
• 只有插件强制要求、动画/UI 资产装配、或无法用 C++/配置表达时，才允许使用蓝图或 DataAsset；使用时必须在交付说明里写明原因。
• 项目按多人优先设计：战斗、交互、背包、效果触发默认考虑 Server authority、复制、预测或回滚风险。
• 首期平台目标为 Win64 / UE 5.7。AuroraDevs_UGC 当前只声明 Win64，因此不要承诺其他平台可用。
• Marketplace 插件源码只允许读取和适配，不直接修改 Engine 下的插件文件。
• Git 远程仓库固定为 https://git.codable.cn/cit110/PHY.git。
• Content 目录只管理 Content/AGame 及其子文件；Content/Collections、Content/Developers 等其他目录默认不纳入版本控制。
• 每次完成修改并通过对应验证后，必须提交并推送到 origin；如果远程认证或冲突阻塞推送，必须在最终汇报中说明。

插件源码位置

• Generic Combat System：D:\ue\UE_5.7\Engine\Plugins\Marketplace\GenericCd51b9e2c8181V4
  • Runtime 模块：GenericInputSystem、GenericGameplayAbilities、GenericGameplayAttributes、GenericCombatSystem
• Generic Game System：D:\ue\UE_5.7\Engine\Plugins\Marketplace\GenericG08270e38e585V5
  • Runtime 模块：GenericEffectsSystem、GenericCameraSystem、GenericUISystem、GenericGameSystem
• Generic Inventory System：D:\ue\UE_5.7\Engine\Plugins\Marketplace\GenericI359982083d7bV3
  • Runtime 模块：GenericInventorySystem
• Smooth Locomotion System：D:\ue\UE_5.7\Engine\Plugins\Marketplace\SmoothLo6fa0c61bf7bdV5
  • Runtime 模块：SLSCore、SmoothLocomotionSystem、TraversalSystem、FootStepSystem、SLSIntegration、SLSCameraModeSystem 等
• Ultimate Gameplay Camera：D:\ue\UE_5.7\Engine\Plugins\Marketplace\Ultimate683e2e68927aV34
  • Runtime 模块：AuroraDevs_UGC

Agent 职责和汇报链

• 总架构/协调 Agent 是唯一总负责人，直接向用户汇报；所有专家向它汇报。它负责接口边界、任务拆分、跨系统决策、合并顺序、是否允许使用蓝图/DataAsset。
• 相机专家向总架构汇报。主责 AuroraDevs_UGC、战斗锁定/瞄准/移动相机状态；不得主动引入 GenericCameraSystem 或 SLSCameraModeSystem 作为玩法层依赖。
• 战斗/GAS 专家向总架构汇报。主责 ASC、Ability、Attribute、GameplayTag、GameplayCue、伤害、复制、预测。
• 输入专家向总架构汇报。主责 GenericInputSystem、EnhancedInput、输入到 GAS/UGC/运动/UI 的路由。
• 运动专家向总架构汇报。主责 SmoothLocomotionSystem、SLSCore、TraversalSystem、SLSIntegration、FootStepSystem；USLSIntegrationComponent 允许由运动专家集中接入，禁止其它系统散落依赖；运动状态只通过项目接口通知相机。
• UI 专家向总架构汇报。主责 GenericUISystem、CommonUI、UMG、HUD、输入模式切换。
• 背包专家向总架构汇报。主责 GenericInventorySystem、物品、装备、拾取、战斗/UI 联动。
• 交互/效果专家向总架构汇报。主责 GenericGameSystem、GenericEffectsSystem、SmartObjects、TargetingSystem、Niagara。
• 验证 Agent 向总架构汇报，但拥有阻断权；构建、测试、多人验证失败时不得合并。
• Git/仓库 Agent 向总架构汇报；只在验证通过后处理提交、分支、LFS、忽略规则。

工作流

• 用户需求先交给总架构 Agent；总架构拆成单系统任务或跨系统任务，并指定唯一 owner。
• 专家进入实现前先读项目源码、配置和对应插件源码；不得直接修改 Engine Marketplace 插件源码。
• 专家方案必须说明 C++ 接口、配置文件、是否需要蓝图/DataAsset、多人影响、依赖模块。
• 单系统任务由 owner 完成；跨系统任务由总架构先定接口，再分派给对应专家，避免互相改同一批文件。
• 专家交付必须包含：改动范围、新增/修改接口、配置文件、蓝图/DataAsset 使用原因、验证结果、遗留风险。
• 验证 Agent 通过构建和必要测试后，Git/仓库 Agent 才能提交；总架构最终向用户汇报结果。
• Git/仓库 Agent 初始化仓库时必须设置 origin=https://git.codable.cn/cit110/PHY.git，启用 Git LFS，并确认 Content 跟踪范围仅限 Content/AGame/**。
• Git/仓库 Agent 在每次修改完成后负责提交并推送当前改动，不保留已完成但未提交的工作树。
• 相机/输入/运动/战斗之间的接口冲突、是否使用蓝图/DataAsset、是否引入插件模块依赖，统一由总架构裁决。

相机规则

• 项目相机主入口统一使用 Ultimate Gameplay Camera，即 AuroraDevs_UGC。
• GenericCameraSystem 和 SLSCameraModeSystem 只允许作为插件内部依赖、示例资产参考或薄适配层依赖；项目玩法层尽可能不用。
• USLSIntegrationComponent 由运动层集中持有和暴露，不等于允许业务层直接依赖 SLSCameraModeSystem。
• 相机状态由项目级接口接收输入、运动和战斗状态，不允许业务代码到处直接耦合多个相机系统。

C++ 和配置规则

• 配置按功能拆分，不把项目自定义设置堆进一个 ini。
• 项目自有设置使用 UCLASS(Config=PHYCombat, DefaultConfig) 这类配置类，对应 Config/DefaultPHYCombat.ini。
• UE 引擎强制读取的内容仍放在标准文件中，例如 DefaultEngine.ini、DefaultInput.ini、DefaultGame.ini；项目玩法参数尽量迁移到功能专属配置类。
• 建议功能配置文件：DefaultPHYCore.ini、DefaultPHYInput.ini、DefaultPHYCombat.ini、DefaultPHYCamera.ini、DefaultPHYLocomotion.ini、DefaultPHYUI.ini、DefaultPHYInventory.ini、DefaultPHYInteraction.ini、DefaultPHYEffects.ini。
• .h 文件注释使用符合 Doxygen 风格的中文注释：公开类、结构体、枚举、函数、属性使用 /** ... */，需要时使用 @brief、@param、@return。
• .cpp 文件也使用中文注释，但不用 Doxygen 风格；避免在实现文件里写 /** ... */ 形式的 API 文档。
• 包含 *.generated.h 的头文件，其对应 .cpp 必须在包含自身头文件后使用 #include UE_INLINE_GENERATED_CPP_BY_NAME(文件基名)。
• 反射声明禁止 ClassGroup，也禁止在 meta=(...) 中写 class 分组。
• Gameplay Tags 全部使用 Native Gameplay Tags 宏，按功能域拆分到 Source/PHY/Public/GameplayTags 和 Source/PHY/Private/GameplayTags；PHYGameplayTags.h 只作为聚合入口，不直接堆放声明。
• 新增 Gameplay Tag 时按职责放入对应领域文件，例如输入、状态、能力、事件、效果；如果领域不匹配，先新增清晰命名的领域文件，不把所有 Tag 写在一个文件里。
• 核心 Tag 禁止只写在 ini、蓝图字符串或裸字符串里。

验证命令

• 基线构建： D:\ue\UE_5.7\Engine\Build\BatchFiles\Build.bat PHYEditor Win64 Development -Project="D:\ue\Projects\PHY\PHY.uproject" -WaitMutex -NoHotReloadFromIDE
• Git 验证：git status --short --branch 不应显示 Binaries、Intermediate、Saved、DerivedDataCache。
• 代码审查：检查中文注释、Doxygen 规则、UE_INLINE_GENERATED_CPP_BY_NAME、反射 metadata、Native GameplayTags。
• 相机验证：UGC 能响应移动、战斗锁定、瞄准、UI 输入模式；业务层不得新增 GenericCameraSystem / SLSCameraModeSystem 直接依赖。
• 多人验证：战斗、输入、交互、背包、效果改动至少做双客户端 PIE 或 dedicated server smoke test。