1614 行
35 KiB
Markdown
1614 行
35 KiB
Markdown
|
|
# 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<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 双连接事件路由
|
|||
|
|
|
|||
|
|
```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<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>;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
首版只实现:
|
|||
|
|
|
|||
|
|
```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<string, unknown>;
|
|||
|
|
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 开发平台复杂度。
|