@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/jobs.test.js

@@ -0,0 +1,281 @@
+import { AgentJobManager } from './jobs';
+import { AgentApiError } from './errors';
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+test('start publishes a running snapshot and update reaches subscribers', async () => {
+    const manager = new AgentJobManager();
+    const received = [];
+    const unsubscribe = manager.subscribe((snapshot) => {
+        received.push(snapshot);
+    });
+    const gate = deferred();
+    const handle = manager.start({
+        kind: 'test.job',
+        cancelable: true,
+        execute: async ({ update }) => {
+            await Promise.resolve();
+            update({ progress: 0.5, phase: 'committed' });
+            return gate.promise;
+        },
+    });
+    const immediate = manager.get(handle.jobId);
+    expect(['pending', 'running']).toContain(immediate.state);
+    expect(immediate.phase).toBe('accepted');
+    expect(immediate.cancelable).toBe(true);
+    expect(immediate.jobId).toBe(handle.jobId);
+    expect(Object.isFrozen(immediate)).toBe(true);
+    expect(received[0]).toMatchObject({ state: 'running', progress: 0 });
+    // execute 体内的 update 在微任务后到达
+    for (let i = 0; i < 10 && received.length < 2; i += 1) {
+        await Promise.resolve();
+    }
+    expect(received.length).toBeGreaterThanOrEqual(2);
+    expect(received[1]).toMatchObject({ progress: 0.5, phase: 'committed' });
+    expect(received[1]).not.toBe(received[0]);
+    gate.resolve('ok');
+    const final = await handle.done;
+    expect(final).toMatchObject({
+        state: 'succeeded',
+        progress: 1,
+        result: 'ok',
+    });
+    expect(manager.get(handle.jobId)).toMatchObject({
+        state: 'succeeded',
+        result: 'ok',
+    });
+    unsubscribe();
+});
+test('snapshots are immutable copies that never mutate in place', async () => {
+    const manager = new AgentJobManager();
+    const seen = [];
+    manager.subscribe((snapshot) => {
+        seen.push({ progress: snapshot.progress });
+    });
+    const handle = manager.start({
+        kind: 'test.immutable',
+        cancelable: false,
+        execute: async ({ update }) => {
+            update({ progress: 0.5 });
+            return 'done';
+        },
+    });
+    await handle.done;
+    expect(seen.map((s) => s.progress)).toEqual([0, 0.5, 1]);
+    const final = manager.get(handle.jobId);
+    expect(Object.isFrozen(final)).toBe(true);
+});
+test('cancel aborts the signal and maps the job to cancelled', async () => {
+    const manager = new AgentJobManager();
+    const gate = deferred();
+    let seenSignal;
+    const handle = manager.start({
+        kind: 'test.cancelable',
+        cancelable: true,
+        execute: ({ signal }) => {
+            seenSignal = signal;
+            return gate.promise;
+        },
+    });
+    manager.cancel(handle.jobId);
+    expect(seenSignal?.aborted).toBe(true);
+    expect(manager.get(handle.jobId)).toMatchObject({ state: 'cancelled' });
+    // 取消后 execute 晚到的 resolve 不得覆盖终态
+    gate.resolve('late');
+    const final = await handle.done;
+    expect(final).toMatchObject({ state: 'cancelled' });
+});
+test('cancel on a non-cancelable job throws JOB_NOT_CANCELABLE', () => {
+    const manager = new AgentJobManager();
+    const handle = manager.start({
+        kind: 'test.locked',
+        cancelable: false,
+        execute: () => new Promise(() => { }),
+    });
+    try {
+        manager.cancel(handle.jobId);
+        throw new Error('Expected JOB_NOT_CANCELABLE');
+    }
+    catch (error) {
+        expect(error).toBeInstanceOf(AgentApiError);
+        expect(error).toMatchObject({ code: 'JOB_NOT_CANCELABLE' });
+    }
+});
+test('cancel or get on an unknown id throws JOB_NOT_FOUND', () => {
+    const manager = new AgentJobManager();
+    for (const fn of [
+        () => manager.cancel('job-missing'),
+        () => manager.get('job-missing'),
+    ]) {
+        try {
+            fn();
+            throw new Error('Expected JOB_NOT_FOUND');
+        }
+        catch (error) {
+            expect(error).toMatchObject({ code: 'JOB_NOT_FOUND' });
+        }
+    }
+});
+test('cancel on a finished job throws INVALID_STATE', async () => {
+    const manager = new AgentJobManager();
+    const handle = manager.start({
+        kind: 'test.done',
+        cancelable: true,
+        execute: async () => 'ok',
+    });
+    await handle.done;
+    try {
+        manager.cancel(handle.jobId);
+        throw new Error('Expected INVALID_STATE');
+    }
+    catch (error) {
+        expect(error).toMatchObject({ code: 'INVALID_STATE' });
+    }
+});
+test('failure maps to a failed snapshot with a normalized error', async () => {
+    const manager = new AgentJobManager();
+    const handle = manager.start({
+        kind: 'test.fail',
+        cancelable: false,
+        execute: async () => {
+            throw new Error('boom');
+        },
+    });
+    const final = await handle.done;
+    expect(final.state).toBe('failed');
+    expect(final.result).toBeUndefined();
+    expect(final.error).toMatchObject({
+        code: 'INTERNAL_ERROR',
+        message: 'boom',
+        retryable: false,
+    });
+    expect(manager.get(handle.jobId)).toMatchObject({ state: 'failed' });
+});
+test('structured AgentApiError failures keep their code in the snapshot', async () => {
+    const manager = new AgentJobManager();
+    const handle = manager.start({
+        kind: 'test.domain-fail',
+        cancelable: false,
+        execute: async () => {
+            throw new AgentApiError('RESOURCE_LOAD_FAILED', '模型加载失败', {
+                retryable: true,
+                details: { assetId: 'a1' },
+            });
+        },
+    });
+    const final = await handle.done;
+    expect(final).toMatchObject({
+        state: 'failed',
+        error: {
+            code: 'RESOURCE_LOAD_FAILED',
+            retryable: true,
+            details: { assetId: 'a1' },
+        },
+    });
+});
+test('JOB_CANCELLED rejection maps to cancelled (with error code), not failed', async () => {
+    const manager = new AgentJobManager();
+    const handle = manager.start({
+        kind: 'test.user-abort',
+        cancelable: true,
+        execute: async () => {
+            // 用户侧中止(如视频导出 Esc/开录相机被删):非 jobs.cancel 路径,
+            // execute 以 JOB_CANCELLED 拒绝,终态应为 cancelled 而非 failed
+            throw new AgentApiError('JOB_CANCELLED', '视频导出被中止');
+        },
+    });
+    const final = await handle.done;
+    expect(final.state).toBe('cancelled');
+    expect(final.error).toMatchObject({ code: 'JOB_CANCELLED' });
+    expect(manager.get(handle.jobId)).toMatchObject({ state: 'cancelled' });
+    // 已 cancelled 的任务不可再 cancel
+    try {
+        manager.cancel(handle.jobId);
+        throw new Error('Expected INVALID_STATE');
+    }
+    catch (error) {
+        expect(error).toMatchObject({ code: 'INVALID_STATE' });
+    }
+});
+test('falls back to counter-based ids when crypto.randomUUID is unavailable', async () => {
+    const globals = globalThis;
+    const original = globals.crypto?.randomUUID;
+    if (globals.crypto) {
+        globals.crypto.randomUUID = undefined;
+    }
+    try {
+        const manager = new AgentJobManager();
+        const handle = manager.start({
+            kind: 'test.fallback',
+            cancelable: true,
+            execute: async () => 'ok',
+        });
+        expect(handle.jobId).toMatch(/^job-\d+-\d+$/);
+        await handle.done;
+    }
+    finally {
+        if (globals.crypto && original) {
+            globals.crypto.randomUUID = original;
+        }
+    }
+});
+test('unsubscribe stops notifications', async () => {
+    const manager = new AgentJobManager();
+    let calls = 0;
+    const unsubscribe = manager.subscribe(() => {
+        calls += 1;
+    });
+    const handle = manager.start({
+        kind: 'test.unsub',
+        cancelable: false,
+        execute: async () => 'ok',
+    });
+    await handle.done;
+    expect(calls).toBeGreaterThan(0);
+    const before = calls;
+    unsubscribe();
+    manager.start({
+        kind: 'test.unsub2',
+        cancelable: false,
+        execute: async () => 'ok',
+    });
+    await Promise.resolve();
+    expect(calls).toBe(before);
+});
+test('a throwing subscriber neither corrupts job state nor blocks broadcast', async () => {
+    const manager = new AgentJobManager();
+    const received = [];
+    manager.subscribe(() => {
+        throw new Error('subscriber boom');
+    });
+    manager.subscribe((snapshot) => {
+        received.push(`${snapshot.state}:${snapshot.progress}`);
+    });
+    const handle = manager.start({
+        kind: 'test.throwing-subscriber',
+        cancelable: true,
+        execute: async ({ update }) => {
+            update({ progress: 0.5 });
+            return 'ok';
+        },
+    });
+    // 订阅者抛错不得被 start 的 catch 误判为任务失败
+    const final = await handle.done;
+    expect(final).toMatchObject({ state: 'succeeded', progress: 1, result: 'ok' });
+    // 抛错订阅者之后的订阅者仍收到每一次广播
+    expect(received).toEqual(['running:0', 'running:0.5', 'succeeded:1']);
+    // cancel 路径同样隔离订阅者异常
+    const cancelable = manager.start({
+        kind: 'test.throwing-subscriber-cancel',
+        cancelable: true,
+        execute: () => new Promise(() => { }),
+    });
+    expect(() => manager.cancel(cancelable.jobId)).not.toThrow();
+    expect(manager.get(cancelable.jobId)).toMatchObject({ state: 'cancelled' });
+});

