@dreamerbird/camera-studio 0.1.0 → 0.3.0

package/dist/agent/commands/primitives.js

@@ -0,0 +1,117 @@
+import { AgentApiError } from '../errors';
+import { formatSceneObjectId } from '../objectIds';
+import { getSceneObjectSummary } from '../objectResolver';
+import { requireFiniteNumber, requireObject, requireString, requireVec3, } from '../validation';
+import { PRIMITIVE_KINDS } from '../../primitives';
+const createInput = {
+    type: 'object',
+    properties: {
+        kind: {
+            type: 'string',
+            enum: [...PRIMITIVE_KINDS],
+            description: '米制基础几何体类型',
+        },
+        position: {
+            type: 'object',
+            properties: {
+                x: { type: 'number' },
+                y: { type: 'number' },
+                z: { type: 'number' },
+            },
+            required: ['x', 'y', 'z'],
+            additionalProperties: false,
+            description: '创建位置(世界坐标)',
+        },
+        expectedRevision: {
+            type: 'number',
+            description: '乐观并发:读取场景时的 revision',
+        },
+    },
+    required: ['kind', '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 kind = requireString(args, 'kind');
+    if (!PRIMITIVE_KINDS.includes(kind)) {
+        throw new AgentApiError('INVALID_ARGUMENT', `未知基础几何体类型: ${kind}`, {
+            details: { kind },
+        });
+    }
+    const position = requireVec3(args.position);
+    let expectedRevision;
+    if (args.expectedRevision !== undefined) {
+        expectedRevision = requireFiniteNumber(args.expectedRevision, 'expectedRevision');
+    }
+    return { kind: kind, position, expectedRevision };
+}
+export function registerPrimitiveCommands(registry, runtime) {
+    registry.register({
+        name: 'primitives.create',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'mounted',
+        inputSchema: createInput,
+        outputSchema: createOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+            'RESOURCE_LOAD_FAILED',
+            'INTERNAL_ERROR',
+        ],
+        validate: validateCreate,
+        execute: async (args) => {
+            runtime.assertActive();
+            await runtime.project.ready;
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            const createPrimitive = runtime.handlers.createPrimitive;
+            if (!createPrimitive) {
+                throw new AgentApiError('SCENE_UNAVAILABLE', 'Scene Runtime 未绑定 createPrimitive,无法创建基础几何体');
+            }
+            const placed = createPrimitive({ kind: args.kind, position: args.position });
+            try {
+                await placed.persisted;
+            }
+            catch (error) {
+                runtime.assertActive();
+                throw new AgentApiError('RESOURCE_LOAD_FAILED', `基础几何体挂载失败: ${args.kind}`, {
+                    details: {
+                        kind: args.kind,
+                        cause: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            runtime.assertActive();
+            const objectId = formatSceneObjectId('model', placed.key);
+            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/primitives.test.d.ts

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

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

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

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

@@ -0,0 +1,135 @@
+import { getProject, types as t, val } from '@dreamerbird/core';
+import { globals } from '@dreamerbird/core/globals';
+import { PLACEMENTS_REGISTRY_KEY } from '../../PlacementManager';
+import { createCameraStudioApi } from '../api';
+import { formatSceneObjectId } from '../objectIds';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import { registerSceneSheetObject, unregisterSceneSheetObject, } from '../runtime/objectRuntime';
+import { registerPrimitiveCommands } from './primitives';
+let projectSeq = 0;
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const POSITION = { x: 0, y: 0, z: 0 };
+function deferred() {
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    return { promise, resolve };
+}
+function setup() {
+    const project = getProject(`agent-primitives-${++projectSeq}`, {
+        state: {
+            definitionVersion: globals.currentProjectStateDefinitionVersion,
+            sheetsById: {
+                Scene: {
+                    staticOverrides: { byObject: {} },
+                    sequence: {
+                        type: 'PositionalSequence',
+                        length: 10,
+                        subUnitsPerUnit: 30,
+                        tracksByObject: {},
+                    },
+                },
+            },
+        },
+    });
+    const sheet = project.sheet('Scene');
+    let notifyHistoric = () => { };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => undefined,
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const controller = createCameraStudioApi({
+        buildRegistry: (currentRuntime) => {
+            const registry = new AgentCommandRegistry();
+            registerPrimitiveCommands(registry, currentRuntime);
+            return registry;
+        },
+    });
+    controller.activate(runtime);
+    cleanups.push(() => controller.dispose());
+    const createPrimitive = jest.fn();
+    return {
+        api: controller.api,
+        controller,
+        sheet,
+        runtime,
+        createPrimitive,
+        notifyHistoric: () => notifyHistoric(),
+    };
+}
+function bindCreatePrimitive(controller, createPrimitive, key, persisted) {
+    createPrimitive.mockReturnValue({ key, persisted });
+    const unbind = controller.bindSceneHandlers({
+        createPrimitive: (args) => createPrimitive(args),
+    });
+    cleanups.push(unbind);
+}
+function mountPrimitive(sheet, key) {
+    const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+    registryObj.initialValue = {
+        list: JSON.stringify([{ key, primitive: 'box', position: POSITION }]),
+    };
+    const obj = sheet.object(key, {
+        position: t.compound({ x: t.number(0), y: t.number(0), z: t.number(0) }),
+    });
+    const id = formatSceneObjectId('model', key);
+    registerSceneSheetObject(id, obj);
+    cleanups.push(() => unregisterSceneSheetObject(id, obj));
+}
+async function untilCreatePrimitiveCalled(createPrimitive) {
+    for (let i = 0; i < 50 && createPrimitive.mock.calls.length === 0; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    expect(createPrimitive).toHaveBeenCalled();
+}
+test('api.primitives.create resolves after mounting and persists the primitive entry', async () => {
+    const { api, controller, sheet, createPrimitive, notifyHistoric } = setup();
+    const mount = deferred();
+    bindCreatePrimitive(controller, createPrimitive, 'Box', mount.promise);
+    await api.ready;
+    let resolved = false;
+    const promise = api.primitives
+        .create({ kind: 'box', position: POSITION })
+        .then((result) => {
+        resolved = true;
+        return result;
+    });
+    await untilCreatePrimitiveCalled(createPrimitive);
+    expect(createPrimitive).toHaveBeenCalledWith({
+        kind: 'box',
+        position: POSITION,
+    });
+    expect(resolved).toBe(false);
+    mountPrimitive(sheet, 'Box');
+    notifyHistoric();
+    mount.resolve();
+    await expect(promise).resolves.toEqual({
+        objectId: 'model:Box',
+        revision: 2,
+    });
+    const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, {
+        list: t.string('[]'),
+    });
+    expect(JSON.parse(val(registryObj.props.list))).toEqual([
+        { key: 'Box', primitive: 'box', position: POSITION },
+    ]);
+});
+test('api.primitives.create rejects an unknown kind before any handler call', async () => {
+    const { api, controller, createPrimitive } = setup();
+    bindCreatePrimitive(controller, createPrimitive, 'Box', Promise.resolve());
+    await api.ready;
+    await expect(api.primitives.create({ kind: 'cone', position: POSITION })).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(createPrimitive).not.toHaveBeenCalled();
+});

package/dist/agent/expectedCommands.d.ts

@@ -4,6 +4,6 @@
  * 任何变更必须先改 spec 第 9 节,再同步本清单——契约覆盖测试
  * (contractCoverage.test.ts)对缺少与多出都失败。
  */
-export declare const EXPECTED_AGENT_COMMANDS: readonly ["scene.getSnapshot", "selection.get", "selection.selectObject", "selection.clear", "objects.list", "objects.get", "objects.update", "objects.delete", "models.create", "assets.list", "assets.get", "assets.importModel", "assets.rename", "assets.delete", "poses.apply", "poses.applyCustom", "poses.clear", "poses.saveCurrent", "poses.setGesture", "poses.session.start", "poses.session.commit", "poses.session.cancel", "animations.apply", "animations.clear", "animations.getStatus", "cameras.create", "cameras.setActive", "cameras.setAimTarget", "cameras.bindPath", "cameras.unbindPath", "anchors.create", "anchors.setParent", "anchors.clearParent", "paths.listPresets", "paths.createPreset", "paths.addPoint", "paths.updatePoint", "paths.deletePoint", "paths.setPointTiming", "paths.sample", "paths.session.startEditing", "paths.session.exitEditing", "paths.session.selectPoint", "sequence.getState", "sequence.play", "sequence.pause", "sequence.seek", "sequence.setLength", "keyframes.list", "keyframes.set", "keyframes.move", "keyframes.delete", "history.undo", "history.redo", "view.getState", "view.setShotView", "view.setPipVisible", "view.orbit", "view.pan", "view.dolly", "view.reset", "ui.hide", "ui.restore", "ui.setLeftStripHidden", "ui.openPanel", "ui.closePanel", "ui.setGizmoMode", "project.exportState", "exports.startVideo", "jobs.get", "jobs.cancel"];
+export declare const EXPECTED_AGENT_COMMANDS: readonly ["scene.getSnapshot", "selection.get", "selection.selectObject", "selection.clear", "objects.list", "objects.get", "objects.update", "objects.delete", "models.create", "models.retry", "models.replace", "primitives.create", "materials.list", "materials.update", "assets.list", "assets.get", "assets.importModel", "assets.importModels", "assets.rename", "assets.delete", "poses.apply", "poses.applyCustom", "poses.clear", "poses.saveCurrent", "poses.setGesture", "poses.session.start", "poses.session.commit", "poses.session.cancel", "animations.apply", "animations.clear", "animations.getStatus", "cameras.create", "cameras.setActive", "cameras.setAimTarget", "cameras.bindPath", "cameras.unbindPath", "anchors.create", "anchors.setParent", "anchors.clearParent", "paths.listPresets", "paths.createPreset", "paths.addPoint", "paths.updatePoint", "paths.deletePoint", "paths.setPointTiming", "paths.sample", "paths.session.startEditing", "paths.session.exitEditing", "paths.session.selectPoint", "sequence.getState", "sequence.play", "sequence.pause", "sequence.seek", "sequence.setLength", "keyframes.list", "keyframes.set", "keyframes.move", "keyframes.delete", "history.undo", "history.redo", "view.getState", "view.setShotView", "view.setPipVisible", "view.orbit", "view.pan", "view.dolly", "view.reset", "ui.hide", "ui.restore", "ui.setLeftStripHidden", "ui.openPanel", "ui.closePanel", "ui.setGizmoMode", "project.exportState", "exports.startVideo", "jobs.get", "jobs.cancel"];
 export type ExpectedAgentCommand = (typeof EXPECTED_AGENT_COMMANDS)[number];
 //# sourceMappingURL=expectedCommands.d.ts.map

package/dist/agent/expectedCommands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expectedCommands.d.ts","sourceRoot":"","sources":["../../src/agent/expectedCommands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,+1CAwE1B,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA"}
+{"version":3,"file":"expectedCommands.d.ts","sourceRoot":"","sources":["../../src/agent/expectedCommands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,m9CA8E1B,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA"}

package/dist/agent/expectedCommands.js

@@ -14,9 +14,15 @@ export const EXPECTED_AGENT_COMMANDS = [
     'objects.update',
     'objects.delete',
     'models.create',
+    'models.retry',
+    'models.replace',
+    'primitives.create',
+    'materials.list',
+    'materials.update',
     'assets.list',
     'assets.get',
     'assets.importModel',
+    'assets.importModels',
     'assets.rename',
     'assets.delete',
     'poses.apply',

package/dist/agent/propAccess.d.ts

@@ -28,6 +28,8 @@ export declare function assertStaticPropsWritable(sheetObject: ISheetObject<$Int
  * SCENE_UNAVAILABLE(不静默返回,spec 8.3)。
  */
 export declare function setStaticProps(sheetObject: ISheetObject<$IntentionalAny>, props: Record<string, unknown>): void;
+export declare function assertStaticPropsWithLeafGuardWritable(sheetObject: ISheetObject<$IntentionalAny>, props: Record<string, unknown>, guardedPropPaths: string[]): void;
+export declare function setStaticPropsWithLeafGuard(sheetObject: ISheetObject<$IntentionalAny>, props: Record<string, unknown>, guardedPropPaths: string[]): void;
 /**
  * 领域静态写入 + 坐标定格同事务(2026-10-19,Agent API F1 修复):
  * 绑定/父级切换类命令(setParent/clearParent/unbindPath/setAimTarget 解除)

package/dist/agent/propAccess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"propAccess.d.ts","sourceRoot":"","sources":["../../src/agent/propAccess.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gCAAgC,CAAA;AACnE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAA;AAInD;;;GAGG;AACH,QAAA,MAAM,gBAAgB,aAWpB,CAAA;AAEF,OAAO,EAAC,gBAAgB,EAAC,CAAA;AAEzB,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAM1B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAaT;AA4FD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAyBN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAGN;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAGN"}
+{"version":3,"file":"propAccess.d.ts","sourceRoot":"","sources":["../../src/agent/propAccess.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gCAAgC,CAAA;AACnE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAA;AAInD;;;GAGG;AACH,QAAA,MAAM,gBAAgB,aAYpB,CAAA;AAEF,OAAO,EAAC,gBAAgB,EAAC,CAAA;AAEzB,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAM1B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAaT;AA4FD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAyBN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAGN;AAED,wBAAgB,sCAAsC,CACpD,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,gBAAgB,EAAE,MAAM,EAAE,GACzB,IAAI,CAmBN;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,gBAAgB,EAAE,MAAM,EAAE,GACzB,IAAI,CAGN;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAGN"}

package/dist/agent/propAccess.js

@@ -25,6 +25,7 @@ const domainOwnedProps = new Set([
     'gestureL',
     'gestureR',
     'animation',
+    'materialOverrides',
     'aimTarget',
     'pathKey',
     'parent',
@@ -154,6 +155,26 @@ export function setStaticProps(sheetObject, props) {
     assertStaticPropsWritable(sheetObject, props);
     writePropsInTransaction(sheetObject, props);
 }
+export function assertStaticPropsWithLeafGuardWritable(sheetObject, props, guardedPropPaths) {
+    const current = sheetObject.value;
+    for (const [key, value] of Object.entries(props)) {
+        if (!current || !(key in current)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `未知属性: ${key}`, {
+                details: { prop: key },
+            });
+        }
+        validateValueShape(key, current[key], value);
+    }
+    for (const propPath of guardedPropPaths) {
+        if (isPropSequenced(sheetObject, propPath)) {
+            throw new AgentApiError('INVALID_STATE', `属性 ${propPath} 已建轨,请改用 keyframes.* 写入`, { details: { prop: propPath } });
+        }
+    }
+}
+export function setStaticPropsWithLeafGuard(sheetObject, props, guardedPropPaths) {
+    assertStaticPropsWithLeafGuardWritable(sheetObject, props, guardedPropPaths);
+    writePropsInTransaction(sheetObject, props);
+}
 /**
  * 领域静态写入 + 坐标定格同事务(2026-10-19,Agent API F1 修复):
  * 绑定/父级切换类命令(setParent/clearParent/unbindPath/setAimTarget 解除)

package/dist/agent/registerCommands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registerCommands.d.ts","sourceRoot":"","sources":["../../src/agent/registerCommands.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,WAAW,CAAA;AA8B3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAkCN"}
+{"version":3,"file":"registerCommands.d.ts","sourceRoot":"","sources":["../../src/agent/registerCommands.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,WAAW,CAAA;AAgC3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAoCN"}

package/dist/agent/registerCommands.js

@@ -1,6 +1,6 @@
 /**
  * 全量 Agent 命令注册(2026-10-19,Task 15):按 Task 4–14 落地顺序
- * 注册全部 18 个命令组(spec §9 命令面,71 条命令),供生产会话与
+ * 注册全部 20 个命令组(spec §9 命令面,75 条命令),供生产会话与
  * 契约测试共用同一个注册入口。
  *
  * 重复命令兜底:registry.register 本身按名拒重(INVALID_STATE),注册
@@ -20,6 +20,8 @@ import { registerHistoryCommands } from './commands/history';
 import { registerKeyframeCommands } from './commands/keyframes';
 // Task 8:模型创建 + 资产管理 + 任务查询/取消
 import { registerModelCommands } from './commands/models';
+import { registerPrimitiveCommands } from './commands/primitives';
+import { registerMaterialCommands } from './commands/materials';
 import { registerAssetCommands } from './commands/assets';
 import { registerJobCommands } from './commands/jobs';
 // Task 9:姿势/手势 + 动画
@@ -54,6 +56,8 @@ export function registerAllAgentCommands(registry, runtime) {
     registerKeyframeCommands(registry, runtime);
     // Task 8
     registerModelCommands(registry, runtime);
+    registerPrimitiveCommands(registry, runtime);
+    registerMaterialCommands(registry, runtime);
     registerAssetCommands(registry, runtime);
     registerJobCommands(registry, runtime);
     // Task 9

package/dist/agent/runtime/objectRuntime.d.ts

@@ -9,6 +9,8 @@
  */
 import type { ISheetObject } from '@dreamerbird/core';
 import type { SceneObjectId } from '../types';
+export declare function subscribeSceneSheetObjects(listener: () => void): () => void;
+export declare function clearSceneSheetObjects(): void;
 /** 登记某业务对象当前挂载的 SheetObject(objRef 填充时) */
 export declare function registerSceneSheetObject(id: SceneObjectId, obj: ISheetObject<any>): void;
 /**

package/dist/agent/runtime/objectRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objectRuntime.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/objectRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAI3C,2CAA2C;AAC3C,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,aAAa,EACjB,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GACrB,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,aAAa,EACjB,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GACtB,IAAI,CAGN;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,aAAa,GAChB,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAE/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAK5E"}
+{"version":3,"file":"objectRuntime.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/objectRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAS3C,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG3E;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED,2CAA2C;AAC3C,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,aAAa,EACjB,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GACrB,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,aAAa,EACjB,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GACtB,IAAI,CAGN;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,aAAa,GAChB,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAE/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAK5E"}

package/dist/agent/runtime/objectRuntime.js

@@ -1,7 +1,20 @@
 const sceneSheetObjects = new Map();
+const listeners = new Set();
+function emitChange() {
+    listeners.forEach((listener) => listener());
+}
+export function subscribeSceneSheetObjects(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function clearSceneSheetObjects() {
+    sceneSheetObjects.clear();
+    emitChange();
+}
 /** 登记某业务对象当前挂载的 SheetObject(objRef 填充时) */
 export function registerSceneSheetObject(id, obj) {
     sceneSheetObjects.set(id, obj);
+    emitChange();
 }
 /**
  * 按 id 清理登记(objRef 清空/组件卸载时)。传入 obj 时仅当登记的还是
@@ -10,7 +23,8 @@ export function registerSceneSheetObject(id, obj) {
 export function unregisterSceneSheetObject(id, obj) {
     if (obj && sceneSheetObjects.get(id) !== obj)
         return;
-    sceneSheetObjects.delete(id);
+    if (sceneSheetObjects.delete(id))
+        emitChange();
 }
 /** 当前挂载的 SheetObject;未挂载(注册表有条目但组件未起)为 undefined */
 export function getSceneSheetObject(id) {

package/dist/agent/runtime.d.ts

@@ -30,6 +30,7 @@ export type AgentRuntime = {
     readonly library: Library;
     readonly getStudio: () => IStudio | undefined;
     readonly jobs: AgentJobManager;
+    subscribeHistoric(listener: () => void): () => void;
     /** 当前会话的 historic revision,从 1 开始 */
     readonly revision: number;
     /**

package/dist/agent/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/agent/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAC,MAAM,mBAAmB,CAAA;AAGhE,OAAO,EAAC,eAAe,EAAC,MAAM,QAAQ,CAAA;AACtC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,yBAAyB,CAAA;AAyCpD;;;;GAIG;AAEH,MAAM,WAAW,yBAAyB;CAAG;AAE7C,KAAK,QAAQ,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,QAAQ,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAA;IACpC;2FACuF;IACvF,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CACxD,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACrC,6DAA6D;IAC7D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,mBAAmB;IACnB,YAAY,IAAI,IAAI,CAAA;IACpB,uCAAuC;IACvC,aAAa,IAAI,IAAI,CAAA;IACrB,wDAAwD;IACxD,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAA;IAC5C;qEACiE;IACjE,QAAQ,IAAI,YAAY,CAAA;IACxB,qDAAqD;IACrD,SAAS,IAAI,IAAI,CAAA;IACjB;8DAC0D;IAC1D,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAsED,0DAA0D;AAC1D,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOnE;AAqHD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAyBvE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/agent/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAC,MAAM,mBAAmB,CAAA;AAGhE,OAAO,EAAC,eAAe,EAAC,MAAM,QAAQ,CAAA;AACtC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,yBAAyB,CAAA;AAyCpD;;;;GAIG;AAEH,MAAM,WAAW,yBAAyB;CAAG;AAE7C,KAAK,QAAQ,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,QAAQ,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAA;IACpC;2FACuF;IACvF,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CACxD,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,iBAAiB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IACnD,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACrC,6DAA6D;IAC7D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,mBAAmB;IACnB,YAAY,IAAI,IAAI,CAAA;IACpB,uCAAuC;IACvC,aAAa,IAAI,IAAI,CAAA;IACrB,wDAAwD;IACxD,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAA;IAC5C;qEACiE;IACjE,QAAQ,IAAI,YAAY,CAAA;IACxB,qDAAqD;IACrD,SAAS,IAAI,IAAI,CAAA;IACjB;8DAC0D;IAC1D,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAuED,0DAA0D;AAC1D,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOnE;AAsHD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA0BvE"}

package/dist/agent/runtime.js

@@ -87,6 +87,7 @@ function makeRuntime(core, generation) {
         library: core.library,
         getStudio: core.getStudio,
         jobs: core.jobs,
+        subscribeHistoric: core.subscribeHistoric,
         get revision() {
             return core.revision;
         },
@@ -197,6 +198,7 @@ export function createAgentRuntime(deps) {
         revision: 1,
         currentGeneration: first,
         generations: new Set([first]),
+        subscribeHistoric: deps.subscribeHistoric,
         unsubscribeHistoric: () => { },
     };
     // 订阅必须在 core 建好之后:真实 subscribeHistoric 走 core

package/dist/assetLibrary/dispose.d.ts

@@ -1,4 +1,6 @@
 import type { Object3D } from 'three';
-/** 递归释放对象树的 GPU 资源(几何体/材质/纹理),实例卸载时调用 */
-export declare function disposeObjectTree(root: Object3D): void;
+/** 递归释放对象树的 GPU 资源;纹理默认随材质释放,共享纹理的克隆实例可关闭 */
+export declare function disposeObjectTree(root: Object3D, options?: {
+    disposeTextures?: boolean;
+}): void;
 //# sourceMappingURL=dispose.d.ts.map

package/dist/assetLibrary/dispose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispose.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/dispose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,QAAQ,EAAU,MAAM,OAAO,CAAA;AAEtD,yCAAyC;AACzC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAqBtD"}
+{"version":3,"file":"dispose.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/dispose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,QAAQ,EAAU,MAAM,OAAO,CAAA;AAEtD,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAM,GACxC,IAAI,CAuBN"}

package/dist/assetLibrary/dispose.js

@@ -1,5 +1,5 @@
-/** 递归释放对象树的 GPU 资源(几何体/材质/纹理),实例卸载时调用 */
-export function disposeObjectTree(root) {
+/** 递归释放对象树的 GPU 资源;纹理默认随材质释放,共享纹理的克隆实例可关闭 */
+export function disposeObjectTree(root, options = {}) {
     root.traverse((o) => {
         const mesh = o;
         if (!mesh.isMesh)
@@ -11,9 +11,11 @@ export function disposeObjectTree(root) {
                 ? [mesh.material]
                 : [];
         for (const m of mats) {
-            for (const v of Object.values(m)) {
-                if (v?.isTexture)
-                    v.dispose();
+            if (options.disposeTextures !== false) {
+                for (const v of Object.values(m)) {
+                    if (v?.isTexture)
+                        v.dispose();
+                }
             }
             m.dispose();
         }

package/dist/assetLibrary/exportGLB.d.ts

@@ -1,5 +1,30 @@
 import { Group } from 'three';
 import type { AnimationClip, Object3D } from 'three';
+/**
+ * 场景单位 = 米(2026-10-21 起,替代此前「最长边统一拉成 5 单位」的
+ * 归一化约定)。glTF 标准本来就是米,人高 1.8 单位、网格 1 小格 = 1 米,
+ * 模型之间保持真实世界的相对大小(车 4.5 / 人 1.8 / 杯子 0.1)。
+ * PlacementManager 的 useNormalizedModel 用同一套换算兜底未烘焙来源。
+ */
+export declare const SCENE_UNIT_METERS = 1;
+/**
+ * 厘米源判定阈值:最长边超过这个数就按厘米源处理(÷100)。
+ * Mixamo 等 FBX 是厘米(人 180),标准 GLB 是米(人 1.8)。取 50 是因为
+ * 米制模型最长边到 50(=50 米,一栋楼)在本系统里罕见,而厘米源几乎
+ * 都远超(一个人就 180)。猜错的入口(超大道具/建筑)保留手动改缩放。
+ */
+export declare const CENTIMETER_SOURCE_THRESHOLD = 50;
+/** 源尺寸最长边 → 米制换算系数(米源返回 1,厘米源返回 0.01) */
+export declare function metricScaleFactor(maxDim: number): number;
+/**
+ * 把「源单位 → 米」的换算系数烘进根节点 scale(入库前置)。
+ * 源文件单位五花八门(Mixamo FBX 是厘米、GLB 多是米),烘过之后任何
+ * 模型都是真实米制尺寸,放置时 theatre 对象的缩放属性才能以 1 为
+ * 干净基线(1 = 真实大小,2 = 两倍大)。只动根节点变换:蒙皮随骨骼
+ * 世界变换正确缩放,骨骼局部数据(动画轨道寻址的那层)不受影响。
+ * 返回应用的系数(1 = 本来就是米,没动)。
+ */
+export declare function bakeMetricScale(root: Object3D): number;
 /**
  * 移除无法导出的贴图(image 数据缺失)。
  * FBX 常引用本机不存在的外部贴图文件,加载失败后留下 image 为空的 Texture,

package/dist/assetLibrary/exportGLB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exportGLB.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/exportGLB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,EAAC,MAAM,OAAO,CAAA;AACjC,OAAO,KAAK,EAAC,aAAa,EAAQ,QAAQ,EAAU,MAAM,OAAO,CAAA;AAIjE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA6B3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAoBnD;AAgBD,0CAA0C;AAC1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAQnE;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB"}
+{"version":3,"file":"exportGLB.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/exportGLB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,EAAU,MAAM,OAAO,CAAA;AAChD,OAAO,KAAK,EAAC,aAAa,EAAQ,QAAQ,EAAU,MAAM,OAAO,CAAA;AAIjE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,yCAAyC;AACzC,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAStD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA6B3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAoBnD;AAgBD,0CAA0C;AAC1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBnE;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB"}

package/dist/assetLibrary/exportGLB.js

@@ -1,6 +1,44 @@
-import { Bone, Group } from 'three';
+import { Bone, Box3, Group, Vector3 } from 'three';
 import { GLTFExporter } from 'three-stdlib';
 import { compressGLBDraco } from './draco';
+/**
+ * 场景单位 = 米(2026-10-21 起,替代此前「最长边统一拉成 5 单位」的
+ * 归一化约定)。glTF 标准本来就是米,人高 1.8 单位、网格 1 小格 = 1 米,
+ * 模型之间保持真实世界的相对大小(车 4.5 / 人 1.8 / 杯子 0.1)。
+ * PlacementManager 的 useNormalizedModel 用同一套换算兜底未烘焙来源。
+ */
+export const SCENE_UNIT_METERS = 1;
+/**
+ * 厘米源判定阈值:最长边超过这个数就按厘米源处理(÷100)。
+ * Mixamo 等 FBX 是厘米(人 180),标准 GLB 是米(人 1.8)。取 50 是因为
+ * 米制模型最长边到 50(=50 米,一栋楼)在本系统里罕见,而厘米源几乎
+ * 都远超(一个人就 180)。猜错的入口(超大道具/建筑)保留手动改缩放。
+ */
+export const CENTIMETER_SOURCE_THRESHOLD = 50;
+/** 源尺寸最长边 → 米制换算系数(米源返回 1,厘米源返回 0.01) */
+export function metricScaleFactor(maxDim) {
+    return maxDim > CENTIMETER_SOURCE_THRESHOLD ? 0.01 : SCENE_UNIT_METERS;
+}
+/**
+ * 把「源单位 → 米」的换算系数烘进根节点 scale(入库前置)。
+ * 源文件单位五花八门(Mixamo FBX 是厘米、GLB 多是米),烘过之后任何
+ * 模型都是真实米制尺寸,放置时 theatre 对象的缩放属性才能以 1 为
+ * 干净基线(1 = 真实大小,2 = 两倍大)。只动根节点变换:蒙皮随骨骼
+ * 世界变换正确缩放,骨骼局部数据(动画轨道寻址的那层)不受影响。
+ * 返回应用的系数(1 = 本来就是米,没动)。
+ */
+export function bakeMetricScale(root) {
+    const box = new Box3().setFromObject(root);
+    const size = box.getSize(new Vector3());
+    const maxDim = Math.max(size.x, size.y, size.z);
+    if (!(maxDim > 0))
+        return 1;
+    const factor = metricScaleFactor(maxDim);
+    if (factor === 1)
+        return 1;
+    root.scale.multiplyScalar(factor);
+    return factor;
+}
 /**
  * 移除无法导出的贴图(image 数据缺失)。
  * FBX 常引用本机不存在的外部贴图文件,加载失败后留下 image 为空的 Texture,
@@ -75,6 +113,10 @@ export function exportModelGLB(root) {
     if (stripped > 0) {
         console.warn(`[assetLibrary] ${stripped} 张贴图数据无效(源文件引用的贴图缺失或加载失败),已移除后继续导出,模型将以灰模/部分贴图入库`);
     }
+    const factor = bakeMetricScale(root);
+    if (factor !== 1) {
+        console.info(`[assetLibrary] 已把源尺寸换算成米烘进模型(系数 ${factor.toFixed(4)}),放置时缩放基线为 1 = 真实大小`);
+    }
     return exportGLB(root, []).then(compressGLBDraco);
 }
 /** 动作入库:骨骼树克隆 + 单条动画,不含网格 */