@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,518 @@
+var _a;
+/* eslint-disable import/no-extraneous-dependencies */
+/**
+ * objects.delete(2026-10-19,Task 14):统一对象删除与完整清理。
+ *
+ * 真实 Studio 行为测试(同 paths.test.ts 的引导方式,node 环境:jsdom
+ * 会把 studio 依赖链上的 jose 解析成 ESM browser 构建,jest 转不了):
+ * 领域删除经真事务落库,注册表清单 / 持久覆盖 / 撤销栈直接断言。
+ * revision 用捕获的 subscribeHistoric listener 手工推进;会话清理
+ * handler(afterSceneObjectDeleted)用假实现经 bindHandlers 登记,
+ * 形状与接线后的 CameraScene 一致。
+ *
+ * 关键断言:
+ * - 四类对象删除都只有一步撤销(forgetObject/注册表/绑定回退合并到
+ *   同一事务),一次 studio.undo() 完整恢复项目对象和注册表;
+ * - 相机/路径/锚点的持久数据按地址 forget(未挂载对象同样真删,
+ *   不静默 return);
+ * - 锚点删除把子级锚点的 parent 解绑 + 世界定格折进同一事务;
+ * - 路径删除重置绑定相机 pathKey 并定格当前世界机位;
+ * - 会话清理在领域事务提交之后才执行,领域校验失败时不调用;
+ * - 删除选中对象后 selection 不再含已失效 ID(Task 4 遗留窗口关闭);
+ * - undo 不恢复会话状态(选择保持清空)。
+ */
+// getPathMeta 的调试挂钩写 window.__cameraPathMeta;node 环境补一个
+// 全局壳(模块顶层只定义不触碰,测试期调用才写)
+;
+(_a = globalThis).window ?? (_a.window = globalThis);
+import '@dreamerbird/studio';
+import theatre, { getProject, types as t, val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { globals } from '@dreamerbird/core/globals';
+import getStudio from '@dreamerbird/studio/getStudio';
+import { getCoreTicker } from '@dreamerbird/core/coreTicker';
+import { Group } from 'three';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import * as objectRuntime from '../runtime/objectRuntime';
+import * as pathRuntime from '../runtime/pathRuntime';
+import { registerObjectCommands } from './objects';
+import { getPathMeta, pathExists } from '../../CameraPath';
+import { getPathsRegistry, PATHS_REGISTRY_KEY, readPathEntries, } from '../../pathRegistry';
+import { CAMERAS_REGISTRY_KEY, readCameraEntries, getCamerasRegistry, } from '../../cameraRegistry';
+import { ANCHORS_REGISTRY_KEY, getAnchorsRegistry, readAnchorKeys, } from '../../anchorsRegistry';
+import { PLACEMENTS_REGISTRY_KEY, readPlacementEntries, } from '../../PlacementManager';
+import { registerAnchorObject } from '../../aimTargets';
+const studio = getStudio();
+// 公开门面(TheatreStudio):selection/setSelection 只在 publicApi 上,
+// 内部 Studio 没有——生产经 getStudioSync 拿的就是它
+const studioApi = studio.publicApi;
+void theatre.init({ studio: true, usePersistentStorage: false });
+let projectSeq = 0;
+const PATH_KEY = 'Pos Path';
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+/** 探 saaz 撤销栈(私有路径,同 paths.test.ts 的取证方式) */
+const undoStackOf = () => {
+    const s = studio;
+    const saaz = (s._store?._saaz ?? s._saaz);
+    return saaz?._atom?.get?.()?.undoRedo?.stack ?? [];
+};
+async function setup() {
+    const state = {
+        definitionVersion: globals.currentProjectStateDefinitionVersion,
+        sheetsById: {
+            Scene: {
+                staticOverrides: { byObject: {} },
+                sequence: {
+                    type: 'PositionalSequence',
+                    length: 10,
+                    subUnitsPerUnit: 30,
+                    tracksByObject: {},
+                },
+            },
+        },
+    };
+    const project = getProject(`agent-delete-${++projectSeq}`, {
+        state: state,
+    });
+    getCoreTicker().tick();
+    await project.ready;
+    const sheet = project.sheet('Scene');
+    let notifyHistoric = () => { };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => studioApi,
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const registry = new AgentCommandRegistry();
+    registerObjectCommands(registry, runtime);
+    /** 持久覆盖直读(断言 forgetObject 清干净/撤销恢复,不创建对象) */
+    const persistedOverrides = () => val(privateAPI(project).pointers.historic).sheetsById.Scene.staticOverrides.byObject;
+    const registerMounted = (id, obj) => {
+        objectRuntime.registerSceneSheetObject(id, obj);
+        cleanups.push(() => objectRuntime.unregisterSceneSheetObject(id, obj));
+    };
+    /** 布景:相机注册表清单 + 每台相机一个 SheetObject 并登记 objectRuntime */
+    const seedCameras = (entries) => {
+        const objs = new Map();
+        for (const { cameraKey, pathKey } of entries) {
+            const obj = sheet.object(cameraKey, {
+                position: t.compound({
+                    x: t.number(9),
+                    y: t.number(9),
+                    z: t.number(9),
+                }),
+                pathKey: t.string(''),
+            });
+            obj.initialValue = { pathKey: pathKey ?? '', position: { x: 9, y: 9, z: 9 } };
+            registerMounted(`camera:${cameraKey}`, obj);
+            objs.set(cameraKey, obj);
+        }
+        const registryObj = sheet.object(CAMERAS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify(entries.map(({ cameraKey }) => ({ cameraKey }))),
+        };
+        return objs;
+    };
+    /** 布景:锚点注册表清单 + SheetObject 登记;node 在场时登记运行时节点 */
+    const seedAnchors = (entries) => {
+        const objs = new Map();
+        const nodes = new Map();
+        for (const { key, parent, position, node } of entries) {
+            const obj = sheet.object(key, {
+                position: t.compound({
+                    x: t.number(0),
+                    y: t.number(0),
+                    z: t.number(0),
+                }),
+                parent: t.string(''),
+            });
+            obj.initialValue = {
+                parent: parent ?? '',
+                position: position ?? { x: 0, y: 0, z: 0 },
+            };
+            registerMounted(`anchor:${key}`, obj);
+            objs.set(key, obj);
+            if (node) {
+                const group = new Group();
+                group.position.set(node.position.x, node.position.y, node.position.z);
+                nodes.set(key, group);
+            }
+        }
+        // 命令式父子:子节点挂在父节点下(对齐 AnchorObject 的 newParentObj.add)
+        for (const { key, node } of entries) {
+            if (!node)
+                continue;
+            const group = nodes.get(key);
+            if (node.parentKey && nodes.has(node.parentKey)) {
+                nodes.get(node.parentKey).add(group);
+            }
+            registerAnchorObject(key, group);
+            cleanups.push(() => registerAnchorObject(key, null));
+        }
+        const registryObj = sheet.object(ANCHORS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify(entries.map(({ key }) => key)),
+        };
+        return { objs, nodes };
+    };
+    /** 布景:路径注册表清单 + meta 播点(initialValue,不产生历史) */
+    const seedPaths = (entries) => {
+        for (const { key, points } of entries) {
+            if (points.length === 0)
+                continue;
+            const meta = getPathMeta(sheet, key);
+            meta.initialValue = {
+                points: JSON.stringify(points.map((p, i) => ({ key: `P${i + 1}`, position: p }))),
+            };
+        }
+        const registryObj = sheet.object(PATHS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify(entries.map(({ key }) => ({ pathKey: key }))),
+        };
+    };
+    /** 布景:放置清单 + 每个模型一个 SheetObject 并登记 objectRuntime */
+    const seedModels = (entries) => {
+        const objs = new Map();
+        for (const { key, position } of entries) {
+            const obj = sheet.object(key, {
+                position: t.compound({
+                    x: t.number(0),
+                    y: t.number(0),
+                    z: t.number(0),
+                }),
+                label: t.string(''),
+            });
+            obj.initialValue = { position: position ?? { x: 0, y: 0, z: 0 } };
+            registerMounted(`model:${key}`, obj);
+            objs.set(key, obj);
+        }
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify(entries.map(({ key, position }) => ({
+                key,
+                position: position ?? { x: 0, y: 0, z: 0 },
+            }))),
+        };
+        return objs;
+    };
+    const registeredCameras = () => readCameraEntries(getCamerasRegistry(sheet)).map((e) => e.cameraKey);
+    const registeredAnchors = () => readAnchorKeys(getAnchorsRegistry(sheet));
+    const registeredPaths = () => readPathEntries(getPathsRegistry(sheet)).map((e) => e.pathKey);
+    const registeredModels = () => readPlacementEntries(sheet).map((e) => e.key);
+    return {
+        project,
+        sheet,
+        runtime,
+        registry,
+        notifyHistoric: () => notifyHistoric(),
+        persistedOverrides,
+        seedCameras,
+        seedAnchors,
+        seedPaths,
+        seedModels,
+        registeredCameras,
+        registeredAnchors,
+        registeredPaths,
+        registeredModels,
+    };
+}
+/** 登记假的会话清理 handler,返回调用记录 */
+function bindSessionCleanup(runtime) {
+    const calls = [];
+    const unbind = runtime.bindHandlers({
+        afterSceneObjectDeleted: (args) => {
+            calls.push(args);
+        },
+    });
+    cleanups.push(unbind);
+    return calls;
+}
+describe('objects.delete 注册与元数据', () => {
+    test('objects.delete 已注册:mutation/project/single-step/committed,接受 expectedRevision', async () => {
+        const { registry } = await setup();
+        const command = registry
+            .describe()
+            .commands.find((c) => c.name === 'objects.delete');
+        expect(command).toBeDefined();
+        expect(command).toMatchObject({
+            kind: 'mutation',
+            stateDomain: 'project',
+            undoable: 'single-step',
+            completion: 'committed',
+            acceptsExpectedRevision: true,
+        });
+    });
+    test('会话销毁后调用 → API_DISPOSED', async () => {
+        const { registry, runtime } = await setup();
+        runtime.dispose();
+        await expect(registry.execute('objects.delete', { objectId: 'model:Foo' }, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    });
+});
+describe('objects.delete 模型', () => {
+    test('清单行与持久覆盖一并清理;一步撤销完整还原(覆盖一起回来)', async () => {
+        const { registry, registeredModels, persistedOverrides, seedModels } = await setup();
+        const objs = seedModels([{ key: 'Y Bot', position: { x: 1, y: 0, z: 2 } }]);
+        const obj = objs.get('Y Bot');
+        // 持久覆盖:真实事务写 label(initialValue 是 ahistoric 基线,不算持久数据)
+        studio.transaction(({ set }) => set(obj.props.label, 'hero'));
+        expect(persistedOverrides()['Y Bot']).toMatchObject({ label: 'hero' });
+        const stackBefore = undoStackOf().length;
+        await expect(registry.execute('objects.delete', { objectId: 'model:Y Bot' }, ctx())).resolves.toEqual({ deleted: 'model:Y Bot', revision: 1 });
+        expect(registeredModels()).toEqual([]);
+        // 持久覆盖被 forget:对象求值回默认
+        expect(persistedOverrides()['Y Bot']).toBeUndefined();
+        expect(obj.value.label).toBe('');
+        // 一个删除命令 = 一个撤销步骤
+        expect(undoStackOf().length).toBe(stackBefore + 1);
+        studio.undo();
+        expect(registeredModels()).toEqual(['Y Bot']);
+        expect(obj.value.label).toBe('hero');
+    });
+    test('删除选中的模型后,选择里不再含已失效对象(其余选择保留)', async () => {
+        const { registry, seedModels } = await setup();
+        const objs = seedModels([{ key: 'A' }, { key: 'B' }]);
+        studioApi.setSelection([objs.get('A'), objs.get('B')]);
+        await registry.execute('objects.delete', { objectId: 'model:A' }, ctx());
+        expect(studioApi.selection).toEqual([objs.get('B')]);
+    });
+});
+describe('objects.delete 相机', () => {
+    test('forgetObject 与注册表移除在同一个撤销步骤;undo 一次完整还原', async () => {
+        const { registry, registeredCameras, persistedOverrides, seedCameras } = await setup();
+        const objs = seedCameras([{ cameraKey: 'Shot Camera' }]);
+        const obj = objs.get('Shot Camera');
+        studio.transaction(({ set }) => set(obj.props.position, { x: 1, y: 2, z: 3 }));
+        expect(persistedOverrides()['Shot Camera']).toMatchObject({
+            position: { x: 1, y: 2, z: 3 },
+        });
+        const stackBefore = undoStackOf().length;
+        await expect(registry.execute('objects.delete', { objectId: 'camera:Shot Camera' }, ctx())).resolves.toEqual({ deleted: 'camera:Shot Camera', revision: 1 });
+        expect(registeredCameras()).toEqual([]);
+        expect(persistedOverrides()['Shot Camera']).toBeUndefined();
+        // 持久数据被清,求值回默认(initialValue 基线)
+        expect(obj.value.position).toEqual({ x: 9, y: 9, z: 9 });
+        expect(undoStackOf().length).toBe(stackBefore + 1);
+        studio.undo();
+        expect(registeredCameras()).toEqual(['Shot Camera']);
+        expect(obj.value.position).toEqual({ x: 1, y: 2, z: 3 });
+    });
+    test('未挂载相机(有持久数据但无运行时登记)同样真删,不静默返回', async () => {
+        const { sheet, registry, registeredCameras, persistedOverrides } = await setup();
+        // 对象创建过、写过持久数据,但从未登记 objectRuntime(未挂载);
+        // 随后脱离对象表,模拟"只有持久态残留"的注册表条目
+        const obj = sheet.object('Ghost Cam', {
+            position: t.compound({ x: t.number(0), y: t.number(0), z: t.number(0) }),
+        });
+        studio.transaction(({ set }) => set(obj.props.position, { x: 4, y: 5, z: 6 }));
+        sheet.detachObject('Ghost Cam');
+        const registryObj = sheet.object(CAMERAS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([{ cameraKey: 'Ghost Cam' }]),
+        };
+        expect(persistedOverrides()['Ghost Cam']).toBeDefined();
+        await expect(registry.execute('objects.delete', { objectId: 'camera:Ghost Cam' }, ctx())).resolves.toMatchObject({ deleted: 'camera:Ghost Cam' });
+        expect(registeredCameras()).toEqual([]);
+        expect(persistedOverrides()['Ghost Cam']).toBeUndefined();
+    });
+    test('活动相机回退规则(resolveActiveCamera):被删顺位清单第一台,空清单为 null', () => {
+        // 运行时 require:纯函数抽取属于本任务实现,静态 import 会让 RED
+        // 阶段整文件挂在模块加载上
+        const { resolveActiveCamera } = require('../../cameraRegistry');
+        const list = [{ cameraKey: 'A' }, { cameraKey: 'B' }];
+        // 活动相机还在清单里:保持不变
+        expect(resolveActiveCamera(list, 'A')).toEqual({ cameraKey: 'A' });
+        // 活动相机 B 已被删(不在清单):顺位第一台
+        expect(resolveActiveCamera([{ cameraKey: 'A' }], 'B')).toEqual({
+            cameraKey: 'A',
+        });
+        expect(resolveActiveCamera(list, null)).toEqual({ cameraKey: 'A' });
+        expect(resolveActiveCamera([], 'A')).toBeNull();
+    });
+});
+describe('objects.delete 锚点', () => {
+    test('删除父级锚点:子锚点 parent 解绑 + 世界定格折进同一事务,undo 一次还原绑定', async () => {
+        const { registry, registeredAnchors, seedAnchors } = await setup();
+        // A 在 (10,0,0);B 持久绑定 anchor:A,position 是相对 A 的局部偏移
+        // (1,0,0);运行时节点 B 命令式挂在 A 节点下 → 世界坐标 (11,0,0)
+        const { objs } = seedAnchors([
+            {
+                key: 'A',
+                position: { x: 10, y: 0, z: 0 },
+                node: { position: { x: 10, y: 0, z: 0 } },
+            },
+            {
+                key: 'B',
+                parent: 'anchor:A',
+                position: { x: 1, y: 0, z: 0 },
+                node: { position: { x: 1, y: 0, z: 0 }, parentKey: 'A' },
+            },
+        ]);
+        const stackBefore = undoStackOf().length;
+        await expect(registry.execute('objects.delete', { objectId: 'anchor:A' }, ctx())).resolves.toMatchObject({ deleted: 'anchor:A' });
+        expect(registeredAnchors()).toEqual(['B']);
+        // 父级运行时关系清除:parent 解绑 + 世界坐标定格(画面不跳)
+        const child = objs.get('B');
+        expect(val(child.props.parent)).toBe('');
+        expect(val(child.props.position)).toEqual({ x: 11, y: 0, z: 0 });
+        expect(undoStackOf().length).toBe(stackBefore + 1);
+        studio.undo();
+        expect(registeredAnchors()).toEqual(['A', 'B']);
+        expect(val(child.props.parent)).toBe('anchor:A');
+        expect(val(child.props.position)).toEqual({ x: 1, y: 0, z: 0 });
+    });
+    test('子锚点无运行时节点(未挂载)时跳过解绑,删除本身照常完成', async () => {
+        const { registry, registeredAnchors, seedAnchors } = await setup();
+        const { objs } = seedAnchors([
+            { key: 'A' },
+            { key: 'B', parent: 'anchor:A', position: { x: 1, y: 0, z: 0 } },
+        ]);
+        await registry.execute('objects.delete', { objectId: 'anchor:A' }, ctx());
+        expect(registeredAnchors()).toEqual(['B']);
+        // 没有节点就没有世界定格可写:绑定留给挂载后的重试/看护处理
+        expect(val(objs.get('B').props.parent)).toBe('anchor:A');
+    });
+    test('锚点持久覆盖按地址清理;一步撤销', async () => {
+        const { registry, persistedOverrides, seedAnchors } = await setup();
+        const { objs } = seedAnchors([{ key: 'A' }]);
+        studio.transaction(({ set }) => set(objs.get('A').props.position, { x: 3, y: 3, z: 3 }));
+        expect(persistedOverrides()['A']).toBeDefined();
+        const stackBefore = undoStackOf().length;
+        await registry.execute('objects.delete', { objectId: 'anchor:A' }, ctx());
+        expect(persistedOverrides()['A']).toBeUndefined();
+        expect(undoStackOf().length).toBe(stackBefore + 1);
+        studio.undo();
+        expect(val(objs.get('A').props.position)).toEqual({ x: 3, y: 3, z: 3 });
+    });
+});
+describe('objects.delete 路径', () => {
+    test('注册表清理 + 对象脱离 + 绑定相机 pathKey 重置与世界定格,一步撤销', async () => {
+        const { sheet, registry, registeredPaths, seedPaths, seedCameras, persistedOverrides, } = await setup();
+        seedPaths([
+            {
+                key: PATH_KEY,
+                points: [
+                    { x: 0, y: 0, z: 0 },
+                    { x: 10, y: 0, z: 0 },
+                ],
+            },
+        ]);
+        const cameras = seedCameras([{ cameraKey: 'Shot Camera', pathKey: PATH_KEY }]);
+        const camera = cameras.get('Shot Camera');
+        // 挂载采样器(生产由 CameraPath 登记):采样到 (1,2,3) 作为定格机位
+        cleanups.push(pathRuntime.registerPathSampler(PATH_KEY, (_u, out) => {
+            out.set(1, 2, 3);
+            return true;
+        }));
+        // 把播下的点落成持久覆盖:initialValue 是 ahistoric 基线,
+        // forgetObject/undo 只管 historic 层,不先落覆盖 undo 无从恢复
+        const meta = getPathMeta(sheet, PATH_KEY);
+        studio.transaction(({ set }) => set(meta.props.points, meta.value.points));
+        const stackBefore = undoStackOf().length;
+        await expect(registry.execute('objects.delete', { objectId: `path:${PATH_KEY}` }, ctx())).resolves.toEqual({ deleted: `path:${PATH_KEY}`, revision: 1 });
+        expect(registeredPaths()).toEqual([]);
+        expect(pathExists(sheet, PATH_KEY)).toBe(false);
+        // 绑定相机回退:pathKey 清空 + 机位定格在删除前的采样位置
+        expect(val(camera.props.pathKey)).toBe('');
+        expect(val(camera.props.position)).toEqual({ x: 1, y: 2, z: 3 });
+        expect(undoStackOf().length).toBe(stackBefore + 1);
+        // 一次 undo:注册表行/绑定/机位一起还原
+        studio.undo();
+        expect(registeredPaths()).toEqual([PATH_KEY]);
+        expect(val(camera.props.pathKey)).toBe(PATH_KEY);
+        expect(val(camera.props.position)).toEqual({ x: 9, y: 9, z: 9 });
+        // 路径持久数据恢复(对象表重挂是生产端 React 重挂载的职责,
+        // 测试环境直读 historic 底账验证)
+        expect(persistedOverrides()[PATH_KEY]).toBeDefined();
+    });
+    test('已登记但未挂载的路径(无 meta 对象)也真删,不创建对象不静默返回', async () => {
+        const { sheet, registry, registeredPaths, seedPaths } = await setup();
+        // 只写注册表行,不落实 meta 对象
+        seedPaths([{ key: PATH_KEY, points: [] }]);
+        expect(pathExists(sheet, PATH_KEY)).toBe(false);
+        await expect(registry.execute('objects.delete', { objectId: `path:${PATH_KEY}` }, ctx())).resolves.toMatchObject({ deleted: `path:${PATH_KEY}` });
+        expect(registeredPaths()).toEqual([]);
+        expect(pathExists(sheet, PATH_KEY)).toBe(false);
+    });
+    test('删除正在编辑的路径:会话清理 handler 在项目事务提交后调用', async () => {
+        const { registry, runtime, registeredPaths, seedPaths } = await setup();
+        seedPaths([{ key: PATH_KEY, points: [{ x: 0, y: 0, z: 0 }] }]);
+        // 假 handler 复刻 CameraScene 语义:清编辑态与点选择;并记录调用时
+        // 注册表已清理(领域事务先于会话清理)
+        const session = {
+            editingPath: PATH_KEY,
+            selectedPathPoint: { metaKey: PATH_KEY, key: 'P1' },
+        };
+        const registryStateAtCall = [];
+        cleanups.push(runtime.bindHandlers({
+            afterSceneObjectDeleted: ({ kind, key }) => {
+                registryStateAtCall.push(registeredPaths());
+                if (kind !== 'path')
+                    return;
+                if (session.editingPath === key)
+                    session.editingPath = null;
+                if (session.selectedPathPoint?.metaKey === key) {
+                    session.selectedPathPoint = null;
+                }
+            },
+        }));
+        await registry.execute('objects.delete', { objectId: `path:${PATH_KEY}` }, ctx());
+        expect(session.editingPath).toBeNull();
+        expect(session.selectedPathPoint).toBeNull();
+        // 调用时项目事务已提交(注册表行已移除)
+        expect(registryStateAtCall).toEqual([[]]);
+    });
+});
+describe('objects.delete 会话清理与 undo', () => {
+    test('删除选中的相机后 selection 清空;undo 恢复项目对象但不恢复会话选择', async () => {
+        const { registry, registeredCameras, seedCameras } = await setup();
+        const objs = seedCameras([{ cameraKey: 'Shot Camera' }]);
+        studioApi.setSelection([objs.get('Shot Camera')]);
+        await registry.execute('objects.delete', { objectId: 'camera:Shot Camera' }, ctx());
+        expect(studioApi.selection).toHaveLength(0);
+        studio.undo();
+        expect(registeredCameras()).toEqual(['Shot Camera']);
+        // 会话状态不进项目历史:undo 不会把选择恢复到任何 ID
+        expect(studioApi.selection).toHaveLength(0);
+    });
+    test('领域校验失败(OBJECT_NOT_FOUND/INVALID_ID_KIND/REVISION_CONFLICT)时不调用会话清理、不返回 deleted', async () => {
+        const { registry, runtime, seedCameras, registeredCameras, notifyHistoric } = await setup();
+        seedCameras([{ cameraKey: 'Shot Camera' }]);
+        const calls = bindSessionCleanup(runtime);
+        await expect(registry.execute('objects.delete', { objectId: 'camera:Ghost' }, ctx())).rejects.toMatchObject({ code: 'OBJECT_NOT_FOUND' });
+        await expect(registry.execute('objects.delete', { objectId: 'nocolon' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ID_KIND' });
+        await expect(registry.execute('objects.delete', {}, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        notifyHistoric();
+        await expect(registry.execute('objects.delete', { objectId: 'camera:Shot Camera', expectedRevision: 1 }, ctx())).rejects.toMatchObject({
+            code: 'REVISION_CONFLICT',
+            details: { expectedRevision: 1, actualRevision: 2 },
+        });
+        expect(registeredCameras()).toEqual(['Shot Camera']);
+        expect(calls).toEqual([]);
+    });
+    test('会话清理 handler 未绑定时删除照常完成(会话态不存在,静默跳过)', async () => {
+        const { registry, registeredCameras, seedCameras } = await setup();
+        seedCameras([{ cameraKey: 'Shot Camera' }]);
+        await expect(registry.execute('objects.delete', { objectId: 'camera:Shot Camera' }, ctx())).resolves.toMatchObject({ deleted: 'camera:Shot Camera' });
+        expect(registeredCameras()).toEqual([]);
+    });
+    test('expectedRevision 匹配时正常删除', async () => {
+        const { registry, registeredCameras, seedCameras } = await setup();
+        seedCameras([{ cameraKey: 'Shot Camera' }]);
+        await expect(registry.execute('objects.delete', { objectId: 'camera:Shot Camera', expectedRevision: 1 }, ctx())).resolves.toEqual({ deleted: 'camera:Shot Camera', revision: 1 });
+        expect(registeredCameras()).toEqual([]);
+    });
+});

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

@@ -0,0 +1,12 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+/** 导出门面(Task 15 由同名命令转发实现) */
+export type ExportsApi = {
+    startVideo(args?: {
+        cameraId?: string;
+    }): Promise<{
+        jobId: string;
+    }>;
+};
+export declare function registerExportCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=exports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/exports.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAM5C,8BAA8B;AAC9B,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,CAAC,IAAI,CAAC,EAAE;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACjE,CAAA;AAoCD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAiGN"}

package/dist/agent/commands/exports.js

@@ -0,0 +1,132 @@
+/**
+ * exports.*(2026-10-17,Task 13):视频导出任务。
+ *
+ * `exports.startVideo` 从指定或当前活动相机导出镜头视频,返回任务 ID
+ * (kind:job、stateDomain:session、undoable:none、cancelable:true、
+ * completion:loaded;会话操作不进 Theatre undo,也不用项目 revision
+ * 伪装并发保护,spec 8.5/8.6.4/9)。
+ *
+ * 流程:命令先做前置校验(控制器未注册 SCENE_UNAVAILABLE、cameraId
+ * 类型 INVALID_ID_KIND、相机不存在 OBJECT_NOT_FOUND、无活动相机/正在
+ * 导出 INVALID_STATE),再经 runtime.jobs.start 起任务;录制本身由场景
+ * 导出控制器(agent/runtime/exportRuntime,CameraScene 挂载时登记)
+ * 执行——与 UI 导出菜单同一流程。handle.done 是任务成功的唯一权威;
+ * jobs.cancel 触发 signal → handle.abort + sink.abort,任务置 cancelled。
+ *
+ * 二进制契约(preflight ruling,同 assets.importModel):JS 任务结果是
+ * VideoExportResult(blob/fileName/mimeType/size),Blob 绝不 JSON 序列化;
+ * jobResultSchema 描述 HTTP FileDescriptor(fileId/fileName/mimeType/size),
+ * Blob → fileId 的适配是桥接职责(POST 临时文件,GET /v1/files/:id 下载)。
+ */
+import { AgentApiError } from '../errors';
+import { parseSceneObjectId } from '../objectIds';
+import { getSceneExportController } from '../runtime/exportRuntime';
+import { requireObject } from '../validation';
+const startVideoInput = {
+    type: 'object',
+    properties: {
+        cameraId: {
+            type: 'string',
+            description: '相机对象 ID(camera:<key>);缺省 = 当前活动相机',
+        },
+    },
+    additionalProperties: false,
+};
+const jobIdOutput = {
+    type: 'object',
+    properties: { jobId: { type: 'string' } },
+    required: ['jobId'],
+};
+/**
+ * HTTP 任务结果形状:桥接把导出 Blob 写入临时文件后下发文件描述;
+ * JS 侧任务结果是 VideoExportResult(blob 不序列化)。
+ */
+const fileDescriptorSchema = {
+    type: 'object',
+    description: 'HTTP:导出文件描述(经 GET /v1/files/:id 下载);JS 结果为 VideoExportResult(blob/fileName/mimeType/size)',
+    properties: {
+        fileId: { type: 'string', description: '桥接临时文件 id' },
+        fileName: { type: 'string' },
+        mimeType: { type: 'string' },
+        size: { type: 'number', description: '字节数' },
+    },
+    required: ['fileId', 'fileName', 'mimeType', 'size'],
+};
+export function registerExportCommands(registry, runtime) {
+    registry.register({
+        name: 'exports.startVideo',
+        kind: 'job',
+        stateDomain: 'session',
+        undoable: 'none',
+        completion: 'loaded',
+        cancelable: true,
+        inputSchema: startVideoInput,
+        outputSchema: jobIdOutput,
+        jobResultSchema: fileDescriptorSchema,
+        errorCodes: [
+            'API_DISPOSED',
+            'SCENE_UNAVAILABLE',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'CAPABILITY_UNAVAILABLE',
+            'JOB_CANCELLED',
+            'INTERNAL_ERROR',
+        ],
+        validate: (value) => {
+            const args = value === undefined || value === null ? {} : requireObject(value);
+            if (args.cameraId === undefined)
+                return {};
+            if (typeof args.cameraId !== 'string' || !args.cameraId) {
+                throw new AgentApiError('INVALID_ARGUMENT', 'cameraId 必须是非空字符串(camera:<key>)');
+            }
+            return { cameraId: args.cameraId };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const controller = getSceneExportController();
+            if (!controller) {
+                throw new AgentApiError('SCENE_UNAVAILABLE', '场景导出控制器未注册(场景尚未挂载)');
+            }
+            // 前置校验在起任务前完成,直接拒绝命令(任务内的失败才走任务终态)
+            let cameraKey;
+            if (args.cameraId !== undefined) {
+                const id = parseSceneObjectId(args.cameraId);
+                if (id.kind !== 'camera') {
+                    throw new AgentApiError('INVALID_ID_KIND', `exports.startVideo 只接受相机对象 ID: ${args.cameraId}`, { details: { cameraId: args.cameraId } });
+                }
+                if (!controller.hasCamera(id.key)) {
+                    throw new AgentApiError('OBJECT_NOT_FOUND', `相机不存在: ${args.cameraId}`, { details: { cameraId: args.cameraId } });
+                }
+                cameraKey = id.key;
+            }
+            const resolvedCameraKey = cameraKey ?? controller.getActiveCameraKey();
+            if (!resolvedCameraKey) {
+                throw new AgentApiError('INVALID_STATE', '没有活动相机,无法导出视频(先创建相机或指定 cameraId)');
+            }
+            if (controller.isExporting()) {
+                throw new AgentApiError('INVALID_STATE', '已有视频导出进行中,请先等待完成或取消(jobs.cancel)');
+            }
+            const { jobId } = runtime.jobs.start({
+                kind: 'exports.startVideo',
+                cancelable: true,
+                execute: async (controls) => {
+                    const result = await controller.startVideo({
+                        cameraKey: resolvedCameraKey,
+                        signal: controls.signal,
+                        onProgress: (progress) => controls.update({ progress }),
+                    });
+                    if (!result) {
+                        // 内存收集路径必然有结果;undefined 只出现在 UI sink
+                        throw new AgentApiError('INTERNAL_ERROR', '导出结束但未产出文件');
+                    }
+                    // 文件已交付(Blob 在手):声明的完成阶段
+                    controls.update({ phase: 'loaded', progress: 1 });
+                    return result;
+                },
+            });
+            return { jobId };
+        },
+    });
+}

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

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

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

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