适用引擎：Cocos Creator 3.8.0 及以上 ｜ 当前版本：v3.1.6

✨ 功能特性

1. Schema 模板驱动，不是"读个 Excel"

  • 内置 7 套标准模板：道具、关卡、任务、商城、Buff、多语言、自定义（带基础字段，可自由扩展）。
  • 模板自带默认字段、校验规则与引用关系 —— 新表一建立，规矩就已经在那儿了。
  • 字段设计器：可视化增删字段、拖拽排序、配别名 / 默认值 / 数值范围 / 枚举项 / 正则 / 非空 / 唯一（支持多字段组合唯一）/ 资源类型 / 引用表与引用键。
  • 9 种字段类型：字符串、整数、浮点、布尔、枚举、数组、对象（可嵌套编辑）、资源、主键 ID。

2. 真实资源校验（核心卖点）

  • 表里填的图片、音效、Prefab、Spine、字体、材质、动画等路径，不当作字符串看 —— 拿去和当前 Cocos 工程真实的资源库比对一次，找不到就当场标红。
  • 支持 db://assets/... 与工程相对路径；错误出现在填表当天下午，而不是测试第二天早上。

3. 一整套数据校验 + 跨表引用

  • 规则校验：非空、唯一、组合唯一、数值范围、数组元素类型、枚举合法值、正则。
  • 跨表校验：字段上声明引用（如商城 itemId → 道具 id），点一下跑全工作区，指向不存在的 id 当场报红 —— 表与表之间的错误，才是最贵的那一类。
  • 校验报告逐条给出表名 / 行号 / 字段 / 原因，点击定位到行。

4. 导入既有 Excel，不允许"稀里糊涂覆盖"

  • 支持导入 Excel / CSV / JSON / TS（TS 走生成式常量反解析，支持 round-trip）。
  • 表头按字段名或中文别名匹配：写 id、ID、"编号"都能对上；#、// 开头的注释行列自动跳过；未命中的列忽略。
  • 拖拽导入有嗅探确认弹窗：把 Excel / CSV / JSON 拖进面板会先告诉你"识别到了什么、准备怎么写"，你确认了才落库 —— 辛苦配过的表，不该被一次误拖干掉。

5. 导出：多格式 + 增量 + 可回溯

  • 格式：json / ts / csv / excel / bin（bin 为紧凑二进制，YKT1 布局公开，体积更小、解析更快）。
  • 目录分流干净：数据 → assets/resources/yyka_table_config/，TS 类型与运行时 → assets/scripts/yyka_table_config/；导出成功后自动刷新编辑器资源库，不用手动切前后台。
  • 增量导出：按内容哈希比对，只重导变更的表，大项目从"全量等半天"变成"秒级"。
  • 导出前自动备份：按时间戳归档上一版产物，面板里可浏览与一键恢复；CSV 为 UTF-8/BOM + 引号转义 + 稳定列序，Git diff 友好。

6. 强类型 TS：数据不进代码，分表懒加载

  • 导出一张表得到三份产物：item.json（纯数据）、item.ts（类型 + 加载函数）、ykTableRuntime.ts（运行时）。
  • 自动生成 ItemConfig 接口与 loadItem() / getItem(1) / getAllItem() 异步访问函数，数据不内联进 TS —— 改数据不用重编译大模块，编译与包体都不背这份体积。
  • 新增「导出示例脚本」：一键生成 YKTableBootstrap.ts 引导组件，挂到场景节点即可完成 YKTableData.setReader(...) 注册，之后项目里任意脚本都能 await getItem(1) 强类型取数（键自动补全）。

7. 编辑器内全流程面板

  • 左侧边栏：概览 / 配表 / 导出 / MCP / 设置 / 关于；深色默认 + 浅色开关。
  • 配表页表格增删改查、字段设计器、导入弹窗、校验报告、日志停靠条，日常配表不用离开 Cocos。

8. 命令行 CLI（CI / 无编辑器）

bash 复制代码 
# 工作区所有表导出 json + ts + bin
node bin/yyka-export.mjs --workspace ./ws --out ./dist --formats json,ts,bin

