@aotui/runtime 1.0.0

package/dist/spi/app/view-link.types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * SPI Layer - ViewLink Types
+ *
+ * [RFC-006] ViewLink/View ID 解耦设计的核心类型定义。
+ *
+ * 三层 ID 体系：
+ * - ViewID: App 全局唯一，Runtime BFS 分配 (view_0, view_1, ...)
+ * - LinkID: 父 View 内唯一，开发者 prefix + SDK 自动索引 (CD_0, CD_1, ...)
+ * - UniqueID: 开发者提供的业务 ID，用于跨快照匹配 (conversation:conv_456)
+ *
+ * @module @aotui/runtime/spi/app/view-link
+ */
+import type { ViewID } from '../core/types.js';
+import type { IView } from './view.interface.js';
+/**
+ * ViewLink 注册信息
+ *
+ * 当 ViewLink 组件渲染时，向 Runtime 注册此信息。
+ * 包含创建 View 所需的所有数据。
+ */
+export interface LinkEntry {
+    /**
+     * LinkID - 父 View 内唯一
+     *
+     * 格式: `${prefix}_${index}` 或显式指定
+     * 示例: "ConversationDetail_0", "settings_panel"
+     */
+    linkId: string;
+    /**
+     * UniqueID - 业务唯一标识
+     *
+     * 由开发者基于业务数据提供，用于跨快照匹配 ViewLink 和 View。
+     * 匹配键: ViewType + UniqueID
+     *
+     * 示例: "conv_456", "order_789"
+     */
+    uniqueId: string;
+    /**
+     * View 类型名称
+     *
+     * 来自 IViewFactory.displayName
+     * 与 uniqueId 组合形成跨快照匹配键
+     */
+    viewType: string;
+    /**
+     * 父 View ID
+     */
+    parentViewId: ViewID;
+    /**
+     * View 工厂函数
+     */
+    factory: (viewId: string, props?: Record<string, unknown>) => IView;
+    /**
+     * 传递给 View 的 Props (对 Agent 隐藏)
+     */
+    props?: Record<string, unknown>;
+    /**
+     * 显示标签 (用于 ViewTree 渲染)
+     */
+    label?: string;
+}
+/**
+ * View 绑定信息
+ *
+ * 当 View 通过 ViewLink 被 mount 时，记录绑定关系。
+ * 用于幂等 mount 和跨快照匹配。
+ */
+export interface ViewBinding {
+    /**
+     * 分配的 ViewID
+     */
+    viewId: ViewID;
+    /**
+     * 绑定的 UniqueID
+     */
+    uniqueId: string;
+    /**
+     * View 类型名称
+     */
+    viewType: string;
+    /**
+     * 父 View ID
+     */
+    parentViewId: ViewID;
+}
+/**
+ * 匹配键：ViewType + UniqueID
+ *
+ * 用于在 Map 中查找绑定关系
+ */
+export type BindingKey = `${string}:${string}`;
+/**
+ * 创建匹配键
+ */
+export declare function createBindingKey(viewType: string, uniqueId: string): BindingKey;
+/**
+ * Mount 操作参数 (V2)
+ *
+ * [RFC-006] 新的 mount 操作需要指定父 View 和 LinkID
+ */
+export interface MountViewArgsV2 {
+    /**
+     * App ID
+     */
+    app_id: string;
+    /**
+     * 父 View ID (ViewLink 所在的 View)
+     */
+    parent_view: string;
+    /**
+     * Link ID (父 View 内唯一)
+     */
+    link_id: string;
+}
+/**
+ * Mount 操作结果
+ */
+export interface MountViewResult {
+    /**
+     * 挂载的 View ID
+     */
+    viewId: ViewID;
+    /**
+     * 执行的动作
+     * - MOUNTED: 新创建并挂载
+     * - ALREADY_MOUNTED: 已存在，幂等返回
+     */
+    action: 'MOUNTED' | 'ALREADY_MOUNTED';
+}
+/**
+ * Dismount 操作参数 (不变)
+ */
+export interface DismountViewArgs {
+    app_id: string;
+    view_id: string;
+}

