Files
makeCAD/docs/vibemake/frontend-implementation.md
likang 2cdf535fd1
CI / Select checks (push) Has been cancelled
CI / Format and repository checks (push) Has been cancelled
CI / Compile RISC-V (manual) (push) Has been cancelled
Docker / image (push) Has been cancelled
Generated files / Regenerate and commit (push) Has been cancelled
Lists / Design format changes merge cleanly (push) Has been cancelled
Lists / Lists are sorted one item per line (push) Has been cancelled
Packaging lint / lint (push) Has been cancelled
Pages / build (push) Has been cancelled
CI / Dependency advisories (push) Has been cancelled
CI / Quick compile (push) Has been cancelled
CI / Native Linux Clippy (push) Has been cancelled
CI / Build tests (push) Has been cancelled
CI / Native Linux tests (push) Has been cancelled
CI / GPU path tests (1/4) (push) Has been cancelled
CI / GPU path tests (2/4) (push) Has been cancelled
CI / GPU path tests (3/4) (push) Has been cancelled
CI / GPU path tests (4/4) (push) Has been cancelled
CI / Action matrix (1/16) (push) Has been cancelled
CI / Action matrix (10/16) (push) Has been cancelled
CI / Action matrix (11/16) (push) Has been cancelled
CI / Action matrix (12/16) (push) Has been cancelled
CI / Action matrix (13/16) (push) Has been cancelled
CI / Action matrix (14/16) (push) Has been cancelled
CI / Action matrix (15/16) (push) Has been cancelled
CI / Action matrix (16/16) (push) Has been cancelled
CI / Action matrix (2/16) (push) Has been cancelled
CI / Action matrix (3/16) (push) Has been cancelled
CI / Action matrix (4/16) (push) Has been cancelled
CI / Action matrix (5/16) (push) Has been cancelled
CI / Action matrix (6/16) (push) Has been cancelled
CI / Action matrix (7/16) (push) Has been cancelled
CI / Action matrix (8/16) (push) Has been cancelled
CI / Action matrix (9/16) (push) Has been cancelled
CI / Action matrix determinism (push) Has been cancelled
CI / Property tests (many cases) (push) Has been cancelled
CI / Doc tests (push) Has been cancelled
CI / Reference tests (push) Has been cancelled
CI / Windows D3D12 FXC shaders (push) Has been cancelled
CI / Windows app startup (push) Has been cancelled
CI / ci (push) Has been cancelled
CI / Compile WebAssembly (push) Has been cancelled
CI / Nightly alert (push) Has been cancelled
Pages / deploy (push) Has been cancelled
修改ai助手
2026-11-09 18:53:36 +08:00

19 KiB
Raw Permalink Blame History

VibeMake CAD 前端与引擎集成

Workspace STEP integration uses the bodyless association POST and the additive stepImport bridge capability. See Workspace STEP integration. Initial STEP files have a separate 500 MiB input limit; native cloud designs retain their 256 MiB limit.

本文记录 VibeMake 主站与 SolidCraft WASM 引擎的前端集成边界、构建步骤、运行配置和发布验收。云项目 API 与上传协议以同目录的 CAD 个人工作空间前端对接 为准(2026-11-05 同步)。backend-implementation.md v1.2 是历史方案,其中的旧接口、私有 Bucket 和下载签名约定不再作为当前对接依据。

产品结构

路径 用途 加载 CAD WASM
/cad/ VibeMake CAD 项目列表 否
/cad/editor/?project=<cadProjectCode> 单项目编辑器 是

VibeMake 原生 ES 模块负责账号复用、登录弹窗、项目 CRUD、路由、设备检查、二进制下载、IndexedDB 草稿和云保存协调。SolidCraft Rust/WASM 负责文档解析、参数化建模、模型视图、原生格式序列化、快照和精确保存基线。浏览器中的 window.vibemakeCad 是平台宿主桥;既有 window.solidcraft 建模 API 仍由引擎提供。

登录沿用主站 vm.auth 和邮箱图片验证码弹窗。进入列表或编辑页时先验证身份,再读取私有数据。取消弹窗不加载项目或引擎。CAD 本身不签发凭据;CAD API 每次仍需校验当前身份和项目 owner。

源码位置

