@dreamerbird/camera-studio 0.2.0 → 0.3.0

package/dist/agent/commands/materials.test.js

@@ -0,0 +1,294 @@
+let projectSeq = 0;
+let activeFakeStudio;
+jest.doMock('@dreamerbird/core', () => ({
+    ...jest.requireActual('@dreamerbird/core'),
+    getStudioSync: () => activeFakeStudio,
+}));
+jest.doMock('@dreamerbird/studio/getStudio', () => ({
+    __esModule: true,
+    default: () => activeFakeStudio,
+}));
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+function setup(options = {}) {
+    const { getPointerParts } = require('@dreamerbird/dataverse');
+    const core = require('@dreamerbird/core');
+    const { globals } = require('@dreamerbird/core/globals');
+    const three = require('three');
+    const { AgentCommandRegistry } = require('../registry');
+    const { createAgentRuntime } = require('../runtime');
+    const objectRuntime = require('../runtime/objectRuntime');
+    const { registerMaterialCommands } = require('./materials');
+    const { registerKeyframeCommands } = require('./keyframes');
+    const { registerObjectCommands } = require('./objects');
+    const { PLACEMENTS_REGISTRY_KEY } = require('../../PlacementManager');
+    const { collectMaterialSlots, createMaterialOverridesConfig } = require('../../materials/modelMaterials');
+    const instance = new three.Group();
+    const mesh = new three.Mesh(new three.BoxGeometry(), new three.MeshStandardMaterial({ roughness: 0.8 }));
+    mesh.name = 'Body';
+    instance.add(mesh);
+    if (options.secondSlot) {
+        const sibling = new three.Mesh(new three.BoxGeometry(), new three.MeshStandardMaterial({ roughness: 0.7 }));
+        sibling.name = 'Trim';
+        instance.add(sibling);
+    }
+    const slots = collectMaterialSlots(instance);
+    const slot = slots[0];
+    const slotKey = slot.slotKey;
+    const calls = [];
+    const sequenceEditor = {
+        setPrimitivePropAsSequenced: jest.fn((args) => {
+            calls.push({ op: 'sequenceProp', args });
+        }),
+        setPrimitivePropAsStatic: jest.fn(),
+        transformKeyframes: jest.fn(),
+    };
+    const fakeStudio = {
+        transaction: jest.fn((fn, undoable) => fn({
+            set: (pointer, value) => {
+                const { path } = getPointerParts(pointer);
+                calls.push({ op: 'set', path: path.join('.'), value });
+            },
+            unset: (pointer) => {
+                const { path } = getPointerParts(pointer);
+                calls.push({ op: 'unset', path: path.join('.') });
+            },
+            stateEditors: {
+                coreByProject: {
+                    historic: { sheetsById: { sequence: sequenceEditor } },
+                },
+            },
+        })),
+    };
+    activeFakeStudio = fakeStudio;
+    cleanups.push(() => {
+        activeFakeStudio = undefined;
+    });
+    const trackPath = JSON.stringify(['materialOverrides', slotKey, 'roughness']);
+    const state = {
+        definitionVersion: globals.currentProjectStateDefinitionVersion,
+        sheetsById: {
+            Scene: {
+                staticOverrides: { byObject: {} },
+                sequence: {
+                    type: 'PositionalSequence',
+                    length: 10,
+                    subUnitsPerUnit: 30,
+                    tracksByObject: options.roughnessTrack
+                        ? {
+                            Foo: {
+                                trackIdByPropPath: { [trackPath]: 'roughness-track' },
+                                trackData: {
+                                    'roughness-track': {
+                                        type: 'BasicKeyframedTrack',
+                                        keyframes: {
+                                            byId: {
+                                                kf1: {
+                                                    id: 'kf1',
+                                                    position: 0,
+                                                    connectedRight: true,
+                                                    handles: [0.5, 0.5, 0.5, 0.5],
+                                                    value: 0.25,
+                                                },
+                                            },
+                                            allIds: { kf1: true },
+                                        },
+                                    },
+                                },
+                            },
+                        }
+                        : {},
+                },
+            },
+        },
+    };
+    const project = core.getProject(`agent-materials-${++projectSeq}`, {
+        state: state,
+    });
+    const sheet = project.sheet('Scene');
+    sheet.sequence.position = 0;
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => fakeStudio,
+        subscribeHistoric: () => () => { },
+    });
+    const registry = new AgentCommandRegistry();
+    registerMaterialCommands(registry, runtime);
+    const placement = {
+        entry: { key: 'Foo', position: { x: 0, y: 0, z: 0 } },
+        instance,
+    };
+    cleanups.push(runtime.bindHandlers({
+        getModelPlacement: ({ key }) => (key === 'Foo' ? placement : undefined),
+    }));
+    function mountFoo() {
+        const t = core.types;
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([placement.entry]),
+        };
+        const obj = sheet.object('Foo', {
+            materialOverrides: createMaterialOverridesConfig(slots),
+        });
+        objectRuntime.registerSceneSheetObject('model:Foo', obj);
+        cleanups.push(() => objectRuntime.unregisterSceneSheetObject('model:Foo', obj));
+        return obj;
+    }
+    return {
+        core,
+        registry,
+        runtime,
+        fakeStudio,
+        calls,
+        mountFoo,
+        slot,
+        slots,
+        instance,
+        registerKeyframeCommands: () => registerKeyframeCommands(registry, runtime),
+        registerObjectCommands: () => registerObjectCommands(registry, runtime),
+    };
+}
+test('materials.list returns evaluated values for the mounted model', async () => {
+    const { registry, mountFoo, slot } = setup({ roughnessTrack: true });
+    mountFoo();
+    const result = (await registry.execute('materials.list', { objectId: 'model:Foo' }, ctx()));
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+        slotId: slot.slotId,
+        slotKey: slot.slotKey,
+        meshName: 'Body',
+        values: { roughness: 0.25 },
+    });
+});
+test('materials.update writes one full compound patch in one undoable transaction', async () => {
+    const { registry, fakeStudio, calls, mountFoo, slot } = setup();
+    mountFoo();
+    const result = await registry.execute('materials.update', {
+        objectId: 'model:Foo',
+        slotId: slot.slotId,
+        values: { roughness: 0.4, color: '#112233' },
+    }, ctx());
+    expect(result).toEqual({ revision: 1 });
+    expect(fakeStudio.transaction).toHaveBeenCalledTimes(1);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ op: 'set', path: 'materialOverrides' });
+    const patch = calls[0].value;
+    expect(patch[slot.slotKey]).toMatchObject({
+        roughness: 0.4,
+        color: '#112233',
+        metalness: 0,
+        opacity: 1,
+        mapBlobId: '',
+    });
+});
+test('materials.update validates ranges, colors, textures, slots and empty patches before writing', async () => {
+    const { registry, fakeStudio, mountFoo, slot } = setup();
+    mountFoo();
+    const badValues = [
+        {},
+        { roughness: -0.1 },
+        { metalness: 1.1 },
+        { opacity: Number.NaN },
+        { color: 'red' },
+        { emissive: '#fff' },
+        { mapBlobId: 4 },
+        { unknown: true },
+    ];
+    for (const values of badValues) {
+        await expect(registry.execute('materials.update', { objectId: 'model:Foo', slotId: slot.slotId, values }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    }
+    await expect(registry.execute('materials.update', { objectId: 'model:Foo', slotId: 'missing', values: { roughness: 0.2 } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(fakeStudio.transaction).not.toHaveBeenCalled();
+});
+test('materials.update honors expectedRevision and rejects sequenced properties', async () => {
+    const sequenced = setup({ roughnessTrack: true });
+    sequenced.mountFoo();
+    await expect(sequenced.registry.execute('materials.update', {
+        objectId: 'model:Foo',
+        slotId: sequenced.slot.slotId,
+        values: { roughness: 0.6 },
+    }, ctx())).rejects.toMatchObject({ code: 'INVALID_STATE' });
+    expect(sequenced.fakeStudio.transaction).not.toHaveBeenCalled();
+    const conflict = setup();
+    conflict.mountFoo();
+    await expect(conflict.registry.execute('materials.update', {
+        objectId: 'model:Foo',
+        slotId: conflict.slot.slotId,
+        values: { roughness: 0.6 },
+        expectedRevision: 99,
+    }, ctx())).rejects.toMatchObject({ code: 'REVISION_CONFLICT' });
+    expect(conflict.fakeStudio.transaction).not.toHaveBeenCalled();
+});
+test('materials.update guards only changed sequenced leaves and preserves siblings in one transaction', async () => {
+    const { registry, fakeStudio, calls, mountFoo, slot, slots } = setup({
+        roughnessTrack: true,
+        secondSlot: true,
+    });
+    mountFoo();
+    const sibling = slots[1];
+    for (const [slotId, values] of [
+        [slot.slotId, { color: '#112233' }],
+        [slot.slotId, { metalness: 0.6 }],
+        [slot.slotId, { mapBlobId: 'texture-new' }],
+        [sibling.slotId, { roughness: 0.45 }],
+    ]) {
+        await expect(registry.execute('materials.update', { objectId: 'model:Foo', slotId, values }, ctx())).resolves.toEqual({ revision: expect.any(Number) });
+    }
+    expect(fakeStudio.transaction).toHaveBeenCalledTimes(4);
+    const patches = calls
+        .filter((call) => call.op === 'set')
+        .map((call) => call.value);
+    expect(patches).toHaveLength(4);
+    expect(patches[0][slot.slotKey]).toMatchObject({
+        roughness: 0.25,
+        color: '#112233',
+    });
+    expect(patches[1][slot.slotKey]).toMatchObject({
+        roughness: 0.25,
+        metalness: 0.6,
+    });
+    expect(patches[2][slot.slotKey]).toMatchObject({
+        roughness: 0.25,
+        mapBlobId: 'texture-new',
+    });
+    expect(patches[3]).toMatchObject({
+        [slot.slotKey]: { roughness: 0.25 },
+        [sibling.slotKey]: { roughness: 0.45 },
+    });
+});
+test('roughness accepts keyframes at the materialOverrides compound leaf', async () => {
+    const { registry, registerKeyframeCommands, calls, mountFoo, slot } = setup();
+    mountFoo();
+    registerKeyframeCommands();
+    await registry.execute('keyframes.set', {
+        objectId: 'model:Foo',
+        propPath: ['materialOverrides', slot.slotKey, 'roughness'],
+        at: 0,
+        value: 0.35,
+    }, ctx());
+    expect(calls).toContainEqual({
+        op: 'set',
+        path: `materialOverrides.${slot.slotKey}.roughness`,
+        value: 0.35,
+    });
+});
+test('objects.update cannot write materialOverrides directly', async () => {
+    const { registry, registerObjectCommands, fakeStudio, mountFoo, slot } = setup();
+    mountFoo();
+    registerObjectCommands();
+    await expect(registry.execute('objects.update', {
+        objectId: 'model:Foo',
+        props: { materialOverrides: { [slot.slotKey]: slot.values } },
+    }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(fakeStudio.transaction).not.toHaveBeenCalled();
+});
+export {};

package/dist/agent/commands/modelRecovery.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=modelRecovery.test.d.ts.map

package/dist/agent/commands/modelRecovery.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelRecovery.test.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/modelRecovery.test.ts"],"names":[],"mappings":""}

package/dist/agent/commands/modelRecovery.test.js

@@ -0,0 +1,122 @@
+let activeFakeStudio;
+jest.doMock('@dreamerbird/studio/getStudio', () => ({
+    __esModule: true,
+    default: () => activeFakeStudio,
+}));
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+test('retry and replacement remount an unmounted model in one undoable transaction', async () => {
+    const core = require('@dreamerbird/core');
+    const { globals } = require('@dreamerbird/core/globals');
+    const { AgentCommandRegistry } = require('../registry');
+    const { createAgentRuntime } = require('../runtime');
+    const { registerModelCommands } = require('./models');
+    const { PLACEMENTS_REGISTRY_KEY } = require('../../PlacementManager');
+    const project = core.getProject('agent-model-recovery', {
+        state: {
+            definitionVersion: globals.currentProjectStateDefinitionVersion,
+            sheetsById: {
+                Scene: {
+                    staticOverrides: { byObject: {} },
+                    sequence: {
+                        type: 'PositionalSequence',
+                        length: 10,
+                        subUnitsPerUnit: 30,
+                        tracksByObject: {},
+                    },
+                },
+            },
+        },
+    });
+    const sheet = project.sheet('Scene');
+    const registryObject = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: core.types.string('[]') }, { hideFromOutline: true });
+    registryObject.initialValue = {
+        list: JSON.stringify([
+            {
+                key: 'Broken',
+                libraryEntryId: 'old-model',
+                position: { x: 1, y: 2, z: 3 },
+            },
+        ]),
+    };
+    const calls = [];
+    let notifyHistoric = () => { };
+    const fakeStudio = {
+        transaction: jest.fn((fn) => {
+            fn({
+                set: (pointer, value) => {
+                    const { getPointerParts } = require('@dreamerbird/dataverse');
+                    calls.push({
+                        path: getPointerParts(pointer).path.join('.'),
+                        value,
+                    });
+                },
+            });
+            queueMicrotask(() => notifyHistoric());
+        }),
+    };
+    activeFakeStudio = fakeStudio;
+    const replacement = {
+        id: 'new-model',
+        kind: 'model',
+        name: 'Replacement',
+        rig: 'static',
+        blobId: 'new-blob',
+        contentHash: 'new-hash',
+        boneCount: 0,
+        vertexCount: 8,
+        createdAt: 2,
+    };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {
+            getEntry: async (id) => id === replacement.id ? replacement : undefined,
+        },
+        getStudio: () => fakeStudio,
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const registry = new AgentCommandRegistry();
+    registerModelCommands(registry, runtime);
+    try {
+        await expect(registry.execute('models.retry', { objectId: 'model:Broken' }, ctx())).resolves.toEqual({ revision: expect.any(Number) });
+        await expect(registry.execute('models.replace', {
+            objectId: 'model:Broken',
+            assetId: replacement.id,
+        }, ctx())).resolves.toEqual({ revision: expect.any(Number) });
+        expect(fakeStudio.transaction).toHaveBeenCalledTimes(2);
+        const retryEntry = JSON.parse(String(calls[0].value))[0];
+        expect(retryEntry).toMatchObject({
+            key: 'Broken',
+            libraryEntryId: 'old-model',
+            loadAttempt: 1,
+            position: { x: 1, y: 2, z: 3 },
+        });
+        const replacementEntry = JSON.parse(String(calls[1].value))[0];
+        expect(replacementEntry).toMatchObject({
+            key: 'Broken',
+            libraryEntryId: replacement.id,
+            loadAttempt: 1,
+            position: { x: 1, y: 2, z: 3 },
+        });
+        expect(replacementEntry.assetId).toBeUndefined();
+    }
+    finally {
+        activeFakeStudio = undefined;
+        runtime.dispose();
+    }
+});
+test('failed model placeholder remains an identifiable scene object', () => {
+    const { Group, Mesh } = require('three');
+    const { createFailedModelPlaceholder } = require('../../PlacementManager');
+    const placeholder = createFailedModelPlaceholder('Broken');
+    expect(placeholder).toBeInstanceOf(Group);
+    expect(placeholder.name).toBe('Failed/Broken');
+    expect(placeholder.children.some((child) => child instanceof Mesh)).toBe(true);
+});
+export {};

package/dist/agent/commands/models.d.ts

@@ -29,6 +29,19 @@ export type ModelsApi = {
         objectId: SceneObjectId;
         revision: number;
     }>;
+    retry(args: {
+        objectId: string;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    replace(args: {
+        objectId: string;
+        assetId: string;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
 };
 export declare function registerModelCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
 //# sourceMappingURL=models.d.ts.map

package/dist/agent/commands/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/models.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAG5C,OAAO,KAAK,EAAa,aAAa,EAAE,IAAI,EAAC,MAAM,UAAU,CAAA;AAO7D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,0BAA0B,CAAA;AAExD,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB;QACjC;;;;;WAKG;QACH,WAAW,CAAC,IAAI,EAAE;YAAC,KAAK,EAAE,UAAU,CAAC;YAAC,QAAQ,EAAE,IAAI,CAAA;SAAC,GAAG;YACtD,GAAG,EAAE,MAAM,CAAA;YACX,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;SACzB,CAAA;KACF;CACF;AAED,8BAA8B;AAC9B,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,CAAC,IAAI,EAAE;QACX,OAAO,EAAE,MAAM,CAAA;QACf,QAAQ,EAAE,IAAI,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACzD,CAAA;AAwDD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAiGN"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/models.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAI5C,OAAO,KAAK,EAAa,aAAa,EAAE,IAAI,EAAC,MAAM,UAAU,CAAA;AAO7D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,0BAA0B,CAAA;AAExD,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB;QACjC;;;;;WAKG;QACH,WAAW,CAAC,IAAI,EAAE;YAAC,KAAK,EAAE,UAAU,CAAC;YAAC,QAAQ,EAAE,IAAI,CAAA;SAAC,GAAG;YACtD,GAAG,EAAE,MAAM,CAAA;YACX,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;SACzB,CAAA;KACF;CACF;AAED,8BAA8B;AAC9B,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,CAAC,IAAI,EAAE;QACX,OAAO,EAAE,MAAM,CAAA;QACf,QAAQ,EAAE,IAAI,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACxD,KAAK,CAAC,IAAI,EAAE;QACV,QAAQ,EAAE,MAAM,CAAA;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC/B,OAAO,CAAC,IAAI,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAChC,CAAA;AAwDD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CA2MN"}

package/dist/agent/commands/models.js

@@ -14,8 +14,9 @@
  * 对历史只呈现一步(undoable:single-step)。
  */
 import { AgentApiError } from '../errors';
-import { formatSceneObjectId } from '../objectIds';
+import { formatSceneObjectId, parseSceneObjectId } from '../objectIds';
 import { getSceneObjectSummary } from '../objectResolver';
+import { retryPlacement } from '../../PlacementManager';
 import { requireFiniteNumber, requireObject, requireString, requireVec3, } from '../validation';
 const vec3Schema = {
     type: 'object',
@@ -134,4 +135,100 @@ export function registerModelCommands(registry, runtime) {
             return { objectId, revision: await runtime.nextRevision() };
         },
     });
+    const recoveryInput = {
+        type: 'object',
+        properties: {
+            objectId: { type: 'string' },
+            expectedRevision: { type: 'number' },
+        },
+        required: ['objectId'],
+        additionalProperties: false,
+    };
+    const revisionOutput = {
+        type: 'object',
+        properties: { revision: { type: 'number' } },
+        required: ['revision'],
+    };
+    const validateRecovery = (value) => {
+        const args = requireObject(value);
+        return {
+            objectId: requireString(args, 'objectId'),
+            expectedRevision: optionalRecoveryRevision(args.expectedRevision),
+        };
+    };
+    const recover = (objectId, expectedRevision, replacementEntryId) => {
+        getSceneObjectSummary(runtime.sheet, objectId);
+        const { key } = parseSceneObjectId(objectId);
+        if (expectedRevision !== undefined)
+            runtime.assertRevision(expectedRevision);
+        if (!retryPlacement(runtime.sheet, key, replacementEntryId)) {
+            throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法重试模型加载');
+        }
+    };
+    registry.register({
+        name: 'models.retry',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: recoveryInput,
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'OBJECT_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateRecovery,
+        execute: async ({ objectId, expectedRevision }) => {
+            runtime.assertActive();
+            recover(objectId, expectedRevision);
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+    registry.register({
+        name: 'models.replace',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            ...recoveryInput,
+            properties: { ...recoveryInput.properties, assetId: { type: 'string' } },
+            required: ['objectId', 'assetId'],
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'ASSET_NOT_FOUND',
+            'OBJECT_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => ({
+            ...validateRecovery(value),
+            assetId: requireString(requireObject(value), 'assetId'),
+        }),
+        execute: async ({ objectId, assetId, expectedRevision }) => {
+            runtime.assertActive();
+            const entry = await runtime.library.getEntry(assetId);
+            if (!entry) {
+                throw new AgentApiError('ASSET_NOT_FOUND', `资产不存在: ${assetId}`, {
+                    details: { assetId },
+                });
+            }
+            if (entry.kind !== 'model') {
+                throw new AgentApiError('INVALID_ARGUMENT', `资产 ${assetId} 不是模型`);
+            }
+            recover(objectId, expectedRevision, assetId);
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+}
+function optionalRecoveryRevision(value) {
+    return value === undefined
+        ? undefined
+        : requireFiniteNumber(value, 'expectedRevision');
 }

package/dist/agent/commands/primitives.d.ts

@@ -0,0 +1,27 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId, Vec3 } from '../types';
+import type { PrimitiveKind } from '../../primitives';
+declare module '../runtime' {
+    interface AgentSceneRuntimeHandlers {
+        createPrimitive(args: {
+            kind: PrimitiveKind;
+            position: Vec3;
+        }): {
+            key: string;
+            persisted: Promise<void>;
+        };
+    }
+}
+export type PrimitivesApi = {
+    create(args: {
+        kind: PrimitiveKind;
+        position: Vec3;
+        expectedRevision?: number;
+    }): Promise<{
+        objectId: SceneObjectId;
+        revision: number;
+    }>;
+};
+export declare function registerPrimitiveCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/agent/commands/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/primitives.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAG5C,OAAO,KAAK,EAAa,aAAa,EAAE,IAAI,EAAC,MAAM,UAAU,CAAA;AAQ7D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAA;AAEnD,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB;QACjC,eAAe,CAAC,IAAI,EAAE;YAAC,IAAI,EAAE,aAAa,CAAC;YAAC,QAAQ,EAAE,IAAI,CAAA;SAAC,GAAG;YAC5D,GAAG,EAAE,MAAM,CAAA;YACX,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;SACzB,CAAA;KACF;CACF;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,IAAI,EAAE;QACX,IAAI,EAAE,aAAa,CAAA;QACnB,QAAQ,EAAE,IAAI,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACzD,CAAA;AAgED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CA0EN"}