Skip to content

feat(export): 新增 Cocos Creator 2D 一键导入 - #494

Open
xyh202131 wants to merge 1 commit into
1024XEngineer:mainfrom
xyh202131:feat/directional-generation-backend
Open

feat(export): 新增 Cocos Creator 2D 一键导入#494
xyh202131 wants to merge 1 commit into
1024XEngineer:mainfrom
xyh202131:feat/directional-generation-backend

Conversation

@xyh202131

@xyh202131 xyh202131 commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

改动概述

为 Windup 增加 Cocos Creator 3.8.8 2D 资产一键导入能力：

  • 网页端新增 Cocos Creator 导出目标、配对、进度展示和失败后下载回退。
  • 提供 Creator 扩展，在本机通过六位连接码完成授权，并把资产事务式写入当前工程。
  • 生成 Creator 可识别的纹理、SpriteFrame、AnimationClip、Prefab 与稳定 .meta。
  • 增加 ZIP 完整性、路径穿越、容量上限、来源校验、任务幂等和失败回滚保护。
  • 保留命令行导入方式，并提供可重建、可校验的扩展源码和打包脚本。
  • 修复旧版资产显示名与实际导出目录不一致时的导入失败，兼容方向与重名后缀。

验收结果

  • 使用真实“网站看板娘-46-默认造型”2D 资产在 Cocos Creator 3.8.8 中连续导入 2 次。
  • 每次导入均得到 64 张 256×256 RGBA8 帧、2 个动画和 1 个 Prefab。
  • 重复导入更新同一目录，动画时序、引用、锚点和资源 UUID 校验通过。
  • 前端：70 个测试文件、943 项测试通过。
  • 覆盖率：语句 92.65%、分支 87.42%、函数 94.87%、行 95.56%。
  • 导入器 51 项测试、Creator 扩展 31 项测试通过。
  • 格式检查、静态检查、类型检查、生产构建和扩展安装包校验通过。

范围说明

本 PR 不修改后端。未包含内部过程文档、构建压缩包、本地记忆文件和测试临时输出。

Closes #94

@vercel

vercel Bot commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
windup Ready Ready Preview Aug 24, 2026 6:19am

@github-actions

github-actions Bot commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ 此 PR 已关联 issue，之前的提醒已自动标记为已解决。

@codecov

codecov Bot commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.61977% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...ntend/src/features/export-package/export-panel.tsx 98.95% 0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

fennoai[bot]
fennoai Bot reviewed Aug 20, 2026
View reviewed changes

@fennoai fennoai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

本次重点核对了网页桥接、导出清单、旧包兼容路径、Creator 扩展的事务/回滚以及生成资产引用。扩展与清单的聚焦测试通过，但旧版通用包转换在带方向或需清洗名称的动作上会构造错误的帧目录，导致导入直接失败。

验证：扩展/清单/规划/UUID 共 65 项测试通过；最小复现返回 IMPORT_SOURCE_MISSING: frames/Walk / Forward/Walk-Forward-south_000.png。完整前端测试因当前工作区依赖可执行权限问题未能运行。

View job run

Comment thread tools/cocos-importer/src/manifest-reader.js Outdated
@huyanxius

huyanxius commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator

建议拆几个 PR,这个没法review

@huyanxius
huyanxius self-requested a review August 20, 2026 12:34
@vercel

vercel Bot commented Aug 20, 2026

Copy link
Copy Markdown

Deployment failed for project windup with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/huyan-s-projects1?upgradeToPro=build-rate-limit

huyanxius
huyanxius requested changes Aug 21, 2026
View reviewed changes
Comment thread docs/superpowers/plans/2026-08-20-cocos-one-click-export.md Outdated
Comment thread docs/superpowers/specs/2026-08-20-cocos-web-one-click-import-design.md Outdated
Comment thread tools/cocos-importer/dist/windup-cocos-importer.zip Outdated
@huyanxius

