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 | 会破坏表头，整表作废 |
✅ 写完必 | 兜底，防止半成品数据上线 |
🐍 命名用 snake_case | Luban 生成 C# 自动转 PascalCase |
| 触发自动注册 |
⚠️ 多行表不用 | 改表头太复杂，统一用 export/import |
五、一图流：完整数据流
写入流：Agent 提交 JSON 命令 → CLI 改 xlsx → gen_json.bat 刷新 JSON
读取流：Agent 读命令 → CLI 读 output/table_json/*.json → 返 JSON 对象
技术前瞻)
