# Luban 游戏配置编辑器 Skill 需求文档 ## 1. 背景 Luban 是一个强大的游戏配置表生成工具，支持从 Excel/JSON 等格式导出到多种语言和平台。但在 AI 辅助开发场景下，AI 需要一种高效的方式来读取、修改和创建游戏配置表，而不是每次都读取整张表。 ## 2. 核心目标 让 AI 能够以**最小代价**操作 Luban 配置表，包括： - 快速读取表结构和字段信息 - 按需查询特定数据行 - 精准修改/新增数据 - 避免加载整张表到上下文 ## 3. 功能需求 ### 3.1 表结构查询 #### 3.1.1 获取表的所有字段定义 **输入**：表名（如 `TbItem`） **输出**： - 字段名称列表 - 字段类型 - 字段描述/注释 **示例输出**： ``` 表名: TbItem 字段: - id (int): 道具ID，唯一标识 - name (string): 道具名称 - desc (string): 道具描述 - count (int): 堆叠数量 ``` #### 3.1.2 获取表的基本信息 **输入**：表名 **输出**： - 表类型（单例表/列表表/Map表） - 主键字段（支持单主键、联合主键、多索引） - 数据行数 - 文件路径 **主键类型说明**： | 类型 | 定义示例 | 说明 | |------|---------|------| | 单主键 | `index="id"` | 单个字段唯一 | | 联合主键 | `index="id1+id2+id3"` | 多字段组合唯一 | | 多索引 | `index="id1,id2,id3"` | 每个字段各自唯一 | ### 3.2 数据查询 #### 3.2.1 按主键查询数据行 **输入**：表名 + 主键值（或多个主键值） **输出**：匹配的数据行 **支持复合主键**： - 单主键：`id=1` - 联合主键：`id1=1,id2=100,id3="abc"`（多字段组合唯一） - 多主键查询：`id=[1, 4, 7]` 或 `id1=1,id2=[100,200]` **示例**： ``` 查询: TbItem, id=[1, 4, 7] 输出: id=1: {id: 1, name: "道具1", desc: "描述1", count: 10} id=4: {id: 4, name: "道具4", desc: "描述4", count: 50} id=7: {id: 7, name: "道具7", desc: "描述7", count: 100} 查询: TbMultiUnionIndexList, id1=1, id2=100, id3="abc" 输出: {id1: 1, id2: 100, id3: "abc", num: 10, desc: "描述"} ``` #### 3.2.2 按条件筛选数据 **输入**：表名 + 筛选条件 **输出**：匹配的数据行列表 **示例**： ``` 查询: TbItem, where count > 50 输出: 所有 count > 50 的行 ``` #### 3.2.3 获取字段的所有唯一值 **输入**：表名 + 字段名 **输出**：该字段所有不重复的值 **示例**： ``` 查询: TbItem, field=name 输出: ["道具1", "道具2", "道具3", ...] ``` ### 3.3 数据修改 #### 3.3.1 新增数据行 **输入**：表名 + 数据内容 **输出**：操作结果（成功/失败/警告） #### 3.3.2 修改数据行 **输入**：表名 + 主键 + 要修改的字段和值 **输出**：操作结果 #### 3.3.3 删除数据行 **输入**：表名 + 主键 **输出**：操作结果 ### 3.4 表结构修改 #### 3.4.1 新增字段 **输入**：表名 + 字段定义（名称、类型、描述、默认值） **操作**： 1. 修改 XML 定义文件，添加 `` 标签 2. 修改 Excel 数据文件，添加新列 3. 为现有数据行填充默认值（可选） **示例**： ``` 新增字段: TbItem, field="quality", type="int", desc="品质", default=0 结果: - XML: - Excel: 新增 quality 列，现有行填充 0 ``` #### 3.4.2 修改字段 **输入**：表名 + 字段名 + 要修改的属性（类型、描述等） **输出**：操作结果 #### 3.4.3 删除字段 **输入**：表名 + 字段名 **操作**： 1. 修改 XML 定义文件，删除对应 `` 标签 2. 修改 Excel 数据文件，删除对应列 ### 3.5 表管理 #### 3.5.1 列出所有表 **输出**：项目中所有配置表的列表 #### 3.5.2 创建新表 **输入**：表名 + 字段定义 **输出**：创建结果（生成对应的 Excel/JSON 文件和定义） ### 3.6 类型系统查询 #### 3.6.1 枚举查询 **输入**：枚举名称（如 `EItemQuality`） **输出**：枚举的所有值及含义 **示例**： ``` 查询: EItemQuality 输出: 枚举名: EItemQuality 描述: 道具品质 值: - WHITE (0): 白 - GREEN (1): 绿 - BLUE (2): 蓝 - PURPLE (3): 紫 - GOLDEN (4): 金 ``` #### 3.6.2 枚举反向查询 **输入**：枚举值或别名 **输出**：对应的枚举名和值 **示例**： ``` 查询: EItemQuality, value="绿" 输出: GREEN = 1 查询: EItemQuality, value=2 输出: BLUE = 2, 别名: 蓝 ``` #### 3.6.3 Bean 结构查询 **输入**：Bean 名称（如 `Item`） **输出**：Bean 的所有字段定义 **示例**： ``` 查询: Item 输出: Bean名: Item 描述: 道具 字段: - id (int): 道具id - name (string): 名称 - major_type (EMajorType): 主类型 - minor_type (EMinorType): 子类型 ``` #### 3.6.4 Bean 继承关系查询 **输入**：Bean 名称 **输出**：父类、子类列表 **示例**： ``` 查询: DemoDynamic 输出: Bean名: DemoDynamic 描述: 多态数据结构 子类: - DemoD2 (测试别名) - DemoD3 - DemoD5 ``` #### 3.6.5 列出所有枚举/Bean **输出**：项目中所有枚举或 Bean 的列表 ### 3.7 类型系统管理 > **说明**：Luban 支持两种类型定义方式：XML（`Defines/*.xml`）和 Excel（`__enums__.xlsx`、`__beans__.xlsx`）。Skill 优先使用 Excel 方式，更易于 AI 操作。 #### `__enums__.xlsx` 结构说明 所有枚举定义在同一个 sheet 中，结构如下： ``` | ##var | full_name | flags | unique | group | comment | tags | *items | |-------|-------------------|-------|--------|-------|---------|------|---------------------| | ##var | name | alias | value | comment | tags | | | | ## | 全名 | 是否标志| 是否唯一 | | | | 枚举名 | | | test.ETestQuality | False | True | | | | A | 白 | 1 | 最高品质 | ← 枚举定义行（full_name有值） | | | | | | | | B | 黑 | 2 | 黑色的 | ← 枚举项行（full_name为空） | | | | | | | | C | 蓝 | 3 | 蓝色的 | | | test.AccessFlag | True | True | | | | WRITE | | 1 | | ← 新枚举定义 | | | | | | | | READ | | 2 | | ``` **关键规则**： - `full_name` 有值的行 = 枚举定义开始 - `full_name` 为空的行 = 上一枚举的枚举项 - `*items` 列开始是枚举项数据（name, alias, value, comment, tags） #### 3.7.1 新增枚举 **输入**：枚举名 + 描述 + 值列表 **操作**：在 `__enums__.xlsx` 末尾添加行 **示例**： ``` 新增枚举: test.EWeaponType, desc="武器类型" 值: SWORD=1(剑), BOW=2(弓), STAFF=3(法杖) 操作: 在 __enums__.xlsx 末尾添加： Row N: | test.EWeaponType | False | True | | | | SWORD | 剑 | 1 | | Row N+1: | | | | | | | BOW | 弓 | 2 | | Row N+2: | | | | | | | STAFF | 法杖 | 3 | | ``` #### 3.7.2 修改枚举 **输入**：枚举名 + 要修改的内容（新增值、删除值、修改别名） **操作**：找到枚举定义行，修改对应行或新增/删除枚举项行 #### 3.7.3 删除枚举 **输入**：枚举名 **操作**： 1. 找到 `full_name` = 枚举名的行 2. 删除该行及后续所有 `full_name` 为空的行（直到下一个枚举定义） **检查**：是否有表/Bean 正在使用此枚举 #### 3.7.4 新增 Bean **输入**：Bean 名 + 描述 + 字段列表 + 父类（可选） **操作**：在 `__beans__.xlsx` 末尾添加行 #### `__beans__.xlsx` 结构说明 所有 Bean 定义在同一个 sheet 中，结构如下： ``` | ##var | full_name | parent | valueType | alias | sep | comment | tags | group | *fields | |-------|-------------------|--------|-----------|-------|-----|---------|------|-------|--------------| | ##var | name | alias | type | group | comment | tags | variants | | | ## | 全名 | 父类 | 是否值类型 | 别名 | 分隔符 | 字段名 | 别名 | 类型 | 分组 | 注释 | | | test.TestBean1 | | | | | 测试Bean | | c | x1 | int | 最高品质 | | | | | | | | | | | x2 | string | 黑色的 | | | test.Circle | Shape | | 圆 | | | | | radius | float | 半径 | ``` **关键规则**： - `full_name` 有值的行 = Bean 定义开始 - `full_name` 为空的行 = 上一 Bean 的字段 - `*fields` 列开始是字段数据（name, alias, type, group, comment, tags, variants） **示例**： ``` 新增Bean: test.Weapon, desc="武器", parent="Item" 字段: attack(int,攻击力), speed(float,攻击速度) 操作: 在 __beans__.xlsx 末尾添加： Row N: | test.Weapon | Item | | | | 武器 | | | attack | | int | | 攻击力 | Row N+1: | | | | | | | | | speed | | float | | 攻击速度 | ``` #### 3.7.5 修改 Bean **输入**：Bean 名 + 要修改的内容（新增字段、删除字段、修改类型） **操作**：找到 Bean 定义行，修改对应行或新增/删除字段行 #### 3.7.6 删除 Bean **输入**：Bean 名 **操作**： 1. 找到 `full_name` = Bean 名的行 2. 删除该行及后续所有 `full_name` 为空的行（直到下一个 Bean 定义） **检查**：是否有表正在使用此 Bean，是否有子类 ## 4. 注释约定规范 ### 4.1 问题背景 Luban 的 Excel 表格中，字段注释没有明确的规范说明。需要定义一个约定，让 AI 能够正确识别字段描述。 ### 4.2 字段注释约定 #### 约定规则 在 Luban Excel 表格中，`##` 开头的行是注释行，会被 Luban 忽略。我们约定： **`##var` 行和数据起始行之间的所有 `##` 开头的行，作为字段注释。** #### 示例 ``` 行号 | A列 | B列 | C列 | D列 -----|------|----------|----------|----------- 1 | ##var| id | name | count ← ##var 单独一列，标识字段名行 2 | ##type| int | string | int ← ##type 单独一列，标识类型行 3 | ## | 道具ID | 道具名称 | 堆叠数量 ← 注释行1，## 单独一列 4 | ## | 唯一标识 | | ← 注释行2（可多行） 5 | | 1 | 道具1 | 10 ← 数据起始行，A列空，数据从B列开始 6 | | 2 | 道具2 | 100 ``` #### 解析规则 1. 找到 `##var` 行，确定字段名行位置 2. 找到 `##type` 行，确定类型行位置 3. 收集 `##var` 之后、数据行之前所有 `##` 开头的行 4. 将这些注释行按列对齐，合并为字段描述 5. 多个注释行用换行或空格连接 #### 优点 - **零改动**：完全兼容现有 Luban，`##` 本来就是注释 - **向后兼容**：现有表格无需修改 - **灵活**：支持多行注释 - **简单**：无需额外语法 ## 5. Skill 命令设计 ### 5.1 命令格式 | 命令 | 功能 | 示例 | |------|------|------| | `/luban list` | 列出所有表 | `/luban list` | | `/luban schema <表名>` | 获取表结构 | `/luban schema TbItem` | | `/luban get <表名> <主键>` | 查询数据行 | `/luban get TbItem 1,4,7` | | `/luban query <表名> <条件>` | 条件查询 | `/luban query TbItem "count>50"` | | `/luban values <表名> <字段>` | 获取字段唯一值 | `/luban values TbItem name` | | `/luban add <表名>` | 新增数据行 | `/luban add TbItem` | | `/luban update <表名> <主键>` | 修改数据行 | `/luban update TbItem 1` | | `/luban delete <表名> <主键>` | 删除数据行 | `/luban delete TbItem 1` | ### 5.2 交互模式 Skill 应支持两种模式： 1. **命令模式**：直接执行命令，返回结果 2. **对话模式**：AI 通过自然语言理解用户意图，调用相应功能 ## 6. 技术实现建议 ### 6.1 数据读取策略 #### 惰性缓存机制 采用惰性生成 + 哈希校验的缓存策略： ``` 读取配置时： 1. 检查是否存在缓存文件 .luban_cache/{table}_index.json 2. 不存在 → 生成索引 → 保存缓存 3. 存在 → 计算源文件哈希 → 对比缓存中的哈希 - 相同 → 读缓存 - 不同 → 重新生成索引 ``` #### 缓存文件结构 ``` .luban_cache/ ├── tbitem_index.json # TbItem 的索引缓存 ├── tbitem2_index.json └── ... ``` #### 单个缓存文件格式 ```json { "table": "TbItem", "sourceFile": "Datas/item/道具系统表.xlsx", "sourceHash": "a1b2c3d4e5f6", "updatedAt": "2026-03-22T10:00:00", "primaryKey": "id", "primaryKeyType": "single", "fields": [ {"name": "id", "type": "int", "desc": "道具ID"}, {"name": "name", "type": "string", "desc": "道具名称"}, {"name": "count", "type": "int", "desc": "堆叠数量"} ], "data": [ {"id": 1, "name": "道具1", "count": 10}, {"id": 2, "name": "道具2", "count": 100} ] } ``` #### 优点 - **惰性生成**：首次使用才生成，不浪费资源 - **增量更新**：只在源文件变化时重建缓存 - **透明**：用户无需手动操作，AI 自动管理 ### 6.2 数据索引 为支持快速查询，建议： 1. 解析 Excel/JSON 生成索引文件（`.index.json`） 2. 索引包含：表结构、主键索引、字段统计信息 3. AI 操作时先读取索引，再按需读取数据 ### 6.2 缓存机制 - 缓存已解析的表结构 - 增量更新索引 ### 6.3 校验机制 - 修改前校验数据类型 - 校验主键唯一性 - 校验引用完整性 ## 7. 优先级排序 ### P0 - 核心功能（必须实现） - [x] 列出所有表 - [x] 获取表结构（字段名、类型、描述） - [x] 按主键查询数据行 - [x] 枚举查询（查询枚举值及含义） - [x] Bean 结构查询 ### P1 - 重要功能 - [x] 条件筛选查询 - [x] 新增/修改/删除数据行 - [x] 字段唯一值查询 - [x] 模糊搜索（按字段值搜索） - [x] 主键重复检查 - [x] 枚举反向查询 - [x] Bean 继承关系查询 ### P2 - 增强功能 - [x] 创建新表 - [x] 数据校验（类型、空值、引用完整性） - [x] 批量操作（批量修改、克隆、删除） - [ ] ~~统计信息（最大/最小/平均值、分组统计）~~ - 暂不实现 - [x] 引用关系查询（查看被引用、引用链） - [x] 枚举值查询 - [x] 字段管理（新增/修改/删除字段） - [x] 类型系统管理（新增/修改/删除枚举和 Bean） ## 8. 后续扩展 - 支持多语言本地化表 - 支持表间引用关系查询 - 支持数据版本对比 - 支持导入导出 --- *文档版本: v1.0* *创建日期: 2026-03-22*