# AstrBot Desktop 后续开发队列 ## 目标形态 产品采用一套共享聊天运行时,提供三种展示形态: 1. **主页面聊天**:类似 QQ / Telegram 的完整窗口,支持会话列表、双槽位、消息流、未读数、主动消息和设置入口。 2. **快速聊天窗口**:桌面小窗口,支持拖动和调整大小;与主页面共享会话、消息、连接和未读状态,不复制聊天逻辑。 3. **气泡/桌宠入口**:默认不置顶,可显示连接和代理状态;点击行为在设置中选择“打开主页面”或“打开快速聊天”。后续扩展为桌面宠物。 ## 隔离基线 所有后续队列必须遵守以下五层边界: - **账号与账号隔离**:不同本地账号的连接配置、凭据引用、聊天记录、长期记忆和权限互不共享。 - **槽位与槽位隔离**:同一账号下的 Companion 与 Operations 分别维护连接、SSE、会话、消息、未读数、错误状态和权限。 - **Profile 与 Profile 隔离**:每个 AstrBot 连接 Profile 固定绑定地址、凭据引用、server_instance_id 和远端身份。 - **Session 与 Session 隔离**:不同槽位使用不同 sticky session;本地消息键不能只使用 session_id 或 conversation_id。 - **权限与权限隔离**:Companion 默认无本机工具权限;Operations 的诊断或文件提案必须经过本地策略、风险判断和用户确认。 推荐的本地事件和消息归属字段为: `account_id + profile_id + slot + server_instance_id + remote_username + session_id + message_id` remote_username 用于远端聊天身份和会话命名,不作为本机权限判断依据;本机权限只由本地账号、Profile、槽位和策略引擎决定。 ## 执行原则 - 先做真实 AstrBot OpenAPI 的文字聊天闭环,再做视觉增强。 - React 只消费 Rust 输出的规范化事件,不直接访问 AstrBot 原始接口。 - Companion 与 Operations 的消息、会话、未读数和错误状态始终隔离。 - 气泡、快速窗口和主窗口只改变展示方式,不改变消息权限和槽位权限。 - 桌宠动画、跨屏移动和游戏模式先做数据模型及控制器接口,避免提前绑定素材或第三方运行时。 - 不默认开启置顶;全屏浮动必须有显式设置和可关闭路径。 ## 队列 ### Q0:阶段收口与基础校验 - 检查当前 P02 未提交改动,消除意外的大范围格式或换行 diff。 - 完成 Rust fmt、Clippy、TypeScript、ESLint、Prettier、Vite build、Playwright 和适用的 Tauri 构建检查。 - 测试容器允许长期使用;API Key 只在进入生产前轮换,任何阶段都不得写入日志、快照或测试夹具。 - 保留 `desktop-v1` Mock 传输;真实 AstrBot 走 `astrbot-openapi` 适配器。 验收:现有连接基础可构建,敏感信息边界无回归,Mock 与真实适配器不会互相污染。 ### Q1:统一聊天运行时与事件归一化 - 为每个槽位建立 Rust-owned `ChatRuntime`,绑定 `profile_id`、`server_instance_id`、`conversation_id`。 - 将 AstrBot SSE 映射为统一的消息增量、完成、错误、心跳和主动消息事件。 - 处理流式消息合并、重复事件、断线恢复、取消生成和请求失败。 - 明确 `remote_username` 与 sticky session 的会话恢复策略。 - 增加前端订阅 IPC/事件桥;React 不接触 API Key 和原始 HTTP 客户端。 验收:两个槽位可同时发送和接收文字消息;同一 `conversation_id` 在不同 Profile 下不会串线。 ### Q2:聊天数据与历史持久化 - 新增会话、消息、消息块、发送状态、未读数和主动消息的 SQLite 表及迁移。 - 本地唯一键至少包含 `profile_id`、`server_instance_id`、`conversation_id`、`message_id`。 - 支持启动恢复、分页加载、失败重试、流式消息落盘和未读数清零。 - 对消息内容做长度限制和展示层安全处理;日志不得记录完整聊天内容或凭据。 验收:重启应用后可恢复两个槽位的会话和未完成消息状态,数据隔离测试通过。 ### Q3:主页面聊天 MVP - 将当前 bootstrap/Profile 骨架替换为应用壳:侧栏、槽位切换、会话列表和聊天区域。 - 支持双面板并排模式、单面板 Tab 模式、Focus Companion、Focus Operations。 - 支持文本消息、流式渲染、发送中/失败/重试、连接状态、未读标记和主动消息入口。 - Operations 的本机工具提案只显示安全确认卡片,不在聊天文本中伪装成已执行。 - Companion 默认隐藏本机工具入口;Operations 仍受本地策略引擎约束。 验收:主窗口能完成真实 AstrBot 文字聊天;布局切换不丢流式内容;主动消息能跳转到正确槽位。 ### Q4:快速聊天窗口 - 增加独立 Tauri 窗口,初始尺寸适合快速回复。 - 已完成:窗口单实例、拖动/调整大小、SQLite 几何状态持久化、屏幕工作区夹紧和显示器标识恢复。 - 支持拖动、调整大小、关闭后恢复位置和尺寸。 - 与主窗口共享 `ChatRuntime`、会话选择、消息缓存、未读数和发送队列。 - 设置中只提供一个快速聊天目标:`companion` 或 `operations`,二选一。 - 设置中提供气泡点击导向:主页面或快速聊天;不增加第三种导向模式。 - 处理主窗口关闭到托盘、快速窗口关闭、单实例和窗口重启恢复。 - 已修复:快捷窗口关闭按钮现在正常销毁窗口;主窗口仍保持关闭到托盘。 验收:从主窗口和快速窗口发送的消息进入同一会话;任一窗口关闭不影响连接和另一个窗口。 ### Q5:状态气泡与托盘整合 - 增加非默认置顶的气泡窗口,显示连接状态、思考中、回复完成、错误和未读数。 - 浮动桌宠窗口必须使用无装饰、跳过任务栏的后台窗口;主对话框关闭后应用继续由托盘驻留。 - 已完成:修复气泡状态标签和无障碍名称的乱码,保持默认不置顶和设置导向逻辑不变。 - 允许用户关闭气泡或切换到仅应用 UI 模式。 - 气泡点击按设置打开主页面或快速聊天;右键菜单提供显示、隐藏、设置和退出。 - 明确窗口层级、焦点、点击穿透(如需要)和屏幕边界策略。 - 只在 Rust 窗口控制器中执行显示/隐藏/置顶,React 仅发出受限意图。 验收:气泡不默认置顶;两个槽位状态可区分;点击行为与设置一致;托盘隐藏主窗口后仍可恢复。 ### Q6:桌宠基础模型与素材包 - 抽象 `CompanionState`:`idle`、`thinking`、`speaking`、`error`、 otification`、`offline`。 - 抽象 `PetRenderer`、`PetWindowController` 和 `PetInteractionPolicy`,先支持静态 PNG/WebP 和 spritesheet。 - 定义可校验的 `pet-pack/manifest.json`,包含尺寸、动画帧、状态映射和可选点击动作。 - 动作采用受限动画片段和状态机:待机、工作写字/看书、说话、通知、休息走动和错误状态;移动路径与渲染帧分离。 - 支持应用内显示模式与全屏浮动模式的设置模型;浮动模式不占用任务栏、不默认置顶,首版接入 spritesheet 动画。 - 上传素材只进入沙箱目录,校验格式、尺寸、文件大小和 manifest,不执行脚本或插件代码。 验收:可加载一个本地安全素材包并根据聊天状态切换静态状态;错误素材被拒绝且不影响主 UI。 ### Q7:多显示器与游戏模式控制器 - Rust 获取显示器工作区、主屏/副屏标识、DPI 和任务栏边界,形成稳定的 `MonitorGeometry`。 - 提供桌宠位置策略:自由、靠边、指定屏幕、跟随主窗口。 - 游戏模式只做策略层:优先选择副屏,无法识别时选择非当前游戏窗口所在屏幕;宠物限制在边缘安全区。 - 通过受限的窗口/进程检测判断前台游戏,不读取或注入游戏进程,不做鼠标键盘控制。 - 增加双屏断开、DPI 变化、全屏游戏和窗口切换的回退策略。 验收:双屏场景下位置计算稳定;游戏模式不会把宠物放到游戏中心;权限不足时安全降级为应用内模式。 ### Q8:语音、主动消息与游戏陪伴接入 - 在统一聊天运行时之上接入 STT/TTS,不为快速窗口或桌宠复制语音管线。 - 必须支持 AstrBot Dashboard JWT 登录,并与 API Key / 设备 Token 作为并列认证方式,凭据统一存入 Windows Credential Manager。 - 明确语音目标槽位,默认 Companion;Operations 需要显式切换。 - 将主动消息映射为通知、气泡状态和未读数,并提供静默时段设置。 - 游戏模式接入截图/状态摘要前,先完成授权提示、频率限制和隐私开关。 ### Q9:稳定性、发布与验收 - 覆盖网络切换、SSE 重连、托盘驻留、窗口恢复、凭据失效和数据库迁移。 - 完成日志脱敏、诊断包预览、崩溃恢复和更新流程。 - 完成 Windows release/installer、签名、版本号、CHANGELOG 和阶段总结。 - 通过全套阶段门槛后再进入主干合并和验收版本打包。 ## 暂不进入实现 ### 本轮已推进 - 远端身份已拆分为协议 ID(`remote_username`)与 BOT 称呼昵称(`remote_display_name`),两者不再共用字段。 - 2D 纸片人桌宠已从 manifest 基础推进到可运行窗口:透明、无边框、跳过任务栏、关闭后回托盘,并预留状态动作循环。 - JWT 运行时已支持 `exp` 过期识别、401/403 状态映射和聊天界面重新登录提示。 - 桌宠窗口已接入双槽位运行状态:连接中工作、重连回应、断开休息、认证过期/致命错误提示。 - 已接入 `aemeath_withclaude-2.0.8` 的 MIT 像素素材;保留来源署名,并将 spritesheet 动作行映射到当前桌宠状态。 - 不复制 Hermes 或 Codex 的私有实现;只参考交互模式和资源组织方式。 - 不在首轮实现 Live2D、Spine、3D 桌宠或用户脚本插件。 - 不实现任意 Shell、PowerShell、CMD、鼠标键盘控制。 - 不把 AstrBot 的工具调用直接当成本机命令执行。 - 不在没有真实附件协议验证前承诺文件上传;附件单独做 Spike。 ## 需要用户后续接入 - 测试容器 API Key 轮换。 - 真实双服务器或第二容器,用于两个不同 `server_instance_id` 的长期并行测试。 - 最终确定 Companion/Operations 的远端用户名命名规则。 - 首批桌宠素材或授权素材包;在此之前使用测试 PNG/WebP。 - 如需 HTTPS 证书指纹绑定,提供可验证的 HTTPS 入口并确认首次信任交互。 ## 2026-07-20 增量:启动自动连接 - 应用启动后由 Rust 读取已保存 Profile,仅处理 `auto_connect=true` 且绑定固定槽位的配置。 - `companion` 与 `operations` 逐槽位独立尝试,不因一个 Profile 凭据缺失、认证失败或服务不可用而跳过另一个槽位。 - API Key / Bearer Token 仍只在 Rust 启动任务和 Windows Credential Manager 之间流动;日志只记录 Profile、槽位和错误类别,不记录凭据或请求内容。 - 启动任务复用现有双槽位 Runtime,不创建额外网络客户端或权限范围。 - 当前仍未实现后台重连退避、JWT 登录和启动自动连接的前端可视化提示。 ## 2026-07-20??? 1-6 ???? ???????????????? 1. Q1 ?????????????????? 2. Q2 chat_sessions???????????? v6? 3. Q3 ???????????? 4. Q4 ??????????? 5. Q5 ????????? 6. Q6 ?? manifest ??????? ??????????? Hook ?????????/??????????????????????????? ### Q3.1: Chat extensibility contract - Expose normalized AstrBot capability discovery through Rust-owned IPC. - Expose model/provider configuration options as a slot-scoped selector; keep the server default when discovery is unavailable. - Add a bounded 16 MiB multipart upload boundary at /api/v1/file; React receives only normalized attachment metadata. - Carry optional configId and attachment metadata through the send request without exposing credentials or raw HTTP clients. - Keep attachment wire mapping isolated in the AstrBot adapter so the internal chat runtime remains transport-neutral. Acceptance: the chat panel can discover model options, stage uploaded files, and submit a normalized message request; real server response-shape compatibility remains verified by the supplied AstrBot containers before claiming end-to-end multimodal support. ### Q3.2: Remote session navigation - Expose the active AstrBot session list through the slot runtime without creating a second network client. - Allow switching the sticky session ID inside one slot and reload only that session history. - Keep message identity scoped by slot and session ID so switching sessions cannot mix content. Acceptance: a connected slot can display remote sessions and switch between them without affecting the other slot. ## 2026-07-21: implementation status for the 13-item roadmap The roadmap items are implemented locally as follows: 1. Startup auto-connect: done in src-tauri/src/networking/commands.rs and src-tauri/src/lib.rs. 2. Credential rotation and JWT: done in src-tauri/src/credentials, src-tauri/src/auth.rs, and CredentialEnrollmentCard.tsx. 3. Server identity protection: done through expected_server_instance_id validation in the Rust clients. 4. Quick chat: done in src-tauri/src/quick_window.rs and the Tauri window controller. 5. Tray and status bubble: done in src-tauri/src/lib.rs and src/features/chat/StatusBubble.tsx. 6. Pet state and assets: done in src/features/pet/DesktopPetView.tsx and src/features/pet/assets. 7. Multi-monitor/game policy: done in src-tauri/src/pet.rs and src-tauri/src/windows. 8. Voice interaction: done as a Web Speech MVP in src/features/chat/ChatPanel.tsx. 9. Proactive messages: done through normalized runtime events and unread persistence. 10. Chat reliability: done with session-scoped history merge and duplicate regression coverage. 11. Diagnostics and log redaction: done in src-tauri/src/diagnostics and src-tauri/src/logging.rs. 12. Release executable and installer: done for unsigned local artifacts under target/release. 13. Final acceptance: local gate is ready; external release acceptance is pending the prerequisites below. The following are deliberately not marked complete: HTTPS certificate pinning, signed updater delivery, and real dual-server soak. They require external infrastructure or release secrets and must not be faked in local development. ## 2026-07-27:陪伴体验页面拆分与定时屏幕感知(C1 已完成) 权威规划见 docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md,安全冲突与决策门见 PD-0014。 ### C0:屏幕感知理解框架复核(2026-07-27,完成;未开发) - 评估结论写入 `docs/reports/screen-awareness-understanding-framework-2026-07-27.md`:全桌面“看一看”必须拆为 WGC 授权、质量门、最小上下文信封、视觉模型验收、低打扰决策和可撤销审计,不能等同于定时截图。 - 在 C2-C4 前新增阻塞子阶段 S0:WGC 对显示器、游戏、锁屏、受保护内容、敏感应用、拔插和资源预算的 Spike;未通过时绝不扩展当前单窗口 GDI 能力。 - 参考插件只借鉴总开关、间隔、概率、时段、互动风格、冷却、触发原因与手动状态页;不引入历史/输入轨迹、长期观察档案、远程桥接或录屏。 验收:框架明确“随机仅指触发时间”、Companion-only、无原始内容持久化、真实视觉验收及 S0-S5 的逐阶段停止条件;本轮无 `src/`、`src-tauri/` 或数据库改动。 ### S0.1:WGC 目标绑定预检(2026-07-27,完成;不读取像素) - 新增 Rust-owned WGC 预检:仅验证 Windows 是否支持 WGC,以及已授权窗口和当前已连接显示器能否绑定为 `GraphicsCaptureItem`;返回目标类型和尺寸元数据。 - 预检通过 `CapturePolicy::inspect` 复用既有窗口授权,不读取窗口文本/像素、不消耗读取预算、不创建 capture session,也不触发编码、持久化、网络或 AstrBot 上传。 - 仅为 S0 证据,不代表游戏、全屏、锁屏、受保护内容或真实画面捕获可用;S0.2 必须完成 D3D11 真实帧、黑帧/透明帧检测和 Windows 人工证据。 验收:隔离目标目录执行 `cargo check -p astrbot-desktop --lib` 通过;`cargo test -p astrbot-desktop --lib` 为 117 passed。 ### S0.2:WGC 单帧 D3D11 质量诊断(2026-07-27,代码完成;人工证据未完成) - 对已授权窗口新增一个仅诊断的一帧路径:硬件 D3D11 + free-threaded WGC frame pool + staging texture readback,最长等待 2 秒。 - 仅在 Rust 内存中将 BGRA 按行距转换为 RGBA,执行 1600 万像素上限、坏行距、黑帧/透明帧检测,并通过 PNG 编码验证转换;返回的 Tauri 元数据不包含图像字节。 - 不创建设置入口、不接入调度、不扩展显示器授权、不持久化原始画面,也不向 AstrBot 发送任何数据。 验收:隔离 Rust check、121 个库测试和 Clippy 均通过。仍缺少实际窗口/游戏、最小化、锁屏、受保护内容、显示器变化的人工证据,故 S0 整体未完成。 ### S0.3:手动 WGC 验收入口(2026-07-27,完成;等待真实场景证据) - 在“窗口读取”已授权会话卡片内增加 `WGC 本地帧验收(不发送)`;用户必须先经现有 5 秒前台窗口授权,按钮不创建新授权。 - 结果只显示尺寸、内存中验证的 PNG 大小和 `usable` / `rejected_blank` 状态;不显示缩略图、不返回图像字节、不上传、不发送消息。 - 任何失败继续显示 Rust 的可行动错误;黑帧/透明帧明确表示不支持,不能据此开启游戏陪玩。 验收:前端 typecheck、61 项 Vitest、生产 Vite 构建及本次文件 Prettier 检查通过;Rust S0.2 检查仍为 121 passed / Clippy 通过。人工场景结果仍是 S0 的阻塞项。 ### C1:聊天、语音聊天、游戏陪玩三页面壳 - 在现有“聊天”之后增加“语音聊天”“游戏陪玩”两个独立导航入口。 - 三页面共享已有连接、会话、消息和权限状态;不得各自创建 REST/SSE 客户端或复制 SQLite 数据。 - 聊天页只承载文字/附件会话;语音页承载录音、播放和转写状态;游戏页承载陪玩会话状态。 验收:导航可键盘访问;切换页面不丢流式消息;两个新增页面无新本机权限。 ### C2:屏幕感知设置页与安全状态模型 - 在“诊断与设置”增加屏幕感知分组:总开关、授权状态、最短触发间隔、概率、活跃时段、停止和脱敏回执。 - 默认关闭;随机只表示触发时机,绝不随机选择未授权的窗口、显示器或应用。 - 方案 B 已选:C2–C6 仍受 PD-0014 约束,必须先通过 WGC、窗口/显示器范围专属授权、锁屏/受保护内容和敏感应用 Spike,才可扩展当前单窗口范围。 验收:未授权、关闭、锁屏、授权过期、目标变化和断连均不能上传画面;活跃会话始终存在可见指示器与停止按钮。 ### C3:Rust 定时调度、附件发送与主动回应 - 在 Rust 侧实现概率判定、硬最短间隔、活跃时段、回复冷却和脱敏审计;React 不拥有调度或权限决定。 - 只发送给 Companion;沿用 message 内附件段的已验证 AstrBot 出站契约。 - 原始画面和窗口文本不写入数据库、日志、快照或测试夹具。 验收:概率 0 永不触发、概率 100 仅在到期后触发一次、停止后不再触发;真实 AstrBot 侧确认模型收到图片。 ### C4:全桌面与游戏陪玩 Windows.Graphics.Capture Spike(方案 B) - 先验证 WGC 对指定窗口、单显示器、全部显示器和 DirectX/Vulkan 游戏窗口的非黑帧捕获;记录 CPU、GPU、内存、窗口进程变化、显示器拔插、最小化、窗口切换、锁屏和受保护内容行为。 - 设计独立的范围专属授权:用户必须明确选定指定窗口、单显示器或全部显示器;随机调度只能复用该范围,不能自行扩张、跟随或改选目标。 - Spike 通过前,游戏陪玩和全桌面感知只显示真实阻塞说明,不能发送 GDI 黑图或声称“正在观察”。 - 禁止输入模拟、进程注入和游戏内存读取;自动画面只送 Companion,始终显示指示器和停止入口。 验收:指定窗口、单显示器和全部显示器均通过 WGC 真实画面、资源预算、敏感/受保护内容降级与可撤销授权测试后,才进入正式全桌面调度或游戏陪玩会话开发。