Files
makeCAD/docs/vibemake/workspace-step-integration.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

6.7 KiB

Workspace STEP integration

VibeMake workspace projects may bootstrap one associated CAD project. This integration is one-way: the first import reads STEP, while subsequent cloud saves and opens use the native .sc document. Neither saving nor Save As changes workspace STEP, Git, or community publication.

Entry and API

The current owner's workspace detail shows Edit only for a READY repository with a nonempty stepMainUrl, outside Git historical views. The existing desktop check runs before creating an association. Use the current fork's projectCode, never its sourceProjectCode.

POST /api/workspace/projects/{projectCode}/cad-project has no body, uses the platform Bearer token, and returns a CadProject in the standard envelope. The server atomically returns or creates one active association, including under retries and concurrent tabs. The editor URL contains only the returned CAD code.

All CAD records include workspaceProjectCode: string | null and initialStep: {downloadUrl, fileName, sizeBytes} | null. An associated source is a creation-time snapshot and remains after native saves. A standalone project has null association fields. Unsaved projects have hasDocument=false and version=0.

Opening and recovery

  1. Fetch latest CAD metadata.
  2. With hasDocument=true, read document metadata and open its .sc using document.version. Failure never falls back to STEP or an empty design.
  3. Without a cloud document, offer pending transaction and local draft recovery before downloading the source. Unresolved transactions or a deferred draft block fresh initialization.
  4. With no recovered document, import initialStep; without a source, open an empty design.
  5. STEP import is unsaved and starts at version zero. Preserve import warnings, offer details, and reject an import with no usable bodies. Capture a local native draft before normal editing continues.

A source STEP accepts at most 524288000 bytes and a filename of 1024 Unicode characters, preserving original case and Unicode. Native cloud documents retain their 268435456-byte and 255-character limits. The source limit is not a guarantee of successful geometry import or native serialization size. All downloads use returned public URLs without platform credentials and validate the actual byte count.

Binary bridge

Bridge version 1 adds ready().capabilities.stepImport=true, openProjectFromStep({projectId,fileName,bytes:Uint8Array}), and cancelOpenProject(). Successful imports return {binding,warnings}. getState() and subscriptions report opening with a phase and available work counts. Native openProject stays compatible; a host only requires STEP capability when it needs to import a source.

createSnapshot({forLocalDownload:true}) permits a local native download above the 256 MiB cloud limit. Ordinary snapshots, native uploads, and native opens retain their existing limit. The host uses this option only for Download design copy; it does not acknowledge a cloud save. If the draft list cannot be read after pending transactions were checked, the user can explicitly retry or continue without restoring a draft. Unresolved transactions always remain blocking.

The bridge stages bytes under a private temporary VFS key, passes the original name separately, and uses file_load to prepare an isolated session through the existing STEP reader and file.insert_step. The prepare-only completion path does not adopt tabs or relax the active document's host command checks. Only a current request may atomically adopt its result and bind a project. Failure, cancellation, release, and stale completion clean up staged bytes. An import keeps its component, Import feature, assembly structure, and existing rigid assembly semantics.

Cancelling an open preserves the current document. Releasing a project also cancels its pending import. Account changes abort downloads and invalidate pending opens before they can adopt a session or bind an assistant.

Recovery prompts close when their opening request is aborted. Restored drafts are rebound to the new native binding only if the stored snapshot has not changed. Successful save acknowledgements clear earlier drafts covered by the same binding's monotonic revision counter, while preserving later revisions, differing visibility at the same counter, and every other binding. A draft write finishing after acknowledgement cannot recreate a covered draft.

Saving

Use the existing native snapshot, signature, anonymous OSS POST, uploadCode confirmation and exact-baseline ACK. First save uses expectedVersion zero. Preserve journals, conflict handling, later edits, covers, and account isolation. Save As creates a standalone CAD project. Cover failure remains nonfatal to native saving.

Backend and release checks

  • Apply association and initial-STEP database increments and verify cover migrations.
  • Verify owner isolation, active association uniqueness, idempotent retries, quota accounting and documented errors.
  • Keep referenced STEP object bytes immutable and retained while a CAD project needs them, including after workspace replacement or deletion.
  • Workspace deletion must not delete CAD. CAD deletion releases its association; a later workspace edit can create a fresh CAD code.
  • Enable CAD native uploads with CAD_OSS_ENABLED and existing shared OSS settings. Creating an association does not depend on this switch.
  • Check real frontend-origin CORS for both STEP reads and native uploads/reads. Object-store 403 does not expire platform authentication.
  • Deploy backend, engine assets/manifest, then host code. Retain previous build-id assets for open tabs and rollback; do not clear drafts, auth, CAD data or associations.

The local workspace contains no backend service implementation. The mock exercises this contract; it does not verify deployed database transactions, resource retention or production CORS.

Validation

npm run test:cad covers metadata, association transport, opening precedence, recovery, stale requests and limits. npm run test:cad:browser adds the real WASM STEP import/save/reopen path, draft recovery without the source, atomic failure/cancellation, and workspace removal/deletion behavior against the mock. Existing cover, assistant, save, browser, and engine-update checks remain relevant. Rust loader tests verify prepare-only completion and cancellation without changing the active host document. Run WASM checks and the required repository gates before committing.

For focused integration checks, set VM_CAD_BROWSER_SUITE=workspace when running the browser suite. VM_CAD_BASE_URL points at the local frontend proxy and VM_CAD_ARTIFACT_DIR enables screenshots and JSON results. Tests must use the local mock backend, not a production account or project.