Files
vibemake/README.md
T
2026-11-05 17:50:35 +08:00

18 KiB
Raw Blame History

vibemake 网站(静态版)

主站使用静态页面,仿真运行器需要先构建。three.js、urdf-loader、marked、DOMPurify 和字体都放在 vendor/(node scripts/vendor.mjs 下载),不依赖外部 CDN;3D 引擎只在需要的页面按需加载。

项目详情页统一采用 Robot Viewer 的光照和高光风格:白色主光 + 补光、半球光、Phong 高光材质、无色调映射和 PCF 柔和阴影,保留模型原色与已有 PBR 材质。原始 URDF 和压缩 GLB 使用相同规则;背景和地面保持原样。Phong 使用中性反射环境,已有 PBR 材质继续使用本地 assets/environments/monochrome_studio_02_1k.hdr(PMREM 过滤,加载失败时回退到程序棚拍环境)。移植来源与许可证见 vendor/robot-viewer/NOTICE。

本地运行

详情页的「行走演示」使用 sandbox/ 中的运动运行器,首次启动先运行:

npm ci
npm --prefix sandbox ci
npm run build:walking

开发环境部署执行 npm run build:dev,生成固定连接 dev 接口的 dist-dev.zip;线上部署执行 npm run build,生成按访问域名选择接口的 dist.zip。把压缩包内容直接解压到静态网站根目录。dist/、dist-dev/、play/ 和 deliverables/ 为本地产物,不提交 Git;生成仿真运行器所需的源码、素材和锁文件保存在 sandbox/。

生成 /play/robots/index.html(Robot Package 通用运行器)和 /play/microduck/index.html(旧版 Microduck 包)。两者由本站提供,按详情接口选择;关闭弹窗会释放仿真。修改沙盒后再次执行 npm run build:walking;npm run build 会自动构建并收录。默认暂停,点击开始后按住键盘 / 触摸方向键运动,松开停止。来源记录见 sandbox/NOTICE。

项目装配与行走资源

社区详情读取后端实际上传绑定:

  • modelGlbUrl:整机 GLB;保留源文件的材质、颜色与纹理。
  • assemblyJsonUrl + modelPartsFiles:装配步骤和零件清单,按 relativePath 对应文件的 url。不同批次上传的资源不共用目录,不能用步骤 JSON 的目录拼接零件地址。
  • walkingResourcesBaseUrl + walkingResourcesFiles:保持路径的运动文件夹;读取其中唯一的 robot.json。必需的是配套 MJCF、引用资源和基础 ONNX 策略,额外动作按配置显示。
  • 字段为空则隐藏对应入口;已删除按 Microban 项目编号注入本地样例的逻辑。

当前通用运行器支持 schema: 1 / adapter: generic、单个主 ONNX 控制器及可选 oscillator 关节动作。加载时校验配置、资源路径 / 大小、模型关节和策略输入输出;仅上传任意 ONNX 或任意 ZIP 不代表可运行。未支持的控制器会明确报错,不套用其他机器人的动作。旧 assemblyManifestUrl / walkingManifestUrl 继续兼容。具体接口和本次验证见 前台资源接口联调记录。

执行 npm run package:experiences 生成两个可上传 ZIP,输出到 deliverables/experience-packages/。装配样例属于 Microban,行走样例属于 Microduck。接口、格式与上传流程见 后端接入说明。

后台与社区下一版行走适配按 最低必传项 + 可选功能规范 和 功能目录配置 实施:基础行走只要求配套控制配置、物理模型及引用文件、行走策略;踢球等动作选填,前台按已发布功能展示。新 Robot Package 的基础行走与可选 oscillator 动作已接入;更复杂的技能运行器仍需扩展。旧 Microduck 的全部启动策略要求仅用于旧包兼容。

本地联调:node scripts/experience-fixtures.mjs 后访问 /examples/experience-preview.html,可填写清单地址或检查多零件步骤;此页面不随正式站点发布。协议回归:npm run test:experiences。

