企业官网建设流程全解析

• 游戏开发

本篇指南面向在 TEngine 仓库中直接维护 Luban 游戏配置数据的开发者与 AI 编程代理，完整讲解luban_helper.py这一底层 Excel 编辑器的命令用法、参数约定、Excel 结构解析原理，以及如何与workflow.py导出工作流安全衔接。读完本文，你将掌握用命令行安全完成表/字段/数据行/枚举/Bean 的增删改查、引用检查、批量导入导出与校验，并学会在操作后交付 diff、校验与导出证据的完整闭环。

一、工具定位：这是"低层编辑器"，不是事务服务

luban_helper.py是 TEngine 仓库内为 AI 与开发者准备的 Luban 配置编辑器辅助脚本，源码位于 UnityProject/.codex/skills/luban-dev/scripts/luban_helper.py，其自身 docstring 即声明为"Luban 配置编辑器辅助脚本，用于 AI 操作 Luban 配置表、枚举、Bean 等"。

使用前必须明确三条边界：

1. 它是底层 CRUD 工具：脚本直接基于openpyxl读写.xlsx文件，属于"低层编辑器"，其成功输出与退出码不能当作完整业务校验。脚本开头即对 openpyxl 做了硬依赖检查，缺少时直接打印错误: 请先安装 openpyxl: pip install openpyxl并退出（源码 L28-L33），且按 SKILL.md 约定"缺少 openpyxl 时阻塞，不自动安装"。
2. 校验以真实 Luban 为准：helper 的validate_all()只做结构级诊断，无法完整解析多行 Bean 表头等语义；工作流会保留该诊断并拒绝零表，但最终依据是 Luban 在隔离目录生成的类型/引用校验结果（详见 SKILL.md）。
3. 导出入口已收口：脚本中旧gen入口已被显式禁用，gen()方法直接抛出RuntimeError（源码 L2606-L2608），生产导出统一走workflow.py工作流，详见后文"与导出工作流衔接"一节。

二、环境与命令基础约定

helper 脚本约定在Unity 项目（UnityProject/）目录下执行，数据源位于仓库Configs/GameConfig，即从 Unity 项目出发的../Configs/GameConfig，其中配置数据目录为Configs/GameConfig/Datas（对应 luban.conf 中的dataDir: "Datas"）。

先查看全部能力：

python .codex/skills/luban-dev/scripts/luban_helper.py --help

基础命令一览（均以 Unity 项目为当前目录）：

# 列出所有表 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table list # 获取某张表（按注册名） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table get <registered-name> # 列出某张表的字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field list <registered-name> # 查询某个 Bean / 枚举被哪些位置引用 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas ref <bean-or-enum>

四条必须遵守的参数约定：

• --data-dir必须在子命令之前（如上面示例所示）；table/field/row等的名称是位置参数，不要随意调换顺序。
• 写入类操作之前先读对应子命令的--help，以脚本真实参数为准，不要照抄或猜测参数名。
• 复杂 JSON 一律用命令支持的--file从文件读取，不要手拼 PowerShell 转义（脚本在 Windows 下会强制重开 stdout/stderr 为 UTF-8 编码以兼容中文输出，源码 L11-L19）。
• 表名、行索引、字段名都先查询再操作；特别注意row update/delete使用的行索引是数据行在表中的物理索引（从 0 开始），不是默认主键值。

helper 的能力面覆盖enum、bean、table、field、row，以及批量（batch）、导入导出（export/import）、引用检查（ref）、类型系统（type）、模板（template）、别名（alias）、标签（tag）、变体（variant）、缓存（cache）等。以下各节逐一展开。

三、子命令体系全览（来自 argparse 定义）

从脚本 argparse 注册段（L4322-L4698） 可以看到完整的命令树：

类型、别名、标签、变体等能力属于进阶维护手段，使用前同样先查询对应子命令--help，并以 type-system.md、schema.md 的语义约束为准。

四、Excel 结构与解析原理（先理解再动手）

helper 内置统一的 Sheet 结构解析器LubanSheetStructure（源码 L36-L55），核心是识别以下标记行：

• ##var：字段名行
• ##type：类型行
• ##：注释行（可有多行）
• ##group：分组行（可选）

数据起始行由这些标记行共同决定，因此不要假设"固定前四行"。extra 注释行和纵表会改变数据起点。helper 新建横表时按"##var行 →##type行 → 多行##注释 → 可选##group行 → 数据行"的布局生成（见_create_table_excel，源码 L847-L941），纵表则以##column开头、每行一个字段（字段名 | 类型 | 注释 | 值），适合单例表。

