@world-engines/authoring-bridge 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/contract.d.ts

@@ -0,0 +1,235 @@
+import { type AuthoringJsonSchema } from "./schemas.js";
+export type AuthoringToolDomain = "world" | "trigger" | "layout" | "retrieval" | "human" | "preview";
+export interface AuthoringToolDescriptor<Name extends string = string> {
+    readonly name: Name;
+    readonly domain: AuthoringToolDomain;
+    /** 只有修改持久化 Scenario Part 的工具才是 project effect。 */
+    readonly project_effect: boolean;
+    readonly input_schema: AuthoringJsonSchema;
+}
+declare const AUTHORING_BRIDGE_TOOL_CORES: readonly [{
+    readonly name: "world_schema";
+    readonly domain: "world";
+    readonly project_effect: false;
+}, {
+    readonly name: "spatial_template_library";
+    readonly domain: "world";
+    readonly project_effect: false;
+}, {
+    readonly name: "world_search";
+    readonly domain: "world";
+    readonly project_effect: false;
+}, {
+    readonly name: "world_get";
+    readonly domain: "world";
+    readonly project_effect: false;
+}, {
+    readonly name: "world_traverse";
+    readonly domain: "world";
+    readonly project_effect: false;
+}, {
+    readonly name: "world_apply";
+    readonly domain: "world";
+    readonly project_effect: true;
+}, {
+    readonly name: "world_history";
+    readonly domain: "world";
+    readonly project_effect: false;
+}, {
+    readonly name: "trigger_schema";
+    readonly domain: "trigger";
+    readonly project_effect: false;
+}, {
+    readonly name: "trigger_read";
+    readonly domain: "trigger";
+    readonly project_effect: false;
+}, {
+    readonly name: "trigger_apply";
+    readonly domain: "trigger";
+    readonly project_effect: true;
+}, {
+    readonly name: "trigger_validate";
+    readonly domain: "trigger";
+    readonly project_effect: false;
+}, {
+    readonly name: "trigger_simulate";
+    readonly domain: "trigger";
+    readonly project_effect: false;
+}, {
+    readonly name: "interaction_layout_read";
+    readonly domain: "layout";
+    readonly project_effect: false;
+}, {
+    readonly name: "interaction_layout_apply";
+    readonly domain: "layout";
+    readonly project_effect: true;
+}, {
+    readonly name: "trigger_blueprint_layout_read";
+    readonly domain: "layout";
+    readonly project_effect: false;
+}, {
+    readonly name: "trigger_blueprint_layout_apply";
+    readonly domain: "layout";
+    readonly project_effect: true;
+}, {
+    readonly name: "retrieval_config_read";
+    readonly domain: "retrieval";
+    readonly project_effect: false;
+}, {
+    readonly name: "retrieval_config_apply";
+    readonly domain: "retrieval";
+    readonly project_effect: true;
+}, {
+    readonly name: "retrieval_probe";
+    readonly domain: "retrieval";
+    readonly project_effect: false;
+}, {
+    readonly name: "ask_user";
+    readonly domain: "human";
+    readonly project_effect: false;
+}, {
+    readonly name: "preview_inspect";
+    readonly domain: "preview";
+    readonly project_effect: false;
+}, {
+    readonly name: "preview_interact";
+    readonly domain: "preview";
+    readonly project_effect: false;
+}];
+export type AuthoringToolName = (typeof AUTHORING_BRIDGE_TOOL_CORES)[number]["name"];
+export declare const AUTHORING_BRIDGE_TOOLS: Readonly<{
+    input_schema: AuthoringJsonSchema;
+    name: "world_schema";
+    domain: "world";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "spatial_template_library";
+    domain: "world";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "world_search";
+    domain: "world";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "world_get";
+    domain: "world";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "world_traverse";
+    domain: "world";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "world_apply";
+    domain: "world";
+    project_effect: true;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "world_history";
+    domain: "world";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_schema";
+    domain: "trigger";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_read";
+    domain: "trigger";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_apply";
+    domain: "trigger";
+    project_effect: true;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_validate";
+    domain: "trigger";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_simulate";
+    domain: "trigger";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "interaction_layout_read";
+    domain: "layout";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "interaction_layout_apply";
+    domain: "layout";
+    project_effect: true;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_blueprint_layout_read";
+    domain: "layout";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "trigger_blueprint_layout_apply";
+    domain: "layout";
+    project_effect: true;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "retrieval_config_read";
+    domain: "retrieval";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "retrieval_config_apply";
+    domain: "retrieval";
+    project_effect: true;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "retrieval_probe";
+    domain: "retrieval";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "ask_user";
+    domain: "human";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "preview_inspect";
+    domain: "preview";
+    project_effect: false;
+} | {
+    input_schema: AuthoringJsonSchema;
+    name: "preview_interact";
+    domain: "preview";
+    project_effect: false;
+}>[];
+/** exact-22 的唯一名称投影；Adapter 不得另行维护平行列表。 */
+export declare const AUTHORING_BRIDGE_TOOL_NAMES: readonly AuthoringToolName[];
+export declare function authoringToolDescriptor(name: AuthoringToolName): (typeof AUTHORING_BRIDGE_TOOLS)[number];
+export interface AuthoringEffectIdentity {
+    readonly operation_id: string;
+    readonly expected_project_revision: number;
+}
+export declare function validateAuthoringEffectIdentity(identity: AuthoringEffectIdentity): AuthoringEffectIdentity;
+export interface AuthoringToolReceiptV1 {
+    readonly schema_version: 1;
+    readonly operation_id: string;
+    readonly project_id: string;
+    readonly previous_project_revision: number;
+    readonly next_project_revision: number;
+    readonly changed_sections: readonly string[];
+    readonly project_snapshot_digest: string;
+    readonly readback_verified: boolean;
+}
+export interface AuthoringToolCall<Name extends AuthoringToolName = AuthoringToolName> {
+    readonly name: Name;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly effect_identity?: AuthoringEffectIdentity;
+}
+export declare function validateAuthoringToolCall(call: AuthoringToolCall): AuthoringToolCall;
+export {};

