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：计算依赖图（被引用方在前）
四、硬性规则（红线）
| 规则 | 为什么 |
|---|---|
| 🚫 禁止直接动 xlsx | 会破坏表头，整表作废 |
✅ 写完必 validate |
兜底，防止半成品数据上线 |
| 🐍 命名用 snake_case | Luban 生成 C# 自动转 PascalCase |
# 表名用 # 前缀 |
触发自动注册 |
⚠️ 多行表不用 add-field |
改表头太复杂，统一用 export/import |
五、一图流：完整数据流
写入流 ：Agent 提交 JSON 命令 → CLI 改 xlsx → gen_json.bat 刷新 JSON
读取流 ：Agent 读命令 → CLI 读 output/table_json/*.json → 返 JSON 对象