真实分件重组:npm run package:assembly-parts 使用用户提供的 ~/Downloads/glb分散零件/ 和 ~/Downloads/机器人.glb,按参考模型恢复 275 个零件的位置,逐件核对三角面和变换误差,输出 microban-parts-assembly.zip 与 microban-reassembled.glb。可传入 --parts / --reference 更换输入路径(算法会严格检查当前导出格式)。预览 /examples/experience-preview.html?assembly=parts;支持逐件播放、暂停和进度定位,保留分件自带材质。

手机与较低配置设备

  • 共用 js/render-budget.js:触屏或已知低核数 / 低内存设备默认 30 FPS,其他设备最多 60 FPS;限制 DPR 与总绘制像素,连续掉帧时逐级降低分辨率、关闭阴影,最低目标 24 FPS。设备信息仅作初始提示,实际帧耗时决定降档,不按 Windows / macOS 区分。
  • 详情静态模型、装配模型按需绘制;打开弹窗暂停底层模型,切到后台停止渲染与行走计算。暂停行走时保留相机操作,关闭弹窗释放 3D 资源 / 卸载仿真 iframe。
  • 旧 Microduck 行走策略使用单个 ONNX Worker;新通用运行器使用单线程 WASM 和串行控制调度,不积压或并行执行推理,物理步长和策略权重不变。平地显示由 131,072 个三角面降为 2 个;完整上游游戏仍保留地形网格。ORT 运行库作为独立同源 JS 输出,避免 Worker 载入含 DOM 操作的页面模块。
  • 手机弹窗使用可视高度和安全区,方向键与操作按钮至少 44 px;窄屏操作区分列,模型根据横竖屏重新构图。
  • 回归:npm --prefix sandbox test(含渲染调度、DPR 上限、持续降档和暂停恢复)。浏览器检查 320 / 390 px 竖屏及 844 px 横屏;视口检查不能代替真实 Android、iOS 和 Windows 低配硬件测试,目标帧率不是所有设备上的保证。

浏览器不允许 file:// 读取 URDF,必须起一个本地服务器:

cd ~/vibemake-site
node scripts/server.mjs
# http://localhost:8091   后端接口数据(/api 转发到 dev 后端;线上也用这个服务器,按域名自动选 dev / 正式后端)
# http://127.0.0.1:8091   本地演示数据(最早的完整样子,作参考)
# /pcb/ 同源代理到相邻的 ziro-designer-main/designer,默认使用真实后端,无需手动打开 5173 端口
# PCB_API_MODE=mock node scripts/server.mjs 显式启用开发模拟(独立存储,不共用主站账号)

手机与电脑连接同一 Wi-Fi 后,用 http://<电脑局域网 IP>:8091 访问。本地 / 局域网下,社区 URDF、网格和贴图统一通过 /__model_assets/ 同源读取,避免 OSS 仅允许 localhost 跨域时手机加载失败。代理仅允许 linkerbot bucket 的 URDF、experiences 与 project-resources 数据资源目录,保留缓存与流式传输,不修改模型文件;线上域名继续使用原 OSS 地址。回归检查:node --test scripts/model-assets.test.mjs。

页面路由(不带 .html):/、/explore、/studio?robot=<id>、/cad、/pcb、/project/<编号>、/workspace、/workspace/<编号>;旧的 xxx.html 地址会 301 跳到新地址。/cad 继续复用独立 CAD 部署;/pcb/ 由独立 PCB 前端应用在主站同源提供,不再嵌入旧 PCB iframe。 CAD / PCB 仅电脑端开放:手机、平板及 820px 以下(含)的窄屏隐藏主站导航入口。CAD 仍由主站的桌面检测保护;PCB 前端自行显示电脑端提示。手机横屏仍按移动设备处理。 线上部署使用构建后的静态文件,不需要启动 Node 服务;具体配置见 dist/DEPLOY.md。

