一个轮子：Luban Skill 制作演示

luban-table是一个 Agent Skill：让 AI 助手能规范地读写本工程（Luban）的配置表（xlsx 文件），而不会破坏表结构。在我的实际使用中，经常出现 LLM 读写表的时候想当然，没有按照特定的规则来读写表，导致表格错误，而且也不会每次都自动验证。因此这里我的方案就是拒绝 AI 直接读写配置表，而是通过这个 Luban Skill 来实现数据表的读写，外部只会接触表格的 Json 结构化数据。

AI 再怎么折腾，也不会把你的 xlsx 搞坏。

一、问题：为什么不能直接改 xlsx

xlsx 不是一个普通文本文件，它内部是：

• 多张工作表（sheet）

• 带格式的单元格（合并、颜色、字体）

• 多级表头（##var/##type/##comment/##group）

• 多行字段（一个主键对应多行数据）

Luban 用这些"格式"表达"表结构"。一旦 AI 误改、漏改、顺序错了，Luban 就读不出这张表——整张配置作废，所有用这张表的代码都报错。

而且，Luban 有一些特殊的格式，AI 不是每次都能正确识别，需要一个专业的 “翻译官” 来告诉 AI 正确的表格结构和数据。

二、核心思路：让 AI 改 JSON，CLI 改 xlsx

两大世界，中间翻译：

• AI只跟 JSON 打交道（写命令用 JSON 参数、读数据看 JSON 对象）

• CLI（Luban 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 写后自动刷新 JSON

xlsx 改了，JSON 怎么办？

每次 CLI 写完 xlsx，立刻调一次gen_json.bat重新生成 JSON。否则下次读到的还是旧数据，AI 会写出"覆盖式"的修改。然后每次当需要对配置表进行读写调用时，也会比对版本号重新生成 JSON 文件。

完全无感，AI 不需要管这件事。

3.4 表引用关系与拓扑

策划想看"哪张表被谁引用？生成顺序是？有没有环？"

关系数据不放进 xlsx（避免污染 Luban 导入），单独存为Data/__relations__.json：

CLI 暴露三个命令：

• rel-add/rel-remove：维护关系

• rel-list：看关系

• topo：计算依赖图（被引用方在前）

四、硬性规则（红线）

五、一图流：完整数据流

写入流：Agent 提交 JSON 命令 → CLI 改 xlsx → gen_json.bat 刷新 JSON

读取流：Agent 读命令 → CLI 读 output/table_json/*.json → 返 JSON 对象