AstrBot-Desktop/docs/01_Architecture_Design.md

35 KiB

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 实例,一个作为陪伴实例,一个作为运维实例。

最终推荐技术方案:

Tauri 2
React + TypeScript + Vite
Rust Native Core
SQLite
Windows Credential Manager / DPAPI
REST + SSE(MVP)
WebSocket(连续语音或高频事件的后续扩展)

双实例的产品规则为:

可保存多个 ConnectionProfile
MVP 最多同时激活两个连接槽位
├─ Companion Slot:陪伴实例
└─ Operations Slot:运维实例

两个实例可以:

  • 并排显示为两个对话框;
  • 切换为单面板标签模式;
  • 分别保持连接、会话、未读状态和主动消息;
  • 使用不同的 AstrBot 地址、账号、人格和插件;
  • 在本地数据层完全隔离。

重要安全结论:

只有运维实例可以申请本机诊断和文件操作;服务端请求只是操作提案,最终是否执行由客户端本地策略引擎和用户确认决定。


2. 产品定位与范围调整

2.1 新定位

AstrBot Companion Desktop
├─ 陪伴沟通
├─ 主动交互
├─ 游戏陪伴
├─ 电脑问题诊断
└─ 安全文件助手

2.2 不再承担的职责

以下内容从桌面客户端项目中删除:

  • 项目工作区;
  • 代码编辑器;
  • VM 任务投递;
  • Codex 对话与开发任务管理;
  • Git 仓库管理;
  • 内置终端;
  • 通用 Agent 编排控制台;
  • 代码补丁审查;
  • 项目文件同步;
  • 开发环境远程执行。

2.3 与 Codex 的边界

桌面 Codex + VM
负责:
- 编程
- Git
- 构建与部署
- 插件开发
- 项目任务

AstrBot Desktop
负责:
- 文字和语音交流
- 主动陪伴
- 游戏陪伴
- 日常电脑诊断
- 文件与 NAS 整理

两个系统不需要在首版互相嵌入。


3. 需求审视与关键修正

3.1 双 AstrBot 不应实现成两个独立客户端进程

推荐在一个桌面客户端内维护两个独立连接槽位,而不是启动两个应用实例。

原因:

  • 单实例、托盘和自动更新更简单;
  • 麦克风、通知和窗口捕获权限不会冲突;
  • 可以统一管理本机工具授权;
  • 用户可以并排查看,也可以快速切换;
  • 避免两个客户端同时读取或移动同一文件。

3.2 “两个实例同时在线”不等于“无限多实例同时在线”

MVP 允许保存任意数量的连接配置,但只允许两个活动连接槽位。

Saved Profiles:N 个
Active Slots:最多 2 个

后续若确有需求,再考虑增加更多活动连接。

3.3 陪伴实例和运维实例必须权限隔离

不能仅依赖提示词区分角色。

必须在客户端本地绑定:

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 前端技术栈

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. 客户端总体架构

┌──────────────────────────────────────────────┐
│ 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 意图转换成领域操作:

发送消息
切换实例
打开双面板
开始诊断
批准工具操作
取消文件事务

不包含 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 连接槽位

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 角色

export type AstrBotProfileRole =
  | "companion"
  | "operations"
  | "general";
  • companion:默认不允许本机工具;
  • operations:可以申请本机诊断工具;
  • general:用户可放入任一槽位,但本机工具默认关闭。

角色本身不是安全授权。真正授权仍由 LocalToolPolicy 决定。

7.3 UI 布局

支持三种布局:

export type ChatLayoutMode =
  | "split"
  | "single-with-tabs"
  | "focus-companion"
  | "focus-operations";

Split 模式

┌──────────────────────┬──────────────────────┐
│ 陪伴 AstrBot          │ 运维 AstrBot          │
│ 聊天 / 主动消息        │ 诊断 / 文件操作        │
│                       │                      │
└──────────────────────┴──────────────────────┘

适合宽屏和同时观察。

Single with Tabs 模式

[陪伴 2] [运维 1]

当前实例对话区

适合窗口较窄或游戏时使用。

7.4 消息来源识别

所有消息必须绑定:

profile_id
slot
server_instance_id
conversation_id
message_id

通知必须显示实例名称,例如:

[小夜·陪伴] 你已经玩两个小时了,要不要休息一下?
[家用运维] NAS 文件复制已完成,共 42 个文件。

7.5 多实例数据隔离

本地唯一键建议:

(profile_id, conversation_id, message_id)

不得只以 conversation_id 或 message_id 作为全局唯一键。

所有本地缓存、Outbox、事件游标、附件和诊断记录都必须带 profile_id。


8. 连接协议与通信方式

8.1 MVP 建议:REST + SSE

每个活动 Profile 独立维护:

GatewaySession
├─ REST Client
├─ SSE Event Stream
├─ Authentication State
├─ Retry State
├─ last_event_id
└─ Deduplication Cache

8.2 REST 用途

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 用途

GET /desktop/v1/events/stream