package/dist/contract.js

@@ -0,0 +1,67 @@
+import { AuthoringBridgeError } from "./errors.js";
+import { AUTHORING_TOOL_INPUT_SCHEMAS, validateAuthoringToolInput, } from "./schemas.js";
+const AUTHORING_BRIDGE_TOOL_CORES = [
+    { name: "world_schema", domain: "world", project_effect: false },
+    { name: "spatial_template_library", domain: "world", project_effect: false },
+    { name: "world_search", domain: "world", project_effect: false },
+    { name: "world_get", domain: "world", project_effect: false },
+    { name: "world_traverse", domain: "world", project_effect: false },
+    { name: "world_apply", domain: "world", project_effect: true },
+    { name: "world_history", domain: "world", project_effect: false },
+    { name: "trigger_schema", domain: "trigger", project_effect: false },
+    { name: "trigger_read", domain: "trigger", project_effect: false },
+    { name: "trigger_apply", domain: "trigger", project_effect: true },
+    { name: "trigger_validate", domain: "trigger", project_effect: false },
+    { name: "trigger_simulate", domain: "trigger", project_effect: false },
+    { name: "interaction_layout_read", domain: "layout", project_effect: false },
+    { name: "interaction_layout_apply", domain: "layout", project_effect: true },
+    { name: "trigger_blueprint_layout_read", domain: "layout", project_effect: false },
+    { name: "trigger_blueprint_layout_apply", domain: "layout", project_effect: true },
+    { name: "retrieval_config_read", domain: "retrieval", project_effect: false },
+    { name: "retrieval_config_apply", domain: "retrieval", project_effect: true },
+    { name: "retrieval_probe", domain: "retrieval", project_effect: false },
+    { name: "ask_user", domain: "human", project_effect: false },
+    { name: "preview_inspect", domain: "preview", project_effect: false },
+    { name: "preview_interact", domain: "preview", project_effect: false },
+];
+export const AUTHORING_BRIDGE_TOOLS = AUTHORING_BRIDGE_TOOL_CORES.map((descriptor) => Object.freeze({
+    ...descriptor,
+    input_schema: AUTHORING_TOOL_INPUT_SCHEMAS[descriptor.name],
+}));
+/** exact-22 的唯一名称投影；Adapter 不得另行维护平行列表。 */
+export const AUTHORING_BRIDGE_TOOL_NAMES = Object.freeze(AUTHORING_BRIDGE_TOOLS.map(({ name }) => name));
+const DESCRIPTORS = new Map(AUTHORING_BRIDGE_TOOLS.map((descriptor) => [descriptor.name, descriptor]));
+export function authoringToolDescriptor(name) {
+    const descriptor = DESCRIPTORS.get(name);
+    if (descriptor === undefined) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", `未知 AuthoringBridge tool：${name}`);
+    }
+    return descriptor;
+}
+export function validateAuthoringEffectIdentity(identity) {
+    if (typeof identity.operation_id !== "string" || identity.operation_id.trim().length === 0) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "operation_id 不能为空");
+    }
+    if (!Number.isSafeInteger(identity.expected_project_revision) ||
+        identity.expected_project_revision < 0) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "expected_project_revision 必须是非负安全整数");
+    }
+    return {
+        operation_id: identity.operation_id,
+        expected_project_revision: identity.expected_project_revision,
+    };
+}
+export function validateAuthoringToolCall(call) {
+    const descriptor = authoringToolDescriptor(call.name);
+    validateAuthoringToolInput(call.name, call.input);
+    if (descriptor.project_effect) {
+        if (call.effect_identity === undefined) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", `${call.name} 必须提供 effect_identity`);
+        }
+        validateAuthoringEffectIdentity(call.effect_identity);
+    }
+    else if (call.effect_identity !== undefined) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", `${call.name} 是只读或运行时工具，不接受 effect_identity`);
+    }
+    return call;
+}

