# 桌面宠物 User Stories

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [桌面宠物 PRD](./prd.md) |
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |

## 角色

- **日常用户**：在多任务、多显示器场景下使用 GoodBuddy 处理日常工作。
- **首次体验用户**：刚升级或安装 GoodBuddy，尚未接触过桌面宠物功能。
- **键盘用户**：主要通过键盘操作，可能同时使用屏幕阅读器。
- **多显示器用户**：使用两个或更多显示器，可能随时插拔外接显示器。

## US-A 首次启用

### US-A1 默认不出现

**Given** 用户全新安装或刚升级 GoodBuddy
**When** 用户尚未进入“桌面宠物”设置
**Then** 桌面上不出现任何宠物窗口，托盘菜单显示“显示桌面宠物”而非“隐藏”

### US-A2 首次启用

**Given** 用户在设置中打开“启用桌面宠物”总开关
**When** 开关切换为开启
**Then** 宠物窗口在默认位置出现，使用默认外观，且不产生任何应用级或原生通知

### US-A3 关闭后完全消失

**Given** 桌面宠物已启用并可见
**When** 用户关闭“启用桌面宠物”总开关
**Then** 宠物窗口立即消失，未完成的气泡提示一并消失，托盘菜单条目恢复为“显示桌面宠物”，
且用户之前设置的位置、外观和提示偏好被保留供下次开启时使用

## US-B 快速起草

### US-B1 起草文字并转入主窗口

**Given** 桌面宠物已启用，主窗口当前隐藏
**When** 用户点击宠物并输入一段文字后点击提交
**Then** 主窗口被显示并聚焦，目标会话的输入区出现刚输入的文字作为草稿，输入焦点落在
该输入区，且没有任何消息被发送、没有任何任务被创建

### US-B2 起草时附加文件

**Given** 快速起草弹出框已打开
**When** 用户点击“附加文件”并选择一个受支持类型和大小内的文件
**Then** 该文件在弹出框内显示为待提交附件；提交后该附件出现在主窗口对应会话输入区的
待发送附件列表中

### US-B3 附加不受支持的文件

**Given** 快速起草弹出框已打开
**When** 用户选择一个超出大小限制或类型不受支持的文件
**Then** 弹出框就地显示明确的拒绝原因，不添加该文件，且不影响已经添加的其他文字或附件

### US-B4 取消起草

**Given** 用户已在快速起草弹出框中输入文字或添加附件
**When** 用户点击取消或按 Escape 关闭弹出框
**Then** 弹出框关闭且草稿被丢弃，主窗口任何会话的现有草稿不受影响，且不创建任何草稿或
任务记录

### US-B5 选择目标会话

**Given** 主窗口当前存在多个会话，且用户在快速起草弹出框中看到默认目标会话
**When** 用户在弹出框内切换目标为“新建对话”
**Then** 提交后主窗口创建并激活一个新会话，草稿内容进入该新会话的输入区，不影响原有
会话的草稿

## US-C 拖放暂存

### US-C1 拖放单个文件

**Given** 桌面宠物已启用并可见
**When** 用户从文件管理器拖动一个受支持类型的文件到宠物窗口上并释放
**Then** 宠物在拖入过程中显示可放置的视觉反馈，释放后主窗口被显示并聚焦，该文件出现在
目标会话输入区的待发送附件列表中

### US-C2 拖放多个文件，部分超限

**Given** 用户同时拖动数量或大小超出限制的多个文件到宠物窗口
**When** 用户释放拖放
**Then** 合法文件正常进入目标会话的待发送附件列表，超限或不支持的文件被单独列出拒绝
原因，不阻止合法文件被暂存

### US-C3 拖放文件夹

**Given** 用户拖动一个文件夹到宠物窗口
**When** 用户释放拖放
**Then** 宠物提示不支持文件夹，不递归展开文件夹内容，也不产生任何暂存

### US-C4 拖放选中文字

**Given** 用户在其他应用中选中一段文字并拖动到宠物窗口
**When** 用户释放拖放
**Then** 该文字进入目标会话输入区的草稿文本，行为与快速起草输入文字一致

## US-D 状态镜面

### US-D1 查看空闲状态

**Given** 当前没有任何活跃 Task
**When** 用户查看宠物外观
**Then** 宠物显示空闲状态，且可访问名称明确说明当前没有进行中的任务

### US-D2 查看执行中状态

**Given** 有一个 Task 处于执行中
**When** 用户查看宠物外观
**Then** 宠物切换为执行中状态，且该状态与 Task Center 中该任务的状态一致

### US-D3 多任务状态优先级

**Given** 同时存在一个等待处理的任务和一个执行中的任务
**When** 用户查看宠物外观
**Then** 宠物按照“等待处理优先于执行中”的规则显示等待处理状态

### US-D4 点击状态镜面打开任务详情

