# 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`；运动状态只通过项目接口通知相机。
- 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` 只允许作为插件内部依赖、示例资产参考或薄适配层依赖；项目玩法层尽可能不用。
- 相机状态由项目级接口接收输入、运动和战斗状态，不允许业务代码到处直接耦合多个相机系统。

## 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。