AstrBot-Desktop/docs/implementation-queue.md
YokiiroBW 3d1d962461
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(chat): add AstrBot dual-slot chat foundation
2026-07-20 11:31:41 +08:00

8.9 KiB

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 窗口,初始尺寸适合快速回复。
  • 支持拖动、调整大小、关闭后恢复位置和尺寸。
  • 与主窗口共享 ChatRuntime、会话选择、消息缓存、未读数和发送队列。
  • 设置中只提供一个快速聊天目标:companion 或 operations,二选一。
  • 设置中提供气泡点击导向:主页面或快速聊天;不增加第三种导向模式。
  • 处理主窗口关闭到托盘、快速窗口关闭、单实例和窗口重启恢复。

验收:从主窗口和快速窗口发送的消息进入同一会话;任一窗口关闭不影响连接和另一个窗口。

Q5:状态气泡与托盘整合

  • 增加非默认置顶的气泡窗口,显示连接状态、思考中、回复完成、错误和未读数。
  • 允许用户关闭气泡或切换到仅应用 UI 模式。
  • 气泡点击按设置打开主页面或快速聊天;右键菜单提供显示、隐藏、设置和退出。
  • 明确窗口层级、焦点、点击穿透(如需要)和屏幕边界策略。
  • 只在 Rust 窗口控制器中执行显示/隐藏/置顶,React 仅发出受限意图。

验收:气泡不默认置顶;两个槽位状态可区分;点击行为与设置一致;托盘隐藏主窗口后仍可恢复。

Q6:桌宠基础模型与素材包

  • 抽象 CompanionState:idle、thinking、speaking、error、notification、offline。
  • 抽象 PetRenderer、PetWindowController 和 PetInteractionPolicy,先支持静态 PNG/WebP 和 spritesheet。
  • 定义可校验的 pet-pack/manifest.json,包含尺寸、动画帧、状态映射和可选点击动作。
  • 支持应用内显示模式与全屏浮动模式的设置模型,但首版只接入状态气泡/静态形象。
  • 上传素材只进入沙箱目录,校验格式、尺寸、文件大小和 manifest,不执行脚本或插件代码。

验收:可加载一个本地安全素材包并根据聊天状态切换静态状态;错误素材被拒绝且不影响主 UI。

Q7:多显示器与游戏模式控制器

  • Rust 获取显示器工作区、主屏/副屏标识、DPI 和任务栏边界,形成稳定的 MonitorGeometry。
  • 提供桌宠位置策略:自由、靠边、指定屏幕、跟随主窗口。
  • 游戏模式只做策略层:优先选择副屏,无法识别时选择非当前游戏窗口所在屏幕;宠物限制在边缘安全区。
  • 通过受限的窗口/进程检测判断前台游戏,不读取或注入游戏进程,不做鼠标键盘控制。
  • 增加双屏断开、DPI 变化、全屏游戏和窗口切换的回退策略。

验收:双屏场景下位置计算稳定;游戏模式不会把宠物放到游戏中心;权限不足时安全降级为应用内模式。

Q8:语音、主动消息与游戏陪伴接入

  • 在统一聊天运行时之上接入 STT/TTS,不为快速窗口或桌宠复制语音管线。
  • 明确语音目标槽位,默认 Companion;Operations 需要显式切换。
  • 将主动消息映射为通知、气泡状态和未读数,并提供静默时段设置。
  • 游戏模式接入截图/状态摘要前,先完成授权提示、频率限制和隐私开关。

Q9:稳定性、发布与验收

  • 覆盖网络切换、SSE 重连、托盘驻留、窗口恢复、凭据失效和数据库迁移。
  • 完成日志脱敏、诊断包预览、崩溃恢复和更新流程。
  • 完成 Windows release/installer、签名、版本号、CHANGELOG 和阶段总结。
  • 通过全套阶段门槛后再进入主干合并和验收版本打包。

暂不进入实现

  • 不复制 Hermes 或 Codex 的私有实现;只参考交互模式和资源组织方式。
  • 不在首轮实现 Live2D、Spine、3D 桌宠或用户脚本插件。
  • 不实现任意 Shell、PowerShell、CMD、鼠标键盘控制。
  • 不把 AstrBot 的工具调用直接当成本机命令执行。
  • 不在没有真实附件协议验证前承诺文件上传;附件单独做 Spike。

需要用户后续接入

  • 测试容器 API Key 轮换。
  • 真实双服务器或第二容器,用于两个不同 server_instance_id 的长期并行测试。
  • 最终确定 Companion/Operations 的远端用户名命名规则。
  • 首批桌宠素材或授权素材包;在此之前使用测试 PNG/WebP。
  • 如需 HTTPS 证书指纹绑定,提供可验证的 HTTPS 入口并确认首次信任交互。