@aotui/runtime 1.0.0

package/dist/spi/app/app-factory.interface.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TUI App Factory Interface
+ *
+ * 第三方 App 开发者需要导出符合此接口的 factory 对象。
+ * Runtime 通过此接口创建 App 实例。
+ *
+ * [方案 B] 支持两种模式：
+ * - 传统模式：manifest + create() - 第三方 App
+ * - KernelConfig 模式：kernelConfig - SDK 工厂返回
+ *
+ * @module @aotui/runtime/spi/app-factory
+ */
+import type { IAOTUIApp } from './app.interface.js';
+import type { AOAppManifest } from './aoapp.js';
+import type { AppKernelConfig } from './app-kernel.interface.js';
+/**
+ * TUI App 工厂接口 (支持双模式)
+ *
+ * 模式 1 (传统)：第三方 App 使用
+ * @example
+ * ```typescript
+ * export const factory: TUIAppFactory = {
+ *     manifest,
+ *     create: () => new WeatherApp()
+ * };
+ * ```
+ *
+ * 模式 2 (方案 B)：SDK 工厂返回
+ * @example
+ * ```typescript
+ * export default createTUIApp({ name: 'Chat', component: ChatApp });
+ * // 返回 { kernelConfig, displayName, create: () => throw... }
+ * ```
+ */
+export interface TUIAppFactory {
+    /**
+     * App 清单 (传统模式)
+     * 包含 App 的元数据，如名称、版本、描述等。
+     */
+    readonly manifest?: AOAppManifest;
+    /**
+     * 创建 App 实例 (传统模式)
+     * 每次调用应返回一个新的 IAOTUIApp 实例。
+     * [方案 B] 新模式下此方法可能抛错，应检查 kernelConfig
+     */
+    create?(): IAOTUIApp;
+    /**
+     * [方案 B] App 内核配置
+     * 由 SDK 工厂返回，Worker Runtime 用此配置实例化 AppKernel
+     */
+    readonly kernelConfig?: AppKernelConfig;
+    /**
+     * [方案 B] 显示名称
+     * 用于日志和调试
+     */
+    readonly displayName?: string;
+}
+/**
+ * 验证对象是否为有效的 TUIAppFactory
+ *
+ * [方案 B] 支持两种模式：
+ * - 传统模式：有 manifest + create
+ * - KernelConfig 模式：有 kernelConfig
+ */
+export declare function isTUIAppFactory(obj: unknown): obj is TUIAppFactory;
+/**
+ * 检查工厂是否是 KernelConfig 模式 (方案 B)
+ */
+export declare function isKernelConfigFactory(factory: TUIAppFactory): factory is TUIAppFactory & {
+    kernelConfig: AppKernelConfig;
+};
+/**
+ * 检查工厂是否是传统模式
+ */
+export declare function isLegacyFactory(factory: TUIAppFactory): factory is TUIAppFactory & {
+    manifest: AOAppManifest;
+    create: () => IAOTUIApp;
+};

package/dist/spi/app/app-factory.interface.js

