real2sim-platform/docs/open-source-launch.md
eust-w 56f124fab1
Some checks failed
CI / workbench (push) Has been cancelled
🚀 Release reproducible Real2Sim Studio alpha workbench
2026-10-28 01:13:52 +08:00

124 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Real2Sim 开源首发与视频方案
核查日期:2026-10-26。代码基线:`3e4c2f4`。
本文保留 2026-10-26 的发布前基线,表内“当前”均指该次核查,不是最新状态。后续实现、验证与限制见 [v0.1.0 Alpha 发布说明](releases/v0.1.0-alpha.1.md);平台实际发布证据单独记录,不以本方案作为已发布证明。
## 判断与定位
项目具备开源工具的基础,但当前应定位为早期工作台。成为有影响力的开源项目,需要真实可复现的使用价值、清楚的技术边界和持续维护,不能由一次宣传或 Star 数承诺保证。
建议展示名:**Real2Sim Studio**,暂保留仓库名 `real2sim-platform`。
当前可用介绍:
> 一个开源准备中的 3D 资产工作台,连接 Tripo 生成、本地资产预览、材料参数配置和 Genesis 场景包导出。
首发目标定位:
> 面向具身智能开发者的可视化资产到仿真工作台,让第一个可运行案例更容易复现。
首要用户是需要把单个物体带入仿真的开发者和研究者。首版围绕一个完整案例展开,不同时承诺场景重建、机器人训练和多个仿真器。
当前生成依赖 DashScope / Tripo 服务;开源工作台不等于开源底层生成模型,也不等于免费生成。项目没有验证几何重建精度、实物材料参数辨识或 sim-to-real 效果。
## 已核查的状态
| 项目 | 本轮结果 | 能证明的范围 |
| --- | --- | --- |
| GitHub | `eust-w/real2sim-platform` 当前 PRIVATE,无许可证 | 还未成为公开授权的开源仓库 |
| 工作区 | 核查前干净 | 本轮方案以当前提交为基线 |
| 功能代码 | 文本 / 单图 / 多图生成、任务管理、缓存、GLB 预览、配置和 Genesis 导出 | 代码具备这些路径,未重新调用付费生成接口 |
| 单元测试 | 3 个文件、7 个测试通过 | 资产缓存、配置和导出包逻辑;不含真实 Genesis 执行 |
| lint / build | 均通过 | 编译与静态检查通过;构建仍提示较大的 JS bundle |
| 本地任务 | 5 条历史任务,其中 2 条记录有本地模型 URL | 可作为后续检查素材的候选,不证明素材权利或仿真成功 |
| 生产依赖审计 | 5 个受影响依赖:1 critical、2 high、2 moderate | npm advisory 分级,不等同于已验证可利用 |
| 敏感文件路径历史 | 本地可达 Git 历史的指定路径检查只出现 `.env.example` | 尚未进行完整内容级历史密钥扫描 |
审计涉及 `proxy-addr`、`body-parser`、`zod`、`qs`、`fflate`;应结合实际调用路径更新和复验。
## 首发前优先处理
1. **修复本地资产到柔性任务的接口契约。** `src/App.tsx` 将本地 `/assets/...` 路径作为 `sourceModelUrl` 提交,而 `server/schemas.ts` 使用绝对 URL 校验。本轮直接调用 schema 已复现 `Invalid URL`。需要覆盖真实本地资产选择流程。
2. **让导出参数与 UI 一致。** `server/genesisPackage.ts` 的脚本生成固定使用 `-9.8`,忽略用户重力。还要核对 UI、flex profile 和 Genesis manifest 对 solver、单位和参数含义的约定。
3. **验证真正的 Genesis 执行。** 当前测试用几个字节代替 GLB,并检查生成的 Python 文本,不能证明四面体化、材质创建和求解运行成功。固定已验证的 Genesis 版本、运行环境和样例,保存运行命令、日志、视频及失败限制。
4. **明确预览与求解的区别。** `Viewport3D.tsx` 的 `SoftBody` 使用 `MeshDistortMaterial` 和周期缩放;它是视觉占位效果。已有 GLB 的 `AssetModel` 路径展示几何,并未执行浏览器物理求解。宣传中的柔体结果必须来自实际仿真录屏。
5. **补齐可复现的首次体验。** 提供可再分发的样例和无需 API Key 的样例模式;生成模式使用用户自己的 Key,并写清服务依赖和费用边界。记录全新环境的安装和运行结果。
6. **完成发布基础。** 明确代码和素材授权主体,选定 LICENSE,补第三方素材说明、英文首页与中文文档、CI、CONTRIBUTING、问题模板、路线图和版本说明。完成依赖修复及完整历史密钥检查。
开放源码与公开托管服务是不同交付。当前后端没有用户鉴权、配额或请求限流,且监听地址没有限制为 loopback;公开演示若连接维护者的付费 Key,需先解决访问和成本控制。首发优先采用本地运行与只读样例展示。
README 现在写着 GitHub 应为 private、Gitea 应为 public。确定开源发布策略后,需要同步更新这段约定;本轮未调整远端可见性。
## 差异化方向
EmbodiedGen 官方项目已经描述了多种生成后端、物理属性、跨仿真器导出及 Genesis 柔体示例。仅以“AI 生成 3D + 导出仿真”做介绍,差异不明显。
建议把工作集中在可验证的体验优势:
- 用户能从干净环境快速复现一个已验证案例,而不是自行调通许多组件。
- 同一资产的来源、尺寸、材料配置、导出版本和运行结果可以追溯。
- 失败时能明确指出问题发生在生成、网格、导出还是求解阶段。
- 后续将生成后端做成可替换适配器;首发先交付一个可靠路径。
这些是产品方向,尚不是当前已经实现的能力。
## 分阶段交付
| 阶段 | 具体交付 | 进入下一阶段的条件 |
| --- | --- | --- |
| 可运行案例 | 修复主流程、锁定仿真版本、一个有授权的样例、运行日志和实录 | 他人在干净环境按说明复现 |
| 开源发布包 | LICENSE、英文 README、中文指南、CI、样例、v0.1.0 说明 | 功能声明与证据一致,授权和密钥检查完成 |
| 视频成片 | 90 秒横版母片、竖版短片、中英文字幕、封面、发布文案 | 所有镜头来自本项目可验证的行为 |
| 对外首发 | GitHub Release 与选定账号发布;记录实际链接 | 仓库和下载入口可访问,各平台发布结果可核对 |
| 用户迭代 | 收集安装失败、仿真失败和复现反馈,完善贡献入口 | 用真实使用与贡献衡量价值 |
首轮观察目标可设为 10 位独立用户成功复现、3 条具体使用反馈,再争取外部贡献。它们是内部验证目标,不是效果保证。
## 90 秒主视频分镜
主题:**从 3D 资产到 Genesis:把生成、配置和导出串起来。**
以下分镜用于主流程修复和真实仿真验证之后。尚未录制的结果不能用生成式视频或浏览器占位动画替代。
| 时长 | 画面 | 旁白方向 |
| --- | --- | --- |
| 0–6 秒 | 同一个样例的输入、GLB 和 Genesis 运行结果并列 | “生成一个 3D 模型之后,怎样把它带进仿真?” |
| 6–16 秒 | 工作台全景与样例选择 | “Real2Sim Studio 把资产预览、材料配置和场景导出放在一起。” |
| 16–32 秒 | 实际生成记录、缓存结果和模型旋转 | “使用 Tripo 生成资产,再把模型保存在本地。” |
| 32–48 秒 | 参数配置、单位、导出的配置文件 | “选择材料并调整参数,导出模型、配置和 Genesis 脚本。” |
| 48–68 秒 | 执行包内命令,展示真实求解画面 | “这是这个样例在已验证环境中的运行结果。” |
| 68–80 秒 | 完整下载包、示例和复现命令 | “同一份样例和配置可以下载复现。” |
| 80–90 秒 | GitHub 地址、版本号、示例入口 | “代码与示例已开放,欢迎复现并反馈。” |
制作要求:
- 录屏时保留同一资产的身份和过程连续性;等待过程可剪辑,但标注加速或省略,耗时只报实测值。
- 参数对比必须重新运行真实仿真;未验证前不使用“物理准确”“一键任意物体”“世界首个”等描述。
- 把 `API generation`、`3D preview`、`Genesis simulation` 的画面阶段标清。
- 画面不包含 API Key、服务令牌、私人任务内容或内部页面。
- 片尾“已开源”只在仓库可见性和许可证发布完成后使用。
- 留存无字幕母片、中文 SRT、英文 SRT、配音音轨和素材来源记录,便于后续适配。
## 平台版本建议
以下是编辑方案,不是平台上传限制或流量保证;实际上传时再核对各账号当时支持的规格。
| 渠道 | 建议版本 | 内容侧重 |
| --- | --- | --- |
| GitHub README / Release | 10–20 秒循环演示,加 90 秒完整视频入口 | 能做什么、如何复现、当前限制 |
| B 站 / YouTube | 90 秒介绍,加独立 3–5 分钟复现教程 | 实际操作、环境和失败排查 |
| 抖音 / 视频号 / 小红书 | 30–45 秒竖版,重新排版而非直接裁切横屏 | 先展示结果,再讲一个使用场景 |
| X / LinkedIn | 30–60 秒英文字幕版本,加项目链接 | 开发者价值、贡献方向 |
| 公众号 / 知乎 | 视频配技术文章与运行步骤 | 技术边界、设计取舍和可复现证据 |
发布次序建议:先让 GitHub 代码和示例可用,再发布完整演示与教程,随后分发短版。每次发布保留平台、账号、文案版本、成片版本、实际 URL 和状态。
具体账号和首发平台尚未指定。本轮未连接社交账号、未上传视频。
## 参考依据
- [GitHub:仓库许可说明](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository):公开仓库需要明确开源许可,不能将可见性视为完整授权。
- [EmbodiedGen 官方仓库](https://github.com/HorizonRobotics/EmbodiedGen):用于核对相邻项目的能力与本项目差异化方向,不代表已完成运行对比。
- 本地证据:`README.md`、`src/App.tsx`、`src/components/Viewport3D.tsx`、`server/schemas.ts`、`server/flex.ts`、`server/genesisPackage.ts`、`server/genesisPackage.test.ts`。