定义类文件有三张，均位于Configs/GameConfig/Datas：

• __tables__.xlsx：表注册表（列含 full_name、value、input、index、mode、comment 等）
• __beans__.xlsx：Bean 定义表
• __enums__.xlsx：枚举定义表

这三张是定义表，不按业务行表的列格式处理。此外 helper 支持"自动导入表"约定：以#开头的 xlsx 文件会被自动扫描注册（源码 L545-L593），命名规则为：

• #Item.xlsx→ 表名TbItem，记录类型Item
• #Item-道具表.xlsx→ 表名TbItem，注释"道具表"
• reward/#Reward.xlsx→ 表名reward.TbReward（子目录表示模块前缀）

默认偏好prefer_auto_import = False，即默认在__tables__.xlsx正式注册（源码 L604-L606）。

另外注意：保留 Sheet 名、表头、批注、公式和非目标单元格，不要把整个 workbook 重建为纯值表；容器与 Bean 的分隔符来自类型/schema，不能普遍将中文逗号替换后认为合法（详见 excel-format.md）。

五、表级操作实战（table）

查看

python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table list python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table get <registered-name>

table list会合并输出__tables__.xlsx中的正式注册表与#前缀自动导入表，并标注source字段。

新增表

python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table add test.TbItem ` --fields "id:int:ID:c,name:string:名称:c" ` --value-type TbItem --input item.xlsx --mode map --index id --groups c,s --comment 物品表

关键参数（源码 L4382-L4394）：

helper 在add_table后会自动对新建表执行一次validate_table并打印发现的错误/警告（源码 L725-L732）。

分组（group）的显式性

写入字段时必须显式给出group（c/s/e）。虽然脚本提供了_infer_field_group关键词推断（如字段名含name/icon/model/ui/texture推断为c，含hp/mp/rate/cooldown推断为s，源码 L1171-L1209），但helper 的关键词推断不是业务分组依据，不可依赖。业务分组以 luban.conf 的groups（c/s/e三组）与targets定义为准；新增字段和表时必须检查客户端/服务端影响，且不要把"c,s"与["c","s"]两种写法机械互换。

其他表操作

• table update --comment/--input/--mode/--value-type：修改表属性
• table delete [--delete-data]：删除注册行，可选同时删除数据文件
• table check-legacy：检查可迁移到自动导入格式的老表
• table migrate-auto [name]：迁移老表到#前缀格式（不指定 name 则迁移所有）
• rename <old> <new> [--migrate-data]、copy <source> <target> [--copy-data]、diff <table1> <table2> [--json]

六、字段级操作实战（field）

# 列出字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field list <table> # 添加字段（--position 控制插入位置，从 0 开始，-1 为末尾） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field add <table> <name> --type int --comment 说明 --group c --position -1 # 修改字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field update <table> <name> --new-name <new> --type <type> --comment <c> --group <g> # 禁用字段（注释列：不导出但保留数据） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field disable <table> <name> # 启用字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field enable <table> <name> # 删除字段（危险操作，--force 跳过确认） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field delete <table> <name>

多 Sheet 文件需追加--sheet <sheet名>。批量添加字段用batch fields <table> --data '[{"name":"f1","type":"int"}]'。

类型写法遵循 type-system.md 的约定：常用源类型为bool/byte/short/int/long/float/double/string/text/datetime及自定义 enum/bean；容器示例list,int、array,string、map,string,int。源类型名不保证等于 C# 类型（尤其 datetime、text、mapper、容器），必须以当前 cs-bin 生成结果为准。

七、数据行操作实战（row）

# 列出数据行（--start 从 0 开始，--limit 默认 100） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row list <table> --start 0 --limit 100 # 按字段值取单行 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row get <table> --field id --value 1001 # 多条件查询 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row query <table> --conditions '{"type":"Weapon","quality":5}' # 新增行（复杂 JSON 推荐 --file） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row add <table> --file row.json # 更新行（index 为物理行索引，从 0 开始，不是主键值！） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row update <table> 3 --file row.json # 删除行（index 同上；--force 跳过确认） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row delete <table> 3

批量新增用batch rows <table> --data '[{"id":1,...},{"id":2,...}]'。row add同时支持--data（内联 JSON）与--file（推荐，规避 PowerShell 转义问题），两者在 源码 L4930-L4953 中统一经json.loads解析。

红线：row update/delete的INDEX参数是行索引而非主键值，操作前务必先row list确认物理行位置。另外，复杂/多行表头不要使用假定单行扁平结构的 CRUD——对纵表、多行列表等结构，先读源码确认 helper 支持情况，使用能保留单元格结构的编辑方式；不支持时停止自动批量改写（excel-format.md）。

