@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,23 @@
+/**
+ * jobs.get / jobs.cancel(2026-10-17,Task 8):长任务查询与取消,
+ * 本任务的 assets.importModel 与后续视频导出(exports.startVideo)共用。
+ *
+ * 任务状态是会话域(stateDomain:session):不属于项目 undo,也不接受
+ * expectedRevision(spec 8.5)。get 透传 job manager 的冻结快照;
+ * cancel 先取消再返回取消后的快照(manager 抛 JOB_NOT_FOUND /
+ * JOB_NOT_CANCELABLE / INVALID_STATE 原样上抛)。
+ */
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { JobSnapshot } from '../types';
+/** 任务门面(Task 15 由同名命令转发实现) */
+export type JobsApi = {
+    get(args: {
+        jobId: string;
+    }): Promise<JobSnapshot>;
+    cancel(args: {
+        jobId: string;
+    }): Promise<JobSnapshot>;
+};
+export declare function registerJobCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=jobs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAC,WAAW,EAAa,MAAM,UAAU,CAAA;AAGrD,8BAA8B;AAC9B,MAAM,MAAM,OAAO,GAAG;IACpB,GAAG,CAAC,IAAI,EAAE;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAChD,MAAM,CAAC,IAAI,EAAE;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACpD,CAAA;AAiCD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAqCN"}

package/dist/agent/commands/jobs.js

@@ -0,0 +1,66 @@
+import { requireObject, requireString } from '../validation';
+const jobIdInput = {
+    type: 'object',
+    properties: {
+        jobId: { type: 'string', description: '任务 id(任务命令的返回值)' },
+    },
+    required: ['jobId'],
+    additionalProperties: false,
+};
+const jobSnapshotSchema = {
+    type: 'object',
+    properties: {
+        jobId: { type: 'string' },
+        kind: { type: 'string' },
+        state: { enum: ['pending', 'running', 'succeeded', 'failed', 'cancelled'] },
+        progress: { type: 'number', description: '0..1' },
+        phase: { enum: ['accepted', 'committed', 'mounted', 'loaded'] },
+        result: { description: '成功时的任务输出(形状见各命令 jobResultSchema)' },
+        error: {
+            type: 'object',
+            description: '失败时的结构化错误{code,message,retryable,details?}',
+        },
+        cancelable: { type: 'boolean' },
+    },
+    required: ['jobId', 'kind', 'state', 'progress', 'phase', 'cancelable'],
+};
+function validateJobId(value) {
+    return { jobId: requireString(requireObject(value), 'jobId') };
+}
+export function registerJobCommands(registry, runtime) {
+    registry.register({
+        name: 'jobs.get',
+        kind: 'query',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: jobIdInput,
+        outputSchema: jobSnapshotSchema,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'JOB_NOT_FOUND'],
+        validate: validateJobId,
+        execute: async (args) => {
+            runtime.assertActive();
+            return runtime.jobs.get(args.jobId);
+        },
+    });
+    registry.register({
+        name: 'jobs.cancel',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: jobIdInput,
+        outputSchema: jobSnapshotSchema,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'JOB_NOT_FOUND',
+            'JOB_NOT_CANCELABLE',
+            'INVALID_STATE',
+        ],
+        validate: validateJobId,
+        execute: async (args) => {
+            runtime.assertActive();
+            runtime.jobs.cancel(args.jobId);
+            return runtime.jobs.get(args.jobId);
+        },
+    });
+}

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