VibeMake:

  • js/cad/ 页面控制器、文案、接口、快照保存协调器、本机草稿和引擎加载。
  • js/auth-dialog.js 主站与 CAD 共用的登录表单;js/auth.js 保留既有导出接口。
  • cad.html 列表入口;cad/editor/index.html 编辑器壳层;css/cad.css 产品样式。
  • scripts/cad-engine.mjs 校验并组合独立引擎;scripts/server.mjs 提供本地深链接、API 代理和引擎资源。

SolidCraft:

  • crates/ui-egui/src/platform.rs 平台策略与单文档约束。
  • apps/solidcraft-web/src/platform.rs WASM 二进制宿主桥。
  • crates/engine/src/lib.rs 快照 ACK 的文档基线,以及宿主项目替换时的旧检查点隔离。
  • assets/styles/ui/themes/vibemake-dark.json VibeMake Dark UI token;视口底色、坐标轴、选择、警告、错误与预览颜色继续由原工程主题提供。
  • assets/locales/pending/vibemake-platform.json 与 attribution/pending/vibemake-platform.md 按上游目录规则保留新主题及消息。

前端行为约束

  • 编辑页固定 42px HTML CAD 应用栏,VibeMake Logo 返回 CAD 项目列表,文件/保存/撤销/重做靠左,助手/首选项/帮助/保存状态/账号靠右;不显示主页图标或独立产品标题。WASM 画布使用其余视口。单页只绑定一个项目;多个项目由多个浏览器标签页承载。
  • 初始设备检查在引擎加载之前执行。手机、平板或宽度不大于 820px 时显示桌面提示;编辑时窗口变窄则锁住画布并保留当前页面和文档。
  • 品牌色、产品名、帮助目标和外部链接集中维护。对外只开放简体中文与英文,语言偏好键为 vm.cad.locale,新账号首次进入默认中文。
  • Rust 平台模式独立于旧 embed。它隐藏不能接入的桌面进程、ACP、本机工具发现和插件功能,过滤菜单、命令搜索和命令执行入口。原版助手通过浏览器模型连接运行,详见 Web 助手说明。宿主接管的文档重绑命令明确拒绝调用。
  • Native .sc 打开先在临时会话校验,再创建云项目。坏文件、格式不兼容或权限失败不会替换当前文档。插入 STEP、Mesh、Point Cloud 和实际可用的导出仍走已有 Rust 命令。
  • 项目列表展示接口返回的 coverUrl,只接受完整 HTTPS 地址;图片延迟解码、按需加载并完整展示,缺少封面或加载失败时显示既有占位。列表不加载 CAD 引擎。
  • 云保存和另存通过 createSnapshot({includeCover:true}) 同时获取原生文件和 640×400 PNG。封面复用缓存显示网格、实体颜色和独立等轴测相机,不读取或修改编辑相机,不包含平台 UI、网格或选择高亮;空模型、未就绪缓存或超出绘制预算时保留原封面并提示预览不可用。普通草稿不额外生成云封面,原生容器内缩略图规格不变。
  • 原生文件确认并 ACK 后,复用 /uploads/project-covers/signature 签名、匿名 OSS FormData 上传,再以 PATCH {coverUrl} 绑定到 CAD 项目。封面任务单独保存在账号和项目隔离的 IndexedDB 日志,失败显示工程已保存,重试不重复上传工程或增加版本;PATCH 失败可重用已上传的普通图片地址。页面重新打开后可恢复同版本的封面任务。
  • 封面 PATCH 按当前接口没有版本条件参数。前端在上传前和绑定前检查远端文件版本,放弃已知过期的任务;这不等于服务端原子版本校验,最后一次 GET 与 PATCH 之间的跨客户端竞态仍需后端条件更新协议解决。封面上传需要 OSS_ENABLED,独立于工程的 CAD_OSS_ENABLED。
  • 保存只传固定的原生工程快照。单个 SaveCoordinator 串行执行申请签名、OSS 表单直传和 PUT document 确认;确认回执的 cadProjectCode、下一版本号和 savedAt 校验成功后,才 ACK 对应 binding 下的快照。快照 ACK 不修改随后发生的更改、项目名或视图。
  • 上传响应丢失或上传失败时,先用原 uploadCode 确认;确认仍不明确时保留批次和原生文件。仅后端明确返回文件缺失、大小不符或批次过期时才申请新批次。确认超时重试原批次,不重复创建项目或版本。
  • IndexedDB 数据库存于 vm.cad,按账号、项目、标签页会话分区;草稿是二进制原生工程,保存事务日志不含认证 token、签名地址或 OSS 凭据。不可用时明确告警。草稿不等于云端保存。
  • 离开保护、Ctrl/⌘+S、另存和下载都由宿主统一协调。冲突时保留当前内容并提供另存、下载或用户确认重载;不会自动更新 head 后覆盖远端。
  • UI 更新使用同源 /cad/sw.js,worker 只认识当前 engine manifest 中列出的无查询参数静态资源路径,不拦截 API、身份响应、私有文件或签名 URL。它不调用 skipWaiting,更新通过“保存后刷新”提示交给用户。

