\r \r

luban_skill\r

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

前置条件\r

\r

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

使用方式\r

\r

python scripts/luban_helper.py \x3Ccommand> --data-dir \x3C项目的Datas目录>\r
```\r
\r
**注意**：PowerShell 中使用分号 `;` 作为命令分隔符，不要使用 `&&`。\r
\r
### PowerShell JSON 参数问题\r
\r
PowerShell 处理 JSON 字符串参数会有转义问题。**推荐使用 `--file` 参数从文件读取**：\r
\r
```bash\r
# 方法1：从JSON文件读取（推荐）\r
python scripts/luban_helper.py row add TbItem --file item.json --data-dir ...\r
\r
# 方法2：使用Python脚本调用\r
python -c "import json; ..."\r
```\r
\r
---\r
\r
## AI 操作工作流\r
\r
### ⚠️ 操作前确认机制（强制）\r
\r
**所有写入/修改/删除操作在执行前，必须明确询问用户确认。**\r
\r
确认信息必须包含：\r
1. **目标文件**：完整的 Excel 文件路径\r
2. **操作类型**：添加/修改/删除 字段/数据行/枚举/Bean 等\r
3. **具体内容**：详细的操作参数\r
\r
#### 各类操作确认模板\r
\r
**添加字段时**：\r
```\r
我将执行以下操作：\r
- 目标文件：tables/datas/#Item-道具表.xlsx\r
- 操作：添加新字段\r
- 字段名：soul\r
- 字段类型：string\r
- 字段注释：灵魂\r
- 分组：c (客户端)\r
\r
确认执行吗？(是/否)\r
```\r
\r
**添加数据行时**：\r
```\r
我将执行以下操作：\r
- 目标文件：tables/datas/#Item-道具表.xlsx\r
- 操作：新增数据行\r
- 数据内容：\r
  - id: 3007\r
  - name: 魔丸\r
  - type: Consumable\r
  - quality: 5\r
  - ...\r