目录

index.html            首页:精选项目 3D 轮播 → 本周热门 → 社区讨论 → 创客 → 发布引导
explore.html          发现:搜索(/ 聚焦)/ 类型筛选 / 我的收藏·Fork / 排序 / 网格-列表切换
project.html          项目页(类 GitHub):标题 + Star / Fork / 关注 → 大尺寸 3D 舞台 →
                      概览·文件·讨论·Fork·动态标签(?id=&tab=&path=),右侧关于/贡献者/语言/相关项目
workspace.html        「我的」:/workspace 我的项目;/workspace/<编号> 仓库页(代码浏览、在线编辑、上传、提交记录、发布、设置)
studio.html           工作台:左侧选机器人,底部「遥控 / 动作 / 爆炸图」切换、录制回放(纯仿真)
css/style.css         全部样式(:root 里是颜色变量)
js/layout.js          顶部导航 renderShell(active, {overlay, footer})、⌘K 搜索、页脚、图标、头像、toast
js/community.js       社区数据层:合并 robots.json + community.json,文件树、缩略图、本地 Star/评论状态
js/registry.js        机器人配置来源(ROBOTS_ENDPOINT)
js/viewer.js          3D 渲染:URDF 加载、取景、地面、关节拖拽、遥控跟随、爆炸图、离屏缩略图
js/motion.js          运动控制器 + 模板(generic/quadruped/hexapod/biped/arm/wheeled)
js/assistant.js       Maker AI(AI 项目助手)(右下角按钮 + 对话面板,⌘J 打开):找项目、创建空项目、Fork,接 /api/community/ai/chat;演示数据模式下播放示例对话
js/connection.js      实体机器人连接(Web Serial / WebSocket),控制台暂未使用,接硬件时再接回
robots/robots.json    机器人配置(URDF、jointMap、步态……)
data/community.json   社区演示数据(用户、Star 数、README、提交、讨论、Fork)
robots/phantomx/      PhantomX 六足(HumaRobotics/phantomx_description,BSD)
robots/xlerobot/      XLeRobot 轮式双臂(Vector-Wangel/XLeRobot,Apache-2.0)
robots/open-duck-mini/ Open Duck Mini v2 双足(apirrone/Open_Duck_Mini,Apache-2.0)
robots/so101/         SO-ARM101 机械臂(TheRobotStudio/SO-ARM100,Apache-2.0)
                      以上均从 GitHub 导入:只保留 <visual> 用到的网格,路径改为 meshes/<文件名>,
                      浮动根关节改为 fixed;版权归原作者,许可证见各项目 README
robots/demo-*/        早期用基础几何体生成的演示 URDF(已不在列表中,可作为写配置的参考)

演示环境下 Star / Fork / 关注 / 点赞 / 评论保存在浏览器 localStorage; 接后端后把这些操作换成接口调用即可(集中在 js/project.js 的事件处理里)。

添加一个机器人

  1. 把 URDF 和网格放到 robots/<id>/(或任意 CDN 地址)。 URDF 里网格写成相对路径 meshes/xxx.stl 即可;用了 package://xxx/ 的话配置 packages。
  2. 在 robots/robots.json 加一项:
{
  "id": "xlerobot",
  "name": "XLeRobot",
  "maker": "Vector Wang",
  "description": "双臂移动机器人",
  "urdf": "robots/xlerobot/xlerobot.urdf",
  "packages": { "xlerobot": "robots/xlerobot" },
  "thumbnail": "robots/xlerobot/thumb.webp",
  "upAxis": "z",
  "archetype": ["wheeled", "arm"],
  "jointMap": {
    "base.x": "root_x_axis_joint",
    "base.y": "root_y_axis_joint",
    "base.yaw": "root_z_rotation_joint",
    "arm.R.base": "Rotation",   "arm.R.shoulder": "Pitch",   "arm.R.elbow": "Elbow",
    "arm.R.wrist_pitch": "Wrist_Pitch", "arm.R.wrist_roll": "Wrist_Roll", "arm.R.gripper": "Jaw",
    "arm.L.base": "Rotation_2", "arm.L.shoulder": "Pitch_2", "arm.L.elbow": "Elbow_2",
    "arm.L.wrist_pitch": "Wrist_Pitch_2", "arm.L.wrist_roll": "Wrist_Roll_2", "arm.L.gripper": "Jaw_2",
    "head.yaw": "head_pan_joint", "head.pitch": "head_tilt_joint"
  },
  "jointSign": {},
  "stance": {},
  "gait": { "speed": 0.4, "turnRate": 1.2 },
  "view": { "yaw": 35, "pitch": 16, "distance": 1 },
  "stats": { "stars": 0, "mods": 0 },
  "hardware": { "connection": "usb-serial", "baudRate": 1000000, "servoIds": { "Rotation": 1 } }
}