# 只导 item，开增量与备份
node bin/yyka-export.mjs --workspace ./ws --tables item --formats json,bin --incremental --backup
  • 支持 --workspace / --out / --tables / --formats / --state / --incremental / --backup；有错返回非 0 退出码，可直接卡住 CI 流水线（仓库内附示例 workflow）。

9. 打包联动（Cocos 独有）

  • 作为自定义构建扩展接入 editor:build 前置钩子：打包前自动跑「全表校验 + 资源真实校验 + 导出」，任一失败阻断打包并回传错误 —— 让配表的错误出现在打包之前，而不是上线之后。

10. MCP 服务：让 AI / 脚本直接配表

  • 双模式传输：stdio + Streamable HTTP，面板内一键启停、可配端口、可选 Bearer Token 鉴权、支持一键复制标准 mcpServers 连接配置。
  • 8 个工具：列模板、一键建表、按 Schema 生成仿真数据、整表校验、跨表校验、导出（增量/备份）、行级增删改（支持按主键定位）、读取操作日志。
  • 收发日志在面板可视化，方便判断"是模型写错了，还是工具没接上"。

11. 开箱即用的示例与文档

  • examples/ 完整示例工程（工作区 + 待导入 CSV + 导出脚本 + 消费侧代码），docs/ 含 3 分钟演示脚本与开发文档。

📋 使用说明

① 安装

  1. 把扩展包放进全局扩展目录（Windows：%USERPROFILE%\.CocosCreator\extensions）或工程的 extensions 目录；
  2. 打开 Cocos Creator → 扩展 → 扩展管理器 → 刷新 → 在列表里点启用；
  3. 菜单 YYKA插件 → YYKA配表设计转换插件 打开面板。

② 建表 → 设计字段

  1. 「配表」页 → 新建表 → 选模板（道具 / 关卡 / 任务 / 商城 / Buff / 多语言 / 自定义）→ 填表名 → 创建。
  2. 进字段设计器：加字段、选类型、拖拽排序、配别名 / 范围 / 枚举 / 非空 / 唯一；需要外键就填"引用表 + 引用键"。

③ 填数据（录入或导入）

  1. 表格里直接增删改行；
  2. 或点「导入」选 Excel / CSV / JSON / TS，也可直接把文件拖进面板：先看嗅探确认弹窗（识别到什么表、哪些列命中、注释行列如何跳过），确认后写入。

④ 校验

  1. 点「校验」：规则 + 资源真实存在性 + 跨表引用一次跑完；报告逐条列出表 / 行 / 字段 / 原因，点一下跳到那一行。有错先改再导。

⑤ 导出

  1. 「导出」页勾格式（json / ts / csv / excel / bin），按需开启增量导出与导出前备份 → 导出；备份可在同一页浏览与恢复。
  2. 需要示例工程代码就点「导出示例脚本」，会生成 YKTableBootstrap.ts（挂节点即完成读取注册）。

⑥ 在工程里用起来

ts 复制代码 
import { YKTableData } from './yyka_table_config/ykTableRuntime';
import { loadItem, getItem } from './yyka_table_config/item';

// 入口处一次性注册（Cocos 用 resources.load 读 yyka_table_config 目录）
YKTableData.setReader((relPath) => resources.load(`yyka_table_config/${relPath}`, ...));

const itemMap = await loadItem();   // Record<number, ItemConfig>
const sword   = await getItem(1);   // ItemConfig | undefined

⑦ 自动化（按需）

  1. CI：node bin/yyka-export.mjs --workspace ./ws --formats json,ts --incremental --backup，接进流水线。
  2. AI / MCP：「MCP」页 → 启动服务 → 复制连接配置；HTTP 模式连 http://127.0.0.1:17320/mcp，或 stdio 模式直接拉起 server.js。端口、工作区、Token 都在页面里改。

⚙️ 引擎与环境要求

项目 要求
引擎版本 Cocos Creator 3.8.0 及以上（已在 3.8.x 上实测全流程）
面板尺寸 最小 1280 × 720，dockable 可停靠
操作系统 Windows 10/11 已实测；macOS 遵循 Cocos 官方扩展规范（未实测）
Node.js 仅 CLI（bin/yyka-export.mjs） 与 stdio 模式 MCP 需要 Node 18+；编辑器内使用编辑器自带运行时
依赖 插件 release 自带运行依赖（xlsx 等），无需你自己装包
网络 全程本地：MCP 只监听 127.0.0.1，支持 Token 鉴权；配表数据与素材不出发你的机器
权限 项目目录读写（工作区、assets/resources、assets/scripts）

