| name | luban-dev |
| description | Luban 游戏配置全栈工具，支持枚举/Bean/数据表的增删改查、代码生成、TEngine 集成。触发场景：(1) 编辑游戏配置数据（配置表/数据表/道具表/技能表/奖励表/活动表），(2) 新增/修改/删除配置表结构，(3) 定义枚举/Bean/字段，(4) 导表/生成配置代码，(5) 编写 luban.conf 或 Schema 定义，(6) Luban 类型系统/校验器问题。即使用户未明确说"Luban"，只要是编辑游戏配置数据，也应使用此技能。 |
Luban 数据配置工具
TEngine 项目核心约定
- 生成格式：
cs-bin（C# 代码）+ bin（二进制数据）
- 命名空间：
GameConfig（非默认 cfg）
- 数据加载：
ConfigSystem.Instance.Tables 懒加载，底层走 YooAsset
- 代码位置：
GameScripts/HotFix/GameProto/GameConfig/（热更程序集）
- 数据位置：
AssetRaw/Configs/bytes/（YooAsset 管理）
- 表定义：Excel（
__tables__.xlsx/__beans__.xlsx/__enums__.xlsx）+ XML Schema（Defines/）
- 导出数据 → 使用导出脚本，不要手动拼 dotnet 命令
导出脚本
所有脚本位于 Configs/GameConfig/，使用相对路径调用。
| 脚本 | 用途 | 说明 |
|---|
gen_code_bin_to_project_lazyload | 客户端（推荐，懒加载模板） | AI 调用此脚本 |
gen_code_bin_to_project | 客户端（标准模板） | 非懒加载 |
gen_code_bin_to_server | 服务端 | - |
AI 调用导表命令
根据操作系统选择对应扩展名：
Windows：
cmd //c "set AI_MODE=1 && Configs/GameConfig/gen_code_bin_to_project_lazyload.bat"
macOS/Linux：
bash Configs/GameConfig/gen_code_bin_to_project_lazyload.sh
新增配置表流程
- 在
Datas/__tables__.xlsx 注册新表（或使用 # 前缀自动导入）
- 创建
Datas/xxx.xlsx 数据表
- 在
__beans__.xlsx / __enums__.xlsx 定义复合类型/枚举（可选）
- 运行导出脚本生成代码和数据
- 在
GameLogic/Config/ 封装 XxxConfigMgr
配置管理红线
- 不要直接修改
GameProto/GameConfig/ 下的生成代码
- 复杂模块封装
XxxConfigMgr，业务代码通过管理器访问
- 新增字段前向兼容，删除/改名字段不兼容
配置表操作工具（luban_helper.py）
通过 Python 脚本直接 CRUD Excel 配置表，无需手动编辑 xlsx。
前置条件
Python 3.8+，pip install openpyxl
执行方式
python scripts/luban_helper.py <command> --data-dir Configs/GameConfig/Datas
PowerShell 中用 ; 分隔命令，JSON 参数推荐用 --file 从文件读取。
命令速查
| 分类 | 命令 | 功能 |
|---|
| 枚举 | enum list/get/add/update/delete | 枚举 CRUD |
| 结构 | bean list/get/add/update/delete | Bean CRUD |
| 表 | table list/get/add/update/delete | 表 CRUD |
| 字段 | field list/add/update/delete/disable/enable | 字段操作 |
| 数据 | row list/get/query/add/update/delete | 数据行操作 |
| 批量 | batch fields/rows | 批量操作 |
| 导入导出 | export/import | JSON 导入导出 |
| 验证 | validate / ref | 数据验证 / 引用检查 |
| 类型 | type list/validate/suggest/search/guide/info | 类型系统 |
| 自动 | auto list/create | 自动导入表 |
| 管理 | rename/copy/diff/template | 表管理工具 |
操作规范
- 只读操作（list/get/query/search）：直接执行
- 写入操作（add/update/delete）：必须确认后再执行
- 删除操作：先
ref 检查引用，提醒风险，二次确认
- 修改前：先
table get / field list 确认结构，row get 避免主键冲突
- 修改后：用
validate 验证
分组自动推断
添加字段时不指定 --group，自动推断：
c（客户端）：name, desc, icon, image, model, effect, sound, ui 等s（服务器）：server, logic, damage, hp, mp, exp, level, rate 等cs（两端）：id, 其他无法判断的字段
参考文档（按需加载）
示例：examples/tengine-project/（TEngine 完整示例）、examples/item-system/（CSV+XML）、examples/skill-system/（JSON+多态）
脚本：scripts/luban_helper.py（操作工具）、scripts/requirements.txt（依赖）
官方文档：https://www.datable.cn/docs/intro
