docs(lineup-app): reorganize program inventory by module

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

@@ -1,159 +1,205 @@
 # LineUp App 程序文件清单与功能说明
 
-> 最后核验：2026-08-04（Asia/Shanghai）
+> 最后核验：2026-08-06（Asia/Shanghai）
 >
-> 本文是 `lineup-app/` 的客户端源码导航，覆盖 Tauri/Desktop Host、Web Reference Host、
-> `LineUpRuntime`、Interact MiniApp（当前兼容名 Chat）与客户端测试。跨项目的 AppServer、Hermes Adapter、
-> WuKongIM 和运行配置见[根程序文件清单](../程序文件清单与功能说明.md)。
+> 本文按“模块”整理 `lineup-app/` 当前客户端代码。每个模块都说明它负责什么、对应哪些程序文件，以及它与其他模块的边界。
+> LineUp App 的设计文档入口见 [设计/README.md](设计/README.md)。跨项目的 AppServer、Hermes Adapter、WuKongIM 和运行配置见[根程序文件清单](../程序文件清单与功能说明.md)。
 
-## 1. 当前客户端怎样运行
+## 一、客户端整体结构
 
-LineUp 不是“聊天页面直接连 Agent”。用户首先打开的是一个运行外壳：正式交付时是 Tauri
-桌面窗口，开发和联调时可在浏览器中打开 Web Reference Host。两种外壳都会启动同一个
-Runtime；Runtime 再加载默认 Chat，并负责 Chat 与 AppServer / Remote Agent 之间的全部
-通信。
+LineUp App 不是一个直接连接 Agent 的聊天页面，而是一个由 Runtime 托管多个 App 的客户端。
+用户打开的是 Tauri 桌面外壳或浏览器开发外壳；外壳启动 Runtime；Runtime 再装载系统级
+Interact App 和其他 MiniApp。
 
 ```text
-Tauri Desktop Host / Web Reference Host
-  → main.ts（启动时把 Host、Runtime 与默认 App 接起来）
+Tauri 桌面外壳 / Web 浏览器外壳
+  → 启动装配模块
   → LineUp Runtime
-  → CoreAppRegistry → chat Core App
-  → ChatRuntimeSDK
+      ├── 系统级 Interact App（当前包含 IM 模式）
+      ├── bundled MiniApp：任务面板
+      └── bundled MiniApp：白板
   → AppServer / Remote Agent
 ```
 
-当前唯一的客户端实现与验收基线是 Tauri 2 Desktop Host + Web Reference Host。两种 Host
-复用同一份 TypeScript Runtime 与 Chat Core App，不是两套客户端。`main.ts` 只在启动时把
-Host、`LineUpRuntime` 和默认 App 接起来；网络传输、消息存储、同步循环、待发送队列、
-scope 路由和旧 `lineup.v1` 兼容都由 Runtime 统一管理。
+必须保持的边界：
 
-## 2. 工作区顶层文件
+- 网络连接、消息同步、本地存储、待发送队列和会话恢复只能由 Runtime 负责。
+- Interact 是系统级 MiniApp，负责人与 Agent 的主要交互；其中 IM 是当前已启用的交互模式。
+- 任务面板和白板是普通 `bundled` MiniApp，必须通过 MiniApp SDK 和受限 Surface 运行。
+- MiniApp 不能直接访问 Transport、Conversation Store 或原始协议解析器。
+- 应用内部的按钮、表单和编辑动作属于该 MiniApp 自己的业务逻辑；只有人与 Agent 的交互才进入 Interact 会话。
 
-| 文件 / 目录 | 功能 |
-|---|---|
-| `README.md` | LineUp App 工作区入口、当前实现摘要、开发与文档导航。 |
-| `程序文件清单与功能说明.md` | 本文：客户端源码与测试导航。 |
-| `APP架构设计.md` | LineUp App、Runtime、MiniApp SDK、Surface/Capability 安全、发布约束和后续路线。 |
-| `tauri/` | Tauri Desktop Host 与 Web Reference Host 的工程目录。 |
+## 二、工作区入口模块
 