只填 id / name / urdf 也能显示,会用 generic 模板让所有关节在限位内摆动。

字段说明

字段 说明
archetype generic / quadruped / hexapod / biped / arm / wheeled,可组合成数组
jointMap 语义名 → URDF 关节名。语义名见下表
jointSign 方向不对就设 -1,支持通配符:{"leg.*.knee": -1}
stance 初始姿态(弧度),键可以是语义名(支持通配符)或 URDF 关节名
gait 步态参数:stepLen 步幅、lift 抬脚、cadence 步频 Hz、speed m/s、turnRate rad/s、wheelRadius、track 轮距
view 相机:yaw / pitch(角度)、distance(倍率)
upAxis URDF 一般是 z(默认),网格本身 Y 轴向上时填 y
facing 模型正面朝向修正(度)。我们的「前进」是 +x,模型正面朝 -x 就填 180
paint 按材质名包含匹配:颜色字符串,或 { "preset": "plastic / metal / rubber", "color": "#16181b", "roughness": 0.45 }。也支持 metalness、envMapIntensity、clearcoat、clearcoatRoughness、emissive、emissiveIntensity;没有 PBR 数据的 URDF / STL 材质默认使用统一的展示金属表面,GLTF PBR 材质保留原参数。
extras 给模型补几何体,如眼珠:[{"link": "head_assembly", "shape": "cylinder", "radius": 0.0115, "xyz": [x, y, z], "axis": "z", "color": "#07080a"}]
gait.footComp 双足脚掌补偿系数,默认 {"hip": 1, "knee": 1}(踝 = -(髋·hip + 膝·knee)),髋膝转向相反的机器人填 -1
gait.armAmp 展示动画里手臂摆动幅度倍率,装在移动底盘上的手臂建议 0.3~0.5
hardware connection: usb-serial / pi-ws;baudRate、url、servoIds、direction
thumbnail 不填会自动离屏渲染一张

语义关节名

类型 语义名
quadruped leg.{FL,FR,RL,RR}.{hip,knee,ankle,yaw}
hexapod leg.{L1,L2,L3,R1,R2,R3}.{hip,knee,ankle}(hip 为水平摆动的 coxa)
biped leg.{L,R}.{hip,knee,ankle}、arm.{L,R}.shoulder
arm arm.{base,shoulder,elbow,wrist_pitch,wrist_roll,gripper},多臂用 arm.L.* / arm.R.*
wheeled wheel.{FL,FR,RL,RR} 或 wheel.{L,R}(名字含 L 为左轮)
通用 head.yaw、head.pitch;base.x / base.y / base.yaw(URDF 自带虚拟底盘关节时)

模板的方向约定:hip 正值脚往后、knee 正值屈膝、wheel 正值向前滚。和你的 URDF 相反就用 jointSign 翻转。

打包部署

