# AGENTS.md

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

## 项目技术栈

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

## 核心目录速览

```
ProjectNLD/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` | 用户明确要求编译 DLL 时使用；修改 `GamePlay/` 后只提醒用户需要编译 |
| `luban-config` | 涉及配置表的新增/修改，或需要理解 Luban 配置结构 |
| `ui-prefab-dev` | 开发 UI 预制体、UI 界面相关功能 |
| `knowledge-base` | 查询已知的最佳实践、性能优化案例、架构决策记录 |

## Excel 操作 (MCP)

本项目集成了 [excel-mcp-server](https://github.com/haris-musa/excel-mcp-server)（v0.1.8），通过 `opencode.jsonc` 中配置的 `excel` MCP 提供 Excel 文件读写能力，无需安装 Microsoft Excel。

### 何时使用

| 场景 | 说明 |
|------|------|
| 读取 Luban 配置表 | 读取 `NLDMisc` 仓库中的 `.xlsx` 配置数据，定位数值问题 |
| 修改 Luban 配置表 | 新增/修改配置行、调整数值字段 |
| 配合 luban-config skill | 操作配置表时优先使用 `luban-config` skill 了解配置结构，再用 Excel MCP 工具读写数据 |

### 可用工具速查

| 工具 | 用途 |
|------|------|
| `get_workbook_metadata` | 获取工作簿元数据（工作表列表、行列范围） |
| `read_data_from_excel` | 从指定工作表读取数据，支持起止单元格范围 |
| `write_data_to_excel` | 向指定工作表写入数据（支持从任意起始单元格开始） |
| `apply_formula` | 向单元格应用 Excel 公式 |
| `validate_formula_syntax` | 校验公式语法（不实际写入） |
| `format_range` | 设置单元格范围格式（字体、颜色、边框、对齐等） |
| `create_worksheet` / `delete_worksheet` / `rename_worksheet` | 工作表增删改 |
| `copy_worksheet` | 复制整个工作表 |
| `insert_rows` / `insert_columns` | 插入行/列 |
| `delete_sheet_rows` / `delete_sheet_columns` | 删除行/列 |
| `create_table` | 创建 Excel 表格 |
| `create_chart` | 创建图表（折线图、柱状图、饼图等） |
| `create_pivot_table` | 创建数据透视表 |
| `copy_range` / `delete_range` | 范围复制/删除 |
| `merge_cells` / `unmerge_cells` | 合并/取消合并单元格 |

### 任务提示

```
操作配置表时使用 excel 工具。首先用 get_workbook_metadata 了解工作表结构，
再用 read_data_from_excel 读取数据，修改后用 write_data_to_excel 写回。
路径指向 ../NLDMisc/ 下的 .xlsx 文件。
```

## 编码要求

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

### 行为约束
- 默认不要手动生成 Unity `.meta` 文件；若新建场景/Prefab/脚本等资产需要稳定 GUID 引用，可以同步生成对应 `.meta`，并确保 GUID 唯一
- 不要主动编译项目（Unity 自动编译；可以做静态代码检查）
- 图片资源处理时可自主决定是否查看图片内容，以获取尺寸、颜色、布局等信息

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

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

### 文件落位约定
新建代码时按以下规则选择落位路径：

| 代码类型 | 落位路径 |
|---------|---------|
| 战斗/技能/Buff/AI/角色 | `ProjectNLD/Assets/Code/Scripts/GamePlay/<模块>/` |
| UI 逻辑（GamePlay 相关） | `ProjectNLD/Assets/Code/Scripts/GamePlay/UI/` |
| UI 框架层 | `ProjectNLD/Assets/Code/Scripts/UI/` |
| 底层框架/工具 | `ProjectNLD/Assets/Code/Scripts/Framework/` |
| 编辑器扩展 | `ProjectNLD/Assets/PhxhSDK/Editor/` |
| 热更新相关 | `ProjectNLD/Assets/Code/Scripts/HotUpdate/` |

- 不确定归属时优先询问用户
- 不要修改 `GenCode/` 下 Luban 自动生成的文件

### 性能黄金法则（热路径必查）
以下规则在 `Update`、`LateUpdate`、`FixedUpdate` 及高频回调中强制要求：

| 禁止 | 替代方案 |
|------|---------|
| `GameObject.Find` / `FindObjectOfType` | 预先缓存引用或通过 Manager 注册 |
| `GetComponent`（每帧调用） | `Awake`/`Start` 中缓存 |
| `foreach` 遍历集合 | `for (int i = 0; i < list.Count; i++)` |
| LINQ（`.Where` `.First` `.ToArray`） | 手动循环或提前缓存结果 |
| lambda / 闭包 | 提取为实例方法或静态方法 |
| 字符串拼接（`+` 或 `$`） | `StringBuilder`（非每帧可酌情 `$`） |
| 装箱拆箱 | 避免 `object` 类型转换，使用泛型 |
| `Instantiate` / `Destroy` | 对象池复用 |

- 声明 `List`/`Dictionary`/`HashSet` 时预分配 `capacity`
- 事件订阅必须在 `OnDestroy`/`OnDisable` 中取消

### 常见反模式（Agent 容易犯的错）

- ❌ 在 GamePlay 代码中直接引用 `Framework` 层类型（架构越界）
- ❌ 修改 `Assets/Code/Scripts/GenCode/` 下 Luban 自动生成的文件
- ❌ 在非主线程访问 Unity API（`Transform`、`GameObject` 等）
- ❌ 忘记在 `OnDestroy`/`OnDisable` 中取消事件订阅 → 内存泄漏
- ❌ 在 `while` 循环中无 yield 导致主线程卡死
- ❌ 协程启动后未管理生命周期（对象销毁后协程继续执行）
- ❌ 对 Unity 资源使用 `new` 构造（应使用 `Instantiate` 或 `ScriptableObject.CreateInstance`）

### HybridCLR 约束
GamePlay 代码编译为独立 DLL，受以下限制：

- **禁止** `System.Reflection.Emit` 相关 API
- 不能依赖主工程中的非 AOT 类型
- 新增外部库需检查 AOT 兼容性
- 不要在 GamePlay 代码中引用 `Assembly-CSharp` 中的类型（除非已做 AOT 预留）
- 使用 `ForceAOT.csproj` / `ScriptsAOT.csproj` 做 AOT 预留注册
- 修改 GamePlay 代码后提醒用户需要通过 Unity 菜单编译生成 DLL；不要主动编译，除非用户明确要求 → 用户要求编译时读取 `compile-gameplay-dll` 技能

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

## 项目仓库结构

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

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

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

## GamePlay 模块速查

`ProjectNLD/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/` | 队伍编辑/派遣/战斗编队 |