-## 3. Tauri/Web 工程入口
+| 中文模块名 | 对应程序 | 作用 |
+|---|---|---|
+| 工作区说明 | `README.md` | 当前客户端基线、开发命令、文档入口和 Host 说明。 |
+| 设计文档 | `设计/README.md`、`设计/APP架构设计.md`、`设计/02.正式方案/` | 当前架构、Runtime、SDK、Surface、Capability 和 MiniApp 约束。 |
+| 迭代与评审记录 | `迭代/` | 每次迭代的目标、设计评审、验收评审和遗留问题。 |
+| 程序清单 | `程序文件清单与功能说明.md` | 本文，按模块说明客户端源码。 |
+| Tauri/Web 工程 | `tauri/` | TypeScript 前端、Vite 工程和 Tauri Rust 外壳。 |
 
-目录：`tauri/`
+## 三、启动与运行外壳模块
 
-| 文件 / 目录 | 功能 |
-|---|---|
-| `package.json` | Vite、Vitest、Tauri CLI 与开发/构建脚本。 |
-| `vite.config.ts` | Vite/Vitest 的 `@/ → src/` 源码别名。 |
-| `tsconfig.json` | TypeScript 严格检查与同一 `@/` 路径别名。 |
-| `index.html` | Vite 页面入口。 |
-| `scripts/tauri.sh` | Tauri/Rust 工具链包装脚本。 |
-| `src/` | TypeScript Host、Runtime、Core App 与测试。 |
-| `src-tauri/` | Tauri Rust Host、窗口配置、能力声明和图标。 |
-| `README.md` | Tauri/Web Host 的运行、构建、回归和历史里程碑。 |
+这一层只负责“把程序启动起来”，不负责业务通信和消息处理。
 
-## 4. TypeScript Runtime 与 Chat Core App
+| 中文模块名 | 对应程序 | 作用 |
+|---|---|---|
+| 启动装配 | `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 构建配置。 |
 
-目录：`tauri/src/`。完整依赖方向见 [src/README.md](tauri/src/README.md)。
+## 四、Runtime 核心协调模块
 
-### 4.1 Host 组合与 Chat Core App
+Runtime 是客户端的唯一协调中心。所有 App 都通过它获得自己范围内的数据和能力。
 
-| 文件 / 目录 | 功能 |
-|---|---|
-| `main.ts` | 应用启动装配入口：创建 Runtime，并请求通用 `RuntimeAppHost` 根据 App Registry 挂载默认 Core App。它不直接导入 Chat Renderer，也不拥有网络传输、消息存储、同步循环或待发送队列。 |
-| `core-apps/chat/chat-shell.ts` | Chat Core App 的可信 DOM Shell。 |
-| `core-apps/chat/chat-app-host.ts` | Chat Core App 的 Host 装配器：集中加载 Chat 样式、Shell、Renderer、DOM 上下文和 Chat SDK，避免这些细节进入 `main.ts`。 |
-| `core-apps/chat/trusted-dom-renderers.ts` | 已验证消息到可信 DOM：Markdown、消息、交互卡、任务、执行摘要、Surface、Capability、Artifact 与 fallback。 |
-| `core-apps/chat/renderer-registry.ts` | 按受信任 `ConversationItem.kind` 分派 Chat Renderer。 |
-| `core-apps/chat/styles/` | Chat Shell、能力卡片、执行摘要样式。 |
+### 4.1 Runtime 总协调
 
-### 4.2 App 管理、SDK 与 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` 等上下文，并兼容旧消息作用域。 |
 