Web 助手边界

助手复用 Rust/egui 面板、对话、权限、工具记录与撤销分组,不加载社区 Maker AI。服务预设、连接类型布局、附件菜单及模型列表沿用原版;图片/文本可选择或拖入,剪贴板图片由浏览器授权后读取。需要本机进程的连接类型和独立系统窗口保留原版位置并显示不可用原因。

浏览器直接访问用户自行配置的模型服务;VibeMake 业务 API 不转发模型请求。协议支持 OpenAI 兼容和 Anthropic 兼容的非流式 JSON 响应,界面异步等待。请求可取消并有超时及响应大小限制。服务必须允许浏览器访问,协议兼容性由一次真实模型请求和无副作用的工具探针确认。工具失败反馈给模型以便解释或修正,后续操作仍通过原版审批和当前工程校验。

下一阶段服务边界、完整事件映射和 CAD 工具往返见 Web 助手后端接入交接。这是待实现协议;接入时仍需实现 Rust RemoteBackend,当前没有已连接的远程助手运行服务。

window.vibemakeCad.ready() 的 capabilities.assistant 表示引擎实现了助手。VibeMake 编辑页绑定工程后助手自动显示在右侧全高分栏,网页菜单栏与助手共用分隔线和栏宽;平台分隔线拖动也会同步更新菜单栏宽度。宿主在工程绑定后调用 setAgentContext({userId, projectId, binding, sessionId}),身份失效或退出时调用 setAgentContext(null);showMenu("assistant") 确保常驻助手可见,不会关闭它。getState() 与订阅的 assistant 仅包含能力、开关、连接、运行、待审批计数及公开的栏宽,不含密钥、消息或平台 token。新外壳使用旧引擎时隐藏助手入口并提示更新。

普通助手配置、权限与授权记录保存在账号独立的 vm.cad.agent.profile.<userId>;共享 vm.cad.engine.prefs 不保存这些内容。密钥默认只保存在页面内存,主动勾选后才写入独立 IndexedDB vm.cad.agent.credentials.v1。该存储不是系统钥匙串,同源脚本可访问。退出或切换账号取消请求并清理内存,对话刷新后不恢复。

AI 工具仍执行 Rust 命令;Web 适配层复用 MCP 的工具 schema 和调用校验,不运行本机进程、任意 JavaScript 或终端。权限不能解除宿主工程绑定和输入锁定。工具发起、审批与实际执行时检查当前轮次和文档修订;用户在轮次中修改模型会取消旧审批。AI 修改只更新工程 dirty,不自动云保存。

引擎产物

Keep the default SolidCraft SMLib WASM build enabled. The CAD page sources still live in the adjacent VibeMake checkout. Run npm ci in that checkout once to install its packaging dependency, then run this command from the SolidCraft repository root:

./build.sh

The script builds the current engine and produces two separate archives:

  • dist/vibemake-cad.zip is the complete CAD deployment package. Its ZIP root contains index.html, editor/index.html, engine.json, workers, the manifest, current _assets/<buildId>/, CAD and shared dependency modules under js/, common and CAD styles under css/, fonts and libraries under vendor/, required brand and environment assets, icons, and robot indexes under data/ and robots/. It has no enclosing cad/ directory. Publish this archive for a first CAD deployment or a combined page and engine update. Its unpacked output is dist/vibemake-cad/.
  • dist/vibemake-cad-engine.zip contains only cad/engine.json, cad/sw.js and the current cad/_assets/<buildId>/. It has no HTML pages and is only for updating an already deployed CAD application. It is not sufficient for a first deployment.