**Given** 宠物当前显示执行中或失败状态
**When** 用户点击宠物的状态镜面区域
**Then** 主窗口被显示并聚焦，Task Center 定位到触发当前状态的具体任务

### US-D5 状态不可用

**Given** 用于确认任务状态的 Runtime 或网络当前不可用
**When** 用户查看宠物外观
**Then** 宠物显示“状态不可用”，不回退显示为空闲或执行中

## US-E 完成与失败提示

### US-E1 主窗口不可见时收到完成提示

**Given** 主窗口当前隐藏或未聚焦，安静模式未开启
**When** 一个任务从执行中变为已完成
**Then** 宠物旁出现说明任务标题和结果的气泡，且该事件不重复触发原生系统通知

### US-E2 失败提示保持可见

**Given** 主窗口当前隐藏，安静模式未开启
**When** 一个任务失败
**Then** 宠物旁出现失败气泡并保持可见，直到用户点击查看或手动关闭，不自动消失

### US-E3 主窗口可见时不重复提示

**Given** 主窗口当前可见并聚焦
**When** 一个任务完成或失败
**Then** 不出现宠物气泡；反馈通过主窗口现有机制呈现，避免同一事件重复出现在两个位置

### US-E4 开启安静模式

**Given** 用户在设置中开启“安静模式”
**When** 之后任意任务完成或失败，且主窗口不可见
**Then** 不出现任何宠物气泡，但状态镜面外观仍随任务状态正常变化

## US-F 位置、外观与多显示器

### US-F1 记忆位置

**Given** 用户把宠物拖动到某个显示器的特定位置
**When** 用户重启 GoodBuddy
**Then** 宠物出现在同一显示器的同一位置

### US-F2 显示器断开后回退

**Given** 宠物位置记忆在一个已插入的外接显示器上
**When** 该外接显示器被移除后重新启动 GoodBuddy
**Then** 宠物出现在当前可用的主显示器上一个可见、不越界的位置，而不是不可见或位于屏幕
之外

### US-F3 贴边吸附

**Given** 用户开启“贴边”选项
**When** 用户把宠物拖动到接近屏幕边缘的位置并释放
**Then** 宠物自动吸附到屏幕边缘，且吸附后仍可被再次拖动离开

### US-F4 调整外观

**Given** 用户在设置中调整宠物尺寸、透明度或动画强度
**When** 用户改变任意一项取值
**Then** 宠物外观立即按新取值更新，且设置持久化，重启后保持

### US-F5 恢复默认外观

**Given** 用户已经修改过角色、尺寸、透明度或动画强度
**When** 用户点击“恢复默认外观”
**Then** 上述设置全部恢复为默认值，宠物位置和总开关状态不受影响

## US-G 暂时隐藏与托盘

### US-G1 暂时隐藏

**Given** 桌面宠物已启用并可见
**When** 用户从托盘菜单选择“隐藏桌面宠物”
**Then** 宠物窗口消失，总开关状态和其他设置不变，托盘菜单条目变为“显示桌面宠物”

### US-G2 重新显示

**Given** 桌面宠物已启用但当前隐藏
**When** 用户从托盘菜单选择“显示桌面宠物”
**Then** 宠物窗口在此前记忆的位置重新出现

### US-G3 应用退出

**Given** 桌面宠物已启用并可见
**When** 用户退出 GoodBuddy
**Then** 宠物窗口一并关闭，不留下任何独立运行的进程或残留窗口

## US-H 键盘与无障碍

### US-H1 键盘打开快速起草

**Given** 桌面宠物窗口通过系统级窗口切换取得焦点
**When** 键盘用户按下预期的激活键
**Then** 快速起草弹出框打开，焦点进入输入框

### US-H2 键盘关闭弹出框

**Given** 快速起草弹出框已打开且有键盘焦点
**When** 用户按下 Escape
**Then** 弹出框关闭，焦点回到宠物窗口本身

### US-H3 屏幕阅读器状态说明

**Given** 用户使用屏幕阅读器
**When** 焦点移动到宠物的状态镜面
**Then** 屏幕阅读器播报当前状态的文字说明，不仅依赖颜色或动画表达状态

## US-I 兼容与边界

### US-I1 升级用户保持现状

**Given** 已在使用 GoodBuddy 且从未接触过桌面宠物功能的用户升级到包含该功能的版本
**When** 用户正常启动应用
**Then** 桌面宠物保持关闭，界面和行为与升级前一致

### US-I2 不支持透明合成的环境

**Given** 用户的操作系统或桌面环境不支持窗口透明合成
**When** 用户启用桌面宠物
**Then** 宠物窗口退化为不透明的小型窗口而不是渲染异常或无法显示，具体规则见
[技术设计](./technical-design.md)

### US-I3 拖放到非目标区域

**Given** 用户尝试把文件拖到宠物窗口之外的桌面区域
**When** 用户释放拖放
**Then** GoodBuddy 不接收该拖放，不产生任何暂存或错误提示