package/dist/dispatcher.d.ts

@@ -0,0 +1,23 @@
+import { type AuthoringEffectIdentity, type AuthoringToolCall, type AuthoringToolDescriptor, type AuthoringToolName } from "./contract.js";
+export interface AuthoringToolDispatchContext {
+    readonly descriptor: AuthoringToolDescriptor;
+    readonly call: AuthoringToolCall;
+    readonly effect_identity: AuthoringEffectIdentity | undefined;
+}
+export type AuthoringToolHandler = (context: AuthoringToolDispatchContext) => Promise<unknown> | unknown;
+export type AuthoringToolHandlerMap = Partial<Record<AuthoringToolName, AuthoringToolHandler>>;
+/** Adapter 必须显式声明每一个可用工具；未声明即拒绝分发。 */
+export interface AuthoringBridgeAdapter {
+    readonly capabilities: ReadonlySet<AuthoringToolName> | readonly AuthoringToolName[];
+    readonly handlers: AuthoringToolHandlerMap;
+}
+/**
+ * exact-21 的唯一分发入口。它不提供 Ladybug、Trigger 或远端实现，只校验并调用 adapter。
+ */
+export declare class AuthoringBridgeDispatcher {
+    #private;
+    private readonly adapter;
+    constructor(adapter: AuthoringBridgeAdapter);
+    dispatch(call: AuthoringToolCall): Promise<unknown>;
+}
+export declare function createAuthoringBridgeDispatcher(adapter: AuthoringBridgeAdapter): AuthoringBridgeDispatcher;

package/dist/dispatcher.js

