@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,101 @@
+/**
+ * poses 命令(2026-10-17,Task 9):apply / applyCustom / clear / saveCurrent /
+ * setGesture + poses.session.start / commit / cancel。
+ *
+ * 静态语义(preflight ruling):apply / applyCustom / setGesture 只写未建轨
+ * 的静态值——props 经 setStaticProps(propAccess 的形状 + 建轨校验),已建轨
+ * 返回 INVALID_STATE,绝不顺手写关键帧;打帧由 keyframes.* 显式进行。
+ * poses.clear 是显式移除姿势轨的例外:单事务 stateEditors
+ * (unsequenceProp + unset 语义)仍保持一个撤销步骤,由
+ * poseTrack.clearPoseValue 实现,UI 清除按钮共用。
+ *
+ * saveCurrent 属资产域(undoable:none,spec 8.6.4):实例经 Scene Runtime
+ * 的 getModelPlacement handler 取得(不直接摸 React 闭包),入库流程与
+ * CameraScene 共用 poseMode/savePose.savePoseFromInstance。
+ *
+ * 会话命令(会话域,不用项目 revision 伪装并发):start 进会话并等
+ * PoseModeRig 经 poseSessionRuntime 登记 Rig 句柄(completion:mounted,
+ * 防御性清会话 = Rig 未挂载,拒绝 INVALID_STATE 不悬挂);commit/cancel
+ * 调用 Rig 登记的句柄,与 UI 的 Esc/双击空白同一提交路径。
+ *
+ * 校验顺序同 objects.update:对象(类型/存在/挂载)→ 参数 → 资产/兼容性 →
+ * 建轨预检 → expectedRevision → 事务。
+ */
+import type { Group } from 'three';
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId } from '../types';
+import type { PoseBones } from '../../poseMode/poseOverride';
+import type { PoseFrameMode } from '../../poseMode/poseFrame';
+import type { GestureSide } from '../../gestureProps';
+import type { PlacementEntry } from '../../PlacementManager';
+import type { PoseEntry } from '../../assetLibrary/types';
+declare module '../runtime' {
+    interface AgentSceneRuntimeHandlers {
+        /**
+         * 取已放置模型的运行时实例与放置条目(未挂载返回 undefined)。
+         * 生产由 CameraScene/PlacementManager 绑定(转发
+         * getPlacementInstanceForObject);poses.saveCurrent /
+         * poses.session.start / animations.apply 共用。
+         */
+        getModelPlacement(args: {
+            key: string;
+        }): {
+            entry: PlacementEntry;
+            instance: Group;
+        } | undefined;
+    }
+}
+/** 姿势门面(Task 15 由同名命令转发实现) */
+export type PosesApi = {
+    apply(args: {
+        objectId: string;
+        assetId: string;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    applyCustom(args: {
+        objectId: string;
+        bones: PoseBones;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    clear(args: {
+        objectId: string;
+        expectedRevision?: number;
+    }): Promise<{
+        cleared: boolean;
+        revision: number;
+    }>;
+    saveCurrent(args: {
+        objectId: string;
+        name?: string;
+    }): Promise<PoseEntry>;
+    setGesture(args: {
+        objectId: string;
+        side: GestureSide;
+        assetId: string | null;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+};
+/** 姿势会话门面(IK 摆姿势;需要已挂载 Rig) */
+export type PosesSessionApi = {
+    start(args: {
+        objectId: string;
+    }): Promise<{
+        objectId: SceneObjectId;
+        frame?: PoseFrameMode;
+    }>;
+    commit(): Promise<{
+        objectId: SceneObjectId;
+    }>;
+    cancel(): Promise<{
+        objectId: SceneObjectId;
+    }>;
+};
+export declare function registerPoseCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=poses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"poses.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/poses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,OAAO,CAAA;AAKhC,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAa,aAAa,EAAC,MAAM,UAAU,CAAA;AAavD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,6BAA6B,CAAA;AAE1D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAA;AAE3D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAA;AAGvD,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB;QACjC;;;;;WAKG;QACH,iBAAiB,CAAC,IAAI,EAAE;YACtB,GAAG,EAAE,MAAM,CAAA;SACZ,GAAG;YAAC,KAAK,EAAE,cAAc,CAAC;YAAC,QAAQ,EAAE,KAAK,CAAA;SAAC,GAAG,SAAS,CAAA;KACzD;CACF;AAED,8BAA8B;AAC9B,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,CAAC,IAAI,EAAE;QACV,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC/B,WAAW,CAAC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,KAAK,EAAE,SAAS,CAAA;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC/B,KAAK,CAAC,IAAI,EAAE;QACV,QAAQ,EAAE,MAAM,CAAA;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACjD,WAAW,CAAC,IAAI,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACxE,UAAU,CAAC,IAAI,EAAE;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,EAAE,WAAW,CAAA;QACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAChC,CAAA;AAED,+BAA+B;AAC/B,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,IAAI,EAAE;QACV,QAAQ,EAAE,MAAM,CAAA;KACjB,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,KAAK,CAAC,EAAE,aAAa,CAAA;KAAC,CAAC,CAAA;IAC7D,MAAM,IAAI,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAC,CAAC,CAAA;IAC5C,MAAM,IAAI,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAC,CAAC,CAAA;CAC7C,CAAA;AAiMD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CA+ZN"}

package/dist/agent/commands/poses.js

@@ -0,0 +1,500 @@
+import { AgentApiError } from '../errors';
+import { resolveSceneSheetObject } from '../objectResolver';
+import { formatSceneObjectId, parseSceneObjectId } from '../objectIds';
+import { assertStaticPropsWritable, setStaticProps } from '../propAccess';
+import { requireFiniteNumber, requireObject, requireString } from '../validation';
+import { getPoseSessionRig, whenPoseSessionRig, } from '../runtime/poseSessionRuntime';
+import { enterPoseSession, getPoseSession, getPoseSessionFrame, } from '../../poseMode/poseSession';
+import { clearPoseValue } from '../../poseMode/poseTrack';
+import { serializeCustomPose, serializeLibPose } from '../../poseMode/poseValue';
+import { savePoseFromInstance } from '../../poseMode/savePose';
+import { gestureEntryNameSide, isHandPoseEntry } from '../../gestureProps';
+import { mapLibraryError } from './assets';
+const objectIdProperty = {
+    type: 'string',
+    description: '带类型场景对象 ID(模型),如 model:Y Bot',
+};
+const expectedRevisionProperty = {
+    type: 'number',
+    description: '乐观并发:读取场景时的 revision',
+};
+const bonesSchema = {
+    type: 'object',
+    description: '骨骼快照:骨骼名 → {rotation?: [x,y,z,w] 四元数, position?: [x,y,z]}',
+    additionalProperties: {
+        type: 'object',
+        properties: {
+            rotation: { type: 'array', items: { type: 'number' } },
+            position: { type: 'array', items: { type: 'number' } },
+        },
+        additionalProperties: false,
+    },
+};
+const revisionOutput = {
+    type: 'object',
+    properties: { revision: { type: 'number' } },
+    required: ['revision'],
+};
+const poseEntryOutput = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        kind: { enum: ['pose'] },
+        name: { type: 'string' },
+        rig: { type: 'string' },
+        bones: bonesSchema,
+        createdAt: { type: 'number' },
+    },
+    required: ['id', 'kind', 'name', 'rig', 'bones', 'createdAt'],
+};
+function optionalExpectedRevision(value) {
+    if (value === undefined)
+        return undefined;
+    return requireFiniteNumber(value, 'expectedRevision');
+}
+/** 骨骼快照参数校验:非空表;每根骨至多 rotation[4]/position[3] 且有限 */
+function requireBones(value) {
+    const record = requireObject(value);
+    const names = Object.keys(record);
+    if (names.length === 0) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'bones 不能为空对象');
+    }
+    for (const name of names) {
+        const entry = requireObject(record[name]);
+        const keys = Object.keys(entry);
+        if (keys.some((k) => k !== 'rotation' && k !== 'position')) {
+            throw new AgentApiError('INVALID_ARGUMENT', `bones.${name} 只接受 rotation / position 字段`);
+        }
+        if (!('rotation' in entry) && !('position' in entry)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `bones.${name} 至少需要 rotation 或 position 之一`);
+        }
+        if ('rotation' in entry)
+            requireNumberTuple(entry.rotation, `bones.${name}.rotation`, 4);
+        if ('position' in entry)
+            requireNumberTuple(entry.position, `bones.${name}.position`, 3);
+    }
+    return record;
+}
+function requireNumberTuple(value, label, length) {
+    if (!Array.isArray(value) ||
+        value.length !== length ||
+        value.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是长度为 ${length} 的有限数字数组`);
+    }
+}
+function requireSide(value) {
+    if (value !== 'left' && value !== 'right') {
+        throw new AgentApiError('INVALID_ARGUMENT', 'side 必须是 left 或 right');
+    }
+    return value;
+}
+/** 解析模型对象:类型不符 INVALID_ID_KIND、不存在 OBJECT_NOT_FOUND、未挂载 INVALID_STATE */
+function resolveMountedModel(runtime, objectId) {
+    const sheetObject = resolveSceneSheetObject(runtime.sheet, objectId, 'model');
+    if (!sheetObject) {
+        throw new AgentApiError('INVALID_STATE', `对象未挂载,无法操作: ${objectId}`, { details: { objectId } });
+    }
+    return sheetObject;
+}
+/** 经 Scene Runtime 取模型的挂载实例与放置条目(handler 未绑定 SCENE_UNAVAILABLE) */
+function requireModelPlacement(runtime, objectId) {
+    const getModelPlacement = runtime.handlers.getModelPlacement;
+    if (!getModelPlacement) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Scene Runtime 未绑定 getModelPlacement,无法访问模型实例');
+    }
+    const { key } = parseSceneObjectId(objectId);
+    const placement = getModelPlacement({ key });
+    if (!placement) {
+        throw new AgentApiError('INVALID_STATE', `模型实例未挂载: ${objectId}`, {
+            details: { objectId },
+        });
+    }
+    return placement;
+}
+/** 取库姿势条目:不存在 ASSET_NOT_FOUND;非姿势 INVALID_ARGUMENT */
+async function requirePoseEntry(runtime, assetId) {
+    const entry = await runtime.library.getEntry(assetId);
+    if (!entry) {
+        throw new AgentApiError('ASSET_NOT_FOUND', `资产不存在: ${assetId}`, {
+            details: { assetId },
+        });
+    }
+    if (entry.kind !== 'pose') {
+        throw new AgentApiError('INVALID_ARGUMENT', `资产 ${assetId} 不是姿势(kind: ${entry.kind})`, { details: { assetId, kind: entry.kind } });
+    }
+    return entry;
+}
+/** 领域静态写入:建轨预检 → expectedRevision → 单事务写完(propAccess);revision 等一个 core tick 再读(F2) */
+async function writeStaticProp(runtime, sheetObject, props, expectedRevision) {
+    assertStaticPropsWritable(sheetObject, props);
+    if (expectedRevision !== undefined)
+        runtime.assertRevision(expectedRevision);
+    setStaticProps(sheetObject, props);
+    // historic 通知 tick 调度:等一个 tick,返回反映本次写入的 revision
+    return { revision: await runtime.nextRevision() };
+}
+export function registerPoseCommands(registry, runtime) {
+    registry.register({
+        name: 'poses.apply',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                assetId: { type: 'string', description: '库姿势条目 id' },
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'assetId'],
+            additionalProperties: false,
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'ASSET_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => {
+            const args = requireObject(value);
+            return {
+                objectId: requireString(args, 'objectId'),
+                assetId: requireString(args, 'assetId'),
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveMountedModel(runtime, args.objectId);
+            await requirePoseEntry(runtime, args.assetId);
+            return writeStaticProp(runtime, sheetObject, { pose: serializeLibPose(args.assetId) }, args.expectedRevision);
+        },
+    });
+    registry.register({
+        name: 'poses.applyCustom',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                bones: bonesSchema,
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'bones'],
+            additionalProperties: false,
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => {
+            const args = requireObject(value);
+            return {
+                objectId: requireString(args, 'objectId'),
+                bones: requireBones(args.bones),
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveMountedModel(runtime, args.objectId);
+            return writeStaticProp(runtime, sheetObject, { pose: serializeCustomPose(args.bones) }, args.expectedRevision);
+        },
+    });
+    registry.register({
+        name: 'poses.clear',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId'],
+            additionalProperties: false,
+        },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                cleared: {
+                    type: 'boolean',
+                    description: '是否确有轨道或静态值被清除(空姿势为 false)',
+                },
+                revision: { type: 'number' },
+            },
+            required: ['cleared', 'revision'],
+        },
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => {
+            const args = requireObject(value);
+            return {
+                objectId: requireString(args, 'objectId'),
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveMountedModel(runtime, args.objectId);
+            // 乐观并发先于任何副作用
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            // 显式移除姿势轨的例外:单事务 unsequenceProp + unset 语义
+            // (stateEditors 直写,一个撤销步骤);空姿势不开事务
+            const outcome = clearPoseValue(sheetObject);
+            if (outcome === 'unavailable') {
+                throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法清除姿势');
+            }
+            return {
+                cleared: outcome === 'cleared',
+                revision: await runtime.nextRevision(),
+            };
+        },
+    });
+    registry.register({
+        name: 'poses.saveCurrent',
+        kind: 'mutation',
+        stateDomain: 'asset',
+        undoable: 'none',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                name: {
+                    type: 'string',
+                    description: '姿势名称;缺省为 姿势-N(库姿势数 + 1)',
+                },
+            },
+            required: ['objectId'],
+            additionalProperties: false,
+        },
+        outputSchema: poseEntryOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'SCENE_UNAVAILABLE',
+            'STORAGE_ERROR',
+            'NETWORK_ERROR',
+            'INTERNAL_ERROR',
+        ],
+        validate: (value) => {
+            const args = requireObject(value);
+            let name;
+            if (args.name !== undefined) {
+                name = requireString(args, 'name').trim();
+                if (!name) {
+                    throw new AgentApiError('INVALID_ARGUMENT', 'name 不能是空白字符串');
+                }
+            }
+            return { objectId: requireString(args, 'objectId'), name };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            resolveMountedModel(runtime, args.objectId);
+            const placement = requireModelPlacement(runtime, args.objectId);
+            const library = runtime.library;
+            const name = args.name ?? `姿势-${(await library.listEntries('pose')).length + 1}`;
+            try {
+                const entry = await savePoseFromInstance({
+                    library,
+                    instance: placement.instance,
+                    libraryEntryId: placement.entry.libraryEntryId,
+                    name,
+                });
+                if (!entry) {
+                    throw new AgentApiError('INVALID_STATE', `静态骨架模型不能保存姿势: ${args.objectId}`, { details: { objectId: args.objectId } });
+                }
+                return entry;
+            }
+            catch (error) {
+                if (error instanceof AgentApiError)
+                    throw error;
+                throw mapLibraryError(error);
+            }
+        },
+    });
+    registry.register({
+        name: 'poses.setGesture',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                side: { enum: ['left', 'right'], description: '手势侧别' },
+                assetId: {
+                    type: 'string',
+                    description: '库手势条目 id;null 清除本侧手势',
+                },
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'side', 'assetId'],
+            additionalProperties: false,
+        },
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'ASSET_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => {
+            const args = requireObject(value);
+            const assetId = args.assetId;
+            if (assetId !== null && typeof assetId !== 'string') {
+                throw new AgentApiError('INVALID_ARGUMENT', 'assetId 必须是字符串或 null');
+            }
+            if (typeof assetId === 'string' && !assetId) {
+                throw new AgentApiError('INVALID_ARGUMENT', 'assetId 不能为空字符串');
+            }
+            return {
+                objectId: requireString(args, 'objectId'),
+                side: requireSide(args.side),
+                assetId: assetId,
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveMountedModel(runtime, args.objectId);
+            const prop = args.side === 'left' ? 'gestureL' : 'gestureR';
+            let value = '';
+            if (args.assetId !== null) {
+                const entry = await requirePoseEntry(runtime, args.assetId);
+                // 手势属性只收手势条目(纯手指骨),全身姿势拒绝
+                if (!isHandPoseEntry(entry)) {
+                    throw new AgentApiError('INVALID_ARGUMENT', `条目 ${args.assetId} 不是手势(含非手指骨)`, { details: { assetId: args.assetId } });
+                }
+                // 侧别校验:带「· 左手/· 右手」后缀的条目必须落在本侧;
+                // 无后缀 = 双手手势,两侧可用(与 buildGestureOptions 同规则)
+                const nameSide = gestureEntryNameSide(entry.name);
+                if (nameSide !== null && nameSide !== args.side) {
+                    throw new AgentApiError('INVALID_ARGUMENT', `手势条目侧别不符: ${entry.name} 不能用于 ${args.side} 侧`, { details: { assetId: args.assetId, side: args.side, nameSide } });
+                }
+                value = serializeLibPose(args.assetId);
+            }
+            return writeStaticProp(runtime, sheetObject, { [prop]: value }, args.expectedRevision);
+        },
+    });
+    // —— 姿势会话(IK 摆姿势;会话域,不用项目 revision)——
+    const sessionObjectOutput = {
+        type: 'object',
+        properties: {
+            objectId: { type: 'string', description: '会话所在模型的带类型 ID' },
+            frame: {
+                type: 'object',
+                description: '会话帧信息(帧上=编辑该帧 / 帧间=新建帧);仅 start 返回',
+            },
+        },
+        required: ['objectId'],
+    };
+    registry.register({
+        name: 'poses.session.start',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        completion: 'mounted',
+        inputSchema: {
+            type: 'object',
+            properties: { objectId: objectIdProperty },
+            required: ['objectId'],
+            additionalProperties: false,
+        },
+        outputSchema: sessionObjectOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => ({
+            objectId: requireString(requireObject(value), 'objectId'),
+        }),
+        execute: async (args) => {
+            runtime.assertActive();
+            resolveMountedModel(runtime, args.objectId);
+            // 模型实例必须已挂载,Rig 才挂得上
+            requireModelPlacement(runtime, args.objectId);
+            const { key } = parseSceneObjectId(args.objectId);
+            // 与 UI 同一入口:已在摆别的模型时先按退出流程提交旧会话
+            enterPoseSession(key);
+            // completion:mounted——等 PoseModeRig 登记 Rig 句柄;防御性清会话
+            // (无根骨/无装配表)时 waiter 以 INVALID_STATE 拒绝,不悬挂
+            await whenPoseSessionRig(key);
+            runtime.assertActive();
+            // Rig 登记在帧信息写入之后,此处 frame 可用;测试手工登记时缺省
+            const frame = getPoseSessionFrame() ?? undefined;
+            return { objectId: formatSceneObjectId('model', key), frame };
+        },
+    });
+    const registerSessionEndCommand = (name, pick) => {
+        registry.register({
+            name,
+            kind: 'mutation',
+            stateDomain: 'session',
+            // commit 在脏会话里写姿势帧(writePoseKeyframe 单个 scrub commit);
+            // cancel 不写项目状态
+            undoable: pick === 'commit' ? 'single-step' : 'none',
+            ...(pick === 'commit' ? { completion: 'committed' } : {}),
+            inputSchema: { type: 'object', additionalProperties: false },
+            outputSchema: sessionObjectOutput,
+            errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'INVALID_STATE'],
+            validate: (value) => value === undefined || value === null ? {} : requireObject(value),
+            execute: async () => {
+                runtime.assertActive();
+                const session = getPoseSession();
+                if (!session) {
+                    throw new AgentApiError('INVALID_STATE', '当前没有姿势会话');
+                }
+                const rig = getPoseSessionRig(session.key);
+                if (!rig) {
+                    throw new AgentApiError('INVALID_STATE', `姿势会话的 Rig 未挂载: ${session.key}`, { details: { key: session.key } });
+                }
+                // 先快照 key:句柄内部会清会话
+                const objectId = formatSceneObjectId('model', session.key);
+                rig[pick]();
+                return { objectId };
+            },
+        });
+    };
+    registerSessionEndCommand('poses.session.commit', 'commit');
+    registerSessionEndCommand('poses.session.cancel', 'cancel');
+}

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

@@ -0,0 +1,15 @@
+/**
+ * poses.clear 的真实 Studio 行为测试(2026-10-17,Task 9):
+ * 「单事务 unsequenceProp + unset」用 stateEditors 直改 historic 实现
+ * (绕开指针级 unset 读事务前轨道树的已知限制,CameraScene 2026-10-01
+ * 冒烟记录),必须验证:
+ *   1. 已建轨姿势:一次 clear 后轨道删除、值回默认、撤销栈只增一步,
+ *      undo 后轨道与值一并恢复;
+ *   2. 纯静态姿势:clear 后值清空、只增一步,undo 恢复;
+ *   3. 空姿势:不产生任何事务(栈长不变),返回 cleared:false。
+ *
+ * 与 poses.test.ts(假事务,验调用形状)互补:本文件用真实 Studio
+ * (同 keyframes.realStudio.test.ts 的引导方式)验端到端落库与撤销粒度。
+ */
+import '@dreamerbird/studio';
+//# sourceMappingURL=poses.realStudio.test.d.ts.map

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

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