Extract the complete archive directly into the website's cad/ directory:

unzip -o /path/to/solidcraft-main/dist/vibemake-cad.zip -d /path/to/vibemake/cad

The result must include <website-root>/cad/index.html and <website-root>/cad/editor/index.html. Extract the archive itself; copying a ZIP into the directory does not publish its contents. Do not extract the complete package into the website root or add an extra enclosing directory. All CAD frontend dependencies are contained under cad/; it does not depend on the website root's shared JS, CSS, fonts or vendor files. Preserve the main site, PCB, server configuration and older cad/_assets/<buildId>/ directories used by open editors. Do not clear the website or CAD directory before extraction.

The default frontend checkout is ../vibemake. Set VIBEMAKE_SITE_ROOT=/absolute/path/to/vibemake when it lives elsewhere. The script passes the freshly built engine directory to scripts/build-cad.mjs, so the complete archive cannot silently use an older engine installed in the frontend checkout. The engine itself remains in dist/vibemake-cad-engine/; its manifest records the bridge version, engine kind, kernel, build ID, sizes and SHA-256 digests.

For local development, install only the engine archive from the VibeMake repository root:

unzip -o ../solidcraft-main/dist/vibemake-cad-engine.zip -d .

Unlike the complete package, the engine-only archive already contains a top-level cad/ directory. Extract that archive into the website or VibeMake project root, not into its cad/ directory. Preserve the pages and other CAD frontend files. Do not create a nested cad/cad/ directory. Engine binaries installed here are ignored by Git.

Start the local server from VibeMake without a CAD engine path setting:

npm run dev

Restart the development server after installing a new engine. Local startup validates cad/engine.json and its assets. The former external-directory environment setting remains an optional development override for compatibility; the normal workflow uses the files in cad/.

VibeMake's npm run build and npm run build:dev exclude cad/, pcb/, js/cad/ and css/cad.css. They do not require CAD or PCB sources or engine files, and never publish those independent modules. The optional compatibility command npm run build:cad packages the engine already installed in VibeMake with the CAD pages and frontend dependencies as dist-cad.zip. Extract this complete package directly into the website's cad/ directory as well. It is not required after SolidCraft's ./build.sh, which produces the complete deployment archive directly.

Development /api requests use the existing same-origin proxy. Deployment retains the site's API base selection and backend CORS configuration. Mock APIs are for isolated tests only.

静态主站需要为两条 CAD URL 配置 SPA/目录索引回退;/cad/_assets/<buildId>/... 使用一年 immutable 缓存,/cad/engine.json、页面、worker 不做长缓存。WASM 返回 application/wasm,页面通过绝对 /cad/ 资源 URL 载入。不要在部署清理时删除仍被已打开页面引用的旧 build-id 资源。发布新版本不改变 PCB 路由;回滚时恢复页面和 engine.json,保留所有 engine asset 目录。

API 与错误边界

云接口前缀为 /api/cad/workspace/projects,字段、幂等回执、版本冲突、错误语义和容量上限由 workspace-api.md 定义。当前接口不提供 capabilities、complete 或上传状态查询端点。读取文件和原生工程快照受编辑器 256 MiB 上限约束;下载内容在解析前校验实际长度,草稿和事务日志使用本机 SHA-256 校验。

对象存储上传将签名中的 formFields 原样加入 FormData,最后追加名为 file 的原生 .sc;不注入 private ACL,不手写 multipart Content-Type。上传和文件读取均不带平台 Bearer token。文件读取使用普通 OSS/CDN 地址,允许 expiresAt=null,不做签名续期。403 提示管理员检查 OSS/CDN 访问权限和跨域配置,不触发平台退出登录或自动重新获取地址。编辑基础版本始终来自同次读取的 document.version。

后端 CAD 存储复用主站 vibemake.oss 的连接参数和 OSS_PUBLIC_BASE_URL,由 CAD_OSS_ENABLED 独立开启;不要求专用私有 Bucket。CAD_STORAGE_UNAVAILABLE / CAD_STORAGE_UNSAFE 提示管理员检查开关和连接配置。前端不接收或保存 RAM 密钥。删除项目不会撤销已发出的普通文件直链。

