Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vibemake 网站(静态版)
纯静态页面,无需构建。three.js、urdf-loader、marked、DOMPurify 和字体都放在 vendor/(node scripts/vendor.mjs 下载),不依赖外部 CDN;3D 引擎只在需要的页面按需加载。
本地运行
浏览器不允许 file:// 读取 URDF,必须起一个本地服务器:
cd ~/vibemake-site
node scripts/server.mjs
# http://localhost:8091 后端接口数据(/api 转发到 dev 后端;线上也用这个服务器,按域名自动选 dev / 正式后端)
# http://127.0.0.1:8091 本地演示数据(最早的完整样子,作参考)
页面路由(不带 .html):/、/explore、/studio?robot=<id>、/project/<编号>、/workspace、/workspace/<编号>;旧的 xxx.html 地址会 301 跳到新地址。
线上部署用同一个 server.mjs(在 dist 里 npm start),nginx / 1Panel 只需把整个站点反向代理到它,见 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的事件处理里)。
添加一个机器人
- 把 URDF 和网格放到
robots/<id>/(或任意 CDN 地址)。 URDF 里网格写成相对路径meshes/xxx.stl即可;用了package://xxx/的话配置packages。 - 在
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 |
按 URDF 材质名改颜色:{"wj-wk00": "#16181b"}(包含即匹配) |
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 # 第一次打包前装一次(只是打包工具:模型压缩)
node scripts/build.mjs # 生成 dist/ 和 dist.zip;STL 网格会转成 Draco 压缩的 GLB(47 MB → 3 MB)
SITE_ROOT=dist PORT=8093 node scripts/server.mjs # 本地预览打包结果
dist 里附带 nginx.conf.example(/api 转发、页面路由、缓存、gzip)和 DEPLOY.md。
接入后端(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。