@@ -0,0 +1,49 @@
+/**
+ * TUI App Factory Interface
+ *
+ * 第三方 App 开发者需要导出符合此接口的 factory 对象。
+ * Runtime 通过此接口创建 App 实例。
+ *
+ * [方案 B] 支持两种模式：
+ * - 传统模式：manifest + create() - 第三方 App
+ * - KernelConfig 模式：kernelConfig - SDK 工厂返回
+ *
+ * @module @aotui/runtime/spi/app-factory
+ */
+/**
+ * 验证对象是否为有效的 TUIAppFactory
+ *
+ * [方案 B] 支持两种模式：
+ * - 传统模式：有 manifest + create
+ * - KernelConfig 模式：有 kernelConfig
+ */
+export function isTUIAppFactory(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    const factory = obj;
+    // 方案 B: kernelConfig 模式
+    if (factory.kernelConfig && typeof factory.kernelConfig === 'object') {
+        return true;
+    }
+    // 传统模式: manifest + create
+    if (typeof factory.manifest === 'object' && factory.manifest !== null) {
+        if (typeof factory.create === 'function') {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * 检查工厂是否是 KernelConfig 模式 (方案 B)
+ */
+export function isKernelConfigFactory(factory) {
+    return factory.kernelConfig !== undefined;
+}
+/**
+ * 检查工厂是否是传统模式
+ */
+export function isLegacyFactory(factory) {
+    return factory.manifest !== undefined && typeof factory.create === 'function';
+}
+//# sourceMappingURL=app-factory.interface.js.map

package/dist/spi/app/app-factory.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-factory.interface.js","sourceRoot":"","sources":["../../../src/spi/app/app-factory.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoDH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,GAA8B,CAAC;IAE/C,wBAAwB;IACxB,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,OAAO,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,0BAA0B;IAC1B,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QACpE,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAsB;IACxD,OAAO,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAAsB;IAClD,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC;AAClF,CAAC"}

package/dist/spi/app/app-kernel.interface.d.ts

@@ -0,0 +1,139 @@
+/**
+ * SPI Layer - AppKernel Configuration Interface
+ *
+ * App Kernel 的配置接口，由 SDK 生成，
+ * 传递给 Runtime 的 AppKernel 实例化。
+ *
+ * [方案 B] 定义在 SPI 层以解耦 SDK 和 Runtime。
+ * SDK 生成配置，Runtime 消费配置。
+ *
+ * @module @aotui/runtime/spi/app
+ */
+import type { IViewFactory } from './view-factory.interface.js';
+import type { OperationResult } from '../core/operations.js';
+import type { AppLaunchConfig } from './app-config.interface.js';
+import type { AppContext } from './store.interface.js';
+import type { AppID, DesktopID } from '../core/types.js';
+/**
+ * App-level Operation Handler
+ *
+ * 处理 App 级别（非 View 级别）的操作。
+ * 当操作没有指定 viewId 时，路由到此处理器。
+ */
+export type AppOperationHandler = (operation: string, args: Record<string, unknown>, context: {
+    appId: AppID;
+    desktopId: DesktopID;
+}) => Promise<OperationResult>;
+/**
+ * [RFC-012] App 信号策略
+ *
+ * 控制 App 何时触发 UpdateSignal。
+ *
+ * - 'auto' (默认): DOM 变化自动触发 UpdateSignal
+ * - 'manual': 仅显式调用 emitSignal() 时触发
+ * - 'never': 永不触发信号 (被动 App，如 Thought Recorder)
+ */
+export type SignalPolicy = 'auto' | 'manual' | 'never';
+/**
+ * App Kernel Configuration
+ *
+ * 由 SDK 生成的配置对象，传递给 AppKernel。
+ *
+ * @example
+ * ```typescript
+ * // SDK 端
+ * const config: AppKernelConfig = {
+ *     name: 'System Chat',
+ *     root: ChatView,  // IViewFactory
+ * };
+ *
+ * // Runtime 端 (AppKernel)
+ * const kernel = new AppKernel(config);
+ * ```
+ */
+export interface AppKernelConfig {
+    /**
+     * App 语义名称（用于对外暴露给 LLM 的 Tool 名称前缀）
+     *
+     * 约束: 仅允许 [a-zA-Z0-9_]
+     * 示例: system_ide, planning_app, terminal_app
+     *
+     * 若未提供，Runtime 会从 `name` 派生一个兼容值（向后兼容）。
+     */
+    appName?: string;
+    /**
+     * App 名称
+     * 语义化命名，用于日志和调试
+     */
+    name: string;
+    /**
+     * [RFC-013] App 描述
+     *
+     * 告诉 Agent 这个 App 是什么、什么时候该使用它。
+     * 会在 Desktop Snapshot 的 Installed Applications 中展示给 Agent。
+     *
+     * @example
+     * description: 'Agent 与 User 之间的实时对话应用。当需要与 User 对话、询问问题、报告进度时使用此 App。'
+     */
+    description?: string;
+    /** App 是什么 (用于 Desktop State 展示) */
+    whatItIs?: string;
+    /** 什么时候用 (用于 Desktop State 展示) */
+    whenToUse?: string;
+    /**
+     * 根 View 工厂 (传统模式)
+     * App 打开时自动挂载的第一个 View
+     *
+     * 注意: 与component字段互斥,Runtime会优先使用component
+     */
+    root?: IViewFactory;
+    /**
+     * [RFC-027] 根React组件 (新模式)
+     *
+     * 替代root字段,支持开发者完全控制View生命周期。
+     * 使用component时,开发者通过<View>组件声明式控制所有View。
+     *
+     * 与root互斥: Runtime会优先使用component (如果提供)
+     */
+    component?: any;
+    /**
+     * 可选：App 级操作处理器
+     * 处理未指定 viewId 的操作
+     */
+    onOperation?: AppOperationHandler;
+    /**
+     * 运行时启动配置
+     *
+     * 由 Worker Runtime 在实例化 AppKernel 时注入。
+     * 包含环境变量、初始状态等运行时信息。
+     *
+     * 注意：这不是由 SDK 设置的，而是由 Runtime 注入。
+     */
+    launchConfig?: AppLaunchConfig;
+    /**
+     * [RFC-012] 信号策略
+     *
+     * 控制此 App 何时触发 UpdateSignal 通知 Agent。
+     *
+     * - 'auto' (默认): DOM 变化自动触发，适合交互式 App
+     * - 'manual': 仅显式调用时触发，适合批量更新场景
+     * - 'never': 永不触发，适合被动 App（如 Thought Recorder）
+     *
+     * @default 'auto'
+     */
+    signalPolicy?: SignalPolicy;
+    /**
+     * [RFC-015] App 删除回调
+     *
+     * 当 App 被永久删除时调用。
+     * 用于清理持久化数据（如 DB、LocalStorage）。
+     */
+    onDelete?(context: AppContext): Promise<void> | void;
+    /**
+     * [RFC-014 Extension] 应用在 Prompt 中的角色
+     *
+     * - 'user': 默认角色，作为用户消息发送
+     * - 'assistant': 作为助手（LLM）消息发送，用于 Thought Recorder 等应用
+     */
+    promptRole?: 'user' | 'assistant';
+}

package/dist/spi/app/app-kernel.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-kernel.interface.js.map

package/dist/spi/app/app-kernel.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-kernel.interface.js","sourceRoot":"","sources":["../../../src/spi/app/app-kernel.interface.ts"],"names":[],"mappings":""}

package/dist/spi/app/app.interface.d.ts

@@ -0,0 +1,84 @@
+/**
+ * SPI Layer - App Interface
+ *
+ * 定义 App 的契约。只有接口，没有实现。
+ * AOTUIApp 抽象基类在 SDK 层。
+ */
+import type { AppID, OperationID } from '../core/types.js';
+import type { OperationContext, OperationResult } from '../core/operations.js';
+import type { AppContext } from './store.interface.js';
+/**
+ * AOTUI App 接口
+ *
+ * 所有 App 必须实现此接口。定义了 App 的生命周期和核心交互方法。
+ *
+ * 生命周期:
+ * ```
+ * onOpen() → [运行中] → onPause() → [暂停] → onResume() → [运行中] → onClose()
+ * ```
+ */
+export interface IAOTUIApp {
+    /**
+     * App 唯一标识
+     *
+     * 如果不提供，Runtime 会自动分配 (app_0, app_1, ...)
+     */
+    id?: AppID;
+    /** App 语义名称 */
+    readonly name: string;
+    /**
+     * App 打开时调用
+     *
+     * 在此方法中进行初始化工作：
+     * - 从存储加载数据
+     * - 渲染初始 UI
+     * - 设置事件监听
+     *
+     * @param context - App 运行上下文（包含 store 和 notifyUpdate）
+     * @param container - App 的 DOM 容器
+     */
+    onOpen(context: AppContext, container: HTMLElement): Promise<void>;
+    /**
+     * App 关闭时调用
+     *
+     * 在此方法中进行清理工作：
+     * - 断开网络连接
+     * - 清理定时器
+     * - 保存未持久化的状态
+     */
+    onClose(): Promise<void>;
+    /**
+     * [RFC-015] App 删除时调用（可选）
+     *
+     * 在此方法中进行数据清理工作：
+     * - 删除持久化存储 (IndexedDB, SQLite)
+     * - 删除文件
+     *
+     * 注意：onDelete() 执行完后框架会自动调用 onClose()，
+     * 所以只需关注数据清理，不需要重复资源释放逻辑。
+     */
+    onDelete?(): Promise<void>;
+    /**
+     * Desktop 暂停时调用（可选）
+     */
+    onPause?(): Promise<void>;
+    /**
+     * Desktop 恢复时调用（可选）
+     */
+    onResume?(): Promise<void>;
+    /**
+     * 处理 Agent 发送的操作
+     *
+     * @param context - 操作上下文 (包含 appId 和可选的 viewId)
+     * @param operation - 操作名称
+     * @param args - 操作参数
+     */
+    onOperation(context: OperationContext, operation: OperationID, args: Record<string, unknown>): Promise<OperationResult>;
+    /**
+     * [RFC-007] Render View Tree
+     *
+     * Optional method to render the application's view tree in Markdown format.
+     * Used for TUI snapshots.
+     */
+    renderViewTree?(): string;
+}

package/dist/spi/app/app.interface.js

@@ -0,0 +1,8 @@
+/**
+ * SPI Layer - App Interface
+ *
+ * 定义 App 的契约。只有接口，没有实现。
+ * AOTUIApp 抽象基类在 SDK 层。
+ */
+export {};
+//# sourceMappingURL=app.interface.js.map

package/dist/spi/app/app.interface.js.map

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

package/dist/spi/app/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SPI App Layer - App Developer API
+ *
+ * 面向 App 开发者的稳定接口。
+ * 开发者通过 @aotui/sdk 使用这些类型，不直接导入此模块。
+ *
+ * @module @aotui/runtime/spi/app
+ */
+export type { IViewContextCore } from './view-context-core.interface.js';
+export type { IViewContext, IView, IViewContextFull } from './view.interface.js';
+export type { IViewContextMountable, RegisterLinkOptions } from './view-context-ext.interface.js';
+export { hasMountableSupport } from './view-context-ext.interface.js';
+export type { LinkEntry, ViewBinding, BindingKey, MountViewArgsV2, MountViewResult, DismountViewArgs } from './view-link.types.js';
+export { createBindingKey } from './view-link.types.js';
+export type { IViewTree, ViewNode, ViewContextFactory, MountableViewEntry } from './view-tree.interface.js';
+export type { IAOTUIApp } from './app.interface.js';
+export type { IViewFactory } from './view-factory.interface.js';
+export type { AppKernelConfig, AppOperationHandler, SignalPolicy } from './app-kernel.interface.js';
+export type { AppContext } from './store.interface.js';
+export type { AppLaunchConfig } from './app-config.interface.js';
+export type { TUIAppFactory } from './app-factory.interface.js';
+export { isTUIAppFactory, isKernelConfigFactory, isLegacyFactory } from './app-factory.interface.js';
+export type { AOAppManifest, AOAppView, AOAppRuntime, AOAppEntry, } from './aoapp.js';
+export { validateManifest, isValidAppName } from './aoapp.js';
+export type { IRefExporter } from './ref-exporter.interface.js';
+export type { IViewMeta, IRefRegistry, ITypeToolRegistry, TypeToolDefinition, IViewLinkRegistry, IMountableViewRegistry, IOperationRegistry, IDynamicViewRegistry, IAppConfig, RegisterLinkOptions as RegisterLinkOptionsPublic, SimpleOperationHandler, } from './public-types.js';

package/dist/spi/app/index.js

@@ -0,0 +1,13 @@
+/**
+ * SPI App Layer - App Developer API
+ *
+ * 面向 App 开发者的稳定接口。
+ * 开发者通过 @aotui/sdk 使用这些类型，不直接导入此模块。
+ *
+ * @module @aotui/runtime/spi/app
+ */
+export { hasMountableSupport } from './view-context-ext.interface.js';
+export { createBindingKey } from './view-link.types.js';
+export { isTUIAppFactory, isKernelConfigFactory, isLegacyFactory } from './app-factory.interface.js';
+export { validateManifest, isValidAppName } from './aoapp.js';
+//# sourceMappingURL=index.js.map

package/dist/spi/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spi/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAatE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAoCxD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAQrG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}