package/dist/agent/keyframeTracks.d.ts

@@ -0,0 +1,57 @@
+import type { ISheet, ISheetObject } from '@dreamerbird/core';
+import type { $IntentionalAny } from '@dreamerbird/core/types/public';
+/** 单帧摘要:list 的输出元素(不暴露内部 id) */
+export type KeyframeInfo = {
+    position: number;
+    value: unknown;
+};
+/** move/delete 的源帧定位结果:轨道 id + 帧 id */
+export type KeyframeTarget = {
+    trackId: string;
+    keyframeId: string;
+};
+/** 指定简单叶子的全部关键帧(位置升序),未建轨返回空数组 */
+export declare function listKeyframes(sheet: ISheet, obj: ISheetObject<$IntentionalAny>, propPath: string[]): KeyframeInfo[];
+/**
+ * 定位指定位置(调用方已按 snap 规则处理好)的关键帧;无轨道或该位置
+ * 无帧返回 undefined。位置为精确相等:轨道上的帧位置恒为网格吸附值,
+ * 网格外的查询位置必然落空。
+ */
+export declare function findKeyframeAt(sheet: ISheet, obj: ISheetObject<$IntentionalAny>, propPath: string[], position: number): KeyframeTarget | undefined;
+/**
+ * 写关键帧:先把播放头定位到 position(吸附由命令层按 snap 完成;
+ * 事务内 set 的轨道感知写帧依赖播放头位置,core 会先对 position 做
+ * 一次网格吸附),再分两档写值:
+ *
+ *   - 已建轨:单个可撤销事务 set(pointer, value);
+ *   - 首次建轨:先以 undoable:false 的事务 setPrimitivePropAsSequenced
+ *     建轨(轨道落进已提交 state),再以第二个可撤销事务 set 写首帧——
+ *     事务内 set 的轨道检测只读已提交 track map,看不到同事务新建的
+ *     轨道(trackId 随机生成,同 poseTrack.writePoseKeyframe 注释的
+ *     已知限制),所以首帧必须等轨道提交后才能落成关键帧;建轨事务
+ *     不入撤销栈,整个 keyframes.set 对撤销历史只呈现一步。
+ */
+export declare function setKeyframe(sheet: ISheet, obj: ISheetObject<$IntentionalAny>, propPath: string[], args: {
+    position: number;
+    value: unknown;
+    sequenced: boolean;
+}): void;
+/**
+ * 移动关键帧:transformKeyframes 适配(参数形状同 AggregateKeyframeConnector
+ * 拖拽),translate 为 from/to 差值,scale 恒 1、origin 恒 0;目标位置由
+ * snappingFunction(closestGridPosition)落网格。源帧由命令层经
+ * findKeyframeAt 先行校验。
+ */
+export declare function moveKeyframe(sheet: ISheet, obj: ISheetObject<$IntentionalAny>, target: KeyframeTarget, args: {
+    from: number;
+    to: number;
+}): void;
+/**
+ * 删除指定位置的关键帧:播放头定位到 position 后 unset(pointer)——
+ * core 的 unset 在 positionSnappedToGrid 处落刀;只删帧,绝不
+ * unsequenceProp(轨道保留)。源帧由命令层经 findKeyframeAt 先行校验。
+ */
+export declare function deleteKeyframe(sheet: ISheet, obj: ISheetObject<$IntentionalAny>, propPath: string[], args: {
+    position: number;
+}): void;
+//# sourceMappingURL=keyframeTracks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyframeTracks.d.ts","sourceRoot":"","sources":["../../src/agent/keyframeTracks.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAC,MAAM,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,gCAAgC,CAAA;AAMvC,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAC,CAAA;AAE7D,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAAA;AAuClE,kCAAkC;AAClC,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,EAAE,GACjB,YAAY,EAAE,CAIhB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,MAAM,GACf,cAAc,GAAG,SAAS,CAQ5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAC,GAC3D,IAAI,CAmBN;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,GAC/B,IAAI,CAcN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GACvB,IAAI,CAON"}