package/dist/spi/app/view-link.types.js

@@ -0,0 +1,19 @@
+/**
+ * SPI Layer - ViewLink Types
+ *
+ * [RFC-006] ViewLink/View ID 解耦设计的核心类型定义。
+ *
+ * 三层 ID 体系：
+ * - ViewID: App 全局唯一，Runtime BFS 分配 (view_0, view_1, ...)
+ * - LinkID: 父 View 内唯一，开发者 prefix + SDK 自动索引 (CD_0, CD_1, ...)
+ * - UniqueID: 开发者提供的业务 ID，用于跨快照匹配 (conversation:conv_456)
+ *
+ * @module @aotui/runtime/spi/app/view-link
+ */
+/**
+ * 创建匹配键
+ */
+export function createBindingKey(viewType, uniqueId) {
+    return `${viewType}:${uniqueId}`;
+}
+//# sourceMappingURL=view-link.types.js.map

package/dist/spi/app/view-link.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-link.types.js","sourceRoot":"","sources":["../../../src/spi/app/view-link.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkGH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,QAAgB;IAC/D,OAAO,GAAG,QAAQ,IAAI,QAAQ,EAAgB,CAAC;AACnD,CAAC"}

package/dist/spi/app/view-tree.interface.d.ts

@@ -0,0 +1,254 @@
+/**
+ * SPI Layer - IViewTree Interface
+ *
+ * Defines the contract for View tree management.
+ * SDK should depend on this interface, not the Engine implementation.
+ *
+ * [B1 FIX] Extracted from engine/view/types.ts to SPI layer
+ * for proper dependency inversion.
+ *
+ * [RFC-011] Extended with ViewLink and Mountable methods.
+ */
+import type { ViewID } from '../core/types.js';
+import type { IView, IViewContext } from './view.interface.js';
+import type { LinkEntry } from './view-link.types.js';
+/**
+ * View 树节点
+ *
+ * 封装 View 及其在树中的位置信息
+ */
+export interface ViewNode {
+    /** View 实例 */
+    readonly view: IView;
+    /** 父节点 ID (根节点为 null) */
+    readonly parentId: ViewID | null;
+    /** 子节点 ID 列表 */
+    readonly childIds: readonly ViewID[];
+    /** 是否已 mount */
+    mounted: boolean;
+}
+/**
+ * [RFC-006] Mountable View Entry
+ *
+ * 存储尚未实例化的可挂载视图信息。
+ * 当 ViewLink 注册时，只缓存工厂和属性；
+ * 当 Agent 调用 mount_view 时，才实际创建 View 实例。
+ */
+export interface MountableViewEntry {
+    /** View 工厂函数 */
+    factory: (viewId: string, props?: Record<string, unknown>) => IView;
+    /** 初始化属性 */
+    props?: Record<string, unknown>;
+    /** 父视图 ID */
+    parentId: ViewID;
+    /** 显示标签 */
+    label?: string;
+}
+/**
+ * ViewContext 工厂函数类型
+ *
+ * 由 App 提供，用于为每个 View 创建运行上下文。
+ */
+export type ViewContextFactory = (viewId: ViewID) => IViewContext;
+/**
+ * View 树接口
+ *
+ * 维护 App 的完整 View 层级结构。
+ *
+ * [P1 FIX] SDK 必须实现此接口来管理其内部 View 状态。
+ * Runtime 不提供此接口的实现，而是通过 DOM Snapshot 获取 View 结构。
+ *
+ * SSOT (Single Source of Truth):
+ * - SDK: 只有 ViewTree 实体，管理 View 实例生命周期。
+ * - Runtime: 通过 DOM 投影观察 View 结构。
+ *
+ * View 树结构示例:
+ * ```
+ * - [Navigation](view:view_0, mounted)
+ *     - [Conversations](view:view_1, mounted)
+ *         - [Johnny Chat](view:view_3, mounted)
+ *         - [Group Chat](view:view_4)
+ *     - [Contacts](view:view_2)
+ * ```
+ */
+export interface IViewTree {
+    /** 根节点 ID */
+    readonly rootId: ViewID | null;
+    /**
+     * 获取节点
+     */
+    getNode(viewId: ViewID): ViewNode | undefined;
+    /**
+     * 获取 View
+     */
+    getView(viewId: ViewID): IView | undefined;
+    /**
+     * 添加 View 到树
+     *
+     * @param view - View 实例
+     * @param parentId - 父节点 ID (根节点传 null)
+     */
+    addView(view: IView, parentId: ViewID | null): void;
+    /**
+     * 移除 View (及其子树)
+     */
+    removeView(viewId: ViewID): void;
+    /**
+     * Mount View
+     *
+     * 调用 view.onMount() 并标记为 mounted
+     */
+    mountView(viewId: ViewID): Promise<void>;
+    /**
+     * Dismount View
+     *
+     * 先 dismount 所有子 View，再调用 view.onDismount()
+     */
+    dismountView(viewId: ViewID): Promise<void>;
+    /**
+     * 获取所有已 mount 的 View
+     */
+    getMountedViews(): IView[];
+    /**
+     * 获取 View 的完整路径 (从根到此节点)
+     */
+    getPath(viewId: ViewID): ViewID[];
+    /**
+     * 获取子 View
+     */
+    getChildren(viewId: ViewID): IView[];
+    /**
+     * 渲染 View Tree 状态
+     *
+     * 输出 TUI 格式:
+     * ```
+     * ## Application View Tree
+     * - [Navigation](view:view_0, mounted)
+     *     - [Conversations](view:view_1, mounted)
+     *     - [Contacts](view:view_2)
+     * ```
+     */
+    renderTree(): string;
+    /**
+     * 渲染所有已 mount 的 View 内容
+     */
+    renderMountedViews(): string;
+    /**
+     * 注册可挂载视图 (V1 Legacy)
+     *
+     * @param viewId - 预生成的 View ID
+     * @param parentId - 父视图 ID
+     * @param factory - View 工厂函数
+     * @param props - 初始化属性
+     * @param label - 显示标签
+     */
+    registerMountableView(viewId: ViewID, parentId: ViewID, factory: (viewId: string, props?: Record<string, unknown>) => IView, props?: Record<string, unknown>, label?: string): void;
+    /**
+     * 注销可挂载视图
+     */
+    unregisterMountableView(viewId: ViewID): void;
+    /**
+     * 获取可挂载视图条目
+     */
+    getMountableEntry(viewId: ViewID): MountableViewEntry | undefined;
+    /**
+     * 挂载已注册的可挂载视图
+     */
+    mountMountableView(viewId: ViewID): Promise<void>;
+    /**
+     * 检查是否为已注册但未实例化的可挂载视图
+     */
+    isMountableView(viewId: ViewID): boolean;
+    /**
+     * 获取父视图下所有未挂载的子视图 ID
+     */
+    getMountableChildren(parentId: ViewID): ViewID[];
+    /**
+     * 分配唯一的 LinkID
+     *
+     * @param parentId - 父视图 ID
+     * @param prefix - ID 前缀 (通常是 viewType)
+     * @returns 生成的 LinkID (如 "Chat_0")
+     */
+    allocateLinkId(parentId: ViewID, prefix: string): string;
+    /**
+     * 注册 ViewLink
+     *
+     * @param parentId - 父视图 ID
+     * @param entry - Link 条目数据
+     */
+    registerLink(parentId: ViewID, entry: LinkEntry): void;
+    /**
+     * 注销 ViewLink
+     *
+     * @param parentId - 父视图 ID
+     * @param linkId - Link ID
+     */
+    unregisterLink(parentId: ViewID, linkId: string): void;
+    /**
+     * 获取绑定的 ViewID
+     *
+     * 通过 ViewType + UniqueID 组合查找已挂载的 View。
+     * 用于跨 Snapshot 的视图匹配。
+     *
+     * @param viewType - 视图类型
+     * @param uniqueId - 唯一标识符
+     * @returns 已绑定的 ViewID，未找到返回 undefined
+     */
+    getBoundViewId(viewType: string, uniqueId: string): ViewID | undefined;
+    /**
+     * 通过 ViewLink 挂载视图
+     *
+     * 当 Agent 执行 mount(parent_view, link_id) 时调用。
+     *
+     * @param parentId - 父视图 ID
+     * @param linkId - Link ID
+     * @returns 挂载后的 ViewID
+     */
+    mountByLink(parentId: ViewID, linkId: string): Promise<ViewID>;
+    /**
+     * 获取父视图下所有 Link 条目
+     *
+     * @param parentId - 父视图 ID
+     * @returns Link 条目列表
+     */
+    getLinksInParent(parentId: ViewID): LinkEntry[];
+    /**
+     * 重置 Link 计数器
+     *
+     * 在每次渲染周期开始时调用。
+     *
+     * @param parentId - 父视图 ID
+     */
+    resetLinkCounters(parentId: ViewID): void;
+    /**
+     * 清除父视图下所有 Links
+     *
+     * 当父视图被卸载时调用。
+     *
+     * @param parentId - 父视图 ID
+     */
+    clearLinksForParent(parentId: ViewID): void;
+    /**
+     * 注册组件模式View (from SDK's View component)
+     *
+     * Component-mode Views:
+     * - Are registered directly without parent (flat structure)
+     * - Manage their own mounted state via React lifecycle
+     * - Don't participate in traditional ViewTree hierarchy
+     *
+     * This method unifies View storage, making ViewTree the single source of truth
+     * for both traditional-mode and component-mode Views.
+     *
+     * @param view - IView instance created by createInlineView()
+     */
+    registerComponentView(view: IView): void;
+    /**
+     * 注销组件模式View
+     *
+     * Called when SDK View component unmounts (via useLayoutEffect cleanup)
+     *
+     * @param viewId - View ID to unregister
+     */
+    unregisterComponentView(viewId: ViewID): void;
+}