huyanxius commented Aug 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

@fennoai 扫描一下本次提交还夹带了什么与代码无关内容，如文档和压缩包

@fennoai

fennoai Bot commented Aug 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

扫描结果

已按固定范围 0b1e5acd6fa62988dff453161cb09773ecdc0731...0577c89aadeeb13efc697df278940fe41576f6c7 检查本次 PR 的 52 个文件。

  • 设计/过程文档（3 个）：
    • docs/superpowers/plans/2026-08-20-cocos-one-click-export.md（8.3 KB）
    • docs/superpowers/plans/2026-08-20-cocos-web-one-click-import.md（19.1 KB）
    • docs/superpowers/specs/2026-08-20-cocos-web-one-click-import-design.md（8.1 KB）
    • 其中 cocos-one-click-export.md 文件内明确标注“已被取代”，属于早期“下载 ZIP + CLI 导入”方案的历史计划；如果只保留当前方案文档，它是最明显的可清理项。其余两份直接对应本 PR 的设计和实施过程。
  • README（2 个）：frontend/src/features/export-package/README.md、tools/cocos-importer/README.md，内容均为当前功能的使用/架构说明，不属于无关文档。
  • 压缩包（1 个）：tools/cocos-importer/dist/windup-cocos-importer.zip，大小 75,310 bytes，包含 16 个 Cocos 扩展安装文件。它是生成的可直接安装扩展包，与 PR 描述中的“附带可直接安装的扩展包”一致，不是无关文件；但它属于二进制发布产物，会增加审查和仓库体积负担，可考虑改为 Release/CI 产物。
  • tools/cocos-importer/extension/package.json 与 tools/cocos-importer/package.json 是功能所需的包元数据，不算夹带内容。
  • 未发现其他图片、字体、日志、coverage、构建目录或测试临时输出；其余 .ts/.tsx/.js/.mjs 及测试文件均直接服务于该功能。

已运行扩展包校验：verify-package.mjs 报告 OK，压缩包结构完整。

@huyanxius

huyanxius commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

扫描结果

已按固定范围 0b1e5acd6fa62988dff453161cb09773ecdc0731...0577c89aadeeb13efc697df278940fe41576f6c7 检查本次 PR 的 52 个文件。

  • 设计/过程文档（3 个）：

    • docs/superpowers/plans/2026-08-20-cocos-one-click-export.md（8.3 KB）
    • docs/superpowers/plans/2026-08-20-cocos-web-one-click-import.md（19.1 KB）
    • docs/superpowers/specs/2026-08-20-cocos-web-one-click-import-design.md（8.1 KB）
    • 其中 cocos-one-click-export.md 文件内明确标注“已被取代”，属于早期“下载 ZIP + CLI 导入”方案的历史计划；如果只保留当前方案文档，它是最明显的可清理项。其余两份直接对应本 PR 的设计和实施过程。

  • README（2 个）：frontend/src/features/export-package/README.md、tools/cocos-importer/README.md，内容均为当前功能的使用/架构说明，不属于无关文档。

  • 压缩包（1 个）：tools/cocos-importer/dist/windup-cocos-importer.zip，大小 75,310 bytes，包含 16 个 Cocos 扩展安装文件。它是生成的可直接安装扩展包，与 PR 描述中的“附带可直接安装的扩展包”一致，不是无关文件；但它属于二进制发布产物，会增加审查和仓库体积负担，可考虑改为 Release/CI 产物。

  • tools/cocos-importer/extension/package.json 与 tools/cocos-importer/package.json 是功能所需的包元数据，不算夹带内容。

  • 未发现其他图片、字体、日志、coverage、构建目录或测试临时输出；其余 .ts/.tsx/.js/.mjs 及测试文件均直接服务于该功能。

已运行扩展包校验：verify-package.mjs 报告 OK，压缩包结构完整。

@删除掉无关文档，直接在本 PR 上修改