-| 文件 | 功能 |
-|---|---|
-| `runtime/coordination/lineup-runtime.ts` | Runtime 唯一协调器：持有 Transport、Conversation Store、sync loop、outbox、scope 筛选、`lineup.v1` 兼容、可靠 App Inbox 与 Chat SDK 投影。 |
-| `runtime/app-management/app-registry.ts` | 本地 Core App Registry；当前静态注册默认/恢复 `chat`。 |
-| `runtime/app-management/app-sdk.ts` | 当前 Chat/IM Runtime SDK：Core App 与 Runtime 之间的受限接口；提供状态/消息订阅、Inbox ACK、Runtime Action、Tool/Task 投影。Runtime 通过 `openApp(app_scope)` 选择对应 SDK。 |
-| `runtime/app-management/runtime-app-host.ts` | 从 Runtime App Registry 解析默认 App，再通过 Core App Host Registry 找到对应装配器并挂载可信 Core App。 |
-| `runtime/coordination/interaction-kernel.ts` | 无副作用协议入口：decode、重复抑制、Agent 状态、Tool/Task 投影。 |
-| `runtime/coordination/runtime-envelope.ts` | 内部 `RuntimeEnvelope`、`app_scope + conversation_id` 校验及旧协议作用域映射。 |
-| `runtime/coordination/tool-call-state.ts` | `choice / confirm / input` 交互状态机。 |
-| `runtime/coordination/task-state.ts` | `agent.progress` 按 `operation_id` 聚合。 |
-| `runtime/coordination/execution-progress-state.ts` | 按 `execution_id` 关联 ACP 实时步骤。 |
+### 4.2 App 实例、焦点和生命周期
 
-### 4.3 通信、持久化与协议
+| 中文模块名 | 对应程序 | 作用 |
+|---|---|---|
+| 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、工具调用和动作接口。 |
 
-| 文件 | 功能 |
-|---|---|
-| `runtime/communication/transport-adapter.ts` | HTTP Transport：登录、发送、同步、超时和响应校验。 |
-| `runtime/persistence/conversation-store.ts` | 会话持久化：cursor、消息、typed outbox、App Inbox、Tool/Task、摘要、Surface/Capability 快照。 |
-| `runtime/protocol/lineup-v1.ts` | LineUp v1 受限协议模型与解析边界。 |
-| `runtime/protocol/golden/lineup-v1.json` | `lineup-v1-golden-1` Runtime compatibility fixture。 |
+## 五、MiniApp SDK 与应用契约模块
 
-### 4.4 Surface、能力、Artifact 与 Inventory
+这一层定义普通 MiniApp 如何被 Runtime 接受和运行。它不负责加载任意代码，也不直接授予系统权限。
 
