宠物
启用 Kaiwu 宠物伴侣，选择内置或兼容 Codex 的宠物，并了解它们在应用各界面中的展示方式。
Kaiwu 宠物是登录应用后可启用的动态伴侣。它们可以常驻在 Web 应用外壳、移动端应用外壳中；在桌面端，还能以独立原生浮窗的形式驻留在主窗口之外。
宠物功能默认由用户自主选择开启。即使服务端启用了该功能，用户也依然保持禁用状态，直到主动在设置 -> 宠物中将其开启。
宠物功能介绍
宠物能以轻量可视化方式呈现会话动态，且不会干扰常规通知或收件箱工作流。
- 无需关注时，宠物会安静待机。
- 点击或轻触时，它们会轻巧跳跃回应。
- 宠物不会持续循环播放动画，而是在待机时偶尔做出一些微动作。
- 当会话处于运行中、等待操作、失败或待评审等状态时，宠物会切换对应的动画状态。
- 在桌面端，遇到活跃或需要关注的会话时，宠物头顶会显示紧凑的会话气泡。
宠物绝不会自行审批权限或发送消息。它们仅用于打开对应界面；只有在用户输入并提交内容后，才会发送快捷回复。
启用宠物
打开设置 -> 宠物。
- 为当前账号开启启用宠物。
- 选择内置宠物，或从已连接的设备导入宠物。
- 若需调整宠物大小，可设置伴侣尺寸。
- 在桌面端，若想让宠物常驻主窗口之外，可配置桌面浮窗。
该账号级设置默认处于关闭状态。设备级覆盖配置允许单台设备继承、强制启用或强制禁用宠物，而无需更改账号首选项。
宠物仅在已登录的应用界面中渲染，不会出现在登录页、新手引导或其他公共路由页面。
内置宠物
Kaiwu 自带多种内置宠物，无需导入即可直接使用：
- Blink
- Fury
- Milo
- Oli
- Titi
内置宠物在设置 -> 宠物中以卡片形式展示，可供点选。选中某只宠物后，当前账号的默认配置即会同步更新，除非该设备设置了仅限本地生效的覆盖项。
伴侣尺寸
伴侣尺寸滑块属于设备本地设置，对该设备上的所有宠物展示界面均生效：
- Web 应用外壳中的伴侣
- 移动端应用外壳中的伴侣
- 桌面端原生浮窗
- 设置界面中的宠物预览
可调范围为 75% 至 150%。缩放时宠物会保持与 Codex 兼容的精灵图宽高比。
导入兼容 Codex 的宠物
Kaiwu 可以检测已连接设备中与 Codex 兼容的宠物包。
在设置 -> 宠物中使用检测 Codex 宠物即可扫描当前处于活跃状态的守护进程设备。检测流程需要显式触发：在用户发起请求或执行刷新命令前，Kaiwu 不会主动扫描本地 Codex 目录。
检测到的宠物支持以下操作：
- 直接使用检测目录中的 Codex 宠物；
- 作为托管的本地宠物导入 Kaiwu；
- 在启用宠物同步时，导入至账号库中；
- 后续从设备列表中移除。
除非显式导入至账号库，否则本地宠物仅保存在当前设备中。
宠物包格式
宠物包是一个包含如下结构的目录：
<pet-id>/
pet.json
spritesheet.webp系统也支持 spritesheet.png。清单必须使用这两个确切文件名之一。
pet.json 的格式如下：
{
"id": "milo",
"displayName": "Milo",
"description": "A compact tabby companion.",
"spritesheetPath": "spritesheet.webp"
}V1 精灵图与 Codex 兼容：
| 属性 | 取值 |
|---|---|
| 尺寸 | 1536x1872 |
| 网格 | 8 列 9 行 |
| 单帧尺寸 | 192x208 |
| 支持格式 | image/webp、image/png |
各行对应的状态如下：
| 行号 | 状态 |
|---|---|
| 0 | idle |
| 1 | running-right |
| 2 | running-left |
| 3 | waving |
| 4 | jumping |
| 5 | failed |
| 6 | waiting |
| 7 | running |
| 8 | review |
在导入或同步自定义宠物之前，Kaiwu 会校验清单、媒体类型、尺寸规格、包体大小以及路径安全性。
桌面端浮窗
在基于 Tauri 的桌面构建版本中，宠物可以显示在独立的原生浮窗中。
桌面端浮窗具备以下特性：
- 保持在主应用窗口之外；
- 当浮窗接管伴侣展示时，避免在应用内重复渲染宠物；
- 出现会话气泡时自动展开，气泡隐藏后恢复为仅显示宠物形象；
- 拖拽宠物形象即可移动浮窗；
- 托盘按钮、回复输入框等控件区域设为不可拖拽区域；
- 可在设置 -> 宠物中重置回右下角默认位置。
桌面端浮窗设置包含：
- 账号默认开启/关闭状态；
- 单设备维度的继承 / 强制启用 / 强制禁用覆盖项；
- 可见性模式；
- 重置位置。
可见性模式说明：
| 模式 | 行为 |
|---|---|
| 启用时始终显示 | 只要启用了宠物及浮窗功能，就始终显示宠物。 |
| 需关注或活跃时 | 会话处于活跃、运行中或需要关注时显示。 |
| 仅需关注时 | 仅在会话等待操作、失败或待评审时显示。 |
单击宠物形象可将 Kaiwu 主窗口置顶前台。右键单击宠物形象则会弹出快捷菜单，方便将其收起。
会话气泡
当桌面浮窗有动态需要呈现时，宠物头顶会弹出紧凑气泡。气泡会显示会话标题与最新的相关消息，便于用户快速辨认会话。
气泡状态优先级如下：
- 等待操作
- 失败
- 待评审
- 运行中
- 待机
气泡支持在主应用中打开会话、直接关闭，或展开快捷回复输入框。只有在用户提交后，快捷回复才会发送给目标会话。
移动端伴侣
在移动端，开启宠物功能后，伴侣将在应用外壳中渲染。
移动端伴侣具备以下特性：
- 自动适配安全区域、键盘占位以及应用的前后台切换状态；
- 支持原生拖拽手势随意移动；
- 将位置保存为归一化屏幕坐标，自适应不同屏幕尺寸变化；
- 采用最近邻渲染，呈现清晰锐利的像素画风；
- 在平台支持的情况下，点击时提供轻微触觉反馈。
系统启用“减弱动态效果”偏好设置时，将暂停动画播放以作适配。
同步与隐私
宠物伴侣展示与宠物账号同步属于两个独立的服务端功能特性。
pets.companion控制宠物伴侣功能整体是否可用。pets.sync控制账号宠物库的同步。
服务端默认允许 pets.companion，以便用户查看该设置项，但账号级宠物设置默认处于关闭状态。除非服务端显式启用，否则 pets.sync 默认关闭。
同步功能被禁用时，内置宠物与受管本地宠物仍可在其所在设备上正常使用。导入到账号库以及同步账号选中的宠物，则依赖于 pets.sync。
同步设置与宠物记录仅存储脱敏引用、元数据、摘要及大小信息。设置中绝不会保存原始 data: URI、本地文件系统路径、客户端提供的私有对象键或精灵图原始字节。
服务端管理
自托管和托管部署均可通过服务端特性标识禁用宠物功能。
KAIWU_FEATURE_PETS_COMPANION__ENABLED=0
KAIWU_FEATURE_PETS_SYNC__ENABLED=0当服务端禁用 pets.companion 时：
- 客户端会隐藏或禁用宠物伴侣展示界面；
- 设置 -> 宠物中将显示禁用提示，而非宠物库；
- 守护进程的宠物 RPC 将统一返回功能已禁用的响应；
- 自定义宠物的导入、发现、预览及移除操作均被拦截。
当仅禁用 pets.sync 时：
- 本地及内置宠物仍可正常工作；
- 账号库导入与同步账号宠物选择功能将不可用。
故障排查
宠物未显示
请按以下顺序排查：
- 已登录并位于应用外壳内。
- 所选服务端允许
pets.companion。 - 已开启设置 -> 宠物 -> 启用宠物。
- 当前设备未将宠物设置强制覆盖为禁用。
- 在桌面端，浮窗已启用，或应用外壳宠物获准渲染。
未检测到 Codex 宠物
请确保处于活跃状态的守护进程设备在线，然后再次点击检测 Codex 宠物。检测会扫描当前活跃设备，且可能存在简短的发现缓存，因此新建的包可能需要在数秒后再次刷新。
宠物包目录内必须包含有效的 pet.json，以及名为 spritesheet.webp 或 spritesheet.png 的确切文件。
导入的本地宠物在其他设备上不可见
本地导入的宠物按设计仅保存在单台设备上。若服务端启用了 pets.sync 且您希望在多设备间通用，请将宠物导入账号库中。