@minorcell

minorcell commented Aug 24, 2026

Copy link
Copy Markdown
Member

@fennoai

这个 PR 看起来引入了很多非必要的内容吗？

是否是使用姿势错误了，那部分大量的 mjs、js 文件主要是？

@fennoai

fennoai Bot commented Aug 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

结论

当前最新版并不是夹带了很多无关内容，但这个 PR 的功能边界确实偏大，导致看起来很重。

最新 head 87c9a3f 已专门清理掉此前的 3 份过程/设计文档和提交进仓库的扩展 ZIP，并把 tools/cocos-importer/dist/、测试临时目录加入 .gitignore。因此当前固定 diff 是 49 个文件、+8103/-30 行，已没有压缩包、规划文档或其他明显构建产物。

大量 JS/MJS 是什么

tools/cocos-importer 实际上是一个运行在 Cocos Creator 本机侧的小型导入后端，不是网页前端的重复代码：

  • src/*.js：共享导入核心，约 1340 行。负责读取/校验 Windup ZIP、规划文件、生成 Cocos 的 .meta、SpriteFrame、AnimationClip 和 Prefab。
  • extension/source/*.js：Creator 扩展运行时，约 754 行。负责 localhost HTTP、六位码配对、任务状态、事务写盘、回滚和 AssetDB 调用。
  • bin/*.mjs：约 229 行，是同一导入核心的 CLI 回退入口，供 CI、离线排查或手动导入使用；正常“一键导入”不走它。
  • extension/scripts/*.mjs：约 135 行，只负责构建和校验可安装扩展包。
  • test/**/*.mjs：约 2340 行，是 Node 原生测试与验收工具，并非发布运行代码。

.js 与 .mjs 的选择本身没有问题：该目录使用 Node ESM，Creator 扩展源码直接以 JS 运行；测试用 .mjs 明确采用 ESM。这里也没有因为转译而同时提交 TS 源码和生成 JS，未发现成套重复实现。

为什么必须有本机扩展

如果目标确实是“网页点一下，直接写入当前 Creator 工程并刷新 AssetDB”，这个使用姿势基本正确。浏览器本身不能安全地写本机工程目录，也不能调用 Creator 的 AssetDB，所以必须有 Creator 扩展或独立桌面服务作为本机桥接。配对、来源校验、容量限制、事务写入和回滚也解释了为什么它不只是一个几十行的导出适配器。

反过来，如果需求只是“网页下载一个 Cocos 格式 ZIP，由用户自行导入”，那么当前方案就明显过重，可以完全移除 localhost 桥接、配对、任务管理和事务导入层。

真正可讨论的精简项

  • CLI 回退可拆分：bin/windup-cocos-import.mjs 及其 E2E 测试不是网页一键导入的必需路径；如果项目不需要 CI/离线导入，可单独 PR 或删除。
  • 3 个手工验收脚本可拆分：creator-runtime-check.mjs、snapshot-uuids.mjs、verify-output.mjs 共约 572 行，不在默认 npm test 中，属于真实 Creator 验收工具。它们相关，但不是应用运行必需内容，建议至少移到明确的 scripts/verification/，或随验收说明单独提交。
  • 建议拆 PR，而非认定代码无关：可以拆成“前端导出协议”“纯 Node 导入核心/CLI”“Creator 一键导入扩展”三部分，审查会清楚很多。

总体数据上，前端与导入器测试合计约 4496 行，占新增行数 55%。所以体量大的主要原因是“一次实现了完整本机扩展 + 回退 CLI + 大量安全/回滚测试”，不是大量生成代码或无关文件。我的判断是：技术路线没有明显用错，但 scope 过宽；优先拆 CLI 和手工验收工具，而不是删除核心 .js/.mjs。

View job run

@xyh202131

xyh202131 commented Aug 24, 2026

Copy link
Copy Markdown
Contributor Author

@fennoai