package/dist/agent/keyframeTracks.js

@@ -0,0 +1,127 @@
+/**
+ * 关键帧轨道适配(2026-10-17,Task 7):keyframes.* 命令的唯一 core/Studio
+ * 访问点,命令层不直接触碰 Studio state。集中三件事:
+ *
+ *   1. track map 读取:内部 SheetObject template 的
+ *      getMapOfValidSequenceTracks_forStudio(与 poseTrack.getTrackIdForProp、
+ *      useEditingToolsForSimpleProp 同一数据源)+ sheet.sequence.getKeyframes
+ *      取帧 id/位置;
+ *   2. 播放头定位:写 sequence.position(core 语义,先 pause + clamp);
+ *   3. 事务写入:内部 Studio(`@dreamerbird/studio/getStudio`,与
+ *      TransportBar/CameraPath 同路径)的 transaction,api 携带 set/unset
+ *      与 stateEditors;transformKeyframes 的参数形状抽自
+ *      AggregateKeyframeConnector.tsx:167-186(keyframeIds + translate +
+ *      scale:1 + origin:0 + snappingFunction=sequence.closestGridPosition)。
+ *
+ * 事务回调同步执行,不跨 await;Studio 未初始化抛 SCENE_UNAVAILABLE。
+ */
+import { getPointerParts } from '@dreamerbird/dataverse';
+import getStudio from '@dreamerbird/studio/getStudio';
+import getDeep from '../getDeep';
+import { AgentApiError } from './errors';
+import { getSimplePropPointer } from './propAccess';
+function requireStudio() {
+    const studio = getStudio();
+    if (!studio) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法操作关键帧');
+    }
+    return studio;
+}
+function leafPointer(obj, propPath) {
+    return getSimplePropPointer(obj, propPath.join('.'));
+}
+/** 叶子路径的轨道 id(未建轨返回 undefined);数据源同 getTrackIdForProp */
+function getTrackIdForPath(pointer, propPath) {
+    const { root } = getPointerParts(pointer);
+    const tree = root.template
+        .getMapOfValidSequenceTracks_forStudio()
+        .getValue();
+    const trackId = getDeep(tree, propPath);
+    return typeof trackId === 'string' ? trackId : undefined;
+}
+/** 指定简单叶子的全部关键帧(位置升序),未建轨返回空数组 */
+export function listKeyframes(sheet, obj, propPath) {
+    return sheet.sequence
+        .getKeyframes(leafPointer(obj, propPath))
+        .map((kf) => ({ position: kf.position, value: kf.value }));
+}
+/**
+ * 定位指定位置(调用方已按 snap 规则处理好)的关键帧;无轨道或该位置
+ * 无帧返回 undefined。位置为精确相等:轨道上的帧位置恒为网格吸附值,
+ * 网格外的查询位置必然落空。
+ */
+export function findKeyframeAt(sheet, obj, propPath, position) {
+    const pointer = leafPointer(obj, propPath);
+    const trackId = getTrackIdForPath(pointer, propPath);
+    if (!trackId)
+        return undefined;
+    const keyframe = sheet.sequence
+        .getKeyframes(pointer)
+        .find((kf) => kf.position === position);
+    return keyframe ? { trackId, keyframeId: keyframe.id } : undefined;
+}
+/**
+ * 写关键帧:先把播放头定位到 position(吸附由命令层按 snap 完成;
+ * 事务内 set 的轨道感知写帧依赖播放头位置,core 会先对 position 做
+ * 一次网格吸附),再分两档写值:
+ *
+ *   - 已建轨:单个可撤销事务 set(pointer, value);
+ *   - 首次建轨:先以 undoable:false 的事务 setPrimitivePropAsSequenced
+ *     建轨(轨道落进已提交 state),再以第二个可撤销事务 set 写首帧——
+ *     事务内 set 的轨道检测只读已提交 track map,看不到同事务新建的
+ *     轨道(trackId 随机生成,同 poseTrack.writePoseKeyframe 注释的
+ *     已知限制),所以首帧必须等轨道提交后才能落成关键帧;建轨事务
+ *     不入撤销栈,整个 keyframes.set 对撤销历史只呈现一步。
+ */
+export function setKeyframe(sheet, obj, propPath, args) {
+    const studio = requireStudio();
+    const pointer = leafPointer(obj, propPath);
+    sheet.sequence.position = args.position;
+    if (!args.sequenced) {
+        // 建轨:undoable:false,提交生效但不占撤销栈(同 scrub.commit(false))
+        studio.transaction(({ stateEditors }) => {
+            const { root, path } = getPointerParts(pointer);
+            stateEditors.coreByProject.historic.sheetsById.sequence.setPrimitivePropAsSequenced({
+                ...root.address,
+                pathToProp: path,
+            });
+        }, false);
+    }
+    studio.transaction(({ set }) => {
+        set(pointer, args.value);
+    });
+}
+/**
+ * 移动关键帧:transformKeyframes 适配(参数形状同 AggregateKeyframeConnector
+ * 拖拽),translate 为 from/to 差值,scale 恒 1、origin 恒 0;目标位置由
+ * snappingFunction(closestGridPosition)落网格。源帧由命令层经
+ * findKeyframeAt 先行校验。
+ */
+export function moveKeyframe(sheet, obj, target, args) {
+    const studio = requireStudio();
+    studio.transaction(({ stateEditors }) => {
+        stateEditors.coreByProject.historic.sheetsById.sequence.transformKeyframes({
+            ...obj.address,
+            // id 跨适配层边界按不透明字符串传递,此处回到 core 的名义类型
+            trackId: target.trackId,
+            keyframeIds: [target.keyframeId],
+            translate: args.to - args.from,
+            scale: 1,
+            origin: 0,
+            snappingFunction: sheet.sequence.closestGridPosition,
+        });
+    });
+}
+/**
+ * 删除指定位置的关键帧:播放头定位到 position 后 unset(pointer)——
+ * core 的 unset 在 positionSnappedToGrid 处落刀;只删帧,绝不
+ * unsequenceProp(轨道保留)。源帧由命令层经 findKeyframeAt 先行校验。
+ */
+export function deleteKeyframe(sheet, obj, propPath, args) {
+    const studio = requireStudio();
+    const pointer = leafPointer(obj, propPath);
+    sheet.sequence.position = args.position;
+    studio.transaction(({ unset }) => {
+        unset(pointer);
+    });
+}

