@dreamerbird/camera-studio 0.2.0 → 0.3.0

package/dist/agent/api.test.js

@@ -5,7 +5,7 @@
  * 公开 JS API 门面与启动生命周期(2026-10-19,Task 15,spec §7):
  *
  * suite 1 命名空间转发:fake runtime + stub registry,遍历 spec §9 全部
- *   71 条命令对应的门面方法,断言转发到同名命令、参数原样透传(同引用)、
+ *   75 条命令对应的门面方法,断言转发到同名命令、参数原样透传(同引用)、
  *   返回原始领域结果(绝不包装 {ok,result}),错误以 AgentApiError 原样抛出;
  *   另用真实 registerAllAgentCommands 断言注册清单与 spec 命令面一致、
  *   门面映射与注册表零漂移。
@@ -163,6 +163,7 @@ jest.doMock('../PlacementManager', () => ({
         startPlacingFromLibrary: async () => { },
         // 与生产形状一致:Agent createModel handler 的 {key, persisted} 契约
         placeLibraryEntryAt: () => ({ key: 'm1', persisted: Promise.resolve() }),
+        placePrimitiveAt: () => ({ key: 'box', persisted: Promise.resolve() }),
         cancelPlacing: noop,
         confirmPlacing: noop,
         clearPending: noop,
@@ -274,6 +275,35 @@ const FACADE_COMMANDS = [
         command: 'models.create',
         args: { assetId: 'asset-1', position: { x: 0, y: 0, z: 0 } },
     },
+    {
+        path: 'models.retry',
+        command: 'models.retry',
+        args: { objectId: 'model:M' },
+    },
+    {
+        path: 'models.replace',
+        command: 'models.replace',
+        args: { objectId: 'model:M', assetId: 'asset-2' },
+    },
+    {
+        path: 'primitives.create',
+        command: 'primitives.create',
+        args: { kind: 'box', position: { x: 0, y: 0, z: 0 } },
+    },
+    {
+        path: 'materials.list',
+        command: 'materials.list',
+        args: { objectId: 'model:M' },
+    },
+    {
+        path: 'materials.update',
+        command: 'materials.update',
+        args: {
+            objectId: 'model:M',
+            slotId: 'root:0',
+            values: { roughness: 0.5 },
+        },
+    },
     { path: 'assets.list', command: 'assets.list' },
     { path: 'assets.get', command: 'assets.get', args: { assetId: 'asset-1' } },
     {
@@ -281,6 +311,11 @@ const FACADE_COMMANDS = [
         command: 'assets.importModel',
         args: { file: { name: 'm.glb' } },
     },
+    {
+        path: 'assets.importModels',
+        command: 'assets.importModels',
+        args: { files: [{ name: 'm.gltf' }, { name: 'm.bin' }] },
+    },
     {
         path: 'assets.rename',
         command: 'assets.rename',
@@ -468,6 +503,7 @@ const FACADE_COMMANDS = [
 /** CameraScene 生产绑定必须提供的完整 handler 集(命令侧 SCENE_UNAVAILABLE 的依据) */
 const HANDLER_KEYS = [
     'createModel',
+    'createPrimitive',
     'createCamera',
     'setActiveCamera',
     'createAnchor',
@@ -602,6 +638,44 @@ describe('命名空间转发', () => {
 function commandOf(row) {
     return row.command;
 }
+test('subscribe receives historic and selection changes and stops after unsubscribe', () => {
+    let notifyHistoric = () => { };
+    let notifySelection = () => { };
+    const unsubscribeSelection = jest.fn(() => {
+        notifySelection = () => { };
+    });
+    const runtime = createAgentRuntime({
+        project: {},
+        sheet: {},
+        library: {},
+        getStudio: () => ({
+            onSelectionChange: (listener) => {
+                notifySelection = listener;
+                return unsubscribeSelection;
+            },
+        }),
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => {
+                notifyHistoric = () => { };
+            };
+        },
+    });
+    const controller = createCameraStudioApi();
+    controller.activate(runtime);
+    const listener = jest.fn();
+    const unsubscribe = controller.api.subscribe(listener);
+    notifyHistoric();
+    notifySelection();
+    expect(listener).toHaveBeenCalledTimes(2);
+    listener.mockClear();
+    unsubscribe();
+    notifyHistoric();
+    notifySelection();
+    expect(listener).not.toHaveBeenCalled();
+    expect(unsubscribeSelection).toHaveBeenCalledTimes(1);
+    controller.dispose();
+});
 // ── suite 2:ready / dispose / remount ──────────────────────────
 describe('生命周期', () => {
     test('handlers 未绑定时不 ready:ready 与调用都挂起;绑定后 resolve,挂起调用继续执行', async () => {

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

@@ -15,6 +15,11 @@ export type AssetsApi = {
     }): Promise<{
         jobId: string;
     }>;
+    importModels(args: {
+        files: File[];
+    }): Promise<{
+        jobId: string;
+    }>;
     rename(args: {
         assetId: string;
         name: string;

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

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/assets.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEb,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAC,aAAa,EAAkB,MAAM,WAAW,CAAA;AACxD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAI5C,8BAA8B;AAC9B,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,CAAC,IAAI,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IACxD,GAAG,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACnD,WAAW,CAAC,IAAI,EAAE;QAAC,IAAI,EAAE,IAAI,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACzD,MAAM,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACpE,MAAM,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,IAAI,CAAA;KAAC,CAAC,CAAA;CAC1D,CAAA;AA0GD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAsB7D;AAiFD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAsLN"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/assets.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEb,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAC,aAAa,EAAkB,MAAM,WAAW,CAAA;AACxD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAI5C,8BAA8B;AAC9B,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,CAAC,IAAI,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IACxD,GAAG,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACnD,WAAW,CAAC,IAAI,EAAE;QAAC,IAAI,EAAE,IAAI,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACzD,YAAY,CAAC,IAAI,EAAE;QAAC,KAAK,EAAE,IAAI,EAAE,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC7D,MAAM,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACpE,MAAM,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,IAAI,CAAA;KAAC,CAAC,CAAA;CAC1D,CAAA;AAgHD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAsB7D;AA+GD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CA4ON"}

package/dist/agent/commands/assets.js

@@ -6,9 +6,9 @@
  * rename/delete 直等 Library 完成并返回更新后的条目 / {deleted:true};
  * 无 writable 源或条目属于只读源时返回 INVALID_STATE,不静默成功。
  *
- * importModel 是任务型命令(kind:job, completion:loaded):经
- * runtime.jobs.start 调用 importModelFile(file, library),任务结果即
- * ModelEntry;管线逐项落库,中途失败时 diff 出已创建条目,报
+ * importModel/importModels 是任务型命令(kind:job, completion:loaded):经
+ * runtime.jobs.start 调用单/多文件导入,任务结果分别为 ModelEntry 与
+ * ModelEntry[];管线逐项落库,中途失败时 diff 出已创建条目,报
  * PARTIAL_FAILURE(details 含 createdAssetIds 与失败项);Library 的
  * quota/network 等结构化错误分别保留为 STORAGE_ERROR / NETWORK_ERROR,
  * 不统一吞成 unknown。
@@ -19,6 +19,7 @@
  * fileRef 不许绕过传输适配直接进入 Library。
  */
 import { importModelFile } from '../../assetLibrary/importModelFile';
+import { importModelFiles } from '../../assetLibrary/importModelFiles';
 import { LibraryError } from '../../assetLibrary/source';
 import { AgentApiError, asAgentApiError } from '../errors';
 import { requireObject, requireString } from '../validation';
@@ -36,7 +37,7 @@ const libraryEntrySchema = {
     },
     required: ['id', 'kind', 'name'],
 };
-/** ModelEntry 形状(importModel 的 jobResult) */
+/** ModelEntry 形状(importModel/importModels 的 jobResult 元素) */
 const modelEntrySchema = {
     type: 'object',
     properties: {
@@ -88,24 +89,29 @@ const renameInput = {
     additionalProperties: false,
 };
 /** HTTP 传输形状:桥接把 fileId 水合成 File 后才进 validator */
-const importModelInput = {
+const fileRefSchema = {
     type: 'object',
+    description: 'HTTP:经 POST /v1/files 上传后的引用;JS:直接传 hydrated File',
     properties: {
-        file: {
-            type: 'object',
-            description: 'HTTP:经 POST /v1/files 上传后的引用;JS:直接传 hydrated File',
-            properties: {
-                fileId: { type: 'string', description: '桥接上传返回的文件 id' },
-                fileName: { type: 'string' },
-                mimeType: { type: 'string' },
-            },
-            required: ['fileId'],
-            additionalProperties: false,
-        },
+        fileId: { type: 'string', description: '桥接上传返回的文件 id' },
+        fileName: { type: 'string' },
+        mimeType: { type: 'string' },
     },
+    required: ['fileId'],
+    additionalProperties: false,
+};
+const importModelInput = {
+    type: 'object',
+    properties: { file: fileRefSchema },
     required: ['file'],
     additionalProperties: false,
 };
+const importModelsInput = {
+    type: 'object',
+    properties: { files: { type: 'array', items: fileRefSchema } },
+    required: ['files'],
+    additionalProperties: false,
+};
 const jobIdOutput = {
     type: 'object',
     properties: { jobId: { type: 'string' } },
@@ -149,6 +155,12 @@ function requireFile(value) {
         return value;
     throw new AgentApiError('INVALID_ARGUMENT', 'file 必须是 File(HTTP 调用先经桥接上传拿 fileId,由桥接水合成 File)');
 }
+function requireFiles(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'files 必须是非空 File 数组');
+    }
+    return value.map(requireFile);
+}
 function requireWritable(library) {
     if (!library.canWrite) {
         throw new AgentApiError('INVALID_STATE', '资产库为纯查看器模式:未配置可写存储');
@@ -177,7 +189,7 @@ async function requireWritableEntry(library, assetId) {
  * 导入失败的结构化描述:导入管线逐项落库,中途失败时 diff 出本任务
  * 已创建的条目报 PARTIAL_FAILURE;无部分写入时按错误类型映射。
  */
-async function describeImportFailure(library, before, file, error) {
+async function describeImportFailure(library, before, files, error) {
     let createdAssetIds = [];
     try {
         createdAssetIds = (await library.listEntries())
@@ -187,16 +199,34 @@ async function describeImportFailure(library, before, file, error) {
     catch {
         // 连列举都失败时不掩盖原始错误
     }
-    const cause = error instanceof Error ? error.message : String(error);
+    const structured = error;
+    const failedItems = Array.isArray(structured?.failedItems)
+        ? structured.failedItems
+        : undefined;
+    const sourceError = structured?.cause ?? error;
+    const cause = sourceError instanceof Error ? sourceError.message : String(sourceError);
     if (createdAssetIds.length > 0) {
         return new AgentApiError('PARTIAL_FAILURE', `模型导入部分完成后中断: ${cause}`, {
             details: {
                 createdAssetIds,
-                failedItems: [{ file: file.name, message: cause }],
+                failedItems: failedItems ??
+                    files.map((file) => ({ file: file.name, message: cause })),
             },
         });
     }
-    return mapLibraryError(error);
+    const normalized = mapLibraryError(sourceError);
+    if (failedItems) {
+        return new AgentApiError(normalized.code, normalized.message, {
+            retryable: normalized.retryable,
+            details: {
+                ...(typeof normalized.details === 'object' && normalized.details
+                    ? normalized.details
+                    : {}),
+                failedItems,
+            },
+        });
+    }
+    return normalized;
 }
 export function registerAssetCommands(registry, runtime) {
     registry.register({
@@ -282,7 +312,49 @@ export function registerAssetCommands(registry, runtime) {
                         return entry;
                     }
                     catch (error) {
-                        throw await describeImportFailure(library, before, args.file, error);
+                        throw await describeImportFailure(library, before, [args.file], error);
+                    }
+                },
+            });
+            return { jobId };
+        },
+    });
+    registry.register({
+        name: 'assets.importModels',
+        kind: 'job',
+        stateDomain: 'asset',
+        undoable: 'none',
+        completion: 'loaded',
+        cancelable: false,
+        inputSchema: importModelsInput,
+        outputSchema: jobIdOutput,
+        jobResultSchema: { type: 'array', items: modelEntrySchema },
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_STATE',
+            'STORAGE_ERROR',
+            'NETWORK_ERROR',
+            'PARTIAL_FAILURE',
+            'INTERNAL_ERROR',
+        ],
+        validate: (value) => ({ files: requireFiles(requireObject(value).files) }),
+        execute: async (args) => {
+            runtime.assertActive();
+            requireWritable(runtime.library);
+            const library = runtime.library;
+            const { jobId } = runtime.jobs.start({
+                kind: 'assets.importModels',
+                cancelable: false,
+                execute: async (controls) => {
+                    const before = new Set((await library.listEntries()).map((entry) => entry.id));
+                    try {
+                        const entries = await importModelFiles(args.files, library);
+                        controls.update({ phase: 'loaded' });
+                        return entries;
+                    }
+                    catch (error) {
+                        throw await describeImportFailure(library, before, args.files, error);
                     }
                 },
             });

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

@@ -1,14 +1,20 @@
 /** 晚绑定:doMock 工厂只登记一次,各用例在 setup 里换实现 */
 let activeImportModelFile;
+let activeImportModelFiles;
 jest.doMock('../../assetLibrary/importModelFile', () => ({
     __esModule: true,
     importModelFile: (...args) => activeImportModelFile(...args),
 }));
+jest.doMock('../../assetLibrary/importModelFiles', () => ({
+    __esModule: true,
+    importModelFiles: (...args) => activeImportModelFiles(...args),
+}));
 const cleanups = [];
 afterEach(() => {
     while (cleanups.length)
         cleanups.pop()();
     activeImportModelFile = undefined;
+    activeImportModelFiles = undefined;
 });
 const ctx = () => ({
     requestId: 'test',
@@ -95,6 +101,7 @@ function setup(options = {}) {
     m.registerAssetCommands(registry, runtime);
     m.registerJobCommands(registry, runtime);
     activeImportModelFile = jest.fn();
+    activeImportModelFiles = jest.fn();
     return { ...m, library, runtime, registry };
 }
 /** 轮询任务到终态(job manager 的 done 不经命令暴露,测试读快照) */
@@ -354,6 +361,52 @@ describe('assets.importModel', () => {
         expect(done.error?.code).toBe('INTERNAL_ERROR');
     });
 });
+describe('assets.importModels', () => {
+    test('多个模型根成功时任务结果保持 ModelEntry[]', async () => {
+        const { registry, runtime, library } = setup();
+        const imported = [modelEntry('lib-a', 'a'), modelEntry('lib-b', 'b')];
+        activeImportModelFiles = jest.fn(async () => imported);
+        const files = [
+            new File(['a'], 'a.gltf'),
+            new File(['b'], 'b.gltf'),
+            new File(['bin'], 'shared.bin'),
+        ];
+        const { jobId } = (await registry.execute('assets.importModels', { files }, ctx()));
+        const done = await settleJob(runtime, jobId);
+        expect(activeImportModelFiles).toHaveBeenCalledWith(files, library);
+        expect(done).toMatchObject({
+            state: 'succeeded',
+            phase: 'loaded',
+            result: imported,
+        });
+    });
+    test('部分成功时只报告实际失败模型根,不误报成功项和伴随资源', async () => {
+        const { registry, runtime } = setup();
+        const partial = modelEntry('lib-a', 'a');
+        activeImportModelFiles = jest.fn(async (_files, library) => {
+            await library.putEntry(partial);
+            throw Object.assign(new Error('b 写入失败'), {
+                entries: [partial],
+                failedItems: [{ file: 'b.gltf', message: 'b 写入失败' }],
+            });
+        });
+        const files = [
+            new File(['a'], 'a.gltf'),
+            new File(['b'], 'b.gltf'),
+            new File(['bin'], 'shared.bin'),
+        ];
+        const { jobId } = (await registry.execute('assets.importModels', { files }, ctx()));
+        const done = await settleJob(runtime, jobId);
+        expect(done.state).toBe('failed');
+        expect(done.error).toMatchObject({
+            code: 'PARTIAL_FAILURE',
+            details: {
+                createdAssetIds: ['lib-a'],
+                failedItems: [{ file: 'b.gltf', message: 'b 写入失败' }],
+            },
+        });
+    });
+});
 describe('jobs.get / jobs.cancel', () => {
     test('jobs.get 返回任务快照;未知任务 → JOB_NOT_FOUND', async () => {
         const { registry, runtime } = setup();

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

@@ -0,0 +1,18 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { MaterialSlot, MaterialValues } from '../../materials/types';
+export type MaterialsApi = {
+    list(args: {
+        objectId: string;
+    }): Promise<MaterialSlot[]>;
+    update(args: {
+        objectId: string;
+        slotId: string;
+        values: Partial<MaterialValues>;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+};
+export declare function registerMaterialCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=materials.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"materials.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/materials.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAI5C,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,uBAAuB,CAAA;AAEvE,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,CAAC,IAAI,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IACvD,MAAM,CAAC,IAAI,EAAE;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAChC,CAAA;AAsHD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAiHN"}

package/dist/agent/commands/materials.js

@@ -0,0 +1,192 @@
+import { AgentApiError } from '../errors';
+import { parseSceneObjectId } from '../objectIds';
+import { resolveSceneSheetObject } from '../objectResolver';
+import { assertStaticPropsWithLeafGuardWritable, setStaticPropsWithLeafGuard, } from '../propAccess';
+import { requireFiniteNumber, requireObject, requireString } from '../validation';
+import { collectMaterialSlots } from '../../materials/modelMaterials';
+const materialValueProperties = {
+    color: { type: 'string', description: '#RRGGBB' },
+    metalness: { type: 'number', description: '0..1' },
+    roughness: { type: 'number', description: '0..1' },
+    emissive: { type: 'string', description: '#RRGGBB' },
+    opacity: { type: 'number', description: '0..1' },
+    mapBlobId: { type: 'string', description: '贴图 blob ID;空字符串恢复原图' },
+    normalMapBlobId: { type: 'string' },
+    roughnessMapBlobId: { type: 'string' },
+    metalnessMapBlobId: { type: 'string' },
+    emissiveMapBlobId: { type: 'string' },
+};
+const materialValuesSchema = {
+    type: 'object',
+    properties: materialValueProperties,
+    additionalProperties: false,
+};
+const materialSlotSchema = {
+    type: 'object',
+    properties: {
+        slotId: { type: 'string' },
+        slotKey: { type: 'string' },
+        meshName: { type: 'string' },
+        materialName: { type: 'string' },
+        values: {
+            ...materialValuesSchema,
+            required: Object.keys(materialValueProperties),
+        },
+    },
+    required: ['slotId', 'slotKey', 'meshName', 'materialName', 'values'],
+};
+function optionalExpectedRevision(value) {
+    return value === undefined
+        ? undefined
+        : requireFiniteNumber(value, 'expectedRevision');
+}
+function validateMaterialValues(value) {
+    const values = requireObject(value);
+    const entries = Object.entries(values);
+    if (entries.length === 0) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'values 不能为空对象');
+    }
+    for (const [key, input] of entries) {
+        if (!(key in materialValueProperties)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `未知材质属性: ${key}`);
+        }
+        if (['metalness', 'roughness', 'opacity'].includes(key)) {
+            const number = requireFiniteNumber(input, `values.${key}`);
+            if (number < 0 || number > 1) {
+                throw new AgentApiError('INVALID_ARGUMENT', `values.${key} 必须在 0..1 范围内`);
+            }
+        }
+        else if (key === 'color' || key === 'emissive') {
+            if (typeof input !== 'string' || !/^#[0-9a-fA-F]{6}$/.test(input)) {
+                throw new AgentApiError('INVALID_ARGUMENT', `values.${key} 必须是 #RRGGBB 颜色`);
+            }
+        }
+        else if (typeof input !== 'string') {
+            throw new AgentApiError('INVALID_ARGUMENT', `values.${key} 必须是贴图 blob ID 或空字符串`);
+        }
+    }
+    return values;
+}
+function mountedModel(runtime, objectId) {
+    const sheetObject = resolveSceneSheetObject(runtime.sheet, objectId, 'model');
+    if (!sheetObject) {
+        throw new AgentApiError('INVALID_STATE', `对象未挂载,无法访问材质: ${objectId}`, { details: { 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 { sheetObject, instance: placement.instance };
+}
+function evaluatedOverrides(sheetObject) {
+    const value = sheetObject.value;
+    return (value.materialOverrides ?? {});
+}
+export function registerMaterialCommands(registry, runtime) {
+    registry.register({
+        name: 'materials.list',
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: { objectId: { type: 'string' } },
+            required: ['objectId'],
+            additionalProperties: false,
+        },
+        outputSchema: { type: 'array', items: materialSlotSchema },
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => ({
+            objectId: requireString(requireObject(value), 'objectId'),
+        }),
+        execute: async ({ objectId }) => {
+            runtime.assertActive();
+            const { sheetObject, instance } = mountedModel(runtime, objectId);
+            const overrides = evaluatedOverrides(sheetObject);
+            return collectMaterialSlots(instance).map((slot) => ({
+                ...slot,
+                values: { ...slot.values, ...overrides[slot.slotKey] },
+            }));
+        },
+    });
+    registry.register({
+        name: 'materials.update',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                objectId: { type: 'string' },
+                slotId: { type: 'string' },
+                values: materialValuesSchema,
+                expectedRevision: { type: 'number' },
+            },
+            required: ['objectId', 'slotId', 'values'],
+            additionalProperties: false,
+        },
+        outputSchema: {
+            type: 'object',
+            properties: { revision: { type: 'number' } },
+            required: ['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'),
+                slotId: requireString(args, 'slotId'),
+                values: validateMaterialValues(args.values),
+                expectedRevision: optionalExpectedRevision(args.expectedRevision),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            const { sheetObject, instance } = mountedModel(runtime, args.objectId);
+            const slot = collectMaterialSlots(instance).find((candidate) => candidate.slotId === args.slotId);
+            if (!slot) {
+                throw new AgentApiError('INVALID_ARGUMENT', `材质槽不存在: ${args.slotId}`, { details: { objectId: args.objectId, slotId: args.slotId } });
+            }
+            const current = evaluatedOverrides(sheetObject);
+            const materialOverrides = {
+                ...current,
+                [slot.slotKey]: {
+                    ...slot.values,
+                    ...current[slot.slotKey],
+                    ...args.values,
+                },
+            };
+            const patch = { materialOverrides };
+            const guardedPropPaths = Object.keys(args.values).map((property) => `materialOverrides.${slot.slotKey}.${property}`);
+            assertStaticPropsWithLeafGuardWritable(sheetObject, patch, guardedPropPaths);
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            setStaticPropsWithLeafGuard(sheetObject, patch, guardedPropPaths);
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+}

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

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

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

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