Skip to main content

​
AI 伴侣系统

伴侣系统将 Agent 变为具备个性、情感感知与游戏化成长的虚拟伴侣。

​
特性

15 物种 + 9 帽子

15 种伴侣物种和 9 种帽子，各有独特 SVG 图标与稀有度光效。支持 Agent 外观自动关联（开发者🤖🔥、研究员🦉🎓、写手🦊🌸等）。

Hermes 7 态 Petdex 引擎

精灵层采用 7 态 Petdex 语义（idle/run/review/jump/wave/failed/waiting）。审批/澄清/桌面与浏览器接管等 HITL 阻塞时显示 waiting，不再误挥手。SSE 工作流事件配合 transient/sticky/release 与心跳防卡死。

桌面端原生桌宠

Tauri 桌面端：默认在主窗口内嵌精灵；右键 「弹出到桌面」 或 Shift+点击 可打开透明置顶外置窗（PSUA），主窗最小化后仍可见状态。外置窗支持拖拽、状态气泡、单击 mini-composer 发消息、双击切换主窗、Shift 收回、透明区域点击穿透、离屏完成 mail 提醒。WebUI/SaaS：页内可拖拽覆盖层（无 OS 外置窗）。

成长与进化

5 级稀有度（Common→Legendary）+ 属性进化 + XP 经验值 + 每日零食互动 + 生日检测。

社区精灵图画廊

内置 petdex.dev 社区画廊，Canvas 缩略图预览 + 懒加载 + 搜索过滤 + 一键安装。无需手动输入 URL。

动态精灵图兼容

resolveAnimRow 引擎使用别名映射系统，自动适配 Codex 9 行、Legacy 8 行及任意行数精灵图。社区素材”即装即用”。

抗疲劳 UX

常规错误映射为安静的”审查”动画而非惊恐的失败表情。审批请求触发友好的挥手而非加载圈。

跨设备配置同步

伴侣配置（含精灵图选择）通过 /companion/config API 服务端持久化，多设备切换不丢失个性化选择。

会话 /pet 命令

在聊天输入 /pet 即可打开 Pet Palette。提交拦截在本地处理，零 LLM 消耗，无需 Agent 回合。

已安装宠物管理

画廊上方 chip 行展示已安装宠物。通过菜单移除并确认；若移除当前激活精灵，会自动清空选择并同步服务端配置。

离线 fail-open

petdex.dev 图鉴不可用时，已安装宠物仍可切换使用，无需等待 manifest 恢复。

Atlas 画质预检

安装时自动校验精灵图尺寸（Codex 8×9 / Legacy 8×8 / 非标准 / 不合格）。不合格素材在安装前即被拦截，避免模糊或损坏的精灵图进入你的收藏。

GUI 健康检查 Doctor

一键 6 项诊断：feature gate / 配置 / 磁盘 / atlas 格式 / SHA 完整性 / 本地 serve。结果中英双语 i18n，可从画廊手动触发或精灵加载失败时自动弹出。

零配置主题联动

桌宠强调色（稀有度光效、ring 阴影、状态气泡边框）通过 Theme Profile CSS 变量 token 派生自动跟随工作区主题。在「外观」设置中切换主题，桌宠即时更新，无需额外配置。Tauri 外置窗（/pet-overlay）保持轻量：跳过壁纸/ArtLayer 加载，跨窗同步强调色 token。

​
配置

  1. 进入 设置 > 伴侣 — 伴侣系统默认开启
  2. 从 15 种物种和 9 种帽子中选择
  3. 切换到 画廊 标签页浏览 petdex.dev 社区精灵图 — 搜索、预览、一键安装
  4. 在 chip 行管理已安装宠物 — 切换激活精灵或通过菜单移除
  5. 聊天输入 /pet 随时打开 Pet Palette，零 LLM 消耗
  6. 选中的精灵图配置通过服务端 API 自动跨设备同步
  7. 伴侣自动关联当前活跃 Agent 的外观

​
工作原理

伴侣系统在两个视觉层面运作：
  • SVG 层（默认）：轻量图标渲染，嵌入聊天输入区附近。自动反映活跃 Agent 的物种和帽子。
  • 精灵层（可选）：Canvas 2D 动画引擎，支持 Codex 8×9 标准精灵图（1536×1872px）。Tauri 桌面端默认主窗嵌入，可 Pop Out 至 OS 外置窗（主窗 SSOT + 傀儡窗 event 同步）；WebUI 为页内可拖拽覆盖层。resolvePetSheetRow() 自动检测 Codex（9 行）/ Legacy（8 行）布局，映射 Hermes 对齐的 7 态。状态气泡 仅在外置桌面窗 显示。
精灵状态机 = SSE 工作流事件 + GUI 阻塞信号：
  • 工作流 SSE（stepKeyToPetEvent）：规划→review、执行→run、失败→failed、里程碑→jump/review（transient）
  • HITL 阻塞（deriveBlockedOnUser 聚合审批/澄清/桌面/浏览器 store）：waiting — 需你操作时优先于 run/wave；Codex 第 6 行（Legacy 回退 idle）
  • 流式活跃：busy→review；回合结束→wave（未被阻塞时）
所有状态通过 Zustand + localStorage 管理。伴侣配置通过 /companion/config API 同步到服务端。

​
质量验证

伴侣全模块 291 项测试全部通过（2026-08-02 实测）：
  • 后端 pytest：57/57 通过 — pet_store（7）+ companion API（10）+ feature gate（23）+ companion config（17）
  • 前端 vitest：234/234 通过 — companion service（28：petInstall/petSpritesheet/formatLabel/doctorI18n/slashCommand/companionTheme）+ 组件（147：Gallery/Sprite/Icons/snack/generator/manifest/assets）+ sprite（65：Engine/StateMachine/stateMapping/surfaceBridge/statusBubble/blockedOnUser/awayCompletion）
关键覆盖率：
  • PetStateMachine：100% 行覆盖率
  • CompanionSprite：91.83% 行覆盖率
  • petSurfaceBridge：100% 行覆盖率
  • companionGenerator：99.13% 行覆盖率
  • Atlas 画质预检：Codex/Legacy/非标准/无效均已验证
  • GUI Doctor：6 项诊断链 + 中英双语 i18n
#12 伴侣 ↔ Theme Profile SSOT（2026-08-02）：
  • Gate 脚本 scripts/dev/e2e-companion-theme-ssot-gate.sh：15/15 vitest（companionTheme 含 inline style mutation + marketing-paths + ThemeProfileProvider pet-overlay）
  • Chrome MCP smoke：/settings/preferences 主题预设可点选 + 伴侣设置「跟随工作区主题」只读引导
  • 可选：COMPANION_THEME_SSOT_CHROME=1 对 live 栈跑 pytest chrome_e2e
  • 诚实边界：Canvas 精灵像素不随主题 tint（仅强调色 UI）