\r
确认执行吗？(是/否)\r
```\r
\r
**删除字段/数据时**：\r
```\r
⚠️ 警告：此操作不可逆！\r
- 目标文件：tables/datas/#Item-道具表.xlsx\r
- 操作：删除字段 "price"\r
- 影响：该字段的所有数据将被永久删除\r
\r
确认执行吗？(是/否)\r
```\r
\r
**模糊指令时的确认**：\r
\r
| 场景 | 需要确认的内容 |\r
|------|---------------|\r
| "加个道具" | 确认表名、道具名、具体字段值 |\r
| "加个字段" | 确认表名、字段名、字段类型 |\r
| "删除xxx" | 确认删除目标、影响范围、二次确认 |\r
| "修改xxx" | 确认修改内容、影响的数据行 |\r
\r
**多文件选择**：\r
```\r
找到多个可能的目标表：\r
1. TbItem (道具表) - #Item-道具表.xlsx\r
2. TbSkill (技能表) - #Skill-技能表.xlsx\r
\r
请选择要操作的表？\r
```\r
\r
### 首次操作项目时\r
1. 执行 `table list` 了解项目有哪些表\r
2. 执行 `enum list` 和 `bean list` 了解类型系统\r
3. 根据用户需求定位具体表\r
\r
### 修改数据前\r
1. 先用 `table get` 或 `field list` 确认表结构\r
2. 用 `row get` 查询现有数据，避免主键冲突\r
3. **执行写入/修改/删除前，明确询问用户确认（目标文件 + 操作内容）**\r
4. 执行修改后用 `validate` 验证\r
\r
### 删除操作前\r
1. 用 `ref` 检查引用关系\r
2. 提醒用户确认风险\r
3. 危险操作需要二次确认\r
\r
### 智能推断指南\r
\r
| 用户说 | 推断命令 | 必须确认的内容 |\r
|--------|---------|---------------|\r
| "查一下屠龙刀" | `row get TbItem --field name --value "屠龙刀"` | 无需确认（只读） |\r
| "道具表加个字段" | `field add TbItem \x3C字段名> --type ...` | **必须确认**：目标文件、字段名、类型、注释 |\r
| "删除道具1001" | `row get TbItem --field id --value 1001` 确认后删除 | **必须确认**：目标文件、删除的数据行 |\r
| "看看品质枚举" | 先 `enum list` 找到匹配项，再 `enum get` | 无需确认（只读） |\r
| "加个新道具" | `row add TbItem --data '{"id":...}'` | **必须确认**：目标文件、所有字段值 |\r
\r
**重要原则**：\r
- **只读操作**（list/get/query/search）：无需确认，直接执行\r
- **写入操作**（add/update/delete）：**必须明确询问用户确认**，包括目标文件和具体操作内容\r
\r
---\r
\r
## 常见错误速查\r
\r
| 错误 | 原因 | 解决方案 |\r
|------|------|---------|\r
| 找不到表 | 表名不带模块或拼写错误 | 用 `table list` 确认完整表名 |\r
| 主键冲突 | 添加的数据 id 已存在 | 先 `row get` 检查是否已存在 |\r
| 类型错误 | 数据格式不匹配字段类型 | 用 `table get` 确认字段类型 |\r
| 引用约束 | 删除被引用的枚举/Bean | 用 `ref` 检查引用关系 |\r
| 找不到枚举 | 未带模块名 | 用 `enum list` 确认完整名称 |\r
\r
---\r
\r
## 常见场景速查\r
\r
| 场景 | 命令 |\r
|------|------|\r
| 查看项目有哪些表 | `table list` |\r
| 查看表结构 | `table get TbItem` |\r
| 查看所有枚举 | `enum list` |\r
| 查看枚举详情 | `enum get test.EItemQuality` |\r
| 查看所有 Bean | `bean list` |\r
| 查询 id=1001 的数据 | `row get TbItem --field id --value 1001` |\r
| 按条件查询数据 | `row query TbItem --conditions '{"type":"Weapon"}'` |\r
| 添加新字段 | `field add TbItem price --type int --comment 价格` |\r
| 删除字段（危险） | `field delete TbItem price` |\r
| 创建新表 | `table add test.TbEquip --fields "id:int,name:string"` |\r
| 创建纵表 | `table add test.TbConfig --fields "key:string,value:int" --vertical` |\r
| 添加数据行 | `row add TbItem --data '{"id":1001,"name":"宝剑"}'` |\r
| 添加数据行（从文件） | `row add TbItem --file item.json` |\r
| 导出表数据 | `export TbItem --output backup.json` |\r
\r
**智能插入**：添加数据行时自动按 ID 顺序插入到合适位置，而非追加到末尾。\r
- ID 最大 → 追加到末尾\r
- ID 在中间 → 插入到合适位置\r
\r
---\r
\r
## 命令概览\r
\r
| 命令 | 功能 | 示例 |\r
|------|------|------|\r
| `enum list/get/add/update/delete` | 枚举操作 | `enum get test.EQuality` |\r
| `bean list/get/add/update/delete` | Bean操作 | `bean get test.RewardItem` |\r
| `table list/get/add/update/delete` | 表操作 | `table get TbItem` |\r
| `field list/add/update/delete/disable/enable` | 字段操作 | `field add TbItem desc --type string` |\r
| `row list/get/query/add/update/delete` | 数据行操作 | `row get TbItem --field id --value 1` |\r
| `batch fields/rows` | 批量操作 | `batch rows TbItem --data '[...]'` |\r
| `export/import` | 导入导出 | `export TbItem --output backup.json` |\r
| `validate` | 验证表数据 | `validate TbItem` |\r
| `ref` | 引用检查 | `ref test.RewardItem` |\r
| `template` | 配置模板 | `template create item TbEquip` |\r
| `rename/copy/diff` | 表管理 | `rename TbItem TbItemNew` |\r
| `auto` | 自动导入表 | `auto create #Item --fields "..."` |\r
| `alias` | 常量别名 | `alias add GOLD 10000` |\r
| `tag` | 数据标签 | `tag add TbItem 2 dev` |\r
| `variant` | 字段变体 | `variant add TbItem name zh` |\r
| `multirow` | 多行结构 | `multirow TbReward items` |\r
| `type` | 类型系统操作 | `type list`, `type suggest quality --context item` |\r
| `type info \x3Cname>` | 查询类型详情 | `type info "list\x3Cint>"` |\r
| `type list` | 列出所有类型 | `type list --category enum` |\r
| `type validate \x3Cname>` | 验证类型 | `type validate "list\x3Cint>"` |\r
| `type suggest \x3Cfield>` | 建议字段类型 | `type suggest drops --context monster` |\r
| `type search \x3Ckeyword>` | 搜索类型 | `type search Quality` |\r
| `type guide` | 类型使用指南 | `type guide --topic container` |\r
| `cache` | 缓存管理 | `cache build` |\r
| `pref` | 用户偏好 | `pref set prefer_auto_import true` |\r
\r
---\r
\r
## 核心操作示例\r
\r
### 枚举操作\r
\r
```bash\r
# 列出所有枚举\r
python scripts/luban_helper.py enum list --data-dir DataTables/Datas\r
\r
# 查询枚举详情\r
python scripts/luban_helper.py enum get test.ETestQuality --data-dir DataTables/Datas\r
\r
# 新增枚举\r
python scripts/luban_helper.py enum add test.EWeaponType --values "SWORD=1:剑,BOW=2:弓,STAFF=3:法杖" --comment "武器类型" --data-dir DataTables/Datas\r
\r
# 删除枚举\r
python scripts/luban_helper.py enum delete test.EWeaponType --data-dir DataTables/Datas\r
```\r
\r
### Bean 操作\r
\r
```bash\r
# 列出所有 Bean\r
python scripts/luban_helper.py bean list --data-dir DataTables/Datas\r
\r
# 查询 Bean 详情\r
python scripts/luban_helper.py bean get test.TestBean1 --data-dir DataTables/Datas\r
\r
# 新增 Bean\r
python scripts/luban_helper.py bean add test.Weapon --fields "attack:int:攻击力,speed:float:攻击速度" --parent Item --comment "武器" --data-dir DataTables/Datas\r
```\r
\r
### 表操作\r
\r
```bash\r
# 列出所有表\r
python scripts/luban_helper.py table list --data-dir DataTables/Datas\r
\r
# 查询表详情\r
python scripts/luban_helper.py table get test.TbItem --data-dir DataTables/Datas\r
\r
# 新增配置表（默认自动导入格式）\r
python scripts/luban_helper.py table add test.TbItem --fields "id:int:道具ID,name:string:道具名称" --comment "道具表" --data-dir DataTables/Datas\r
\r
# 创建纵表（单例表）\r
python scripts/luban_helper.py table add test.TbGlobalConfig --fields "guild_open_level:int:公会开启等级,bag_init_size:int:初始格子数" --comment "全局配置" --vertical --data-dir DataTables/Datas\r
```\r
\r
### 字段操作\r
\r
```bash\r
# 列出表的所有字段\r
python scripts/luban_helper.py field list test.TbItem --data-dir DataTables/Datas\r
\r
# 添加字段（分组自动推断）\r
python scripts/luban_helper.py field add test.TbItem desc --type "string" --comment "道具描述" --data-dir DataTables/Datas\r
\r
# 删除字段（危险操作，需确认）\r
python scripts/luban_helper.py field delete test.TbItem desc --data-dir DataTables/Datas\r
\r
# 禁用/启用字段\r
python scripts/luban_helper.py field disable test.TbItem desc --data-dir DataTables/Datas\r
python scripts/luban_helper.py field enable test.TbItem desc --data-dir DataTables/Datas\r
```\r
\r
**分组自动推断规则**：\r
- `c` (客户端): name, desc, icon, image, model, effect, sound, ui 等\r
- `s` (服务器): server, logic, damage, hp, mp, exp, level, rate 等\r
- `cs` (两者): id, 其他无法明确判断的字段\r
\r
### 数据行操作\r
\r
```bash\r
# 列出数据行\r
python scripts/luban_helper.py row list test.TbItem --data-dir DataTables/Datas\r
\r
# 按字段值查询\r
python scripts/luban_helper.py row get TbItem --field id --value 1004 --data-dir DataTables/Datas\r
\r
# 多条件查询\r
python scripts/luban_helper.py row query TbItem --conditions '{"type":"Weapon","quality":5}' --data-dir DataTables/Datas\r
\r
# 添加数据行\r
python scripts/luban_helper.py row add test.TbItem --data '{"id":1001,"name":"宝剑","count":1}' --data-dir DataTables/Datas\r
```\r
\r
---\r
\r
## 自动导入表\r
\r
Luban 支持文件名以 `#` 开头的 Excel 文件自动导入为表。\r
\r
**命名规则**：\r
- `#Item.xlsx` → 表名 `TbItem`，记录类型 `Item`\r
- `#Item-道具表.xlsx` → 表名 `TbItem`，注释 `道具表`\r
- `reward/#Reward.xlsx` → 表名 `reward.TbReward`\r
\r
```bash\r
# 列出自动导入的表\r
python scripts/luban_helper.py auto list --data-dir DataTables/Datas\r
\r
# 创建自动导入表\r
python scripts/luban_helper.py auto create #Item --fields "id:int:ID,name:string:名称" --data-dir DataTables/Datas\r
```\r
\r
---\r
\r
## Excel 结构说明\r
\r
### 数据表结构\r
```\r
| ##var   | id  | name   | count   |\r
| ##type  | int | string | int     |\r
| ##      | 道具ID | 道具名称 | 堆叠数量  |\r
| ##group | c   | c      | c       |  ← 可选\r
```\r
\r
### 纵表结构（单例表）\r
```\r
| ##column |          |          |         |\r
| ##var    | ##type   | ##       | ##group |\r
| key      | string   | 配置键    | c       |\r
| value    | int      | 配置值    | s       |\r
```\r
\r
### __enums__.xlsx 结构\r
- `full_name` 有值 = 枚举定义开始\r
- `full_name` 为空 = 上一枚举的枚举项\r
- `*items` 列（H列开始）= 枚举项数据\r
\r
### __beans__.xlsx 结构\r
- `full_name` 有值 = Bean 定义开始\r
- `full_name` 为空 = 上一 Bean 的字段\r
- `*fields` 列（J列开始）= 字段数据\r
\r
---\r
\r
## 支持的类型\r
\r
### 基本类型\r
`bool` `byte` `short` `int` `long` `float` `double` `string` `text` `datetime`\r
\r
### 容器类型\r
`array\x3CT>` `list\x3CT>` `set\x3CT>` `map\x3CK,V>`\r
\r
### 可空类型\r
在类型后加 `?`：`int?` `string?` `MyBean?`\r
\r
---\r
\r
## 类型系统操作指南\r
\r
Skill 提供强大的类型系统支持，帮助快速查找和使用正确的类型。\r
\r
### 列出所有可用类型\r
\r
```bash\r
# 列出所有类型（基本类型 + 容器类型 + 枚举 + Bean）\r
python scripts/luban_helper.py type list --data-dir DataTables/Datas\r
\r
# 只列出基本类型\r
python scripts/luban_helper.py type list --category basic --data-dir DataTables/Datas\r
\r
# 只列出枚举\r
python scripts/luban_helper.py type list --category enum --data-dir DataTables/Datas\r
\r
# 只列出 Bean\r
python scripts/luban_helper.py type list --category bean --data-dir DataTables/Datas\r
```\r
\r
### 验证类型是否有效\r
\r
```bash\r
# 验证单个类型\r
python scripts/luban_helper.py type validate "list\x3Cint>" --data-dir DataTables/Datas\r
\r
# 验证枚举类型\r
python scripts/luban_helper.py type validate "test.EQuality" --data-dir DataTables/Datas\r
```\r
\r
### 根据字段名建议类型\r
\r
```bash\r
# 通用建议\r
python scripts/luban_helper.py type suggest "item_id" --data-dir DataTables/Datas\r
\r
# 怪物上下文建议\r
python scripts/luban_helper.py type suggest "drops" --context monster --data-dir DataTables/Datas\r
\r
# 道具上下文建议\r
python scripts/luban_helper.py type suggest "quality" --context item --data-dir DataTables/Datas\r
```\r
\r
**支持的上下文**：`item`(道具), `skill`(技能), `monster`(怪物), `quest`(任务), `general`(通用)\r
\r
### 搜索类型\r
\r
```bash\r
# 搜索包含关键词的类型\r
python scripts/luban_helper.py type search Quality --data-dir DataTables/Datas\r
\r
# 只搜索枚举\r
python scripts/luban_helper.py type search Quality --category enum --data-dir DataTables/Datas\r
\r
# 只搜索 Bean\r
python scripts/luban_helper.py type search Reward --category bean --data-dir DataTables/Datas\r
```\r
\r
### 查看类型使用指南\r
\r
```bash\r
# 查看完整类型指南\r
python scripts/luban_helper.py type guide --data-dir DataTables/Datas\r
\r
# 查看容器类型指南\r
python scripts/luban_helper.py type guide --topic container --data-dir DataTables/Datas\r
\r
# 查看可空类型指南\r
python scripts/luban_helper.py type guide --topic nullable --data-dir DataTables/Datas\r
\r
# 查看枚举使用指南\r
python scripts/luban_helper.py type guide --topic enum --data-dir DataTables/Datas\r
```\r
\r
### 查询类型详情\r
\r
```bash\r
# 查询 list\x3Cint> 的详细信息\r
python scripts/luban_helper.py type info "list\x3Cint>" --data-dir DataTables/Datas\r
\r
# 查询枚举详情\r
python scripts/luban_helper.py type info "test.EQuality" --data-dir DataTables/Datas\r
```\r
\r
### 字段类型推断规则\r
\r
Skill 内置智能类型推断，根据字段名自动建议类型：\r
\r
| 字段名模式 | 建议类型 | 说明 |\r
|-----------|---------|------|\r
| `*_id`, `id` | int, long | ID 字段 |\r
| `name`, `title`, `desc` | string | 名称/描述 |\r
| `*count`, `*num` | int | 数量 |\r
| `*price`, `*cost` | int, long | 价格/成本 |\r
| `quality`, `level`, `grade` | int | 品质/等级 |\r
| `*rate`, `*ratio`, `*prob` | float, double | 概率/比率 |\r
| `*time`, `*duration` | int, datetime | 时间 |\r
| `is_*`, `has_*`, `can_*` | bool | 布尔标志 |\r
| `*icon`, `*image`, `*model` | string | 资源路径 |\r
| `*s`, `*_list`, `*ids` | list\x3Cint> | 列表 |\r
| `*x`, `*y`, `*z`, `*pos*` | float | 坐标 |\r
\r
---\r
\r
## 危险操作说明\r
\r
以下操作需要二次确认：\r
\r
| 操作 | 说明 |\r
|------|------|\r
| `field delete` | 删除字段会同时删除该字段的所有数据 |\r
| `row delete` | 删除数据行不可恢复 |\r
| `enum delete` | 删除被引用的枚举会导致错误 |\r
| `bean delete` | 删除被引用的 Bean 会导致错误 |\r
\r
使用 `--force` 可跳过确认，但请谨慎使用。\r
\r
---\r
\r
## 注意事项\r
\r
1. **枚举/Bean 名称**：需要包含模块名，如 `test.EWeaponType`\r
2. **删除前检查**：删除前确认没有其他地方引用该枚举/Bean\r
3. **路径问题**：确保 `--data-dir` 指向正确的 `Datas` 目录\r
\r
---\r
\r
## 详细文档\r
\r
- 完整命令文档：[references/commands.md](references/commands.md)\r
- 需求参考文档：[references/REFERENCE.md](references/REFERENCE.md)\r