NLDClient-yudde/ProjectNLD/AGENTS.md

AGENTS.md

最高优先级规则：执行大量代码修改之前，先和用户确认设计思路再继续执行。

项目技术栈

类别	技术	说明
引擎	Unity	C# 脚本后端
热更新	HybridCLR	GamePlay 代码编译为独立 DLL（GamePlay_Dll/GamePlay.dll），支持运行时热更新
配置表	Luban	游戏参数、数值配置的数据驱动方案，配置源位于 NLDMisc 仓库
行为树/状态机	NodeCanvas	位于 Assets/PhxhSDK/ThirdParty/ParadoxNotion/，提供 BehaviourTree、FSM、DialogueTree
编辑器	Odin Inspector	用于开发自定义 Inspector 和 EditorWindow
动画	DOTween	补间动画库
资源管理	YooAsset	资源打包、加载、热更新
物理切割	BzKovSoft	角色/物体切片系统

核心目录速览

Assets/
├── Code/Scripts/
│   ├── GamePlay/          ← 核心战斗逻辑 (75+ 模块，编译为独立 DLL)
│   ├── Framework/         ← 底层框架代码
│   ├── GameWrapper/       ← 游戏外壳/入口
│   ├── HotUpdate/         ← 热更新相关代码
│   ├── UI/                ← UI 框架层（非 GamePlay UI）
│   ├── Camera/            ← 相机系统
│   └── GenCode/           ← Luban 生成的配置表代码
├── PhxhSDK/
│   ├── Phxh/              ← 工作室自研框架
│   ├── ThirdParty/        ← 第三方库（NodeCanvas 等）
│   ├── Plugins/           ← 原生插件
│   └── Editor/            ← 编辑器工具
├── Plugins/               ← Unity 插件
└── StreamingAssets/       ← 流式资源

规则协议（Protocols）

行为规则以 .ai/protocols/ 为权威定义，包括：

• confirm-before-act.md — 大量修改前确认
• git-safety.md — Git 操作安全规范
• no-meta-files.md — Unity 项目约定（不生成 .meta、不主动编译）

技能系统与同步

• 技能定义唯一源位于 .ai/skills/，协议源位于 .ai/protocols/，Agent 定义源位于 .ai/agents/
• 通过 .ai/sync-all.sh（macOS/Linux）或 .ai/sync-all.ps1（Windows）将 skills、protocols、agents 一键同步到各平台目录（.cursor/ .claude/ .github/ .kiro/）
• 新增或更新任何技能、协议、Agent 后运行同步脚本即可

当前可用技能

技能	何时使用
batch-git-ops	任何 Git 操作（pull/push/commit/checkout），必须读取并按流程执行
compile-gameplay-dll	修改了 GamePlay/ 下任何代码后，需要编译 DLL
luban-config	涉及配置表的新增/修改，或需要理解 Luban 配置结构
ui-prefab-dev	开发 UI 预制体、UI 界面相关功能
knowledge-base	查询已知的最佳实践、性能优化案例、架构决策记录

编码要求

设计原则

• 使用面向对象的设计思路，单个文件/模块尽可能小且功能单一
• 按要求去做，不扩展额外的功能
• 遵循 C# 标准命名：类/方法 PascalCase，私有字段 _camelCase，常量 UPPER_SNAKE

行为约束

• 不要生成 Unity .meta 文件，留给 Unity 自己生成
• 不要主动编译项目（Unity 自动编译；可以做静态代码检查）
• 图片资源处理时可自主决定是否查看图片内容，以获取尺寸、颜色、布局等信息

交互协议

• 编码前将计划描述给用户并获得确认（收集信息、编写 plan 不需要确认）
• 如果有疑问主动向用户确认

编辑器开发

• 使用 Odin Inspector 开发自定义编辑器和 Inspector 面板

Git 操作

• 除非用户要求，AI 不做任何 git 提交相关操作
• 当用户让 AI 操作 git 时提醒用户 git 操作有风险
• 重要：本项目有三个关联的 Git 仓库（见下方"项目仓库结构"），任何 git 操作（pull/push/commit/checkout 等）都必须同时考虑三个仓库的同步对齐，务必读取 batch-git-ops skill 后按其流程执行

项目仓库结构

本项目包含三个独立的 Git 仓库，路径相对于 workspace 根目录（ProjectNLD）：

仓库	相对路径	定位
NLDClient	../../	游戏客户端主仓库，包含 Unity 项目配置、资源、框架代码等
NLDMisc	../../../NLDMisc	配置表相关仓库，存放游戏参数、数值配置等数据
GamePlay	Assets/Code/Scripts/GamePlay	核心游戏逻辑代码仓库，编译产物为 GamePlay_Dll/GamePlay.dll

• 执行 git 操作时必须明确区分当前操作的是哪个仓库，不要混淆仓库边界
• 查找或修改代码时注意文件属于哪个仓库，避免在错误的仓库中操作

GamePlay 模块速查

Assets/Code/Scripts/GamePlay/ 下 75+ 功能模块。完整模块索引见 .ai/agents/default.md，常用模块：

模块	路径	职责
Buff	GamePlay/Buff/	Buff 添加/移除/叠加/属性修改
Character	GamePlay/Character/	角色单位、动画、状态、属性
Fight	GamePlay/Fight/	战斗核心、伤害计算、武器、浮字
Skill	GamePlay/Skill/	技能释放/充能/状态机
UI	GamePlay/UI/	60+ UI 控制器
AI	GamePlay/AI/	AI 行为树/军团/目标选择
Level	GamePlay/Level/	关卡管理/状态/事件/引导
Net	GamePlay/Net/	网络消息/Proto/Actor
Team	GamePlay/Team/	队伍编辑/派遣/战斗编队