package/dist/agent/objectIds.d.ts

@@ -0,0 +1,7 @@
+import type { SceneObjectId, SceneObjectKind } from './types';
+export declare function formatSceneObjectId(kind: SceneObjectKind, key: string): SceneObjectId;
+export declare function parseSceneObjectId(id: string): {
+    kind: SceneObjectKind;
+    key: string;
+};
+//# sourceMappingURL=objectIds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objectIds.d.ts","sourceRoot":"","sources":["../../src/agent/objectIds.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,SAAS,CAAA;AAI3D,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,MAAM,GACV,aAAa,CAGf;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG;IAC9C,IAAI,EAAE,eAAe,CAAA;IACrB,GAAG,EAAE,MAAM,CAAA;CACZ,CAQA"}

package/dist/agent/objectIds.js

@@ -0,0 +1,20 @@
+/**
+ * 带类型场景对象 ID(spec 8.4):`model:` / `camera:` / `anchor:` / `path:`
+ * 前缀 + key。key 内可含额外冒号,解析只按第一个冒号分隔。
+ */
+import { AgentApiError } from './errors';
+const kinds = new Set(['model', 'camera', 'anchor', 'path']);
+export function formatSceneObjectId(kind, key) {
+    if (!key)
+        throw new AgentApiError('INVALID_ARGUMENT', '对象 key 不能为空');
+    return `${kind}:${key}`;
+}
+export function parseSceneObjectId(id) {
+    const separator = id.indexOf(':');
+    const kind = separator > 0 ? id.slice(0, separator) : '';
+    const key = separator > 0 ? id.slice(separator + 1) : '';
+    if (!kinds.has(kind) || !key) {
+        throw new AgentApiError('INVALID_ID_KIND', `无效场景对象 ID: ${id}`);
+    }
+    return { kind: kind, key };
+}