🖥️ 平台支持情况

  • 编辑器侧（插件本体）：Windows 10/11 ✅ 实测；macOS 依据 Cocos 官方扩展与面板机制理论可用（未实测，有问题欢迎反馈）。
  • 产物侧（与插件无关，跨平台）：导出的 json / ts / csv / excel / bin 是纯数据与代码，Web、iOS、Android、Windows、macOS、各类小游戏平台都能直接读，不依赖任何平台特性。
  • CLI / MCP 侧：本机运行，与目标平台无关；CI 可跑在任意支持 Node 18+ 的构建机上。

📜 更新日志

v3.1.x 系列（当前 v3.1.6）

  • 拖拽导入嗅探确认弹窗：拖文件进面板先确认再落库，杜绝误拖覆盖。
  • 新增「导出示例脚本」：生成 YKTableBootstrap.ts 引导组件，挂节点即完成配表读取注册。
  • 新增导出备份浏览与一键恢复，误操作可回退。
  • 新增 bin 紧凑二进制导出格式（YKT1 布局，体积更小、解析更快）。
  • 新增独立 CLI（bin/yyka-export.mjs）与 CI 示例 workflow，无编辑器也能导表。
  • MCP 支持 stdio + HTTP 双模式、Bearer Token 鉴权与一键复制连接配置。
  • 对象 / 数组字段支持嵌套可视化编辑。
  • 面板新增关于页、深浅主题切换；导出后自动刷新资源库。
  • 健壮性：工作区根目录混入非配表 json 时，跨表校验与全量导出不再整体失败。

3.0.x 系列

  • TS 产物改为「接口 + 异步加载函数」：loadXxx() / getXxx(key) / getAllXxx()，数据不再内联进 TS，也不再向 assets/scripts 写同名 json，勾选 ts 时自动补产数据 json。
  • 数据 json 统一落在 assets/resources/yyka_table_config/，运行时 ykTableRuntime.ts 随 ts 产物写入类型目录。
  • 导出成功后自动刷新编辑器资源库。

1.3.x 系列（MCP 与数据安全加固）

  • 重复建表不再清空已有行（返回"已存在，跳过创建"）。
  • 生成数据时的占位素材不再覆盖同名真实素材（改为不存在才创建，图片写真实 1×1 PNG）。
  • 操作日志失败只记一条，不再出现"先成功后失败"的矛盾记录。
  • 行级增删改支持按主键定位（key 优先于 index）。
  • MCP Bearer Token 鉴权 + 一键复制连接配置。

1.2.x 系列（面板与 MCP 可启动）

  • 左侧边栏布局（概览 / 配表 / 导出 / MCP / 设置）、首页功能全景卡片墙。
  • MCP 工作台：配置保存、在线探测、8 工具清单、操作日志可视化；面板一键启停 MCP 服务。
  • 深色 / 浅色主题修复（弹层不透明、菜单跟随主题）。

1.0.x–1.1.x 系列（打底）

  • Schema 模板驱动、资源真实校验、多格式导入导出、强类型 TS 生成、编辑器内 CRUD、打包前置自动校验。
  • MCP 双模式服务与 8 个工具；构建时版本号自动递增。
  • release 自包含（自带运行依赖），安装即用。

❓ 常见问题 FAQ

Q1：导出成功，但游戏里读不到数据？
A：确认三点：① 数据在 assets/resources/yyka_table_config/ 下（必须在 resources 目录内才能被 resources.load 读到）；② 入口处注册过 YKTableData.setReader(...)（可直接用「导出示例脚本」生成的 YKTableBootstrap.ts）；③ 加载路径形如 yyka_table_config/item.json。

Q2：校验报"资源不存在"，可我的图明明在工程里？
A：路径要写成工程相对路径（assets/ai/icon1.png）或 db:// 形式，不能是绝对路径或工程外路径。校验按当前工程的真实资源库比对，写对即通过。

