app/程序文件清单与功能说明.md

# LineUp App 程序文件清单与功能说明

> 最后核验：2026-08-06（Asia/Shanghai）
>
> 本文按“模块”整理 `lineup-app/` 当前客户端代码。每个模块都说明它负责什么、对应哪些程序文件，以及它与其他模块的边界。
> LineUp App 的设计文档入口见 [设计/README.md](设计/README.md)。跨项目的 AppServer、Hermes Adapter、WuKongIM 和运行配置见[根程序文件清单](../程序文件清单与功能说明.md)。

## 一、客户端整体结构

LineUp App 不是一个直接连接 Agent 的聊天页面，而是一个由 Runtime 托管多个 App 的客户端。
用户打开的是 Tauri 桌面外壳或浏览器开发外壳；外壳启动 Runtime；Runtime 再装载系统级
Interact App 和其他 MiniApp。

```text
Tauri 桌面外壳 / Web 浏览器外壳
  → 启动装配模块
  → LineUp Runtime
      ├── 系统级 Interact App（当前包含 IM 模式）
      ├── bundled MiniApp：任务面板
      └── bundled MiniApp：白板
  → AppServer / Remote Agent
```

必须保持的边界：

- 网络连接、消息同步、本地存储、待发送队列和会话恢复只能由 Runtime 负责。
- Interact 是系统级 MiniApp，负责人与 Agent 的主要交互；其中 IM 是当前已启用的交互模式。
- 任务面板和白板是普通 `bundled` MiniApp，必须通过 MiniApp SDK 和受限 Surface 运行。
- MiniApp 不能直接访问 Transport、Conversation Store 或原始协议解析器。
- 应用内部的按钮、表单和编辑动作属于该 MiniApp 自己的业务逻辑；只有人与 Agent 的交互才进入 Interact 会话。

## 二、工作区入口模块

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| 工作区说明 | `README.md` | 当前客户端基线、开发命令、文档入口和 Host 说明。 |
| 设计文档 | `设计/README.md`、`设计/APP架构设计.md`、`设计/02.正式方案/` | 当前架构、Runtime、SDK、Surface、Capability 和 MiniApp 约束。 |
| 迭代与评审记录 | `迭代/` | 每次迭代的目标、设计评审、验收评审和遗留问题。 |
| 程序清单 | `程序文件清单与功能说明.md` | 本文，按模块说明客户端源码。 |
| Tauri/Web 工程 | `tauri/` | TypeScript 前端、Vite 工程和 Tauri Rust 外壳。 |

## 三、启动与运行外壳模块

这一层只负责“把程序启动起来”，不负责业务通信和消息处理。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| 启动装配 | `tauri/src/main.ts` | 创建 Host 适配、LineUp Runtime 和默认应用；不直接处理网络、存储或 Chat Renderer。 |
| Web 开发外壳 | `tauri/index.html`、`tauri/vite.config.ts` | 提供浏览器中的 Web Reference Host、源码别名和开发构建入口。 |
| TypeScript 工程配置 | `tauri/tsconfig.json`、`tauri/package.json`、`tauri/package-lock.json` | TypeScript 检查、Vite、Vitest、Tauri CLI 和开发脚本。 |
| Tauri 构建脚本 | `tauri/scripts/tauri.sh` | 统一调用 Tauri/Rust 工具链。 |
| Tauri 桌面外壳 | `tauri/src-tauri/src/main.rs`、`tauri/src-tauri/src/lib.rs` | 创建正式桌面窗口并运行 Tauri 应用。 |
| 桌面权限与配置 | `tauri/src-tauri/tauri.conf.json`、`tauri/src-tauri/capabilities/default.json`、`tauri/src-tauri/Info.plist`、`tauri/src-tauri/build.rs` | 窗口、应用元数据、系统权限、macOS WebView/ATS 和 Rust 构建配置。 |

## 四、Runtime 核心协调模块

Runtime 是客户端的唯一协调中心。所有 App 都通过它获得自己范围内的数据和能力。

### 4.1 Runtime 总协调

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| Runtime 总协调器 | `tauri/src/runtime/coordination/lineup-runtime.ts` | 统一持有 Transport、会话 Store、同步循环、outbox、作用域筛选、App Inbox、协议兼容和 SDK 投影。 |
| 交互内核 | `tauri/src/runtime/coordination/interaction-kernel.ts` | 解码受信消息、抑制重复消息、整理 Agent 状态、Tool/Task 投影；不直接渲染页面。 |
| Agent 交互服务 | `tauri/src/runtime/coordination/agent-interaction-service.ts` | 组织 Agent 交互请求、标准交互结果和 Runtime 内部事件。 |
| App 编排器 | `tauri/src/runtime/coordination/app-orchestrator.ts` | 根据 Agent Tool 调用启动、切换、恢复或关闭目标 MiniApp。 |
| 运行时信封 | `tauri/src/runtime/coordination/runtime-envelope.ts` | 校验 `app_scope`、`conversation_id`、`app_session_id` 等上下文，并兼容旧消息作用域。 |

