luban_skill

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

前置条件

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

使用方式

bash
python scripts/luban_helper.py --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. 1. 目标文件：完整的 Excel 文件路径
2. 操作类型：添加/修改/删除 字段/数据行/枚举/Bean 等
3. 具体内容：详细的操作参数

各类操作确认模板

添加字段时：

我将执行以下操作：

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

确认执行吗？(是/否)

添加数据行时：

我将执行以下操作：

• - 目标文件：tables/datas/#Item-道具表.xlsx
• 操作：新增数据行
• 数据内容：

- id: 3007
- name: 魔丸
- type: Consumable
- quality: 5
- ...

确认执行吗？(是/否)

删除字段/数据时：

⚠️ 警告：此操作不可逆！

• - 目标文件：tables/datas/#Item-道具表.xlsx
• 操作：删除字段 price
• 影响：该字段的所有数据将被永久删除

确认执行吗？(是/否)

模糊指令时的确认：

场景	需要确认的内容
加个道具	确认表名、道具名、具体字段值
加个字段

确认表名、字段名、字段类型 |
| 删除xxx | 确认删除目标、影响范围、二次确认 |
| 修改xxx | 确认修改内容、影响的数据行 |

多文件选择：

找到多个可能的目标表：

1. 1. TbItem (道具表) - #Item-道具表.xlsx
2. TbSkill (技能表) - #Skill-技能表.xlsx

请选择要操作的表？

首次操作项目时

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

修改数据前

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

删除操作前

1. 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 |
| 查看所有 Bean | bean 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/delete

Bean操作 | 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 |
|