支持:

  • 文本流式输出;
  • 消息结束;
  • 主动消息;
  • 简化 Agent 状态;
  • 工具状态;
  • 本机工具提案;
  • 文件计划建议;
  • TTS 准备完成;
  • 游戏陪伴事件;
  • 服务端能力变化;
  • 错误和兼容性事件。

8.4 通用事件信封

export interface GatewayEventEnvelope<T = unknown> {
  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 双连接事件路由

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 重连

每个连接单独采用:

1s → 2s → 4s → 8s → 15s → 30s

带随机抖动。

重连携带:

Last-Event-ID
client_id
device_id

客户端使用 event_id 去重,服务端短期保存未 ACK 的重要事件。

8.7 WebSocket 的后续使用范围

只在以下场景增加:

  • 连续全双工语音;
  • 边说边识别;
  • 服务端打断 TTS;
  • 高频游戏事件;
  • 亚秒级互动。

普通文字、诊断和文件事务不需要 WebSocket。


9. GatewayClient 接口

export interface CompanionGatewayClient {
  connect(profileId: string): Promise<ConnectionResult>;
  disconnect(): Promise<void>;

  getServerInfo(): Promise<ServerInfo>;
  getCapabilities(): Promise<ServerCapabilities>;

  listConversations(): Promise<ConversationSummary[]>;
  getConversationMessages(
    conversationId: string,
    cursor?: string
  ): Promise<MessagePage>;

  sendMessage(request: SendMessageRequest): Promise<AcceptedMessage>;
  stopGeneration(requestId: string): Promise<void>;

  uploadAttachment(request: UploadAttachmentRequest): Promise<UploadedAttachment>;

  sendVoiceTurn(request: VoiceTurnRequest): Promise<VoiceTurnAccepted>;

  startCompanionMode(
    request: StartCompanionModeRequest
  ): Promise<CompanionSession>;

  stopCompanionMode(sessionId: string): Promise<void>;

  sendContextEvent(event: ContextEvent): Promise<EventAccepted>;

  subscribeEvents(
    options: EventSubscriptionOptions
  ): AsyncIterable<GatewayEventEnvelope>;

  acknowledgeEvent(eventId: string): Promise<void>;

  submitLocalActionDecision(
    decision: LocalActionDecision
  ): Promise<void>;

  submitLocalActionProgress(
    progress: LocalActionProgress
  ): Promise<void>;

  submitLocalActionResult(
    result: LocalActionResult
  ): Promise<void>;
}

首版只实现:

AstrBotCompanionGatewayAdapter
MockGatewayAdapter

Mock 仅用于开发和测试,不进入正式连接列表。


10. 连接配置数据模型

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

DiagnosticService
├─ ForegroundWindowInspector
├─ UIAutomationReader
├─ SelectedWindowCapture
├─ ProcessInspector
├─ EventLogReader
├─ FileReader
├─ ConfigParser
├─ LogCollector
├─ PortInspector
├─ NetworkInspector
├─ ServiceInspector
├─ RedactionEngine
└─ DiagnosticBundleBuilder

11.4 支持的首批格式

.log
.txt
.json
.yaml / .yml
.toml
.ini
.xml
.env(强制脱敏)

11.5 文件读取策略

默认:

  • 先读取元数据;
  • 日志优先读取尾部;
  • 按错误时间截取上下文;
  • 限制单文件最大读取量;
  • 二进制文件不直接读取;
  • 用户可预览将发送的内容;
  • 上传前执行自动脱敏。

11.6 脱敏规则

字段名匹配:

token
api_key
apikey
secret
password
passwd
private_key
cookie
authorization
refresh_token
access_token

值模式匹配:

  • Bearer Token;
  • 常见 API Key;
  • PEM 私钥;
  • URL 中用户名和密码;
  • 数据库连接串密码;
  • NAS 凭据。

敏感字段发送形式:

{
  "api_key_present": true,
  "api_key_length": 48,
  "api_key_value": "[REDACTED]"
}

11.7 诊断适配器

支持针对常用软件扩展:

DiagnosticAdapter
├─ AstrBotAdapter
├─ DockerAdapter
├─ ComfyUIAdapter
├─ BlenderAdapter
├─ SynologyConnectionAdapter
└─ GenericWindowsAppAdapter

专用适配器只封装日志位置和安全检查,不获得无限文件权限。


12. 本机工具提案与执行安全

12.1 信任模型

用户消息:可信意图来源
服务端模型:不可信操作建议来源
屏幕内容:不可信数据
文件内容:不可信数据
本地策略引擎:最终授权边界
用户确认:写操作最终授权

12.2 本地操作提案

export interface LocalActionProposal {
  actionId: string;
  profileId: string;
  toolName: string;
  reason: string;
  riskLevel: "read" | "reversible-write" | "destructive";
  arguments: Record<string, unknown>;
  requestedAt: string;
  expiresAt: string;
  requiresApproval: boolean;
}

12.3 权限等级

L0:低敏只读

可根据用户开启的“自动诊断”策略执行:

