| name | luban-dev |
| description | DGame Luban 游戏配置全栈工具，支持枚举/Bean/数据表/字段/数据行的增删改查、配置校验、引用检查、导表脚本调用、ConfigMgr 封装与运行时消费链路排查。触发场景：(1) 编辑 GameConfig/Datas 下的游戏配置数据（道具表、文本表、模型表、音效表、特效表、GM 表等），(2) 新增/修改/删除配置表结构、字段、枚举或 Bean，(3) 处理 __tables__.xlsx/__beans__.xlsx/__enums__.xlsx、# 自动导入表或 DGame Sheet 拆表规则，(4) 修改 luban.conf、Defines、CustomTemplate 或 GenerateTool_Binary 导表脚本，(5) 生成/校验客户端 GameProto 配置代码和二进制配置数据，(6) 排查 ConfigSystem、Tables、GameLogic/ConfigMgr 配置访问问题。即使用户未明确说 “Luban”，只要是在编辑或排查游戏配置数据，也应使用此技能。 |
DGame Luban 配置开发
核心约定
- 源头：
GameConfig/Datas/、GameConfig/Defines/、GameConfig/CustomTemplate/，不要手改生成产物。
- 默认生成：客户端
cs-bin 代码 + bin/json 数据，优先走 LazyLoad。
- 默认脚本：
GameConfig/GenerateTool_Binary/gen_bin_client_lazyload.bat。
- 代码输出：
GameUnity/Assets/Scripts/HotFix/GameProto/LubanConfig/。
- 桥接文件：
ConfigSystem.cs、ExternalTypeUtil.cs 由模板复制到 GameUnity/Assets/Scripts/HotFix/GameProto/。
- 数据输出：二进制到
GameUnity/Assets/BundleAssets/Configs/Binary/；Json 路径以 GenerateTool_Binary/path_define.* 当前配置为准。
- 命名空间/顶层模块：
GameProto；总表管理器：Tables。
- 业务访问：优先在
GameUnity/Assets/Scripts/HotFix/GameLogic/ConfigMgr/ 封装 XxxConfigMgr，不要把 TbXXX 访问散落到业务层。
导出脚本
所有脚本位于 GameConfig/GenerateTool_Binary/，使用相对路径调用。
| 脚本 | 用途 | 说明 |
|---|
gen_bin_client_lazyload | 客户端（推荐，LazyLoad 模板） | AI 默认调用此脚本 |
gen_bin_client | 客户端（标准模板） | 非懒加载 |
gen_bin_server_lazyload | 服务端（LazyLoad 模板） | 需要服务端配置时使用 |
gen_bin_server | 服务端（标准模板） | 非懒加载 |
gen_bin_all_lazyload | 客户端 + 服务端（LazyLoad 模板） | 一键导出两端 |
gen_bin_all | 客户端 + 服务端（标准模板） | 一键导出两端，非懒加载 |
AI 调用导表命令
根据操作系统选择对应扩展名。默认只导客户端 LazyLoad：
Windows：
cmd /c "set AI_MODE=1 && GameConfig\GenerateTool_Binary\gen_bin_client_lazyload.bat"
macOS/Linux：
bash GameConfig/GenerateTool_Binary/gen_bin_client_lazyload.sh
默认工作流
- 先判断改动属于数据、表结构、Bean/Enum、schema、模板、导表脚本还是运行时消费。
- 读现有定义：
__tables__.xlsx、__beans__.xlsx、__enums__.xlsx、目标业务表和相关 ConfigMgr。
- 改源文件，不改
LubanConfig/ 下生成代码。
- 运行或提示运行默认导表脚本。
- 验证生成目录、Unity 编译、
ConfigSystem.Instance.Tables 访问和业务管理器封装。
新增配置表
- 在
GameConfig/Datas/ 新增业务 Excel，前四行固定为 ##var、##type、##group、##。
- 需要复合字段时补
__beans__.xlsx，需要枚举时补 __enums__.xlsx。
- 默认推荐在
__tables__.xlsx 显式注册 full_name、value_type、input、mode、tags。
- Luban 支持文件名
#<value_type>-<comment>.xlsx 自动导入，不需要在 __tables__.xlsx 注册；DGame 可用但不作为默认推荐。
- DGame 扩展支持 Sheet 名
#<value_type>-<comment> 自动拆表；导表前会拆成临时 # 文件，同样不需要注册，但仍按自动导入场景谨慎使用。
- 需要按字段分组访问时，优先在
__tables__.xlsx 的 tags 写 group_by:字段名；自动导入表如需特殊 tags，先确认当前 Luban 支持方式。
- 单例配置可用
mode=one。
- 导表后在
GameLogic/ConfigMgr/ 补 XxxConfigMgr。
业务层常用访问：
using GameLogic;
var modelCfg = ModelConfigMgr.Instance.GetOrDefault(modelId);
var hasModel = ModelConfigMgr.Instance.ContainsKey(modelId);
var ok = SoundConfigMgr.Instance.TryGetValue(soundId, out var soundCfg);
只有在 XxxConfigMgr 内部封装时才直接碰 TbXXX：
using GameProto;
public ModelConfig GetOrDefault(int modelID) => TbModelConfig.GetOrDefault(modelID);
操作工具
可用 scripts/luban_helper.py 读写 Excel 配置，适合批量增删字段、查引用、校验数据。
前置条件
Python 3.8+，pip install -r .claude/skills/luban-dev/scripts/requirements.txt
执行方式
python .claude/skills/luban-dev/scripts/luban_helper.py --data-dir GameConfig/Datas <command>
--data-dir 默认就是 GameConfig/Datas，可省略；PowerShell 中 JSON 参数推荐用 --file 从文件读取。
参数类型：位置参数直接传值，不加 -- 前缀。例如 table get TbItemConfig，不是 table get --name TbItemConfig。
命令速查
| 分类 | 命令 | 功能 |
|---|
| 枚举 | enum list/get/add/update/delete | 枚举 CRUD |
| 结构 | bean list/get/add/update/delete | Bean CRUD |
| 表 | table list/get/add/update/delete | 表 CRUD；默认显式注册到 __tables__.xlsx |
| 字段 | 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 | # 自动导入表；DGame 支持但不默认推荐 |
| 管理 | rename/copy/diff/template | 表管理工具 |
| 附加 | alias/tag/variant/multirow/cache | 常量别名、标签、字段变体、多行结构、缓存 |
操作规范
- 只读操作（
list/get/query/search/validate/ref/diff）：可直接执行。
- 写入操作（
add/update/delete/import/rename/copy/template/create）：先确认目标表、字段、Sheet 和影响面。
- 删除操作：先跑
ref 检查引用，提醒兼容性风险，再二次确认。
- 修改前：先
table get / field list 确认结构，row get 避免主键冲突。
- 修改后：跑
validate --all，再运行 DGame 导表脚本。
- 自动导入：Luban 支持
# 文件，DGame 支持 # Sheet 拆表，但默认仍推荐 __tables__.xlsx 显式注册。
- 迁移自动导入：
migrate-auto 在 DGame 版本中保留命令入口但禁止执行，避免把推荐的显式注册表误迁移。
分组自动推断
添加字段时不指定 --group，脚本会按字段名和类型做保守推断：
c（客户端）：name、desc、icon、image、sprite、model、spine、effect、sound、audio、ui、location、path、prefab、asset、local 等。s（服务端）：server、backend、logic、damage、hp、mp、exp、level、rate、attack、defense、platform、channel 等。cs（两端）：id、*_id、无法明确归属的字段。
这是辅助推断，不是架构决策；关键配置仍以目标表现有 ##group 和需求为准。
红线
- 不直接改
GameUnity/Assets/Scripts/HotFix/GameProto/LubanConfig/。
- 字段改名、删字段、改类型要当作兼容性风险处理。
- 资源加载链路以当前
ConfigSystem 和 DGame 资源模块为准；若文档和代码冲突，优先信任代码。
- 配置表运行时中文文本仍遵守项目文本规范，不把玩家可见文本硬编码进业务代码。
按需参考
示例：DGame 当前不额外内置 examples/，以真实项目 GameConfig/Datas/、GameConfig/Defines/、GameConfig/CustomTemplate/、GameConfig/GenerateTool_Binary/ 作为示例来源。
脚本：scripts/luban_helper.py（DGame 化配置表操作工具）、scripts/requirements.txt（依赖）。
官方文档：https://www.datable.cn/docs/intro
