@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/agent/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAC,MAAM,mBAAmB,CAAA;AAGhE,OAAO,EAAC,eAAe,EAAC,MAAM,QAAQ,CAAA;AACtC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,yBAAyB,CAAA;AAyCpD;;;;GAIG;AAEH,MAAM,WAAW,yBAAyB;CAAG;AAE7C,KAAK,QAAQ,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,QAAQ,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAA;IACpC;2FACuF;IACvF,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CACxD,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACrC,6DAA6D;IAC7D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,mBAAmB;IACnB,YAAY,IAAI,IAAI,CAAA;IACpB,uCAAuC;IACvC,aAAa,IAAI,IAAI,CAAA;IACrB,wDAAwD;IACxD,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAA;IAC5C;qEACiE;IACjE,QAAQ,IAAI,YAAY,CAAA;IACxB,qDAAqD;IACrD,SAAS,IAAI,IAAI,CAAA;IACjB;8DAC0D;IAC1D,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAsED,0DAA0D;AAC1D,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOnE;AAqHD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAyBvE"}

package/dist/agent/runtime.js

@@ -0,0 +1,214 @@
+import { getCoreTicker } from '@dreamerbird/core/coreTicker';
+import { AgentApiError } from './errors';
+import { AgentJobManager } from './jobs';
+import { rejectAllPlacements } from './runtime/placementLifecycle';
+import { rejectAllAnchorMounts, rejectAllCameraMounts, } from './runtime/cameraLifecycle';
+/**
+ * 等一个 core tick(2026-10-19,F2 修复):historic 指针的 onChange 监听
+ * 经 prism.onChange → ticker.onThisOrNextTick 调度(prism.ts),事务提交后
+ * 同步读 revision 拿到的是写入前的值;写命令返回前必须等一个 tick。
+ *
+ * 生产浏览器:RAF 驱动持续 tick,dormant→active 时 start() 自动武装。
+ * 测试(node):SSR start() 只在 dormant→active 补两脚 tick 就停,ticker
+ * 可能停在 active 但无人驱动(测试手动 tick 过);有的测试文件还会把
+ * window 残桩成 globalThis(delete/paths.test.ts,为 getPathMeta 的调试
+ * 挂钩)——window 在但 requestAnimationFrame 不在,start() 的 RAF 分支
+ * 直接抛错(此时 fn 已入队、ticker 已转 active)。两种情形统一手动补
+ * 一脚兜底;已同步触发的(dormant+SSR)不重复补。
+ */
+function nextCoreTick() {
+    const ticker = getCoreTicker();
+    const hasRafDriver = typeof window !== 'undefined' &&
+        typeof window.requestAnimationFrame === 'function';
+    return new Promise((resolve) => {
+        let fired = false;
+        try {
+            ticker.onNextTick(() => {
+                fired = true;
+                resolve();
+            });
+        }
+        catch {
+            // 无 RAF 的 window 残桩:start() 抛错,但 fn 已入队——落到手动 tick
+        }
+        if (!hasRafDriver && !fired) {
+            ticker.tick();
+        }
+    });
+}
+function makeGeneration(index) {
+    let resolveReady;
+    let rejectReady;
+    const readyPromise = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    // 内部兜底:没有消费者 await 本代 ready 时,dispose 的拒绝
+    // 不至于触发 unhandledRejection(Node 会直接崩掉测试进程);
+    // 真正 await 的消费者仍然收到拒绝。
+    readyPromise.catch(() => { });
+    return {
+        index,
+        superseded: false,
+        readySettled: false,
+        readyPromise,
+        resolveReady,
+        rejectReady,
+        handlers: {},
+    };
+}
+function assertGenerationUsable(core, generation) {
+    if (core.disposed) {
+        throw new AgentApiError('API_DISPOSED', 'Camera Studio API 已销毁');
+    }
+    if (generation.superseded) {
+        // 代次被替换 ≠ 会话销毁:携带结构化标记,门面层(api.ts invoke 复核)
+        // 据此映射为可重试的 API_NOT_READY;runtime/命令层维持 API_DISPOSED
+        // 语义不变(既有用例与调用方依赖)
+        throw new AgentApiError('API_DISPOSED', `执行代次 ${generation.index} 已被替换`, {
+            details: {
+                reason: 'GENERATION_SUPERSEDED',
+                generation: generation.index,
+            },
+        });
+    }
+}
+/** 判定错误是否来自"代次被替换但会话未 dispose"(门面映射 API_NOT_READY 的依据) */
+export function isGenerationSupersededError(error) {
+    return (error instanceof AgentApiError &&
+        error.code === 'API_DISPOSED' &&
+        error.details?.reason ===
+            'GENERATION_SUPERSEDED');
+}
+function makeRuntime(core, generation) {
+    return {
+        project: core.project,
+        sheet: core.sheet,
+        library: core.library,
+        getStudio: core.getStudio,
+        jobs: core.jobs,
+        get revision() {
+            return core.revision;
+        },
+        async nextRevision() {
+            await nextCoreTick();
+            // 等待期间会话可能已拆解:已提交的写入不回滚,但调用方不得再拿到
+            // 成功结果(与 create 等命令 await 后 assertActive 同一语义)
+            if (core.disposed) {
+                throw new AgentApiError('API_DISPOSED', 'Camera Studio API 已销毁');
+            }
+            return core.revision;
+        },
+        get ready() {
+            return generation.readyPromise;
+        },
+        get handlers() {
+            return generation.handlers;
+        },
+        assertRevision(expected) {
+            assertGenerationUsable(core, generation);
+            if (expected !== core.revision) {
+                throw new AgentApiError('REVISION_CONFLICT', `revision 冲突: expected ${expected}, actual ${core.revision}`, {
+                    details: {
+                        expectedRevision: expected,
+                        actualRevision: core.revision,
+                    },
+                });
+            }
+        },
+        assertActive() {
+            if (core.disposed) {
+                throw new AgentApiError('API_DISPOSED', 'Camera Studio API 已销毁');
+            }
+        },
+        assertCurrent() {
+            assertGenerationUsable(core, generation);
+        },
+        bindHandlers(handlers) {
+            // 与其余代次操作一致:代次被替换或会话销毁后拒绝绑定,
+            // 避免 remount 场景"绑了却无效"的静默失败
+            assertGenerationUsable(core, generation);
+            const keys = Object.keys(handlers);
+            generation.handlers = { ...generation.handlers, ...handlers };
+            return () => {
+                if (generation.superseded || core.disposed)
+                    return;
+                const rest = { ...generation.handlers };
+                for (const key of keys)
+                    delete rest[key];
+                generation.handlers = rest;
+            };
+        },
+        activate() {
+            if (core.disposed) {
+                throw new AgentApiError('API_DISPOSED', 'Camera Studio API 已销毁');
+            }
+            generation.superseded = true;
+            // handler 解绑换代(Task 15 预检裁定):旧代次未 settle 的 ready 以
+            // API_NOT_READY 拒绝——等待方拿到"暂时不就绪"而非悬挂;已 settle 的
+            // 不动。永久性 API_DISPOSED 只留给会话拆解(dispose)
+            if (!generation.readySettled) {
+                generation.readySettled = true;
+                generation.rejectReady(new AgentApiError('API_NOT_READY', `执行代次 ${generation.index} 的就绪已失效(Scene Runtime 解绑)`));
+            }
+            const next = makeGeneration(generation.index + 1);
+            core.generations.add(next);
+            core.currentGeneration = next;
+            return makeRuntime(core, next);
+        },
+        markReady() {
+            assertGenerationUsable(core, generation);
+            if (!generation.readySettled) {
+                generation.readySettled = true;
+                generation.resolveReady();
+            }
+        },
+        dispose() {
+            if (core.disposed)
+                return;
+            core.disposed = true;
+            core.unsubscribeHistoric();
+            const disposedError = new AgentApiError('API_DISPOSED', 'Camera Studio API 已销毁');
+            // 挂载等待者(Task 8/10)与在途任务(Task 15 决策:硬取消)一并收尾——
+            // dispose 不伴随 React 卸载时组件 cleanup 不会跑,waiter 不得悬挂
+            rejectAllPlacements(disposedError);
+            rejectAllCameraMounts(disposedError);
+            rejectAllAnchorMounts(disposedError);
+            core.jobs.dispose();
+            for (const gen of core.generations) {
+                gen.superseded = true;
+                if (!gen.readySettled) {
+                    gen.readySettled = true;
+                    gen.rejectReady(disposedError);
+                }
+            }
+        },
+    };
+}
+export function createAgentRuntime(deps) {
+    const first = makeGeneration(1);
+    const core = {
+        project: deps.project,
+        sheet: deps.sheet,
+        library: deps.library,
+        getStudio: deps.getStudio,
+        jobs: new AgentJobManager(),
+        disposed: false,
+        revision: 1,
+        currentGeneration: first,
+        generations: new Set([first]),
+        unsubscribeHistoric: () => { },
+    };
+    // 订阅必须在 core 建好之后:真实 subscribeHistoric 走 core
+    // onChange(pointers.historic)(immediate:true),订阅瞬间同步回调一次——
+    // 字面量内联订阅会撞上 TDZ(core 尚未初始化,生产 bootstrap 必崩),
+    // 且那次回调是订阅产物而非 historic 变更,不得递增 revision
+    let subscribing = true;
+    core.unsubscribeHistoric = deps.subscribeHistoric(() => {
+        if (subscribing)
+            return;
+        core.revision += 1;
+    });
+    subscribing = false;
+    return makeRuntime(core, first);
+}

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

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

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

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