  • 客户端版本;
  • 系统版本;
  • 磁盘空间;
  • AstrBot 连接测试;
  • NAS 可达性;
  • 客户端自身日志。

L1:受控只读

需用户发起或会话级授权:

  • 当前窗口文字;
  • 指定窗口截图;
  • 指定应用日志;
  • 指定配置;
  • Windows 事件日志;
  • 指定目录文件列表。

L2:可恢复写操作

必须显示计划并确认:

  • 创建目录;
  • 复制文件;
  • 重命名;
  • NAS 归类;
  • 源文件移入回收站;
  • 修改用户级非敏感配置。

L3:破坏性或系统级操作

MVP 不实现:

  • 永久删除;
  • 覆盖系统文件;
  • 修改注册表;
  • 修改防火墙;
  • 安装驱动;
  • 管理员命令;
  • 格式化磁盘。

12.4 运维实例专属限制

tool.proposal 只有在以下条件全部满足时才进入 UI:

事件来自 operations slot
Profile 角色允许运维
server_instance_id 匹配
证书指纹或已确认身份匹配
LocalToolPolicy 允许该工具
请求未过期

陪伴实例发来的本机工具请求直接拒绝,并记录安全审计事件。


13. NAS 文件整理与事务系统

13.1 NAS 目标模型

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 文件事务流程

用户选择源文件或目录
  ↓
客户端只读取元数据
  ↓
生成归类计划
  ↓
用户预览并确认
  ↓
复制到 NAS 临时文件
  ↓
大小和哈希校验
  ↓
原子重命名为目标文件
  ↓
记录事务清单
  ↓
源文件保留 / 回收站 / 删除(按用户选择)

13.3 禁止直接 Move

跨本机与 NAS 操作必须采用:

copy → verify → commit → source cleanup

NAS 断线时不得删除源文件。

13.4 FileTransferPlan

export interface FileTransferPlan {
  planId: string;
  profileId: string;
  sourceSelectionId: string;
  nasTargetId: string;
  items: FileTransferPlanItem[];
  totalBytes: number;
  conflictCount: number;
  warningCount: number;
  sourceCleanupPolicy: "keep" | "recycle";
  expiresAt: string;
}
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

按键录音
→ 上传音频
→ 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 只保存:

credential_reference

15.3 Profile 数据隔离

所有表中涉及服务端数据的记录必须带:

profile_id
server_instance_id

本机诊断和文件事务还要带:

initiating_profile_id
initiating_slot

16. 状态机

16.1 每个连接槽位的状态机

DISCONNECTED
  ↓
CONNECTING
  ↓
AUTHENTICATING
  ↓
SYNCING
  ↓
CONNECTED

异常状态:

RECONNECTING
AUTH_EXPIRED
INCOMPATIBLE
SERVER_UNAVAILABLE
OFFLINE
CERTIFICATE_CHANGED
FATAL_ERROR

两个槽位状态独立。

16.2 应用运行状态

FOREGROUND
BACKGROUND_TRAY
LOCKED
UPDATING
EXITING

16.3 本地操作状态机

PROPOSED
  ↓
POLICY_CHECKING
  ├─ REJECTED_BY_POLICY
  ↓
AWAITING_USER_APPROVAL
  ├─ REJECTED_BY_USER
  ↓
APPROVED
  ↓
EXECUTING
  ├─ PAUSED
  ├─ FAILED
  ├─ ROLLING_BACK
  ↓
COMPLETED

16.4 文件事务状态机

PLANNED
  ↓
APPROVED
  ↓
COPYING
  ↓
VERIFYING
  ↓
COMMITTING
  ↓
SOURCE_CLEANUP
  ↓
COMPLETED

异常:

PAUSED_NETWORK_LOST
CONFLICT_WAITING
VERIFY_FAILED
ROLLBACK_REQUIRED
CANCELLED
FAILED

17. 推荐目录结构

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. 最终决策摘要

项目定位:
AstrBot Windows 陪伴与本机助手客户端

桌面框架:
Tauri 2 + React + TypeScript + Rust

通信:
MVP 使用 REST + SSE
连续语音等后续使用 WebSocket

多实例:
保存多个 Profile
最多两个活动连接
陪伴槽位 + 运维槽位
支持双面板和切换

电脑诊断:
允许读取用户授权的文件、配置、日志和系统诊断信息
本地脱敏后发送给运维 AstrBot

本机操作:
服务端只提交提案
客户端本地策略引擎最终裁决
写操作需要用户确认
不提供任意 Shell

NAS 文件整理:
copy → verify → commit → source cleanup
禁止直接跨设备 Move

权限:
陪伴实例默认无本机工具权限
运维实例按白名单申请本机工具

该方案同时满足:

  • 日常陪伴;
  • 运维问题咨询;
  • 两个 AstrBot 同时在线;
  • 双对话框或快速切换;
  • 电脑日志和配置诊断;
  • 安全的 NAS 文件归档;
  • 不重新引入项目工作区和 Codex 开发平台复杂度。