docs(product): define jwt and background pet behavior
这个提交存在于:
父节点
9f61578a73
当前提交
8ec7fa9612
共有 2 个文件被更改,包括 37 次插入 和 6 次删除
|
|
@ -0,0 +1,26 @@
|
||||||
|
# ADR-0007: JWT authentication, remote identity, and background pet windows
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
AstrBot Desktop must support both API-key automation and Dashboard user login. The pet must continue running after the main chat window is closed, without creating a separate Windows taskbar button. Users also need a stable remote chat identity and animated behavior.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
1. JWT login is a required capability, alongside API Key and device token. JWTs, API keys, passwords, and other credentials are accessed only by Rust and stored in Windows Credential Manager. React never receives plaintext credentials.
|
||||||
|
2. Remote identity consists of a nickname and an ID configured by the user. The nickname is for display and addressing the user; the ID is used as AstrBot `username` and for local isolation. IDs allow 3-32 ASCII letters and digits and must be unique within a local account.
|
||||||
|
3. Floating pet mode uses a borderless, skip-taskbar background window. Closing the main chat window leaves the application resident in the system tray. Floating mode is not topmost by default and is controlled by settings.
|
||||||
|
4. The first pet renderer uses PNG/WebP spritesheets and bounded animation clips. Animation state and movement control are separate. Initial clips include idle, working with a book, speaking, notification, resting walk, and error. Live2D, Spine, 3D, and user script plugins are deferred.
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
- JWT supports normal user login while API Key remains useful for automation and testing.
|
||||||
|
- Separating nickname and ID provides natural addressing without sacrificing stable session isolation.
|
||||||
|
- A skip-taskbar background window provides a clean desktop pet experience without changing local permission boundaries.
|
||||||
|
- Spritesheets provide animated and interactive behavior at lower implementation and security cost, while leaving room for a richer renderer later.
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
- Add JWT login, expiration, 401 re-login, and secure credential migration tests.
|
||||||
|
- Connect the existing pet display-range setting to the Rust window controller instead of leaving it as a frontend placeholder.
|
||||||
|
- Extend the pet-pack manifest with animation clips, state transitions, and bounded interaction actions.
|
||||||
|
- Defer game mode to Q7; do not implement game detection or game-window behavior in this decision.
|
||||||
|
|
@ -39,7 +39,7 @@ remote_username 用于远端聊天身份和会话命名,不作为本机权限
|
||||||
|
|
||||||
- 检查当前 P02 未提交改动,消除意外的大范围格式或换行 diff。
|
- 检查当前 P02 未提交改动,消除意外的大范围格式或换行 diff。
|
||||||
- 完成 Rust fmt、Clippy、TypeScript、ESLint、Prettier、Vite build、Playwright 和适用的 Tauri 构建检查。
|
- 完成 Rust fmt、Clippy、TypeScript、ESLint、Prettier、Vite build、Playwright 和适用的 Tauri 构建检查。
|
||||||
- 将测试 API Key 标记为待轮换,不再写入日志、快照或测试夹具。
|
- 测试容器允许长期使用;API Key 只在进入生产前轮换,任何阶段都不得写入日志、快照或测试夹具。
|
||||||
- 保留 `desktop-v1` Mock 传输;真实 AstrBot 走 `astrbot-openapi` 适配器。
|
- 保留 `desktop-v1` Mock 传输;真实 AstrBot 走 `astrbot-openapi` 适配器。
|
||||||
|
|
||||||
验收:现有连接基础可构建,敏感信息边界无回归,Mock 与真实适配器不会互相污染。
|
验收:现有连接基础可构建,敏感信息边界无回归,Mock 与真实适配器不会互相污染。
|
||||||
|
|
@ -88,7 +88,9 @@ remote_username 用于远端聊天身份和会话命名,不作为本机权限
|
||||||
|
|
||||||
### Q5:状态气泡与托盘整合
|
### Q5:状态气泡与托盘整合
|
||||||
|
|
||||||
- 增加非默认置顶的气泡窗口,显示连接状态、思考中、回复完成、错误和未读数。`n- 已完成:修复气泡状态标签和无障碍名称的乱码,保持默认不置顶和设置导向逻辑不变。
|
- 增加非默认置顶的气泡窗口,显示连接状态、思考中、回复完成、错误和未读数。
|
||||||
|
- 浮动桌宠窗口必须使用无装饰、跳过任务栏的后台窗口;主对话框关闭后应用继续由托盘驻留。
|
||||||
|
- 已完成:修复气泡状态标签和无障碍名称的乱码,保持默认不置顶和设置导向逻辑不变。
|
||||||
- 允许用户关闭气泡或切换到仅应用 UI 模式。
|
- 允许用户关闭气泡或切换到仅应用 UI 模式。
|
||||||
- 气泡点击按设置打开主页面或快速聊天;右键菜单提供显示、隐藏、设置和退出。
|
- 气泡点击按设置打开主页面或快速聊天;右键菜单提供显示、隐藏、设置和退出。
|
||||||
- 明确窗口层级、焦点、点击穿透(如需要)和屏幕边界策略。
|
- 明确窗口层级、焦点、点击穿透(如需要)和屏幕边界策略。
|
||||||
|
|
@ -98,10 +100,12 @@ remote_username 用于远端聊天身份和会话命名,不作为本机权限
|
||||||
|
|
||||||
### Q6:桌宠基础模型与素材包
|
### Q6:桌宠基础模型与素材包
|
||||||
|
|
||||||
- 抽象 `CompanionState`:`idle`、`thinking`、`speaking`、`error`、`notification`、`offline`。
|
- 抽象 `CompanionState`:`idle`、`thinking`、`speaking`、`error`、
|
||||||
|
otification`、`offline`。
|
||||||
- 抽象 `PetRenderer`、`PetWindowController` 和 `PetInteractionPolicy`,先支持静态 PNG/WebP 和 spritesheet。
|
- 抽象 `PetRenderer`、`PetWindowController` 和 `PetInteractionPolicy`,先支持静态 PNG/WebP 和 spritesheet。
|
||||||
- 定义可校验的 `pet-pack/manifest.json`,包含尺寸、动画帧、状态映射和可选点击动作。
|
- 定义可校验的 `pet-pack/manifest.json`,包含尺寸、动画帧、状态映射和可选点击动作。
|
||||||
- 支持应用内显示模式与全屏浮动模式的设置模型,但首版只接入状态气泡/静态形象。
|
- 动作采用受限动画片段和状态机:待机、工作写字/看书、说话、通知、休息走动和错误状态;移动路径与渲染帧分离。
|
||||||
|
- 支持应用内显示模式与全屏浮动模式的设置模型;浮动模式不占用任务栏、不默认置顶,首版接入 spritesheet 动画。
|
||||||
- 上传素材只进入沙箱目录,校验格式、尺寸、文件大小和 manifest,不执行脚本或插件代码。
|
- 上传素材只进入沙箱目录,校验格式、尺寸、文件大小和 manifest,不执行脚本或插件代码。
|
||||||
|
|
||||||
验收:可加载一个本地安全素材包并根据聊天状态切换静态状态;错误素材被拒绝且不影响主 UI。
|
验收:可加载一个本地安全素材包并根据聊天状态切换静态状态;错误素材被拒绝且不影响主 UI。
|
||||||
|
|
@ -119,6 +123,7 @@ remote_username 用于远端聊天身份和会话命名,不作为本机权限
|
||||||
### Q8:语音、主动消息与游戏陪伴接入
|
### Q8:语音、主动消息与游戏陪伴接入
|
||||||
|
|
||||||
- 在统一聊天运行时之上接入 STT/TTS,不为快速窗口或桌宠复制语音管线。
|
- 在统一聊天运行时之上接入 STT/TTS,不为快速窗口或桌宠复制语音管线。
|
||||||
|
- 必须支持 AstrBot Dashboard JWT 登录,并与 API Key / 设备 Token 作为并列认证方式,凭据统一存入 Windows Credential Manager。
|
||||||
- 明确语音目标槽位,默认 Companion;Operations 需要显式切换。
|
- 明确语音目标槽位,默认 Companion;Operations 需要显式切换。
|
||||||
- 将主动消息映射为通知、气泡状态和未读数,并提供静默时段设置。
|
- 将主动消息映射为通知、气泡状态和未读数,并提供静默时段设置。
|
||||||
- 游戏模式接入截图/状态摘要前,先完成授权提示、频率限制和隐私开关。
|
- 游戏模式接入截图/状态摘要前,先完成授权提示、频率限制和隐私开关。
|
||||||
|
|
|
||||||
正在加载…
添加表格
在新工单中引用