### 4.2 App 实例、焦点和生命周期

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| App 实例管理 | `tauri/src/runtime/app-management/app-instance-manager.ts` | 保存每个 App instance 的状态、所属会话、父子关系和恢复信息。 |
| App 焦点管理 | `tauri/src/runtime/app-management/app-focus-manager.ts` | 维护前台 App 的焦点栈；切换应用时由 Runtime 调整，不由 MiniApp 自己决定。 |
| App 生命周期管理 | `tauri/src/runtime/app-management/app-lifecycle-manager.ts` | 统一处理启动、前台、后台、挂起、关闭、失败和恢复。 |
| App 注册表 | `tauri/src/runtime/app-management/app-registry.ts` | 保存 Runtime 已知的内置 App 及其作用域；当前包括 Interact 和 bundled MiniApp 注册信息。 |
| App Host 装配 | `tauri/src/runtime/app-management/runtime-app-host.ts` | 根据注册表找到对应 Host 装配器并挂载可信 App。 |
| App SDK 投影 | `tauri/src/runtime/app-management/app-sdk.ts` | 向系统级 App 提供受限的 Runtime 状态、消息、Inbox、工具调用和动作接口。 |

## 五、MiniApp SDK 与应用契约模块

这一层定义普通 MiniApp 如何被 Runtime 接受和运行。它不负责加载任意代码，也不直接授予系统权限。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| MiniApp 清单契约 | `tauri/src/runtime/app-management/miniapp-manifest.ts` | 定义 `system | bundled`、工具、订阅、请求能力、Surface 和最低 Host 版本，并执行静态校验。 |
| MiniApp SDK 接口 | `tauri/src/runtime/app-management/miniapp-sdk.ts` | 提供 MiniApp 自己的会话上下文、Inbox、工具进度/完成/失败/取消、生命周期、Surface 和能力请求。 |
| SDK 兼容契约 | `tauri/src/runtime/app-management/golden/miniapp-sdk-v1.json` | 冻结 SDK v1 的关键字段和示例，供实现与回归测试对照。 |
| MiniApp 工具注册 | `tauri/src/runtime/coordination/miniapp-tool-schema.ts`、`tool-router.ts` | 定义工具输入输出、目标 App、前台要求和调用路由。 |
| MiniApp 工具状态 | `tauri/src/runtime/coordination/miniapp-tool-state.ts` | 保存工具调用的状态、进度、完成、失败和取消结果。 |

## 六、Interact 系统级 App 模块

Interact 是系统级核心 App，负责人与 Agent 的交互。当前实现以 IM 为主，未来可在同一系统级
交互 App 中扩展其他交互模式。标准 `notice`、`choice`、`confirm`、`input` 等交互，都是
Agent 在会话中向用户确认信息的交互记录，不是普通 MiniApp 的内部表单组件。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| Interact App 外壳 | `tauri/src/core-apps/chat/chat-app-host.ts`、`chat-shell.ts` | 装配系统级 Interact 的可信 DOM、样式、Renderer 和 SDK。当前目录仍使用 `chat` 兼容目录名。 |
| Interact 模式管理 | `tauri/src/core-apps/chat/interaction-mode-registry.ts`、`interaction-runtime.ts` | 注册和切换 IM 等交互模式；当前默认模式为 `im`。 |
| 消息与交互卡片渲染 | `tauri/src/core-apps/chat/trusted-dom-renderers.ts`、`renderer-registry.ts` | 将 Runtime 已筛选的消息、Agent 状态、交互卡、任务、执行摘要、Surface、Capability 和 Artifact 渲染为可信 DOM。 |
| Interact 样式 | `tauri/src/core-apps/chat/styles/app.css`、`capability-card.css`、`execution-progress.css` | IM 页面、能力卡片和执行进度的视觉样式。 |
| 标准交互状态 | `tauri/src/runtime/coordination/standard-interaction-contract.ts`、`tool-call-state.ts` | 定义 Agent 提问、用户回答、过期、取消和关闭等状态；上下文中携带 IM 会话和 App 子会话标识。 |
| 任务与执行展示状态 | `tauri/src/runtime/coordination/task-state.ts`、`execution-progress-state.ts` | 分别聚合 Agent 任务进度和 ACP 执行步骤，供 Interact 展示。 |