package/dist/agent/objectIds.test.d.ts

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

package/dist/agent/objectIds.test.d.ts.map

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

package/dist/agent/objectIds.test.js

@@ -0,0 +1,10 @@
+import { formatSceneObjectId, parseSceneObjectId } from './objectIds';
+import { AgentApiError } from './errors';
+test('round trips typed ids and preserves additional colons in keys', () => {
+    const id = formatSceneObjectId('model', 'Rig:Left');
+    expect(id).toBe('model:Rig:Left');
+    expect(parseSceneObjectId(id)).toEqual({ kind: 'model', key: 'Rig:Left' });
+});
+test.each(['unknown:x', 'model:', 'model'])('rejects %s', (value) => {
+    expect(() => parseSceneObjectId(value)).toThrow(AgentApiError);
+});

package/dist/agent/objectResolver.d.ts

@@ -0,0 +1,34 @@
+import type { ISheet, ISheetObject } from '@dreamerbird/core';
+import type { SceneObjectId, SceneObjectKind } from './types';
+/** 场景对象摘要(spec 8.4/9):带类型 ID + 当前求值属性 + 挂载状态 */
+export type SceneObjectSummary = {
+    id: SceneObjectId;
+    kind: SceneObjectKind;
+    key: string;
+    /** 已挂载:SheetObject 当前求值属性的深拷贝;未挂载:null */
+    props: Record<string, unknown> | null;
+    /** 运行时 SheetObject 已登记(资源加载状态由领域 handler 另行上报) */
+    mounted: boolean;
+};
+/** 场景快照:revision 与对象清单(无副作用) */
+export type SceneSnapshot = {
+    revision: number;
+    objects: SceneObjectSummary[];
+};
+/** 某类业务对象的全量 key;注册表未创建时为空(不创建) */
+export declare function listSceneObjectKeys(sheet: ISheet, kind: SceneObjectKind): string[];
+/** 全场景对象清单(无副作用) */
+export declare function listSceneObjects(sheet: ISheet): SceneObjectSummary[];
+/**
+ * 单个对象摘要。ID 前缀非法抛 INVALID_ID_KIND;注册表里没有抛
+ * OBJECT_NOT_FOUND(details 含 objectId 和 kind);有条目但未挂载返回
+ * props:null, mounted:false。
+ */
+export declare function getSceneObjectSummary(sheet: ISheet, objectId: string): SceneObjectSummary;
+/**
+ * 解析业务 ID 到当前挂载的 SheetObject(未挂载返回 undefined)。
+ * expectedKind 用于领域命令的类型约束:类型不匹配抛 INVALID_ID_KIND
+ * (spec 8.4:解析时同时校验类型和存在性)。
+ */
+export declare function resolveSceneSheetObject(sheet: ISheet, objectId: string, expectedKind?: SceneObjectKind): ISheetObject<any> | undefined;
+//# sourceMappingURL=objectResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objectResolver.d.ts","sourceRoot":"","sources":["../../src/agent/objectResolver.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,MAAM,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAQ3D,OAAO,KAAK,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,SAAS,CAAA;AAE3D,gDAAgD;AAChD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,aAAa,CAAA;IACjB,IAAI,EAAE,eAAe,CAAA;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACrC,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,gCAAgC;AAChC,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,kBAAkB,EAAE,CAAA;CAC9B,CAAA;AAqDD,mCAAmC;AACnC,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,eAAe,GACpB,MAAM,EAAE,CAIV;AAmBD,oBAAoB;AACpB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,kBAAkB,CAQpB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,eAAe,GAC7B,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAe/B"}

