luban_skill#

帮助 AI 高效操作 Luban 游戏配置表，支持枚举、Bean、数据表的增删改查。

前置条件#

1. 确保 Python 3.8+ 已安装
2. 安装依赖： pip install openpyxl

使用方式#

bash

python scripts/luban_helper.py <command> --data-dir <项目的Datas目录>

注意：PowerShell 中使用分号 ; 作为命令分隔符，不要使用 &&。

PowerShell JSON 参数问题#

PowerShell 处理 JSON 字符串参数会有转义问题。 推荐使用 --file 参数从文件读取：

bash

# 方法1：从JSON文件读取（推荐）
python scripts/luban_helper.py row add TbItem --file item.json --data-dir ...

# 方法2：使用Python脚本调用
python -c "import json; ..."

---

AI 操作工作流#

⚠️ 操作前确认机制（强制）#

所有写入/修改/删除操作在执行前，必须明确询问用户确认。

确认信息必须包含：

1. 目标文件：完整的 Excel 文件路径
2. 操作类型：添加/修改/删除 字段/数据行/枚举/Bean 等
3. 具体内容：详细的操作参数

各类操作确认模板

添加字段时：

text

我将执行以下操作：
- 目标文件：tables/datas/#Item-道具表.xlsx
- 操作：添加新字段
- 字段名：soul
- 字段类型：string
- 字段注释：灵魂
- 分组：c (客户端)

确认执行吗？(是/否)

添加数据行时：

text

我将执行以下操作：
- 目标文件：tables/datas/#Item-道具表.xlsx
- 操作：新增数据行
- 数据内容：
  - id: 3007
  - name: 魔丸
  - type: Consumable
  - quality: 5
  - ...

确认执行吗？(是/否)

删除字段/数据时：

text

⚠️ 警告：此操作不可逆！
- 目标文件：tables/datas/#Item-道具表.xlsx
- 操作：删除字段 "price"
- 影响：该字段的所有数据将被永久删除

确认执行吗？(是/否)

模糊指令时的确认：

场景需要确认的内容"加个道具"确认表名、道具名、具体字段值"加个字段"确认表名、字段名、字段类型"删除xxx"确认删除目标、影响范围、二次确认"修改xxx"确认修改内容、影响的数据行

多文件选择：

text

找到多个可能的目标表：
1. TbItem (道具表) - #Item-道具表.xlsx
2. TbSkill (技能表) - #Skill-技能表.xlsx

请选择要操作的表？

首次操作项目时#

1. 执行 table list 了解项目有哪些表
2. 执行 enum list 和 bean list 了解类型系统
3. 根据用户需求定位具体表

修改数据前#

1. 先用 table get 或 field list 确认表结构
2. 用 row get 查询现有数据，避免主键冲突
3. 执行写入/修改/删除前，明确询问用户确认（目标文件 + 操作内容）
4. 执行修改后用 validate 验证

删除操作前#

1. 用 ref 检查引用关系
2. 提醒用户确认风险
3. 危险操作需要二次确认

智能推断指南#

用户说推断命令必须确认的内容"查一下屠龙刀"row get TbItem --field name --value "屠龙刀"无需确认（只读）"道具表加个字段"field add TbItem <字段名> --type ...必须确认：目标文件、字段名、类型、注释"删除道具1001"row get TbItem --field id --value 1001 确认后删除必须确认：目标文件、删除的数据行"看看品质枚举"先 enum list 找到匹配项，再 enum get无需确认（只读）"加个新道具"row add TbItem --data '{"id":...}'必须确认：目标文件、所有字段值

重要原则：

• 只读操作（list/get/query/search）：无需确认，直接执行
• 写入操作（add/update/delete）： 必须明确询问用户确认，包括目标文件和具体操作内容

---

常见错误速查#

错误原因解决方案找不到表表名不带模块或拼写错误用 table list 确认完整表名主键冲突添加的数据 id 已存在先 row get 检查是否已存在类型错误数据格式不匹配字段类型用 table get 确认字段类型引用约束删除被引用的枚举/Bean用 ref 检查引用关系找不到枚举未带模块名用 enum list 确认完整名称

---

常见场景速查#

场景命令查看项目有哪些表table list查看表结构table get TbItem查看所有枚举enum list查看枚举详情enum get test.EItemQuality查看所有 Beanbean list查询 id=1001 的数据row get TbItem --field id --value 1001按条件查询数据row query TbItem --conditions '{"type":"Weapon"}'添加新字段field add TbItem price --type int --comment 价格删除字段（危险）field delete TbItem price创建新表table add test.TbEquip --fields "id:int,name:string"创建纵表table add test.TbConfig --fields "key:string,value:int" --vertical添加数据行row add TbItem --data '{"id":1001,"name":"宝剑"}'添加数据行（从文件）row add TbItem --file item.json导出表数据export TbItem --output backup.json

智能插入：添加数据行时自动按 ID 顺序插入到合适位置，而非追加到末尾。