## 七、普通 bundled MiniApp 模块

这些 App 与其他 MiniApp 使用同一套 SDK 和受限 Surface，不是系统级 App。它们的内部编辑、按钮和表单
操作不自动写入 IM；只有 Agent 通过 Tool 与它们交互时，才通过 Runtime 产生可追踪的工具调用。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| 任务面板 MiniApp | `tauri/src/core-apps/task-dashboard/task-dashboard-miniapp.ts` | 验证 MiniApp Inbox、工具进度/结果、任务创建和生命周期；Agent 可通过 `task-dashboard.open/update` 操作它。 |
| 任务面板测试 | `tauri/src/core-apps/task-dashboard/task-dashboard-miniapp.test.ts` | 验证任务面板遵守 MiniApp SDK 和工具调用边界。 |
| 白板 MiniApp | `tauri/src/core-apps/whiteboard/whiteboard-miniapp.ts` | 验证受限 Surface、内部状态编辑和 Artifact 导出；Agent 可通过 `whiteboard.open/submit` 操作它。 |
| 白板测试 | `tauri/src/core-apps/whiteboard/whiteboard-miniapp.test.ts` | 验证白板内部编辑不进入 IM transcript，导出时通过 Runtime 处理 Artifact 元数据。 |
| 参考 MiniApp 装配 | `tauri/src/runtime/app-management/reference-miniapps.ts`、`reference-miniapps.test.ts` | 注册和验证任务面板、白板等 bundled MiniApp 的 SDK 接入方式。 |

## 八、通信、协议与会话存储模块

这些模块是 Runtime 的内部基础设施，MiniApp 不得直接调用。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| AppServer 通信 | `tauri/src/runtime/communication/transport-adapter.ts` | 负责登录、发送、同步、超时处理和响应校验。 |
| 会话与消息存储 | `tauri/src/runtime/persistence/conversation-store.ts` | 保存会话、消息、cursor、outbox、App Inbox、工具/任务、摘要和 Surface/Capability 快照。 |
| Runtime v1 协议 | `tauri/src/runtime/protocol/lineup-v1.ts` | 定义和解析当前客户端兼容的 `lineup.v1` 消息及 JSON 类型。 |
| 协议黄金样例 | `tauri/src/runtime/protocol/golden/lineup-v1.json`、`golden-protocol.test.ts` | 固定兼容协议的样例，防止后续修改破坏 Agent 通信。 |
| Runtime 信封与作用域路由 | `tauri/src/runtime/coordination/runtime-envelope.ts`、`lineup-runtime.ts` | 确保消息只投递给对应的 Interact 会话或 MiniApp 子会话。 |

## 九、工具调用与标准能力模块

工具调用由 Agent 发起，但最终由 Runtime 校验、路由和记录；MiniApp 只能处理分配给自己实例的调用。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| 工具调用路由 | `tauri/src/runtime/coordination/tool-router.ts` | 根据工具描述和目标 App，将调用送到 Interact 或指定 MiniApp。 |
| 工具调用状态 | `tauri/src/runtime/coordination/tool-call-state.ts`、`miniapp-tool-state.ts` | 管理 pending、执行中、完成、失败、取消和过期等状态。 |
| 能力注册 | `tauri/src/runtime/capabilities/capability-registry.ts` | 声明能力、风险等级、可见性和参数 schema。 |
| 能力调用状态 | `tauri/src/runtime/capabilities/capability-call-state.ts` | 管理能力调用的确认、执行和最终状态。 |
| 能力执行器 | `tauri/src/runtime/capabilities/capability-executor.ts` | 调用经过授权的 Host handler，并把结果收敛为安全的 `app.result`。 |
| 能力审计 | `tauri/src/runtime/capabilities/capability-audit.ts` | 记录调用标识、能力、风险和处置，不保存敏感参数。 |
| 客户端清单 | `tauri/src/runtime/inventory/client-inventory.ts` | 生成带 revision 的客户端能力和工具清单，供 Agent 了解当前可用能力。 |

## 十、Surface、Artifact 与隔离模块

普通 bundled MiniApp 的界面运行在受限 Surface 中。Surface 是显示和交互边界，不等于 MiniApp 自己获得了系统权限。