package/dist/agent/objectResolver.js

@@ -0,0 +1,112 @@
+/**
+ * Agent 场景对象 resolver(2026-10-17,Task 4):无副作用是核心契约。
+ *
+ * 存在性底账 = 四个业务注册表(Placements/Cameras/Anchors/Paths),
+ * 只用 privateAPI(sheet).getObject(registryKey) 探测 —— 注册表对象
+ * 不存在时按空清单算,绝不创建;也绝不调用 sheet.object / getPathMeta /
+ * readPathPoints(它们会顺手创建对象)。
+ *
+ * 业务 ID 的 key 分别来自 placement key、cameraKey、anchorKey、pathKey,
+ * 但不假定这些 key 能绕过运行时直接构造 SheetObject:运行时对象一律经
+ * objectRuntime 登记读取。注册表有条目但运行时未挂载时返回
+ * props:null, mounted:false,而不是误报 OBJECT_NOT_FOUND
+ * (后续写命令对此返回 INVALID_STATE)。
+ */
+import { val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { ANCHORS_REGISTRY_KEY, parseAnchorKeys } from '../anchorsRegistry';
+import { CAMERAS_REGISTRY_KEY, parseCameraEntries } from '../cameraRegistry';
+import { PATHS_REGISTRY_KEY, parsePathEntries } from '../pathRegistry';
+import { PLACEMENTS_REGISTRY_KEY, readRegistry } from '../PlacementManager';
+import { AgentApiError } from './errors';
+import { formatSceneObjectId, parseSceneObjectId } from './objectIds';
+import { getSceneSheetObject } from './runtime/objectRuntime';
+const sources = [
+    {
+        kind: 'model',
+        registryKey: PLACEMENTS_REGISTRY_KEY,
+        keysFrom: (registry) => readRegistry(registry).map((entry) => entry.key),
+    },
+    {
+        kind: 'camera',
+        registryKey: CAMERAS_REGISTRY_KEY,
+        keysFrom: (registry) => parseCameraEntries(val(registry.props.list)).map((entry) => entry.cameraKey),
+    },
+    {
+        kind: 'anchor',
+        registryKey: ANCHORS_REGISTRY_KEY,
+        keysFrom: (registry) => parseAnchorKeys(val(registry.props.list)),
+    },
+    {
+        kind: 'path',
+        registryKey: PATHS_REGISTRY_KEY,
+        keysFrom: (registry) => parsePathEntries(val(registry.props.list)).map((entry) => entry.pathKey),
+    },
+];
+/**
+ * 只探测不创建:内部对象表里没有就返回 undefined。
+ * getObject 返回的是内部 SheetObject,经 publicApi 拿公开门面再读 props。
+ */
+function peekRegistry(sheet, registryKey) {
+    const internal = privateAPI(sheet).getObject(registryKey);
+    return (internal?.publicApi ?? undefined);
+}
+function sourceFor(kind) {
+    return sources.find((source) => source.kind === kind);
+}
+/** 某类业务对象的全量 key;注册表未创建时为空(不创建) */
+export function listSceneObjectKeys(sheet, kind) {
+    const source = sourceFor(kind);
+    const registry = peekRegistry(sheet, source.registryKey);
+    return registry ? source.keysFrom(registry) : [];
+}
+/** theatre 的值层保证可序列化,JSON 往返即深拷贝(防调用方改返回值污染场景) */
+function deepCopyProps(value) {
+    return JSON.parse(JSON.stringify(value ?? {}));
+}
+function summarize(kind, key) {
+    const id = formatSceneObjectId(kind, key);
+    const obj = getSceneSheetObject(id);
+    return {
+        id,
+        kind,
+        key,
+        props: obj ? deepCopyProps(obj.value) : null,
+        mounted: Boolean(obj),
+    };
+}
+/** 全场景对象清单(无副作用) */
+export function listSceneObjects(sheet) {
+    return sources.flatMap((source) => listSceneObjectKeys(sheet, source.kind).map((key) => summarize(source.kind, key)));
+}
+/**
+ * 单个对象摘要。ID 前缀非法抛 INVALID_ID_KIND;注册表里没有抛
+ * OBJECT_NOT_FOUND(details 含 objectId 和 kind);有条目但未挂载返回
+ * props:null, mounted:false。
+ */
+export function getSceneObjectSummary(sheet, objectId) {
+    const { kind, key } = parseSceneObjectId(objectId);
+    if (!listSceneObjectKeys(sheet, kind).includes(key)) {
+        throw new AgentApiError('OBJECT_NOT_FOUND', `场景对象不存在: ${objectId}`, {
+            details: { objectId, kind },
+        });
+    }
+    return summarize(kind, key);
+}
+/**
+ * 解析业务 ID 到当前挂载的 SheetObject(未挂载返回 undefined)。
+ * expectedKind 用于领域命令的类型约束:类型不匹配抛 INVALID_ID_KIND
+ * (spec 8.4:解析时同时校验类型和存在性)。
+ */
+export function resolveSceneSheetObject(sheet, objectId, expectedKind) {
+    const { kind, key } = parseSceneObjectId(objectId);
+    if (expectedKind && kind !== expectedKind) {
+        throw new AgentApiError('INVALID_ID_KIND', `对象 ${objectId} 的类型是 ${kind},此处需要 ${expectedKind}`, { details: { objectId, kind, expectedKind } });
+    }
+    if (!listSceneObjectKeys(sheet, kind).includes(key)) {
+        throw new AgentApiError('OBJECT_NOT_FOUND', `场景对象不存在: ${objectId}`, {
+            details: { objectId, kind },
+        });
+    }
+    return getSceneSheetObject(formatSceneObjectId(kind, key));
+}