进行中工具
DeepSeek Pet
DeepSeek 余额管家 × 桌面桌宠（Electron）
常驻桌面的 Electron 桌宠：实时监控 DeepSeek API 余额、在低价时段提醒跑任务，支持 AI 聊天、识屏陪伴，并把 Claude / ZCode 等 Agent 的任务进度投射到桌面。
角色 独立开发（产品设计 / 架构 / 主进程与渲染层 / AI 与联动 / 打包发布）
- Electron 33（Windows 10/11）
- Node.js ≥ 20
- 主进程子系统：agentLink / llm / providers / chatStore / screen / collision / updater / hotAssets
- 原生 HTML / CSS / JS 渲染层（无前端框架）
- 14 态 FSM 与三段式帧动画播放器
- 多模块 UI（pet / bubble / panel / chat）
- 任意 OpenAI 兼容 Provider（默认 DeepSeek，V4 Flash / V4 Pro）
- SSE 流式聊天
- 还有 8 项技术
概览
一只住在桌面右下角的桌宠：实时监控 DeepSeek API 余额、在低价时段提醒「现在跑任务最划算」，还能 AI 聊天、看看你的屏幕，并与 Claude / ZCode 等 Agent 联动显示任务进度。
基于 Electron 构建的 Windows 桌面应用，透明无边框、常驻托盘、可拖拽互动、多开碰撞、角色与音效热加载；主进程子系统与渲染层、测试三端共用同一套纯逻辑模块。
问题
用 DeepSeek API 跑任务时，余额和计费时段并不直观：工作日高峰原价、其余时间半价，很容易在高峰烧钱、或者余额告急才发现。
AI Agent（Claude Code、ZCode 等）在终端里跑，进度不可见，缺少一个「抬头就能看到」的状态投射。
常见桌宠只有静态立绘与固定动作，无法和真实工作流联动，也缺少工程化的可测试架构。
目标
把「余额监控 + 低价提醒 + AI 对话 + Agent 状态投射」做成一个常驻桌面的轻量客户端。
桌宠要好用且不挡事：透明无边框、鼠标穿透、迷你模式、锁定位置、全屏自动隐藏、闲置降帧。
工程可交付：纯逻辑与 UI 分离、可离线测试、双平台 CI、能真正打出安装版与便携版。
方案
用有限状态机统一驱动桌宠行为：高优先级事件（警报 / 完成）立即打断当前动作，动作播完再回退，避免多个触发源互相抢立绘。
把时段判断、Agent 协议、碰撞物理、余额分档、semver 等抽成不依赖 Electron 的纯模块，渲染层、主进程与测试三端复用，因此行为可以离线确定性验证。
对外暴露一个本机 HTTP 事件服务：任何脚本或 Agent hook 只要发一条 POST，就能把任务进度、台词、心情推给桌宠。
架构
主进程 main.js 作为组合根（窗口 / 托盘 / IPC / 余额查询 / GPU 回退 / 多实例），下辖 electron/agentLink.js（本机 HTTP 事件服务 127.0.0.1:27890）、llm.js + providers.js（OpenAI 兼容 SSE 流式客户端与多 Provider，Key 用 safeStorage 加密）、chatStore.js、screen.js、collision.js、updater.js、hotAssets.js，并通过 preload.js 暴露 contextBridge 与 IPC 白名单（关闭 nodeIntegration、开启 contextIsolation）。渲染层由 renderer.js + modules（pet / bubble / panel / menu / drag / wander / task / balanceMood / musicDetector / easterEgg / sound / quickChat / screenSense / characters）组成，其中 src/modules/fsm 是 14 态有限状态机（五级优先级仲裁）与三段式帧动画播放器，src/chat/chat.js 是 AI 聊天工作台；src/shared/*.mjs 为三端复用的纯逻辑。
14 态 FSM + 五级优先级仲裁
- 背景
- 桌宠同时受互动、任务、余额、Agent 驱动，容易出现立绘与气泡互相覆盖。
- 选择
- 14 态有限状态机 + 五级优先级仲裁，临时动作到期自动回退
- 原因
- 高优先级事件（警报 / 完成）能立即打断当前动作，触发源之间互不感知，只调用 changeState。
- 考虑过的方案
- 各处自行决定显示内容
- 用状态机集中仲裁
- 代价
- 需要额外维护状态机与视觉门控，换取行为可预测。
纯逻辑与渲染分离
- 背景
- 桌面应用的很多行为（时段判断、碰撞物理、协议解析）本可以离线验证，但若写在渲染层就只能靠手工点击测试。
- 选择
- 把纯逻辑抽成 .mjs 共享模块，渲染层 / 主进程 / 测试三端复用
- 原因
- 同一份实现既跑在应用里，也跑在测试里，避免两套逻辑分叉。
用架构红线测试防止架构腐化
- 背景
- 桌面应用容易出现「核心文件越写越大」「共享模块偷偷依赖 Electron」这类渐进式腐化。
- 选择
- 把核心文件行数预算、共享模块纯净性、IPC 白名单一致性写成测试
- 原因
- 让架构约束变成可执行的检查，而不是靠人工 review 记得。
Key 用 safeStorage 加密，渲染层不直连 Node
- 背景
- 桌面客户端持有 API Key，且渲染层会加载外部网页内容。
- 选择
- contextBridge + IPC 白名单 + 关闭 nodeIntegration + safeStorage 加密 Key + CSP 与外链白名单 + 自定义协议路径穿越防护
- 原因
- 把密钥与文件系统访问限制在主进程，渲染层只通过白名单 IPC 通信。
技术栈
后端
- Electron 33（Windows 10/11）
- Node.js ≥ 20
- 主进程子系统：agentLink / llm / providers / chatStore / screen / collision / updater / hotAssets
前端
- 原生 HTML / CSS / JS 渲染层（无前端框架）
- 14 态 FSM 与三段式帧动画播放器
- 多模块 UI（pet / bubble / panel / chat）
AI
- 任意 OpenAI 兼容 Provider（默认 DeepSeek，V4 Flash / V4 Pro）
- SSE 流式聊天
- 识屏视觉模型
测试
- node:test（67 用例）
- 架构红线测试
- ESLint
- Prettier
DevOps 与基础设施
- GitHub Actions（Ubuntu / Windows 双平台 lint + test）
- 打 tag 自动构建 portable + NSIS
- electron-builder
基础设施
- 本机 HTTP 事件服务（127.0.0.1:27890，供 Agent hook 调用）
- GitHub Releases 自动更新（jsDelivr 兜底）
- 双平台 CI 打包
技术亮点
14 态有限状态机 + 五级优先级仲裁
高优先级事件立即打断当前动作，临时动作播完自动回退；任务、余额、Agent、菜单、互动等触发源互不感知，只调 changeState。
纯逻辑与渲染分离
时段判断、Agent 协议、碰撞物理、余额分档、semver 抽成 .mjs 共享模块，三端复用，可离线确定性验证。
三段式帧动画管线
上一状态 out → 本状态 entry → loop × repeat → out，代际令牌防竞态；统一画布 720×960 + 脚底锚点 (360,900) + alpha 交叉溶解实现无缝衔接，748 帧 / 14 状态自动校验 0 问题。
自动骨骼 rig
对平设立绘做 alpha 连通域分析，自动抠出呆毛、鲸鱼跟班、尾巴三个可动图层并驱动次要动作，零手工标注。
Agent 联动协议
一条 HTTP POST 就能把任务进度 / 台词 / 心情 / 姿势推给桌宠，天然接入 Claude hooks 与 CI 脚本。
安全与工程质量
contextBridge + IPC 白名单 + 关闭 nodeIntegration、safeStorage 加密 Key、CSP 与外链白名单、自定义协议路径穿越防护。
难点与取舍
多源状态互抢
- 问题
- 桌宠同时受互动、任务、余额、Agent 驱动，容易出现立绘 / 气泡互相覆盖。
- 做法
- 引入 14 态 FSM + 五级优先级仲裁 + 临时态到期回退，并用 fsmVisualGate() 保证基础态之外不抢立绘。
- 结果
- 状态切换可预测，高优先级事件能立即呈现。
动画接缝跳变
- 问题
- 不同状态切换时立绘会跳。
- 做法
- 三段式序列帧（entry / loop / out），entry 首帧 = out 末帧 = IDLE 首帧 = 标准站姿，用 alpha 交叉溶解消除接缝。
- 结果
- 状态切换视觉上连续。
锚点逐帧漂移
- 问题
- 帧画布与显示尺寸不一致会导致脚底抖动。
- 做法
- 统一锚点 (360,900) + 接触阴影烘焙 + 锚点以下像素清零，并用校验断言「锚点行恒为 900」。
- 结果
- 748 帧校验 0 问题。
多实例协同
- 问题
- 多开桌宠既要互相碰撞又不能相互干扰。
- 做法
- UDP gossip 交换位置 + AABB 碰撞解算（抽成纯函数便于测试），配置与进程隔离。
- 结果
- 多开可互相互动且互不影响。
桌面体感与性能的平衡
- 问题
- 透明无边框、鼠标穿透、全屏检测、闲置降帧之间存在取舍。
- 做法
- 在「看得见 / 点得到 / 不挡事 / 省电」之间逐项设置开关与阈值。
- 结果
- 常驻桌面但不影响正常使用。
进程与页面安全
- 问题
- 渲染层与主进程通信、外部网页、API Key 存储都存在边界风险。
- 做法
- contextBridge + IPC 白名单 + safeStorage 加密 + CSP + 自定义协议路径穿越防护。
- 结果
- 密钥与文件访问被限制在主进程。
权衡取舍
行为控制方式
选了 集中式状态机 + 优先级仲裁，而不是 各模块自行决定显示内容 —— 多个触发源并存时，集中仲裁才能保证视觉一致与优先级正确。
代价：需要维护状态机与视觉门控逻辑。
架构约束方式
选了 把红线约束写成测试，而不是 只靠人工 review 与约定 —— 桌面项目容易随时间腐化，可执行的检查比文档约定更可靠。
代价：核心文件的改动需要兼顾行数预算与模块纯净性约束。
资源取舍
选了 闲置降帧、窗口隐藏时暂停余额刷新、30 秒缓存，而不是 始终保持满帧与实时刷新 —— 桌宠需要长期常驻，功耗与请求量必须受控。
代价：状态更新存在最长约 30 秒的延迟。
结果
测试：npm test 67 个用例全绿（本次实测 67 passed / 0 fail），覆盖时段判断、Agent 协议、碰撞物理、余额分档、semver、白名单匹配、会话存储、FSM（14 用例）、生活状态引擎，以及架构红线。
迭代速度：5 天内从 v1.0.0（09-03）迭代到 v2.7.0（09-07），CHANGELOG 记录 24 个版本。
出包：本机 dist/ 已实际产出 12 个安装包版本（1.7.0 → 2.7.0，单包 74–127 MB）+ 便携版 exe，CI 打 tag 自动构建。
动画管线：14 个 FSM 状态、748 帧序列帧自动校验通过（画布一致 / RGBA / 锚点行恒 900 / 帧号连续）；运行时引用 WebP 约 90KB/帧，PNG 源帧不进安装包。
性能与体验：角色 / 音效包 1 秒内热加载；30 秒无交互进入降帧省电；余额查询 30 秒缓存、窗口隐藏时暂停刷新。
截图：本次实际启动打包前的开发版应用截取（桌宠 + 余额面板、AI 聊天工作台）。
收获
多个触发源共用一个视觉出口时，必须先有仲裁机制：优先级与回退规则写进状态机，比在每个模块里判断「现在能不能显示」更可控。
看起来只是细节的问题（接缝、脚底锚点）需要自动校验：748 帧靠人工看根本验不完，写成断言才能长期守住。
架构腐化可以预防：把行数预算、模块纯净性、IPC 白名单一致性变成测试，比写在文档里更有效。
截图
桌宠与余额面板（面板数据为应用内的演示数据视图） 
AI 聊天工作台：多会话、Provider 选择与流式输出 
14 态序列帧素材（含锚点与接缝校验）