• ID 最大 → 追加到末尾
• ID 在中间 → 插入到合适位置

---

命令概览#

命令功能示例enum list/get/add/update/delete枚举操作enum get test.EQuality``bean list/get/add/update/deleteBean操作bean get test.RewardItem``table list/get/add/update/delete表操作table get TbItem``field list/add/update/delete/disable/enable字段操作field add TbItem desc --type string``row list/get/query/add/update/delete数据行操作row get TbItem --field id --value 1``batch fields/rows批量操作batch rows TbItem --data '[...]'``export/import导入导出export TbItem --output backup.json``validate验证表数据validate TbItem``ref引用检查ref test.RewardItem``template配置模板template create item TbEquip``rename/copy/diff表管理rename TbItem TbItemNew``auto自动导入表auto create #Item --fields "..."``alias常量别名alias add GOLD 10000``tag数据标签tag add TbItem 2 dev``variant字段变体variant add TbItem name zh``multirow多行结构multirow TbReward items``type类型系统操作type list, type suggest quality --context item``type info <name>查询类型详情type info "list<int>"``type list列出所有类型type list --category enum``type validate <name>验证类型type validate "list<int>"``type suggest <field>建议字段类型type suggest drops --context monster``type search <keyword>搜索类型type search Quality``type guide类型使用指南type guide --topic container``cache缓存管理cache build``pref用户偏好pref set prefer_auto_import true

---

核心操作示例#

枚举操作#

bash

# 列出所有枚举
python scripts/luban_helper.py enum list --data-dir DataTables/Datas

# 查询枚举详情
python scripts/luban_helper.py enum get test.ETestQuality --data-dir DataTables/Datas

# 新增枚举
python scripts/luban_helper.py enum add test.EWeaponType --values "SWORD=1:剑,BOW=2:弓,STAFF=3:法杖" --comment "武器类型" --data-dir DataTables/Datas

# 删除枚举
python scripts/luban_helper.py enum delete test.EWeaponType --data-dir DataTables/Datas

Bean 操作#

bash

# 列出所有 Bean
python scripts/luban_helper.py bean list --data-dir DataTables/Datas

# 查询 Bean 详情
python scripts/luban_helper.py bean get test.TestBean1 --data-dir DataTables/Datas

# 新增 Bean
python scripts/luban_helper.py bean add test.Weapon --fields "attack:int:攻击力,speed:float:攻击速度" --parent Item --comment "武器" --data-dir DataTables/Datas

表操作#

bash

# 列出所有表
python scripts/luban_helper.py table list --data-dir DataTables/Datas

# 查询表详情
python scripts/luban_helper.py table get test.TbItem --data-dir DataTables/Datas

# 新增配置表（默认自动导入格式）
python scripts/luban_helper.py table add test.TbItem --fields "id:int:道具ID,name:string:道具名称" --comment "道具表" --data-dir DataTables/Datas

# 创建纵表（单例表）
python scripts/luban_helper.py table add test.TbGlobalConfig --fields "guild_open_level:int:公会开启等级,bag_init_size:int:初始格子数" --comment "全局配置" --vertical --data-dir DataTables/Datas

字段操作#

bash

# 列出表的所有字段
python scripts/luban_helper.py field list test.TbItem --data-dir DataTables/Datas

# 添加字段（分组自动推断）
python scripts/luban_helper.py field add test.TbItem desc --type "string" --comment "道具描述" --data-dir DataTables/Datas

# 删除字段（危险操作，需确认）
python scripts/luban_helper.py field delete test.TbItem desc --data-dir DataTables/Datas

# 禁用/启用字段
python scripts/luban_helper.py field disable test.TbItem desc --data-dir DataTables/Datas
python scripts/luban_helper.py field enable test.TbItem desc --data-dir DataTables/Datas

分组自动推断规则：

• c (客户端): name, desc, icon, image, model, effect, sound, ui 等
• s (服务器): server, logic, damage, hp, mp, exp, level, rate 等
• cs (两者): id, 其他无法明确判断的字段

数据行操作#

bash

# 列出数据行
python scripts/luban_helper.py row list test.TbItem --data-dir DataTables/Datas

# 按字段值查询
python scripts/luban_helper.py row get TbItem --field id --value 1004 --data-dir DataTables/Datas

# 多条件查询
python scripts/luban_helper.py row query TbItem --conditions '{"type":"Weapon","quality":5}' --data-dir DataTables/Datas

# 添加数据行
python scripts/luban_helper.py row add test.TbItem --data '{"id":1001,"name":"宝剑","count":1}' --data-dir DataTables/Datas

---

自动导入表#

Luban 支持文件名以 # 开头的 Excel 文件自动导入为表。

命名规则：

• #Item.xlsx → 表名 TbItem，记录类型 Item
• #Item-道具表.xlsx → 表名 TbItem，注释 道具表
• reward/#Reward.xlsx → 表名 reward.TbReward

