@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/agent/bridgeFiles.test.js

@@ -0,0 +1,220 @@
+/*
+ * @jest-environment jsdom
+ */
+/**
+ * 桥接二进制适配(2026-10-19,Task 6,spec §10.2):
+ *
+ * - hydrate:`{file:{fileId,...}}` → GET `${httpUrl}/v1/files/<fileId>`
+ *   (Bearer token)→ File;401 → UNAUTHORIZED,404 → FILE_NOT_FOUND,
+ *   其余非 ok / fetch 拒绝(CORS/网络)→ NETWORK_ERROR;CORS 日志保留
+ *   httpUrl 与 location.origin,提示宿主加精确 origin(不建议 *),
+ *   token 绝不进日志;
+ * - dehydrate:succeeded 任务结果里的 Blob(VideoExportResult)→ POST
+ *   `${httpUrl}/v1/files`(X-File-Name encodeURIComponent、Content-Type、
+ *   Bearer)→ result 换成 {fileId,fileName,mimeType,size},不带 Blob;
+ *   上传失败 → 任务投影为 failed NETWORK_ERROR,绝不报告成功但缺文件。
+ */
+import { AgentApiError } from './errors';
+import { hydrateCommandArgs, dehydrateJobResult } from './bridgeFiles';
+const transport = {
+    httpUrl: 'http://127.0.0.1:43110',
+    token: 'secret-token',
+};
+/** fetch 替身形状(只需本套件用到的字段) */
+function fakeResponse(init) {
+    return {
+        ok: init.ok,
+        status: init.status,
+        arrayBuffer: init.arrayBuffer ?? (async () => new ArrayBuffer(0)),
+        json: init.json ?? (async () => ({})),
+        headers: { get: () => null },
+    };
+}
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+describe('hydrateCommandArgs', () => {
+    test('fileRef → 下载字节并构造 File(名称/类型/字节正确),带 Bearer token', async () => {
+        const bytes = new Uint8Array([1, 2, 3, 4]);
+        const fetchMock = jest.fn(async () => fakeResponse({
+            ok: true,
+            status: 200,
+            arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+        }));
+        const hydrated = (await hydrateCommandArgs({
+            file: {
+                fileId: 'f1',
+                fileName: 'Y Bot.glb',
+                mimeType: 'model/gltf-binary',
+            },
+        }, transport, fetchMock));
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe('http://127.0.0.1:43110/v1/files/f1');
+        expect(init.headers.Authorization).toBe('Bearer secret-token');
+        expect(hydrated.file).toBeInstanceOf(File);
+        expect(hydrated.file.name).toBe('Y Bot.glb');
+        expect(hydrated.file.type).toBe('model/gltf-binary');
+        expect(hydrated.file.size).toBe(4);
+        // jsdom 的 File 无 arrayBuffer():用 FileReader 读回字节
+        const readBack = await new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onload = () => resolve(new Uint8Array(reader.result));
+            reader.onerror = () => reject(reader.error);
+            reader.readAsArrayBuffer(hydrated.file);
+        });
+        expect(readBack).toEqual(bytes);
+    });
+    test('无 fileRef 的 args 原样返回(同引用),不发起 fetch', async () => {
+        const fetchMock = jest.fn();
+        const args = { objectId: 'model:M', props: { position: { x: 1, y: 0, z: 0 } } };
+        const result = await hydrateCommandArgs(args, transport, fetchMock);
+        expect(result).toBe(args);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    test('file 已是 File(JS 侧直呼)时不重新下载', async () => {
+        const fetchMock = jest.fn();
+        const file = new File([new Uint8Array([9])], 'm.glb', {
+            type: 'model/gltf-binary',
+        });
+        const args = { file };
+        const result = await hydrateCommandArgs(args, transport, fetchMock);
+        expect(result).toBe(args);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    test('401 → UNAUTHORIZED', async () => {
+        const fetchMock = jest.fn(async () => fakeResponse({ ok: false, status: 401 }));
+        const error = await hydrateCommandArgs({ file: { fileId: 'f1' } }, transport, fetchMock).catch((e) => e);
+        expect(error).toBeInstanceOf(AgentApiError);
+        expect(error.code).toBe('UNAUTHORIZED');
+    });
+    test('404 → FILE_NOT_FOUND', async () => {
+        const fetchMock = jest.fn(async () => fakeResponse({ ok: false, status: 404 }));
+        const error = await hydrateCommandArgs({ file: { fileId: 'missing' } }, transport, fetchMock).catch((e) => e);
+        expect(error).toBeInstanceOf(AgentApiError);
+        expect(error.code).toBe('FILE_NOT_FOUND');
+    });
+    test('其余非 ok(如 500)→ NETWORK_ERROR', async () => {
+        const fetchMock = jest.fn(async () => fakeResponse({ ok: false, status: 500 }));
+        const error = await hydrateCommandArgs({ file: { fileId: 'f1' } }, transport, fetchMock).catch((e) => e);
+        expect(error).toBeInstanceOf(AgentApiError);
+        expect(error.code).toBe('NETWORK_ERROR');
+    });
+    test('fetch 拒绝(CORS/网络)→ NETWORK_ERROR;日志保留 httpUrl 与 origin,不含 token', async () => {
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const fetchMock = jest
+            .fn()
+            .mockRejectedValue(new TypeError('Failed to fetch'));
+        const error = await hydrateCommandArgs({ file: { fileId: 'f1' } }, transport, fetchMock).catch((e) => e);
+        expect(error).toBeInstanceOf(AgentApiError);
+        expect(error.code).toBe('NETWORK_ERROR');
+        expect(error.retryable).toBe(true);
+        const logged = JSON.stringify(errorSpy.mock.calls);
+        expect(logged).toContain('http://127.0.0.1:43110');
+        expect(logged).toContain(location.origin);
+        expect(logged).toContain('corsOrigins');
+        expect(logged).not.toContain('secret-token');
+    });
+});
+describe('dehydrateJobResult', () => {
+    function videoSnapshot() {
+        return {
+            jobId: 'j1',
+            kind: 'exports.startVideo',
+            state: 'succeeded',
+            progress: 1,
+            phase: 'loaded',
+            cancelable: true,
+            result: {
+                blob: new Blob(['webm-bytes'], { type: 'video/webm' }),
+                fileName: '镜头 1.webm',
+                mimeType: 'video/webm',
+                size: 10,
+            },
+        };
+    }
+    test('Blob 结果 POST 到 /v1/files,result 换成 fileId 描述(不含 Blob)', async () => {
+        const snapshot = videoSnapshot();
+        const blob = snapshot.result.blob;
+        const fetchMock = jest.fn(async () => fakeResponse({
+            ok: true,
+            status: 201,
+            json: async () => ({
+                ok: true,
+                result: {
+                    fileId: 'f9',
+                    fileName: '镜头 1.webm',
+                    mimeType: 'video/webm',
+                    size: 10,
+                },
+            }),
+        }));
+        const projected = await dehydrateJobResult(snapshot, transport, fetchMock);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe('http://127.0.0.1:43110/v1/files');
+        expect(init.method).toBe('POST');
+        expect(init.headers['X-File-Name']).toBe(encodeURIComponent('镜头 1.webm'));
+        expect(init.headers['Content-Type']).toBe('video/webm');
+        expect(init.headers.Authorization).toBe('Bearer secret-token');
+        expect(init.body).toBe(blob);
+        expect(projected.state).toBe('succeeded');
+        expect(projected.result).toEqual({
+            fileId: 'f9',
+            fileName: '镜头 1.webm',
+            mimeType: 'video/webm',
+            size: 10,
+        });
+        expect(projected.result.blob).toBeUndefined();
+        // 原始快照不被改写
+        expect(snapshot.result.blob).toBe(blob);
+    });
+    test('上传失败 → 任务投影为 failed NETWORK_ERROR(绝不报告成功但缺文件)', async () => {
+        const fetchMock = jest.fn(async () => fakeResponse({ ok: false, status: 500 }));
+        const projected = await dehydrateJobResult(videoSnapshot(), transport, fetchMock);
+        expect(projected.state).toBe('failed');
+        expect(projected.error?.code).toBe('NETWORK_ERROR');
+        expect(projected.result).toBeUndefined();
+    });
+    test('上传 fetch 拒绝(CORS/网络)→ failed NETWORK_ERROR;日志不含 token', async () => {
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const fetchMock = jest
+            .fn()
+            .mockRejectedValue(new TypeError('Failed to fetch'));
+        const projected = await dehydrateJobResult(videoSnapshot(), transport, fetchMock);
+        expect(projected.state).toBe('failed');
+        expect(projected.error?.code).toBe('NETWORK_ERROR');
+        const logged = JSON.stringify(errorSpy.mock.calls);
+        expect(logged).toContain('http://127.0.0.1:43110');
+        expect(logged).not.toContain('secret-token');
+    });
+    test('非 Blob 结果原样返回(同引用),不发起 fetch', async () => {
+        const fetchMock = jest.fn();
+        const snapshot = {
+            jobId: 'j2',
+            kind: 'assets.importModel',
+            state: 'succeeded',
+            progress: 1,
+            phase: 'loaded',
+            cancelable: false,
+            result: { assetId: 'asset-1' },
+        };
+        const projected = await dehydrateJobResult(snapshot, transport, fetchMock);
+        expect(projected).toBe(snapshot);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    test('非 succeeded 状态不上传(同引用返回)', async () => {
+        const fetchMock = jest.fn();
+        const snapshot = {
+            jobId: 'j3',
+            kind: 'exports.startVideo',
+            state: 'running',
+            progress: 0.3,
+            phase: 'committed',
+            cancelable: true,
+        };
+        const projected = await dehydrateJobResult(snapshot, transport, fetchMock);
+        expect(projected).toBe(snapshot);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,43 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId, Vec3 } from '../types';
+declare module '../runtime' {
+    interface AgentSceneRuntimeHandlers {
+        /**
+         * 创建锚点(CameraScene 绑定,转发 addAnchorToRegistry):同步生成
+         * key、写注册表清单、stash 位置种子,立即返回;position 缺省时由
+         * CameraScene 按当前导演视角前方 5 单位计算(captureAnchorSeed)。
+         * 挂载完成经 cameraLifecycle.notifyAnchorReady 通知。
+         */
+        createAnchor(args: {
+            position?: Vec3;
+        }): {
+            key: string;
+        };
+    }
+}
+/** 锚点门面(Task 15 由同名命令转发实现) */
+export type AnchorsApi = {
+    create(args: {
+        position?: Vec3;
+        expectedRevision?: number;
+    }): Promise<{
+        objectId: SceneObjectId;
+        revision: number;
+    }>;
+    setParent(args: {
+        objectId: SceneObjectId;
+        parent: string;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    clearParent(args: {
+        objectId: SceneObjectId;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+};
+export declare function registerAnchorCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=anchors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/anchors.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAY5C,OAAO,KAAK,EAAa,aAAa,EAAE,IAAI,EAAC,MAAM,UAAU,CAAA;AAa7D,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB;QACjC;;;;;WAKG;QACH,YAAY,CAAC,IAAI,EAAE;YAAC,QAAQ,CAAC,EAAE,IAAI,CAAA;SAAC,GAAG;YAAC,GAAG,EAAE,MAAM,CAAA;SAAC,CAAA;KACrD;CACF;AAED,8BAA8B;AAC9B,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,IAAI,EAAE;QACX,QAAQ,CAAC,EAAE,IAAI,CAAA;QACf,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACxD,SAAS,CAAC,IAAI,EAAE;QACd,QAAQ,EAAE,aAAa,CAAA;QACvB,MAAM,EAAE,MAAM,CAAA;QACd,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,aAAa,CAAA;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAChC,CAAA;AAqLD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAgMN"}

package/dist/agent/commands/anchors.js

@@ -0,0 +1,331 @@
+/**
+ * anchors 命令(2026-10-17,Task 10):create / setParent / clearParent。
+ *
+ * create 执行顺序:assertActive → expectedRevision 乐观并发(先于任何
+ * 副作用)→ Scene Runtime createAnchor handler(未绑定
+ * SCENE_UNAVAILABLE;生产由 CameraScene 绑定,缺省位置由它按导演前方
+ * 5 单位计算,captureAnchorSeed)→ 创建挂载 waiter 并等 AnchorObject
+ * 的种子 layout effect 通知(completion:mounted;期间 dispose 优先
+ * 映射 API_DISPOSED,其余拒绝 INTERNAL_ERROR)→ resolver 复核注册表
+ * 与 SheetObject 双双可见(脱节 = INTERNAL_ERROR,不静默成功)。
+ *
+ * setParent / clearParent 是领域静态写入:parent 属 domainOwnedProps,
+ * 命令完成自身校验(目标类型/存在性/自身与成环)与建轨预检后,把
+ * parent 与世界/局部坐标定格折进同一事务写入(F1 修复,见
+ * writeAnchorParent;AnchorObject 看护 effect 的同值守卫随之跳过,
+ * 一步撤销);父级目标运行时对象未就绪(异步加载)抛 INVALID_STATE
+ * 可重试。刷新/撤销恢复既有绑定的挂载仍由既有 useFrame 重试循环兜底。
+ *
+ * 父级目标与 UI 下拉同集:anchor:<key>(排除自身与后代,成环
+ * INVALID_ARGUMENT)/ model:<key> / camera:<key> /
+ * bone:<placement>#<part>;空串归 clearParent。
+ */
+import { val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { AgentApiError } from '../errors';
+import { formatSceneObjectId } from '../objectIds';
+import { getSceneObjectSummary, listSceneObjectKeys, resolveSceneSheetObject, } from '../objectResolver';
+import { assertStaticPropsWritable, setStaticPropsWithFreeze, } from '../propAccess';
+import { createAnchorWaiter } from '../runtime/cameraLifecycle';
+import { requireFiniteNumber, requireObject, requireString, requireVec3, } from '../validation';
+import { isDescendantAnchor, parseTargetId, planAnchorParentFreeze, } from '../../aimTargets';
+const vec3Schema = {
+    type: 'object',
+    properties: {
+        x: { type: 'number' },
+        y: { type: 'number' },
+        z: { type: 'number' },
+    },
+    required: ['x', 'y', 'z'],
+    additionalProperties: false,
+};
+const expectedRevisionProperty = {
+    type: 'number',
+    description: '乐观并发:读取场景时的 revision',
+};
+const objectIdProperty = {
+    type: 'string',
+    description: '带类型场景对象 ID,anchor:<key>',
+};
+const createOutput = {
+    type: 'object',
+    properties: {
+        objectId: { type: 'string', description: '带类型场景对象 ID,anchor:<key>' },
+        revision: { type: 'number' },
+    },
+    required: ['objectId', 'revision'],
+};
+const revisionOutput = {
+    type: 'object',
+    properties: { revision: { type: 'number' } },
+    required: ['revision'],
+};
+function optionalExpectedRevision(value) {
+    return value === undefined
+        ? undefined
+        : requireFiniteNumber(value, 'expectedRevision');
+}
+/** 解析锚点对象:类型不符 INVALID_ID_KIND、不存在 OBJECT_NOT_FOUND、未挂载 INVALID_STATE */
+function resolveMountedAnchor(runtime, objectId) {
+    const sheetObject = resolveSceneSheetObject(runtime.sheet, objectId, 'anchor');
+    if (!sheetObject) {
+        throw new AgentApiError('INVALID_STATE', `锚点已登记但尚未挂载,无法操作: ${objectId}`, { details: { objectId } });
+    }
+    return sheetObject;
+}
+/** 注册表存在性底账(只探测不创建);缺失 OBJECT_NOT_FOUND */
+function assertRegistryHasKey(sheet, kind, key) {
+    if (!listSceneObjectKeys(sheet, kind).includes(key)) {
+        throw new AgentApiError('OBJECT_NOT_FOUND', `父级目标不存在: ${kind}:${key}`, { details: { objectId: formatSceneObjectId(kind, key), kind } });
+    }
+}
+/**
+ * 父级目标校验:类型/存在性/自身与成环。只校验不写 props。
+ * 成环检测与 UI 下拉(anchorParentOptionsFor)同一判定:
+ * isDescendantAnchor + 沿父链读持久 parent 值。
+ */
+function assertParentValid(sheet, selfKey, parent) {
+    const parsed = parseTargetId(parent);
+    if (!parsed) {
+        throw new AgentApiError('INVALID_ID_KIND', `无效父级目标 ID: ${parent}`, {
+            details: { parent },
+        });
+    }
+    switch (parsed.kind) {
+        case 'anchor': {
+            if (parsed.key === selfKey) {
+                throw new AgentApiError('INVALID_ARGUMENT', `锚点不能以自己为父级: ${parent}`, { details: { parent } });
+            }
+            assertRegistryHasKey(sheet, 'anchor', parsed.key);
+            // 沿父链读持久 parent(只探测不创建:sheet.object 会顺手建对象;
+            // getObject 返回内部对象,props 在 publicApi 上,须剥一层)
+            const parentOf = (key) => {
+                try {
+                    const internal = privateAPI(sheet).getObject(key);
+                    const obj = (internal?.publicApi ?? undefined);
+                    return obj ? val(obj.props.parent) ?? '' : '';
+                }
+                catch {
+                    return '';
+                }
+            };
+            if (isDescendantAnchor(selfKey, parsed.key, parentOf)) {
+                throw new AgentApiError('INVALID_ARGUMENT', `父级绑定成环: ${selfKey} → ${parsed.key}`, { details: { parent } });
+            }
+            return;
+        }
+        case 'model':
+            assertRegistryHasKey(sheet, 'model', parsed.key);
+            return;
+        case 'camera':
+            assertRegistryHasKey(sheet, 'camera', parsed.key);
+            return;
+        case 'bone':
+            assertRegistryHasKey(sheet, 'model', parsed.placementKey);
+            return;
+    }
+}
+/**
+ * 父级切换写入(2026-10-19,F1 修复):parent 与坐标定格折进同一事务。
+ *
+ * 原实现只写 parent,世界/局部换算由 AnchorObject 的看护 effect 在属性
+ * 变化后补一笔提交——属性一笔、定格一笔,两步撤销,undo 一次只回属性
+ * 不回定格,锚点跳变(撤销陷阱,同 removeAnchor 注释)。现在:同步算
+ * 定格(planAnchorParentFreeze,命令要求锚点已挂载,世界矩阵可解析),
+ * 事务内同写 parent+position,提交后立即换父(抢在包装器应用新
+ * position 与看护 effect 之前);看护的同值守卫看到 persisted==定格值
+ * 即跳过提交,全程一步撤销。
+ *
+ * 锚点网格未登记 / 父级目标运行时对象未就绪(异步加载)→ INVALID_STATE
+ * (可重试),不写半悬挂状态。
+ */
+async function writeAnchorParent(runtime, sheetObject, parent, expectedRevision) {
+    assertStaticPropsWritable(sheetObject, { parent });
+    if (expectedRevision !== undefined)
+        runtime.assertRevision(expectedRevision);
+    const { objectKey: selfKey } = sheetObject.address;
+    const freeze = planAnchorParentFreeze(selfKey, parent);
+    if (!freeze) {
+        throw new AgentApiError('INVALID_STATE', parent === ''
+            ? `锚点网格尚未挂载,无法定格世界坐标: anchor:${selfKey}`
+            : `父级目标已登记但运行时对象未就绪(异步加载中),请重试: ${parent}`, { details: { objectId: formatSceneObjectId('anchor', selfKey), parent } });
+    }
+    setStaticPropsWithFreeze(sheetObject, { parent }, { position: freeze.position });
+    // 事务已提交,立即换父:包装器下一 tick 应用 position=定格值时节点已在
+    // 正确父级下,世界坐标不跳;看护 effect 的同值守卫随之跳过提交
+    freeze.reparent();
+    // historic 通知 tick 调度:等一个 tick,返回反映本次写入的 revision
+    return { revision: await runtime.nextRevision() };
+}
+export function registerAnchorCommands(registry, runtime) {
+    registry.register({
+        name: 'anchors.create',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'mounted',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                position: {
+                    ...vec3Schema,
+                    description: '创建位置(世界坐标);缺省 = 导演视角前方 5 单位',
+                },
+                expectedRevision: expectedRevisionProperty,
+            },
+            additionalProperties: false,
+        },
+        outputSchema: createOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+            'INTERNAL_ERROR',
+        ],
+        validate: (value) => {
+            const args = requireObject(value);
+            return {
+                position: args.position === undefined ? undefined : requireVec3(args.position),
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            // 乐观并发:先于任何副作用(handler 经它写注册表)
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            const createAnchor = runtime.handlers.createAnchor;
+            if (!createAnchor) {
+                throw new AgentApiError('SCENE_UNAVAILABLE', 'Scene Runtime 未绑定 createAnchor,无法创建锚点');
+            }
+            const { key } = createAnchor(args.position ? { position: args.position } : {});
+            // handler 同步写注册表返回 key;React 挂载必然晚于本调用栈,
+            // 此处创建 waiter 不会错过通知
+            const mounted = createAnchorWaiter(key);
+            try {
+                await mounted;
+            }
+            catch (error) {
+                // dispose 优先于挂载失败:会话已销毁时统一 API_DISPOSED
+                runtime.assertActive();
+                throw new AgentApiError('INTERNAL_ERROR', `锚点挂载失败: ${key}`, {
+                    details: {
+                        objectId: formatSceneObjectId('anchor', key),
+                        cause: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            runtime.assertActive();
+            const objectId = formatSceneObjectId('anchor', key);
+            // 双可见复核(与 models.create 同一不变量)
+            let summary;
+            try {
+                summary = getSceneObjectSummary(runtime.sheet, objectId);
+            }
+            catch (error) {
+                throw new AgentApiError('INTERNAL_ERROR', `创建已提交但场景对象不可见: ${objectId}`, {
+                    details: {
+                        objectId,
+                        cause: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            if (!summary.mounted) {
+                throw new AgentApiError('INTERNAL_ERROR', `创建已提交但 SheetObject 未登记: ${objectId}`, { details: { objectId } });
+            }
+            return { objectId, revision: await runtime.nextRevision() };
+        },
+    });
+    registry.register({
+        name: 'anchors.setParent',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                parent: {
+                    type: 'string',
+                    description: '父级目标:anchor:<key> | model:<key> | camera:<key> | bone:<placementKey>#<part>',
+                },
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId', 'parent'],
+            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);
+            const parent = args.parent;
+            if (typeof parent !== 'string' || !parent) {
+                throw new AgentApiError('INVALID_ARGUMENT', 'parent 必须是非空字符串(解除父级用 anchors.clearParent)');
+            }
+            return {
+                objectId: requireString(args, 'objectId'),
+                parent,
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveMountedAnchor(runtime, args.objectId);
+            // 目标校验先于建轨预检:无效目标不得写 props
+            const { objectKey: selfKey } = sheetObject.address;
+            assertParentValid(runtime.sheet, selfKey, args.parent);
+            return writeAnchorParent(runtime, sheetObject, args.parent, args.expectedRevision);
+        },
+    });
+    registry.register({
+        name: 'anchors.clearParent',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: objectIdProperty,
+                expectedRevision: expectedRevisionProperty,
+            },
+            required: ['objectId'],
+            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'),
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveMountedAnchor(runtime, args.objectId);
+            // 清空父级 + 世界坐标定格同一事务(F1);定格后看护 effect 同值守卫
+            // 跳过,挂回 home 由 writeAnchorParent 的 reparent 同步完成
+            return writeAnchorParent(runtime, sheetObject, '', args.expectedRevision);
+        },
+    });
+}

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

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

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

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