npm install                            # 第一次打包前装一次(只是打包工具:模型压缩)
pnpm -C ../ziro-designer-main/designer build  # 独立构建 PCB 应用
npm run build                          # 收录相邻 PCB designer/dist,构建主站并生成 dist.zip
npm run build:dev                      # 同样收录 PCB 应用,生成固定 dev 接口的 dist-dev.zip
PCB_DIST=/path/to/designer/dist node scripts/build.mjs # PCB 仓库不在默认相邻目录时指定构建产物
SITE_ROOT=dist PORT=8093 node scripts/server.mjs   # 本地预览打包结果

两套源代码和构建仍独立;网站打包时将 PCB 的 Vite 静态产物复制到 dist/pcb/。线上服务器需将无扩展名 PCB 工程地址回退到 /pcb/index.html,静态资源则按原路径返回。部署检查见 dist/DEPLOY.md。

CAD 平台助手的容量、截图、超时和请求频率读取 /api/cad/ai/capabilities 的实际 limits,缺失或为 0 的字段不增加前端业务上限。每次续调都会向模型补充当前限额、已用容量和剩余图片数;图片自动缩小并重新编码,过大的工具文字结果返回明确错误,要求缩小查询,禁止将残缺 JSON 当成结果或重做已执行修改。旧历史只按完整用户轮次裁剪。按照复杂建模需求,当前前端继续取消单轮 12 次模型调用和 24 条修改的限制;这些整轮限额若要恢复,需要前后端先统一产品配置。

/api/cad/ai/chat 必须按 SSE 透传:禁止缓存,Nginx 设置 proxy_buffering off、proxy_cache off,网关、负载均衡及代理的请求/读取超时至少 90 秒,覆盖当前 60 秒模型请求超时。4 MiB JSON 配额只配置在 chat 路径;实例并发数、Redis 用户限流、断连取消和日志脱敏由后端保证,浏览器排队不能代替服务端限制。

接入后端(Community API)

node scripts/server.mjs                                    # http://localhost:8091,/api 代理到 https://dev-vibemake-api.robotquan.com
API_TARGET=http://localhost:8993 node scripts/server.mjs   # 换成本机后端
  • 页面数据只来自后端接口,接口出错(如 502)就在页面上直接显示错误,不会换成演示数据。 地址栏写 ?source=mock 才使用本地演示数据(data/community.json),只对当前这次打开有效。
  • 接口封装在 js/api.js(全部接口、统一错误、Token、SSE);登录、发布、Fork 弹窗在 js/auth.js。
  • 线上同样由 server.mjs 转发 /api:dev-*、localhost、局域网 → dev 后端,其他域名 → 正式后端 vibemake-api.robotquan.com。
  • 3D 模型:项目字段 urdfMainUrl 有值就显示,在「我的 → 项目 → 设置 → 3D 模型」上传 URDF 文件夹(直传 OSS)。 文件夹里只有 .xacro 时,浏览器先用 xacro-parser 展开成 .urdf(js/xacro.js),和原文件一起上传;$(find 包名)、package://包名/ 按 package.xml 找目录。
  • 后端暂缺的接口和字段见 docs/api-gaps.md。

演示数据 / 硬件

  • 机器人列表:修改 js/registry.js 的 ROBOTS_ENDPOINT,接口返回同结构的数组(或 { robots: [...] })。
  • 硬件协议:修改 js/connection.js 的 encode()。默认每行一条 JSON: {"type":"joints","t":1712345678901,"q":{"joint":0.12},"servo":{"1":0.12}}
  • 校准零位保存在浏览器 localStorage(vm.cal.<id>),录制片段可导出 JSON。

社区数据(data/community.json)

projects 以机器人 id 为键:slug、owner、stars、forks、watchers、license、updated、topics、 languages、contributors、featured(true,或写数字决定首页轮播顺序,越小越靠前)、readme(Markdown)、commits([消息, 作者, 时间])、 discussions(含 replies)、forkList([作者, 名称, 收藏, 说明, 时间])。 users 以 handle 为键:name、color、bio。接后端时替换 js/community.js 的 COMMUNITY_ENDPOINT。