luban-table是一个 Agent Skill让 AI 助手能规范地读写本工程Luban的配置表xlsx 文件而不会破坏表结构。在我的实际使用中经常出现 LLM 读写表的时候想当然没有按照特定的规则来读写表导致表格错误而且也不会每次都自动验证。因此这里我的方案就是拒绝 AI 直接读写配置表而是通过这个 Luban Skill 来实现数据表的读写外部只会接触表格的 Json 结构化数据。AI 再怎么折腾也不会把你的 xlsx 搞坏。一、问题为什么不能直接改 xlsxxlsx 不是一个普通文本文件它内部是多张工作表sheet带格式的单元格合并、颜色、字体多级表头##var/##type/##comment/##group多行字段一个主键对应多行数据Luban 用这些格式表达表结构。一旦 AI 误改、漏改、顺序错了Luban 就读不出这张表——整张配置作废所有用这张表的代码都报错。而且Luban 有一些特殊的格式AI 不是每次都能正确识别需要一个专业的 “翻译官” 来告诉 AI 正确的表格结构和数据。二、核心思路让 AI 改 JSONCLI 改 xlsx两大世界中间翻译AI只跟 JSON 打交道写命令用 JSON 参数、读数据看 JSON 对象CLILuban Skill负责 JSON 与 xlsx 之间的转换写、读、刷新三、关键设计3.1 自动表名识别#前缀Luban 的__tables__.xlsx是表注册表。新加一张表本来要在那里登记一行。我们的简化文件名以#开头 自动注册成表。子目录 命名空间虽然对于编辑配置表的 AI 来说命名空间并没有什么实际意义。好处新建表 复制一份 xlsx 改文件名无需懂 Luban 注册表命名空间一目了然子目录结构 命名空间结构注册表永远是空的不会被搞乱3.2 JSON 面向对象解决多行字段问题最棘手的情况一张表的一行在 xlsx 里其实是多行多行字段元素是结构体。AI 看到的JSON 视角{ id: 1, rewards: [ {ItemID: 1001, Count: 3}, {ItemID: 1002, Count: 5} ] }xlsx 里实际长这样行1: ##var id *rewards 行2: ##var ItemID Count 行3: ##type int (array#sep,),ItemSet 行4: ##comment 主键 道具列表 行5: 数据 1 1001 3 行6: 数据 1002 5 ← 续行设计原则AI 永远只看到 JSON 对象CLI 负责展开和收起。判定续行的规则最简单的一条一行里所有非 * 字段都为空→ 续行否则 → 新记录3.3 写后自动刷新 JSONxlsx 改了JSON 怎么办每次 CLI 写完 xlsx立刻调一次gen_json.bat重新生成 JSON。否则下次读到的还是旧数据AI 会写出覆盖式的修改。然后每次当需要对配置表进行读写调用时也会比对版本号重新生成 JSON 文件。完全无感AI 不需要管这件事。3.4 表引用关系与拓扑策划想看哪张表被谁引用生成顺序是有没有环关系数据不放进 xlsx避免污染 Luban 导入单独存为Data/__relations__.jsonCLI 暴露三个命令rel-add/rel-remove维护关系rel-list看关系topo计算依赖图被引用方在前四、硬性规则红线规则为什么 禁止直接动 xlsx会破坏表头整表作废✅ 写完必validate兜底防止半成品数据上线 命名用 snake_caseLuban 生成 C# 自动转 PascalCase#表名用#前缀触发自动注册⚠️ 多行表不用add-field改表头太复杂统一用 export/import五、一图流完整数据流写入流Agent 提交 JSON 命令 → CLI 改 xlsx → gen_json.bat 刷新 JSON读取流Agent 读命令 → CLI 读 output/table_json/*.json → 返 JSON 对象