@@ -0,0 +1,42 @@
+import type { KeyframeInfo } from '../keyframeTracks';
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+export type { KeyframeInfo } from '../keyframeTracks';
+/** 关键帧门面(Task 15 由同名命令转发实现) */
+export type KeyframesApi = {
+    list(args: {
+        objectId: string;
+        propPath: string[];
+    }): Promise<KeyframeInfo[]>;
+    set(args: {
+        objectId: string;
+        propPath: string[];
+        at: number;
+        value: unknown;
+        snap?: boolean;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    move(args: {
+        objectId: string;
+        propPath: string[];
+        from: number;
+        to: number;
+        snap?: boolean;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    delete(args: {
+        objectId: string;
+        propPath: string[];
+        at: number;
+        snap?: boolean;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+};
+export declare function registerKeyframeCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=keyframes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyframes.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/keyframes.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAGnD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAI5C,YAAY,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAEnD,+BAA+B;AAC/B,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,CAAC,IAAI,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IAC3E,GAAG,CAAC,IAAI,EAAE;QACR,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;QAClB,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,EAAE,OAAO,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC/B,IAAI,CAAC,IAAI,EAAE;QACT,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;QAClB,IAAI,EAAE,MAAM,CAAA;QACZ,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC/B,MAAM,CAAC,IAAI,EAAE;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;QAClB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAChC,CAAA;AA6MD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAoMN"}

package/dist/agent/commands/keyframes.js

@@ -0,0 +1,310 @@
+import { AgentApiError } from '../errors';
+import { deleteKeyframe, findKeyframeAt, listKeyframes, moveKeyframe, setKeyframe, } from '../keyframeTracks';
+import { resolveSceneSheetObject } from '../objectResolver';
+import { isPropSequenced } from '../propAccess';
+import { requireFiniteNumber, requireObject, requireString } from '../validation';
+const objectTargetProperties = {
+    objectId: { type: 'string', description: '带类型场景对象 ID,如 model:Y Bot' },
+    propPath: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '简单叶子的属性路径分段,如 ["position","x"]',
+    },
+};
+const snapProperty = {
+    type: 'boolean',
+    description: '先按序列网格吸附位置再写入,默认 false',
+};
+const expectedRevisionProperty = {
+    type: 'number',
+    description: '乐观并发:读取场景时的 revision',
+};
+const keyframeListOutput = {
+    type: 'array',
+    items: {
+        type: 'object',
+        properties: {
+            position: { type: 'number' },
+            value: { description: '关键帧值(简单叶子的标量)' },
+        },
+        required: ['position', 'value'],
+    },
+};
+const revisionOutput = {
+    type: 'object',
+    properties: { revision: { type: 'number' } },
+    required: ['revision'],
+};
+function requirePropPath(value) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.some((segment) => typeof segment !== 'string' || segment.length === 0)) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'propPath 必须是非空字符串数组,如 ["position","x"]');
+    }
+    return value;
+}
+function optionalSnap(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean') {
+        throw new AgentApiError('INVALID_ARGUMENT', 'snap 必须是布尔值');
+    }
+    return value;
+}
+function optionalExpectedRevision(value) {
+    if (value === undefined)
+        return undefined;
+    return requireFiniteNumber(value, 'expectedRevision');
+}
+function validateTarget(value) {
+    const args = requireObject(value);
+    return {
+        objectId: requireString(args, 'objectId'),
+        propPath: requirePropPath(args.propPath),
+    };
+}
+function validateSet(value) {
+    const target = validateTarget(value);
+    const args = value;
+    if (!('value' in args)) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'value 必填');
+    }
+    return {
+        ...target,
+        at: requireFiniteNumber(args.at, 'at'),
+        value: args.value,
+        snap: optionalSnap(args.snap),
+        expectedRevision: optionalExpectedRevision(args.expectedRevision),
+    };
+}
+function validateMove(value) {
+    const target = validateTarget(value);
+    const args = value;
+    return {
+        ...target,
+        from: requireFiniteNumber(args.from, 'from'),
+        to: requireFiniteNumber(args.to, 'to'),
+        snap: optionalSnap(args.snap),
+        expectedRevision: optionalExpectedRevision(args.expectedRevision),
+    };
+}
+function validateDelete(value) {
+    const target = validateTarget(value);
+    const args = value;
+    return {
+        ...target,
+        at: requireFiniteNumber(args.at, 'at'),
+        snap: optionalSnap(args.snap),
+        expectedRevision: optionalExpectedRevision(args.expectedRevision),
+    };
+}
+/**
+ * 解析对象并校验 propPath 指向简单叶子:对象不存在 OBJECT_NOT_FOUND、
+ * 类型不符 INVALID_ID_KIND、未挂载 INVALID_STATE;路径未知或指向
+ * compound 抛 INVALID_ARGUMENT。返回叶子当前求值供值形状校验。
+ */
+function resolveSimpleLeaf(runtime, objectId, propPath) {
+    const sheetObject = resolveSceneSheetObject(runtime.sheet, objectId);
+    if (!sheetObject) {
+        throw new AgentApiError('INVALID_STATE', `对象未挂载,无法操作关键帧: ${objectId}`, { details: { objectId } });
+    }
+    let current = sheetObject.value;
+    for (const segment of propPath) {
+        if (!current ||
+            typeof current !== 'object' ||
+            Array.isArray(current) ||
+            !(segment in current)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `未知属性路径: ${propPath.join('.')}`, { details: { objectId, propPath } });
+        }
+        current = current[segment];
+    }
+    if (typeof current !== 'number' &&
+        typeof current !== 'string' &&
+        typeof current !== 'boolean') {
+        throw new AgentApiError('INVALID_ARGUMENT', `propPath 必须指向简单叶子属性: ${propPath.join('.')}`, { details: { objectId, propPath } });
+    }
+    return { sheetObject, current };
+}
+/** 值形状与叶子当前简单值类型匹配(数字须有限) */
+function assertValueMatchesLeaf(label, current, value) {
+    if (typeof current === 'number') {
+        requireFiniteNumber(value, label);
+        return;
+    }
+    if (typeof value !== typeof current) {
+        throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是 ${typeof current} 类型`);
+    }
+}
+function keyframeNotFound(propPath, position) {
+    return new AgentApiError('KEYFRAME_NOT_FOUND', `位置 ${position} 没有关键帧: ${propPath.join('.')}`, { details: { propPath, position } });
+}
+export function registerKeyframeCommands(registry, runtime) {
+    registry.register({
+        name: 'keyframes.list',
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: objectTargetProperties,
+            required: ['objectId', 'propPath'],
+            additionalProperties: false,
+        },
+        outputSchema: keyframeListOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+        ],
+        validate: validateTarget,
+        execute: async (args) => {
+            runtime.assertActive();
+            const { sheetObject } = resolveSimpleLeaf(runtime, args.objectId, args.propPath);
+            return listKeyframes(runtime.sheet, sheetObject, args.propPath);
+        },
+    });
+    registry.register({
+        name: 'keyframes.set',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...objectTargetProperties,
+                at: { type: 'number', description: '关键帧位置(秒)' },
+                value: { description: '关键帧值,形状与叶子当前值一致' },
+                snap: snapProperty,
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'propPath', 'at', 'value'],
+            additionalProperties: false,
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateSet,
+        execute: async (args) => {
+            runtime.assertActive();
+            const { sheetObject, current } = resolveSimpleLeaf(runtime, args.objectId, args.propPath);
+            assertValueMatchesLeaf(args.propPath.join('.'), current, args.value);
+            const sequenced = isPropSequenced(sheetObject, args.propPath.join('.'));
+            const sequence = runtime.sheet.sequence;
+            const at = args.snap ? sequence.closestGridPosition(args.at) : args.at;
+            // 全部校验先于乐观并发与事务(同 objects.update)
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            setKeyframe(runtime.sheet, sheetObject, args.propPath, {
+                position: at,
+                value: args.value,
+                sequenced,
+            });
+            // historic 通知 tick 调度:等一个 tick,返回反映本次写入的 revision
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+    registry.register({
+        name: 'keyframes.move',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...objectTargetProperties,
+                from: { type: 'number', description: '源关键帧位置(秒)' },
+                to: { type: 'number', description: '目标位置(秒)' },
+                snap: snapProperty,
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'propPath', 'from', 'to'],
+            additionalProperties: false,
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'KEYFRAME_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateMove,
+        execute: async (args) => {
+            runtime.assertActive();
+            const { sheetObject } = resolveSimpleLeaf(runtime, args.objectId, args.propPath);
+            const sequence = runtime.sheet.sequence;
+            const from = args.snap
+                ? sequence.closestGridPosition(args.from)
+                : args.from;
+            const to = args.snap ? sequence.closestGridPosition(args.to) : args.to;
+            const target = findKeyframeAt(runtime.sheet, sheetObject, args.propPath, from);
+            if (!target)
+                throw keyframeNotFound(args.propPath, from);
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            moveKeyframe(runtime.sheet, sheetObject, target, { from, to });
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+    registry.register({
+        name: 'keyframes.delete',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...objectTargetProperties,
+                at: { type: 'number', description: '要删除的关键帧位置(秒)' },
+                snap: snapProperty,
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'propPath', 'at'],
+            additionalProperties: false,
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'KEYFRAME_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateDelete,
+        execute: async (args) => {
+            runtime.assertActive();
+            const { sheetObject } = resolveSimpleLeaf(runtime, args.objectId, args.propPath);
+            const sequence = runtime.sheet.sequence;
+            const at = args.snap ? sequence.closestGridPosition(args.at) : args.at;
+            // 先确认该位置确有关键帧:否则 core 的 unset 会落到静态覆盖上
+            const target = findKeyframeAt(runtime.sheet, sheetObject, args.propPath, at);
+            if (!target)
+                throw keyframeNotFound(args.propPath, at);
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            deleteKeyframe(runtime.sheet, sheetObject, args.propPath, { position: at });
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+}

package/dist/agent/commands/keyframes.realStudio.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * keyframes.set 首次建轨的真实 Studio 行为测试(2026-10-17,Ruling 1):
+ * 第一次 keyframes.set 必须真正落下关键帧——随后 keyframes.list 能读到
+ * 新的 {position,value};且整个调用对撤销历史只呈现一步(建轨事务
+ * undoable:false,一次 undo 后帧消失、轨道保留)。
+ *
+ * 与 keyframes.test.ts(假事务,验调用形状)互补:本文件用真实 Studio
+ * (同 studio integration-tests 的引导方式)验端到端落库。
+ */
+import '@dreamerbird/studio';
+//# sourceMappingURL=keyframes.realStudio.test.d.ts.map

package/dist/agent/commands/keyframes.realStudio.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyframes.realStudio.test.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/keyframes.realStudio.test.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AACH,OAAO,qBAAqB,CAAA"}

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

@@ -0,0 +1,95 @@
+/* eslint-disable import/no-extraneous-dependencies */
+/**
+ * keyframes.set 首次建轨的真实 Studio 行为测试(2026-10-17,Ruling 1):
+ * 第一次 keyframes.set 必须真正落下关键帧——随后 keyframes.list 能读到
+ * 新的 {position,value};且整个调用对撤销历史只呈现一步(建轨事务
+ * undoable:false,一次 undo 后帧消失、轨道保留)。
+ *
+ * 与 keyframes.test.ts(假事务,验调用形状)互补:本文件用真实 Studio
+ * (同 studio integration-tests 的引导方式)验端到端落库。
+ */
+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 { PLACEMENTS_REGISTRY_KEY } from '../../PlacementManager';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import * as objectRuntime from '../runtime/objectRuntime';
+import { registerKeyframeCommands } from './keyframes';
+const studio = getStudio();
+void theatre.init({ studio: true, usePersistentStorage: false });
+let projectSeq = 0;
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+/** 探 saaz 撤销栈(私有路径,同 studio undoHistory.test.ts 的取证方式) */
+const undoStackOf = () => {
+    const s = studio;
+    const saaz = (s._store?._saaz ?? s._saaz);
+    return saaz?._atom?.get?.()?.undoRedo?.stack ?? [];
+};
+test('首次 keyframes.set 真正落帧:list 读到新帧;撤销历史只增一步,undo 后帧消轨存', async () => {
+    const project = getProject(`agent-kf-real-${++projectSeq}`, {
+        state: {
+            definitionVersion: globals.currentProjectStateDefinitionVersion,
+            sheetsById: {
+                Scene: {
+                    staticOverrides: { byObject: {} },
+                    sequence: {
+                        type: 'PositionalSequence',
+                        length: 10,
+                        subUnitsPerUnit: 30,
+                        tracksByObject: {},
+                    },
+                },
+            },
+        },
+    });
+    getCoreTicker().tick();
+    await project.ready;
+    const sheet = project.sheet('Scene');
+    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) }),
+    });
+    objectRuntime.registerSceneSheetObject('model:Foo', obj);
+    try {
+        const runtime = createAgentRuntime({
+            project,
+            sheet,
+            library: {},
+            getStudio: () => studio,
+            subscribeHistoric: () => () => { },
+        });
+        const registry = new AgentCommandRegistry();
+        registerKeyframeCommands(registry, runtime);
+        const stackBefore = undoStackOf().length;
+        await registry.execute('keyframes.set', { objectId: 'model:Foo', propPath: ['position', 'x'], at: 0.5, value: 7 }, ctx());
+        // 核心断言:第一次 set 之后,list 立即读到真实落库的关键帧
+        const listed = await registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['position', 'x'] }, ctx());
+        expect(listed).toEqual([{ position: 0.5, value: 7 }]);
+        expect(sheet.sequence.position).toBe(0.5);
+        // 两笔底层事务,但撤销栈只增一步(建轨 undoable:false)
+        expect(undoStackOf().length).toBe(stackBefore + 1);
+        // 一次 undo:关键帧被撤销,轨道保留(建轨事务不入栈)
+        studio.undo();
+        const afterUndo = await registry.execute('keyframes.list', { objectId: 'model:Foo', propPath: ['position', 'x'] }, ctx());
+        expect(afterUndo).toEqual([]);
+        const tracksP = privateAPI(project).pointers.historic
+            .sheetsById.Scene.sequence.tracksByObject.Foo;
+        const tracksOfFoo = val(tracksP);
+        expect(Object.keys(tracksOfFoo?.trackIdByPropPath ?? {})).toEqual([
+            '["position","x"]',
+        ]);
+    }
+    finally {
+        objectRuntime.unregisterSceneSheetObject('model:Foo', obj);
+    }
+}, 20000);

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

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

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

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