-| 文件 | 功能 |
-|---|---|
-| `runtime/surfaces/surface-registry.ts` | 开发期 Surface Manifest 与本地启用注册表；仅精确 app id/version 可用。 |
-| `runtime/surfaces/surface-instance-manager.ts` | `open / ready / patch / close / restore` 的纯状态生命周期、幂等与冲突拒绝。 |
-| `runtime/surfaces/isolated-surface-host.ts` | opaque-origin iframe 宿主；`sandbox="allow-scripts"`、严格 CSP、仅受限 bridge。 |
-| `runtime/surfaces/production-surface-manifest.ts` | 生产 Manifest：immutable artifact、版本、大小、SHA-256、Ed25519、key id、最小 Host、权限 allowlist。 |
-| `runtime/surfaces/production-surface-policy.ts` | production admission policy：只允许已验证的精确 app/version 创建实例。 |
-| `runtime/surfaces/surface-bundle-cache.ts` | HTTPS 下载、Ed25519 验签、大小/SHA-256 校验、verified cache、失效与回滚。 |
-| `runtime/inventory/client-inventory.ts` | 生成 revisioned `lineup.v1.client.inventory`。 |
-| `runtime/capabilities/capability-registry.ts` | 能力声明、风险等级、可见性与参数 schema 校验。 |
-| `runtime/capabilities/capability-call-state.ts` | 能力调用状态机：`pending → approved → executing → terminal`。 |
-| `runtime/capabilities/capability-executor.ts` | 调用 Host handler，并将结果归约为安全确定的 `app.result`。 |
-| `runtime/capabilities/capability-audit.ts` | 最小审计：call id、能力、风险、处置、时间；不保存敏感参数。 |
-| `runtime/artifacts/artifact-state.ts` | Artifact 元数据状态：名称、MIME、大小、完整性。 |
-| `runtime/artifacts/artifact-content-cache.ts` | Host-owned 易失内容缓存；内容不进入 Conversation Store。 |
+| 中文模块名 | 对应程序 | 作用 |
+|---|---|---|
+| 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` | 保存工具调用的状态、进度、完成、失败和取消结果。 |
 
-## 5. Tauri Rust Host
+## 六、Interact 系统级 App 模块
 
-目录：`tauri/src-tauri/`
+Interact 是系统级核心 App，负责人与 Agent 的交互。当前实现以 IM 为主，未来可在同一系统级
+交互 App 中扩展其他交互模式。标准 `notice`、`choice`、`confirm`、`input` 等交互，都是
+Agent 在会话中向用户确认信息的交互记录，不是普通 MiniApp 的内部表单组件。
 
-| 文件 | 功能 |
-|---|---|
-| `src/main.rs` | Tauri 桌面二进制入口。 |
-| `src/lib.rs` | Tauri 应用构造与运行库入口。 |
-| `tauri.conf.json` | 窗口、应用元数据与构建配置。 |
-| `capabilities/default.json` | Tauri 权限声明；当前只保留核心默认能力。 |
-| `Info.plist` | macOS WebView / ATS 兼容配置。 |
-| `build.rs` | Tauri/Rust 构建脚本入口。 |
+| 中文模块名 | 对应程序 | 作用 |
+|---|---|---|
+| 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 展示。 |
 
-## 6. 客户端测试与构建
+## 七、普通 bundled MiniApp 模块
 
-各 `src/runtime/**` 模块的 `.test.ts` 与实现同目录放置，主要覆盖 Runtime/SDK、协议与
-Kernel、Store/App Inbox、Tool Call、Task、执行摘要、Surface、Capability、Artifact、
-生产 Bundle 与 golden fixture。
+这些 App 与其他 MiniApp 使用同一套 SDK 和受限 Surface，不是系统级 App。它们的内部编辑、按钮和表单
+操作不自动写入 IM；只有 Agent 通过 Tool 与它们交互时，才通过 Runtime 产生可追踪的工具调用。
 
-`runtime/coordination/lineup-runtime.test.ts` 覆盖 MVP-R1 的 Core App Registry、scope
-筛选、`lineup.v1` 兼容、App Inbox 恢复、去重和 Runtime Action 边界；
-`runtime/app-management/runtime-app-host.test.ts` 验证默认 Chat 由 Runtime Registry 加载。
+| 中文模块名 | 对应程序 | 作用 |
+|---|---|---|
+| 任务面板 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
 
-# Runtime / SDK / Renderer 自动化回归
+# 自动化测试
 npm test -- --run
 
-# TypeScript 检查与 Web production build
+# TypeScript 检查和 Web production build
 npm run build
 
-# Web Reference Host（Tailscale 开发）
+# Web Reference Host
 npm run web:dev
 
 # Tauri Desktop Host
 npm run desktop:dev
 ```
 
-当前验证基线：23 个测试文件、99 个测试通过，`npm run build` 通过。
+当前文档按源码盘点；测试数量、构建结果和真实浏览器验收结果应以最近一次迭代验收记录为准。
 
-## 7. 相关文档
+## 十二、相关文档
 
-- [工作区 README](README.md)：产品基线、MVP-R1、开发入口与文档导航。
-- [迭代基线与目标](迭代/00.base/00.base.md)：`00.base` 已实现内容和 `01.kernel` Runtime Kernel 目标。
-- [APP 架构设计](设计/APP架构设计.md)：LineUp App、Runtime、MiniApp SDK、发布安全与后续阶段。
-- [Tauri/Web 源码导航](tauri/src/README.md)：目录边界与依赖方向。
-- [Tauri/Web Host README](tauri/README.md)：Host 运行、构建、行为回归与历史记录。
+- [工作区 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 和运行配置。
-- [App 最终设计方案](设计/02.正式方案/app_final_design.md)：架构决策的唯一汇总入口。