NLDClient-yudde/AGENTS.md

AGENTS.md

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

重要

• 使用中文进行交流
• 有疑问或者不确定的地方，必须先和用户确认，不要自行决定
• 如果用户的需求有冲突, 明确的告诉用户冲突点并提供建议，不要自行决定
• 如果现有代码或设计有不合理的地方, 明确的告诉用户并提供建议，不要直接修改
• 当任务结束时发现有建设性的意见可以提醒用户
  • 比如有什么通用要求可以写进 指导文档 (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（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/	队伍编辑/派遣/战斗编队

项目记忆

• 在.ai/memory/ 目录下，每个文件对应一个记忆条目，文件名为记忆条目的标题，内容为记忆条目的详细信息
• 在.ai/memory/summary.md 文件中，记录所有记忆条目的标题和简要描述，方便快速浏览和查找
• 记忆条目可以包含项目的设计决策、代码规范、已知问题、解决方案等重要信息
• 在修改代码或设计时，应该参考相关的记忆条目，确保不违反之前的设计决策或规范
• 如果发现新的设计决策、代码规范、已知问题或解决方案，应该及时创建新的记忆条目，或者更新已有的记忆条目，以保持项目记忆的完整和准确