@@ -0,0 +1,97 @@
+import { authoringToolDescriptor, validateAuthoringToolCall, } from "./contract.js";
+import { AuthoringBridgeError } from "./errors.js";
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+function hasCapability(adapter, name) {
+    if ("has" in adapter.capabilities)
+        return adapter.capabilities.has(name);
+    return adapter.capabilities.includes(name);
+}
+function unavailable(kind, name) {
+    throw new AuthoringBridgeError("E_VALIDATION_FAILED", `${kind}: adapter 未提供 ${name}`, {
+        failure: kind,
+        tool_name: name,
+    });
+}
+function validateReceipt(receipt, identity) {
+    if (typeof receipt !== "object" || receipt === null || Array.isArray(receipt)) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "E_EFFECT_RECEIPT_INVALID: apply handler 未返回 receipt");
+    }
+    const value = receipt;
+    const changedSections = value.changed_sections;
+    const validSections = Array.isArray(changedSections) &&
+        changedSections.every((section) => typeof section === "string" && section.length > 0) &&
+        new Set(changedSections).size === changedSections.length;
+    const changed = changedSections?.length ?? 0;
+    const expectedNext = identity.expected_project_revision + (changed === 0 ? 0 : 1);
+    if (value.schema_version !== 1 ||
+        value.operation_id !== identity.operation_id ||
+        typeof value.project_id !== "string" ||
+        value.project_id.trim().length === 0 ||
+        value.previous_project_revision !== identity.expected_project_revision ||
+        value.next_project_revision !== expectedNext ||
+        !validSections ||
+        typeof value.project_snapshot_digest !== "string" ||
+        !/^[a-f0-9]{64}$/i.test(value.project_snapshot_digest) ||
+        value.readback_verified !== true) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "E_EFFECT_RECEIPT_INVALID: apply receipt 未通过 identity/readback 校验", {
+            operation_id: identity.operation_id,
+        });
+    }
+    return value;
+}
+/**
+ * exact-21 的唯一分发入口。它不提供 Ladybug、Trigger 或远端实现，只校验并调用 adapter。
+ */
+export class AuthoringBridgeDispatcher {
+    adapter;
+    #operations = new Map();
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    async dispatch(call) {
+        validateAuthoringToolCall(call);
+        const descriptor = authoringToolDescriptor(call.name);
+        if (!hasCapability(this.adapter, call.name))
+            unavailable("E_CAPABILITY_UNAVAILABLE", call.name);
+        const handler = this.adapter.handlers[call.name];
+        if (handler === undefined)
+            unavailable("E_HANDLER_UNAVAILABLE", call.name);
+        const effectIdentity = call.effect_identity;
+        if (!descriptor.project_effect) {
+            return handler({ descriptor, call, effect_identity: undefined });
+        }
+        const identity = effectIdentity;
+        const fingerprint = canonicalJson({
+            name: call.name,
+            input: call.input,
+            effect_identity: identity,
+        });
+        const replay = this.#operations.get(identity.operation_id);
+        if (replay !== undefined) {
+            if (replay.fingerprint !== fingerprint) {
+                throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "operation_id 已绑定到不同的 canonical call", {
+                    operation_id: identity.operation_id,
+                });
+            }
+            return replay.result;
+        }
+        const result = Promise.resolve()
+            .then(() => handler({ descriptor, call, effect_identity: identity }))
+            .then((receipt) => validateReceipt(receipt, identity));
+        this.#operations.set(identity.operation_id, { fingerprint, result });
+        return result;
+    }
+}
+export function createAuthoringBridgeDispatcher(adapter) {
+    return new AuthoringBridgeDispatcher(adapter);
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare const AUTHORING_BRIDGE_ERROR_CODES: readonly ["E_PROJECT_NOT_OPEN", "E_PROJECT_BUSY", "E_PATH_OUTSIDE_PROJECT", "E_STALE_PROJECT_REVISION", "E_SCHEMA_INVALID", "E_VALIDATION_FAILED", "E_REFERENCE_MISSING", "E_OPERATION_ID_CONFLICT", "E_OPERATION_UNCERTAIN", "E_PREVIEW_NOT_RUNNING", "E_PREVIEW_NOT_READY", "E_AUTH_REQUIRED", "E_REMOTE_FORBIDDEN", "E_CONFIRMATION_REQUIRED", "E_ROLLBACK_FAILED"];
+export type AuthoringBridgeErrorCode = (typeof AUTHORING_BRIDGE_ERROR_CODES)[number];
+export declare class AuthoringBridgeError extends Error {
+    readonly code: AuthoringBridgeErrorCode;
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: AuthoringBridgeErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+export const AUTHORING_BRIDGE_ERROR_CODES = [
+    "E_PROJECT_NOT_OPEN",
+    "E_PROJECT_BUSY",
+    "E_PATH_OUTSIDE_PROJECT",
+    "E_STALE_PROJECT_REVISION",
+    "E_SCHEMA_INVALID",
+    "E_VALIDATION_FAILED",
+    "E_REFERENCE_MISSING",
+    "E_OPERATION_ID_CONFLICT",
+    "E_OPERATION_UNCERTAIN",
+    "E_PREVIEW_NOT_RUNNING",
+    "E_PREVIEW_NOT_READY",
+    "E_AUTH_REQUIRED",
+    "E_REMOTE_FORBIDDEN",
+    "E_CONFIRMATION_REQUIRED",
+    "E_ROLLBACK_FAILED",
+];
+export class AuthoringBridgeError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "AuthoringBridgeError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./dispatcher.js";
+export * from "./errors.js";
+export * from "./schemas.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./dispatcher.js";
+export * from "./errors.js";
+export * from "./schemas.js";

package/dist/schemas.d.ts

@@ -0,0 +1,58 @@
+export interface AuthoringJsonSchema {
+    readonly type: "object" | "array" | "string" | "integer" | "boolean";
+    readonly required?: readonly string[];
+    readonly properties?: Readonly<Record<string, AuthoringJsonSchema>>;
+    readonly additionalProperties?: boolean;
+    readonly items?: AuthoringJsonSchema;
+    readonly enum?: readonly (string | number | boolean)[];
+    readonly oneOf?: readonly AuthoringJsonSchema[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minItems?: number;
+    readonly minLength?: number;
+}
+/** world_apply 内的 spatial mutation 仍由现有第 21 个 tool 承载，不能另起 tool authority。 */
+export type SpatialWorldApplyOperation = {
+    readonly type: "spatial_create";
+    readonly key: string;
+    readonly kind: "location" | "portal" | "region";
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly type: "spatial_update";
+    readonly id: string;
+    readonly label?: string;
+    readonly x?: number;
+    readonly y?: number;
+} | {
+    readonly type: "spatial_remove";
+    readonly id: string;
+    readonly confirmed: boolean;
+};
+export declare const AUTHORING_TOOL_INPUT_SCHEMAS: Readonly<{
+    readonly world_schema: AuthoringJsonSchema;
+    readonly spatial_template_library: AuthoringJsonSchema;
+    readonly world_search: AuthoringJsonSchema;
+    readonly world_get: AuthoringJsonSchema;
+    readonly world_traverse: AuthoringJsonSchema;
+    readonly world_apply: AuthoringJsonSchema;
+    readonly world_history: AuthoringJsonSchema;
+    readonly trigger_schema: AuthoringJsonSchema;
+    readonly trigger_read: AuthoringJsonSchema;
+    readonly trigger_apply: AuthoringJsonSchema;
+    readonly trigger_validate: AuthoringJsonSchema;
+    readonly trigger_simulate: AuthoringJsonSchema;
+    readonly interaction_layout_read: AuthoringJsonSchema;
+    readonly interaction_layout_apply: AuthoringJsonSchema;
+    readonly trigger_blueprint_layout_read: AuthoringJsonSchema;
+    readonly trigger_blueprint_layout_apply: AuthoringJsonSchema;
+    readonly retrieval_config_read: AuthoringJsonSchema;
+    readonly retrieval_config_apply: AuthoringJsonSchema;
+    readonly retrieval_probe: AuthoringJsonSchema;
+    readonly ask_user: AuthoringJsonSchema;
+    readonly preview_inspect: AuthoringJsonSchema;
+    readonly preview_interact: AuthoringJsonSchema;
+}>;
+export type AuthoringSchemaToolName = keyof typeof AUTHORING_TOOL_INPUT_SCHEMAS;
+export declare function validateAuthoringToolInput(name: AuthoringSchemaToolName, input: unknown): Readonly<Record<string, unknown>>;

package/dist/schemas.js

@@ -0,0 +1,190 @@
+import { AuthoringBridgeError } from "./errors.js";
+const string = (options = {}) => ({
+    type: "string",
+    ...options,
+});
+const integer = (minimum = 0, maximum) => ({ type: "integer", minimum, ...(maximum === undefined ? {} : { maximum }) });
+const array = (items, minItems = 0) => ({
+    type: "array",
+    items,
+    minItems,
+});
+const opaqueObject = { type: "object", additionalProperties: true };
+const object = (properties, required = []) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const worldGetProperties = {
+    ids: array(string({ minLength: 1 }), 1),
+    limit: integer(1, 200),
+    cursor: string({ minLength: 1 }),
+    include_relations: { type: "boolean" },
+};
+const worldGetSchema = {
+    ...object(worldGetProperties),
+    oneOf: [
+        object({ ids: worldGetProperties.ids, include_relations: worldGetProperties.include_relations }, ["ids"]),
+        object({ limit: worldGetProperties.limit, cursor: worldGetProperties.cursor, include_relations: worldGetProperties.include_relations }, ["limit"]),
+    ],
+};
+export const AUTHORING_TOOL_INPUT_SCHEMAS = Object.freeze({
+    world_schema: object({}),
+    spatial_template_library: object({}),
+    world_search: object({
+        query: string({ minLength: 1 }),
+        mode: string({ enum: ["keyword", "full_text", "semantic", "hybrid"] }),
+        limit: integer(1),
+        cursor: string(),
+        filters: opaqueObject,
+    }, ["query", "mode"]),
+    world_get: worldGetSchema,
+    world_traverse: object({
+        start_ids: array(string({ minLength: 1 }), 1),
+        scope_id: string({ minLength: 1 }),
+        direction: string({ enum: ["in", "out", "both"] }),
+        depth: integer(1, 4),
+        entity_kinds: array(string({ minLength: 1 })),
+        relation_kinds: array(string({ minLength: 1 })),
+        semantic_only: { type: "boolean" },
+        limit: integer(1, 1_000),
+    }, ["start_ids", "direction", "depth"]),
+    world_apply: object({ operations: array(opaqueObject, 1) }, ["operations"]),
+    world_history: object({ target_ids: array(string({ minLength: 1 }), 1), cursor: string(), limit: integer(1) }, ["target_ids"]),
+    trigger_schema: object({}),
+    trigger_read: object({ trigger_ids: array(string({ minLength: 1 })), include_document: { type: "boolean" } }),
+    trigger_apply: object({ operations: array(opaqueObject, 1) }, ["operations"]),
+    trigger_validate: object({ candidate_document: opaqueObject }),
+    trigger_simulate: object({ event: opaqueObject, state: opaqueObject }, ["event", "state"]),
+    interaction_layout_read: object({ viewport: string({ enum: ["pc", "mobile"] }) }, ["viewport"]),
+    interaction_layout_apply: object({ viewport: string({ enum: ["pc", "mobile"] }), patch: opaqueObject }, ["viewport", "patch"]),
+    trigger_blueprint_layout_read: object({ trigger_ids: array(string({ minLength: 1 })) }),
+    trigger_blueprint_layout_apply: object({ patch: opaqueObject }, ["patch"]),
+    retrieval_config_read: object({}),
+    retrieval_config_apply: object({ patch: opaqueObject }, ["patch"]),
+    retrieval_probe: object({ query: string({ minLength: 1 }), candidate_config: opaqueObject, top_k: integer(1) }, ["query", "candidate_config"]),
+    ask_user: object({ prompt: string({ minLength: 1 }), choices: array(string({ minLength: 1 })), allow_freeform: { type: "boolean" } }, ["prompt"]),
+    preview_inspect: object({ selector: string(), include_screenshot: { type: "boolean" }, include_console: { type: "boolean" } }),
+    preview_interact: object({
+        action: string({ enum: ["click", "type", "press", "scroll", "navigate"] }),
+        target: string({ minLength: 1 }),
+        value: string(),
+    }, ["action", "target"]),
+});
+function invalid(path, message) {
+    throw new AuthoringBridgeError("E_SCHEMA_INVALID", `${path}: ${message}`);
+}
+function validateValue(schema, value, path) {
+    if (schema.type === "string") {
+        if (typeof value !== "string")
+            invalid(path, "必须是 string");
+        if (schema.minLength !== undefined && value.length < schema.minLength)
+            invalid(path, `长度必须 >= ${schema.minLength}`);
+        if (schema.enum !== undefined && !schema.enum.includes(value))
+            invalid(path, "不在允许枚举中");
+        return;
+    }
+    if (schema.type === "integer") {
+        if (!Number.isSafeInteger(value))
+            invalid(path, "必须是安全整数");
+        if (schema.minimum !== undefined && value < schema.minimum)
+            invalid(path, `必须 >= ${schema.minimum}`);
+        if (schema.maximum !== undefined && value > schema.maximum)
+            invalid(path, `必须 <= ${schema.maximum}`);
+        return;
+    }
+    if (schema.type === "boolean") {
+        if (typeof value !== "boolean")
+            invalid(path, "必须是 boolean");
+        return;
+    }
+    if (schema.type === "array") {
+        if (!Array.isArray(value))
+            invalid(path, "必须是 array");
+        if (schema.minItems !== undefined && value.length < schema.minItems)
+            invalid(path, `元素数量必须 >= ${schema.minItems}`);
+        if (schema.items !== undefined)
+            value.forEach((item, index) => validateValue(schema.items, item, `${path}/${index}`));
+        return;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        invalid(path, "必须是 object");
+    const record = value;
+    for (const required of schema.required ?? []) {
+        if (!(required in record))
+            invalid(`${path}/${required}`, "缺少必填字段");
+    }
+    const properties = schema.properties ?? {};
+    if (schema.additionalProperties === false) {
+        for (const key of Object.keys(record)) {
+            if (!(key in properties))
+                invalid(`${path}/${key}`, "未知字段");
+        }
+    }
+    for (const [key, child] of Object.entries(properties)) {
+        if (key in record)
+            validateValue(child, record[key], `${path}/${key}`);
+    }
+    if (schema.oneOf !== undefined) {
+        const matched = schema.oneOf.filter((candidate) => {
+            try {
+                validateValue(candidate, value, path);
+                return true;
+            }
+            catch (error) {
+                if (error instanceof AuthoringBridgeError && error.code === "E_SCHEMA_INVALID")
+                    return false;
+                throw error;
+            }
+        }).length;
+        if (matched !== 1)
+            invalid(path, "必须匹配且仅匹配一个输入模式");
+    }
+}
+function validateSpatialWorldApplyOperation(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        invalid(path, "必须是 object");
+    const operation = value;
+    if (operation.type !== "spatial_create" && operation.type !== "spatial_update" && operation.type !== "spatial_remove"
+        && operation.type !== "bind_gallery_resource" && operation.type !== "unbind_resource_ref")
+        return;
+    if (typeof operation.id === "string" && operation.id.trim().length === 0)
+        invalid(`${path}/id`, "不能为空");
+    if (operation.type === "spatial_create") {
+        if (typeof operation.key !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(operation.key))
+            invalid(`${path}/key`, "必须是稳定 kebab-case key");
+        if (operation.kind !== "location" && operation.kind !== "portal" && operation.kind !== "region")
+            invalid(`${path}/kind`, "不支持的 spatial kind");
+        if (typeof operation.label !== "string" || operation.label.trim().length === 0)
+            invalid(`${path}/label`, "不能为空");
+        if (typeof operation.x !== "number" || !Number.isFinite(operation.x))
+            invalid(`${path}/x`, "必须是有限数");
+        if (typeof operation.y !== "number" || !Number.isFinite(operation.y))
+            invalid(`${path}/y`, "必须是有限数");
+    }
+    if (operation.type === "spatial_update") {
+        if (typeof operation.id !== "string" || operation.id.trim().length === 0)
+            invalid(`${path}/id`, "不能为空");
+        if (operation.label !== undefined && (typeof operation.label !== "string" || operation.label.trim().length === 0))
+            invalid(`${path}/label`, "不能为空");
+        if (operation.x !== undefined && (typeof operation.x !== "number" || !Number.isFinite(operation.x)))
+            invalid(`${path}/x`, "必须是有限数");
+        if (operation.y !== undefined && (typeof operation.y !== "number" || !Number.isFinite(operation.y)))
+            invalid(`${path}/y`, "必须是有限数");
+    }
+    if (operation.type === "spatial_remove" && (typeof operation.id !== "string" || operation.id.trim().length === 0 || typeof operation.confirmed !== "boolean"))
+        invalid(path, "spatial_remove 需要 id 和 confirmed");
+    if (operation.type === "bind_gallery_resource" || operation.type === "unbind_resource_ref") {
+        const keys = Object.keys(operation).sort();
+        if (keys.length !== 2 || keys[0] !== "path" || keys[1] !== "type" || typeof operation.path !== "string" || operation.path.trim().length === 0) {
+            invalid(path, `${operation.type} 只接受非空 path`);
+        }
+    }
+}
+export function validateAuthoringToolInput(name, input) {
+    validateValue(AUTHORING_TOOL_INPUT_SCHEMAS[name], input, `$/${name}`);
+    if (name === "world_apply")
+        input.operations.forEach((operation, index) => validateSpatialWorldApplyOperation(operation, `$/world_apply/operations/${index}`));
+    return input;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@world-engines/authoring-bridge",
+  "version": "0.1.0-alpha.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "worldengine_source_sha256": "c29e5e0ef5129b74c18e2cfa55519fcf93150138f73331436952a10aedc42453",
+  "worldengine_source_identity_provenance": {
+    "schema": "worldengine-public-namespace-projection/v1",
+    "kind": "composite-source-identity; namespace projection; not-full-source-recompile",
+    "original_name": "@worldengine/authoring-bridge",
+    "original_archive_sha256": "3f7f7639ad71921caef6fe1c6d0a61c2d8809c98cd0b717d9ff6ac949743ff7b",
+    "original_source_sha256": "e816d08bc712469b9a36cbe34bfc51fdca719b1c88d98b99e7c8782fb7177f68",
+    "projected_name": "@world-engines/authoring-bridge",
+    "package_name_mapping": {
+      "@chat/blocks-editor": "@world-engines/blocks-editor",
+      "@chat/ladybug-bridge": "@world-engines/ladybug-bridge",
+      "@chat/monaco-host": "@world-engines/monaco-host",
+      "@chat/protocol-ts": "@world-engines/protocol-ts",
+      "@chat/scenario-author-source": "@world-engines/scenario-author-source",
+      "@chat/scenario-review-snapshot": "@world-engines/scenario-review-snapshot",
+      "@chat/tmw": "@world-engines/tmw",
+      "@chat/view-exposure": "@world-engines/view-exposure",
+      "@world-engines/chatplay-vite-plugin": "@world-engines/chatplay-vite-plugin",
+      "@worldengine/agent-kit": "@world-engines/agent-kit",
+      "@worldengine/authoring-bridge": "@world-engines/authoring-bridge",
+      "@worldengine/authoring-ui": "@world-engines/authoring-ui",
+      "@worldengine/create-project": "@world-engines/create-project",
+      "@worldengine/project-format": "@world-engines/project-format",
+      "@worldengine/project-host": "@world-engines/project-host",
+      "@worldengine/project-setup": "@world-engines/project-setup",
+      "@worldengine/spatial-authoring": "@world-engines/spatial-authoring",
+      "@worldengine/view-sdk": "@world-engines/view-sdk"
+    }
+  }
+}