16 KiB
16 KiB
LineUp App 程序文件清单与功能说明
最后核验：2026-08-06（Asia/Shanghai）
本文按“模块”整理
lineup-app/当前客户端代码。每个模块都说明它负责什么、对应哪些程序文件，以及它与其他模块的边界。 LineUp App 的设计文档入口见 设计/README.md。跨项目的 AppServer、Hermes Adapter、WuKongIM 和运行配置见根程序文件清单。
一、客户端整体结构
LineUp App 不是一个直接连接 Agent 的聊天页面，而是一个由 Runtime 托管多个 App 的客户端。 用户打开的是 Tauri 桌面外壳或浏览器开发外壳；外壳启动 Runtime；Runtime 再装载系统级 Interact App 和其他 MiniApp。
Tauri 桌面外壳 / Web 浏览器外壳
→ 启动装配模块
→ LineUp Runtime
├── 系统级 Interact App（当前包含 IM 模式）
├── bundled MiniApp：任务面板
└── bundled MiniApp：白板
→ AppServer / Remote Agent
必须保持的边界：
- 网络连接、消息同步、本地存储、待发送队列和会话恢复只能由 Runtime 负责。
- Interact 是系统级 MiniApp，负责人与 Agent 的主要交互；其中 IM 是当前已启用的交互模式。
- 任务面板和白板是普通
bundledMiniApp，必须通过 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 |
| 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 和工作区快照恢复。 |
常用命令：
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：产品基线、开发入口和文档导航。
- 设计文档入口：当前设计文档的分工和权威入口。
- APP 架构设计：LineUp App、Runtime、MiniApp SDK、发布安全和后续路线。
- Tauri/Web 源码导航：源码目录、依赖方向和新增模块规则。
- Tauri/Web Host README：Host 运行、构建、行为回归和历史记录。
- 当前迭代：MiniApp SDK v1 和内置 MiniApp 的实现定义。
- 根程序文件清单：AppServer、Hermes、WuKongIM 和运行配置。