前端只依稳定错误 code 选择双语文案;平台 API 的 HTTP 401 表示身份失效并打开共用登录弹窗,普通超时、离线和 5xx 不会清除登录态。收到账号切换时先锁画布、保护旧账号草稿并释放旧项目;过期写入回执不得确认新文档。CAD_VERSION_CONFLICT、项目 404、上传结果未知与本机草稿损坏都保留本地工程并明确给出恢复动作。

验证

VibeMake 定向自动测试:

npm run test:cad
npm run test:downloads
npm run test:experiences

真实 WASM 浏览器集成使用测试专用 API/对象存储模拟器,不写真实云端:

node tests/cad/mock-server.mjs
PORT=8091 API_TARGET=http://127.0.0.1:8092 npm run dev

另一个终端执行 npx playwright install chromium(首次运行)和 npm run test:cad:browser。可设置 VM_CAD_BASE_URL、PLAYWRIGHT_CHROMIUM_EXECUTABLE、VM_CAD_ARTIFACT_DIR;浏览器记录和截图只写到指定的本机验收目录。

SolidCraft 定向检查:

cargo fmt --all --check
cargo check -p solidcraft-ui-egui
cargo check -p solidcraft-web --target wasm32-unknown-unknown
cargo test -p solidcraft-engine --lib cloud_snapshot --profile release
cargo test -p solidcraft-ui-egui --lib vibemake_platform --profile release
cargo xtask lists
cargo xtask assets
cargo xtask ui-containers
cargo xtask layers
cargo xtask skills

发布前还需运行各仓库完整 CI,在真实后端和对象存储完成端到端及受支持浏览器矩阵。真实 API、OSS、Windows/Edge、Safari 降级、服务端最大工程容量和生产部署回滚在本机 mock 环境中无法证明,发布记录不得把这些标成已验收。

封面专项验证(2026-11-05)

  • npm run test:cad 57 项、下载测试 7 项、体验资源测试 40 项通过;覆盖封面签名与匿名直传、同快照绑定、封面失败单独重试、重新打开后的任务恢复、账号隔离和过期版本检查。
  • macOS 安全校验进程恢复后,node scripts/build-vibemake-cad.mjs 完整通过(包含 release WASM 编译、Trunk 优化与资源打包)。新引擎构建号为 25c0c2b8b7c9a5235ac69ae0,构建时间为 2026-11-05 17:17:51(Asia/Shanghai),8 个资源均通过 readCadEngine 的大小与 SHA-256 校验。
  • cargo fmt --all --check 以及 cargo test -p solidcraft-engine --lib --features smlib --profile ci cmd::file::thumbnail::tests -- --test-threads=1 通过(4 项),确认固定封面尺寸、保存基线不变及原生缩略图行为。
  • 使用上述实际发布版 WASM 的 createSnapshot({includeCover:true}),未注入测试图片:确认 640×400 PNG、切换实时相机后封面字节不变、截图不移动当前相机。实际页面连接测试专用 API/OSS,验证签名、匿名上传、封面 PATCH 不增加文件版本、列表显示且不加载引擎、图片 404 回退;模拟封面签名失败后,真实保存按钮仍完成原生工程保存,刷新后补传不再增加版本。5 项专项检查通过,页面脚本错误为 0,记录位于 target/cad-cover-verification/actual-engine-browser-results.json,截图为同目录 fixed-camera-cover.png 和 project-list-with-cover-zh.png。
  • npm run test:cad:browser 完整回归未通过:现有菜单断言仍要求 assistant 按钮,而当前页面仅有 file、preferences、help。测试在封面步骤前停止;未将上述封面专项结果写成完整回归通过。
  • npm run build 已生成配套主站 vibemake/dist.zip。独立引擎部署包为 solidcraft-main/dist/vibemake-cad-engine-25c0c2b8b7c9a5235ac69ae0.zip,根目录为 cad/,只包含本次构建及部署说明;两个 ZIP 均通过完整性检查。主站 ZIP 不包含引擎,发布时按独立引擎说明叠加,并最后切换 engine.json。
  • 发布时必须同时更新主站前端和对应的新 WASM 引擎。使用旧引擎或取不到预览时,原生工程仍能保存,界面提示封面预览不可用并保留旧图。真实账号与 OSS 联调尚未执行。