Prg_ZhangXuheng
/
NLDClient-yudde
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NLDClient-yudde/AGENTS.md

10 KiB
Raw Blame History

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