# 01|桌面客户端双实例陪伴与本机运维系统 > 文档名称:`01_桌面客户端双实例陪伴与本机运维系统.md` > 项目:AstrBot Windows 桌面客户端 > 文档状态:架构重构版,可交给 Codex 分阶段开发 > 日期:2026-07-18 > 目标读者:Codex、桌面客户端开发者、AstrBot 插件开发者、测试与发布人员 --- ## 1. 执行摘要 本项目不再建设项目工作区、VM 任务投递、代码编辑、Git 管理或 Codex 控制台。上述开发工作继续由桌面 Codex 与 VM 交付流程承担。 桌面客户端重新定位为: > **AstrBot 的 Windows 陪伴与本机助手客户端。** 核心能力包括: 1. 文字聊天与多会话; 2. 语音聊天; 3. 主动消息与桌面通知; 4. 游戏陪伴与有限窗口感知; 5. 用户主动发起的电脑问题诊断; 6. 受控的本地文件整理与 NAS 归档; 7. 同时连接两个 AstrBot 实例,一个作为陪伴实例,一个作为运维实例。 最终推荐技术方案: ```text Tauri 2 React + TypeScript + Vite Rust Native Core SQLite Windows Credential Manager / DPAPI REST + SSE(MVP) WebSocket(连续语音或高频事件的后续扩展) ``` 双实例的产品规则为: ```text 可保存多个 ConnectionProfile MVP 最多同时激活两个连接槽位 ├─ Companion Slot:陪伴实例 └─ Operations Slot:运维实例 ``` 两个实例可以: - 并排显示为两个对话框; - 切换为单面板标签模式; - 分别保持连接、会话、未读状态和主动消息; - 使用不同的 AstrBot 地址、账号、人格和插件; - 在本地数据层完全隔离。 重要安全结论: > 只有运维实例可以申请本机诊断和文件操作;服务端请求只是操作提案,最终是否执行由客户端本地策略引擎和用户确认决定。 --- ## 2. 产品定位与范围调整 ### 2.1 新定位 ```text AstrBot Companion Desktop ├─ 陪伴沟通 ├─ 主动交互 ├─ 游戏陪伴 ├─ 电脑问题诊断 └─ 安全文件助手 ``` ### 2.2 不再承担的职责 以下内容从桌面客户端项目中删除: - 项目工作区; - 代码编辑器; - VM 任务投递; - Codex 对话与开发任务管理; - Git 仓库管理; - 内置终端; - 通用 Agent 编排控制台; - 代码补丁审查; - 项目文件同步; - 开发环境远程执行。 ### 2.3 与 Codex 的边界 ```text 桌面 Codex + VM 负责: - 编程 - Git - 构建与部署 - 插件开发 - 项目任务 AstrBot Desktop 负责: - 文字和语音交流 - 主动陪伴 - 游戏陪伴 - 日常电脑诊断 - 文件与 NAS 整理 ``` 两个系统不需要在首版互相嵌入。 --- ## 3. 需求审视与关键修正 ### 3.1 双 AstrBot 不应实现成两个独立客户端进程 推荐在一个桌面客户端内维护两个独立连接槽位,而不是启动两个应用实例。 原因: - 单实例、托盘和自动更新更简单; - 麦克风、通知和窗口捕获权限不会冲突; - 可以统一管理本机工具授权; - 用户可以并排查看,也可以快速切换; - 避免两个客户端同时读取或移动同一文件。 ### 3.2 “两个实例同时在线”不等于“无限多实例同时在线” MVP 允许保存任意数量的连接配置,但只允许两个活动连接槽位。 ```text Saved Profiles:N 个 Active Slots:最多 2 个 ``` 后续若确有需求,再考虑增加更多活动连接。 ### 3.3 陪伴实例和运维实例必须权限隔离 不能仅依赖提示词区分角色。 必须在客户端本地绑定: ```text profile_id role server_instance_id certificate_fingerprint local_tool_policy_id ``` 陪伴实例默认无本机工具权限。运维实例也只能申请本地工具白名单中的操作。 ### 3.4 电脑诊断不等于任意电脑控制 MVP 支持: - 读取用户选择的日志和配置; - 读取当前报错窗口文字; - 查询进程、端口、服务、磁盘和网络; - 查询相关 Windows 事件日志; - 生成诊断报告; - 规划并执行可恢复的文件复制或移动。 MVP 不支持: - 任意 PowerShell; - 任意 CMD; - 自动接受 UAC; - 任意注册表修改; - 无确认安装或卸载; - 进程注入; - 游戏内存读取; - 无人值守永久删除。 ### 3.5 REST + SSE 足以支撑双实例 MVP 双连接不强制要求自定义 WebSocket。 每个活动实例维护: - 一个 REST Client; - 一个独立 SSE Event Stream; - 独立 Token 和刷新周期; - 独立断线重连状态机; - 独立 `last_event_id`; - 独立消息去重集合。 连续全双工语音或高频游戏事件出现后,再为对应能力增加 WebSocket。 --- ## 4. 技术选型结论 ### 4.1 桌面框架 继续采用 **Tauri 2**。 理由: - 客户端会长期驻留托盘; - 游戏运行时需要控制内存和 CPU 占用; - 本地诊断、窗口枚举、文件系统和安全存储需要原生层; - Rust 适合实现有限、强类型的本地工具; - 前端仍可使用 React 生态。 ### 4.2 前端技术栈 ```text React TypeScript Vite Zustand TanStack Query Zod React Router Vitest Playwright ``` 前端负责: - 双面板与标签切换; - 会话展示; - 连接状态; - 工具操作提案; - 用户授权和执行进度; - 语音、游戏模式和通知设置。 ### 4.3 Rust 层职责 Rust Core 负责: - 双连接管理; - REST 和 SSE; - Token 与证书处理; - SQLite; - Windows Credential Manager; - 单实例、托盘、自启; - 窗口和进程检查; - 日志与配置读取; - Windows 事件日志查询; - NAS 文件事务; - 本地工具策略与授权; - 自动更新和诊断包。 ### 4.4 不应放在前端的能力 - Token 和密码读取; - SQLite 直接访问; - 任意文件系统访问; - 注册表访问; - Windows 事件日志访问; - 进程和服务控制; - NAS 凭据; - 原始截图捕获; - 本机工具最终执行; - TLS 证书例外处理。 --- ## 5. 客户端总体架构 ```text ┌──────────────────────────────────────────────┐ │ React Desktop UI │ │ ├─ Companion Chat Panel │ │ ├─ Operations Chat Panel │ │ ├─ Diagnostic Review │ │ ├─ File Transfer Review │ │ └─ Settings / Permissions │ └───────────────────────┬──────────────────────┘ │ typed Tauri IPC ┌───────────────────────▼──────────────────────┐ │ Application Services │ │ ├─ ConversationApplicationService │ │ ├─ MultiConnectionApplicationService │ │ ├─ LocalActionApplicationService │ │ ├─ VoiceApplicationService │ │ └─ GameCompanionApplicationService │ └───────────────────────┬──────────────────────┘ │ ┌───────────────────────▼──────────────────────┐ │ Rust Desktop Core │ │ ├─ MultiConnectionManager │ │ │ ├─ Companion Gateway Client │ │ │ └─ Operations Gateway Client │ │ ├─ LocalPolicyEngine │ │ ├─ DiagnosticService │ │ ├─ FileTransactionService │ │ ├─ NativeWindowsService │ │ ├─ SecureCredentialService │ │ ├─ SQLite Repository │ │ ├─ Diagnostics / Logging │ │ └─ Updater / Lifecycle │ └──────────────┬───────────────────┬───────────┘ │ │ REST + SSE A REST + SSE B │ │ ┌──────────────▼──────┐ ┌────────▼────────────┐ │ AstrBot Companion │ │ AstrBot Operations │ │ Gateway │ │ Gateway │ └─────────────────────┘ └─────────────────────┘ ``` --- ## 6. 模块职责边界 ### 6.1 UI 层 只负责展示和收集用户操作。 不得: - 直接请求 AstrBot; - 直接执行本机工具; - 直接读取凭据; - 根据服务端参数绕过确认。 ### 6.2 Application Services 负责把 UI 意图转换成领域操作: ```text 发送消息 切换实例 打开双面板 开始诊断 批准工具操作 取消文件事务 ``` 不包含 Windows API 和网络实现。 ### 6.3 MultiConnectionManager 负责两个连接槽位: - 创建和销毁 GatewayClient; - 管理连接状态; - 管理 SSE; - 路由入站事件; - 限制最多两个活动连接; - 保证实例切换不混淆事件; - 网络恢复后分别重连。 ### 6.4 GatewayClient 每个连接配置对应一个独立客户端实例。 GatewayClient 只描述稳定接口,不依赖 AstrBot 内部实现。 ### 6.5 LocalPolicyEngine 负责判断服务端工具提案是否允许进入执行流程。 判断内容包括: - 发起请求的 `profile_id` 是否为运维实例; - 服务器身份是否与已绑定指纹一致; - 工具是否在白名单; - 路径是否在授权范围; - 是否访问敏感目录; - 是否需要用户确认; - 请求是否过期; - 是否与另一个文件事务冲突。 ### 6.6 DiagnosticService 负责只读诊断采集和脱敏。 ### 6.7 FileTransactionService 负责 NAS 文件计划、复制、校验、提交、恢复和回滚。 --- ## 7. 双 AstrBot 连接设计 ### 7.1 连接槽位 ```typescript export type ActiveSlotKind = "companion" | "operations"; export interface ActiveConnectionSlot { slot: ActiveSlotKind; profileId: string | null; state: ConnectionState; activeConversationId?: string; unreadCount: number; lastEventId?: string; lastConnectedAt?: string; } ``` 规则: - 一个 Profile 同时只能占用一个槽位; - 一个槽位同一时刻只有一个 Profile; - 切换槽位 Profile 前先停止该槽位的感知会话; - 运维工具操作执行中禁止切换运维 Profile; - 陪伴槽位断线不影响运维槽位; - 运维槽位断线不影响陪伴槽位。 ### 7.2 Profile 角色 ```typescript export type AstrBotProfileRole = | "companion" | "operations" | "general"; ``` - `companion`:默认不允许本机工具; - `operations`:可以申请本机诊断工具; - `general`:用户可放入任一槽位,但本机工具默认关闭。 角色本身不是安全授权。真正授权仍由 `LocalToolPolicy` 决定。 ### 7.3 UI 布局 支持三种布局: ```typescript export type ChatLayoutMode = | "split" | "single-with-tabs" | "focus-companion" | "focus-operations"; ``` #### Split 模式 ```text ┌──────────────────────┬──────────────────────┐ │ 陪伴 AstrBot │ 运维 AstrBot │ │ 聊天 / 主动消息 │ 诊断 / 文件操作 │ │ │ │ └──────────────────────┴──────────────────────┘ ``` 适合宽屏和同时观察。 #### Single with Tabs 模式 ```text [陪伴 2] [运维 1] 当前实例对话区 ``` 适合窗口较窄或游戏时使用。 ### 7.4 消息来源识别 所有消息必须绑定: ```text profile_id slot server_instance_id conversation_id message_id ``` 通知必须显示实例名称,例如: ```text [小夜·陪伴] 你已经玩两个小时了,要不要休息一下? [家用运维] NAS 文件复制已完成,共 42 个文件。 ``` ### 7.5 多实例数据隔离 本地唯一键建议: ```text (profile_id, conversation_id, message_id) ``` 不得只以 `conversation_id` 或 `message_id` 作为全局唯一键。 所有本地缓存、Outbox、事件游标、附件和诊断记录都必须带 `profile_id`。 --- ## 8. 连接协议与通信方式 ### 8.1 MVP 建议:REST + SSE 每个活动 Profile 独立维护: ```text GatewaySession ├─ REST Client ├─ SSE Event Stream ├─ Authentication State ├─ Retry State ├─ last_event_id └─ Deduplication Cache ``` ### 8.2 REST 用途 ```text GET /desktop/v1/health GET /desktop/v1/server-info GET /desktop/v1/capabilities POST /desktop/v1/devices/register POST /desktop/v1/auth/login POST /desktop/v1/auth/refresh POST /desktop/v1/auth/revoke GET /desktop/v1/conversations GET /desktop/v1/conversations/{conversation_id}/messages POST /desktop/v1/messages POST /desktop/v1/messages/{request_id}/stop POST /desktop/v1/attachments POST /desktop/v1/events/{event_id}/ack POST /desktop/v1/local-actions/{action_id}/accepted POST /desktop/v1/local-actions/{action_id}/rejected POST /desktop/v1/local-actions/{action_id}/progress POST /desktop/v1/local-actions/{action_id}/result POST /desktop/v1/context-events ``` ### 8.3 SSE 用途 ```text GET /desktop/v1/events/stream ``` 支持: - 文本流式输出; - 消息结束; - 主动消息; - 简化 Agent 状态; - 工具状态; - 本机工具提案; - 文件计划建议; - TTS 准备完成; - 游戏陪伴事件; - 服务端能力变化; - 错误和兼容性事件。 ### 8.4 通用事件信封 ```typescript export interface GatewayEventEnvelope { protocolVersion: string; eventType: string; eventId: string; requestId?: string; profileId?: string; serverInstanceId: string; conversationId?: string; messageId?: string; sessionId?: string; timestamp: string; sequence?: number; payload: T; } ``` 客户端接收到事件后,必须以当前连接对象绑定的 `profile_id` 为准,不能信任服务端自行声明的本地 Profile ID。 ### 8.5 双连接事件路由 ```text SSE Stream A ↓ bind profile_A Event Router ↓ Companion Store SSE Stream B ↓ bind profile_B Event Router ↓ Operations Store ``` 不得把两个 SSE Stream 合并后再靠 `conversation_id` 推断来源。 ### 8.6 SSE 重连 每个连接单独采用: ```text 1s → 2s → 4s → 8s → 15s → 30s ``` 带随机抖动。 重连携带: ```text Last-Event-ID client_id device_id ``` 客户端使用 `event_id` 去重,服务端短期保存未 ACK 的重要事件。 ### 8.7 WebSocket 的后续使用范围 只在以下场景增加: - 连续全双工语音; - 边说边识别; - 服务端打断 TTS; - 高频游戏事件; - 亚秒级互动。 普通文字、诊断和文件事务不需要 WebSocket。 --- ## 9. GatewayClient 接口 ```typescript export interface CompanionGatewayClient { connect(profileId: string): Promise; disconnect(): Promise; getServerInfo(): Promise; getCapabilities(): Promise; listConversations(): Promise; getConversationMessages( conversationId: string, cursor?: string ): Promise; sendMessage(request: SendMessageRequest): Promise; stopGeneration(requestId: string): Promise; uploadAttachment(request: UploadAttachmentRequest): Promise; sendVoiceTurn(request: VoiceTurnRequest): Promise; startCompanionMode( request: StartCompanionModeRequest ): Promise; stopCompanionMode(sessionId: string): Promise; sendContextEvent(event: ContextEvent): Promise; subscribeEvents( options: EventSubscriptionOptions ): AsyncIterable; acknowledgeEvent(eventId: string): Promise; submitLocalActionDecision( decision: LocalActionDecision ): Promise; submitLocalActionProgress( progress: LocalActionProgress ): Promise; submitLocalActionResult( result: LocalActionResult ): Promise; } ``` 首版只实现: ```text AstrBotCompanionGatewayAdapter MockGatewayAdapter ``` Mock 仅用于开发和测试,不进入正式连接列表。 --- ## 10. 连接配置数据模型 ```typescript export interface ConnectionProfile { id: string; displayName: string; role: AstrBotProfileRole; baseUrl: string; eventStreamUrl?: string; authenticationType: "device-token" | "api-key"; credentialReference?: string; allowInsecureHttp: boolean; pinnedCertificateFingerprint?: string; autoConnectSlot?: ActiveSlotKind; autoConnect: boolean; serverInstanceId?: string; serverVersion?: string; protocolVersion?: string; localToolPolicyId?: string; lastConnectedAt?: string; createdAt: string; updatedAt: string; } ``` ### 10.1 多连接规则 - 可保存多个 Profile; - 最多两个 `autoConnect=true`; - 两个自动连接 Profile 的 `autoConnectSlot` 不得相同; - 相同 `serverInstanceId` 被添加两次时提示用户; - 相同地址但证书或服务端实例 ID 改变时,要求重新确认; - 删除 Profile 时默认保留聊天缓存选项,但删除凭据; - 用户可选择同时删除该 Profile 的所有本地数据。 --- ## 11. 本机电脑诊断系统 ### 11.1 能力范围 电脑诊断可以读取: - 用户明确选择的日志文件; - 用户明确选择的配置文件; - 已知软件的标准日志目录; - 当前报错窗口标题和 UI Automation 文本; - 用户授权的单次窗口截图; - 相关进程信息; - 最近相关 Windows 事件日志; - 端口、服务、磁盘、网络和 DNS 状态; - Docker 容器状态与用户选定的日志; - 文件存在性和权限状态。 ### 11.2 不允许默认读取 - 浏览器密码和 Cookie; - Credential Manager 内容; - SSH 私钥; - 完整用户目录; - 聊天数据库; - 密码管理器; - 内存转储全文; - 与当前问题无关的个人文件; - 其他 Windows 用户的数据。 ### 11.3 DiagnosticService ```text DiagnosticService ├─ ForegroundWindowInspector ├─ UIAutomationReader ├─ SelectedWindowCapture ├─ ProcessInspector ├─ EventLogReader ├─ FileReader ├─ ConfigParser ├─ LogCollector ├─ PortInspector ├─ NetworkInspector ├─ ServiceInspector ├─ RedactionEngine └─ DiagnosticBundleBuilder ``` ### 11.4 支持的首批格式 ```text .log .txt .json .yaml / .yml .toml .ini .xml .env(强制脱敏) ``` ### 11.5 文件读取策略 默认: - 先读取元数据; - 日志优先读取尾部; - 按错误时间截取上下文; - 限制单文件最大读取量; - 二进制文件不直接读取; - 用户可预览将发送的内容; - 上传前执行自动脱敏。 ### 11.6 脱敏规则 字段名匹配: ```text token api_key apikey secret password passwd private_key cookie authorization refresh_token access_token ``` 值模式匹配: - Bearer Token; - 常见 API Key; - PEM 私钥; - URL 中用户名和密码; - 数据库连接串密码; - NAS 凭据。 敏感字段发送形式: ```json { "api_key_present": true, "api_key_length": 48, "api_key_value": "[REDACTED]" } ``` ### 11.7 诊断适配器 支持针对常用软件扩展: ```text DiagnosticAdapter ├─ AstrBotAdapter ├─ DockerAdapter ├─ ComfyUIAdapter ├─ BlenderAdapter ├─ SynologyConnectionAdapter └─ GenericWindowsAppAdapter ``` 专用适配器只封装日志位置和安全检查,不获得无限文件权限。 --- ## 12. 本机工具提案与执行安全 ### 12.1 信任模型 ```text 用户消息:可信意图来源 服务端模型:不可信操作建议来源 屏幕内容:不可信数据 文件内容:不可信数据 本地策略引擎:最终授权边界 用户确认:写操作最终授权 ``` ### 12.2 本地操作提案 ```typescript export interface LocalActionProposal { actionId: string; profileId: string; toolName: string; reason: string; riskLevel: "read" | "reversible-write" | "destructive"; arguments: Record; requestedAt: string; expiresAt: string; requiresApproval: boolean; } ``` ### 12.3 权限等级 #### L0:低敏只读 可根据用户开启的“自动诊断”策略执行: - 客户端版本; - 系统版本; - 磁盘空间; - AstrBot 连接测试; - NAS 可达性; - 客户端自身日志。 #### L1:受控只读 需用户发起或会话级授权: - 当前窗口文字; - 指定窗口截图; - 指定应用日志; - 指定配置; - Windows 事件日志; - 指定目录文件列表。 #### L2:可恢复写操作 必须显示计划并确认: - 创建目录; - 复制文件; - 重命名; - NAS 归类; - 源文件移入回收站; - 修改用户级非敏感配置。 #### L3:破坏性或系统级操作 MVP 不实现: - 永久删除; - 覆盖系统文件; - 修改注册表; - 修改防火墙; - 安装驱动; - 管理员命令; - 格式化磁盘。 ### 12.4 运维实例专属限制 `tool.proposal` 只有在以下条件全部满足时才进入 UI: ```text 事件来自 operations slot Profile 角色允许运维 server_instance_id 匹配 证书指纹或已确认身份匹配 LocalToolPolicy 允许该工具 请求未过期 ``` 陪伴实例发来的本机工具请求直接拒绝,并记录安全审计事件。 --- ## 13. NAS 文件整理与事务系统 ### 13.1 NAS 目标模型 ```typescript export interface NasTarget { id: string; displayName: string; uncPath: string; credentialReference?: string; allowedDestinations: string[]; conflictPolicy: "ask" | "rename" | "skip"; verifyAfterCopy: boolean; createdAt: string; updatedAt: string; } ``` ### 13.2 文件事务流程 ```text 用户选择源文件或目录 ↓ 客户端只读取元数据 ↓ 生成归类计划 ↓ 用户预览并确认 ↓ 复制到 NAS 临时文件 ↓ 大小和哈希校验 ↓ 原子重命名为目标文件 ↓ 记录事务清单 ↓ 源文件保留 / 回收站 / 删除(按用户选择) ``` ### 13.3 禁止直接 Move 跨本机与 NAS 操作必须采用: ```text copy → verify → commit → source cleanup ``` NAS 断线时不得删除源文件。 ### 13.4 FileTransferPlan ```typescript export interface FileTransferPlan { planId: string; profileId: string; sourceSelectionId: string; nasTargetId: string; items: FileTransferPlanItem[]; totalBytes: number; conflictCount: number; warningCount: number; sourceCleanupPolicy: "keep" | "recycle"; expiresAt: string; } ``` ```typescript export interface FileTransferPlanItem { sourcePathToken: string; displaySourcePath: string; destinationRelativePath: string; sizeBytes: number; categoryReason: string; conflictAction: "copy" | "rename" | "skip" | "ask"; } ``` 服务端不应接收可任意拼接的完整本地路径。客户端使用短期 `sourcePathToken` 映射到用户选择的真实路径。 ### 13.5 自动分类阶段 #### MVP - 文件名; - 扩展名; - 创建和修改时间; - 大小; - 来源目录; - 用户定义规则。 #### 后续 - 图片缩略图分析; - PDF 和 Office 标题提取; - 媒体元数据; - 文档摘要; - 项目名称识别。 内容分析必须单独提示用户。 --- ## 14. 语音、游戏与主动消息边界 ### 14.1 语音 MVP ```text 按键录音 → 上传音频 → STT → 文本回复 → 可选 TTS ``` 麦克风默认只绑定当前聚焦实例。 若当前为双面板: - 按住说话时显示目标实例; - 支持快捷键切换目标; - 不允许同一段音频同时发送给两个实例,除非用户显式选择“同时发送”。 ### 14.2 游戏陪伴 游戏模式默认绑定 Companion Slot。 运维 Slot 不自动接收游戏截图、窗口状态或游戏事件。 ### 14.3 主动消息 两个实例都可以主动推送,但: - 陪伴实例使用普通陪伴通知; - 运维实例使用操作与告警通知; - 通知必须标明来源; - 文件操作完成通知只能来自运维实例; - 通知点击后打开对应槽位和会话。 --- ## 15. 本地存储与敏感凭据 ### 15.1 SQLite 保存 - ConnectionProfile 非敏感部分; - 活动槽位; - 会话缓存; - 消息缓存; - SSE 游标; - 未确认事件; - 工具提案; - 诊断记录摘要; - 文件事务清单; - NAS 目标非敏感部分; - 设置与迁移版本。 ### 15.2 Credential Manager 保存 - Access Token; - Refresh Token; - API Key; - NAS 用户名和密码; - 设备密钥引用; - 其他连接凭据。 SQLite 只保存: ```text credential_reference ``` ### 15.3 Profile 数据隔离 所有表中涉及服务端数据的记录必须带: ```text profile_id server_instance_id ``` 本机诊断和文件事务还要带: ```text initiating_profile_id initiating_slot ``` --- ## 16. 状态机 ### 16.1 每个连接槽位的状态机 ```text DISCONNECTED ↓ CONNECTING ↓ AUTHENTICATING ↓ SYNCING ↓ CONNECTED ``` 异常状态: ```text RECONNECTING AUTH_EXPIRED INCOMPATIBLE SERVER_UNAVAILABLE OFFLINE CERTIFICATE_CHANGED FATAL_ERROR ``` 两个槽位状态独立。 ### 16.2 应用运行状态 ```text FOREGROUND BACKGROUND_TRAY LOCKED UPDATING EXITING ``` ### 16.3 本地操作状态机 ```text PROPOSED ↓ POLICY_CHECKING ├─ REJECTED_BY_POLICY ↓ AWAITING_USER_APPROVAL ├─ REJECTED_BY_USER ↓ APPROVED ↓ EXECUTING ├─ PAUSED ├─ FAILED ├─ ROLLING_BACK ↓ COMPLETED ``` ### 16.4 文件事务状态机 ```text PLANNED ↓ APPROVED ↓ COPYING ↓ VERIFYING ↓ COMMITTING ↓ SOURCE_CLEANUP ↓ COMPLETED ``` 异常: ```text PAUSED_NETWORK_LOST CONFLICT_WAITING VERIFY_FAILED ROLLBACK_REQUIRED CANCELLED FAILED ``` --- ## 17. 推荐目录结构 ```text astrbot-companion-desktop/ ├─ apps/ │ └─ desktop/ │ ├─ src/ │ │ ├─ app/ │ │ ├─ features/ │ │ │ ├─ chat/ │ │ │ ├─ connections/ │ │ │ ├─ dual-panel/ │ │ │ ├─ voice/ │ │ │ ├─ game-companion/ │ │ │ ├─ diagnostics/ │ │ │ ├─ local-actions/ │ │ │ ├─ file-transfer/ │ │ │ ├─ notifications/ │ │ │ └─ settings/ │ │ ├─ application/ │ │ ├─ stores/ │ │ ├─ shared/ │ │ └─ types/ │ └─ src-tauri/ │ ├─ src/ │ │ ├─ app/ │ │ ├─ connection/ │ │ │ ├─ manager.rs │ │ │ ├─ slot.rs │ │ │ ├─ rest_client.rs │ │ │ ├─ sse_client.rs │ │ │ └─ retry.rs │ │ ├─ gateway/ │ │ ├─ diagnostics/ │ │ ├─ local_policy/ │ │ ├─ local_tools/ │ │ ├─ file_transactions/ │ │ ├─ nas/ │ │ ├─ secure_store/ │ │ ├─ database/ │ │ ├─ windows/ │ │ ├─ tray/ │ │ ├─ updater/ │ │ └─ logging/ │ └─ migrations/ ├─ packages/ │ ├─ protocol-types/ │ ├─ ui-components/ │ └─ test-fixtures/ └─ docs/ ``` --- ## 18. MVP 范围 ### 18.1 MVP-A:客户端与双连接基础 必须: - Tauri 2 Windows 客户端; - 多个 Profile; - 两个活动槽位; - 两个独立 REST + SSE 连接; - 双面板和标签切换; - 独立会话与未读状态; - 安全凭据; - 托盘、单实例和基础更新; - 基础日志和连接诊断。 ### 18.2 MVP-B:文字陪伴与主动消息 必须: - 文本发送; - 流式回复; - 停止生成; - 历史消息; - 主动消息; - 来源明确的通知; - 陪伴实例默认绑定游戏模式。 ### 18.3 MVP-C:只读电脑诊断 必须: - 当前前台窗口信息; - 用户选择的窗口截图; - 指定日志和配置文件读取; - Windows 事件日志查询; - 进程、端口、服务、磁盘和网络检查; - 自动脱敏; - 用户预览诊断包; - 运维实例专属权限。 ### 18.4 MVP-D:安全 NAS 文件归档 建议纳入首个可用正式版本,但晚于只读诊断: - NAS 目标登记; - Credential Manager 凭据; - 用户选择源文件; - 基于元数据的归类计划; - Dry Run; - 复制、校验、提交; - 冲突处理; - 网络断开暂停; - 源文件保留或回收站; - 操作审计。 ### 18.5 MVP 暂不实现 - 无限活动连接; - 同一实例多个本机工具并行写操作; - 任意 Shell; - 自动 UAC; - 永久删除; - 实时全双工语音; - 唤醒词; - 高频视频分析; - 项目工作区; - Codex 集成; - macOS 和 Linux 正式支持。 --- ## 19. 分阶段开发顺序 ### 阶段 0:高风险验证 1. Tauri 双 SSE 长连接后台运行; 2. Windows Credential Manager; 3. UI Automation 读取标准弹窗; 4. Windows Event Log 查询; 5. UNC 路径复制和断线恢复; 6. SQLite 双 Profile 隔离。 ### 阶段 1:项目骨架 - React + Tauri; - IPC 类型; - SQLite 迁移; - Profile CRUD; - 单实例和托盘。 ### 阶段 2:双连接管理 - MultiConnectionManager; - Companion / Operations Slot; - REST Client; - SSE Client; - 重连和去重; - 双面板状态。 ### 阶段 3:聊天 - 会话; - 消息; - 流式输出; - 主动消息; - 通知跳转。 ### 阶段 4:安全策略 - LocalPolicyEngine; - Profile 权限; - 工具白名单; - 用户确认卡片; - 操作审计。 ### 阶段 5:电脑诊断 - 窗口和进程; - 日志、配置; - 事件日志; - 网络和端口; - 脱敏与诊断包。 ### 阶段 6:NAS 文件事务 - NasTarget; - 文件计划; - 复制、哈希、提交; - 冲突和暂停恢复; - 回收站策略。 ### 阶段 7:语音和游戏陪伴 - 按键说话; - TTS; - 游戏窗口绑定; - 时长事件; - 手动和低频截图。 ### 阶段 8:发布 - Updater; - 签名; - 崩溃恢复; - 安装包; - Beta 验收。 --- ## 20. 风险与规避措施 | 风险 | 严重度 | 概率 | 规避方案 | MVP 必须解决 | |---|---:|---:|---|---| | 两个实例消息混淆 | 高 | 中 | 所有记录绑定 profile_id;每条 SSE 在连接层绑定来源 | 是 | | 陪伴实例越权申请工具 | 高 | 中 | 本地按槽位、Profile、服务端身份拒绝 | 是 | | 服务端被入侵后控制电脑 | 高 | 低到中 | 工具白名单、本地策略、用户确认、无任意 Shell | 是 | | 日志泄露 Token | 高 | 中 | 本地脱敏、预览、敏感文件禁止默认读取 | 是 | | NAS 断线导致源文件丢失 | 高 | 中 | copy-verify-commit,不直接 move | 是 | | 同名文件覆盖 | 中 | 高 | ask/rename/skip;默认不覆盖 | 是 | | 双 SSE 占用或重连风暴 | 中 | 中 | 分别退避、抖动、网络状态统一协调 | 是 | | 同一个服务被配置两次 | 中 | 中 | server_instance_id 检测和提示 | 是 | | UI Automation 读不到自绘窗口 | 中 | 中 | 单次窗口截图降级 | 否,但需降级 | | 管理员程序无法读取 | 中 | 中 | 不常驻管理员;提示权限边界 | 是 | | Windows Defender 误报 | 中 | 中 | 代码签名、不注入、不 Hook、透明权限 | 正式版 | | 数据库异常退出损坏 | 高 | 低 | WAL、事务、迁移备份、启动恢复 | 是 | | 两实例同时发声 | 中 | 中 | 全局音频仲裁器、当前实例优先 | 是 | --- ## 21. 验收标准 ### 21.1 双实例 - 可以保存至少 5 个 Profile; - 可选择两个不同 Profile 同时连接; - 两个实例分别显示连接状态; - 任一实例断线不影响另一个实例; - 可并排显示两个对话框; - 可切换单面板标签; - 主动消息正确进入来源面板; - 通知点击后进入正确会话; - 两个实例相同 conversation_id 时不混淆数据。 ### 21.2 权限隔离 - 陪伴实例请求本机工具时客户端拒绝; - 运维实例请求只读工具时显示采集范围; - 写操作未确认不得执行; - 远程 payload 不能传入任意本地路径执行; - 工具请求过期后不能再次批准; - 服务端身份改变后工具权限自动冻结。 ### 21.3 电脑诊断 - 能读取标准错误弹窗文字; - 读取失败时可单次选择窗口截图; - 能读取用户选择的日志与配置; - 能查询指定进程相关事件日志; - Token、密码和私钥被脱敏; - 用户可以预览实际发送内容; - 诊断结束不保留原始截图,除非用户选择保存。 ### 21.4 NAS 文件事务 - 能登记 UNC 共享; - 凭据不进入 SQLite 明文字段; - 复制前显示完整计划; - NAS 断线时源文件不丢失; - 校验失败时不执行源清理; - 同名冲突不会静默覆盖; - 操作结束生成事务报告; - 用户选择回收站时可以恢复源文件。 ### 21.5 稳定性 - 主窗口关闭到托盘后两个连接继续在线; - 网络切换后分别恢复 SSE; - 客户端重启后恢复活动槽位和未完成文件事务; - 日志不包含完整 Token、密码、私钥、聊天全文或截图。 --- ## 22. 需要其他专题配合的接口清单 ### 22.1 AstrBot Gateway 专题 需要提供: - 设备注册; - Token 刷新; - ServerInfo; - Capabilities; - 会话和消息接口; - SSE 事件流; - 主动消息 ACK; - 本机工具提案协议; - 诊断结果回传协议; - 服务端实例唯一 ID。 ### 22.2 聊天专题 需要确认: - 会话数据结构; - 消息内容块; - 附件格式; - 流式消息合并规则; - 停止生成行为。 ### 22.3 语音专题 需要确认: - STT 和 TTS 提供者; - 音频格式; - 目标实例选择; - 两实例语音仲裁。 ### 22.4 游戏陪伴专题 需要确认: - 游戏模式事件; - 截图频率; - 捕获权限提示; - 默认绑定 Companion Slot。 ### 22.5 本机助手专题 需要进一步细化: - 首批 DiagnosticAdapter; - 本机工具注册表; - 每项工具风险等级; - 日志脱敏规则测试集; - 文件分类规则; - NAS 恢复和回滚细节。 --- ## 23. 最终决策摘要 ```text 项目定位: AstrBot Windows 陪伴与本机助手客户端 桌面框架: Tauri 2 + React + TypeScript + Rust 通信: MVP 使用 REST + SSE 连续语音等后续使用 WebSocket 多实例: 保存多个 Profile 最多两个活动连接 陪伴槽位 + 运维槽位 支持双面板和切换 电脑诊断: 允许读取用户授权的文件、配置、日志和系统诊断信息 本地脱敏后发送给运维 AstrBot 本机操作: 服务端只提交提案 客户端本地策略引擎最终裁决 写操作需要用户确认 不提供任意 Shell NAS 文件整理: copy → verify → commit → source cleanup 禁止直接跨设备 Move 权限: 陪伴实例默认无本机工具权限 运维实例按白名单申请本机工具 ``` 该方案同时满足: - 日常陪伴; - 运维问题咨询; - 两个 AstrBot 同时在线; - 双对话框或快速切换; - 电脑日志和配置诊断; - 安全的 NAS 文件归档; - 不重新引入项目工作区和 Codex 开发平台复杂度。