八、枚举与 Bean 维护（含引用安全删除）

枚举

# 新增：--values 格式 name1=value1:alias1,name2=value2:alias2 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum add test.EQuality ` --values "Normal=1:普通,Rare=2:稀有" --comment 品质枚举 # 更新注释 / 切换 flags python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum update test.EQuality --comment 新注释 # 删除（默认受引用检查保护；--force 强制忽略引用） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum delete test.EQuality

enum add的--flags用于标志枚举，flags 必须验证值组合（type-system.md）；枚举别名只是数据输入便利，不可随意重编号。

Bean

# 新增：--fields 支持 CSV 简写或 --file JSON 数组 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas bean add test.EquipInfo ` --fields "id:int:ID,quality:test.EQuality:品质" --value-type 0 --sep "|" # 更新属性（--sep/--comment/--alias/--parent/--value-type） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas bean update test.EquipInfo --value-type 1

bean add关键参数：--value-type 1表示值类型/struct（用于list<Bean>中的 Bean 必须设为 1），--sep为 list 类型元素分隔符，--parent支持继承（多态、mapper、refgroup 等高级规则需先检查已安装 Luban 版本与现有示例，再以隔离数据生成验证，见 schema.md）。

引用安全删除（ref + delete_*_safe）

删除 Bean/枚举前必须先ref检查引用，禁止为"完成任务"使用--force忽略引用。底层实现中：

• check_references(type_name)构建类型引用索引_build_type_index()（递归解析 Bean 字段与表字段中的list<...>、map<k,v>容器引用），返回referenced_by与can_delete（源码 L2688-L2722）；
• delete_bean_safe()/delete_enum_safe()会先做引用检查，存在引用时打印引用者列表并拒绝删除，除非显式--force（源码 L2724-L2749）。

正确姿势：

# 先查引用 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas ref test.EQuality # 确认无引用后删除（不加 --force） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum delete test.EQuality

九、校验、导入导出与批量

校验 validate / validate_all

# 校验单表 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas validate <table> # 校验全部表 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas validate --all

validate_all()（源码 L2576-L2602）返回结构：{total, valid, invalid, details[]}，其中details逐表给出valid/errors/warnings。类型校验覆盖 int/float/bool 等基础类型（源码 L2550-L2574），对list/map/vector/array复杂类型跳过验证。

必须牢记的局限：helper 校验不能完整解析多行 Bean 表头等语义；工作流会保留该诊断并拒绝零表（total 为 0 时拒绝通过），但最终以真实 Luban 在 runs 隔离目录生成的类型/引用校验为最终依据（SKILL.md）。

导入导出

# 导出表数据为 JSON（默认打印到控制台，--output 指定文件） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas export <table> --output export.json # 从 JSON 导入（--mode append 默认；replace 未实现时必须明确失败，不能退化为 append） python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas import <table> import.json --mode append

JSON 导入契约详见>python .codex/scripts/workflow.py luban validate python .codex/scripts/workflow.py luban preview --mode lazyload # 展示预览，收到真实确认后才执行： python .codex/scripts/workflow.py approve --plan <preview.json> --by <reviewer> --reason <confirmation> --high-risk python .codex/scripts/workflow.py luban apply --plan <preview.json> --approval <approval.json> python .codex/scripts/workflow.py luban test

工作流validate会保存 helper 诊断，再用当前 Luban 在runs隔离目录校验并导出，不写生产产物；preview --mode lazyload复用现有bin-sharded、dataExporter=sharded与自定义懒加载模板，standard必须显式选择（普通bin，不是分片模式的故障回退）。生成代码与 bytes 的目标目录为Assets/GameScripts/HotFix/GameProto与Assets/AssetRaw/Configs/bytes，模板位于Configs/GameConfig/CustomTemplate（加载器 ConfigSystem.cs），运行时依赖说明见 runtime.md。

缓存纪律：缓存是派生数据，不能覆盖源；不要对任意目录执行cache clear。缓存命令cache build/clear只应在明确了解其语义后使用。

证据交付：每次操作后的源文件 diff、校验结果与导出证据必须一并交付（SKILL.md 输出约定），失败时保留输入与日志，不回滚用户已有数据，不将缺失产物或 Editor 离线写成通过。

十一、安全红线与最佳实践小结

按照以上约定，你可以在 TEngine 仓库中安全、可审计地完成 Luban 配置的日常维护，并与 TEngine 的 Lazyload/分片导出流水线无缝衔接。

• 游戏开发