| 中文模块名 | 对应程序 | 作用 |
|---|---|---|
| Surface 注册 | `tauri/src/runtime/surfaces/surface-registry.ts` | 保存开发期已知的 Surface Manifest，并按精确 App 标识和版本启用。 |
| Surface 实例生命周期 | `tauri/src/runtime/surfaces/surface-instance-manager.ts` | 管理 `open / ready / patch / close / restore`，处理幂等和冲突。 |
| 隔离 Surface 宿主 | `tauri/src/runtime/surfaces/isolated-surface-host.ts` | 使用 opaque-origin iframe、`sandbox="allow-scripts"`、严格 CSP 和受限 bridge。 |
| 生产 Surface 清单 | `tauri/src/runtime/surfaces/production-surface-manifest.ts` | 保存不可变资源、版本、大小、SHA-256、Ed25519、key id、最低 Host 和权限白名单。 |
| 生产准入策略 | `tauri/src/runtime/surfaces/production-surface-policy.ts` | 只允许已验证的精确 App/版本创建生产 Surface。 |
| Surface Bundle 缓存 | `tauri/src/runtime/surfaces/surface-bundle-cache.ts` | 下载、验签、大小和 SHA-256 校验、verified cache、失效与回滚。 |
| Artifact 元数据 | `tauri/src/runtime/artifacts/artifact-state.ts` | 保存 Artifact 名称、MIME、大小和完整性等元数据。 |
| Artifact 内容缓存 | `tauri/src/runtime/artifacts/artifact-content-cache.ts` | 保存由 Host 管理的短生命周期内容；具体内容不进入会话消息存储。 |

## 十一、自动化测试与契约样例

测试文件与被测模块放在同一目录，覆盖 Runtime、SDK、协议、应用生命周期和 Surface 安全边界。

| 中文测试范围 | 对应程序 | 验证内容 |
|---|---|---|
| Runtime 主流程 | `runtime/coordination/lineup-runtime.test.ts` | Core App 注册、作用域筛选、协议兼容、App Inbox 恢复、去重和 Runtime Action。 |
| App 生命周期 | `runtime/app-management/app-lifecycle-manager.test.ts`、`runtime-app-host.test.ts` | App 启动、前后台切换、关闭、恢复以及由 Registry 装载 App。 |
| MiniApp SDK 契约 | `miniapp-sdk-golden-contract.test.ts`、`golden/miniapp-sdk-v1.json` | SDK v1 字段、状态和 Golden Fixture。 |
| 参考 MiniApp | `reference-miniapps.test.ts`、`core-apps/task-dashboard/*.test.ts`、`core-apps/whiteboard/*.test.ts` | 任务面板和白板是否只通过 SDK、Tool 和 Surface 工作。 |
| 协议兼容 | `runtime/protocol/golden-protocol.test.ts`、`runtime/protocol/golden/lineup-v1.json` | `lineup.v1` 解码和兼容样例。 |
| 工具、任务和执行进度 | `runtime/coordination/*tool*.test.ts`、`task-state.test.ts`、`execution-progress-state.test.ts` | 工具调用路由、状态变化、任务聚合和执行步骤展示。 |
| 能力安全 | `runtime/capabilities/*test.ts` | 能力注册、确认、执行、失败和最小审计。 |
| Surface 与 Bundle 安全 | `runtime/surfaces/*test.ts` | 隔离宿主、实例生命周期、Manifest、验签、缓存和生产准入。 |
| 会话存储与恢复 | `runtime/persistence/conversation-store.test.ts` | 消息、cursor、outbox、Inbox 和工作区快照恢复。 |

常用命令：

```bash
cd lineup-app/tauri

# 自动化测试
npm test -- --run

# TypeScript 检查和 Web production build
npm run build

# Web Reference Host
npm run web:dev

# Tauri Desktop Host
npm run desktop:dev
```

当前文档按源码盘点；测试数量、构建结果和真实浏览器验收结果应以最近一次迭代验收记录为准。

## 十二、相关文档

- [工作区 README](README.md)：产品基线、开发入口和文档导航。
- [设计文档入口](设计/README.md)：当前设计文档的分工和权威入口。
- [APP 架构设计](设计/APP架构设计.md)：LineUp App、Runtime、MiniApp SDK、发布安全和后续路线。
- [Tauri/Web 源码导航](tauri/src/README.md)：源码目录、依赖方向和新增模块规则。
- [Tauri/Web Host README](tauri/README.md)：Host 运行、构建、行为回归和历史记录。
- [当前迭代](迭代/03.sdk_and_coreapp/03.sdk_and_coreapp.md)：MiniApp SDK v1 和内置 MiniApp 的实现定义。
- [根程序文件清单](../程序文件清单与功能说明.md)：AppServer、Hermes、WuKongIM 和运行配置。