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

必读顺序

1. 先读 .agents/skills/tyou-dev/references/luban-config.md。
2. 再查 Design/tools/genBin.bat、Design/tools/Defines/ 和实际配置加载代码。
3. 涉及业务访问方式时，用 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。写入前先确认源表、字段定义、引用关系和导表验证；删除、重命名、改类型或主键必须按 Deep 说明影响并得到确认。

常用只读命令：

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 或导表脚本。

执行方式

分类与确认统一按 sdd-explore/references/alignment-contract.md，本 skill 不另定门槛。提供字段/schema、消费者、生成位置、兼容性和回滚事实；沿用已有授权，不因跨表或多文件重复确认。

操作红线

• 不直接修改 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

在 Design/tools 工作目录启动 genBin.bat，其相对路径依赖该 CWD，末尾 pause 需要 stdin/交互处理。自动调用须捕获 dotnet/Luban 错误和产物差异，不能仅把最后一条命令退出码当作导表成功。不要从仓库根直接按相对脚本路径运行，也不要为自动化临时重写生成器。

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

validate

验证顺序：

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

推荐节奏

1. 明确目标：结构变更、数据变更、访问封装，还是导表问题。
2. 查源码和现有配置，确认真实路径与命名。
3. 对删除/重命名/类型变更做引用检查。
4. 修改源表或 schema。
5. 运行现有导表脚本。
6. 验证生成结果和业务访问代码。
7. 记录实际导表与验证结果；可复发坑才写入 .codex/memory/ Project Knowledge。