这个 PR 看起来引入了很多非必要的内容吗？

是否是使用姿势错误了，那部分大量的 mjs、js 文件主要是？

还在看要不要做这个导出机制，因为需要本地搭建桥接，反而可能会更加复杂

@fennoai

fennoai Bot commented Aug 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

建议

你的顾虑是成立的。如果目前还没有明确、频繁的“一键导入”使用需求，我不建议现在就合入浏览器 → localhost → Creator 的完整桥接。

这里需要区分两件事：

  • Cocos 资源转换本身仍然需要实现：Windup 图片和 manifest 要转成 Creator 可识别的 .meta、SpriteFrame、AnimationClip、Prefab，并刷新 AssetDB。这部分复杂度基本躲不掉。
  • 浏览器一键桥接是额外的体验层：HTTP 服务、固定端口、配对码、来源/CORS、token、上传校验、任务轮询、进度 UI、幂等和错误恢复。它并不创造新的导出能力，只是少了用户几次点击。

扩展当前会自动启动本机服务，用户不是手工部署一个独立后端；但项目仍要长期承担端口冲突、浏览器私网访问策略、跨域、安全边界、Creator 生命周期和版本兼容等维护成本。对于低频导出场景，这个交换通常不划算。

推荐的中间方案

建议先做成：

  1. 网页生成并下载 Cocos 导入包。
  2. 用户首次安装 Creator 扩展。
  3. 在 Creator 菜单点击“导入 Windup 包”，通过文件选择器选中 ZIP。
  4. 扩展继续负责事务写入、AssetDB 刷新、引用校验、回滚和 Prefab 定位。

这仍然保留了真正有价值、容易出错的 Creator 原生导入逻辑，只把“网页自动找到并上传给本机扩展”改成用户手动选包。体验多一两步，但不再需要常驻 HTTP 服务和配对机制。

当前 PR 可如何收敛

建议保留：

  • cocos-target.ts：网页生成 Cocos manifest。
  • tools/cocos-importer/src/*.js：ZIP 校验、资源规划和 Cocos 文件生成核心。
  • creator-assets.js、import-job.js：AssetDB 操作、事务写入与回滚。
  • 与上述核心行为直接相关的测试。

建议暂缓或移出本 PR：

  • 前端 cocos-bridge-client.ts、cocos-one-click.ts 及配对/轮询 UI。
  • 扩展 http-server.js、pairing-store.js、import-jobs.js、protocol.js。
  • 对应的 HTTP、配对、浏览器桥接测试。
  • CLI 回退也可以单独判断；它不是 Creator 扩展手动导入的必要条件。

仅桥接直接相关的生产文件目前就约 852 行，加上前后端对应测试和 UI，实际可以减少更多。资源生成核心不需要因为取消桥接而推倒重来。

产品判断

  • 如果用户一天会在网页与 Creator 之间反复导入多次，一键桥接有价值，可以在手动导入方案验证稳定后再加。
  • 如果只是资产完成后偶尔导入一次，下载 ZIP + Creator 扩展选包会更稳、更容易理解，也更容易维护。
  • 如果现在连 Cocos 导出是否有人使用都还在验证，建议不要先承担完整桥接的长期成本。

所以我的推荐不是放弃 Cocos 导出，而是把当前 PR 从“完整一键导入系统”降级为“可验证的 Cocos 导出格式 + Creator 内手动导入扩展”。先证明导出格式和实际工作流有价值，再单独做一键桥接，会比当前一次合入全部机制更合适。

View job run

@xyh202131
xyh202131 force-pushed the feat/directional-generation-backend branch from 87c9a3f to 5eb2b50 Compare August 24, 2026 06:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fennoai fennoai[bot] fennoai[bot] left review comments
@huyanxius huyanxius huyanxius requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

导出产物契约与 Cocos 适配（Refs #37 §3.9）

3 participants

@xyh202131 @huyanxius @minorcell