@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,474 @@
+let projectSeq = 0;
+/** 晚绑定:doMock 工厂只跑一次,getStudio 读取当前 setup 的 studio */
+let 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,
+});
+/** 带 Scene sheet 的初始 project state;tracks 时附 position.x/y 轨道 */
+function projectState(definitionVersion, tracks) {
+    const keyframe = (id, position, value) => ({
+        id,
+        position,
+        connectedRight: true,
+        handles: [0.5, 0.5, 0.5, 0.5],
+        value,
+    });
+    return {
+        definitionVersion,
+        sheetsById: {
+            Scene: {
+                staticOverrides: { byObject: {} },
+                sequence: {
+                    type: 'PositionalSequence',
+                    length: 10,
+                    subUnitsPerUnit: 30,
+                    tracksByObject: tracks
+                        ? {
+                            Foo: {
+                                trackIdByPropPath: {
+                                    '["position","x"]': 'track-x',
+                                    '["position","y"]': 'track-y',
+                                },
+                                trackData: {
+                                    'track-x': {
+                                        type: 'BasicKeyframedTrack',
+                                        keyframes: {
+                                            byId: {
+                                                kf1: keyframe('kf1', 0, 5),
+                                                kf2: keyframe('kf2', 2, 10),
+                                            },
+                                            allIds: { kf1: true, kf2: true },
+                                        },
+                                    },
+                                    'track-y': {
+                                        type: 'BasicKeyframedTrack',
+                                        keyframes: {
+                                            byId: { kf3: keyframe('kf3', 1, 7) },
+                                            allIds: { kf3: true },
+                                        },
+                                    },
+                                },
+                            },
+                        }
+                        : {},
+                },
+            },
+        },
+    };
+}
+function setup(options = {}) {
+    const { getPointerParts } = require('@dreamerbird/dataverse');
+    const core = require('@dreamerbird/core');
+    const { globals } = require('@dreamerbird/core/globals');
+    const { AgentCommandRegistry } = require('../registry');
+    const { createAgentRuntime } = require('../runtime');
+    const objectRuntime = require('../runtime/objectRuntime');
+    const { registerKeyframeCommands } = require('./keyframes');
+    const { registerObjectCommands } = require('./objects');
+    const { PLACEMENTS_REGISTRY_KEY } = require('../../PlacementManager');
+    /** 事务调用记录(op 顺序 + 关键参数);transactionFlags 记录各事务的 undoable 实参 */
+    const calls = [];
+    const transactionFlags = [];
+    const sequenceEditor = {
+        setPrimitivePropAsSequenced: jest.fn((args) => {
+            calls.push({
+                op: 'sequenceProp',
+                objectKey: args.objectKey,
+                sheetId: args.sheetId,
+                pathToProp: args.pathToProp,
+            });
+        }),
+        transformKeyframes: jest.fn((args) => {
+            calls.push({ op: 'transformKeyframes', args });
+        }),
+        setPrimitivePropAsStatic: jest.fn((args) => {
+            calls.push({ op: 'unsequenceProp', args });
+        }),
+    };
+    const fakeStudio = {
+        transaction: jest.fn((fn, undoable) => {
+            transactionFlags.push(undoable);
+            return 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 project = core.getProject(`agent-kf-${++projectSeq}`, {
+        state: projectState(globals.currentProjectStateDefinitionVersion, options.tracks === true),
+    });
+    const sheet = project.sheet('Scene');
+    let notifyHistoric = () => { };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => fakeStudio,
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const registry = new AgentCommandRegistry();
+    registerKeyframeCommands(registry, runtime);
+    /** 登记后的清理(模块级登记表跨用例存活,必须逐用例清) */
+    function registerMounted(id, obj) {
+        objectRuntime.registerSceneSheetObject(id, obj);
+        cleanups.push(() => objectRuntime.unregisterSceneSheetObject(id, obj));
+    }
+    /** 布景:注册表写 'Foo' 条目并把 SheetObject 登记为 model:Foo */
+    function mountFoo() {
+        const t = core.types;
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([{ key: 'Foo', position: { x: 0, y: 0, z: 0 } }]),
+        };
+        const obj = sheet.object('Foo', {
+            position: t.compound({
+                x: t.number(0),
+                y: t.number(0),
+                z: t.number(0),
+            }),
+            label: t.string('hello'),
+            visible: t.boolean(true),
+        });
+        registerMounted('model:Foo', obj);
+        return obj;
+    }
+    return {
+        core,
+        project,
+        sheet,
+        registry,
+        runtime,
+        fakeStudio,
+        calls,
+        transactionFlags,
+        sequenceEditor,
+        mountFoo,
+        registerObjectCommands: () => registerObjectCommands(registry, runtime),
+        PLACEMENTS_REGISTRY_KEY,
+        notifyHistoric: () => notifyHistoric(),
+    };
+}
+const COMMAND_NAMES = [
+    'keyframes.list',
+    'keyframes.set',
+    'keyframes.move',
+    'keyframes.delete',
+];
+describe('keyframes 命令注册', () => {
+    test('四个命令全部注册', () => {
+        const { registry } = setup();
+        for (const name of COMMAND_NAMES) {
+            expect(registry.has(name)).toBe(true);
+        }
+    });
+    test('元数据:list 为 query/project;set/move/delete 为项目单步命令且接受 expectedRevision', () => {
+        const { registry } = setup();
+        const described = new Map(registry.describe().commands.map((c) => [c.name, c]));
+        expect(described.get('keyframes.list')).toMatchObject({
+            kind: 'query',
+            stateDomain: 'project',
+            undoable: 'none',
+            acceptsExpectedRevision: false,
+        });
+        for (const name of [
+            'keyframes.set',
+            'keyframes.move',
+            'keyframes.delete',
+        ]) {
+            expect(described.get(name)).toMatchObject({
+                kind: 'mutation',
+                stateDomain: 'project',
+                undoable: 'single-step',
+                completion: 'committed',
+                acceptsExpectedRevision: true,
+            });
+        }
+    });
+});
+describe('keyframes.set', () => {
+    test('未建轨 position.x:先以 undoable:false 事务建轨,再以可撤销事务写首帧,播放头定位到吸附后的 at', async () => {
+        const { registry, sheet, fakeStudio, calls, transactionFlags, mountFoo } = setup();
+        mountFoo();
+        const result = await registry.execute('keyframes.set', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            at: 0.51,
+            value: 7,
+            snap: true,
+        }, ctx());
+        // 两笔事务:建轨(不入撤销栈)→ 写首帧(可撤销);顺序先 sequenceProp 再 set
+        expect(fakeStudio.transaction).toHaveBeenCalledTimes(2);
+        expect(transactionFlags).toEqual([false, undefined]);
+        expect(calls).toEqual([
+            {
+                op: 'sequenceProp',
+                objectKey: 'Foo',
+                sheetId: 'Scene',
+                pathToProp: ['position', 'x'],
+            },
+            { op: 'set', path: 'position.x', value: 7 },
+        ]);
+        // 30 subUnitsPerUnit:0.51 吸附到 0.5
+        expect(sheet.sequence.position).toBe(0.5);
+        expect(result).toEqual({ revision: 1 });
+    });
+    test('已建轨属性不再调用 sequenceProp,直接 set', async () => {
+        const { registry, sheet, fakeStudio, calls, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        await registry.execute('keyframes.set', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            at: 4.01,
+            value: 9,
+            snap: true,
+        }, ctx());
+        expect(fakeStudio.transaction).toHaveBeenCalledTimes(1);
+        expect(calls).toEqual([{ op: 'set', path: 'position.x', value: 9 }]);
+        expect(sheet.sequence.position).toBe(4);
+    });
+    test('snap 默认 false:播放头按原始 at 定位,不吸附', async () => {
+        const { registry, sheet, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        await registry.execute('keyframes.set', { objectId: 'model:Foo', propPath: ['position', 'x'], at: 1.234, value: 9 }, ctx());
+        expect(sheet.sequence.position).toBe(1.234);
+    });
+    test('值形状校验:数字叶子拒绝字符串与 NaN,事务不执行', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        for (const bad of ['7', NaN, Infinity, true]) {
+            await expect(registry.execute('keyframes.set', {
+                objectId: 'model:Foo',
+                propPath: ['position', 'x'],
+                at: 1,
+                value: bad,
+            }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        }
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('propPath 必须指向简单叶子:compound 与未知路径拒绝', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        for (const propPath of [['position'], ['position', 'w'], ['nope']]) {
+            await expect(registry.execute('keyframes.set', { objectId: 'model:Foo', propPath, at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        }
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('propPath 形状:非数组/空数组/空段拒绝', async () => {
+        const { registry, mountFoo } = setup();
+        mountFoo();
+        for (const bad of ['position.x', [], [''], [1]]) {
+            await expect(registry.execute('keyframes.set', { objectId: 'model:Foo', propPath: bad, at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        }
+    });
+    test('对象不存在/类型不符/未挂载分别返回 OBJECT_NOT_FOUND/INVALID_ID_KIND/INVALID_STATE', async () => {
+        const { core, sheet, registry, mountFoo, PLACEMENTS_REGISTRY_KEY } = setup();
+        mountFoo();
+        await expect(registry.execute('keyframes.set', { objectId: 'model:Nope', propPath: ['position', 'x'], at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'OBJECT_NOT_FOUND' });
+        await expect(registry.execute('keyframes.set', { objectId: 'thing:Foo', propPath: ['position', 'x'], at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'INVALID_ID_KIND' });
+        // 注册表有条目但运行时未挂载
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: core.types.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([
+                { key: 'Foo', position: { x: 0, y: 0, z: 0 } },
+                { key: 'Ghost', position: { x: 0, y: 0, z: 0 } },
+            ]),
+        };
+        await expect(registry.execute('keyframes.set', { objectId: 'model:Ghost', propPath: ['position', 'x'], at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'INVALID_STATE' });
+    });
+    test('expectedRevision 冲突返回 REVISION_CONFLICT 且不进入事务', async () => {
+        const { registry, fakeStudio, mountFoo, notifyHistoric } = setup();
+        mountFoo();
+        notifyHistoric();
+        await expect(registry.execute('keyframes.set', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            at: 1,
+            value: 7,
+            expectedRevision: 1,
+        }, ctx())).rejects.toMatchObject({
+            code: 'REVISION_CONFLICT',
+            details: { expectedRevision: 1, actualRevision: 2 },
+        });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('Studio 不可用返回 SCENE_UNAVAILABLE', async () => {
+        const { registry, mountFoo } = setup();
+        mountFoo();
+        activeFakeStudio = undefined;
+        await expect(registry.execute('keyframes.set', { objectId: 'model:Foo', propPath: ['position', 'x'], at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+    });
+});
+describe('keyframes.list', () => {
+    test('只返回指定简单叶子的 {position,value},按位置升序,不含其他属性', async () => {
+        const { registry, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        const xs = await registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['position', 'x'] }, ctx());
+        expect(xs).toEqual([
+            { position: 0, value: 5 },
+            { position: 2, value: 10 },
+        ]);
+        const ys = await registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['position', 'y'] }, ctx());
+        expect(ys).toEqual([{ position: 1, value: 7 }]);
+    });
+    test('未建轨叶子返回空数组', async () => {
+        const { registry, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        const result = await registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['visible'] }, ctx());
+        expect(result).toEqual([]);
+    });
+    test('compound 路径拒绝 INVALID_ARGUMENT', async () => {
+        const { registry, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        await expect(registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['position'] }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    });
+});
+describe('keyframes.move', () => {
+    test('from/to 按网格规则计算后经 transformKeyframes 适配移动源关键帧', async () => {
+        const { registry, sheet, fakeStudio, calls, mountFoo } = setup({
+            tracks: true,
+        });
+        mountFoo();
+        const result = await registry.execute('keyframes.move', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            from: 2.01,
+            to: 4.01,
+            snap: true,
+        }, ctx());
+        expect(fakeStudio.transaction).toHaveBeenCalledTimes(1);
+        expect(calls).toHaveLength(1);
+        const call = calls[0];
+        expect(call.op).toBe('transformKeyframes');
+        expect(call.args).toMatchObject({
+            objectKey: 'Foo',
+            sheetId: 'Scene',
+            trackId: 'track-x',
+            keyframeIds: ['kf2'],
+            translate: 2,
+            scale: 1,
+            origin: 0,
+        });
+        // 与 AggregateKeyframeConnector 相同的吸附函数
+        expect(call.args.snappingFunction).toBe(sheet.sequence.closestGridPosition);
+        expect(result).toEqual({ revision: 1 });
+    });
+    test('源位置无关键帧返回 KEYFRAME_NOT_FOUND,不进入事务', async () => {
+        const { registry, fakeStudio, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        await expect(registry.execute('keyframes.move', { objectId: 'model:Foo', propPath: ['position', 'x'], from: 5, to: 6 }, ctx())).rejects.toMatchObject({ code: 'KEYFRAME_NOT_FOUND' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('未建轨叶子返回 KEYFRAME_NOT_FOUND', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        await expect(registry.execute('keyframes.move', { objectId: 'model:Foo', propPath: ['position', 'x'], from: 0, to: 1 }, ctx())).rejects.toMatchObject({ code: 'KEYFRAME_NOT_FOUND' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('expectedRevision 冲突返回 REVISION_CONFLICT', async () => {
+        const { registry, fakeStudio, mountFoo, notifyHistoric } = setup({
+            tracks: true,
+        });
+        mountFoo();
+        notifyHistoric();
+        await expect(registry.execute('keyframes.move', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            from: 2,
+            to: 4,
+            expectedRevision: 1,
+        }, ctx())).rejects.toMatchObject({ code: 'REVISION_CONFLICT' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+});
+describe('keyframes.delete', () => {
+    test('在指定位置 unset(pointer),不擅自 unsequenceProp', async () => {
+        const { registry, sheet, fakeStudio, calls, sequenceEditor, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        const result = await registry.execute('keyframes.delete', { objectId: 'model:Foo', propPath: ['position', 'x'], at: 2 }, ctx());
+        expect(fakeStudio.transaction).toHaveBeenCalledTimes(1);
+        expect(calls).toEqual([{ op: 'unset', path: 'position.x' }]);
+        expect(sequenceEditor.setPrimitivePropAsStatic).not.toHaveBeenCalled();
+        expect(sheet.sequence.position).toBe(2);
+        expect(result).toEqual({ revision: 1 });
+    });
+    test('snap:true 时播放头定位到吸附后的 at', async () => {
+        const { registry, sheet, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        await registry.execute('keyframes.delete', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            at: 2.01,
+            snap: true,
+        }, ctx());
+        expect(sheet.sequence.position).toBe(2);
+    });
+    test('指定位置无关键帧返回 KEYFRAME_NOT_FOUND,不进入事务', async () => {
+        const { registry, fakeStudio, mountFoo } = setup({ tracks: true });
+        mountFoo();
+        await expect(registry.execute('keyframes.delete', { objectId: 'model:Foo', propPath: ['position', 'x'], at: 5 }, ctx())).rejects.toMatchObject({ code: 'KEYFRAME_NOT_FOUND' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('expectedRevision 冲突返回 REVISION_CONFLICT', async () => {
+        const { registry, fakeStudio, mountFoo, notifyHistoric } = setup({
+            tracks: true,
+        });
+        mountFoo();
+        notifyHistoric();
+        await expect(registry.execute('keyframes.delete', {
+            objectId: 'model:Foo',
+            propPath: ['position', 'x'],
+            at: 2,
+            expectedRevision: 1,
+        }, ctx())).rejects.toMatchObject({ code: 'REVISION_CONFLICT' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+});
+describe('与 objects.update 的边界', () => {
+    test('已建轨叶子所在属性:objects.update 仍返回 INVALID_STATE', async () => {
+        const { registry, fakeStudio, mountFoo, registerObjectCommands } = setup({
+            tracks: true,
+        });
+        registerObjectCommands();
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 1, y: 2, z: 3 } } }, ctx())).rejects.toMatchObject({ code: 'INVALID_STATE' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+});
+describe('会话生命周期', () => {
+    test('dispose 后命令拒绝 API_DISPOSED', async () => {
+        const { registry, runtime, mountFoo } = setup();
+        mountFoo();
+        runtime.dispose();
+        await expect(registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['position', 'x'] }, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+        await expect(registry.execute('keyframes.set', { objectId: 'model:Foo', propPath: ['position', 'x'], at: 1, value: 7 }, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    });
+});
+export {};

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

@@ -0,0 +1,34 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId, Vec3 } from '../types';
+import type { ModelEntry } from '../../assetLibrary/types';
+declare module '../runtime' {
+    interface AgentSceneRuntimeHandlers {
+        /**
+         * 把库模型条目放置到指定位置(CameraScene 绑定,转发
+         * placeLibraryEntryAt):同步生成 key、创建挂载 waiter、设置 pending
+         * 条目,立即返回;persisted 在注册表提交 + pending 清理后兑现,
+         * 挂载/加载失败或提前卸载时拒绝。
+         */
+        createModel(args: {
+            entry: ModelEntry;
+            position: Vec3;
+        }): {
+            key: string;
+            persisted: Promise<void>;
+        };
+    }
+}
+/** 模型门面(Task 15 由同名命令转发实现) */
+export type ModelsApi = {
+    create(args: {
+        assetId: string;
+        position: Vec3;
+        expectedRevision?: number;
+    }): Promise<{
+        objectId: SceneObjectId;
+        revision: number;
+    }>;
+};
+export declare function registerModelCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=models.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/commands/models.js

@@ -0,0 +1,137 @@
+/**
+ * models.create(2026-10-17,Task 8):从模型资产直接创建到指定位置。
+ *
+ * 执行顺序:assertActive → project.ready → Library 取条目
+ * (缺失 ASSET_NOT_FOUND / 非模型 INVALID_ARGUMENT) → expectedRevision
+ * 乐观并发(任何副作用之前) → Scene Runtime createModel handler
+ * (未绑定 SCENE_UNAVAILABLE;生产由 CameraScene 绑定,转发
+ * placeLibraryEntryAt) → 等 persisted(completion:mounted;失败
+ * RESOURCE_LOAD_FAILED,期间 dispose 优先映射 API_DISPOSED) →
+ * resolver 复核注册表与 SheetObject 双双可见(脱节 = INTERNAL_ERROR,
+ * 不静默成功)。
+ *
+ * 撤销粒度:PlacedModelCore 的注册表提交是单个 scrub commit,整个命令
+ * 对历史只呈现一步(undoable:single-step)。
+ */
+import { AgentApiError } from '../errors';
+import { formatSceneObjectId } from '../objectIds';
+import { getSceneObjectSummary } from '../objectResolver';
+import { requireFiniteNumber, requireObject, requireString, requireVec3, } from '../validation';
+const vec3Schema = {
+    type: 'object',
+    properties: {
+        x: { type: 'number' },
+        y: { type: 'number' },
+        z: { type: 'number' },
+    },
+    required: ['x', 'y', 'z'],
+    additionalProperties: false,
+};
+const createInput = {
+    type: 'object',
+    properties: {
+        assetId: { type: 'string', description: '模型资产条目 id' },
+        position: { ...vec3Schema, description: '创建位置(世界坐标)' },
+        expectedRevision: {
+            type: 'number',
+            description: '乐观并发:读取场景时的 revision',
+        },
+    },
+    required: ['assetId', 'position'],
+    additionalProperties: false,
+};
+const createOutput = {
+    type: 'object',
+    properties: {
+        objectId: { type: 'string', description: '带类型场景对象 ID,model:<key>' },
+        revision: { type: 'number' },
+    },
+    required: ['objectId', 'revision'],
+};
+function validateCreate(value) {
+    const args = requireObject(value);
+    const assetId = requireString(args, 'assetId');
+    const position = requireVec3(args.position);
+    let expectedRevision;
+    if (args.expectedRevision !== undefined) {
+        expectedRevision = requireFiniteNumber(args.expectedRevision, 'expectedRevision');
+    }
+    return { assetId, position, expectedRevision };
+}
+export function registerModelCommands(registry, runtime) {
+    registry.register({
+        name: 'models.create',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'mounted',
+        inputSchema: createInput,
+        outputSchema: createOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'ASSET_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+            'RESOURCE_LOAD_FAILED',
+            'INTERNAL_ERROR',
+        ],
+        validate: validateCreate,
+        execute: async (args) => {
+            runtime.assertActive();
+            // 资产读取与就绪等待都在副作用之前(事务外异步准备,spec 8.6.1)
+            await runtime.project.ready;
+            const entry = await runtime.library.getEntry(args.assetId);
+            if (!entry) {
+                throw new AgentApiError('ASSET_NOT_FOUND', `资产不存在: ${args.assetId}`, {
+                    details: { assetId: args.assetId },
+                });
+            }
+            if (entry.kind !== 'model') {
+                throw new AgentApiError('INVALID_ARGUMENT', `资产 ${args.assetId} 不是模型(kind: ${entry.kind})`, { details: { assetId: args.assetId, kind: entry.kind } });
+            }
+            // 乐观并发:先于任何副作用(setPendingEntry 经 handler 触发)
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            const createModel = runtime.handlers.createModel;
+            if (!createModel) {
+                throw new AgentApiError('SCENE_UNAVAILABLE', 'Scene Runtime 未绑定 createModel,无法创建模型');
+            }
+            const placed = createModel({ entry, position: args.position });
+            try {
+                await placed.persisted;
+            }
+            catch (error) {
+                // dispose 优先于挂载失败:会话已销毁时统一 API_DISPOSED
+                runtime.assertActive();
+                throw new AgentApiError('RESOURCE_LOAD_FAILED', `模型挂载失败: ${entry.name}`, {
+                    details: {
+                        assetId: args.assetId,
+                        cause: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            runtime.assertActive();
+            const objectId = formatSceneObjectId('model', placed.key);
+            // persisted 兑现后注册表与 SheetObject 必须双双可见;
+            // 任何脱节都是内部不变量被破坏,不是调用方的「对象不存在」
+            let mounted;
+            try {
+                mounted = getSceneObjectSummary(runtime.sheet, objectId).mounted;
+            }
+            catch (error) {
+                throw new AgentApiError('INTERNAL_ERROR', `放置已提交但场景对象不可见: ${objectId}`, {
+                    details: {
+                        objectId,
+                        cause: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            if (!mounted) {
+                throw new AgentApiError('INTERNAL_ERROR', `放置已提交但 SheetObject 未登记: ${objectId}`, { details: { objectId } });
+            }
+            return { objectId, revision: await runtime.nextRevision() };
+        },
+    });
+}

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

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

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

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