@aotui/runtime 1.0.0

package/dist/spi/config/types.js

@@ -0,0 +1,7 @@
+/**
+ * Runtime Configuration Types
+ *
+ * @module @aotui/runtime/spi/config
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/spi/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/spi/config/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/spi/config/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Runtime Configuration Validation
+ *
+ * @module @aotui/runtime/spi/config
+ */
+import type { RuntimeConfig } from './types.js';
+/**
+ * 验证运行时配置
+ *
+ * @throws {AOTUIError} CONFIG_INVALID 如果任何规则失败
+ */
+export declare function validateRuntimeConfig(config: RuntimeConfig): void;

package/dist/spi/config/validate.js

@@ -0,0 +1,90 @@
+/**
+ * Runtime Configuration Validation
+ *
+ * @module @aotui/runtime/spi/config
+ */
+import { AOTUIError } from '../core/errors.js';
+const VALIDATION_RULES = [
+    // Worker 规则
+    {
+        path: 'worker.timeoutMs',
+        validate: (c) => c.worker.timeoutMs >= 1000 && c.worker.timeoutMs <= 300_000,
+        message: 'worker.timeoutMs must be between 1000ms and 300000ms',
+    },
+    {
+        path: 'worker.pool.maxSize',
+        validate: (c) => c.worker.pool.maxSize >= c.worker.pool.initialSize,
+        message: 'worker.pool.maxSize must be >= worker.pool.initialSize',
+    },
+    {
+        path: 'worker.pool.initialSize',
+        validate: (c) => c.worker.pool.initialSize >= 0 && c.worker.pool.initialSize <= 100,
+        message: 'worker.pool.initialSize must be between 0 and 100',
+    },
+    {
+        path: 'worker.pool.idleTimeoutMs',
+        validate: (c) => c.worker.pool.idleTimeoutMs >= 5000 && c.worker.pool.idleTimeoutMs <= 600_000,
+        message: 'worker.pool.idleTimeoutMs must be between 5000ms and 600000ms',
+    },
+    // Bridge 规则
+    {
+        path: 'bridge.debounceMs',
+        validate: (c) => c.bridge.debounceMs >= 0 && c.bridge.debounceMs <= 5000,
+        message: 'bridge.debounceMs must be between 0ms and 5000ms',
+    },
+    // Lock 规则
+    {
+        path: 'lock.ttlMs',
+        validate: (c) => c.lock.ttlMs >= 60_000,
+        message: 'lock.ttlMs must be at least 60000ms (1 minute)',
+    },
+    // Snapshot 规则
+    {
+        path: 'snapshot.ttlMs',
+        validate: (c) => c.snapshot.ttlMs >= 60_000,
+        message: 'snapshot.ttlMs must be at least 60000ms (1 minute)',
+    },
+    // Transform 规则
+    {
+        path: 'transform.domThrottleMs',
+        validate: (c) => c.transform.domThrottleMs >= 0 && c.transform.domThrottleMs <= 1000,
+        message: 'transform.domThrottleMs must be between 0ms and 1000ms',
+    },
+    {
+        path: 'transform.maxTreeDepth',
+        validate: (c) => c.transform.maxTreeDepth >= 1 && c.transform.maxTreeDepth <= 100,
+        message: 'transform.maxTreeDepth must be between 1 and 100',
+    },
+    // Logger 规则
+    {
+        path: 'logger.maxSystemLogs',
+        validate: (c) => c.logger.maxSystemLogs >= 10 && c.logger.maxSystemLogs <= 10000,
+        message: 'logger.maxSystemLogs must be between 10 and 10000',
+    },
+    {
+        path: 'logger.maxAppLogs',
+        validate: (c) => c.logger.maxAppLogs >= 10 && c.logger.maxAppLogs <= 10000,
+        message: 'logger.maxAppLogs must be between 10 and 10000',
+    },
+];
+/**
+ * 验证运行时配置
+ *
+ * @throws {AOTUIError} CONFIG_INVALID 如果任何规则失败
+ */
+export function validateRuntimeConfig(config) {
+    const errors = [];
+    for (const rule of VALIDATION_RULES) {
+        if (!rule.validate(config)) {
+            errors.push(`[${rule.path}] ${rule.message}`);
+        }
+    }
+    if (errors.length > 0) {
+        // 使用简化的上下文对象以避免循环引用或巨大对象
+        throw new AOTUIError('CONFIG_INVALID', {
+            errors: errors.join('; '),
+            // 不要在错误消息中包含完整 config，可能会很大
+        });
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/spi/config/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/spi/config/validate.ts"],"names":[],"mappings":"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"}

package/dist/spi/core/errors.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SPI Core Layer - Error System
+ *
+ * 统一的错误处理机制，提供类型安全的错误码和结构化错误类。
+ *
+ * @module @aotui/runtime/spi/core/errors
+ */
+import type { OperationError } from './operations.js';
+/**
+ * AOTUI 错误码常量
+ *
+ * 命名规范: DOMAIN_SPECIFIC_ERROR
+ * 例如: DESKTOP_NOT_FOUND, VIEW_DUPLICATE
+ */
+export declare const ERROR_CODES: {
+    readonly DESKTOP_NOT_FOUND: "DESKTOP_NOT_FOUND";
+    readonly DESKTOP_DISPOSED: "DESKTOP_DISPOSED";
+    readonly DESKTOP_LOCKED: "DESKTOP_LOCKED";
+    readonly APP_NOT_FOUND: "APP_NOT_FOUND";
+    readonly APP_LOAD_FAILED: "APP_LOAD_FAILED";
+    readonly APP_INVALID_MANIFEST: "APP_INVALID_MANIFEST";
+    readonly APP_INVALID_EXPORT: "APP_INVALID_EXPORT";
+    readonly VIEW_NOT_FOUND: "VIEW_NOT_FOUND";
+    readonly VIEW_DUPLICATE: "VIEW_DUPLICATE";
+    readonly VIEW_PARENT_NOT_FOUND: "VIEW_PARENT_NOT_FOUND";
+    readonly VIEW_ROOT_EXISTS: "VIEW_ROOT_EXISTS";
+    readonly VIEW_MOUNTABLE_NOT_FOUND: "VIEW_MOUNTABLE_NOT_FOUND";
+    readonly VIEW_INVALID_FACTORY: "VIEW_INVALID_FACTORY";
+    readonly LINK_DUPLICATE: "LINK_DUPLICATE";
+    readonly LINK_NOT_FOUND: "LINK_NOT_FOUND";
+    readonly OPERATION_NOT_FOUND: "OPERATION_NOT_FOUND";
+    readonly OPERATION_INVALID_ARGS: "OPERATION_INVALID_ARGS";
+    readonly OPERATION_NO_HANDLER: "OPERATION_NO_HANDLER";
+    readonly OPERATION_DUPLICATE: "OPERATION_DUPLICATE";
+    readonly OPERATION_REQUIRES_CONTEXT: "OPERATION_REQUIRES_CONTEXT";
+    readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
+    readonly WORKER_NOT_STARTED: "WORKER_NOT_STARTED";
+    readonly WORKER_TERMINATED: "WORKER_TERMINATED";
+    readonly SNAPSHOT_NOT_FOUND: "SNAPSHOT_NOT_FOUND";
+    readonly SNAPSHOT_EXPIRED: "SNAPSHOT_EXPIRED";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly CONFIG_NOT_SUPPORTED: "CONFIG_NOT_SUPPORTED";
+    readonly CONTEXT_NOT_FOUND: "CONTEXT_NOT_FOUND";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+    readonly EXECUTION_FAILED: "EXECUTION_FAILED";
+};
+/**
+ * 错误码类型
+ */
+export type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+/**
+ * AOTUI 框架错误基类
+ *
+ * 提供结构化错误信息，包含类型安全的错误码和上下文数据。
+ *
+ * @example
+ * ```typescript
+ * // 抛出错误
+ * throw new AOTUIError('DESKTOP_NOT_FOUND', { desktopId: 'abc123' });
+ *
+ * // 转换为 OperationResult
+ * catch (e) {
+ *     if (AOTUIError.is(e)) {
+ *         return { success: false, error: e.toOperationError() };
+ *     }
+ * }
+ * ```
+ */
+export declare class AOTUIError extends Error {
+    /**
+     * 错误码 (类型安全)
+     */
+    readonly code: ErrorCode;
+    /**
+     * 错误上下文 (结构化调试信息)
+     */
+    readonly context: Record<string, unknown>;
+    /**
+     * 错误发生时间戳
+     */
+    readonly timestamp: number;
+    constructor(code: ErrorCode, context?: Record<string, unknown>);
+    /**
+     * 转换为 OperationError
+     *
+     * 用于在 OperationResult 中返回错误信息
+     */
+    toOperationError(): OperationError;
+    /**
+     * 类型守卫: 检查是否为 AOTUIError
+     */
+    static is(error: unknown): error is AOTUIError;
+    /**
+     * 从普通 Error 创建 AOTUIError
+     *
+     * 用于包装未知错误
+     */
+    static fromError(error: unknown, code?: ErrorCode): AOTUIError;
+    /**
+     * 格式化错误消息
+     */
+    private static formatMessage;
+}
+/**
+ * 创建 OperationError (不抛出异常)
+ *
+ * 用于构造 OperationResult.error
+ */
+export declare function createOperationError(code: ErrorCode, context?: Record<string, unknown>): OperationError;
+/**
+ * 失败的 OperationResult 快捷构造
+ */
+export declare function failedResult(code: ErrorCode, context?: Record<string, unknown>): {
+    success: false;
+    error: OperationError;
+};

package/dist/spi/core/errors.js

@@ -0,0 +1,233 @@
+/**
+ * SPI Core Layer - Error System
+ *
+ * 统一的错误处理机制，提供类型安全的错误码和结构化错误类。
+ *
+ * @module @aotui/runtime/spi/core/errors
+ */
+// ============================================================================
+// Error Code Registry (按域分组)
+// ============================================================================
+/**
+ * AOTUI 错误码常量
+ *
+ * 命名规范: DOMAIN_SPECIFIC_ERROR
+ * 例如: DESKTOP_NOT_FOUND, VIEW_DUPLICATE
+ */
+export const ERROR_CODES = {
+    // ─────────────────────────────────────────────────────────────
+    //  Desktop Domain
+    // ─────────────────────────────────────────────────────────────
+    DESKTOP_NOT_FOUND: 'DESKTOP_NOT_FOUND',
+    DESKTOP_DISPOSED: 'DESKTOP_DISPOSED',
+    DESKTOP_LOCKED: 'DESKTOP_LOCKED',
+    // ─────────────────────────────────────────────────────────────
+    //  App Domain
+    // ─────────────────────────────────────────────────────────────
+    APP_NOT_FOUND: 'APP_NOT_FOUND',
+    APP_LOAD_FAILED: 'APP_LOAD_FAILED',
+    APP_INVALID_MANIFEST: 'APP_INVALID_MANIFEST',
+    APP_INVALID_EXPORT: 'APP_INVALID_EXPORT',
+    // ─────────────────────────────────────────────────────────────
+    //  View Domain
+    // ─────────────────────────────────────────────────────────────
+    VIEW_NOT_FOUND: 'VIEW_NOT_FOUND',
+    VIEW_DUPLICATE: 'VIEW_DUPLICATE',
+    VIEW_PARENT_NOT_FOUND: 'VIEW_PARENT_NOT_FOUND',
+    VIEW_ROOT_EXISTS: 'VIEW_ROOT_EXISTS',
+    VIEW_MOUNTABLE_NOT_FOUND: 'VIEW_MOUNTABLE_NOT_FOUND',
+    VIEW_INVALID_FACTORY: 'VIEW_INVALID_FACTORY',
+    // ─────────────────────────────────────────────────────────────
+    //  ViewLink Domain (RFC-006)
+    // ─────────────────────────────────────────────────────────────
+    LINK_DUPLICATE: 'LINK_DUPLICATE',
+    LINK_NOT_FOUND: 'LINK_NOT_FOUND',
+    // ─────────────────────────────────────────────────────────────
+    //  Operation Domain
+    // ─────────────────────────────────────────────────────────────
+    OPERATION_NOT_FOUND: 'OPERATION_NOT_FOUND',
+    OPERATION_INVALID_ARGS: 'OPERATION_INVALID_ARGS',
+    OPERATION_NO_HANDLER: 'OPERATION_NO_HANDLER',
+    OPERATION_DUPLICATE: 'OPERATION_DUPLICATE',
+    OPERATION_REQUIRES_CONTEXT: 'OPERATION_REQUIRES_CONTEXT',
+    // ─────────────────────────────────────────────────────────────
+    //  Worker Domain
+    // ─────────────────────────────────────────────────────────────
+    WORKER_TIMEOUT: 'WORKER_TIMEOUT',
+    WORKER_NOT_STARTED: 'WORKER_NOT_STARTED',
+    WORKER_TERMINATED: 'WORKER_TERMINATED',
+    // ─────────────────────────────────────────────────────────────
+    //  Snapshot Domain
+    // ─────────────────────────────────────────────────────────────
+    SNAPSHOT_NOT_FOUND: 'SNAPSHOT_NOT_FOUND',
+    SNAPSHOT_EXPIRED: 'SNAPSHOT_EXPIRED',
+    // ─────────────────────────────────────────────────────────────
+    //  Config Domain
+    // ─────────────────────────────────────────────────────────────
+    CONFIG_INVALID: 'CONFIG_INVALID',
+    CONFIG_NOT_SUPPORTED: 'CONFIG_NOT_SUPPORTED',
+    // ─────────────────────────────────────────────────────────────
+    //  Context Domain (SDK)
+    // ─────────────────────────────────────────────────────────────
+    CONTEXT_NOT_FOUND: 'CONTEXT_NOT_FOUND',
+    // ─────────────────────────────────────────────────────────────
+    //  Generic
+    // ─────────────────────────────────────────────────────────────
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    NOT_IMPLEMENTED: 'NOT_IMPLEMENTED',
+    EXECUTION_FAILED: 'EXECUTION_FAILED',
+};
+/**
+ * 错误消息模板
+ *
+ * 每个错误码对应一个消息格式化函数，接收 context 参数生成人类可读的消息。
+ */
+const ERROR_MESSAGES = {
+    // Desktop
+    DESKTOP_NOT_FOUND: (c) => `Desktop '${c.desktopId ?? 'unknown'}' not found`,
+    DESKTOP_DISPOSED: (c) => `Desktop '${c.desktopId ?? 'unknown'}' has been disposed`,
+    DESKTOP_LOCKED: (c) => `Desktop '${c.desktopId ?? 'unknown'}' is locked by '${c.ownerId ?? 'unknown'}'`,
+    // App
+    APP_NOT_FOUND: (c) => `App '${c.appId ?? 'unknown'}' not found${c.desktopId ? ` in Desktop '${c.desktopId}'` : ''}`,
+    APP_LOAD_FAILED: (c) => `Failed to load app '${c.appId ?? c.modulePath ?? 'unknown'}': ${c.reason ?? 'unknown error'}`,
+    APP_INVALID_MANIFEST: (c) => `Invalid manifest for app module '${c.modulePath ?? 'unknown'}'`,
+    APP_INVALID_EXPORT: (c) => `App module '${c.modulePath ?? 'unknown'}' has invalid export: expected default or app`,
+    // View
+    VIEW_NOT_FOUND: (c) => `View '${c.viewId ?? 'unknown'}' not found`,
+    VIEW_DUPLICATE: (c) => `View '${c.viewId ?? 'unknown'}' already exists`,
+    VIEW_PARENT_NOT_FOUND: (c) => `Parent view '${c.parentId ?? 'unknown'}' not found`,
+    VIEW_ROOT_EXISTS: (c) => `Root view already exists. Remove it first.`,
+    VIEW_MOUNTABLE_NOT_FOUND: (c) => `Mountable view '${c.viewId ?? 'unknown'}' not registered`,
+    VIEW_INVALID_FACTORY: (c) => `Invalid factory for view '${c.viewId ?? 'unknown'}'. Expected function or Factory object`,
+    // ViewLink (RFC-006)
+    LINK_DUPLICATE: (c) => `Duplicate LinkID '${c.linkId ?? 'unknown'}' in parent view '${c.parentId ?? 'unknown'}'`,
+    LINK_NOT_FOUND: (c) => `Link '${c.linkId ?? 'unknown'}' not found in parent view '${c.parentId ?? 'unknown'}'`,
+    // Operation
+    OPERATION_NOT_FOUND: (c) => `Operation '${c.operationName ?? 'unknown'}' not found`,
+    OPERATION_INVALID_ARGS: (c) => `Invalid arguments for operation '${c.operationName ?? 'unknown'}': ${c.reason ?? 'validation failed'}`,
+    OPERATION_NO_HANDLER: (c) => `No handler registered for operation '${c.operationName ?? 'unknown'}'`,
+    OPERATION_DUPLICATE: (c) => `Operation '${c.operationName ?? 'unknown'}' is already registered`,
+    OPERATION_REQUIRES_CONTEXT: (c) => `Operation '${c.operationName ?? 'unknown'}' requires an App context`,
+    // Worker
+    WORKER_TIMEOUT: (c) => `Worker request timed out after ${c.timeoutMs ?? 30000}ms`,
+    WORKER_NOT_STARTED: (c) => `Worker '${c.appId ?? 'unknown'}' not started`,
+    WORKER_TERMINATED: (c) => `Worker '${c.appId ?? 'unknown'}' has been terminated`,
+    // Snapshot
+    SNAPSHOT_NOT_FOUND: (c) => `Snapshot '${c.snapshotId ?? 'unknown'}' not found`,
+    SNAPSHOT_EXPIRED: (c) => `Snapshot '${c.snapshotId ?? 'unknown'}' has expired`,
+    // Config
+    CONFIG_INVALID: (c) => `Invalid configuration: ${c.reason ?? 'unknown'}`,
+    CONFIG_NOT_SUPPORTED: (c) => `Configuration not supported: ${c.feature ?? 'unknown'}`,
+    // Context
+    CONTEXT_NOT_FOUND: (c) => `${c.contextName ?? 'Context'} not found. Ensure component is wrapped in proper Provider.`,
+    // Generic
+    INTERNAL_ERROR: (c) => `Internal error: ${c.message ?? 'unknown'}`,
+    NOT_IMPLEMENTED: (c) => `Not implemented: ${c.feature ?? 'unknown'}`,
+    EXECUTION_FAILED: (c) => `Execution failed: ${c.message ?? 'unknown'}`,
+};
+// ============================================================================
+// AOTUIError Class
+// ============================================================================
+/**
+ * AOTUI 框架错误基类
+ *
+ * 提供结构化错误信息，包含类型安全的错误码和上下文数据。
+ *
+ * @example
+ * ```typescript
+ * // 抛出错误
+ * throw new AOTUIError('DESKTOP_NOT_FOUND', { desktopId: 'abc123' });
+ *
+ * // 转换为 OperationResult
+ * catch (e) {
+ *     if (AOTUIError.is(e)) {
+ *         return { success: false, error: e.toOperationError() };
+ *     }
+ * }
+ * ```
+ */
+export class AOTUIError extends Error {
+    /**
+     * 错误码 (类型安全)
+     */
+    code;
+    /**
+     * 错误上下文 (结构化调试信息)
+     */
+    context;
+    /**
+     * 错误发生时间戳
+     */
+    timestamp;
+    constructor(code, context = {}) {
+        const message = AOTUIError.formatMessage(code, context);
+        super(message);
+        this.name = 'AOTUIError';
+        this.code = code;
+        this.context = context;
+        this.timestamp = Date.now();
+        // 保持原型链正确 (TypeScript 继承 Error 的已知问题)
+        Object.setPrototypeOf(this, AOTUIError.prototype);
+    }
+    /**
+     * 转换为 OperationError
+     *
+     * 用于在 OperationResult 中返回错误信息
+     */
+    toOperationError() {
+        return {
+            code: this.code,
+            message: this.message,
+            context: this.context,
+        };
+    }
+    /**
+     * 类型守卫: 检查是否为 AOTUIError
+     */
+    static is(error) {
+        return error instanceof AOTUIError;
+    }
+    /**
+     * 从普通 Error 创建 AOTUIError
+     *
+     * 用于包装未知错误
+     */
+    static fromError(error, code = 'INTERNAL_ERROR') {
+        if (AOTUIError.is(error)) {
+            return error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return new AOTUIError(code, { message, originalError: error });
+    }
+    /**
+     * 格式化错误消息
+     */
+    static formatMessage(code, context) {
+        const formatter = ERROR_MESSAGES[code];
+        if (formatter) {
+            return formatter(context);
+        }
+        return `[${code}]`;
+    }
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/**
+ * 创建 OperationError (不抛出异常)
+ *
+ * 用于构造 OperationResult.error
+ */
+export function createOperationError(code, context = {}) {
+    return new AOTUIError(code, context).toOperationError();
+}
+/**
+ * 失败的 OperationResult 快捷构造
+ */
+export function failedResult(code, context = {}) {
+    return {
+        success: false,
+        error: createOperationError(code, context),
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/spi/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/spi/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/spi/core/id-factory.d.ts

@@ -0,0 +1,85 @@
+/**
+ * SPI Layer - ID Factory Functions
+ *
+ * 提供类型安全的 ID 创建函数。
+ *
+ * 使用工厂函数代替直接 `as TYPE` 断言，确保 ID 格式一致性。
+ *
+ * @example
+ * ```typescript
+ * import { createDesktopId, createAppId } from '@aotui/runtime';
+ *
+ * const desktopId = createDesktopId();           // 'dt_abc12345'
+ * const customId = createDesktopId('dt_my-id');  // 'dt_my-id'
+ * const appId = createAppId(0);                   // 'app_0'
+ * ```
+ *
+ * @module @aotui/runtime/spi/core
+ */
+import type { DesktopID, AppID, ViewID, SnapshotID, OperationID } from './types.js';
+/**
+ * ID 前缀约定（内部使用）
+ *
+ * @internal
+ */
+export declare const ID_PREFIXES: {
+    readonly Desktop: "dt_";
+    readonly App: "app_";
+    readonly View: "view_";
+    readonly Snapshot: "snap_";
+    readonly Operation: "op_";
+};
+/**
+ * 创建 DesktopID
+ *
+ * @param id - 可选的自定义 ID（应包含 'dt_' 前缀）
+ * @returns Branded DesktopID
+ */
+export declare function createDesktopId(id?: string): DesktopID;
+/**
+ * 创建 AppID
+ *
+ * @param indexOrId - App 索引号或现有 ID 字符串
+ * @returns Branded AppID
+ */
+export declare function createAppId(indexOrId: number | string): AppID;
+/**
+ * 创建 ViewID
+ *
+ * @param indexOrId - View 索引号或现有 ID 字符串
+ * @returns Branded ViewID
+ */
+export declare function createViewId(indexOrId: number | string): ViewID;
+/**
+ * 创建 SnapshotID
+ *
+ * @param id - 可选的现有 ID 字符串
+ * @returns Branded SnapshotID
+ */
+export declare function createSnapshotId(id?: string): SnapshotID;
+/**
+ * 创建 OperationID
+ *
+ * @param name - 操作名称
+ * @returns Branded OperationID
+ */
+export declare function createOperationId(name: string): OperationID;
+/**
+ * 检查字符串是否为有效的 DesktopID 格式
+ *
+ * @param value - 要检查的字符串
+ * @returns 类型谓词
+ */
+export declare function isDesktopId(value: string): value is DesktopID;
+/**
+ * 检查字符串是否为有效的 AppID 格式
+ */
+export declare function isAppId(value: string): value is AppID;
+/**
+ * 检查字符串是否为有效的 ViewID 格式
+ */
+export declare function isViewId(value: string): value is ViewID;
+/**
+ * 检查字符串是否为有效的 SnapshotID 格式
+ */
+export declare function isSnapshotId(value: string): value is SnapshotID;