luban-dev

name: luban-dev description: Tyou Luban 配表开发专用指导。涉及新增/修改/删除配置表、Excel/Defines、Luban schema、导表、生成二进制配置、配置访问封装、字段变更安全、配置数据校验时必须使用。触发词：Luban、配表、配置表、Excel、Defines、genBin、导表、Tb、Config、配置数据、字段、枚举、Bean。

Tyou Luban 配表指导

本 skill 只处理 Tyou 的 Luban 配表工作。框架与业务参考仍以源码和 .agents/skills/tyou-dev/references/luban-config.md 为准。

当前项目路径

配表源：Design/config/*.xlsx
表/Bean/Enum 定义：Design/config/__tables__.xlsx、Design/config/__beans__.xlsx、Design/config/__enums__.xlsx
内置定义：Design/tools/Defines/builtin.xml
Luban 配置：Design/tools/luban.conf
导表脚本：Design/tools/genBin.bat
生成数据：Client/assets/asset-raw/config/game/*.bin
生成代码：Client/assets/scripts/proto/config/bin/schema.ts
运行时加载：Client/assets/ty-framework/module/table/TableModule.ts

必读顺序

先读 .agents/skills/tyou-dev/references/luban-config.md。
再查 Design/tools/genBin.bat、Design/tools/Defines/ 和实际配置加载代码。
涉及业务访问方式时，用 rg "tyou.table" 和 rg "Tb" 查现有调用。

快速扫描

处理配表问题前，优先运行只读扫描脚本：

powershell -ExecutionPolicy Bypass -File .agents/skills/luban-dev/scripts/scan-luban.ps1

扫描只检查路径、源表、生成物和运行时代码线索，不修改文件。

操作工具

Tyou 版 Luban helper：

python .agents/skills/luban-dev/scripts/luban_helper.py table list

工具默认只读；任何写 Excel 的命令必须显式传入 --write，并且必须已经进入 OpenSpec change。

常用只读命令：

python .agents/skills/luban-dev/scripts/luban_helper.py table list
python .agents/skills/luban-dev/scripts/luban_helper.py table get TableFollower
python .agents/skills/luban-dev/scripts/luban_helper.py field list TableFollower
python .agents/skills/luban-dev/scripts/luban_helper.py row query TableFollower --conditions id=1001
python .agents/skills/luban-dev/scripts/luban_helper.py validate --all
python .agents/skills/luban-dev/scripts/luban_helper.py ref TableFollower

支持范围：

table list/get/add/delete
field list/add/update/delete
row list/query/add/update/delete
enum list/get/add/update/delete
bean list/get/add/update/delete
validate
ref

写操作只面向 Design/config/#*.xlsx 自动导入表；不直接修改生成代码、.bin 或导表脚本。

OpenSpec

L1 typo 可以直接处理。
任何新增/删除/改字段、改数据、改导表流程、改生成代码位置，都属于 L2+，必须进入 OpenSpec change。

操作红线

不直接修改 Luban 生成代码和二进制产物，除非明确是重新导表生成结果。
删除字段、改字段名、改主键、改类型属于破坏性变更，必须先查引用并请求确认。
写入配置数据前先读取现有表结构和引用关系；无法确认引用时停止。
导表优先使用项目现有脚本，不手拼新的 Luban 命令。

工作模式

scan

只读确认配表链路是否完整：

Design/config/*.xlsx 是否存在。
__tables__.xlsx、__beans__.xlsx、__enums__.xlsx 是否存在。
genBin.bat、luban.conf、builtin.xml 是否存在。
schema.ts 和 .bin 是否存在。
TableModule.ts 是否仍按 config/game + BufferAsset + Tables 加载。

get

只读查看表结构、字段、枚举、Bean 和现有业务引用；不要先写 Excel。

优先使用 luban_helper.py table get、field list、row query。

ref

修改字段、删除字段、改主键、改类型、改表名之前，必须用 rg 查：

生成类名、Tb* 类名、字段名。
tyou.table.getConfig() 后的访问链。
配置表路径、bin 文件名、Bundle 名称。

同时运行 luban_helper.py ref <Name> 查生成代码、源表和业务引用。

apply

只修改源 Excel/定义或明确要求的业务访问封装；生成代码和 .bin 只能通过 Design/tools/genBin.bat 产生。

使用 luban_helper.py 写入时必须传 --write，且删除/改名/改类型前先完成 ref。

export

导表只使用：

Design/tools/genBin.bat

导表后检查 .bin、.meta、schema.ts 的变化，并确认没有手工修改生成物。

validate

验证顺序：

检查导表命令是否成功。
检查生成数据和生成代码是否更新。
检查 TableModule.ts 加载路径是否匹配生成数据。
检查业务引用是否仍能通过 tyou.table.getConfig() 访问。
必要时运行 TypeScript/Cocos 可接受的项目校验命令。