package/dist/agent/runtime.test.js

@@ -0,0 +1,142 @@
+import { createAgentRuntime } from './runtime';
+/**
+ * 本文件的绑定键是合成假键(a/b/c/d),不属于任何领域 handler;
+ * 真实 handler 由各领域任务经 declaration merging 加入接口(Task 4 起),
+ * 之后 Partial<AgentSceneRuntimeHandlers> 成为弱类型,对象字面量会触发
+ * 多余属性检查 —— 故此处统一断言绕过(语义不变:仍验证合并/解绑行为)。
+ */
+const fakeHandlers = (handlers) => handlers;
+function expectErrorCode(fn, code) {
+    try {
+        fn();
+    }
+    catch (error) {
+        expect(error).toMatchObject({ code });
+        return;
+    }
+    throw new Error(`Expected ${code}`);
+}
+function makeDeps(overrides = {}) {
+    return {
+        project: { ready: Promise.resolve() },
+        sheet: {},
+        library: {},
+        getStudio: () => ({}),
+        subscribeHistoric: () => () => { },
+        ...overrides,
+    };
+}
+test('tracks every historic change and rejects stale writes', () => {
+    let notify;
+    const runtime = createAgentRuntime({
+        project: { ready: Promise.resolve() },
+        sheet: {},
+        library: {},
+        getStudio: () => ({}),
+        subscribeHistoric: (listener) => {
+            notify = listener;
+            return () => {
+                notify = undefined;
+            };
+        },
+    });
+    expect(runtime.revision).toBe(1);
+    expect(() => runtime.assertRevision(1)).not.toThrow();
+    notify?.();
+    expect(runtime.revision).toBe(2);
+    expectErrorCode(() => runtime.assertRevision(1), 'REVISION_CONFLICT');
+    runtime.dispose();
+    expectErrorCode(() => runtime.assertActive(), 'API_DISPOSED');
+});
+test('revision conflict details carry expected and actual revision', () => {
+    let notify;
+    const runtime = createAgentRuntime(makeDeps({
+        subscribeHistoric: (listener) => {
+            notify = listener;
+            return () => {
+                notify = undefined;
+            };
+        },
+    }));
+    notify?.();
+    notify?.();
+    expect(runtime.revision).toBe(3);
+    try {
+        runtime.assertRevision(1);
+        throw new Error('Expected REVISION_CONFLICT');
+    }
+    catch (error) {
+        expect(error).toMatchObject({
+            code: 'REVISION_CONFLICT',
+            details: { expectedRevision: 1, actualRevision: 3 },
+        });
+    }
+});
+test('activate() supersedes the old generation', () => {
+    const runtime = createAgentRuntime(makeDeps());
+    expect(() => runtime.assertCurrent()).not.toThrow();
+    const next = runtime.activate();
+    expectErrorCode(() => runtime.assertCurrent(), 'API_DISPOSED');
+    expect(() => next.assertCurrent()).not.toThrow();
+    expect(() => next.assertActive()).not.toThrow();
+    // 会话级 revision/jobs 在代次间共享
+    expect(next.jobs).toBe(runtime.jobs);
+    expectErrorCode(() => runtime.markReady(), 'API_DISPOSED');
+});
+test('stale generation fails revision checks before comparing', () => {
+    let notify;
+    const runtime = createAgentRuntime(makeDeps({
+        subscribeHistoric: (listener) => {
+            notify = listener;
+            return () => {
+                notify = undefined;
+            };
+        },
+    }));
+    const next = runtime.activate();
+    notify?.();
+    expect(next.revision).toBe(2);
+    // 旧代次先撞代次检查,而不是报 revision 冲突
+    expectErrorCode(() => runtime.assertRevision(2), 'API_DISPOSED');
+    expect(() => next.assertRevision(2)).not.toThrow();
+});
+test('readiness resolves per generation and dispose rejects pending ready', async () => {
+    const runtime = createAgentRuntime(makeDeps());
+    let settled = false;
+    void runtime.ready.then(() => {
+        settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    runtime.markReady();
+    await runtime.ready;
+    const next = runtime.activate();
+    const nextReady = next.ready;
+    const rejected = expect(nextReady).rejects.toMatchObject({
+        code: 'API_DISPOSED',
+    });
+    await Promise.resolve();
+    next.dispose();
+    await rejected;
+    expectErrorCode(() => next.assertActive(), 'API_DISPOSED');
+    expectErrorCode(() => runtime.assertActive(), 'API_DISPOSED');
+    expectErrorCode(() => runtime.activate(), 'API_DISPOSED');
+});
+test('bindHandlers merges handlers and unbind removes only its own keys', () => {
+    const runtime = createAgentRuntime(makeDeps());
+    const unbindA = runtime.bindHandlers(fakeHandlers({ a: 1 }));
+    const unbindB = runtime.bindHandlers(fakeHandlers({ b: 2 }));
+    expect(runtime.handlers).toEqual({ a: 1, b: 2 });
+    unbindA();
+    expect(runtime.handlers).toEqual({ b: 2 });
+    // 代次被替换后:在存活期创建的解绑函数调用静默失效,
+    // 而继续绑定被明确拒绝(与 markReady/assertCurrent 一致)
+    const next = runtime.activate();
+    expect(() => unbindB()).not.toThrow();
+    expect(runtime.handlers).toEqual({ b: 2 });
+    expect(next.handlers).toEqual({});
+    expectErrorCode(() => runtime.bindHandlers(fakeHandlers({ c: 3 })), 'API_DISPOSED');
+    // 会话 dispose 后同样拒绝绑定
+    next.dispose();
+    expectErrorCode(() => next.bindHandlers(fakeHandlers({ d: 4 })), 'API_DISPOSED');
+});

package/dist/agent/sequenceLength.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Studio stateEditors 时长适配(2026-10-17,Task 6 初版;同日修正):
+ * sequence.setLength 的唯一 stateEditors 通道,与 TransportBar.tsx:152-157
+ * 完全同路径(`stateEditors.coreByProject.historic.sheetsById.sequence.setLength`),
+ * 把 Studio 内部能力隔离在这一处(spec:sequence.setLength 只能经内部适配层
+ * 完成并配套行为测试)。Studio 不可用抛 SCENE_UNAVAILABLE(spec 8.3)。
+ *
+ * Studio 访问必须用内部 `@dreamerbird/studio/getStudio`(TransportBar 先例):
+ * 只有内部 Studio 的事务 api(ITransactionPrivateApi)携带 stateEditors;
+ * 公开 TheatreStudio.transaction 的回调 api 只有 set/unset/sequenceProp 等
+ * (TheatreStudio.ts:202-209),经 getStudioSync() 拿公开 api 再类型断言出
+ * stateEditors 在生产上是 undefined 而抛错——初版即踩此坑。
+ */
+import type { ISheet } from '@dreamerbird/core';
+/**
+ * 在单个历史事务里把 sheet 的 sequence 时长改为 length(秒)。
+ * length 的正数/有限校验由调用方(命令 validate)在事务之前完成。
+ */
+export declare function setSequenceLength(sheet: ISheet, length: number): void;
+//# sourceMappingURL=sequenceLength.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequenceLength.d.ts","sourceRoot":"","sources":["../../src/agent/sequenceLength.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAA;AAI7C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAcrE"}

package/dist/agent/sequenceLength.js

@@ -0,0 +1,18 @@
+import getStudio from '@dreamerbird/studio/getStudio';
+import { AgentApiError } from './errors';
+/**
+ * 在单个历史事务里把 sheet 的 sequence 时长改为 length(秒)。
+ * length 的正数/有限校验由调用方(命令 validate)在事务之前完成。
+ */
+export function setSequenceLength(sheet, length) {
+    const studio = getStudio();
+    if (!studio) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法设置序列时长');
+    }
+    studio.transaction(({ stateEditors }) => {
+        stateEditors.coreByProject.historic.sheetsById.sequence.setLength({
+            ...sheet.address,
+            length,
+        });
+    });
+}

package/dist/agent/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Agent 命令通用契约(2026-10-17):命令元数据、JSON Schema 子集、
+ * 任务快照和带类型 ID。纯类型模块,无运行时依赖,后续注册表、
+ * 运行时和领域命令都建立在这些契约上(见 spec 第 8 节)。
+ */
+/** 三维向量 DTO(JS 与 HTTP 共用同一形状) */
+export type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** 场景对象稳定 ID 的类型部分(spec 8.4) */
+export type SceneObjectKind = 'model' | 'camera' | 'anchor' | 'path';
+/** 带类型场景对象 ID,如 `model:Y Bot` */
+export type SceneObjectId = `${SceneObjectKind}:${string}`;
+export type JobState = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+/** 写命令/任务声明的完成阶段(spec 8.7) */
+export type CompletionPhase = 'committed' | 'mounted' | 'loaded';
+/** 结构化错误 DTO(任务快照与资源加载状态共用;HTTP 桥接原样透传) */
+export type AgentErrorDto = {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+};
+/**
+ * JSON Schema 子集:只覆盖命令参数/结果声明需要的结构,
+ * 桥接层原样透传给 Agent 做客户端校验。
+ */
+export type JsonSchema = {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: readonly (string | number | boolean | null)[];
+    additionalProperties?: boolean | JsonSchema;
+};
+/** 任务句柄快照(spec 8.7);`accepted` 不等于最终成功 */
+export type JobSnapshot<T = unknown> = {
+    jobId: string;
+    kind: string;
+    state: JobState;
+    progress: number;
+    phase: 'accepted' | CompletionPhase;
+    result?: T;
+    error?: AgentErrorDto;
+    cancelable: boolean;
+};
+/** 每次命令调用携带的执行上下文 */
+export type CommandContext = {
+    requestId: string;
+    signal: AbortSignal;
+};
+/** 命令定义:元数据 + 运行时校验 + 执行体(spec 8.1) */
+export type CommandDefinition<A, R> = {
+    name: string;
+    kind: 'query' | 'mutation' | 'job';
+    stateDomain: 'project' | 'asset' | 'session' | 'transport';
+    undoable: 'single-step' | 'none';
+    completion?: CompletionPhase;
+    cancelable?: boolean;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    jobResultSchema?: JsonSchema;
+    errorCodes: readonly string[];
+    validate: (value: unknown) => A;
+    execute: (args: A, context: CommandContext) => Promise<R>;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iCAAiC;AACjC,MAAM,MAAM,IAAI,GAAG;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAEpD,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,iCAAiC;AACjC,MAAM,MAAM,aAAa,GAAG,GAAG,eAAe,IAAI,MAAM,EAAE,CAAA;AAE1D,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,CAAA;AAEf,8BAA8B;AAC9B,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEhE,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACvC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAA;IACpD,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;CAC5C,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,QAAQ,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,UAAU,GAAG,eAAe,CAAA;IACnC,MAAM,CAAC,EAAE,CAAC,CAAA;IACV,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,qBAAqB;AACrB,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,uCAAuC;AACvC,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,IAAI;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,KAAK,CAAA;IAClC,WAAW,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAA;IAC1D,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAA;IAChC,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,EAAE,UAAU,CAAA;IACvB,YAAY,EAAE,UAAU,CAAA;IACxB,eAAe,CAAC,EAAE,UAAU,CAAA;IAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CAC1D,CAAA"}

package/dist/agent/types.js

@@ -0,0 +1,6 @@
+/**
+ * Agent 命令通用契约(2026-10-17):命令元数据、JSON Schema 子集、
+ * 任务快照和带类型 ID。纯类型模块,无运行时依赖,后续注册表、
+ * 运行时和领域命令都建立在这些契约上(见 spec 第 8 节)。
+ */
+export {};

package/dist/agent/validation.d.ts

@@ -0,0 +1,7 @@
+import type { Vec3 } from './types';
+export declare function requireObject(value: unknown): Record<string, unknown>;
+export declare function requireString(object: Record<string, unknown>, key: string): string;
+export declare function requireBoolean(object: Record<string, unknown>, key: string): boolean;
+export declare function requireFiniteNumber(value: unknown, label: string): number;
+export declare function requireVec3(value: unknown, label?: string): Vec3;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/agent/validation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,SAAS,CAAA;AAEjC,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKrE;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,MAAM,GACV,MAAM,CAMR;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,MAAM,GACV,OAAO,CAMT;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKzE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAa,GAAG,IAAI,CAOpE"}

package/dist/agent/validation.js

@@ -0,0 +1,39 @@
+/**
+ * Agent 命令参数校验复用器(2026-10-17):所有领域命令的 validate
+ * 都组合这些函数,统一抛 `INVALID_ARGUMENT`(spec 第 12 节)。
+ */
+import { AgentApiError } from './errors';
+export function requireObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new AgentApiError('INVALID_ARGUMENT', '参数必须是对象');
+    }
+    return value;
+}
+export function requireString(object, key) {
+    const value = object[key];
+    if (typeof value !== 'string' || !value) {
+        throw new AgentApiError('INVALID_ARGUMENT', `${key} 必须是非空字符串`);
+    }
+    return value;
+}
+export function requireBoolean(object, key) {
+    const value = object[key];
+    if (typeof value !== 'boolean') {
+        throw new AgentApiError('INVALID_ARGUMENT', `${key} 必须是布尔值`);
+    }
+    return value;
+}
+export function requireFiniteNumber(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是有限数字`);
+    }
+    return value;
+}
+export function requireVec3(value, label = 'position') {
+    const object = requireObject(value);
+    return {
+        x: requireFiniteNumber(object.x, `${label}.x`),
+        y: requireFiniteNumber(object.y, `${label}.y`),
+        z: requireFiniteNumber(object.z, `${label}.z`),
+    };
+}