dsh-cad 0.2.0 → 0.8.0

package/lib/tools/cad-model.js

@@ -6,6 +6,7 @@ import { composeAssemblyMeshes } from '../modeling/assembly.js';
 import { buildDrawingSheet, drawingToDxf, drawingToSvg } from '../modeling/drawing.js';
 import { resolveWorkspacePath } from './util.js';
 import { toDcPrtDocument } from '../feature_script/dc_prt.js';
+import { createConstraintTools } from './cad-constraint.js';
 /** Mirror a worker mesh with its raw typed arrays (binary-transport ready). */
 function mirrorMesh(mesh, bodyId) {
     return {
@@ -15,17 +16,22 @@ function mirrorMesh(mesh, bodyId) {
         indices: mesh.indices,
     };
 }
-/** Build the whole tool family over one document + worker + scene store. */
+/** Build the whole tool family over the document registry + worker + stores. */
 export function createModelTools(deps) {
-    const document = new ModelDocument(deps.workspaceRoot);
+    // The active document and its derived caches are swapped as a unit whenever
+    // a session's binding points elsewhere (see resolveDoc). meshCache /
+    // drawingSheets are cleared and rebuilt by replay.
+    let document = new ModelDocument(deps.workspaceRoot);
     /** bodyId → raw worker mesh mirror (binary scene source, zero encoding). */
     const meshCache = new Map();
     /** Reset epoch after the last sync — out-of-band replays (cad_view on a
      *  .dcprt) bump the epoch and force a re-replay before the next op. */
     let syncedEpoch = -1;
     /** drawingId → rebuilt sheet (backing cad_export .svg/.dxf). */
-    const drawingSheets = new Map();
+    let drawingSheets = new Map();
     let lastDrawingId = null;
+    /** Live constraint-model state (rebuilt from the op log on replay). */
+    const constraintState = { model: null, lastSuggestions: [] };
     /**
      * Standard drawing views (GB first-angle): 主视图 front, 俯视图 top,
      * 左视图 left, 轴测 iso. Same constants as the worker's fallback.
@@ -46,34 +52,44 @@ export function createModelTools(deps) {
         const salted = (hex.slice(0, 12) + salt + hex.slice(13)).slice(0, 32);
         return `${salted.slice(0, 8)}-${salted.slice(8, 12)}-${salted.slice(12, 16)}-${salted.slice(16, 20)}-${salted.slice(20, 32)}`;
     };
-    async function restoreOnce() {
-        if (syncedEpoch === workerResetEpoch())
-            return;
-        await document.restore();
-        if (document.doc.ops.length > 0) {
-            await runModelOp({ kind: 'reset' });
-            for (const op of document.doc.ops) {
-                try {
-                    const result = await runModelOp(op);
-                    // A replayed drawing re-generates its sheet and re-publishes the
-                    // scene so the stable viewId keeps serving after restarts.
-                    if (op.kind === 'drawing' && op.sceneViewId !== undefined && result.views !== undefined) {
-                        const sheet = buildDrawingSheet({ partName: op.name ?? op.target, views: result.views, paper: op.paper });
-                        drawingSheets.set(op.sceneViewId, { sheet, partName: op.name ?? op.target });
-                        lastDrawingId = op.sceneViewId;
-                        await deps.sceneStore.putAt(op.sceneViewId, {
-                            kind: '2d',
-                            format: 'drawing',
-                            entities: sheet.entities,
-                            bounds: sheet.bounds,
-                            layers: sheet.layers,
-                        });
-                    }
+    /**
+     * Replay a document's ops into the worker and rebuild the derived caches
+     * (mesh mirror, drawing sheets, constraint model). The worker is always
+     * reset first — also for empty documents, so a previous document's shapes
+     * never leak in. Absorbs the old restoreOnce body.
+     */
+    async function replayActiveDoc() {
+        await runModelOp({ kind: 'reset' });
+        // Derived state belongs to the outgoing document: clear before replay so
+        // a document without constraints/drawings never inherits the previous one's.
+        constraintState.model = null;
+        for (const op of document.doc.ops) {
+            try {
+                const result = await runModelOp(op);
+                // A replayed constraint model returns to live state.
+                if (op.kind === 'constraints') {
+                    constraintState.model = op.model;
                 }
-                catch {
-                    // A single stale op must not block recovery; later ops may be independent.
+                // A replayed drawing re-generates its sheet and re-publishes the
+                // scene so the stable viewId keeps serving after restarts.
+                if (op.kind === 'drawing' && op.sceneViewId !== undefined && result.views !== undefined) {
+                    const sheet = buildDrawingSheet({ partName: op.name ?? op.target, views: result.views, paper: op.paper });
+                    drawingSheets.set(op.sceneViewId, { sheet, partName: op.name ?? op.target });
+                    lastDrawingId = op.sceneViewId;
+                    await deps.sceneStore.putAt(op.sceneViewId, {
+                        kind: '2d',
+                        format: 'drawing',
+                        entities: sheet.entities,
+                        bounds: sheet.bounds,
+                        layers: sheet.layers,
+                    });
                 }
             }
+            catch {
+                // A single stale op must not block recovery; later ops may be independent.
+            }
+        }
+        if (document.doc.ops.length > 0) {
             const all = await runModelOp({ kind: 'tessellate_all' });
             meshCache.clear();
             for (const mesh of all.meshes ?? []) {
@@ -82,6 +98,62 @@ export function createModelTools(deps) {
         }
         syncedEpoch = workerResetEpoch();
     }
+    /** Swap the active document: restore from disk, reset the worker, replay. */
+    async function activateDocument(next) {
+        await next.restore();
+        document = next;
+        meshCache.clear();
+        drawingSheets = new Map();
+        lastDrawingId = null;
+        await replayActiveDoc();
+    }
+    /** Session key from the tool run context (`_default` outside a session). */
+    const sessionKeyOf = (exec) => {
+        const agent = exec?.agent;
+        return typeof agent?.id === 'string' && agent.id !== '' ? agent.id : '_default';
+    };
+    /**
+     * Per-op entry point (replaces restoreOnce): resolve the calling session's
+     * active document, switching documents (reset + replay) when its binding
+     * points elsewhere, then re-sync when the worker was reset out of band.
+     */
+    async function resolveDoc(exec) {
+        const sessionId = sessionKeyOf(exec);
+        const bound = await deps.registry.bindingOf(sessionId);
+        if (bound === null) {
+            // Upgrade continuity: the first unbound session inherits the migrated
+            // legacy document (if any) instead of starting from scratch.
+            const legacy = await deps.registry.claimLegacyFor(sessionId);
+            if (legacy !== null) {
+                const doc = await deps.registry.open(legacy);
+                if (doc !== null) {
+                    await activateDocument(doc);
+                    return;
+                }
+            }
+            // Unbound session (new conversation): start on a fresh empty document.
+            const fresh = await deps.registry.create();
+            await deps.registry.bind(sessionId, fresh.doc.docId);
+            await activateDocument(fresh);
+            return;
+        }
+        if (bound !== document.doc.docId) {
+            const next = await deps.registry.open(bound);
+            if (next === null) {
+                // Manifest entry without a document file — recover with a fresh doc.
+                const fresh = await deps.registry.create();
+                await deps.registry.bind(sessionId, fresh.doc.docId);
+                await activateDocument(fresh);
+                return;
+            }
+            await activateDocument(next);
+            return;
+        }
+        if (syncedEpoch !== workerResetEpoch()) {
+            await document.restore();
+            await replayActiveDoc();
+        }
+    }
     async function syncScene(op, result, filePath) {
         if (result.mesh !== undefined && result.bodyId !== undefined) {
             meshCache.set(result.bodyId, mirrorMesh(result.mesh, result.bodyId));
@@ -94,6 +166,7 @@ export function createModelTools(deps) {
             meshCache.delete(id);
         const nameEntry = result.bodyId !== undefined && result.name !== undefined ? { bodyId: result.bodyId, name: result.name } : null;
         await document.record(op, nameEntry);
+        await deps.registry.touch(document.doc.docId, { opCount: document.doc.version, bodyCount: meshCache.size });
         const meshes = [...meshCache.values()];
         const triangles = meshes.reduce((sum, mesh) => sum + mesh.indices.length / 3, 0);
         const sceneUrlBase = deps.ensureSceneRoute();
@@ -134,6 +207,7 @@ export function createModelTools(deps) {
         const instances = result.instances ?? [];
         const meshes = composeAssemblyMeshes(meshCache, instances);
         await document.record(op, null);
+        await deps.registry.touch(document.doc.docId, { opCount: document.doc.version, bodyCount: meshCache.size });
         const sceneUrlBase = deps.ensureSceneRoute();
         if (sceneUrlBase !== null) {
             // Publish even when empty — removing the last instance must refresh the tab.
@@ -248,7 +322,7 @@ export function createModelTools(deps) {
     };
     const renderDrawing = (value) => {
         const lines = [
-            `工程图 ${String(value.target)}: 主视图/俯视图/左视图/轴测 · 比例 ${String(value.scaleText ?? '')} · ${String(value.entities)} 实体 (version ${String(value.version)})`,
+            `工程图 ${String(value.target)}: 主视图/俯视图/左视图/轴测 · OCCT 真实消隐 · 比例 ${String(value.scaleText ?? '')} · ${String(value.entities)} 实体 (version ${String(value.version)})`,
         ];
         if (value.filePath !== undefined)
             lines.push(`written: ${String(value.filePath)}`);
@@ -328,8 +402,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const bodyId = nextBodyId();
             const params = args;
             const op = { kind: 'create_prim', bodyId, prim: args.kind, params, name: args.name };
@@ -341,9 +415,11 @@ export function createModelTools(deps) {
     });
     const cadExtrude = defineTool({
         name: 'cad_extrude_profile',
-        description: 'Create a solid by extruding a closed polygon profile in the XY plane along +Z (mm). `points` is a flat [x0,y0, x1,y1, …] loop (≥3 points, auto-closed). Use cad_boolean with cylinders for holes.',
+        description: 'Create a solid by extruding a closed profile in the XY plane along +Z (mm). `profile` accepts CURVE SEGMENTS — {start: [x,y], segments: [{type: "line"|"arc"|"bspline", …}]} (arc: to/center/ccw; bspline: through-points, sampled smooth curve) — or {circle: {center, radius}} for a round profile. ' +
+            'The legacy flat `points` polygon loop (≥3 points, auto-closed) still works. Use cad_boolean for holes.',
         parameters: {
-            points: { type: 'array', required: true, items: { type: 'number' }, description: 'Flat [x0,y0,x1,y1,…] loop (mm).' },
+            points: { type: 'array', items: { type: 'number' }, description: 'Legacy flat [x0,y0,x1,y1,…] polygon loop (mm).' },
+            profile: { type: 'json', description: 'Curve-segment profile: {start:[x,y], segments:[…]} or {circle:{center:[x,y], radius}}.' },
             height: { type: 'number', description: 'Extrusion height (mm, default 10).' },
             base: { type: 'number', description: 'Z of the profile plane (mm, default 0).' },
             name: { type: 'string', description: 'Optional display name.' },
@@ -362,19 +438,292 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
-            if (args.points.length < 6 || args.points.length % 2 !== 0) {
-                throw new Error('points must be a flat array of ≥3 [x,y] pairs (≥6 numbers)');
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            if (args.profile === undefined && (args.points === undefined || args.points.length < 6 || args.points.length % 2 !== 0)) {
+                throw new Error('provide a curve-segment `profile` object or a flat points array of ≥3 [x,y] pairs');
             }
             const bodyId = nextBodyId();
-            const op = { kind: 'extrude_profile', bodyId, points: args.points, height: args.height, base: args.base, name: args.name };
+            const op = { kind: 'extrude_profile', bodyId, ...(args.profile !== undefined ? { profile: args.profile } : { points: args.points }), height: args.height, base: args.base, name: args.name };
             const result = await runModelOp(op);
             return syncScene(op, result);
         },
         presentCall: () => ({ card: 'generic', title: 'CAD extrude profile', kind: 'other' }),
         presentResult: () => ({ card: 'generic', title: 'CAD extrude' }),
     });
+    const cadLoft = defineTool({
+        name: 'cad_loft',
+        description: 'Loft (放样): skin a solid through successive closed sections. `sections` is a list of ≥2 loops, each a flat [x0,y0,z0, x1,y1,z1, …] triplet list in its own plane (≥3 points, auto-closed), ordered along the loft. ' +
+            'Sections may differ in shape and point count (e.g. a square lofted to a hexagon). `ruled` keeps the sides straight instead of smoothing. ' +
+            'Each result passes a BRepCheck validity gate: a self-intersecting or degenerate loft is rejected with a clear message instead of storing an unusable body.',
+        parameters: {
+            sections: {
+                type: 'array',
+                required: true,
+                description: 'Ordered sections, each a flat [x,y,z,…] loop (≥9 numbers).',
+                items: { type: 'array', items: { type: 'number' }, description: 'One closed section loop.' },
+            },
+            ruled: { type: 'boolean', description: 'Straight (ruled) sides instead of a smoothed surface (default false).' },
+            solid: { type: 'boolean', description: 'Cap the ends into a solid (default true).' },
+            name: { type: 'string', description: 'Optional display name.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            if (!Array.isArray(args.sections) || args.sections.length < 2)
+                throw new Error('sections must list at least 2 closed loops');
+            const bodyId = nextBodyId();
+            const op = { kind: 'loft', bodyId, sections: args.sections, solid: args.solid, ruled: args.ruled, name: args.name };
+            const result = await runModelOp(op);
+            return syncScene(op, result);
+        },
+        presentCall: () => ({ card: 'generic', title: 'CAD loft', kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD loft' }),
+    });
+    const cadSweep = defineTool({
+        name: 'cad_sweep',
+        description: 'Sweep (扫掠): pipe a closed 2D profile along a 3D path. `profile` is a flat [x0,y0, x1,y1, …] outline (≥3 points, auto-closed) placed in the plane PERPENDICULAR TO THE PATH\'S START TANGENT, so the outline\'s 2D axes map onto that plane — no manual orientation needed. ' +
+            '`path` is a flat [x0,y0,z0, …] polyline. Straight, collinear and gently curved paths give exact solids; a SHARP direction change with a section large relative to the corner self-intersects — such a result is REJECTED by the BRepCheck validity gate (the error names the cause), so round or chamfer the corners in the path.',
+        parameters: {
+            profile: { type: 'json', required: true, description: 'Closed outline on the start plane: flat [x,y,…] array, {start, segments:[…]} curve chain, or {circle:{center,radius}}.' },
+            path: { type: 'array', required: true, items: { type: 'number' }, description: 'Sweep path as [x,y,z,…] triplets (≥6 numbers).' },
+            name: { type: 'string', description: 'Optional display name.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            const bodyId = nextBodyId();
+            const op = { kind: 'sweep', bodyId, profile: args.profile, path: args.path, name: args.name };
+            const result = await runModelOp(op);
+            return syncScene(op, result);
+        },
+        presentCall: () => ({ card: 'generic', title: 'CAD sweep', kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD sweep' }),
+    });
+    const cadRevolve = defineTool({
+        name: 'cad_revolve',
+        description: 'Revolve (旋转): sweep a closed 2D profile around an axis into a solid of revolution — shafts, wheels, vases, cones, spheres. Profile coordinates are (radius, height) relative to the axis: with the default +Z axis, profile [x,y] means radius x at height y. ' +
+            'Accepts the same curve-segment profiles as cad_extrude_profile (lines/arcs/bspline/circle), so rounded rims are exact. `angle` in degrees (default 360).',
+        parameters: {
+            profile: { type: 'json', required: true, description: 'Profile in (radius, height): flat [r0,h0, r1,h1,…] loop, {start, segments:[…]}, or {circle:{center,radius}}.' },
+            angle: { type: 'number', description: 'Sweep angle in degrees (default 360).' },
+            axis: { type: 'array', items: { type: 'number' }, description: 'Revolve axis direction [x,y,z] (default +Z).' },
+            at: { type: 'array', items: { type: 'number' }, description: 'A point the axis passes through [x,y,z] (default origin).' },
+            name: { type: 'string', description: 'Optional display name.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            const bodyId = nextBodyId();
+            const op = {
+                kind: 'revolve', bodyId, profile: args.profile,
+                ...(args.angle !== undefined ? { angle: (args.angle * Math.PI) / 180 } : {}),
+                ...(Array.isArray(args.axis) ? { axis: args.axis } : {}),
+                ...(Array.isArray(args.at) ? { at: args.at } : {}),
+                ...(args.name !== undefined ? { name: args.name } : {}),
+            };
+            const result = await runModelOp(op);
+            return syncScene(op, result);
+        },
+        presentCall: () => ({ card: 'generic', title: 'CAD revolve', kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD revolve' }),
+    });
+    const cadChamfer = defineTool({
+        name: 'cad_chamfer',
+        description: 'Chamfer (倒角): bevel every sharp edge of a body with one equal distance (mm). Fails when the distance exceeds the adjacent faces.',
+        parameters: {
+            target: bodyTarget,
+            distance: { type: 'number', required: true, description: 'Chamfer distance (mm).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            const op = { kind: 'chamfer', target: args.target, distance: args.distance };
+            const result = await runModelOp(op);
+            return syncScene(op, result);
+        },
+        presentCall: (args) => ({ card: 'generic', title: `CAD chamfer ${String(args.target)}`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD chamfer' }),
+    });
+    const cadShell = defineTool({
+        name: 'cad_shell',
+        description: 'Shell (抽壳): hollow a solid into a wall of `thickness` mm (the wall grows inward, the outer skin is preserved). `open` lists outward NORMALS [x,y,z] whose faces become openings (e.g. [[0,0,1]] opens the top of a box; empty = sealed hollow). ' +
+            'Runs on the occt.ts kernel (>= 0.3.0): the result becomes a HOSTED body — volume/export(.step)/display keep working, but opencascade.js-only edits (fillet/chamfer/loft/sweep/revolve/boolean) on it are refused, so do those before shelling.',
+        parameters: {
+            target: bodyTarget,
+            thickness: { type: 'number', required: true, description: 'Wall thickness (mm, positive).' },
+            open: { type: 'array', items: { type: 'array', items: { type: 'number' } }, description: 'Outward normals of the faces to open, e.g. [[0,0,1]].' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            const op = { kind: 'shell', target: args.target, thickness: args.thickness, ...(Array.isArray(args.open) ? { openNormals: args.open } : {}) };
+            const result = await runModelOp(op);
+            return syncScene(op, result);
+        },
+        presentCall: (args) => ({ card: 'generic', title: `CAD shell ${String(args.target)}`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD shell' }),
+    });
+    const cadDraft = defineTool({
+        name: 'cad_draft',
+        description: 'Draft (拔模): tilt the walls of a solid by `angle` degrees for mold release — faces pivot about a neutral plane, dimensions there unchanged. `direction` is the pull direction (default +Z); by default the faces parallel to it (the walls) are drafted. ' +
+            'Runs on the occt.ts kernel (>= 0.3.0): the result becomes a HOSTED body (same caveats as cad_shell).',
+        parameters: {
+            target: bodyTarget,
+            angle: { type: 'number', required: true, description: 'Draft angle in degrees (positive opens the walls toward the pull direction).' },
+            direction: { type: 'array', items: { type: 'number' }, description: 'Pull direction [x,y,z] (default +Z).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            const op = { kind: 'draft', target: args.target, angle: args.angle, ...(Array.isArray(args.direction) ? { direction: args.direction } : {}) };
+            const result = await runModelOp(op);
+            return syncScene(op, result);
+        },
+        presentCall: (args) => ({ card: 'generic', title: `CAD draft ${String(args.target)} ${String(args.angle ?? '')}°`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD draft' }),
+    });
+    const cadPattern = defineTool({
+        name: 'cad_pattern',
+        description: 'Pattern (阵列): replicate a body into `count` total placements. Linear: `delta` [dx,dy,dz] spacing per copy. Circular: rotate copies around a principal axis (+X/+Y/+Z) through `at` over `angle` degrees (default 360). Creates new bodies (target·1 … target·(count−1)); fuse afterwards for a single body.',
+        parameters: {
+            target: bodyTarget,
+            mode: { type: 'string', required: true, enum: ['linear', 'circular'], description: 'Pattern mode.' },
+            count: { type: 'number', required: true, description: 'Total placements (≥2).' },
+            delta: { type: 'array', items: { type: 'number' }, description: 'linear: spacing [dx,dy,dz] per copy (mm).' },
+            axis: { type: 'array', items: { type: 'number' }, description: 'circular: principal axis [x,y,z] (default +Z).' },
+            at: { type: 'array', items: { type: 'number' }, description: 'circular: axis point [x,y,z] (default origin).' },
+            angle: { type: 'number', description: 'circular: total sweep in degrees (default 360).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bodyId: { type: 'string', required: true },
+                    created: { type: 'array', items: { type: 'string' }, required: true, description: 'Ids of the newly created copy bodies.' },
+                    ...requiredCounts,
+                    ...commonOptional,
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModel(value) + '\ncreated: ' + value.created.join(', ') }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            await resolveDoc(exec);
+            if (args.mode === 'linear' && !Array.isArray(args.delta))
+                throw new Error('linear patterns need delta: [dx,dy,dz]');
+            const op = {
+                kind: 'pattern', target: args.target, mode: args.mode, count: args.count,
+                ...(Array.isArray(args.delta) ? { delta: args.delta } : {}),
+                ...(Array.isArray(args.axis) ? { axis: args.axis } : {}),
+                ...(Array.isArray(args.at) ? { at: args.at } : {}),
+                ...(args.angle !== undefined ? { angle: args.angle } : {}),
+            };
+            const result = await runModelOp(op);
+            const created = (result.created ?? []).map((entry) => {
+                if (entry.mesh !== undefined)
+                    meshCache.set(entry.bodyId, mirrorMesh(entry.mesh, entry.bodyId));
+                return entry.bodyId;
+            });
+            await document.record(op, null);
+            const meshes = [...meshCache.values()];
+            const sceneUrlBase = deps.ensureSceneRoute();
+            if (sceneUrlBase !== null && meshes.length > 0) {
+                await deps.store.publish(document.doc.docId, meshes);
+            }
+            const value = {
+                bodyId: args.target,
+                created,
+                triangles: meshes.reduce((sum, mesh) => sum + mesh.indices.length / 3, 0),
+                bodies: meshes.length,
+                version: document.doc.version,
+                ...(sceneUrlBase !== null ? { sceneUrl: `${sceneUrlBase.replace('/scene', '/bin')}/${document.doc.docId}?v=${document.doc.version}` } : {}),
+            };
+            return value;
+        },
+        presentCall: (args) => ({ card: 'generic', title: `CAD ${String(args.mode ?? '')} pattern ×${String(args.count ?? '')}`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: 'CAD pattern' }),
+    });
     const cadBoolean = defineTool({
         name: 'cad_boolean',
         description: 'Boolean-combine bodies: fuse (union), cut (subtract tools from target), common (intersection). Consumed tool bodies are removed; the result keeps the target bodyId. Classic pattern for holes: cut a cylinder from a plate.',
@@ -397,8 +746,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = { kind: 'boolean', op: args.op, target: args.target, tools: args.tools };
             const result = await runModelOp(op);
             return syncScene(op, result);
@@ -427,8 +776,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = { kind: 'fillet', target: args.target, radius: args.radius };
             const result = await runModelOp(op);
             return syncScene(op, result);
@@ -459,8 +808,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = {
                 kind: 'transform',
                 target: args.target,
@@ -514,8 +863,8 @@ export function createModelTools(deps) {
             },
         },
         isConcurrencySafe: () => true,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const resolved = resolveWorkspacePath(args.path, deps.workspaceRoot);
             const lower = args.path.toLowerCase();
             // Assembly export: compound of transformed instances via the worker.
@@ -611,8 +960,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = { kind: 'delete', target: args.target };
             const result = await runModelOp(op);
             return syncScene(op, result);
@@ -640,8 +989,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => metaOf(value),
         },
         isConcurrencySafe: () => true,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = { kind: 'volume', target: args.target };
             const result = await runModelOp(op);
             return syncScene(op, result);
@@ -668,8 +1017,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => drawingMetaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const target = args.target ?? lastBodyId();
             if (target === undefined)
                 throw new Error('nothing to draw — create a body first');
@@ -717,8 +1066,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => assemblyMetaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             if (!meshCache.has(args.bodyId))
                 throw new Error(`unknown body: ${args.bodyId}`);
             const instanceId = nextInstanceId();
@@ -750,8 +1099,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => assemblyMetaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = {
                 kind: 'assembly_transform',
                 instanceId: args.instanceId,
@@ -776,8 +1125,8 @@ export function createModelTools(deps) {
             presentationMeta: (_args, value) => assemblyMetaOf(value),
         },
         isConcurrencySafe: () => false,
-        async execute(args) {
-            await restoreOnce();
+        async execute(args, exec) {
+            await resolveDoc(exec);
             const op = { kind: 'assembly_remove', instanceId: args.instanceId };
             const result = await runModelOp(op);
             return syncAssembly(op, result);
@@ -785,9 +1134,244 @@ export function createModelTools(deps) {
         presentCall: (args) => ({ card: 'generic', title: `移除 ${String(args.instanceId)}`, kind: 'delete' }),
         presentResult: () => ({ card: 'generic', title: '装配移除' }),
     });
+    // ── document (file space) tools ───────────────────────────────────────────
+    const docRefParam = { type: 'string', required: true, description: 'Document id or exact name (list with cad_docs).' };
+    const renderDocs = (value) => {
+        const docs = Array.isArray(value.docs) ? value.docs : [];
+        const active = typeof value.activeDoc === 'string' ? value.activeDoc : '';
+        const lines = docs.map((doc) => `${doc.id === active ? '● ' : '  '}${String(doc.name)} · ${Number(doc.bodies)} 体 · ${String(doc.updatedAt).slice(0, 16).replace('T', ' ')} · ${String(doc.id)}`);
+        return lines.length > 0 ? ['工作区文档:', ...lines].join('\n') : '工作区还没有建模文档';
+    };
+    const cadDocs = defineTool({
+        name: 'cad_docs',
+        description: 'List the workspace modeling documents (the file space): id, name, body count and update time, marking the one active for this session. ' +
+            'Call before cad_doc_open / cad_doc_delete to discover ids and names.',
+        parameters: {},
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    docs: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                id: { type: 'string', required: true },
+                                name: { type: 'string', required: true },
+                                bodies: { type: 'number', required: true },
+                                ops: { type: 'number', required: true },
+                                updatedAt: { type: 'string', required: true },
+                                active: { type: 'boolean' },
+                            },
+                        },
+                    },
+                    activeDoc: { type: 'string', description: 'Active document id for this session (absent: none).' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderDocs(value) }],
+        },
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            const sessionId = sessionKeyOf(exec);
+            const docs = await deps.registry.list();
+            const activeDoc = await deps.registry.bindingOf(sessionId);
+            return {
+                docs: docs.map((doc) => ({ id: doc.id, name: doc.name, bodies: doc.bodyCount, ops: doc.opCount, updatedAt: doc.updatedAt, ...(doc.id === activeDoc ? { active: true } : {}) })),
+                ...(activeDoc === null ? {} : { activeDoc }),
+            };
+        },
+        presentCall: () => ({ card: 'generic', title: '文档列表', kind: 'read' }),
+        presentResult: () => ({ card: 'generic', title: '文档列表' }),
+    });
+    const cadDocNew = defineTool({
+        name: 'cad_doc_new',
+        description: 'Create a new modeling document and make it this session\'s active modeling target (previous documents stay in the file space). ' +
+            'Name it when the task has a clear subject (e.g. 发动机 / 齿轮箱) — start multi-part projects with this tool so each project keeps its own document.',
+        parameters: {
+            name: { type: 'string', description: 'Document name (default: 未命名 N).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    docId: { type: 'string', required: true, description: 'New document id.' },
+                    name: { type: 'string', required: true, description: 'Document name.' },
+                    bodies: { type: 'number', required: true, description: 'Bodies (0 for a fresh document).' },
+                    version: { type: 'number', required: true, description: 'Document version.' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `新建文档 ${String(value.name)}（后续建模操作都写入该文档）` }],
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const sessionId = sessionKeyOf(exec);
+            const doc = await deps.registry.create(args.name);
+            await deps.registry.bind(sessionId, doc.doc.docId);
+            await activateDocument(doc);
+            const name = (await deps.registry.list()).find((meta) => meta.id === doc.doc.docId)?.name ?? doc.doc.docId;
+            return { docId: doc.doc.docId, name, bodies: 0, version: doc.doc.version };
+        },
+        presentCall: (args) => ({ card: 'generic', title: `新建文档 ${String(args.name ?? '')}`.trim(), kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: '新建文档' }),
+    });
+    const cadDocOpen = defineTool({
+        name: 'cad_doc_open',
+        description: 'Open an existing modeling document and make it this session\'s active modeling target (its bodies load back exactly). ' +
+            'Use when the user asks to continue an earlier model (e.g. “打开发动机文档”) — resolve the id/name with cad_docs first when unsure.',
+        parameters: {
+            doc: docRefParam,
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    docId: { type: 'string', required: true, description: 'Opened document id.' },
+                    name: { type: 'string', required: true, description: 'Document name.' },
+                    bodies: { type: 'number', required: true, description: 'Bodies in the document.' },
+                    triangles: { type: 'number', required: true, description: 'Document triangle count.' },
+                    version: { type: 'number', required: true, description: 'Document version.' },
+                    sceneUrl: { type: 'string', description: 'Versioned viewer URL (web compositions).' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `打开文档 ${String(value.name)} · ${Number(value.bodies)} 体 (version ${Number(value.version)})` }],
+            presentationMeta: (_args, value) => metaOf(value),
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const sessionId = sessionKeyOf(exec);
+            const meta = await deps.registry.resolve(args.doc);
+            if (meta === null) {
+                const available = (await deps.registry.list()).map((doc) => doc.name).join(' / ');
+                throw new Error(`no document matches "${String(args.doc)}" — available: ${available === '' ? '(none)' : available}`);
+            }
+            await deps.registry.bind(sessionId, meta.id);
+            const doc = await deps.registry.open(meta.id);
+            if (doc === null)
+                throw new Error(`document file missing: ${meta.id}`);
+            await activateDocument(doc);
+            const meshes = [...meshCache.values()];
+            const triangles = meshes.reduce((sum, mesh) => sum + mesh.indices.length / 3, 0);
+            const sceneUrlBase = deps.ensureSceneRoute();
+            const value = {
+                docId: meta.id,
+                name: meta.name,
+                bodies: meshes.length,
+                triangles,
+                version: document.doc.version,
+            };
+            if (meshes.length > 0)
+                await deps.store.publish(meta.id, meshes);
+            if (meshes.length > 0 && sceneUrlBase !== null) {
+                value.sceneUrl = `${sceneUrlBase.replace('/scene', '/bin')}/${meta.id}?v=${document.doc.version}`;
+            }
+            return value;
+        },
+        presentCall: (args) => ({ card: 'generic', title: `打开文档 ${String(args.doc)}`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: '打开文档' }),
+    });
+    const cadDocRename = defineTool({
+        name: 'cad_doc_rename',
+        description: 'Rename a modeling document in the file space.',
+        parameters: {
+            doc: docRefParam,
+            name: { type: 'string', required: true, description: 'New document name.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    docId: { type: 'string', required: true, description: 'Document id.' },
+                    name: { type: 'string', required: true, description: 'New name.' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `文档已重命名为 ${String(value.name)}` }],
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            void exec;
+            const meta = await deps.registry.resolve(args.doc);
+            if (meta === null)
+                throw new Error(`no document matches "${String(args.doc)}"`);
+            const renamed = await deps.registry.rename(meta.id, args.name);
+            if (renamed === null)
+                throw new Error(`rename failed: ${meta.id}`);
+            return { docId: renamed.id, name: renamed.name };
+        },
+        presentCall: (args) => ({ card: 'generic', title: `重命名文档 ${String(args.doc)}`, kind: 'other' }),
+        presentResult: () => ({ card: 'generic', title: '重命名文档' }),
+    });
+    const cadDocDelete = defineTool({
+        name: 'cad_doc_delete',
+        description: 'Permanently delete a modeling document from the file space (op log + bodies). Requires confirm=true — ask the user before calling. ' +
+            'To delete a single body inside a document, use cad_delete instead.',
+        parameters: {
+            doc: docRefParam,
+            confirm: { type: 'boolean', required: true, description: 'Must be explicitly true to delete.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    deleted: { type: 'string', required: true, description: 'Deleted document id.' },
+                    name: { type: 'string', required: true, description: 'Deleted document name.' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `已删除文档 ${String(value.name)}` }],
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            void exec;
+            if (args.confirm !== true) {
+                throw new Error('pass confirm=true to delete — this permanently removes the document and its bodies');
+            }
+            const meta = await deps.registry.resolve(args.doc);
+            if (meta === null)
+                throw new Error(`no document matches "${String(args.doc)}"`);
+            const removed = await deps.registry.remove(meta.id);
+            if (!removed)
+                throw new Error(`delete failed: ${meta.id}`);
+            // Drop the active-document state if it was the deleted one; the next
+            // modeling op lazily creates a fresh document for its session.
+            if (document.doc.docId === meta.id) {
+                document = new ModelDocument(deps.workspaceRoot);
+                meshCache.clear();
+                drawingSheets = new Map();
+                lastDrawingId = null;
+                syncedEpoch = -1;
+            }
+            return { deleted: meta.id, name: meta.name };
+        },
+        presentCall: (args) => ({ card: 'generic', title: `删除文档 ${String(args.doc)}`, kind: 'delete' }),
+        presentResult: () => ({ card: 'generic', title: '删除文档' }),
+    });
+    // ── constraint tools (Ansatz solver) ──────────────────────────────────────
+    const constraintTools = createConstraintTools({
+        deps,
+        // Read the ACTIVE document per call: multi-document sessions swap it.
+        getDocument: () => document,
+        meshCache,
+        constraintState,
+        resolveDoc,
+        syncAssembly,
+        assemblyMetaOf,
+    });
     return [
         cadCreatePrim,
         cadExtrude,
+        cadRevolve,
+        cadChamfer,
+        cadShell,
+        cadDraft,
+        cadPattern,
+        cadLoft,
+        cadSweep,
         cadBoolean,
         cadFillet,
         cadTransform,
@@ -798,11 +1382,24 @@ export function createModelTools(deps) {
         cadAssemblyInsert,
         cadAssemblyMove,
         cadAssemblyRemove,
+        cadDocs,
+        cadDocNew,
+        cadDocOpen,
+        cadDocRename,
+        cadDocDelete,
+        ...constraintTools,
     ];
 }
 export const MODEL_TOOL_NAMES = [
     'cad_create_prim',
     'cad_extrude_profile',
+    'cad_revolve',
+    'cad_chamfer',
+    'cad_shell',
+    'cad_draft',
+    'cad_pattern',
+    'cad_loft',
+    'cad_sweep',
     'cad_boolean',
     'cad_fillet',
     'cad_transform',
@@ -813,4 +1410,12 @@ export const MODEL_TOOL_NAMES = [
     'cad_assembly_insert',
     'cad_assembly_move',
     'cad_assembly_remove',
+    'cad_docs',
+    'cad_doc_new',
+    'cad_doc_open',
+    'cad_doc_rename',
+    'cad_doc_delete',
+    'cad_constraint',
+    'cad_solve',
+    'cad_motion',
 ];