---

name: luban-config-editor description: Luban游戏配置表编辑器。当用户上传Excel文件并请求"修改配置表"、"编辑Luban表格"、"更新游戏配置"、"查看配置数据"时触发。支持符合Luban格式（含##var和##type行）的Excel表格的查询、更新、插入和删除操作。

Luban 配置表编辑器 (v2.1)

采用 "Query (精读) + Patch (微修)" 模式处理 Luban 格式 Excel 配置表。

⚠️ 强制约束

严禁直接使用 pandas/openpyxl 操作 Excel 文件。

必须通过脚本完成所有操作：

• scripts/query.py — 查询（摘要/条件/分页/列裁剪）
• scripts/patch.py — 修改（update/insert/delete + Diff预览）

核心原则

1. 最小化读取：严禁无理由全量拉取。必须用 --columns 裁剪列，用 --limit/--offset 分页
2. 内存逻辑：工具只负责基础筛选，复杂判断（如 age > 10）由 LLM 在读取数据后内存处理
3. 预览先行：修改前优先用 --dry_run 查看 Diff
4. 原子修改：Patch 中只包含主键和真正变化的字段

前置条件

pip install pandas openpyxl --break-system-packages

支持的数据类型

基础类型

类型定义	说明	Excel示例	Python映射
int, int32, long	整数	100	int
byte, short	小整数	255	int
datetime	时间戳	1704067200	int
float, double	浮点数	3.14	float
bool	布尔值	true / 1 / yes / on	bool
string, text	文本字符串	hello	str

Bool兼容性：读取时兼容 true/false, 1/0, yes/no, t/f, on/off（不区分大小写）

容器类型

类型定义	Excel格式	Python映射
array,int	1,2,3	[1, 2, 3]
list,string	a,b,c	["a", "b", "c"]
set,int	1,2,3	[1, 2, 3]
(array#sep=|),int	1|2|3	[1, 2, 3]
map,int,string	1:a,2:b	{1: "a", 2: "b"}
(map#sep=|),int,int	1:10|2:20	{1: 10, 2: 20}

Map KV分隔符：读取时兼容 _、:、=，写入时统一使用 :

标准操作步骤

第一步：结构侦察

获取表名、主键、列名列表：

python scripts/query.py --excel_path "data.xlsx" --summary

输出示例：

{
  "Items": {
    "rows": 2000,
    "pk": "id",
    "fields": [
      {"name": "id", "type": "int"},
      {"name": "rewards", "type": "map,int,int"}
    ]
  }
}

第二步：外科手术式读取

场景A：已知主键

python scripts/query.py --excel_path "data.xlsx" --sheet Items --where "id=1001"

场景B：批量扫描（必须裁剪+分页）

python scripts/query.py --excel_path "data.xlsx" --sheet Items --columns "id,name" --limit 100 --offset 0

第三步：生成Patch

import json

patch = {
    "Items": {
        "update": [
            {"id": 102, "active": False},
            {"id": 103, "rewards": {1001: 5, 1002: 10}}  # Map类型
        ],
        "insert": [
            {"id": 201, "name": "新道具", "tags": ["vip", "test"]}  # Array类型
        ],
        "delete": [103, 104]
    }
}

with open('patch.json', 'w', encoding='utf-8') as f:
    json.dump(patch, f, ensure_ascii=False, indent=2)

第四步：安全预览

python scripts/patch.py --excel_path "data.xlsx" --patch_path patch.json --dry_run

输出 Diff：

{
  "Items": {
    "updated": 2,
    "diff": [
      "UPDATE pk=102: active: True -> False",
      "UPDATE pk=103: rewards: 1001:3,1002:5 -> 1001:5,1002:10"
    ]
  }
}

必须检查 Diff：是否修改了错误的行？值的变化是否合理？

第五步：执行

python scripts/patch.py --excel_path "data.xlsx" --patch_path patch.json

Query 参数速查

参数	说明	示例
--summary	获取所有Sheet结构	--summary
--sheet	指定Sheet名	--sheet Items
--where	主键条件	--where "id=1001"
--columns	只返回指定列	--columns "id,name"
--limit	最大返回行数	--limit 100
--offset	跳过前N行	--offset 100

Patch 格式规范

{
  "SheetName": {
    "update": [{"pk": value, "field1": newValue}],
    "insert": [{"pk": value, "field1": value, ...}],
    "delete": [pk1, pk2, ...]
  }
}

操作	说明
update	必须含主键，只写变更字段，智能跳过无变化字段
insert	必须含主键和必要字段
delete	主键列表，软删除（标记#DELETED#）

JSON生成规范

禁止手写JSON字符串，必须用 dict + json.dump

# ❌ 严禁
json_str = '{"name": "他说"你好""}'

# ✅ 正确
data = {"name": '他说"你好"'}
json.dump(data, f, ensure_ascii=False)

常见场景策略

场景	❌ 错误做法	✅ 正确做法
全表搜索	一次性query全表	分批 --limit 100 --offset N
修改某列	读取整行 select *	只读主键+目标列 --columns "id,gold"
验证结果	修改后query全表	查看 --dry_run 的 diff 字段