bash

# 列出自动导入的表
python scripts/luban_helper.py auto list --data-dir DataTables/Datas

# 创建自动导入表
python scripts/luban_helper.py auto create #Item --fields "id:int:ID,name:string:名称" --data-dir DataTables/Datas

---

Excel 结构说明#

数据表结构#

text

| ##var   | id  | name   | count   |
| ##type  | int | string | int     |
| ##      | 道具ID | 道具名称 | 堆叠数量  |
| ##group | c   | c      | c       |  ← 可选

纵表结构（单例表）#

text

| ##column |          |          |         |
| ##var    | ##type   | ##       | ##group |
| key      | string   | 配置键    | c       |
| value    | int      | 配置值    | s       |

enums.xlsx 结构#

• full_name 有值 = 枚举定义开始
• full_name 为空 = 上一枚举的枚举项
• *items 列（H列开始）= 枚举项数据

beans.xlsx 结构#

• full_name 有值 = Bean 定义开始
• full_name 为空 = 上一 Bean 的字段
• *fields 列（J列开始）= 字段数据

---

支持的类型#

基本类型#

bool byte short int long float double string text datetime

容器类型#

array<T> list<T> set<T> map<K,V>

可空类型#

在类型后加 ?： int? string? MyBean?

---

类型系统操作指南#

Skill 提供强大的类型系统支持，帮助快速查找和使用正确的类型。

列出所有可用类型#

bash

# 列出所有类型（基本类型 + 容器类型 + 枚举 + Bean）
python scripts/luban_helper.py type list --data-dir DataTables/Datas

# 只列出基本类型
python scripts/luban_helper.py type list --category basic --data-dir DataTables/Datas

# 只列出枚举
python scripts/luban_helper.py type list --category enum --data-dir DataTables/Datas

# 只列出 Bean
python scripts/luban_helper.py type list --category bean --data-dir DataTables/Datas

验证类型是否有效#

bash

# 验证单个类型
python scripts/luban_helper.py type validate "list<int>" --data-dir DataTables/Datas

# 验证枚举类型
python scripts/luban_helper.py type validate "test.EQuality" --data-dir DataTables/Datas

根据字段名建议类型#

bash

# 通用建议
python scripts/luban_helper.py type suggest "item_id" --data-dir DataTables/Datas

# 怪物上下文建议
python scripts/luban_helper.py type suggest "drops" --context monster --data-dir DataTables/Datas

# 道具上下文建议
python scripts/luban_helper.py type suggest "quality" --context item --data-dir DataTables/Datas

支持的上下文： item(道具), skill(技能), monster(怪物), quest(任务), general(通用)

搜索类型#

bash

# 搜索包含关键词的类型
python scripts/luban_helper.py type search Quality --data-dir DataTables/Datas

# 只搜索枚举
python scripts/luban_helper.py type search Quality --category enum --data-dir DataTables/Datas

# 只搜索 Bean
python scripts/luban_helper.py type search Reward --category bean --data-dir DataTables/Datas

查看类型使用指南#

bash

# 查看完整类型指南
python scripts/luban_helper.py type guide --data-dir DataTables/Datas

# 查看容器类型指南
python scripts/luban_helper.py type guide --topic container --data-dir DataTables/Datas

# 查看可空类型指南
python scripts/luban_helper.py type guide --topic nullable --data-dir DataTables/Datas

# 查看枚举使用指南
python scripts/luban_helper.py type guide --topic enum --data-dir DataTables/Datas

查询类型详情#

bash

# 查询 list<int> 的详细信息
python scripts/luban_helper.py type info "list<int>" --data-dir DataTables/Datas

# 查询枚举详情
python scripts/luban_helper.py type info "test.EQuality" --data-dir DataTables/Datas

字段类型推断规则#

Skill 内置智能类型推断，根据字段名自动建议类型：

字段名模式建议类型说明*_id, idint, longID 字段name, title, descstring名称/描述*count, *numint数量*price, *costint, long价格/成本quality, level, gradeint品质/等级*rate, *ratio, *probfloat, double概率/比率*time, *durationint, datetime时间is_*, has_*, can_*bool布尔标志*icon, *image, *modelstring资源路径*s, *_list, *idslist列表*x, *y, *z, *pos*float坐标

---

危险操作说明#

以下操作需要二次确认：

操作说明field delete删除字段会同时删除该字段的所有数据row delete删除数据行不可恢复enum delete删除被引用的枚举会导致错误bean delete删除被引用的 Bean 会导致错误

使用 --force 可跳过确认，但请谨慎使用。

---

注意事项#

1. 枚举/Bean 名称：需要包含模块名，如 test.EWeaponType
2. 删除前检查：删除前确认没有其他地方引用该枚举/Bean
3. 路径问题：确保 --data-dir 指向正确的 Datas 目录

---

详细文档#

• 完整命令文档： references/commands.md
• 需求参考文档： references/REFERENCE.md