package/dist/spi/app/view-tree.interface.js

@@ -0,0 +1,13 @@
+/**
+ * SPI Layer - IViewTree Interface
+ *
+ * Defines the contract for View tree management.
+ * SDK should depend on this interface, not the Engine implementation.
+ *
+ * [B1 FIX] Extracted from engine/view/types.ts to SPI layer
+ * for proper dependency inversion.
+ *
+ * [RFC-011] Extended with ViewLink and Mountable methods.
+ */
+export {};
+//# sourceMappingURL=view-tree.interface.js.map

package/dist/spi/app/view-tree.interface.js.map

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

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

@@ -0,0 +1,122 @@
+/**
+ * SPI Layer - IView Interface
+ *
+ * [H1 FIX] 从 Engine 层提取的 View 接口定义。
+ *
+ * View 是 App 内部的 UI 组件单元。每个 View:
+ * - 有自己的数据状态
+ * - 有自己的操作集合 (operations)
+ * - 可以被 mount/dismount
+ * - 处理针对自己的操作
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { OperationID, ViewID } from '../core/types.js';
+import type { OperationResult } from '../core/operations.js';
+import type { IViewContextCore } from './view-context-core.interface.js';
+/**
+ * Level 2: View 运行上下文 (Full Contract)
+ *
+ * SDK 内部使用的完整上下文，包含生命周期管理能力。
+ * 继承自 Core 契约。
+ */
+export interface IViewContext extends IViewContextCore {
+    /**
+     * [Option D] 标记 View 为 dirty
+     *
+     * Runtime 会在收到 DOM_UPDATE 后检查 dirty 标记，才实际发送 UpdateSignal。
+     */
+    markDirty(): void;
+    /**
+     * 请求 mount 子 View
+     */
+    mountChildView(viewId: ViewID): Promise<void>;
+    /**
+     * 请求 dismount 子 View
+     */
+    dismountChildView(viewId: ViewID): Promise<void>;
+    /**
+     * Register a dynamic child view
+     *
+     * Called by `<ChildView>` component to register a dynamically created view.
+     * The system assigns a sequential ViewID (view_0, view_1, ...).
+     *
+     * @param view - The IView instance to register
+     * @returns The assigned ViewID
+     */
+    registerChildView(view: IView): ViewID;
+    /**
+     * Unregister a dynamic child view
+     *
+     * Called when `<ChildView>` unmounts. Dismounts and removes the view.
+     *
+     * @param viewId - The ViewID to unregister
+     */
+    unregisterChildView(viewId: ViewID): void;
+}
+import type { IViewContextMountable } from './view-context-ext.interface.js';
+/**
+ * Level 2+3: Full ViewContext (Composite Type)
+ *
+ * SDK 内部使用的完整上下文，包含 Core + Full + Mountable 所有能力。
+ * 用于 AppRuntime 创建的实际 context 对象。
+ */
+export type IViewContextFull = IViewContext & IViewContextMountable;
+/**
+ * AOTUI View 接口
+ *
+ * View 是 App 内部的 UI 组件单元。每个 View:
+ * - 有自己的数据状态
+ * - 有自己的操作集合 (operations)
+ * - 可以被 mount/dismount
+ * - 处理针对自己的操作
+ */
+export interface IView {
+    /** View 唯一标识符 (developer-specified in component mode) */
+    readonly id: ViewID;
+    /** View 显示名称 (开发者定义的语义名称) */
+    readonly name?: string;
+    /**
+     * View 的显示名称，用于调试、日志和开发工具。
+     * @optional
+     */
+    readonly displayName?: string;
+    /**
+     * View 类型 (用于Tool聚合)
+     *
+     * Multiple views can share the same type.
+     * Used for grouping tools by view type in Snapshot.
+     *
+     * @optional
+     * @example "FileDetail", "UserProfile", "Workspace"
+     */
+    readonly type?: string;
+    /**
+     * 由 Runtime 调用设置 ID (可选，框架内部使用)
+     */
+    setId?(newId: ViewID): void;
+    /**
+     * View 被 mount 时调用
+     *
+     * @param context - View 运行上下文
+     */
+    onMount(context: IViewContext): Promise<void>;
+    /**
+     * View 被 dismount 时调用
+     */
+    onDismount(): Promise<void>;
+    /**
+     * 处理针对此 View 的操作
+     *
+     * @param operation - 操作名称 (如 'send_message')
+     * @param args - 操作参数
+     * @returns 操作执行结果
+     */
+    onOperation(operation: OperationID, args: Record<string, unknown>): Promise<OperationResult>;
+    /**
+     * 渲染 View 内容
+     *
+     * 返回 TUI Markdown 格式的内容
+     */
+    render(): string;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * SPI Layer - IView Interface
+ *
+ * [H1 FIX] 从 Engine 层提取的 View 接口定义。
+ *
+ * View 是 App 内部的 UI 组件单元。每个 View:
+ * - 有自己的数据状态
+ * - 有自己的操作集合 (operations)
+ * - 可以被 mount/dismount
+ * - 处理针对自己的操作
+ *
+ * @module @aotui/runtime/spi
+ */
+export {};
+//# sourceMappingURL=view.interface.js.map

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

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

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

@@ -0,0 +1,118 @@
+/**
+ * IBridge - Agent 与 Runtime 的 I/O 边界
+ *
+ * 这是 Agent（或 AgentDriver）与 AOTUI Runtime 交互的唯一接口。
+ *
+ * 设计原则：
+ * - 完全解耦：不暴露 Kernel 内部类型（如 SnapshotID）
+ * - 可替换：支持 Mock、HTTP、WebSocket 等多种实现
+ * - 简单：只提供 Agent 真正需要的能力
+ *
+ * @example
+ * ```typescript
+ * // 获取快照
+ * const snapshot = await bridge.getSnapshot();
+ * console.log(snapshot.markup);
+ *
+ * // 执行操作
+ * const results = await bridge.execute(
+ *     [{ name: 'send_message', args: { content: 'Hello' }, context: {} }],
+ *     snapshot.id
+ * );
+ *
+ * // 订阅更新
+ * const unsubscribe = bridge.subscribe(() => {
+ *     console.log('Desktop updated');
+ * });
+ * ```
+ *
+ * @module @aotui/runtime/spi/bridge
+ */
+import type { Operation, OperationResult } from '../core/operations.js';
+import type { SnapshotID } from '../core/types.js';
+import type { LLMOutputEventMeta } from '../core/llm-output.js';
+/**
+ * Agent 可见的快照
+ *
+ * 与内部的 CachedSnapshot 不同，这是面向外部消费者的简化视图。
+ * 不暴露 Runtime 内部类型，只提供 Agent 需要的信息。
+ */
+export interface BridgeSnapshot {
+    /** 快照唯一标识（用于 execute 时绑定操作） */
+    readonly id: string;
+    /** TUI Markdown 内容 */
+    readonly markup: string;
+    /** 快照生成时间戳 (ms) */
+    readonly timestamp: number;
+}
+/**
+ * IBridge - Agent 与 Runtime 的 I/O 边界
+ *
+ * 职责：
+ * 1. 获取/释放 Snapshot（Agent 视图）
+ * 2. 执行 Operations
+ * 3. 订阅更新信号
+ *
+ * 实现者：
+ * - Bridge（标准实现，依赖 IKernel）
+ * - MockBridge（测试用）
+ * - HttpBridge（远程调用，未来扩展）
+ */
+export interface IBridge {
+    /**
+     * 获取当前 Desktop 的最新快照
+     *
+     * 每次调用都会生成新的快照。调用者应在操作完成后
+     * 调用 releaseSnapshot() 释放资源（可选）。
+     *
+     * @returns 最新的 Desktop 快照
+     */
+    getSnapshot(): Promise<BridgeSnapshot>;
+    /**
+     * 释放快照资源
+     *
+     * 可选方法。如果不调用，快照将在 TTL 后自动过期。
+     * 显式释放可以更快回收内存。
+     *
+     * @param snapshotId - 要释放的快照 ID
+     */
+    releaseSnapshot?(snapshotId: string): void;
+    /**
+     * 执行一批操作
+     *
+     * 所有操作绑定到同一个 snapshotId，保证时间安全。
+     * 当 Agent 执行操作时调用此方法。
+     *
+     * @param operations - 要执行的操作列表
+     * @param snapshotId - 基于哪个快照执行
+     */
+    executeOperations(operations: Operation[], snapshotId: SnapshotID): Promise<OperationResult[]>;
+    /**
+     * 推送 LLM 文本到 Runtime (RFC-011)
+     *
+     * [RFC-020] 支持结构化格式，包含 reasoning 和 content
+     * 用于将 LLM 的思考过程或回复文本实时推送到 Desktop。
+     * 可选方法 - 老版本 Bridge 实现不受影响。
+     *
+     * @param payload - 结构化内容 { reasoning?: 思考过程, content?: 最终回复 }
+     * @param type - 事件类型 (complete=完整消息, chunk=流式片段预留)
+     * @param meta - 可选元数据 (model, role)
+     * @since RFC-011, RFC-020
+     */
+    pushLLMOutput?(payload: {
+        reasoning?: string;
+        content?: string;
+    }, type: 'complete', meta?: LLMOutputEventMeta): void;
+    /**
+     * 订阅 Desktop 状态变化
+     *
+     * 当 Desktop 中的任何 App 触发 UpdateSignal 时，
+     * 注册的 listener 会被调用。
+     *
+     * 典型用法：收到更新后重新获取快照。
+     *
+     * @param listener - 状态变化回调（无参数，调用者应自行获取新快照）
+     * @returns 取消订阅函数
+     */
+    subscribe(listener: () => void): () => void;
+}