Q3：拖文件进面板会不会直接把我的表覆盖了？
A：不会。拖拽导入会先弹出嗅探确认弹窗，告诉你识别到的目标和列映射，确认后才写；表格导入同样是"预览确认后写入"。

Q4：Excel 导入后列对不上？
A：导入按"字段名或字段中文别名"匹配表头。给字段配好中文别名，或把 Excel 表头改成字段名；#、// 开头的注释行列会自动跳过，未命中的列被忽略，导入前有预览可核对。

Q5：ts 导出会把整张表的数据塞进代码吗？会不会拖慢编译和包体？
A：不会。TS 只生成类型 + 加载函数，数据留在 json 里按需异步加载；类型负责让 item.name、枚举值在编辑器里可提示、可查错（注意：类型拦不住 JSON 内容错误，那由校验环节负责）。

Q6：增量导出怎么判断该不该重导？
A：按每张表的内容哈希与上次导出记录比对，内容未变就跳过，只有改过的表重导。首次开启增量时会全量导一次并写入状态文件。

Q7：备份在哪？怎么恢复？
A：按时间戳归档在工作区的 export/backup/<时间戳>/ 下，导出页可浏览并一键恢复。

Q8：MCP 对外网开放吗？AI 怎么接？
A：不开放，只监听 127.0.0.1（可加 Bearer Token）。接法两种：HTTP 模式填 url: http://127.0.0.1:17320/mcp；或 stdio 模式用 node 拉起 server.js。MCP 页有「复制连接配置」按钮，直接生成标准 mcpServers 片段。

Q9：MCP 生成数据有上限吗？
A：单次生成上限 200 行，且会返回全表数据（避免一次调用把工程写爆）。要大批量，走 CLI + 增量导出更稳。

Q10：支持哪些 Creator 版本？2.x 能用吗？
A：仅 Cocos Creator 3.8.0 及以上。3.7 及更早、2.x 未适配。

Q11：需要联网 / 会把我的配表传到云端吗？
A：不需要，也没有云端。工作区就在你的工程目录里，团队协作靠 Git 传文件，数据不出你的机器。

Q12：bin 格式怎么用？
A：bin 是紧凑二进制导出（表头 + 紧凑记录，YKT1 布局），适合对体积与加载速度敏感的场景；布局在插件源码 binExporter 中公开，可自行解析或扩展。

⚠️ 购买须知

本产品为付费虚拟插件商品，一经购买成功概不退款，请支付前谨慎确认购买内容。

  • 购买后获得对应版本授权，仅限授权范围内使用；
  • 插件仅支持标注的 Cocos Creator 版本，请确认引擎版本符合要求再下单；
  • 不包含定制开发服务，如有定制需求可单独咨询；
  • 严禁二次分发、转售、反编译本插件。

📞 联系我们

如遇问题、有定制需求或希望增加动画 / 功能，欢迎联系作者：

关键词（商店后台标签）

Cocos Creator Cocos Creator 插件 Cocos 3.8 配表工具 配置表 Excel 导表 数据表设计 Schema 模板 TypeScript 代码生成 强类型配置 资源校验 跨表校验 增量导出 导出备份 JSON 导出 二进制导出 命令行导表 CI 自动化 MCP AI 配表 游戏开发工具 策划工具 程序工具 提效工具 本地运行 无云端

感谢用户的内容

做这个插件的起点很朴素：受够了"改一列、翻十个文件、跑起来才发现资源路径写错"。

谢谢每一位把它放进自己项目里的你。你们提的"重复建表别把我的数据清了""生成素材别覆盖我的图""导出目录要记住上次的选择""校验要按工程真实路径来"，都一条条变成了版本记录 —— 这个插件现在的样子，是你们用出来的。

它现在确实还做不到所有事：只管配表链路，不碰引擎行为；资源校验只判"存在性"，替不了你判断美术风格。这些边界我们写在明处，省得你装了之后觉得被骗。

如果它帮你省下了几个凌晨三点，那就值了。有问题、想加功能、或者只是想说一句"这里不好用"，都欢迎直接找我们 —— 每一条反馈都会被看见。

祝你导表顺利，早点下班。