35 KiB
01|桌面客户端双实例陪伴与本机运维系统
文档名称:
01_桌面客户端双实例陪伴与本机运维系统.md项目:AstrBot Windows 桌面客户端 文档状态:架构重构版,可交给 Codex 分阶段开发 日期:2026-07-18 目标读者:Codex、桌面客户端开发者、AstrBot 插件开发者、测试与发布人员
1. 执行摘要
本项目不再建设项目工作区、VM 任务投递、代码编辑、Git 管理或 Codex 控制台。上述开发工作继续由桌面 Codex 与 VM 交付流程承担。
桌面客户端重新定位为:
AstrBot 的 Windows 陪伴与本机助手客户端。
核心能力包括:
- 文字聊天与多会话;
- 语音聊天;
- 主动消息与桌面通知;
- 游戏陪伴与有限窗口感知;
- 用户主动发起的电脑问题诊断;
- 受控的本地文件整理与 NAS 归档;
- 同时连接两个 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:高风险验证
- Tauri 双 SSE 长连接后台运行;
- Windows Credential Manager;
- UI Automation 读取标准弹窗;
- Windows Event Log 查询;
- UNC 路径复制和断线恢复;
- 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 开发平台复杂度。