dsh-pet-indesktop README

The project's README from github.com/MerZlin/dsh-pet-indesktop. As one markdown file: README.md.

dsh-pet-indesktop

一个基于 Python + PySide6 的独立桌面宠物。项目脱离 DSH 运行时，提供透明无边框、置顶、可拖动、角色切换、动画播放、系统托盘和可选 AI 对话能力。

当前版本 v4.2.0（2026-09-10 发布）：自 v4.1.0 以来的功能与修复汇总（PR #57/#64/#65/#68/#70/#71/#72/#73/#76/#79/#80/#82/#85/#86/#87/#90/#91/#93/#94/#96）。亮点：桌宠内存专项治理（长时运行不再单调上涨）、单进程多窗与同角色共享解码链（3 窗 1 进程 1 解码器）、设置与菜单重构（右键菜单可编排、快捷启动、主题即时生效）、边缘探头 / 黄金回旋 / 撞飞彩蛋 / 省电模式、待办提醒、DSH 事件层与探索 Watchdog 控制链、子肥鱼「只退出不删数据」、台词模板 v2 与表达风格、高刷屏流畅度、气泡行尾字裁切修复、DLC 换角色加固。

v4.2.1（2026-09-23 发布）：v4.2.0 之后又并入 57 个已合并 PR、192 个提交，逐项清单见 v4.2.0 以来的变更（v4.2.1）、v4.2.1 发布草稿（含发布前测试清单与视频预演脚本）与下方最近修复与变更记录。新功能：灵动岛重做（#113）、语音报时 voice_chime（#118 / #125）、节日提醒 festival_reminder（#127）、事件汇报概率门（#97）、气泡文字大小可调（#153）、Harness 服务重启/停止（#153）、聊天背景裁切取景（#163 / #167 / #169 / #170）、音乐歌词显示与「上一首」（#128 / #129 / #135）、歌词对齐（#175）、点击台词朗读与本机语音预缓存（#176）、音乐播放器路径进设置页（#177）、「互动」域设置页分页（#179）。关键修复：Windows 关机/注销弹 0xc0000142（#112，issue #111）、桥接插件归零外部依赖（#104）、DSH 事件层系统性收尾（#105）、启动即按配置装配可选服务（#100 / #102）、单进程多开下主动识屏永不触发（#145）、Linux 屏幕边缘无法贴边（#137）、岛碰撞改同步硬墙（#173）、AI 会话窗不再「贴不到底」、edge 音色被下架后「配了却不出声」自动兜底（#178）、构建不再被 PyInstaller 的 Qt 绑定互斥中止 + 产物 TTS 自检（#180）。回退：#136 / #131（歌词显示审计 + 节日动画/生日）已由 #143 撤出。

发布形态为 onedir 目录打包 + Inno Setup 安装包（.exe）+ 便携 zip 绿色版：安装版与绿色版运行期都不解压、不产生临时缓存，启动快、卸载干净。v4.2.0 完整发布清单见 docs/RELEASE-v4.2.0.md，v4.2.1 发布草稿（含测试清单与视频预演脚本）见 docs/RELEASE-v4.2.1.md，产物见 GitHub Releases。

开发约束与规则

本节的约束来自 PR #76 那轮“实测数据驱动的性能 + 结构治理”，此后每个版本都在沿用并加固；给本项目提交代码前请先读本节以及 AGENTS.md、docs/WINDOW_PY_SPLIT_GUIDE.md。

架构红线（`tests/test_architecture.py`，红了即 CI 失败）

纯逻辑层不依赖 Qt：collision.py / physics.py / collision_codec.py 禁止 import PySide6。
共享解码链单向依赖：decode_fanout.py 不得反向依赖 window.py / webm_clip.py，窗口钩子只能通过注入接入。
窗口私有面冻结：PetWindow 的 win._xxx 只允许 window.py 自身与 collision_client.py 访问；app.py / agent_link.py / context_menus/ 出现即为违规。
window.py 行数预算：当前预算 4648 行（常量 WINDOW_PY_LINE_BUDGET 见 tests/test_architecture.py，实测 4648 行，2026-09-23 校准）。历次校准理由逐行记在该文件注释里（含 #101/#102 启动装配与探头闸门、#108 弹射飞行守卫、#109 探头旋转/软撞位移、#112 会话结束的 _closing 守卫、#182 的实时性改造与上游合入）。预算只随实测校准，不靠压缩行宽/合并语句硬塞；确需上调要在 PR 说明理由。
modern_settings_dialog.py 行数预算：当前预算 2347 行（常量 MODERN_SETTINGS_DIALOG_PY_LINE_BUDGET，实测 2343 行，2026-09-22 随 #179 整域拆分首次下调；已拆出 pet/settings_interaction.py、settings_widgets / settings_menu_layout_editor / chat/ai_settings_page / settings_theme_qss），再往主对话框塞新页面属于红线。
孤儿簇守卫：settings_widgets.py、settings_styles*.qss 等文件不允许“存在但零引用”——要么删除，要么真正接线；防再发由测试守护。

文件 / 结构演进规则

window.py 处于 “只许瘦不许胖” 的增量拆分公约下：新功能预计超过约 100 行、需改 3 个以上同域方法、或行数预算告警时，先按 docs/WINDOW_PY_SPLIT_GUIDE.md 拆控制器。
拆分应机械搬移、不夹带行为变更；保留薄委托/兼容面；PR 里说明拆分域、迁出字段与共享字段。
新增普通顶层配置键必须三处同步登记：默认值 dict + reload 白名单 + test_config_schema.py 快照；特例键（version / proactive_screen / agent_link / chat）走专门迁移路径，不塞普通白名单。
单进程多开的设置作用域：每窗独立项（形象/位置/聊天等）存 config-slot-N.json；进程级共享项（托盘/共享解码/Agent 联动/待办提醒等）以主桌宠 config.json 为准，非主窗修改不生效。
新增子桌宠只在 slot 无存档时从主配置落种，已有用户存档一律保留。

CI 与测试纪律（`AGENTS.md`“CI cost discipline”）

推送前必须过三道本地门：ruff、全量 pytest、受影响时序测试族高负载复跑 3 遍；缝合/脚本化改动后必须重跑 ruff。
新测试涉及真实线程/Qt 事件循环时，必须事件同步 + 宽预算；禁止固定 sleep 猜时序、禁止赌目录枚举顺序、禁止用 monotonic 绝对值做回拨算术（CI runner 可能刚开机）。
同一族时序测试连续两轮不绿就停止重试，按既有先例隔离出主套件，不要在 PR 门禁里赌时序。
能本地复现的诊断不派付费子代理；派子代理必须给齐已知排除项。

PR 交付证据（三份证据，2026-09-22 起硬要求）

每个 PR 必须随附三份证据，缺一即视为未完成，审查时按缺陷提出（出处：AGENTS.md 的 "Delivery evidence discipline"，细则见 docs/DEV-HANDOVER.md §8.2/§8.3）：

修改文件说明：逐文件写「改了什么 + 为什么」，给出增删行数（git diff --numstat），新增/删除的文件都要列出。只写「修了 bug」不算说明。
性能分析：受影响路径的实测数字（命令 + 环境 + 样本量），并逐条回答：稳态开销、新增路径的成本与触发频率、有没有新的系统调用/网络/磁盘/线程、内存有无增长。形容词不算分析——用「可忽略 / 更快 / 优化了」代替数字视为没写。
实机测试记录：在本机真实环境（不是 CI、不是 mock）跑过什么的记录——命令、真实输出、以及用户可见行为的确认。无法自动验证的能力，必须给出「为什么不能自动」的排查证据（探针结果），不许用沉默代替结论。

落地形式：报告写入 docs/PR-REPORT-<主题>-<YYYY-MM-DD>.md（骨架照抄 docs/PR-REPORT-TEMPLATE.md），并在 docs/INDEX.md 的「PR 报告存档」登记一行；PR 描述放摘要 + 报告链接，不要把报告全文粘进去。豁免：纯文档/文案/依赖版本号这类不改变运行行为的改动，可只保留第 1 条，但必须在 PR 描述里写明豁免理由。机器化校验：tests/test_pr_report_discipline.py 对 2026-09-22 之后的报告强制校验三个必备章节（标题级）与索引登记。

版本亮点（v4.2.1）
v4.2.0 以来的变更（v4.2.1）
开发约束与规则
项目来源与素材声明
当前状态
下载与版本选择
安装教程
快速开始（安装之后）
功能概览
使用教程
AI 对话使用教程（Chat 版）
动画素材与自定义角色
开发结构
测试与验证
打包发布
旧版 onefile 缓存清理（仅旧版本需要）
配置与安全说明
最近修复与变更记录
已知限制
项目文档
许可证与致谢

版本亮点（v4.2.1）

v4.2.1 覆盖 v4.2.0 之后合并的 57 个 PR / 192 个提交，其中有 5 位外部贡献者各带了一整批（klxxya 26 个、Anguis-L 4 个、KagurazakaChizuru 3 个、Daliuq 2 个、lscatfish 2 个，逐人致谢见发布说明）。逐项清单见下方 v4.2.0 以来的变更（v4.2.1），完整发布说明见 docs/RELEASE-v4.2.1.md。

设置与菜单（本版最直观的变化）

「互动」域改页内标签（设置 → 互动：「点击与音效」/「自言自语」），侧栏 9 个域与组名不变；设置搜索命中非当前标签的行会自动切过去。
音乐播放器路径进设置页（设置 → 桌宠 → 音乐关联：两行路径 + 「自动检测」按钮），不必再手改配置文件。
气泡文字大小 50–300% 可调、Harness 服务可重启/停止、设置窗内可直接裁切聊天背景取景、「多开」开关从设置页收起（配置键原样保留）。

音乐与歌词

右键新增 音乐 → 歌词对齐（回到开头 / 上一句 / 下一句 / 后退·前进 5 秒）：网易云不上报 SMTC 播放进度，歌词只能按本地时钟估算，快进或半途起播后用它对一句即可；报进度的播放器自动置灰。
新增**「上一首」**、修「关掉再打开歌词功能后歌词永久不动」、music_player_paths 支持。
开着 VPN / 系统代理时歌词取不到词已修（歌词请求改直连，实测同一首歌 9.01s / 0 行 → 0.88s / 53 行）；网易云「音乐 → 歌词对齐」不再被误置灰。逐功能影响面见 docs/NETWORK-PROXY-AND-VPN-2026-09-22.md。

台词朗读、语音与内容

点击台词朗读默认开（self_talk_speak_enabled）：点击桌宠弹出的自言自语会用语音念出来；可选本机语音预缓存（CosyVoice 127.0.0.1:9880，默认关）。
配图概率可设（self_talk_image_chance，默认 30），修掉「图片目录一多就几乎轮不到文本」（旧行为实测出图 82.8%）。
语音报时 voice_chime（六种调度模式）与节日提醒 festival_reminder（46 个日子 / 314 条文案）；edge 音色被微软下架时自动兜底 + 重试，0 字节缓存不再算命中。

桌面玩法、碰撞与灵动岛

灵动岛重做（事件动效 / 四边停靠 / 快捷卡片）；岛碰撞改同步硬墙，杜绝穿透与区内反复反弹。
鱼-鱼碰撞体改用身体框、抛掷中只挡不弹；多进程子宠补挂远端硬墙（修多开时子肥鱼穿岛）。
探头/头槌体验三连修、边缘探头会话期禁位移、移动-动画同步与朝向规则重写（消除「溜冰感」）。

流畅度、内存与包体

走路位置交付 28.6Hz → ~160Hz @170Hz；webm 冷路径首帧不再在 GUI 线程同步解码，碰撞压力下 >50ms 卡顿 133 次 → 3 次；音效包候选解析进程级缓存（0.43ms/次）。
绿色版 zip 176.2 MB → 146.5 MB；单进程多开 + 同角色共享解码链、省电模式（闲置 30s 半帧率，解码 CPU −54.6%）。

工程与质量

PR 交付证据纪律落地并由 tests/test_pr_report_discipline.py 机器化校验（见上文「开发约束与规则」）；构建新增 Qt 绑定排他（否则 PyInstaller 在收集阶段直接中止）与产物 TTS 自检。
设置页结构治理：整域抽 pet/settings_interaction.py，modern_settings_dialog.py 2441 → 2347 行，行数预算首次因拆分下调。
测试：本机全量 2913 passed / 11 skipped / 0 failed，三平台 GitHub Actions 全绿。

上一个版本亮点（v4.2.0）

版本亮点（v4.2.0）

v4.2.0 是自 v4.1.0 以来的开发增量版，主线是「内存长稳与单进程多开」「设置与菜单可配置化」「边缘交互玩法」「Agent/DSH 生态与桌面兼容」。完整发布说明见 docs/RELEASE-v4.2.0.md。

内存与多开

单进程多开：设置 → 常规 → 多开开启后，「生小肥鱼」在本进程内孵化多只桌宠（独立 slot / 配置 / 会话 / 素材库）。实测 3 窗 1 进程 181–197MB，3.5h 无单调上涨（多进程模式约 270MB/3 只）。
同角色共享解码链：同角色多窗只保留 1 条 ffmpeg 解码链（进程内帧扇出），其余窗口订阅进食。
托盘聚合与 slot 落种：单托盘 + 每窗子菜单；新子肥鱼首占 slot 时从主配置落种，已有存档一律保留；「退出子肥鱼」只退出、不删除设置/会话/待办。
省电模式：闲置 30s+ 半帧率呈现并停止后台预热，交互立即回满（解码 CPU 实测 −54.6%）。

设置与菜单

七能力域设置页 + 右键菜单可编排：显隐、子菜单、分割线、别名、图标覆盖（内置矢量/本地图片 ≤5MB），左侧编辑、右侧实时预览；损坏配置自动回退安全菜单。
快捷启动编辑与应用列表、菜单主题即时生效、图片目录预览抽屉（3 列瀑布流）、三态响应式（1600/900/720px）。

玩法与提醒

黄金回旋（右键入口 + 点击触发/直连两个开关，连点逐圈加速）、边缘探头（±45° 贴边、点击拉直）、撞飞彩蛋（被撞翻鱼头、落地 5s 重新吸附）、拖文件模拟吃掉、动画素材 97 → 106。
待办提醒：右键「待办」面板 + 到期/提前提醒（提前量可设）、10 分钟宽限、一次性项自动归档。
气泡：配图大小 50–300% 可调，文字大小 50–300% 可调（气泡与字号一起等比放大，大屏上嫌字小时调大）；台词模板 JSON 导入/导出 + v2 占位符渲染；表达风格统一入口。

Agent 联动与 DSH

DSH 富事件状态（thinking / working（带工具名）/ attention / error）、审批与提问气泡（多问题项、interaction_id 多交互并存）、探索循环 Watchdog 控制气泡（自动优化 replan / 终止 interrupt / 忽略，GUI 不阻塞）。
启动体验：Harness 复用本机已有实例（不再拉第二个浏览器）、harness_autostart 随桌宠起服务、探测链路静默化、macOS Finder Node 解析；服务本身可重启/停止（见「最近修复与变更记录」的 2026-09-19 条目）。

跨平台、安全与兼容

Windows 打字频闪根治（原生 WS_EX_TRANSPARENT）、macOS Dock 隐藏彻底生效 + 原生 Dock 菜单、Linux Fcitx 中文输入随包插件；明文 API Key 自动迁入 keyring；直播捕获（OBS/直播姬）气泡兼容；DLC/换角色加固（缺失动画不崩、启动回退默认角色、点击台词支持外部素材目录）。

v4.2.0 以来的变更（v4.2.1）

v4.2.0（2026-09-10 发布）之后，main 上又积累了 54 个已合并 PR、约 175 个提交（另有若干直推修复），全部尚未发布——当前正式版本仍是 v4.2.0。本节是这批变更的总览；带根因与验证细节的逐条记录见下方最近修复与变更记录；面向发布的完整说明（含 发布前测试清单 与 视频预演脚本）见 docs/RELEASE-v4.2.1.md。

新增功能

桌宠玩法与外观

灵动岛重做（#113）：事件动效、四边停靠、快捷卡片；果冻墙改本进程直连碰撞。
气泡文字大小可调（#153）：新配置键 bubble_text_scale（50–300%，默认 100，设置 → 外观 → 桌宠显示）。列宽、换行预算、label 尺寸与字号共用同一系数整体等比放大，标准气泡与呼吸气泡都生效；默认 100% 时与旧版逐像素一致。
聊天背景裁切取景（#163 / #167 / #169 / #170）：主设置窗新增取景入口，编辑结果随保存落盘；裁切选区纵横比按编辑风格取值；入口标注当前风格、非填充裁剪时隐藏（渲染链恢复见 #163）。
移动-动画同步与朝向规则重写（#157）：位移锁定步态整圈、位置解码帧驱动，消除「溜冰感」；朝向永远由目标决定，不再被随机数翻转。

设置与菜单

「互动」域设置页分页（#179）：设置 → 互动由 18 行 / 3 组平铺（当时最长的「无折叠」域）改为两个页内标签——「点击与音效」（输入 + 点击反馈）与**「自言自语」（周期气泡的台词 / 节奏 / 配图）；侧栏 9 个域与组名 输入 / 点击反馈 / 自言自语 属对外契约，一律不变。设置搜索命中非当前标签的行时自动切到那个标签**（搜「配图概率」→ 切到「自言自语」）。modern_settings_dialog.py 2441 → 2347 行（首次因拆分下调行数预算），整域搬进新模块 pet/settings_interaction.py。
音乐播放器路径进设置页（#177）：设置 → 桌宠 → 音乐关联新增两行路径（网易云音乐 / QQ音乐）+「自动检测」按钮，不必再手改 config.json。

提醒与音乐

语音报时 voice_chime（#118 / #125）：edge-tts 合成，六种调度（每小时 / 30 / 15 / 5 分钟 / 每分钟 / 自定义时间点）；台词库每天整套换新（按日期确定性洗牌，当天固定一套排列、日内按序取用；中文库 120 条、英文库 96 条，每 15 分钟一天 96 次不重句），气泡文本与口播文本解耦（阿拉伯数字 vs 中文读法）；提前预合成以降低延迟。默认关闭，且默认不占用右键菜单（#157）。
节日提醒 festival_reminder（#127，默认关闭）：中国节日 / 24 节气 / 西方节日三类可选，共 46 个节日定义与 314 条氛围文案；命中当天用气泡告知，可选语音念出，并与语音报时在同一分钟自动让位、不叠音。
音乐歌词显示 / Agent 消费统计（#128 / #129）；音乐菜单**「上一首」与音乐采样线程生命周期修复（#135**）——修「关掉再打开歌词功能后歌词永久不动」（_sample_stop 事件只 set() 没有复位路径），并把 SMTC 查询 / 菜单暂停切歌移出主线程（实测「模拟 SMTC 卡 6 秒」：修复前 _on_tick 阻塞 6.00s、修复后 0.0000s）；同时补齐 psutil 依赖声明与构建收集，否则该修复在打包版里等于没修。
点击台词朗读 self_talk_speak_enabled（#176，默认开）：点击桌宠弹出的自言自语直接用语音报时的音色念出来（与报时共用音频通道、不叠音）；不想要就关掉这一行。同时把**「点击触发自言自语」的显隐与朗读与「气泡自言自语」总开关解耦**——显示与朗读只认 click_show_self_talk（此前关掉定时气泡会连点击台词一起消失）。
台词自动预缓存 self_talk_voice_precache_enabled（#176，默认关）：保存设置后与每次启动 9 秒后，在后台把「点击台词 + 点击动画绑定台词」合成为本机语音文件（<配置目录>/self_talk_voice/<文本摘要>.wav）——命中即本地播放，点击秒出、断网也能说；幂等补齐（只补没有音频的句子）、单飞不叠线程、0 字节残文件当缺失重合成、服务不可用整轮跳过只记一条日志。需要本机 CosyVoice 语音服务（http://127.0.0.1:9880 的 /health 返回 ok；本机合成一句约 20–60 秒，所以只在后台做）；没装就保持关闭，点击仍走在线合成、不会变哑。
自言自语「配图概率」self_talk_image_chance（#176，默认 30）：改为先掷骰决定出图还是出文本，再在对应池内等权选。此前是「文本 + 图片拼成一个列表等权随机」，图片目录里几十张图时实际出图率可达 80%+、文本几乎轮不到（实测 24 图 + 5 句 → 82.8%）。0 = 只出文本、100 = 只出图；想恢复旧观感填 图数 ÷ (图数 + 文本数)。只有一边有内容时不掷骰子（避免「点一下什么都不显示」）。改完需重启桌宠生效。

文件解读与隐藏对话

拖文件解读（#147，PR1 主链路）：拖文件给桌宠吃掉后，若含可解读文本文件且功能开启，弹粘性确认气泡（解读 / 不用了）；确认后新建 AI 会话把内容发给当前模型，请求期间按 progress_interval_seconds（默认 15s）冒泡汇报「已读 N 字 / 已耗时 X 秒」，完成后气泡展示摘要并把 user+assistant 消息回写会话（AI 对话窗口可见，标题「文件解读：<文件名>」）。可解读 = 文本类后缀（聊天附件白名单 ∪ 常见代码后缀），共享 20 万字符预算；目录 / 图片 / 二进制不解读。新增设置域「文件识别」与嵌套配置键 file_interpret。
灵动岛隐藏时对话气泡（#148）：桌宠全部隐藏后单击灵动岛，弹出锚定在岛上的对话气泡；AI 回复到达自动弹预览（不抢焦点、15s 无交互自动收回）；隐藏期间聊的内容与可见时同一条会话链路；气泡内置「显示桌宠」按钮作为恢复入口。配置键 dynamic_island.hidden_chat（默认开）。

Agent 联动与 DSH

事件汇报概率门（#97）：新增 pet/report_gates.py，8 个事件聚合类别各一个 0.00–1.00 概率滑块（默认 activity 0.6、其余 1.0），旧布尔开关自动迁移；概率门只作用于「弹气泡」这一步，检测与原始记录链不采样。
Harness 服务可重启 / 停止（#153）：菜单项升级为子菜单（启动并打开页面 / 重启服务 / 停止服务）；停止时按端口反查进程并核验命令行确为 dsh web，端口被非 dsh 进程占用或反查不到属主时一律不终止，只如实报告。
桌宠隐藏时联动反馈改道灵动岛（#151）：隐藏后 DSH 联动气泡走岛的对话通路，不再整段跳过状态管线。

关键修复

桌面与交互

点击桌宠不再夺走前台/键盘焦点——修全局复制粘贴失效（#121，issue #98）。
点击音效对象粘在 Qt 错误态后永久静音（#120，issue #116）。
边缘探头露出量算错坐标系，角色几乎整只露在屏外（用户反馈「按框探头」）。
探头/头槌体验三连修 + 气泡分页避头尾、末页孤行重平衡、逐页自适应停留（#109）。
探头会话期间禁止位移，不再「挂着探头姿态被平移出屏幕边缘」（#101）。
弹射全程动画切换封死冷首帧解码，消除弹射卡顿（#108）。
灵动岛左右停靠反复滑出/收回时细条持续上窜（#155）；移动续圈在 GifClip 圈边界的一帧位置回退（#168）。
拖文件解读整文件读入卡死 GUI，改为有界读取（#152）。
边缘探头入场可见区与旋转基准换算到虚拟坐标，修边缘松手回弹到修复前位置（#146）。
气泡稳定性与运行时内存治理批（#140）。
气泡长文本体验 + 菜单/设置页折叠收口（#123）；AI 会话窗「贴不到底」（自己发的消息与 AI 回复都贴在上边界，回复生成完还要手动上滑才看得见）。
音乐歌词跟随快进（#175）：实测网易云音乐完全不上报播放进度（SMTC position / end_time 恒为 0.0，播放中、暂停、切歌、快进四种状态采样结果一致），歌词只能按本地时钟估算，于是快进或从中途开始播放必然错位。新增右键菜单「音乐 → 歌词对齐」（回到开头 / 上一句 / 下一句 / 后退 5 秒 / 前进 5 秒；报进度的播放器会自动置灰并说明理由），并把"开启功能时歌已在播"从静默跳过（连歌名都不显示）改为先亮歌名 + 提示一次可对齐；同时修「向后拖到第一句歌词之前仍显示旧句」与多会话下跳到浏览器里那首歌（会话选取改为粘住当前播放器）。

碰撞与物理

岛碰撞彻底移除 30Hz 检测，改为屏幕边界式同步硬墙（位置钳制），杜绝穿透与区内反复反弹的「鬼畜抽搐」（#173，Closes #146）；桌宠碰撞代理改椭圆、抛掷中只挡不弹；鱼-鱼碰撞体改用身体框。
碰撞卡顿三连修：落地预热离线程 / 飞行期首帧 pin / 岛内容层缓存（#114）。

平台与系统

Windows 关机/注销必弹 0xc0000142 且阻塞关机（#112，issue #111）：会话被拆除后仍 CreateProcess 新 ffmpeg；新增进程级「会话结束」闸门，四条 ffmpeg 派生路径全部拒绝，关机不再弹窗。
Linux 屏幕边缘无法贴边（issue #103）：GNOME/mutter 会把移出工作区的窗口整体钳回（raw X11 XMoveWindow 同样被钳，已实测），旧的「窗口悬出屏幕、身体贴边」边界算式全部退化为 no-op。改为虚拟窗口位置语义——窗口本体主动钳入工作区、帧按绘制偏移在窗口内平移，身体贴到屏幕边缘；并新增角色包 manifest 的 body_box 稳定身体框通道（alpha≥128 口径，shenshen 实测 [212,60,428,330]）。真机实测边缘间距 L/R≈154 → 个位数 px；屏幕中央 delta 恒为 0，Windows/macOS 逐像素不变（#137）。
Windows CI 的 C 级 access violation 两次事故：先是 WinRT 并发崩溃（#142，该修复随后与 #141 一起被 #143 回退，实测无效）；真凶是 #140 新增的音乐播放器预热扫盘（#149，事故 2026-09-19）——_search 对 C:/、D:/ 等盘根做三层浅扫，而预热对网易云 / QQ 音乐各起一条线程并发扫同一批盘根，与 Python GC 交叠后在原生层崩溃（崩溃位置漂移、macOS/Linux 全绿）。修复为 _search 全局串行化 + 测试进程内桩掉扫盘。
bridge 冒烟 app-dir 归一绝对路径，修 CI Linux/macOS 构建红（#139）。
POSIX 停止 dsh 改按进程组终止，不再残留 node 子进程；Harness 停止/重启离开 GUI 线程（#158 / #159）。

Agent 联动与 DSH

桥接插件归零外部依赖（#104）：link: 安装不装被链接包自身依赖，打包副本上解析失败会让 dsh web / headless / desktop 全 profile 起不来；恢复零依赖设计，构建门禁从「必须声明依赖」反转为「禁止声明任何依赖」。
DSH 事件层系统性收尾（#105）：cordis 审批交互链从未工作、问题气泡在 mux 断线时关不掉、5 个正常事件漏登记导致每次操作都伴随「请更新/重装 bridge」假提醒、无 pnpm 时卸载假成功并留下 link: 残留。
Windows node/pnpm 解析不再写死（#97，issue #95）。
启动即按配置装配可选服务——重启后已开启的 Agent 联动与主动识屏开机不生效（#100 / #102，issue #99）。
单进程多开下主动识屏永不触发（#145）：_physics_mode 代理返回 False 而非哨兵 None，使交互判定恒真、每次 tick 被静默拦截。
余额多币种响应不再盲取首条，修「余额在 ¥0.00 与真实值之间跳动」（#107，issue #106）。
识屏身份提示改用重命名后的角色别名（#144）。

语音与提醒

edge 音色被下架后「配了音色却没声音」（#178）：微软下架了 10 款 zh-CN 音色（晓辰 / 晓涵 / 晓梦 / 晓墨 / 晓秋 / 晓睿 / 晓双 / 晓萱 / 晓颜 / 晓悠），配置指向它们时 edge-tts 抛 NoAudioReceived: No audio was received. Please verify that your parameters are correct.，用户只看到一句「语音合成失败（NoAudioReceived: …）」；更隐蔽的是缓存目录里留下的 0 字节 mp3 会被当成命中——播出一声静音且永远不再重合成。现在：配置音色不在可用表里 → **自动改用默认音色「晓晓」**并提示一次（音色「晓涵」已不在微软在线音色表里（多半被下架了），本次改用默认音色「晓晓」；可在设置 → 语音 → 语音报时 → 音色里换一个可用的。，每进程只提示一次）；每个候选音色最多重试 2 次（失败后间隔 1.5 s）再退默认音色重试；0 字节缓存判为未命中并清理半截产物（服务端「成功但空文件」也算失败）；内置音色清单按微软在线表重建为 36 款（中文 14 + 英文 22），设置页里不在清单的配置值显示为「不在清单里：<值>」。实机复核：用已下架音色触发 → 自动改用默认音色并产出 22 752 字节音频；list_voices() 返回 322 款。
语音报时 / 提醒链路加固（#159 / #160，逐条清单见下方「工程、测试与文档」）：提醒队列死锁、看门狗误杀新连接、菜单销毁后访问已删对象、POSIX 残留子进程；以及卡住检测定时剪枝、报时 busy 门改排队补播、预热分类口径、quick_chat 气泡形状、连接测试线程安全。

回退

#136 / #131 经 #143 撤出：歌词显示的审计修复与节日动画/生日因 Windows CI 出现 C 级 access violation 被整批回退——#143 一个提交内先撤掉自己的 #142（WinRT 闸门修复）、再撤 #141（#136 / #131），净 diff 为 69 文件 +573 / −5612，#141 的改动在 main 上零残留（pet/festival_animations.py、pet/http_util.py、pet/media_window.py 与 assets/characters/shenshen/videos/random/端蛋糕送礼物.webm 均已删除，节日动画与「我的生日」功能不存在）。歌词显示功能本体仍在（pet/music_lyric.py 等），撤下的只是那批审计修复。#143 明确保留：#135 采样线程修复、#137 Linux 贴边、#139 bridge 冒烟。节日提醒（#127）不受影响，仍然保留。
- 这次回退的判断次日即被证伪：#150 内的修复提交写明「#143 把当时的头号嫌疑 now_playing / WinRT 整体回退后崩溃仍现，说明另有凶手」——真凶是 #140 引入的播放器预热扫盘（见上面「关键修复」的 #149 条目）。
#164 经 #166 回滚：内置自言自语接回 dialogue_mode 风格路由的改动（thinking 键语义误用）已撤回。

工程、测试与文档

测试自欺修复（#161）：把「固定 sleep 赌时序」的用例改成确定性同步（webm_clip_loop 三处、agent_link_threads 两处、slot 竞争改 flag 文件放行），并新增「worker 线程喂入时信号槽必须在 GUI 线程执行」的护栏用例。
删死代码净 −662 行（#162）；收敛四处重复实现（#165）。
新增 scripts/slim_bundle.py 包体瘦身并接入 onedir 构建（#125）：绿色版 zip 176.2 MB → 146.5 MB（−12.8%），onedir 目录约 309 MB → 256.2 MB（移除 124 个冗余文件 / 53.03 MB）；白名单移除 + 依赖闭包校验，任一校验失败即中止。
新增 docs/INDEX.md——全文档唯一入口索引 + 新文档入场与互链规则。
生命周期加固四则（#159）：提醒队列死锁 / 客户端看门狗误杀新连接 / 菜单销毁后访问已删对象 / POSIX 残留子进程。
行为修复五则（#160）：卡住检测定时剪枝后重算分数、语音报时 busy 门改排队补播、预热分类与运行分类统一 manifest 口径、quick_chat 呼吸气泡大圆角回退、连接测试 worker 对已删对话框的安全闸。
交付证据纪律（#180）：每个 PR 必须交付「修改文件说明 / 性能分析 / 实机运行记录」三份证据，模板 docs/PR-REPORT-TEMPLATE.md，由 tests/test_pr_report_discipline.py 机器化校验（校验模板存在、AGENTS.md 与 DEV-HANDOVER.md 仍写明要求、生效日之后的报告标题级含三章节且在 docs/INDEX.md 登记）；2026-09-22 起生效，历史报告豁免。
构建 Qt 绑定排他 + 产物 TTS 自检（#180）：打包机上装了 PyQt5 时 PyInstaller 会在收集阶段直接中止（ERROR: Aborting build process due to attempt to collect multiple Qt bindings packages…），而 edge-tts 正是在收集阶段被打断的——新增 20 个 --exclude-module（其余 Qt 绑定 + 把它们拖进来的 matplotlib / IPython 栈；原有排除一条不减）。另新增 scripts/verify_bundle_tts.py：在打包机算出 import edge_tts 的导入闭包，与产物 exe 的内嵌 PYZ / _internal 清单比对，缺一即中止构建（实测真产物 25 个必需模块全在、exit=0；修复前曾因 .pth 启动期注入模块与运行时合成模块假红，已修并加 7 条回归用例）。
角色头部框数据（#180）：assets/characters/shenshen/videos/manifest.json 新增 head_box，pet/catalog.py 新增 character_head_box()（未声明时按身体框上缘取 45% 兜底）——为「边缘探头只露头」铺路；当前零调用方、本版尚未接线。
设置页结构治理（#179）：整域抽 pet/settings_interaction.py，modern_settings_dialog.py 2441 → 2347 行、行数预算首次因拆分下调；「自动化与联动」（94 行）仍是最长域，按同法分页是下一步。
edge-tts 音色事故档案 + 回归（#178）：新增 docs/ISSUE-EDGE-TTS-VOICE-DEPRECATION-2026-09-22.md（排查链与残留风险）与 13 条离线回归用例 tests/test_voice_chime_edge_voice.py（重试、退默认音色、空音频算失败、非空缓存判定、提示只弹一次）。

历史版本亮点（v4.0.0）

v4.0.0 版本亮点

v4.0.0 是一次大版本升级：在 v3.1.1 的桌宠基础上，合并了社区贡献者的现代桌面体验重构（PR #11/#12/#13）与性能/主动陪伴体系（PR #7），并完成多轮用户反馈修复与新增功能。以下是本版新增能力的总览：

桌面体验重构（现代双 UI）

新版右键菜单：紧凑七组布局 + 线性图标、顶部彩蛋入口、半透明表面、可跟随系统/浅色/深色的主题、UI 字体/字号/密度/圆角可调；「切换菜单模板」可一键回到旧版经典菜单。
新版设置对话框：侧边栏 + 卡片式布局，常规 / 桌宠行为 / 外观 / AI 对话 / 快捷启动 / 主动识屏多个页面；所有改动关闭即自动保存并立即生效（含直接点 X）。
新版 AI 对话窗口：现代双栏工作台（左侧会话管理 + 右侧消息画布），自绘标题栏、会话搜索、批量管理、跟随桌宠、背景主题（内置壁纸/自定义图片/裁剪取景）；保留旧版手机式聊天窗可随时切换。
彩蛋入口（欧鲸鲸）：新版菜单首行可配置的趣味入口，点击随机弹出一张图片；弹窗时机、图片回退、多开层叠都已打磨。
「生小肥鱼」多开：从菜单一键孵化第二只独立桌宠，自动避让位置、配置与会话相互隔离。

性能与主动陪伴（PR #7）

隐藏即零功耗：桌宠隐藏后暂停动画解码与全部活动定时器（实测隐藏后 CPU ≈ 0%），显示时立即恢复。
启动懒加载：动画素材按需加载与优先级预热，冷启动更快。
主动识屏（Windows + Chat 版）：可选的"主动识屏陪伴"——白名单应用切换、停留时长门限、每日上限与冷却、dry-run 验证模式，截图不落盘。
Agent 联动：内置 DSH 桥接插件与 Claude hooks 安装器，桌宠可感知 AI Agent 干活状态并切换动作/冒泡。

稳定与修复批次（多轮用户反馈 + 三方审查）

设置保存链路：X 关闭自动保存、保存即生效（不再需要点「保存」）、钥匙串/文件双通道。
深色系统全面适配：设置界面、菜单、聊天窗按钮/图标在 Windows 深色模式下不再白底白字。
聊天窗渲染修复：无边框圆角窗口（去掉窗外方形背景）、图标颜色跟随界面主题、缩放光标不再卡住。
并发与内存：打字机串写会话、菜单泄漏、ChatService 竞态、子进程回收等一批高危修复。

新增桌宠功能（本版）

锁定位置：桌宠固定不动、无法拖动（点击互动仍有效）。
SHIFT+左键拖动：开启后必须按住 SHIFT 才能拖动桌宠。
不透明度：桌宠窗口 10%–100% 可调。
托盘菜单同步：鼠标穿透 / 开机自启在设置里改动后，托盘菜单勾选状态实时同步。
旧版聊天窗补全：会话重命名（含深色主题适配）。

项目来源与素材声明

项目来源与素材声明

本项目改自、源于 PC2005-cloud/dsh-pet。桌宠的基础交互思路、动画链行为模型和部分资源组织方式来自原项目，感谢原作者的开源贡献。

DeepSeek 余额显示（气泡/小部件思路）参考了 MeteorNOX/DeepSeek-Balance-Whale-Widget，本项目的实现为桌宠内置的轻量版（菜单「DeepSeek 余额」+ 可选自动刷新，通过 DeepSeek 官方 /user/balance 接口查询，详见 DeepSeek API 查询余额文档）。

当前动画素材已同步参考项目近期更新后的高清 WebM 资源。项目以 WebM 目录为动画源；assets/characters 包含 106 个 WebM 动画文件。GIF 目录仅在构建 GIF 变体时生成。后续新增或替换动画时，请更新 WebM，需要构建 GIF 变体时再生成对应 GIF。

当前状态

当前状态

v4.2.1（2026-09-23 发布）：v4.2.0 之后并入 57 个已合并 PR、192 个提交（PR #97–#183）——新功能：灵动岛重做（#113）、语音报时 voice_chime（#118 / #125，默认关闭）、节日提醒 festival_reminder（#127）、事件汇报概率门（#97）、气泡文字大小可调（#153）、Harness 服务重启/停止（#153）、聊天背景裁切取景（#163 / #167 / #169 / #170）、音乐歌词显示与「上一首」（#128 / #129 / #135）、歌词对齐（#175）、点击台词朗读 + 本机语音预缓存 + 配图概率（#176）、音乐播放器路径进设置页（#177）、「互动」域设置页分页（#179）；关键修复：Windows 关机/注销弹 0xc0000142（#112，issue #111）、桥接插件归零外部依赖（#104）、DSH 事件层系统性收尾（#105）、启动即按配置装配可选服务（#100 / #102，issue #99）、单进程多开下主动识屏永不触发（#145）、点击桌宠夺走焦点导致全局复制粘贴失效（#121，issue #98）、Linux 屏幕边缘无法贴边（#137）、岛碰撞改同步硬墙（#173）、edge 音色被下架后自动兜底 + 0 字节缓存不再算命中（#178）、构建不再被 PyInstaller 的 Qt 绑定互斥中止（#180）；另有 #136 / #131（歌词显示审计 + 节日动画/生日）经 #143 回退、#164 经 #166 回滚。逐项清单见 v4.2.0 以来的变更（v4.2.1）与下方最近修复与变更记录；发布说明、验收清单与视频预演脚本见 docs/RELEASE-v4.2.1.md。
v4.2.0（2026-09-10）：自 v4.1.0 以来的功能与修复汇总，含 PR #57/#64/#65/#68/#70/#71/#72/#73/#76/#79/#80/#82/#85/#86/#87/#90/#91/#93/#94/#96——桌宠长时运行内存稳定（多进程模式 ~270MB/3 只；单进程多窗 3 窗共 1 进程约 181–197MB，3.5h 无单调上涨）；单进程多窗共享解码（同角色多窗 1 个 ffmpeg 解码链）；设置与菜单重构（右键菜单可编排、快捷启动、主题即时生效）；边缘探头/黄金回旋/撞飞彩蛋/省电模式；待办提醒；DSH 事件层与探索 Watchdog 控制链；子肥鱼「只退出不删数据」；台词模板 v2 与表达风格；打字频闪根治；气泡行尾字裁切修复；DLC 换角色加固。完整清单见 docs/RELEASE-v4.2.0.md。
v4.1.0（累计版）：自 v4.0.0 以来的功能与修复汇总——多开碰撞、灵动岛、快速对话气泡、自定义 Agent 联动通道、API/Provider 列表、右键菜单 LTR、三平台 CI 等（PR #36/#39/#40/#41/#44/#46/#47/#49/#50/#52/#53/#54/#55/#56/#59/#60）。
v4.0.5：功能版——音效体系升级（点击音效包/Agent 联动音效）、甩出力度档位、弹弓弹射、光标隐藏自动穿透、点击 Q 弹卡顿修复、自启变体独立（PR #33/#34/#35）。
v4.0.4：功能版——余额分档动画、DeepSeek 峰谷提示（可自定义文案与颜色）、后台音乐自动唱歌、点击音效打断、移动动画调整、位置记忆修复、自启残留清理、thinking 专属气泡文案等（PR #29/#30/#31/#32）。
v4.0.3：紧急修复版——修复 Windows 透明像素点击穿透、DSH 桥接插件自动安装 pnpm，以及 Windows 官方包中文乱码（PR #27/#28）。
v4.0.2：v4.0.1 的修复版——自定义点击音效支持 MP3/OGG/FLAC（不再仅限 WAV）、动画边缘毛边与帧率精度修复、右键菜单懒加载与智能避让、设置期间暂停气泡、macOS/Linux 补打包 integrations 资源（DSH 桥接一键安装）、Chat 版显式收集 keyring（API Key 系统安全存储）等（详见下方「最近修复」）。
v4.0.1：v4.0.0 的修复版——修复 Windows「自动隐藏任务栏」下桌宠随任务栏误隐藏（PR #18）与副屏位置开机自启不恢复（PR #16，issue #8），并含主动识屏并发、DSH 桥接安装加固等修复（详见下方「最近修复」）。
v4.0.0：Windows 发布 WebM 两个版本（Chat 版与无 Chat 版），均提供安装包与绿色版；macOS（Apple Silicon）与 Linux（x86_64）由 GitHub Actions 构建发布。
安装包免管理员、按当前用户安装，向导中可自由选择安装盘符与目录；卸载后无残留运行缓存。
绿色版解压即用、删除即卸载，可放在任意盘符或 U 盘。
右键菜单/托盘菜单默认使用新版现代风格（可一键切回旧版模板）；设置对话框与 AI 对话窗口均为新版现代双栏布局，旧版手机式聊天窗保留可切换。
桌宠隐藏后动画与定时器全部暂停（低功耗），显示时立即恢复。
桌宠支持锁定位置、SHIFT+左键拖动与不透明度设置。
可选「主动识屏陪伴」（Windows + Chat 版，默认关闭）与 Agent 联动（DSH 桥接 / Claude hooks，默认关闭）。
WebM 播放速率设置可调，切换动画后仍按当前速率播放；支持相邻非待机动画之间的可选等待间隔。
支持可开关的随机自言自语气泡，并优先定位在角色当前可见形象的正上方。
AI 对话窗口为独立窗口（现代双栏或经典手机式），不改变桌宠主窗口的透明背景、mask、鼠标穿透和动画状态机。

下载与版本选择

下载与版本选择

正式发布时请以 Releases 页面实际上传的文件为准。当前推荐下载的 Windows 产物如下：

版本	安装包（setup.exe）	绿色版（zip）	适合场景
Chat WebM	`dsh-pet-standalone-webm-chat-setup.exe`（约 128 MB）	`dsh-pet-standalone-webm-chat-portable.zip`（约 156 MB）	WebM 高清播放 + AI 对话，功能完整
无 Chat WebM	`dsh-pet-standalone-webm-setup.exe`（约 128 MB）	`dsh-pet-standalone-webm-portable.zip`（约 156 MB）	只想要桌宠本体，不接入 AI

选择建议：

想体验完整功能（含 AI 对话）：装 Chat 版。
只需要桌宠陪伴：装无 Chat 版，包体更小、启动更轻。
不想安装、追求便携：用绿色版 zip，解压到任意目录双击即用。

两个版本使用同一套高清 WebM 素材（106 段动画），只是入口不同：Chat 版会加载聊天子系统，无 Chat 版完全不携带 AI 对话依赖。

旧版 GIF 超大单文件（约 800 MB，运行时会在 C 盘临时目录解压并可能残留缓存）不再默认发布；确有需要可参考本文档「打包发布」一节自行构建 GIF 变体。

macOS（Apple Silicon）用户：产物为 dsh-pet-standalone-<webm-chat|webm>-macos-arm64.zip（onedir .app），由 GitHub Actions 构建，见下方「macOS 使用」。GIF 变体自 v4.0.0 起不再发布，需要请自行构建。

Linux（x86_64）用户：产物为 dsh-pet-standalone-*-linux-x86_64.zip（onedir 目录，解压即用），由 GitHub Actions 构建，见下方「Linux 使用」。

安装教程

安装教程

方式一：安装包（setup.exe）安装

下载：选择 dsh-pet-standalone-webm-chat-setup.exe（或无 Chat 版）放到任意位置。
双击运行：如果出现 Windows SmartScreen 提示，点「更多信息 → 仍要运行」（软件尚未购买代码签名证书）。
选择语言：向导默认简体中文，也可切换 English，点「下一步」。
选择安装目录：
- 默认目录为 %LOCALAPPDATA%\Programs\dsh-pet-standalone-webm-chat（当前用户目录，不需要管理员权限）；
- 想装到其他盘符（如 D:\、E:\），点「浏览」自己选一个目录即可。
附加任务：可勾选「创建桌面快捷方式」（默认不勾选）。
完成：勾选「运行 dsh-pet-standalone-webm-chat」会立即启动桌宠。
首次启动：桌宠出现在屏幕右下角；系统托盘出现常驻图标（右键托盘可打开菜单）。

常见问题

找不到桌宠了？ 看系统托盘（可能收在「显示隐藏的图标」里），双击托盘图标可显示/隐藏桌宠。
想开机自启？ 右键托盘 → 勾选「开机自启」即可（写入当前用户注册表 Run 键，无需管理员）；也可以在「桌宠设置」中开启。
- 自启不生效怎么办：① 安全软件/系统优化工具（360、电脑管家、Defender 等）可能拦截或清理未签名程序的自启项——请到其"开机加速/启动项管理"中恢复；② 程序每次启动会自检：若发现"之前开启过但已被清理"，桌宠会气泡提醒；③ macOS 新版系统需在「系统设置 → 通用 → 登录项」中允许桌宠（勾选时也有气泡提示）。
配置存在哪里？ 设置与聊天会话保存在各版本独立的数据目录（重装/升级不会丢失）：
- Chat 版：%APPDATA%\dsh-pet-standalone-webm-chat\
- 无 Chat 版：%APPDATA%\dsh-pet-standalone-webm\
- 源码运行：%APPDATA%\dsh-pet-standalone\

方式二：绿色版（zip）免安装

下载 dsh-pet-standalone-webm-chat-portable.zip。
解压到任意可写目录（例如 E:\dsh-pet\），保持文件夹内结构完整。
双击文件夹里的 dsh-pet-standalone-webm-chat.exe 即可运行。
删除整个文件夹即完成卸载，不残留任何运行缓存。

绿色版与安装版是同一套 onedir 产物，运行行为完全一致；区别只是安装版多了快捷方式与卸载器。

卸载

安装版：设置 → 应用 → 已安装的应用（或「控制面板 → 程序和功能」）→ 找到 dsh-pet-standalone (WebM Chat) → 卸载。
卸载程序会删除安装目录与快捷方式；各版本的数据目录（见上方「配置存在哪里」）中的配置与会话默认保留，如需彻底清除可手动删除对应目录。

升级

安装版：直接运行新版 setup.exe 覆盖安装即可，配置与聊天会话不受影响。
绿色版：用新版 zip 解压覆盖旧文件夹即可。

快速开始（安装之后）

快速开始（安装之后）

桌宠默认出现在屏幕右下角，播放待机动画。
右键桌宠打开菜单；左键点击触发互动动画，按住拖动可移动桌宠。
首次使用建议打开「设置」：右键桌宠 → 桌宠设置（或托盘菜单 → 桌宠设置）。
Chat 版额外提供「AI 对话」和「AI 设置」入口；无 Chat 版不会显示。

方式三：macOS（Apple Silicon）

获取：GitHub Actions 页面手动运行 Build macOS App（或打 v* tag 自动发布），从 Release / Artifacts 下载 dsh-pet-standalone-webm-chat-macos-arm64.zip（或无 Chat 版）。
解压：得到 dsh-pet-standalone-webm-chat.app，可拖入「应用程序」文件夹。
首次打开：应用未签名（ad-hoc codesign），Gatekeeper 会拦截——右键 .app → 打开，或终端执行：
```
xattr -dr com.apple.quarantine dsh-pet-standalone-webm-chat.app
```
数据目录：~/Library/Application Support/dsh-pet-standalone-<变体>/（各变体相互独立，与 Windows 行为一致）。
开机自启：托盘/右键菜单勾选「开机自启」（按变体生成独立 LaunchAgent）。
启动 DeepSeek Harness：右键菜单的 DeepSeek Harness 子菜单与托盘菜单的两个启动项都提供「启动 dsh web 界面 / 启动桌面端界面」（桌面端当前仅 Windows 支持，macOS 上点它只会如实提示不支持，不会静默改开网页）。需安装 Node.js（brew install node）；启动器会自动探测 Homebrew/nvm 等路径并回退 npx @deepseek-ai/dsh。
关闭 Dock 图标：在「桌宠设置 → 常规 → 显示 Dock 图标」取消勾选后，Dock 隐藏会彻底生效——隐藏桌宠也不会把 Dock 图标临时唤回；恢复入口是菜单栏托盘图标（显示 / 隐藏、鼠标穿透、桌宠设置）。开启鼠标穿透或关闭 Dock 图标时，桌宠会气泡提示恢复位置。

Intel Mac：当前 CI 只构建 arm64；Intel 用户请从源码运行（见下），或在 Intel 机器上自行构建。

方式四：Linux（x86_64）

获取：GitHub Actions 页面手动运行 Build Linux App（或打 v* tag 自动发布），从 Release / Artifacts 下载 dsh-pet-standalone-webm-chat-linux-x86_64.zip（或无 Chat 版）。

解压：得到 dsh-pet-standalone-webm-chat/ 目录，运行其中的同名二进制：

unzip dsh-pet-standalone-webm-chat-linux-x86_64.zip
cd dsh-pet-standalone-webm-chat
chmod +x dsh-pet-standalone-webm-chat   # 一般无需，zip 已保留可执行权限
./dsh-pet-standalone-webm-chat

首次运行缺库（PySide6 需要少量系统库，常见发行版需安装）：
```
# Debian / Ubuntu / Mint 等（其他发行版请找对应包名）
sudo apt install libxcb-cursor0 libxkbcommon-x11-0 libegl1 libgl1 \
                 libfontconfig1 libdbus-1-3 fonts-noto-cjk
```
- fonts-noto-cjk 用于中文显示（缺失时气泡/聊天中文会显示为方块）。
- 默认按 X11 运行；Wayland 会话下若透明/置顶异常，可试 QT_QPA_PLATFORM=xcb ./dsh-pet-standalone-webm-chat。
数据目录：~/.config/dsh-pet-standalone-<变体>/（各变体相互独立，与 Windows/macOS 行为一致）。
开机自启：托盘/右键菜单勾选「开机自启」（写入 ~/.config/autostart/ 的 .desktop 文件）。
点击音效：自动使用系统 paplay（PulseAudio）或 aplay（ALSA）；两者都没有时静默跳过。
启动 DeepSeek Harness：右键菜单的 DeepSeek Harness 子菜单与托盘菜单的两个启动项都提供「启动 dsh web 界面 / 启动桌面端界面」（桌面端当前仅 Windows 支持，Linux 上点它只会如实提示不支持）。需安装 Node.js；启动器会自动探测 PATH 并回退 npx @deepseek-ai/dsh。

建议在 X11 桌面（GNOME/KDE/Xfce 等）上使用；托盘图标依赖桌面环境的系统托盘支持（GNOME 需安装 AppIndicator 扩展）。

从源码运行（开发者）

建议使用 Python 3.10 或更高版本（CI 使用 Python 3.11，Windows 实机开发验证覆盖 Python 3.13），并在项目根目录执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m pet

Windows 也可以直接双击 run.bat。它实际执行的是：

pythonw -m pet

源码入口默认包含 Chat 能力；如果只想验证桌宠核心功能，可使用无 Chat 的打包入口或在本地配置中关闭聊天。

功能概览

功能概览

桌宠窗口

PySide6 透明、无边框、置顶窗口（无边框圆角窗口，窗外无方形背景）。
支持点击互动、拖动、拖动惯性、方向转向和系统托盘。
锁定位置：设置开启后桌宠不可拖动（点击互动仍有效）。
SHIFT+左键拖动：设置开启后必须按住 SHIFT 才能拖动桌宠。
不透明度：桌宠窗口透明度 10%–100% 可调，保存立即生效。
支持角色切换；角色目录按素材自动发现，不要求把角色写死在代码中。
右键菜单默认使用新版现代菜单（紧凑分组 + 线性图标 + 半透明表面），可跟随系统/浅色/深色主题，UI 字体/字号/密度/圆角/浅深主题色均可调；「切换菜单模板」可随时切回旧版经典菜单。
新版菜单首行彩蛋入口（欧鲸鲸，可配置头像/标题/图片目录）与「快捷启动」均可配置；「生小肥鱼」会启动一只独立的新桌宠（自动避让位置、配置隔离）。
右键菜单提供 DeepSeek Harness 子菜单（启动 dsh web 界面 / 启动桌面端界面 / 重启服务 / 停止服务），托盘菜单是两个平铺启动项（启动 dsh web 界面 / 启动桌面端界面）：「启动 dsh web 界面」一键后台拉起 dsh web（默认端口 38080，可用环境变量 DSH_PORT 覆盖；注：3080 在部分 Windows 上会落入 winnat/Hyper-V 保留段导致无法监听）并自动打开浏览器；启动命令自动适配不同安装方式（PATH 上的 dsh → node + npm 全局包 → 官方 npx @deepseek-ai/dsh），macOS 同样可用（.app 环境会额外探测 Homebrew/nvm 等常见目录，需装有 Node.js）。若本机已有 dsh web 在运行（38080 或官方默认 3080），直接复用并打开现有实例，不再重复拉起。首次运行时 npx 拉取组件 + dsh 自举（可能出现 npm/pnpm 安装窗口）在网络较慢时需要几分钟属正常现象，桌宠会冒泡提示启动中；想跳过首次下载可提前手动 npm install -g @deepseek-ai/dsh。「启动桌面端界面」打开已安装的 DeepSeek Harness 桌面端（当前仅 Windows 支持）：默认安装位与注册表卸载项（DisplayName / InstallLocation / DisplayIcon 都算）都会探测，已安装就直接打开，未安装会如实报错、不会悄悄改开网页；桌面端是你自己的应用，桌宠退出不会关掉它。设置中另有「随桌宠启动 dsh 服务」开关与「自启目标」（只影响自启这一路，菜单点哪项就起哪项）：开启后桌宠启动即按目标拉起——目标是 dsh web 时后台静默起服务（不开浏览器、不弹窗口），目标是桌面端界面时直接打开应用；自启还要求同时开着 DSH 联动（联动关着时 dsh web 没有消费者，不会拉起）；关闭开关只是不再自动拉起，已经在跑的 dsh web 要等桌宠退出或关闭 DSH 联动时才收口（唯一例外：在桌宠拉起探测期间关掉开关，那一次刚拉起的实例会被立刻收掉）；非 Windows 上「自启目标」里的桌面端项置灰并写明原因（暂不支持 ≠ 永远不支持）。「重启/停止服务」带确认框（列出将终止的 PID 与端口）：--no-open 静默常驻之后没有可关闭的控制台窗口，这两个入口就是关掉它的正规方式——不必再去任务管理器杀进程。停止按「谁在监听该端口」反查进程，并核验命令行确实是 dsh web；端口被别的程序占用时只报告、不终止（避免误杀），macOS 因无 /proc 暂不支持反查（会如实报告「读不到持有它的进程」）。退出桌宠不会顺带停止你自己起的 dsh 服务（桌宠自拉起的那份由退出收口负责收掉）。
托盘菜单（鼠标穿透 / 开机自启）勾选状态与设置实时同步。

新版设置对话框

侧边栏 + 卡片式布局：常规 / 桌宠行为 / 外观 / AI 对话 / 快捷启动 / 主动识屏（Windows + Chat 版）。
关闭即自动保存并立即生效：直接点 X、ESC、保存按钮都会落盘并刷新桌宠（此前需要点「保存」）。
深色系统下全界面可读：自绘开关、下拉、选项弹窗、颜色块均适配明暗主题。
彩蛋入口、菜单外观（颜色/圆角/半透明/字体）、点击音效、余额自动刷新等集中管理。
桌宠显示分组可调「气泡文字大小」（50–300%，默认 100）：气泡列宽/换行预算/label 尺寸与字号用同一个系数等比放大；默认 100% 时与旧版逐像素一致。审批/提问气泡为固定布局，不随本项变化。

动画播放

WebM 版：直接播放透明 WebM，默认素材为 640×360、24fps。
播放速率可在设置中调整，当前范围为 1.0x 到 2.0x。
动画按 idle、turn、move、click、drag、random 等目录组织。
支持相邻非待机动画之间的等待间隔；等待期间只播放待机和转向动画。
支持随机自言自语气泡；没有自定义文本时使用内置文本。
素材懒加载 + 优先级预热：冷启动更快，隐藏时零解码。

AI 对话（Chat 版）

新版双栏工作台：左侧会话导航（搜索/重命名/置顶/批量管理）+ 右侧消息画布；经典手机式窗口保留可切换。
支持 OpenAI Chat Completions 兼容接口；自定义 API 地址、模型、超时、温度和最大输出 token。
支持 SSE 流式输出、多轮上下文裁剪、会话 JSON 持久化、停止生成、失败重试。
会话按角色隔离；切换角色时不会把旧角色消息带入新角色。
聊天窗靠近桌宠显示，并支持选择是否跟随桌宠移动；背景支持内置主题壁纸 / 自定义图片 / 裁剪取景。
API Key 优先使用系统钥匙串；钥匙串不可用时可按设置选择配置文件回退。
纯文本安全显示，不包含完整 Markdown 渲染器。

主动识屏陪伴（Windows + Chat 版，默认关闭）

白名单应用切换时以桌宠口吻冒泡关怀（截图 + 前台窗口上下文 → 视觉模型）。
停留时长门限、闲置判定、冷却间隔、每日上限、免费模型优先、dry-run 验证模式。
截图仅在内存中压缩处理并直接发送给视觉模型，不写入本地文件、不保留副本。

Agent 联动（默认关闭）

内置 DSH 桥接插件（integrations/dsh-pet-bridge）与 Claude hooks 安装器：感知 AI Agent 状态并切换动作，支持开始干活、过程汇报、任务完成三种气泡反馈，右键 Agent 联动子菜单可独立开关。
DSH 富事件状态：thinking（思考）/ working（干活，带工具名）/ attention（需确认）/ error / idle 多态呈现，多会话按 attention > error > working > thinking > idle 聚合，子代理不抢状态；审批与提问为纯提示常驻气泡（引导回 DSH 界面处理），同一 Agent 的并发审批/提问按 interaction_id 互不覆盖。
开机即按配置装配（PR #100 / #102）：重启后已开启的 Agent 联动与主动识屏直接生效，不再需要手动展开一次菜单或开关一次设置对话框。
自定义联动 Agent：在 config.json 的 agent_link.custom_agents 里声明任意 Agent（key / 显示名 / 事件文件路径），桌宠即对其 JSONL 事件文件做只读监听，联动行为与内置 Agent 一致——不改代码即可接入任何能写本地文件的 Agent，协议详见 docs/AGENT_LINK_PROTOCOL.md。
一键启动 DSH：本机已在跑 dsh web（含官方 3080）时直接复用，不再拉起第二个实例；Windows 上 node/pnpm 解析覆盖 nvm-windows/nvm/fnm/Volta/scoop 等布局（PR #97 修掉「已装 pnpm 仍装不上插件」，issue #95），也可用 pnpm_bin 配置键手动指定 pnpm 入口。

看看屏幕（Chat 版）

右键菜单 →「看看屏幕」：截取当前屏幕（含多显示器）→ 附带前台窗口「程序名 | 标题」上下文 → 发给视觉模型，用人设口吻回应一句（关心/吐槽/好奇），结果以气泡显示。
回复会自动同步到 AI 对话当前会话（一条 [看看屏幕] 前台窗口：… 记录 + 一条回复），可继续追问；聊天窗未打开时仅气泡显示、不写入。
截图自动压缩（最长边 768px、JPEG 70）后仅在内存中处理并直接发送到你配置的模型服务商，不写入本地截图文件、不保留副本；不发送到本项目自建服务器，请你遵循所配置模型服务商的隐私政策。
视觉模型在 AI 设置中配置：可手填模型名/独立端点/独立密钥，或勾选「同聊天模型」复用聊天配置；DeepSeek 聊天模型会自动映射到预览版视觉模型。
注意：每次「看看屏幕」都会按一次视觉模型请求计费，消耗对应模型的 token（截图按像素折算 + 回复输出）；有 4 秒冷却防连点，免费档高峰可能遇到限流（稍后重试即可）。

DeepSeek 余额（Chat 版）

右键菜单或托盘 →「DeepSeek 余额」：查询 DeepSeek 开放平台账户余额，以气泡显示（如"余额 ¥12.34（充值 ¥10.00 / 赠送 ¥2.34）"）。
数据来自 DeepSeek 官方 /user/balance 接口，使用当前配置的 API Key 鉴权（需使用 DeepSeek 官方端点）；查询结果 30 秒内缓存复用，重复查询秒回。
桌宠设置可开启「余额自动刷新」（分钟级，0=关闭），到点自动查询并气泡显示；也可开启「点击显示余额」（与点击自言自语自动排队）。
实现参考 MeteorNOX/DeepSeek-Balance-Whale-Widget（见文首声明）。

点击音效

点击桌宠触发 Q 弹时播放短促音效（内置合成音，可在桌宠设置中关闭）。
可自定义声音：把 click.wav 放到桌宠数据目录 sounds/ 下即可替换内置音效。

待办提醒

右键菜单 →「待办」面板增删改（带矢量图标），数据按实例落盘（todo_items[-instance].json，原子写）。
到期提醒 + 提前提醒（todo_reminder_lead_minutes，默认提前 5 分钟）、10 分钟宽限；一次性待办到期自动归档；错过宽限的提醒静默盖戳，不会一次轰炸。
提醒形式：桌宠可见时用气泡，否则走桌面通知（由 system_notifications_enabled 总门控，默认开）；总开关与提前量在「设置 → 桌宠行为 → 待办提醒」。

边缘交互与彩蛋玩法

黄金回旋：右键菜单新增「黄金回旋」入口；「设置 → 桌宠行为 → 点击反馈」可开「点击触发黄金回旋」（点击动画播完自动接回旋）与「点击回旋跳过动画」（点击直接回旋、跳过 Q 弹/点击素材）；连点逐圈加速（700ms → ×0.82 → 200ms 下限）。
边缘探头（edge_probe_enabled，默认关）：拖到屏幕左右边缘自动进入 ±45° 探头姿态（常驻露出 0.55、点击拉直 0.82、数秒自动退回）；探头激活时点击不播点击音效，且移动被闸门拦住（不会被平移出屏幕边缘，PR #101）。
撞飞彩蛋：探头激活状态被撞飞时头部跟随速度方向整帧旋转，低速触碰边界/其它桌宠回正，落地停稳 5 秒后重新吸附。
拖文件模拟吃掉：把文件拖到桌宠身上播放吃动画并记录统计（不真实删除文件）。

右键菜单编排（可配置菜单）

「设置 → 菜单」左侧编辑、右侧实时预览：显隐勾选、移动到子菜单/根、新建子菜单、插入/删除分割线、别名（运行时只显别名）、图标覆盖（内置矢量 / none / 本地图片 ≤5MB，contain/cover）、恢复默认名称/图标/布局、删除子菜单（二次确认，子项提升回根）。
配置缺失回默认模板；损坏/不支持的 schema 只保留「桌宠设置 / 退出」安全菜单；旧自定义树自动补入新默认项；动作缺条件置灰 + tooltip。
同页 Tab 还有「快捷启动」（双行应用列表编辑，无配置时子菜单显示禁用占位「尚未配置快捷项」）与「外观」（主题即时生效、开关从属项「开显关隐」）。

省电模式

在「设置 → 常规 → 动画与移动」开启「省电模式」后：桌宠一段时间无交互时动画按半帧率呈现（24fps 素材 → 12fps 效果），任何交互立即恢复全帧率；同时停止后台动画预热（不再预载非核心动画的首帧，进一步省 CPU 与内存）。
默认关闭；多开时每只各自独立设置。

性能与内存治理（PR #76）

实测驱动：修复前多开 1-2 小时后每只涨到 220MB+/只且不回落；修复后多进程模式长时运行稳定（3 只合计约 270MB），单进程多窗模式 3 窗共 1 进程、3.5h 浸泡在 181–197MB 区间震荡、无单调上涨。
解码链收敛：同角色多窗共享一条进程内解码链（DecodeFanoutHub），3 窗只启动 1 个 ffmpeg 解码进程；ffmpeg 固定 -threads 1，并按 ffmpeg_recycle_minutes（默认 10 分钟）在圈边界定期回收，避免子进程内存无限爬升。
首帧缓存预算：默认 first_frame_cache_max_mb=8（4–64 可配），只保留点击/转向/拖拽等瞬时交互核的 pinned 缓存，idle/move 交给预测式预热与 LRU，避免“每播一段新动画就 +1.76MB 不释放”的慢涨。
启动与内存降载：未启用点击/碰撞音效时不拉起 QtMultimedia（省约 38MB）；PIL 只在“看看屏幕/主动识屏”截图路径懒加载。
频闪根因修复：全屏自动隐藏排除截图覆盖层/工具窗口；Windows 光标穿透改用原生 WS_EX_TRANSPARENT，不再 setWindowFlag 重建原生窗口。

单进程多开与共享解码

正式特性（默认关闭）：在「设置 → 常规 → 多开」开启「单进程多开（省内存）」并重启后，「生小肥鱼」在同一进程内创建新桌宠：多只宠物只占一个进程，且空闲时多只播的是同一份待机素材，由进程内帧扇出（DecodeFanoutHub）统一解码——待机时 ffmpeg 解码进程从 N 个减到 1 个，解码 CPU 与内存显著降低；机制与平台无关。
每只桌宠的设置存档（含位置、外观）在多开模式间通用，切换开关不会丢配置。
失败无感回退：无发布者、断流等任何情况下，消费端都会自动回退本地解码，播放行为与关闭时一致。

单进程多开下的设置作用域：

每只独立（右键某只 → 桌宠设置，改哪只影响哪只）：形象/缩放/透明度/置顶、拖拽物理/弹射/音效、自言自语、省电降帧、AI 对话内容与各自会话、位置。各只设置存于各自的 config-slot-N.json。
进程级互通（全窗共用一份，随主配置生效）：托盘与灵动岛、DeepSeek 余额查询、更新检查、待办提醒、共享解码链、Agent 联动与主动识屏（dsh 等 agent 只有一条连接，全部窗共享状态）、单进程多开开关本身。
注意：进程级开关以**主桌宠（第一只）**的配置为准——请在第一只的设置里修改「单进程多开」，在其它只的设置里改不会生效；首帧缓存预算同理（建议只改主配置 config.json）。
切换「单进程多开」后需重启生效。

内存调节（高级，改 config.json）

以下键暂无设置 UI，编辑数据目录下的 config.json 后重启生效：

键	默认	说明
`first_frame_cache_max_mb`	8	首帧缓存总预算（MB，4-64）。多开时按进程共享一份预算
`predict_prewarm_lead_ms`	350	预测式预热：动画播到结尾前提前多少毫秒预解码预测的下一段首帧；0=关
`ffmpeg_recycle_minutes`	10	ffmpeg 解码子进程在圈边界的定期回收间隔（分钟，2-120）；0=不回收

使用教程

使用教程

基本操作

操作	效果
左键点击桌宠	触发点击互动动画
按住并拖动	移动桌宠；松开后根据拖动方向和速度处理转向、移动或惯性。多显示器下可以拖到 / 丢到任意一块屏（4.2.1 曾因 `#137` 的落位收口被限制在本屏，2026-09-23 修复，见下方发布后补丁）
按住 SHIFT + 左键拖动	开启了「SHIFT+左键拖动」时，这是唯一的拖动方式；未开启时 SHIFT 无特殊含义
右键桌宠	打开带图标的上下文菜单；可切换新旧菜单模板，或选择「生小肥鱼」启动独立的新桌宠
双击托盘图标	显示 / 隐藏桌宠
右键托盘图标	打开设置、AI 对话、开机自启、DeepSeek Harness（启动/重启/停止）、退出等菜单
拖拽桌宠时	若开启了聊天窗跟随，聊天窗口会一起移动；默认不跟随

锁定位置 / SHIFT 拖动 / 不透明度（v4.0.0）

在「桌宠设置 → 桌宠行为 → 拖拽」与「外观 → 桌宠显示」中：

锁定位置：开启后桌宠固定不动，怎么拖都拖不走（点击互动仍然有效）；想再调整位置时关闭即可。
SHIFT+左键拖动：开启后普通拖动被禁用，必须按住 SHIFT 再左键拖才能移动桌宠——适合防止误拖，或桌面有别的操作需要普通左键时使用。
不透明度：10%–100%，数值越小桌宠越透明（半透明效果），保存立即生效。

三者与「鼠标穿透」的区别：锁定/SHIFT 只是禁止拖动，点击互动（点头、音效、彩蛋）照常；鼠标穿透是桌宠完全不接收鼠标事件（点击会落到下层窗口），需要从托盘菜单关闭（或到「桌宠设置 → 互动」里改）。开启「鼠标穿透」时桌宠会气泡提示恢复位置。

开机自启

右键系统托盘图标。
勾选菜单中的「开机自启」。
取消勾选即关闭自启；状态直接读写当前用户的注册表 Run 键，无需管理员权限。

调整播放速率

右键桌宠（或托盘菜单）→「桌宠设置」。
调整「播放速率」。
点击保存或应用。
播放当前动画或切换到下一段动画，观察节奏是否变化。

速率对当前片段和后续片段均生效；设置范围 1.0x 到 2.0x。

设置动作等待间隔

「动作等待间隔」用于降低连续动作过于密集时的节奏：

在设置中找到「动作等待间隔」。
输入间隔秒数，默认是 0。
设为 0：保持当前连续播放行为。
设为大于 0：相邻的非待机、非转向动画之间等待指定时间；等待期间仍允许待机和转向动画播放。

这个设置只影响动画调度，不会阻塞窗口拖动、点击、设置窗口或聊天窗口。

开启自言自语气泡

在「桌宠设置」中勾选「开启自言自语气泡」。
设置「随机间隔最短」和「随机间隔最长」。
在「自言自语内容」中每行填写一条文本。
留空会恢复内置内容，例如：

好女孩……
好模型……
欧鲸鲸……

气泡默认显示在角色当前可见形象边界的正上方并水平居中；屏幕上方空间不足时，会自动选择不遮挡角色的候选位置。自言自语窗口不会改变桌宠的透明 mask，也不会阻止桌宠移动。

直播捕获兼容模式（Windows）

用哔哩哔哩直播姬 / OBS 做窗口捕获时，如果窗口列表里找不到桌宠，是因为桌宠默认是"工具窗口"形态（不占任务栏，捕获软件会过滤掉这类窗口）——这就是同类软件 Bongo Cat 能被捕获而桌宠不能的原因。

解决办法：在「桌宠设置」中勾选**「直播捕获兼容模式」**（Windows），保存后立即生效：

桌宠变为普通顶层窗口并显示标题「dsh-pet 桌宠」，直播姬/OBS 的窗口捕获列表即可看到并选中它
自言自语与快速对话气泡也会临时变成桌宠主窗的子内容：捕获「dsh-pet 桌宠」这一个源即可同时看到桌宠和气泡，不需要为气泡另加窗口源
气泡在捕获模式下会在桌宠窗口范围内自动选位（上方空间不足时放侧面/下方），避免被主窗边界裁掉；关闭捕获模式后恢复原本的独立浮出定位
代价：任务栏会出现桌宠图标（不开直播时取消勾选即可恢复原样）
开启后窗口置顶、鼠标穿透等其余行为不受影响

切换角色

打开右键菜单中的角色选择入口。
选择角色后，桌宠会加载对应角色目录中的动画（菜单每次打开都会重新扫描，无需重启）。
Chat 版会同步更新聊天窗口的角色名称、头像回退、主题色、有效 system prompt 和会话列表。
角色之间的消息历史相互隔离。

热加载新角色：文件怎么放

除内置角色外，桌宠会自动扫描外部角色目录发现新角色。目录名即角色 ID，按下面的树状结构放置即可（目录里含 webm 或 gif 即被识别）：

characters/                          ← 外部角色根目录（见下方两个扫描位置）
└── <新角色ID>/                      ← 目录名 = 菜单里显示的角色 ID，如 mycat
    ├── manifest.json                ← 可选：角色名 / prompt / 主题色 / 动作映射
    └── videos/
        ├── idle/                    ← 待机（可多个）
        │   └── 待机呼吸.webm
        ├── turn/                    ← 转向
        │   └── 东张西望.webm
        ├── move/                    ← 移动
        │   └── 原地踏步.webm
        ├── click/                   ← 点击回应
        │   └── 点击开心.webm
        ├── drag/                    ← 拖拽（可选）
        │   └── 悬空反馈.webm
        └── random/                  ← 随机动作池
            └── 吃零食.webm

两个扫描位置（exe 同目录优先，其次用户数据目录；用户数据目录跨安装/升级保留）：

平台	exe 同目录	用户数据目录
Windows	`<安装目录>\characters\`	`%APPDATA%\dsh-pet-standalone\characters\`
macOS	`.app/Contents/MacOS/characters/`	`~/Library/Application Support/dsh-pet-standalone/characters/`
Linux	源码运行目录 `characters/`	`~/.config/dsh-pet-standalone/characters/`

把新角色的 videos 放进去后，右键桌宠重新打开菜单即可看到新角色，选中即热加载——不需要重新打包或重启程序。透明 WebM 素材的制作方法见素材生成教学。

AI 对话使用教程（Chat 版）

AI 对话使用教程（Chat 版）

零基础快速配置（小白照抄版）

不想研究 API 的话，打开「AI 设置」后只需要填一样东西：API Key。其他按下面的值照抄即可：

设置项	填这个
API 地址	`https://api.deepseek.com`
模型	`deepseek-v4-flash`
API Key	在 DeepSeek 开放平台创建（步骤见下）

软件首次打开时，API 地址和模型默认就已经是上面这两个值（DeepSeek），不用改；只要把 API Key 粘进去就能用。

如何创建 API Key（5 分钟搞定）：

打开 DeepSeek 开放平台：https://platform.deepseek.com
用手机号注册 / 登录账号
左侧菜单找到 「API Keys」→「创建 API Key」
复制生成的 sk- 开头的密钥
回到桌宠 → 右键 →「AI 设置」→ 粘贴到 API Key 一栏 → 点 「保存」
点 「测试连接」，看到「连接成功」就完成了，去聊天吧！

小提示：

API Key 只在创建时完整显示一次，创建完记得立刻复制保存（丢了就重新建一个，旧的作废）。
新注册账号一般会赠送一点测试额度；用完后到开放平台的「充值」页面充值，充多少用多少。
如果显示「认证失败（401/403）」，基本就是 Key 复制漏了字符或多了空格，重新粘贴一次。
显示「余额不足（402）」就是没额度了，去平台充值即可（网络和配置都是好的）。

第一步：配置 API

右键桌宠（或托盘菜单）→「AI 设置」。
新建或选择一个 Provider。
填写兼容接口的 API 地址、模型、超时和生成参数。
填写 API Key，并按提示选择钥匙串或配置文件回退。
使用「连接测试」确认配置可用。

首期协议是 OpenAI Chat Completions 兼容协议。Gemini 等其他服务只有在提供兼容网关或兼容端点时才可使用。

常见错误码说明

AI 对话接口返回的常见 HTTP 状态码含义与处理方式（「测试连接」与聊天发送遇到 HTTP 错误时，软件内会显示状态码与原始错误信息）：

状态码	含义	处理方式
401 / 403	API Key 无效或无权限	检查 AI 设置中的 API Key 是否正确、是否过期，或服务商账号权限是否足够
402	账户余额不足（Insufficient Balance）	到服务商开放平台充值后重试；此错误说明网络与证书均正常，请求已到达服务器
429	请求过于频繁（限流）	稍等片刻后重试；也可降低对话频率或减少会话历史长度
5xx	服务端故障	服务商临时问题，稍后重试
网络连接失败 / 超时	无法连接 API 地址	检查网络与代理；确认地址可达、超时值足够
SSL CERTIFICATE_VERIFY_FAILED	证书校验失败	开着代理/梯子（证书被拦截）或本地网关 / 自签名证书时，可在 AI 设置中勾选「跳过 SSL 证书验证」

502/503/504 等 5xx 错误通常不是软件问题；若「测试连接」成功但发送失败，请把服务商返回的原始错误信息发到 Issue 便于排查。

第二步：开始对话

右键桌宠（或托盘菜单）→「AI 对话」。
聊天窗第一次打开时会定位在桌宠旁边，并根据桌宠当前可见形象边界和屏幕边界自动避让。
输入区支持多行输入：Enter 发送，Shift+Enter 换行；生成中按钮变为「停止」。
可在 AI 设置中开启或关闭「跟随桌宠移动」。

聊天窗默认为新版现代双栏工作台：左侧是会话导航（新建会话、会话列表、批量管理、跟随桌宠），右侧是消息时间线与输入区，包含：

无边框圆角窗口 + 自绘标题栏：角色头像、会话标题与状态（就绪/思考中/生成中）、模型名、收起侧栏、最小化、关闭。
会话侧栏：每行会话可切换，⋮ 菜单提供重命名 / 置顶 / 删除；底部有「跟随桌宠」「删除当前会话」「清空当前会话」。
消息时间线：用户和桌宠气泡、流式回复、错误与停止状态、复制/重试按钮。
输入区：附件（图片/文本拖拽或选择）、Enter 发送 / Shift+Enter 换行、生成中变为「停止」。
可在「桌宠设置 → AI 对话外观」中切换回经典手机式窗口。

配置 system prompt 和角色 prompt

system prompt 的优先级为：

角色用户自定义 prompt > 角色 manifest 中的 prompt > 全局默认 prompt

角色可在以下文件中声明聊天配置：

assets/characters/<character_id>/manifest.json

可选字段示例：

{
  "chat": {
    "system_prompt": "你是一个温柔的桌面宠物……",
    "theme_color": "#79C7FF",
    "chat_actions": {
      "thinking": "thinking.webm",
      "success": "success.webm",
      "error": "error.webm"
    }
  }
}

非法或缺失的 theme_color 会回退为默认蓝色；缺少头像资源时，聊天窗使用角色 ID 首字母生成圆形头像。

会话管理

会话按角色目录保存。
会话标题优先取用户自定义标题（每行会话的 ⋮ 菜单 → 重命名，可备注会话内容），未自定义时取第一条用户消息，无法生成时使用时间标题。
新版窗口的会话列表位于左侧栏：点击切换会话，每行 ⋮ 菜单提供重命名 / 置顶 / 删除；左侧栏底部有「跟随桌宠」「删除当前会话」「清空当前会话」；顶部的「开启新对话」新建会话，右侧栏头部按钮可收起侧栏。
支持会话搜索、批量管理（多选后置顶 / 删除）；删除带确认框（防误删）。
可新建、删除当前会话（带确认）或清空消息。
生成过程中会限制切换和删除，避免旧请求污染新会话。
停止生成时，未完成的半截 assistant 内容不会作为完整消息保存。
旧版手机式聊天窗同样支持重命名（铅笔按钮）与新建/删除/清空。

配置与会话目录（目录名按变体分：Chat 版 dsh-pet-standalone-webm-chat、无 Chat 版 dsh-pet-standalone-webm、源码运行为 dsh-pet-standalone）：

系统	数据目录
Windows	`%APPDATA%/dsh-pet-standalone-<变体>/`
macOS	`~/Library/Application Support/dsh-pet-standalone-<变体>/`
Linux	`~/.config/dsh-pet-standalone-<变体>/`

目录中主要包含：

config.json
sessions/<character_id>/<session_id>.json
pet.log

配置格式当前为 v3，并兼容历史平铺字段，例如 chat_api_url、chat_api_key、chat_model、chat_system_prompt 和 chat_enabled。日志不会输出 API Key。

动画素材与自定义角色

动画素材与自定义角色

当前目录结构

assets/
└── characters/
    └── shenshen/
        ├── manifest.json
        └── videos/
            ├── idle/
            ├── turn/
            ├── move/
            ├── click/
            ├── drag/
            └── random/

assets/characters 是 WebM 动画源目录，包含 106 个 WebM 动画。
GIF 目录（assets/characters_gif）仅在构建 GIF 变体时生成。
没有稳定静态头像时，不强制从 WebM/GIF 截取首帧，以避免启动变慢和打包兼容性问题。

素材生成教学（从零制作动画素材）

本项目的动画素材沿用参考项目 PC2005-cloud/dsh-pet 的三件套流程：① 提示词（配方）→ ② 素材生成链（引擎）→ ③ 插件（成品）。任何人 clone 参考仓库都可以从零生成自己的桌宠素材，本教学按该流程说明。

① 提示词 → 源视频（绿幕规范）

用 AI 视频生成工具（如可灵、Runway、豆包等；参考项目素材即由豆包生成），按提示词配方为每个动作生成一段 10 秒绿幕视频。配方硬性规范（参考项目的 prompts/桌面宠物 10 秒动作提示词.md，本项目自定义角色配方在本地 assets/prompt/<角色ID>/图像生成提示词.md）：

画面：16:9；背景纯绿幕色 #00FF00，无阴影、杂物、渐变或边框。
人物定位固定：头顶约画幅垂直 20%（按角色头饰可调整为 15%），脚底约 85%；左右边缘约 25% / 75%；不同视频间人物大小、位置、比例完全一致。
安全缓冲：头顶距顶边 ≥15%、脚底距底边 ≥10%、两侧距边缘 ≥10%；任何身体部位/道具/特效不得出画或贴边。
禁止平移：双脚落点恒为画面正中，仅允许原地轴心旋转、原地跳跃；道具与角色组合视觉重心始终居中。
首尾帧闭环：第一帧 = 干净的标准正面站立；第 10 秒结束必须恢复到与第一帧完全一致。
道具"无→有→无"：道具/特效由角色从虚到实渐进生成、结束前由实到虚消散，不得凭空出现或残留。
按秒分解：每个动作的配方按 0–3 / 3–7 / 7–10 秒（或 0–2 / 2–5 / 5–7 / 7–10）分段描述动作节奏，确保生成结果可复现。

一个动作一段视频，按动作名各存一个 mp4（如 video/吃白饭.mp4）。

② 源视频 → 透明动画（素材生成链）

参考项目 scripts/ 提供完整 Python 素材链（依赖：Python 3 + ffmpeg + numpy + scipy），四步：

cd scripts
# step01：水印遮罩填充（源视频若带水印/角标则先填补为纯绿幕）
python watermark_step01.py
# step02：绿幕抠像 → 透明视频（两条路线二选一）
#   路线 A（默认自动化）：HSV 色相抠像，人人可复现
python chroma_step02.py
#   路线 B（精细手工，推荐）：PR 手工抠像导出带 alpha 的透明 .mov，
#   放入 pr/（文件名与动作一致，如 吃白饭.mov）后导入
python pr_import_step02.py
# step03：归一化 2160×1215 统一站立居中（对齐脚底锚点）
python normalize_step03.py
# step04：转码 640×360 透明播放变体（VP9 alpha 透明 WebM）
python encode_thumbs.py

参考项目全部 106 个动作均采用路线 B（PR 手工抠像）：对含第三方物品/透明边缘复杂的动作，自动 HSV 抠像易残边或误抠；chroma_step02.py 保留为自动化兜底。中间产物 step01~04 由脚本生成、不入仓库；video/ 源视频与 scripts/ 是成果、入库维护。

③ 透明动画 → 接入本项目

把 step04 产出的 640×360 透明 WebM 按分类放入角色目录：

assets/characters/<角色ID>/videos/
├── idle/     待机（可多个）
├── turn/     转向
├── move/     移动
├── click/    点击回应
├── drag/     拖拽（可选）
└── random/   随机动作池

保持几何约定与播放器一致：画布 640×360、24fps、VP9 alpha 透明；角色脚底对齐画布 y=330（catalog.py 中 FEET_Y=330、落地偏移 PAD=30），这样桌宠窗口的脚底落地对齐才准确。
命名保持稳定、避免重复；可参考 assets/characters/shenshen/videos/ 现有 106 段动画的组织方式。
如需 GIF 变体，运行 python scripts/convert_to_gif.py --force --clean 同步生成。

不想重新打包？把做好的透明 WebM 按「切换角色」的外部角色目录结构直接放入 characters/<角色ID>/videos/，右键菜单即可热加载新角色。

快速验证：python -m pytest -q 会检查 WebM/GIF 相对路径一一对应；源码运行 python -m pet 或重新打包后检查对应分类是否正常播放。

重新生成 GIF（仅构建 GIF 变体时需要）

更新 WebM 素材后，在项目根目录执行：

python scripts/convert_to_gif.py --force --clean

其中：

--force：覆盖已有 GIF。
--clean：删除目标目录中已经不存在对应 WebM 的旧 GIF，防止两套素材残留不一致。

转换前请确认 imageio-ffmpeg 已安装。生成后可以用下面的命令检查数量：

(Get-ChildItem assets/characters -Recurse -Filter *.webm).Count
(Get-ChildItem assets/characters_gif -Recurse -Filter *.gif).Count

两者应当相同；还应检查相对路径是否一一对应。

新增角色

在 assets/characters/<character_id>/videos/ 下按动画类别建立目录。
放入透明 WebM 文件（制作方法见「素材生成教学」），命名保持稳定、避免重复。
如有角色身份信息，在 <character_id>/manifest.json 中填写名称、prompt、主题色和动作映射。
如需 GIF 变体，运行 GIF 转换脚本同步生成 GIF。
使用源码运行或重新打包验证角色切换、播放、气泡定位和 Chat 身份区。

开发结构

开发结构

pet/
├── app.py                    # AppShell + PetInstance：进程级/每窗容器与装配（托盘、多窗共享）
├── config.py                 # 配置读取、迁移和持久化（reload 白名单 + schema 测试）
├── config_domains.py         # 配置域 facade（chat/agent_link/proactive/collision/menu）
├── window.py                 # 桌宠主窗口（组合根；碰撞/平台层/动画链已拆出，受行数预算红线）
├── window_optional_services.py # 窗口可选服务懒装配 mixin（todo/file_eater 等）
├── collision.py              # 碰撞物理核心（纯 Python，无 Qt）
├── sprite_collision.py       # 进程内 sprite 碰撞世界（多宠统一世界 + 岛静态成员）
├── overlay_shell.py          # 单合成窗产品壳（overlay 拓扑入口：sprite 世界/托盘/指令通道）
├── overlay_spawn_state.py    # 活跃宠清单 + 无锁 slot 身份分配 + 每身份几何持久化
├── pet_sprite.py             # 合成窗内的宠物 sprite（帧签名缓存/拖拽轨迹/抛掷）
├── decode_fanout.py          # 同角色共享解码链（进程内帧扇出 DecodeFanoutHub，单向依赖约束）
├── frame_cache.py            # 通用字节预算 LRU（webm 元数据缓存等小缓存用）
├── perfstats.py              # 性能打点（PET_PERF_STATS=1 启用，atexit 落盘）
├── predictive_prewarm.py     # 预测式预解码预热（切动画前预拉下一段，默认提前 350ms）
├── platform_win.py           # Windows 平台层（鼠标穿透/全屏判定/PerPixel 输入/WS_EX_TRANSPARENT）
├── platform_mac.py           # macOS 平台层（NSWindow level/激活策略）
├── catalog.py                # 角色和动画素材发现
├── library.py                # 动画库访问（懒加载 + 优先级预热）
├── webm_clip.py              # WebM 播放（reader 线程/软停 re-arm/定期回收/fan-out 钩子）
├── speech_bubble.py          # 气泡绘制与交互
├── speech_bubble_text.py     # 气泡分页/定位纯函数
├── click_sound.py            # 点击音效（ClickSoundPool 单例封装）
├── desktop_notify.py         # 自绘右下角系统通知
├── slot_manager.py           # slot 身份/配置落种/旧 spawn 迁移/runtime 标记（D7 避让通道）
├── file_eater.py             # 拖拽文件“吃”动画与统计（不真实删除/移动文件）
├── proactive.py              # 主动识屏陪伴（Watcher 编排）
├── proactive_limiter.py      # 主动识屏频控
├── proactive_memory.py       # 主动识屏记忆
├── agent_link.py             # Agent 联动监视器（多 Agent 事件源：CLI/IDE/SQLite 轮询）
├── multi_window_shared.py    # 进程级多窗共享子系统（agent_link/proactive/全屏 watcher）
├── vision.py                 # 视觉模型调用（看看屏幕/主动识屏；PIL 懒加载）
├── harness_launcher.py       # DeepSeek Harness 一键启动
├── modern_settings_dialog.py # 新版设置主对话框（已拆分瘦身，保留 re-export；受行数预算红线）
├── settings_widgets.py       # 设置控件库（自绘开关/SettingRow/ModernSelect 等）
├── settings_menu_layout_editor.py # 右键菜单布局编辑器
├── settings_theme_qss.py     # 设置主题 QSS（明暗）
├── todo_reminder.py          # 待办提醒调度（气泡/桌面通知，PR72 合入；进程级单例）
├── todo_panel.py             # 待办管理面板（右键菜单「待办提醒」打开）
├── context_menus/            # 新旧菜单模板、图标、彩蛋入口
├── chat/                     # 独立 AI 对话子系统（现代双栏 + 经典手机式）
│   ├── models.py             # 数据模型（ProviderConfig/ChatSession/...）
│   ├── providers.py          # Provider 请求与连接测试
│   ├── service.py            # 对话服务
│   ├── session_store.py      # 会话持久化（异步 writer + 注册表）
│   ├── geometry.py           # 聊天窗跟随定位（双 UI 共享纯函数）
│   ├── utils.py              # 会话标题/时间格式化（双 UI 共享）
│   ├── themes.py             # 聊天窗背景主题
│   ├── widgets.py            # 新版聊天窗
│   ├── legacy_widgets.py     # 经典手机式聊天窗
│   ├── ai_settings_page.py   # AI 设置页（PR #76 从 modern_settings_dialog 拆出）
│   ├── modern_styles.qss / legacy_styles.qss
│   └── ...
└── updater.py                # 检查更新与发布资产解析

integrations/dsh-pet-bridge/  # DSH 桥接插件（Agent 联动）
packaging/
├── pet_entry.py              # Chat 构建入口
├── pet_entry_no_chat.py      # 无 Chat 构建入口
└── dsh-pet.iss               # Inno Setup 通用安装包脚本（/D 参数编译各变体）

scripts/
├── build_onedir.ps1          # Windows onedir 构建 + zip 绿色版打包（本地与 CI 共用入口）
├── build_macos.sh            # macOS .app 构建（本地与 CI 共用入口）
├── build_linux.sh            # Linux onedir 构建（本地与 CI 共用入口）
├── check_bundle_encoding.py  # 产物中文编码自检（issue #26，构建脚本内自动调用）
├── make_icon.py              # 从待机动画提取封面帧生成应用图标（assets/icon.ico）
├── convert_to_gif.py         # WebM → GIF 全量同步脚本
└── cleanup_mei_cache.py      # 检查/清理旧 onefile 版本遗留的 _MEI 缓存（默认预览）

tests/                        # 单元测试、Qt offscreen 测试和构建相关验证
                              # （含 test_architecture.py 架构红线：依赖方向 /
                              #  窗口私有面冻结 / window.py 行数预算 /
                              #  modern_settings_dialog.py 行数预算 / 孤儿簇守卫）

给 window.py 加功能前必读：docs/WINDOW_PY_SPLIT_GUIDE.md ——window.py 处于「只许瘦不许胖」的增量拆分公约下（CI 有行数预算红线），新功能先按公约拆对应控制器再动手。modern_settings_dialog.py 同理：控件库/菜单编辑器/AI 设置页/主题 QSS 已拆出，再往主对话框塞新页面会被行数预算红线拦下。

测试与验证

测试与验证

在项目根目录执行：

pip install -r requirements.txt   # 运行时 + 开发依赖（含 pytest/ruff）
$env:QT_QPA_PLATFORM = "offscreen"
python -m pytest -q
python -m compileall pet packaging scripts

最近一轮记录（PR #76 合并后的 main，2026-09-06）：

pytest：1322 passed / 7 skipped（CI 三平台 windows/ubuntu/macos 全绿；本机如遇 Windows symlink 权限等环境性失败，与改动无关）。
ruff：干净。
compileall：通过。
架构红线测试通过：依赖方向 / 窗口私有面冻结 / window.py 与 modern_settings_dialog.py 行数预算 / 孤儿簇守卫。
WebM Chat、WebM 无 Chat 两个 onedir 构建均完成启动冒烟验证：进程存活超过 8 秒，系统临时目录与程序目录均无新增 _MEI 缓存。

如果要验证真实窗口，不要设置 QT_QPA_PLATFORM=offscreen，直接运行 python -m pet 或打包后的程序，重点检查：

桌宠透明背景、鼠标穿透、拖动和动画播放没有回归。
自言自语气泡位于角色形象正上方，靠近屏幕边缘时不会遮住角色。
动作等待间隔只限制相邻非待机动画，不阻塞待机、转向和窗口操作。
WebM 播放速率切换后，当前片段和下一片段节奏都发生变化。
聊天窗为无边框圆角窗口（窗外无方形背景）、位于桌宠可见形象旁边，跟随开关符合设置。
切换会话和角色时，旧消息、旧流式气泡不会串入当前会话。

打包发布

打包发布

发布流水线：onedir 构建 → zip 绿色版 → Inno Setup 安装包。onedir 运行期零解压，不产生 _MEI 缓存；安装包免管理员、可选安装目录。

1) onedir 构建 + 绿色版 zip

需要 PyInstaller：

python -m pip install pyinstaller

# WebM Chat 版
powershell -ExecutionPolicy Bypass -File scripts\build_onedir.ps1 -Variant webm-chat
# WebM 无 Chat 版
powershell -ExecutionPolicy Bypass -File scripts\build_onedir.ps1 -Variant webm

产物位于 dist-onedir\<name>\（绿色版目录）与 <name>-portable.zip。

GIF 变体（gif-chat / gif）需要先运行 scripts/convert_to_gif.py --force --clean 生成 GIF 素材，构建时加 -Gif 参数；默认发布不含 GIF 版。

macOS / Linux 本地构建与 CI 共用同一份脚本（PyInstaller 打包、中文编码自检都在脚本内完成）：

# macOS（.app，输出 build/macos/）
bash scripts/build_macos.sh --variants webm-chat,webm
# Linux（onedir，输出 dist/）
bash scripts/build_linux.sh --variants webm-chat,webm

2) Inno Setup 安装包

本机已安装便携版 ISCC：E:\tools\InnoSetup6\ISCC.exe（免管理员）。通用脚本 packaging\dsh-pet.iss 用 /D 定义编译不同变体：

# WebM Chat 版（脚本默认值）
E:\tools\InnoSetup6\ISCC.exe packaging\dsh-pet.iss

# WebM 无 Chat 版
E:\tools\InnoSetup6\ISCC.exe /DMyAppShortName=dsh-pet-standalone-webm /DMyAppExeName=dsh-pet-standalone-webm.exe /DMyAppDir=..\dist-onedir\dsh-pet-standalone-webm "/DMyAppId={{3424d6cc-af3c-4383-8797-ab520b923aa6}}" "/DMyAppDisplay=dsh-pet-standalone (WebM)" packaging\dsh-pet.iss

完整命令（含 GIF 变体）与安装包特性见 docs/ONEDIR_PACKAGING.md。

打包注意事项：

构建前关闭正在运行的同类程序，避免文件被占用。
Chat 版使用 packaging/pet_entry.py，无 Chat 版使用 packaging/pet_entry_no_chat.py；无 Chat 入口会排除 pet.chat 和 keyring，不携带 AI 对话依赖。
安装包为按用户安装（PrivilegesRequired=lowest），默认目录 %LOCALAPPDATA%\Programs\...，向导中可自行选择任意盘符。
打包完成后，至少安装/运行一次，检查托盘、角色切换、设置、自言自语和聊天入口。

构建记录和 SHA256 位于：

docs/BUILD_ARTIFACTS-2026-08-22.md

3) Linux 构建（GitHub Actions）

PyInstaller 不支持交叉编译，Linux 包必须在 Linux 上构建。推荐直接使用仓库内的工作流 .github/workflows/build-linux.yml：

Actions 页面手动运行 Build Linux App（workflow_dispatch），或打 v* tag 自动触发并发布到 Release。
产物：dsh-pet-standalone-<变体>-linux-x86_64.zip（onedir 目录，保留可执行权限）。Linux 发布两个 WebM 变体（webm-chat / webm）；GIF 变体包体约 800 MB，不发布。

本地构建（在 Linux 机器上）——以正式脚本为准（手工 PyInstaller 命令长期与脚本漂移、会漏菜单模板/QSS 等资源，审查 P2-07）：

bash scripts/build_linux.sh webm-chat   # 变体：webm-chat / webm / gif-chat / gif

GIF 变体需先运行 python scripts/convert_to_gif.py --force --clean。

旧版 onefile 缓存清理（仅旧版本需要）

旧版 onefile 缓存清理（仅旧版本需要）

旧版单文件 EXE（onefile）运行时会在系统临时目录创建 _MEI数字 目录，崩溃或强制结束时可能残留；当前 onedir 发布版不会再产生该缓存。程序启动时仍会自动尝试清理超过 24 小时的遗留目录，并跳过当前进程正在使用的运行目录；权限不足或目录被占用时只记录日志，不强制修改 ACL。

也可以使用项目提供的专用脚本检查：脚本默认只预览，不会删除任何目录。确认所有桌宠进程都已退出后，才使用 --delete：

python scripts/cleanup_mei_cache.py
python scripts/cleanup_mei_cache.py --min-age-hours 0
python scripts/cleanup_mei_cache.py --delete

如果某些目录因权限异常仍无法删除，请先退出所有桌宠，再用管理员 PowerShell 运行脚本；脚本不会自动接管目录所有权，避免误操作其他临时文件。

配置与安全说明

配置与安全说明

API Key 不会写入日志，也不应放入截图、Issue 或公开配置。
默认优先使用系统钥匙串；钥匙串不可用时，设置界面会提示配置文件回退风险。
会话文件保存在本地，不实现云端同步。
OpenAI 兼容接口的错误响应、网络异常和空响应会转换为界面错误状态，并保留用户消息供重试。
当前消息按纯文本显示；不要把不可信的模型输出当作 HTML 或脚本执行。
开了代理 / VPN 的用户：桌宠的联网功能对「系统代理」的反应各不相同——歌词取词会因此超时失效，更新检查却只有走代理才通，本地服务（本机 TTS、DSH 联动）要求保留 localhost;127.* 绕过。逐条实测与推荐设置见 docs/NETWORK-PROXY-AND-VPN-2026-09-22.md。

最近修复与变更记录（2026-08 起）

最近修复与变更记录

按时间倒序记录。v4.2.0 及更早版本的完整清单见 docs/RELEASE-v4.2.0.md 与 GitHub Releases。 v4.2.0 之后的全部变更（含本表未逐条展开的 #113 / #114 / #118 / #120 / #121 / #123 / #125 / #127–#130 / #135 / #137 / #139–#144 / #146–#152 / #155 / #157–#182）已在上方 v4.2.0 以来的变更（v4.2.1）按功能与修复汇总；面向发布的逐项说明（含发布前测试清单与视频预演脚本）见 docs/RELEASE-v4.2.1.md。

发布后补丁（2026-09-23，`main@1c3a59c`）——纯桌宠版：桌宠隐藏后单击灵动岛即可把桌宠叫回来

问题（用户反馈，纯桌宠版）：把桌宠隐藏后点击灵动岛没有任何反应，只能走托盘菜单「显示桌宠」找回。
根因：岛在「桌宠隐藏 + hidden_chat 默认开」时单击会发 chat_requested，落到 AppShell._chat_from_island → _show_island_chat；而无 Chat 的打包变体（spec excludes=['pet.chat']，enable_chat=False）里 _island_chat_available() 恒为假，该入口直接 return——请求发出后被静默吞掉。岛又是隐藏后唯一的常驻交互面，于是纯桌宠版被困住；有 Chat 的变体恰好被气泡里的「显示桌宠」按钮兜住，所以只有纯桌宠版暴露。
修复：_chat_from_island 先判可用性，没有对话能力时改调 _show_pets_from_island_chat()（显示全部窗 + 同步岛 _pet_visible + 收起气泡，正是气泡内「显示桌宠」按钮那条通路）→ 单击岛 = 显示桌宠。有 Chat 的变体行为一字不变；click_action=toggle_pet 的偏好仍优先；hidden_chat 关闭时仍展开卡片。
验证：新增回归用例 test_shell_click_when_no_chat_reshows_pets（修复前红：assert False is True「点击后桌宠仍未恢复可见」，修复后绿）；test_island_chat.py + test_island_shell_wiring.py 23 passed；全量 2914 passed / 11 skipped；ruff 全清。三平台 workflow_dispatch 重新构建纯桌宠产物并以 gh release upload --clobber 覆盖 Release v4.2.1 的 4 个无 Chat 附件（版本号与 tag 不变）。详见 docs/PR-REPORT-ISLAND-RESHOW-NOCHAT-2026-09-23.md。

发布后补丁（2026-09-23）——多显示器跨屏拖/丢恢复 + 托盘图标消失 + 右键菜单去重

① 丢不到副屏（issue #186，用户反馈）：4.2.0 能把桌宠从主屏丢到副屏，4.2.1 不行。根因是 #137（b418733，不在 v4.2.0 里）把落位统一进 move_window_towards，把身体框与窗口钳进当前屏工作区，throw_bounds 同源——拖拽与抛掷都被钉在本屏。修法：拖拽/抛掷开始时取一次多屏活动区域快照（各屏可用区的包围矩形 + 逐屏可用区），物理 tick 只读快照；活动范围再按「宠物当前所在的屏幕带」收窄（band_bounds），错位拼接（异分辨率/异缩放）时不会落进没有显示器的空洞。单屏、几何异常、没有快照时逐位退回本屏语义（漫游/落位/边缘探头不受影响）。
② 托盘图标消失：4.2.1 起 webm 冷路径不再在 GUI 线程同步解码首帧，而建托盘时正取这份还没到的画面 → 托盘条目没有图标（且此后永不刷新）。修法：先用占位图标（既有矢量图标语言）保证可见，首帧就绪后经一次性信号 frame_ready 换成角色头像。
③ 右键菜单「鼠标穿透」去重：该开关原本同时挂在设置页、托盘菜单、右键菜单。按入口收敛只删右键菜单那份（modern 模板 + legacy 树 + 注册表 + 随之成死代码的 builder），设置页与托盘菜单保留——穿透开启后桌宠不再接收鼠标事件，托盘是唯一的一键恢复入口。用户旧 context_menu_layout 里的残留节点在配置载入时剔除。
验证：新增 tests/test_multi_screen_interaction.py（17 例，假双屏驱动真实钳制/边界代码）与 tests/test_tray_icon_ready.py（7 例）；两项修前分别 15 failed / 5 failed，修后全绿。真 Windows 平台实测托盘：建托盘瞬间 icon_pixmap() 为空（根因现场）→ 占位图标非空 → 首帧就绪后换成 50×64 角色帧。新增排障工具 scripts/probe_multi_screen_area.py（打印逐屏几何与「往每块屏拖」的修前/修后对照；本机只有一块屏 DISPLAY1 1536×[email protected]，真实双屏待用户在双屏机器上验收）。详见 docs/PR-REPORT-ISSUE-186-TRAY-MENU-2026-09-23.md。

PR #182（2026-09-23 合并，klxxya）——流畅度/解码减负 + 岛远端硬墙 + 音效包缓存 + 设置收口

问题：走路动画的位置交付只有 28.6Hz（观感"卡"）；webm 冷路径在 GUI 线程同步解码首帧，碰撞压力下 >50ms 卡顿达 133 次；多进程下的子肥鱼会穿岛（本进程没有岛就以为岛上没墙）；音效包候选解析每帧 iterdir 扫盘；「多开」开关长期挂在设置页但拓扑尚未收口。
修复：走路帧间补点（movement.move_anim_tick，位置交付 28.6Hz → ~160Hz @170Hz）；webm 冷路径首帧不再 GUI 同步解码、抛掷低速冷切走 warm 闸门、meta 探测后台化；抛掷飞行期动画加速（flight_anim_speed）；GUI 冻结采样器；子宠进程补挂远端硬墙 + 岛几何经碰撞 IPC 发布为静态成员（2s 心跳、变化合流 ≤10Hz）+ island_local_owned 双重结算守卫；音效包候选解析改进程级缓存（0.43ms/次命中）；设置页隐藏「多开」开关（拓扑收口 Phase A，配置键原样保留回写，存量用户不丢值）。
验证：新增 tests/test_island_remote_wall.py / test_move_sync.py / test_first_frame_no_gui_decode.py 等 10 个测试文件；受影响时序族（collision / island / webm / move_sync / throw / spawn / first_frame / meta / click_sound）高负载复跑 3 遍全绿；实机走路 A/B 300 秒、三开互撞 5 分钟、多进程岛墙场景；作者本机全量 3009 passed / 12 skipped。完整证据见 docs/PR-REPORT-PERF-ISLAND-CONSOLIDATED-2026-09-23.md。
诚实声明：开发期"零拷贝取帧"的回退保留（后续取证表明 2026-09-22 部署版崩溃的真正机理是绘制重入——同一设备双 QPainter，与零拷贝无因果），该崩溃案未结案，跟踪于 .scratch/single-overlay-window/HANDOFF.md。

PR #181（2026-09-22 合并，MerZlin）——歌词取词被系统代理拖死 + 网易云「歌词对齐」被误关

问题（用户反馈「合并前源码版还能识别网易云的歌词和快进进度，合并后不行了」）：未缓存曲目一律只有歌名、没有歌词——现场日志是 歌词取词完成: 陶喆 - 讨厌红楼梦 -> 0行, 耗时 9.00s（命中缓存的歌正常，63行, 耗时 0.01s）；右键「音乐 → 歌词对齐」整组点不动，而控制器刚弹过提示让用户去点它。
根因一（不是合并改坏的）：取词用 urllib.request.urlopen，会继承系统代理。用户开着全局模式 VPN（127.0.0.1:12450，进程 18:37:41 启动）时，实测三源单次 41.3 / 22.1 / 20.4 秒，全部超过 HTTP_TIMEOUT（8 秒），于是每首未缓存曲目都在 9 秒死线处放弃。git diff 56f8ad2..main -- pet/music_lyric.py 为空（取词代码与合并前逐字节相同），而最后一次成功取词是 18:12:14（代理起来前 25 分钟）——两件事只是时间上撞在一起。
根因二（真 bug）：网易云通过 SMTC 不上报播放进度，_on_lyrics_ready 给的是本地估算位置，却被 LyricTracker.load 按 position is not None 当成"播放器上报的真值" → align_available() 返回假 → 「歌词对齐」子菜单置灰（registry._music_align_ready）。既有用例都用 _tracker.load(position=None) 直接建状态、绕过了生产路径，所以旧实现全绿。
修复：歌词请求改用显式 ProxyHandler({}) 的直连 opener（三源都是公开接口、两个还是国内域名）；失败原因由 log.debug 升到 log.warning（带主机、耗时、异常类型），检测到系统代理时记一行 INFO；load() 新增 reported 参数，生产路径显式传 reported=reported is not None。
验证：同机同曲（代理保持开启）fetch_lyrics 9.00s/None → 1.27s/62 行（第二次命中缓存 0.02s）；真实网易云会话（《蝴蝶》- 陶喆，position=None）上实测 9.01s/None → 0.88s/53 行，控制器级端到端（真 SMTC + 真网络 + 真 Qt 事件循环）气泡出歌名+歌词、align_available=True、「下一句 / 前进5秒 / 回到开头」全部生效。新增 5 条离线用例（3 条代理与日志、2 条对齐闸门），修复前 4 红 1 绿；test_music_lyric.py + test_menu_layout.py + test_now_playing_session.py 165 passed；全量 2866 passed / 11 skipped；ruff 全清。
边界：真上报进度的播放器（QQ 音乐 / Chrome）仍不许手动对齐（护栏用例钉住）；其余联网功能的代理行为刻意不动——实测更新清单（jsdelivr）只有走代理才能通、TTS 端点直连/代理都可用，全局绕过代理会踩坏它们。逐条影响面与 30 秒排查法见 docs/NETWORK-PROXY-AND-VPN-2026-09-22.md。实现细节见 docs/PR-REPORT-MUSIC-LYRIC-SYSTEM-PROXY-2026-09-22.md。

PR #180（2026-09-22 合并，MerZlin）——交付证据纪律 + 构建 Qt 排他 + 产物 TTS 自检 + 角色头部框

问题：2026-09-22 在本机构建 onedir 产物时，PyInstaller 在收集阶段直接中止——ERROR: Aborting build process due to attempt to collect multiple Qt bindings packages: attempting to run hook for 'PyQt5', while hook for 'PySide6' has already been run!（打包机 site-packages 里装着 PyQt5 148 MB、matplotlib 27 MB、IPython 7 MB…）。而 edge-tts 恰恰是在收集阶段被打断的 → 语音永远打不进包。另有一个静默失败面：打包机没装 edge-tts 时 --collect-all edge_tts 只打印一行 WARNING（skipping data collection for module 'edge_tts' as it is not a package）就继续构建，产物缺 TTS——而打包版用户没有 pip 可装。
修复：scripts/build_onedir.ps1 新增 20 个 --exclude-module（其余 Qt 绑定 PyQt5/PyQt6/PySide2 + 把绑定拖进来的上游链 matplotlib 家族、IPython/ipykernel/jupyter/zmq/nbformat），原有排除清单一条不减；新增 scripts/verify_bundle_tts.py，在打包机算出 import edge_tts 的导入闭包并与产物 exe 的内嵌 PYZ / _internal 清单比对，缺一即中止构建。
验证：Qt 互斥用最小复现钉死（import PySide6.QtCore + import PyQt5.QtCore → 原文报错、exit=1；PyInstaller 报错里给出的处置办法正是 --exclude）。产物自检实测：chat 变体 [tts] bundle TTS stack OK (25 modules required, 2178 frozen)、exit=0、0.605 s；无 chat 变体 2068 frozen / 0.464 s；另现造一个真没 TTS 栈的产物仍报 25 个必需模块全缺（exit=4）——判定强度没降。自检脚本自身踩到一次假红：闭包原先按「import edge_tts 后 sys.modules 里所有非标准库模块」算，于是 .pth 启动期注入的 google/mpl_toolkits/pywin32_bootstrap、Cython 运行时现造的 cython_runtime、pkgutil 空壳 backports 全被算成「必须有」，真产物被判 FAIL；改为「导入前后做差 + 只认磁盘上有真实源码的模块」并加 7 条回归用例（改前 5 failed, 2 passed → 改后 7 passed）。
同时落地：交付证据纪律（AGENTS.md + docs/DEV-HANDOVER.md §8.2/8.3/8.4 + docs/PR-REPORT-TEMPLATE.md + tests/test_pr_report_discipline.py；2026-09-22 起对报告强制校验三个必备章节 + 索引登记）、pet/catalog.py character_head_box() 与 shenshen 的 head_box（零调用方，探头锚点接线未做）、主动识屏 v4.2.0 的 issue 草稿 docs/issue-draft-主动识屏v420.md。体量：11 文件、+781 / −7。

PR #179（2026-09-22 合并，MerZlin）——「互动」域设置页分页 + 整域抽 `settings_interaction.py`

问题：互动域 18 行 / 3 组平铺零折叠，是本仓库最长的「无折叠」域；主人反馈「设置界面有点乱，单页面太多东西」。
修复：改为页内任务标签「点击与音效」「自言自语」；侧栏 9 个域与组名 输入 / 点击反馈 / 自言自语 属于对外契约，一律不变；设置搜索命中非当前标签的行时自动切标签；整域搬进 pet/settings_interaction.py（167 行）。
验证：6 条聚焦用例 + 既有硬编码用例（组名与顺序、显隐联动、section 标题集合、点击音效行位置）全绿；受影响 9 文件 298 passed；全量 2793 passed / 11 skipped。行数：modern_settings_dialog.py 2441 → 2347、预算同步下调（首次因拆分下调）；三档宽度截图 docs/screenshots/settings-interaction-tabs-2026-09-22/。非当前标签只是不可见不销毁，objectName 仍是 settingRow_<键>，保存链一字未改。

PR #178（2026-09-22 合并，KagurazakaChizuru）——edge 音色下架兜底 + 连发重试 + 0 字节缓存不算命中

问题（用户报告）：语音报时/朗读「配了音色却没声音」。两条独立根因：① 微软下架了 10 款 zh-CN 音色（晓辰 / 晓涵 / 晓梦 / 晓墨 / 晓秋 / 晓睿 / 晓双 / 晓萱 / 晓颜 / 晓悠），配置指向它们时 edge-tts 抛 NoAudioReceived: No audio was received…，用户只看到「语音合成失败（NoAudioReceived: …）」；② 连发时偶发服务端返回空音频，而缓存里留下的 0 字节 mp3 会被当成命中——播出一声静音且永远不再重合成。
修复：配置音色不在可用表里 → 自动改用默认音色「晓晓」并提示一次（音色「晓涵」已不在微软在线音色表里（多半被下架了），本次改用默认音色「晓晓」；可在设置 → 语音 → 语音报时 → 音色里换一个可用的。）；每个候选音色最多重试 2 次（失败间隔 1.5 s）再退默认音色重试；0 字节缓存判为未命中并清理半截产物；内置音色清单按微软在线表重建为 36 款（中文 14 + 英文 22）；设置页里不在清单的值显示为「不在清单里：<值>」。可用音色表来自在线接口、缓存 6 小时，只在后台合成线程联网，失败沿用旧表。
验证：新增 13 条离线回归用例 tests/test_voice_chime_edge_voice.py（重试成功、退默认音色、空音频算失败且不留文件、非空缓存判定、提示只弹一次、edge-tts 缺失仍走既有降级）；实机复核：已下架音色触发 → 自动改用默认音色并产出 22 752 字节音频；list_voices() 返回 322 款；事故档案 docs/ISSUE-EDGE-TTS-VOICE-DEPRECATION-2026-09-22.md（已登记进 docs/INDEX.md）。无新增配置键。

PR #177（2026-09-22 合并，MerZlin）——音乐播放器路径进设置页 + 后台自动检测

问题：全仓没有任何 UI 能写 music_player_paths；自动搜索（深度 ≤3 的浅扫）扫不到时右键菜单项置灰，提示语是「找不到 X，可在配置文件中手动指定路径」——等于要求用户手改 JSON。
修复：设置 → 桌宠 → 音乐关联新增两行路径（网易云音乐 / QQ音乐）+「自动检测」按钮（后台按常见目录名搜、20 秒超时、300 ms 轮询，结束后弹「自动检测播放器」结果框）；菜单提示改指设置页；路径真的变了才 clear_cache()（否则右键菜单下次要重扫盘 4–5 秒）。
验证：真机（本机未装播放器）点「自动检测」4.17–4.77 秒收敛、GUI 全程不卡；用 C:\Windows\System32\notepad.exe 代替播放器验证「写盘 → 菜单消费」链路（music_player_paths 落盘、菜单项由灰变亮、tooltip 不再报「找不到」）；缺陷注入证明用例承重（去掉保存时的 clear_cache() → 2 条变红）；设置页宽度探针 1100 / 720 px 无溢出，截图 docs/screenshots/music-player-paths-2026-09-22/。体量：19 文件、+568 / −9。稳态零新增定时器/线程（不点按钮则 QTimer 从不启动）。

PR #176（2026-09-22 合并，MerZlin）——点击台词朗读 + 本机语音预缓存 + 配图概率

问题：点击桌宠弹出的自言自语没有语音；而且「点击触发自言自语」的显隐与朗读被「气泡自言自语」总开关裹住——关掉定时气泡会连点击台词一起消失。另有主人反馈「点击老是冒图片」：文本与图片拼成一个列表等权随机，24 张图 + 5 句文本时实际出图率 82.8%，文本几乎轮不到。
修复：① 新增 self_talk_speak_enabled（点击台词朗读，默认开）与 self_talk_voice_precache_enabled（后台把点击台词与点击动画绑定台词合成为本机语音文件，默认关，需本机 CosyVoice http://127.0.0.1:9880）；② 显示与朗读只认 click_show_self_talk，与周期气泡解耦；③ 新增 self_talk_image_chance（默认 30）：先掷骰决定出图还是出文本，再在对应池内等权选（0 只出文本、100 只出图；只有一边有内容时不掷骰子）。
验证：真机点击 A/B（真实 PostMessage 点击窗口中心 + 读日志计数，隔离 APPDATA）：chance=0 → 6 次点击 / 4 条朗读 / 6 条音效；chance=100 → 8 次点击 / 0 / 8。预缓存实测四行日志文案（已开始后台预缓存台词语音… / 台词语音预缓存完成：[声线] 台词 -> 文件名 / 播放预缓存台词 xxx.wav（本地，不走网络） / 台词语音预缓存跳过：本地 TTS 服务不可用）；本机无 CosyVoice 时验证「整轮跳过 + 只记一条 info + 不抛异常」。聚焦 264 passed、全量 2774 passed / 11 skipped；三档宽度截图 docs/screenshots/self-talk-2026-09-22/。配图概率默认 30% 是有意的行为变更，回滚口径：把它填成 图数 ÷ (图数 + 文本数)。改完需重启桌宠生效（行为在窗口启动时读一次）。

PR #175（2026-09-22 合并，MerZlin）——歌词跟随快进/半途起播（手动「歌词对齐」）

问题（用户报告）：快进、或从歌曲中途开始播放时歌词必然错位。实测网易云音乐完全不上报播放进度（SMTC position / end_time 恒为 0.0，播放中 / 暂停 / 切歌 / 快进四种状态采样结果一致），歌词只能按本地时钟估算；另修「向后拖到第一句歌词之前仍显示旧句」与多会话时跳到浏览器里在播的那首歌。
修复：右键菜单新增「音乐 → 歌词对齐」（回到开头 / 上一句 / 下一句 / 后退 5 秒 / 前进 5 秒；报进度的播放器自动置灰并说明理由）；把「开启功能时歌已经在播」从静默跳过（连歌名都不显示）改为先亮歌名 + 提示一次可对齐；会话选取改为粘住当前播放器。
验证：新增 tests/test_now_playing_session.py（224 行）与 tests/test_music_lyric.py 扩展；性能实测脚本 scripts/bench_music_lyric_align.py；完整证据（含网易云「不上报进度」的实机复现记录）见 docs/PR-REPORT-music-lyric-align-2026-09-22.md。

PR #163 / #169（2026-09-20 合并，MerZlin）——聊天背景取景渲染恢复与入口语义修正

问题：自定义裁切与主题 focus 在渲染链上失效（取景改了画面不跟着变）；取景入口在非填充裁剪风格下仍显示、且不标注当前风格。
修复：#163 恢复取景渲染；#169 入口标注当前风格并在非填充裁剪时隐藏；#170 裁切选区纵横比按编辑风格取值。
验证：设置窗内编辑保存 → 聊天窗即时生效；tests/test_desktop_pet_features.py 相关用例同步更新。

PR #153（2026-09-19 合并，MerZlin）——气泡文字大小可调 + Harness 启停 + 会话底线修复

气泡文字大小可调（新配置键 bubble_text_scale，50–300%，默认 100，设置 → 外观 → 桌宠显示）：与既有「配图大小」并列的独立系数。列宽、换行预算、label 尺寸与字号用同一个系数整体等比放大（bubble_column_for_text(text, scale) + scale_bubble_font_px），所以「字号变大、气泡没变大」导致的行尾切字在这条链路上不可能发生；标准气泡与呼吸气泡两种形态都生效（呼吸气泡画布与安全区一起缩放），歌词/标题气泡的锁宽锁高语义不变。默认 100% 时 bubble_column_for_text / bubble_label_size / 字号与旧版逐像素一致（用例硬断言）。文字放大到超过屏幕可用区时，列宽按可用区收窄、气泡高度按可用区上沿钳制，分页（圆点页码 / 逐页停留）与缩放无关照常工作。审批/提问气泡保持既有固定布局（源码注释里写明了它有自己的按钮行布局）。
Harness（DSH dsh web）可以重启/停止了：菜单项从单项「启动 DeepSeek Harness」改为 DeepSeek Harness 子菜单（启动并打开页面 / 重启服务 / 停止服务）。用子菜单而不是三个平级项，是因为菜单模板与用户自定义布局里只有 harness 一个 id，新增平级 id 对老布局不生效。停止按「谁在监听该端口」反查进程（Windows GetExtendedTcpTable，POSIX /proc/net/tcp + /proc/*/fd），并核验命令行确为 dsh web；端口被非 dsh 进程占用或反查不到属主时一律不终止，只如实报告（防 pid 复用误杀）。踩坑记录：ctypes 调 GetExtendedTcpTable 必须显式声明 restype/argtypes，否则 64 位进程的缓冲区指针被截断成低 32 位、函数返回非 0、表永远是空的——本地第一次跑就是「假绿」（用例 skip 掉），probe-listener-pid.py 才定位到。
AI 会话窗「底线」修复（用户反馈：自己发的内容和 AI 回复都贴在对话显示部分的上边界，AI 回复生成完还要滚轮往上滑才看得见）：根因是 ChatWindow._add() 只挂 _update_conversation_height、从不贴底，滚底只在 _load() 与 _begin_generation() 里显式调用——于是「用户自己刚发的那条消息」整条落在视口外（本地实测 value=2433 max=5206 gap=2773，单条超长用户消息即可复现），后续流式回复也就跟着停在半路。修复：_add() 贴底（用户角色显式恢复跟随）、resizeEvent 重排后重新贴底、贴底改为欠账式（_scroll_pin + scrollbar rangeChanged 追平），不再依赖「猜 singleShot 时机」；上翻阅读期间被动到达的流式内容不会把读者拽回底部。3 条回归用例（红→绿逐条验证）。

PR #145（2026-09-19 合并，MerZlin）——单进程多开下主动识屏永不触发（`_physics_mode` 哨兵类型不匹配）

问题（用户报告，v4.2.0 安装版）：experimental_single_process_spawn: true 时主动识屏从不触发——零日志、proactive_screen_state.json 从不创建；手动「看看屏幕」一切正常；dry_run=true + change_threshold=0 组合下仍零输出（已排除截图/频控/dHash/API 全部环节）；右键反复开关无效。
根因：MultiWindowProxy._physics_mode 是聚合属性，早期实现返回 any(...) 的 bool；而 pet/proactive.py 的 G1 守卫按哨兵语义读取 getattr(self.win, "_physics_mode", None) is not None。单窗 PetWindow._physics_mode 的取值域是 None / 'drag' / 'throw'，代理把「无人处于物理模式」表达成 False——False is not None 恒真 → interacting 恒真 → should_watch() 恒假 → 每次 8s tick 都在 G1 被静默拦截。又因 app.py 把 shared.proactive 注入为窗口的 proactive_watcher，右键开关拿到的是同一个共享实例，用户侧无法绕过。
修复：代理保持哨兵契约——遍历各窗取第一个非 None 的模式返回，无窗处于物理模式时返回 None（本地实测 python -c 复现：修复前 proxy._physics_mode 为 False）。
验证：新增 3 条用例（tests/test_single_process_shared.py）——「无人物理模式时哨兵必须是 None」「任一窗进入物理模式时报出该模式」「端到端：无人交互时 tick 必须越过 G1 守卫（前台窗口探测被调用）」；修复前 3 条全红、修复后全绿。
附带确认：用户同报的第二个问题（spawn=false 路径下配置已 enabled 的主动识屏/DSH 监视器重启后不自启）属 v4.2.0 已存在的缺口，main 上已由 #100 / #102 修掉（PetWindow.__init__ 收尾 sync_optional_services()，见下方同名条目）。本次补上该修复缺的主动识屏侧回归（既有 #99 用例只钉了 agent_link 通道）：新增 test_petwindow_proactive_enabled_at_startup_starts_watcher，并实测「把 __init__ 收尾改回 _install_effect_services() 即红」。
顺带清理：#140（squash）误把合并冲突用的临时文件 window.py.base/.ours/.theirs、wp.base/.ours/.theirs（合计约 726 KB，非源码、v4.2.0 中不存在）提交进了 main，本次一并删除。

PR #112（2026-09-12 合并，MerZlin）——Windows 关机/注销不再弹 `0xc0000142`（issue #111）

问题：每次关机/注销必弹「ffmpeg-win-x86_64-v7.1.exe - 应用程序无法正常启动 (0xc0000142)」并阻塞关机流程；桌宠未运行时不弹。
根因：0xc0000142 = STATUS_DLL_INIT_FAILED。系统先发 WM_QUERYENDSESSION，随后拆除本次登录会话（窗口站 / 桌面堆 / CSRSS）；本进程此前对该消息零感知，动画链照常运转并随时 CreateProcess 新的 ffmpeg 取帧进程（冷首帧预热 / reader 换代 / 元数据探测 / 圈末回收后 fresh spawn —— 日志里 reader 启停每几秒一次），新进程在已拆除的会话里 DLL 初始化失败，系统于是弹窗阻塞关机。
修复：pet/webm_clip.py 新增进程级「会话结束」闸门，四条 ffmpeg spawn 路径全部拒绝（start() 返回 False，复用既有「启动被拒」降级契约，调用方零改动；reader 线程 / 首帧解码 / 元数据探测 / exe 探测各自短路，并在 Popen 前二次复查收紧并发窗口）；新增 pet/session_watcher.py 用应用级原生事件过滤器捕获 WM_QUERYENDSESSION / WM_ENDSESSION（恒返回 (False, 0)，只观测、不 veto 关机），Qt 的 commitDataRequest / aboutToQuit 作次生兜底；会话结束时逐窗冻结（match_shutdown）、停素材库全部已建 clip（含圈末软停驻留的）、日志留痕（收到会话结束通知 / 会话结束：已停止全部 ffmpeg reader）。
验证：新增 tests/test_session_end_ffmpeg_guard.py（25 例，含「未置位对照组照常 spawn」证明门是唯一差异、真实 ctypes MSG 投递、tokenize 级 spawn 清单静态护栏）；窗口层 match_shutdown / _resume_activity 用例；真机实测向运行中的窗口投递 WM_QUERYENDSESSION 后闸门即时置位，报告者本机复测关机无弹窗；打包产物（onedir + setup.exe）内实跑同一路径复验。
设计与残余风险（在飞 Popen 无法撤回、node/pnpm 等非 ffmpeg 派生未纳入）见 docs/ISSUE-111-WINDOWS-SESSION-END-FFMPEG-2026-09-12.md。

PR #109（2026-09-12 合并，klxxya）——探头/头槌体验三连修 + 气泡分页避头尾

头槌飞行中被碰撞闪一瞬间回正：碰撞 squash Q 弹的 paintEvent 分支没走特效旋转管线（_sync_mask 一直在转，画面与轮廓还错位）。squash 分支补上与 _sync_mask 一致的旋转路径，仅特效角非零时启用。
探头状态被撞不飞、卡出错误身位：PEEKING 稳态没有 timer 归位，软撞的分离位移把窗口顶偏后停住。探头会话激活且非真实撞击时丢弃分离位移（位置归探头控制器管）；真实撞击仍进入 throw。
头槌减速后鱼头固定成探头角度：防抖阈值 780 本为贴地弹跳设计，却把空中低速段一起冻结。跟随阈值分档——触界维持 780，空中降为 150 继续跟随。
气泡分页：长消息末页只剩一个标点、每页固定时长、翻页硬切。改为换行避头尾（闭标点不站行首，elide/paginate 合并为同一换行助手）、末页孤行重平衡（3+1 → 2+2）、逐页字数自适应停留（page_dwell_ms）、翻页淡入淡出 + 圆点页码。
新增 4 组共 12 条用例（含「无修复时必红」的 squash 旋转 spy 断言）。

PR #108（2026-09-12 合并，klxxya）——弹射全程动画切换封死冷首帧解码

取证：PET_PERF_STATS + >100ms 帧空窗看门狗抓到 26 次卡顿，其中 19 次是动画切换命中冷首帧——GUI 线程同步拉 ffmpeg 解码（冷解码均值 100.7ms / 最差 1.4s，而 60Hz 单帧预算只有 16.7ms）。
根因：预测式预热只覆盖正常播放链；弹射的每次切换都是事件驱动并绕开预测（拖拽交互让路挡住预热、松手现场掷骰、飞行途中照常推进动画链）。
修复：分级策略——松手时拖拽动画继续播完；高速飞行（≥400px/s）固定循环悬空动画（pinned 首帧必热）；低速滚动（<400px/s）降速同一 tick 即时过渡并只掷「首帧已热」的目标（冷目标退回必热 idle/turn 池）；起飞时后台预热 idle 首帧（绕过交互让路闸门）；落地停稳回待机。掷骰概率与正常链共用同一 _roll_next（30/10/40/20 不变形）。
已知边界：飞行途中点击触发的黄金回旋被飞行循环接管，落地后恢复（空中回旋与悬空动画本就互抢旋转管线）。

PR #107（2026-09-12 合并，klxxya）——余额多币种响应不再盲取首条（issue #106）

问题：GET /user/balance 可能返回多条 balance_infos（如 CNY + USD）且顺序不保证，旧实现直接取 infos[0]；USD 排前面时读到 0.00，右键余额在 ¥0.00 与真实值之间来回跳，灵动岛余额档位动画跟着错。
修复：新增 _pick_balance_info()——优先取有余额的一条，同分优先 CNY，全为 0 退回首条（保持原行为），非 dict / 非数值条目防御跳过；改动只有 pet/balance.py 一个函数 + 调用点一行，新增 5 条用例。
未采纳项：issue 里提到的「¥ 符号写死」未动（不影响 CNY 账户）。

PR #104 / #105（2026-09-12 合并，klxxya）——桥接插件归零外部依赖 + DSH 事件层系统性收尾

#104：桥接插件归零外部依赖（事故级）

问题：桥接插件经 pnpm link: 安装，而 link: 不安装被链接包自身的依赖，链接目标又是打包版 _internal 副本（不带 node_modules）。#57 给桥接引入的 @deepseek-ai/dsh-llm 在打包副本上解析失败 → Cordis 插件树初始化整体抛错，dsh web / headless / desktop 全 profile 无法启动（多位用户实机复现）。
修复：恢复「零外部依赖」设计——index.js 手写 user-message envelope（与 dsh createUserMessage 键序/覆盖语义/深冻结逐项对拍），清空 dependencies、删除 pnpm-lock.yaml。
防线（构建期红线反转）：build_onedir.ps1 从「必须声明依赖」改为「禁止声明任何依赖」（含 peer/optional）；fix_bridge_bundle.py 新增不依赖 node 的 dist 清单零依赖校验；PR 门禁新增 7 个 bridge 契约测试 + verify_import.mjs hermetic 冒烟（无 node_modules 隔离目录 import、动态 import/require 一律禁止、临时目录祖先链污染负向对照）。

#105：PR57 系统性收尾（先红后绿）

真功能断裂修复：cordis 审批交互链从未工作（bridge 把 requiresApproval 嵌在 payload 内写盘、pet 门禁查顶层字段，判定恒 False，而测试用手写顶层形状掩盖了断裂）；问题气泡在 mux 断线时关不掉（pet 侧升级重建把旧 call_id 覆盖成 None、bridge 侧帧不带 callId）；5 个正常事件漏登记导致每次「终止/自动优化」都伴随「请更新/重装 bridge」假提醒；无 pnpm 时卸载假成功并留下 link: 残留。
错误分支与不可达映射：审批 resolved 的 callId 分支关错 kind（误关问题气泡）；dsh_state 认桥接真实写的 llm_error（旧表键无生产者，ERROR 态永不可达），删死键。
两处产品语义统一：看门狗计时改任务级（边界重建沿用旧锚点，原实现下「启动宽限」实际每轮续期、「连续运行降阈值」常态不可达）；桌宠隐藏时暂停看门狗并在恢复时把计时锚点后移隐藏时长（原实现隐藏期提醒被丢弃且「已上报」标志已置位 → 永久丢失）。控制成功后记宽限，不再「刚点完又弹」。
死机制清理与门禁：移除引入起零消费的 AgentEventRuntime 分发层与 Judge 机制等 20 项死信号/死键/孤儿方法（逐项 grep 零消费证据）；设置页新增「行为重复检测」组（开关 + 9 阈值）；检测器节流「记账后置」（被概率门抽稀的提醒不再占用 30s 节流槽）。
验证：全量 pytest 1895 passed / 8 skipped，node --test 7 文件全过 + hermetic 冒烟通过；新增/更新约 30 条用例全部先红后绿。

PR #97（2026-09-11 合并，Daliuq）——事件汇报概率门 + 事件链路语义对齐 + issue #95

新功能：事件汇报概率门（pet/report_gates.py）

联动气泡从布尔开关统一为概率门模型（0.00–1.00），8 个事件聚合类别各一个滑块，默认 activity=0.6、其余 1.0；旧开关/百分比自动迁移；右键菜单保留 0/1 两端快捷入口，细粒度概率走设置页滑块。
概率门只管气泡这一步：检测器与原始记录链不采样，也不会把整个功能静音。

事件链路语义对齐（Bridge → 传输 → 气泡渲染）

rate_limit 事件 → model_access（语义从「限流」扩展为「模型访问失败」：限流/过载/AI 服务错误）；RateLimitTracker → ModelAccessTracker。
errorText → errorMessage（tool/result 与 llm/retry 等统一）；source → failureType（model_retry_exhausted / tool_failed）。
归一化层补 event 字段（agent/status 别名 → 规范名），修掉模型访问失败连续计数丢失；占位符与文案键同步迁移（{source}→{failureType}、{errorText}→{errorMessage}、rate_limit.*→model_access.*）。

Persona 模板升级

记住上次编辑层 + Agent 层隐藏公共事件；导出模板支持全部 Agent 单独配置脚手架与 entries 语义描述；预设键序排齐、占位符迁移；修掉自定义模式 {text} 字面量泄漏与双层预设取 global 层的问题。

issue #95（DSH 联动装不上插件）

Windows node/pnpm 解析不再写死：增强 PATH 补注册表最新 PATH 与各版本管理器真实目录（nvm-windows %NVM_HOME%\v*、%NVM_SYMLINK%、%PNPM_HOME%、%APPDATA%\npm、Volta/fnm/scoop/choco/bun/yarn、%ProgramFiles%\nodejs），POSIX 补 PNPM_HOME/$NVM_DIR/fnm/volta/asdf/linuxbrew；nvm 自定义根 ~/nvm（无点号）与 %APPDATA%\nvm 兜底。
bridge 安装的 pnpm 入口改为多布局发现（.cmd/.ps1 包装脚本里的真实 JS 入口、独立 pnpm.exe、DSH_PNPM_BIN/pnpm_bin 配置键）；一键启动 DSH 的全局包根目录在 Windows 上补 nvm-windows 等目录。
依赖规格体检（指名报错 + 候选路径）、启动 link 自检、坏依赖路径实修（改写 + 备份 package.json.bak-* + pnpm 重试）、未知桥接事件不再误报「更新/重装 bridge」。

其它修复

菜单布局编辑器 QTimer 崩溃（C++ 析构后回调 → 成员 timer + shiboken6.isValid()）；全量测试 access violation（全局 processEvents 冲刷 → 定向 DeferredDelete）；桥接硬失败误报（恢复后未清零）；连续点击动画不从头播放（_soft_parked 未清零）；AppShell/共享子系统退出生命周期收口（解释器退出 access violation）。

PR #100 / #102（2026-09-11 合并，Daliuq / klxxya）——启动即按配置装配可选服务（issue #99）

问题：AgentLinkManager 懒创建、监视器真正启动靠 apply_config()，而工程里只有「展开 Agent 联动菜单」与「关闭设置对话框」两条路径会触发——重启后已开启的 Agent 联动（DSH/Claude/Cursor/OpenCode 与 custom_agents）与主动识屏开机不生效，必须手动点一次菜单或设置。
修复：PetWindow.__init__ 收尾改为 sync_optional_services()（其内部仍以 _install_effect_services() 收尾，净增 0 行），开机即按配置装配主动识屏 / Agent 联动 / 效果控制器；隐私红线不变（仍受 proactive_screen.enabled 与白名单/上限/冷却约束）。
回归：tests/test_feature_gating.py 两条用例（dsh 与 opencode 通道各一），断言管理器已创建且 monitor._running，并以 mgr.shutdown() 收尾。

PR #101（2026-09-11 合并，klxxya）——边缘探头会话期间禁止位移

问题：探头会话期间移动动画会被效果闸门降级为待机/转向，但 _try_move 仍会建立位移计划——桌宠挂着探头姿态被平移出屏幕边缘（自动掷骰与右键「移动」两条路径都会）。
修复：PetWindow._try_move 入口加 _effects_probe_active() 闸门，探头会话激活时直接返回 False（不建立位移计划）；回归用例同时验证「退出探头后移动恢复可用」的正向对照。
说明：该修复使 window.py 涨到 4385 行，行数预算按仓库惯例随实测校准（带日期注释）。

v4.2.0（2026-09-10 发布）

完整清单（含全部小项与修复）见 docs/RELEASE-v4.2.0.md，GitHub Release 同步。

新功能

桌宠本体玩法：右键菜单「黄金回旋」入口（连点逐圈加速）；拖文件模拟吃掉（不真实删除）；动画素材 97 → 106；「回到右下角」先取消探头姿态。
边缘交互与省电：边缘探头（±45° 贴边、露出 0.55、点击拉直、探头时静音）；撞飞彩蛋（被撞翻鱼头、落地 5s 重新吸附）；点击触发黄金回旋 + 直连跳过动画；省电模式（闲置半帧率 + 停预热）；音乐自动唱歌。
台词、气泡与提醒：气泡配图大小可调（50–300%）；图片目录预览抽屉（3 列瀑布流）；台词模板 JSON 导入/导出/复制 + v2 占位符渲染；表达风格统一入口；待办提醒（右键「待办」面板 + 提前量/宽限/归档）；会话保存原子化 + 异步写盘。
设置与菜单重构（PR #64）：七能力域侧栏；右键菜单可编排（显隐/子菜单/分割线/别名/图标覆盖/实时预览/损坏回退安全菜单）；快捷启动编辑与禁用占位；主题即时生效 + 从属项开显关隐；三态响应式；macOS 原生 Dock 菜单。
识屏与灵动岛：识屏自我识别（模型以第一人称看待画面里的自己）；可选服务懒加载；灵动岛峰谷档位显示「当前档位→下一档切换时间」。
Agent 联动与 DSH：富事件状态（thinking/working/attention/error）；统一事件层与事件队列（三层事件契约）；审批/提问气泡（多问题项、interaction_id 多交互并存）；探索 Watchdog 控制链（常驻气泡 + 自动优化/终止/忽略，GUI 不阻塞）；Harness 复用本机实例、harness_autostart、启动链路静默化；macOS Node 解析。
多开与子肥鱼：单进程多开（3 窗 1 进程 181–197MB）；同角色共享解码链（1 个 ffmpeg）；托盘聚合与灵动岛聚合；slot 落种；「退出子肥鱼」只退出不删数据；多窗提醒只在首个可见窗展示（行为变更）。
安全与跨平台（PR #68/#71/#94）：明文 API Key 自动迁移 keyring；Linux Fcitx 中文输入随包插件；macOS Dock 隐藏彻底生效；DLC/换角色加固（缺失动画守卫、启动回退默认角色、点击台词支持外部素材目录）。
性能：高刷屏节拍跟随刷新率（PR #70）；非显示 clip 清空显示槽（修内存慢涨主因）；ffmpeg 常驻循环解码 + -threads 1 + 圈边界回收；预测式首帧预热；碰撞预测限频（CPU 61%→43%）。

关键修复

Windows 打字时桌宠频闪根治（排除工具窗口/截图覆盖层 + 原生 WS_EX_TRANSPARENT）。
气泡行尾字被裁切（PR #96）：折行与 label 宽度改用同一套“真正绘制的行”度量 + ensurePolished()，女仆模式 30/111 条台词切字问题消失。
点「终止」无效：控制归一到根会话；提问气泡占住提醒队列、提醒队列卡死、审批被静默吞掉、审批按钮丢失（含单进程多窗）等整族修复。
首次告警必抛 AttributeError、dsh_control 每次请求必 TypeError、opencode 假完成、429 双提醒、联动气泡时钟域错误、检测器连环换弹。
子肥鱼杀不掉/误杀/控制台弹窗/覆盖用户存档整族修复；POSIX 选举死循环（issue #42）；会话并发覆盖与幻影消息；跨 DPI 重建；macOS Dock/Finder node；Linux 输入法。
CI 原生崩溃根治：parent=None 的 manager 被循环 GC 在 worker 线程回收 → 腐化 Qt 事件队列（现 shutdown 过继 QApplication + 停定时器 + 控制 worker 可取消）。

PR #76（2026-09-06 合并）

性能与内存

桌宠长时运行内存不再单调上涨：非显示 clip 清空显示槽，修复每播一段动画就滞留约 1.76MB 的慢涨主因；3.5 小时浸泡无泄漏。
ffmpeg 解码改为常驻循环 + -threads 1，消灭每 10s 杀进程重启的 churn；圈边界按 ffmpeg_recycle_minutes（默认 10 分钟）定期回收。
首帧缓存预算默认降到 8MB（4–64 可配），pinned 集瘦身到点击/转向/拖拽等瞬时交互核；新增预测式首帧预热（默认提前 350ms）。
未启用音效时不拉起 QtMultimedia（省约 38MB）；PIL 改为截图功能按需导入。

单进程多窗与共享解码

PetApp 拆为进程级 AppShell + 每窗 PetInstance；「单进程多开」转正为设置页正式开关（默认关闭，重启生效）。
同角色共享解码链：进程内 DecodeFanoutHub 替代旧 shm broker，3 窗 1 进程 1 解码器；旧 decode_broker.py（1464 行）退役删除。
新开实例首次占用 slot 时从主配置落种；移除 DSH_PET_SPAWN_FRESH 强制重播种，已有 slot 用户存档一律保留。

交互稳定性

全屏自动隐藏排除截图覆盖层/工具窗口，修复打字时桌宠频闪第一触发源。
Windows 鼠标穿透切换改原生 WS_EX_TRANSPARENT，不再 setWindowFlag 重建原生窗口，根治第二触发源。

结构治理 / 代码健康

modern_settings_dialog.py 从 4811 行拆到 1857 行：控件库/菜单布局编辑器/AI 设置页/主题 QSS 四模块拆出；新增行数预算红线。
死代码清理净 -1300+ 行：删除被合并静默回退的孤儿文件簇（settings_widgets.py 旧残壳、死 QSS、decode_broker.py 等），并新增孤儿簇守卫测试。
新增/加固架构红线测试：decode_fanout 单向依赖、window.py 与 modern_settings_dialog.py 行数预算、窗口私有面冻结。
文档漂移修正 16 条，重写“全程未触被测对象”的假测试；AGENTS.md 新增 CI 成本纪律。

验证

全量测试 1322 passed / 7 skipped；CI 三平台（windows/ubuntu/macos）全绿；ruff 干净。
实机浸泡 3.5 小时无泄漏；关键并发/生命周期改动经独立静态审查 + 实机回归双闸门。

PR #73（2026-09-05 合并）

点击音效连续播放修复：每次 QSoundEffect 播放前显式 stop()，解决“首次点击有音效、后续点击无声”的问题（源码版/试听均验证）。
issue #69 修复：后台音乐检测从 4s 提速到 1s，并在窗口显示时立即检测，唱歌动画响应更快；减少透明窗口偶发频闪。
生小肥鱼继承主配置：通过“生小肥鱼”孵化的新槽位在首次创建时继承主设置，不再出现新鱼恢复默认配置；已有存档的槽位（用户改过的设置）复用时一律保留，不被主配置覆盖。
生小肥鱼大小设置：新增“继承主肥鱼大小”开关（默认开启）；关闭后可为小肥鱼独立选择大小。
生小肥鱼灵动岛设置：新增“继承灵动岛”开关（默认关闭）；关闭时小肥鱼不会打开自己的灵动岛。
一键清除子肥鱼：设置页新增“一键清除子肥鱼”，可关闭所有运行中的小肥鱼并删除其 slot 配置/会话/待办数据，主肥鱼数据不受影响。
右键菜单快捷清除：「桌宠控制」子菜单新增“清除子肥鱼”入口，点击后走同样的确认与清理流程；旧版菜单也同步提供。
“吃垃圾文件”模拟投喂：把本地文件/文件夹拖到桌宠上会播放吃相关动画并弹出统计气泡；累计次数、文件/文件夹数与总大小写入 <config_dir>/file_eaten_stats.json；不会真实删除、移动或修改文件。
Windows PR test 偶发失败处理：PR 合并前 Windows 平台一次主套件偶发失败，对同一提交重跑后通过；最新三平台 CI 均绿。

v4.1.0（累计版）

发布 v4.1.0：自 v4.0.0 以来的功能与修复完整汇总（详见 GitHub Release）。
API / Provider 列表（PR #59）：AI 设置新增 API 列表，可快速添加 / 删除 / 切换模型服务 Provider，并修复 Provider id 复用与 Key 草稿覆盖问题。
灵动岛余额峰谷颜色同步（PR #60）：灵动岛余额峰谷文字颜色跟随设置的峰谷提示颜色开关（高峰红 / 低谷绿）。
纯桌宠菜单入口收敛（PR #60）：无 Chat 的纯桌宠版本去掉“启动 DeepSeek Harness”入口，只保留“打开网页版 DeepSeek”。
系统通知（系统级原生弹窗暂未实现）：AI 对话在“对话完成 / 生成失败 / 需要授权”时，界面不在前台会用应用自绘的右下角提示气泡提醒，点击可跳回会话或打开 AI 设置。为什么没有接入系统原生通知（Windows 操作中心 toast / macOS / Linux 桌面通知）：
- Windows 用 QSystemTrayIcon.showMessage 的原生气泡在托盘图标被系统收进“隐藏的图标”区域时可能不弹出（v4.1.0 评估后弃用该通道的直接原因）；要真正进入 Windows 通知中心还需 AppUserModelID + 原生通知 API（WinRT），在 PyInstaller 冻结、多实例与绿色版/安装版并存下涉及打包身份与升级路径，验证成本高；
- macOS 系统通知需用户授权且强依赖签名打包的 .app，绿色/未签名分发下不可靠；Linux 桌面通知依赖各发行版的 DBus/notify 服务，实现不一；
- 三平台一致且可靠的原生通知仍属待办；在此之前不把“系统通知”当作正式可用能力宣告，设置/文档中若出现相关文案以本说明为准。

v4.0.5 之后（开发版）

多开碰撞引擎「鱼塘碰碰车」（PR #41）：多开桌宠物理对撞、槽位管理、碰撞 IPC 与缩略图缓存；支持拖拽/甩出/弹弓等物理交互。
灵动岛（PR #36）：新增独立灵动岛胶囊窗口，展示余额/状态信息，可拖拽、贴边吸附、记忆位置，支持暗色/浅色/玻璃风格与自定义图标。
聊天窗置顶与点击台词绑定（PR #36）：AI 聊天窗支持始终置顶；点击桌宠可按配置触发对应台词/动画。
快速对话气泡（PR #40）：点击桌宠头顶气泡直接打开 Quick Chat，长文本分页滚动，支持焦点输入。
统一三平台构建与 CI（PR #39）：统一 Linux/macOS/Windows 构建脚本与测试基建，修复 Wayland 下拖动/拖影，CI 测试全局 mock QMessageBox 等。
自定义 Agent 联动通道（PR #44）：agent_link.custom_agents 配置驱动，声明 {key, name, path} 即可零代码接入任意符合统一事件协议的 JSONL Agent；新增 docs/AGENT_LINK_PROTOCOL.md 协议文档。
POSIX 碰撞 IPC 重选修复（PR #46）：QLocalServer 在 Linux/macOS 残留 Unix socket 导致协调者重选死循环——改为先探测活监听者，确认无人应答再清理残留并重试；补 bytesAvailable() 兜底读取，恢复 POSIX 测试覆盖。
右键菜单 LTR 与平滑入场（PR #47）：菜单始终 LTR 布局，不再镜像子菜单；新增 140ms OutCubic 位置动画。
碰撞协议与协调者生命周期加固（PR #49）：协议预算（协调者下行 256 KiB / 客户端上行 4 KiB）、成员数/载荷限制、残留端点恢复、锁文件初始化、成员 freshness 统一、leave/failover/epoch 切换时序修正。
拖动不再触发点击音效（PR #50）：按下阶段不再播放 press 音效，确认是点击后才播放完整 press+release。
Cloudflare 1010 请求头优化（PR #50）：urllib 请求统一增加浏览器特征头（Mozilla User-Agent / Accept-Language 等），规避 opencode go 等网关的 Cloudflare 浏览器签名拦截。
点击音效切换/解析失败修复（PR #52）：每次按下都重置当前音效 pair，切换音效包或解析失败后不会复用上一次的旧音效。

构建 / CI 失败经验（v4.0.5 之后）

POSIX 碰撞 IPC 测试失败（issue #42）：Linux/macOS 上协调者被强杀后 QLocalServer 的 Unix socket 文件残留，幸存者 listen() 报 AddressInUseError 导致重选死循环；submit_leave 成员表为空属于同批时序问题。处理：先探测活监听者、确认无人应答再清理残留并重试；补 bytesAvailable() 兜底读取；测试服务名缩短规避 macOS socket 路径长度上限（PR #46/#49）。
WebM 线程回收偶发失败：test_rapid_start_stop_no_leaked_running_threads 在 Linux/macOS 偶发断言残留新出现的非预期线程（含 reader 线程）。处理：线程退出是异步的，断言前给 5s 宽限等待；若仍偶发可重跑定位是否负载相关。
macOS 右键菜单动画时序失败：test_context_menu_transitions_smoothly_to_safe_target 原先固定 qWait(50) 采样动画中间位置，macOS offscreen 子进程定时器调度延迟时会采样到尚未推进的帧（middle.x == 40）。处理：改为轮询等待菜单位置首次变化（上限 2s）后再采样，并等待 duration + margin 验证最终位置；恢复严格下界断言（PR #53/#54）。
本机缺新声明依赖 → 设置页类用例整族红（2026-09-16，PR #127/#128/#129）：合并新增了运行时依赖的 PR（lunar-python、winrt-Windows.*）后本机跑套件，test_menu_layout.py 一次红 20 条、test_architecture.py/test_config_schema.py 也有红，看着像合并把设置页改坏。根因是第三方库只在叶子模块导入（pet/festival_calendar.py 里的 lunar_python），而 ModernSettingsDialog.__init__ 在导入期就 import 设置页，于是所有构造设置页的用例都在 import 阶段炸；CI 会自动 pip install -r requirements.txt，所以各 PR 自己的 CI 都是绿的。判定：红的是同一族 + 报错是 ModuleNotFoundError + 在合并前的分支上对照组也红 ⇒ 环境问题，不是合并。修复：pip install -r requirements.txt。详见 docs/BUILD-CI-FAILURE-NOTES-2026-08.md 第 2.4 节。
经验总结：
- 本地 Windows 全量通过 ≠ 三平台通过；QLocalServer、子进程、UI 动画等平台敏感测试必须跑真实 Linux/macOS。
- 固定短等待采样 UI 中间态是 flaky 主要来源，应轮询“状态变化”而非假设固定帧率/调度。
- 合并"新增了运行时依赖"的 PR 后，先同步依赖再判定红；报红前先确认本机环境与 CI 等价（requirements.txt 是唯一权威清单）。
- workflow_dispatch 手动触发 CI 只测试+构建+上传 artifact，不创建/修改 Release，适合合并前/后验证。
- 遇到平台相关 flaky 先定位根因，不要简单放宽断言到“永远通过”。
- 更完整记录见 docs/BUILD-CI-FAILURE-NOTES-2026-08.md。

v4.0.5（功能版）

音效体系升级（PR #33）：点击音效从单个 click.wav 升级为完整音效包——内置默认 / 小黄鸭 / 自定义单文件 / 自定义文件夹随机播放；新增音量（0–100%）与试听；播放层统一 QtMultimedia（QSoundEffect 即时重启 + MP3/OGG 解码缓存 + 播放器池兜底），旧配置自动迁移。
Agent 联动音效（PR #33）：start / done / error 三类事件支持独立开关、音效路径与试听，统一音量与全局冷却；内置合成提示音，无版权问题。
甩出力度档位（PR #33）：轻柔 / 标准 / 强力 / 疯狂四档力度，物理计时器改真实 dt + 子步积分，高速甩出不再单步瞬移。
弹弓弹射（PR #33）：左键拖拽中按住右键蓄力，反向拉动后松左键发射；带橡皮筋拉带、抛物线预测轨迹与方向性形变；互斥/失焦/隐藏自动取消。
光标隐藏自动穿透（PR #33）：Windows 下只读 GetCursorInfo 轮询，系统光标持续隐藏 200ms 自动鼠标穿透、出现即恢复；绝不调用 ShowCursor 干扰其他程序。
点击 Q 弹卡顿修复（PR #34）：音频预热等待 QSoundEffect 加载完成、点击动画首帧优先预热、音效延迟到下一事件循环，消除首次点击/快速连点的数百 ms 卡顿。
开机自启变体独立（PR #35）：Chat 版与无 Chat 版各自管理自己的 HKCU Run 自启值，关闭其中一个不再影响另一个。
失效开机自启自动清理：启动时自动清理指向已不存在目录/程序的旧自启项，修复“更新后直接删除旧文件夹但忘了关自启，每次开机弹终端报找不到文件夹”的问题。
测试兼容与 Python 版本声明：QMenu 可见性测试兼容无交互桌面环境；README 明确 CI 使用 Python 3.11、Windows 实机验证覆盖 Python 3.13。

v4.0.4（功能版）

余额分档动画（PR #31）：同步上游 6 个余额动画（钱袋满溢 / 金袋叮当 / 钱袋如常 / 数金皱眉 / 袋空如洗 / 分文不剩），查询余额时按余额档位自动播放对应动画；余额动画同时进入随机动作池，可随机/手动播放。
DeepSeek 峰谷提示（PR #31/#32）：余额气泡下方显示当前高峰/空闲与下一切换时间；可在设置中选择默认「空闲/高峰」、预设「梁文谷/梁文峰」，或自定义高峰/空闲文本；可开关峰谷提示颜色（默认高峰红、低谷绿）。
后台音乐自动唱歌（PR #31）：新增 Windows 音频检测（pycaw），检测到后台播放音乐时自动循环播放「悠闲哼歌」；可在桌宠设置中开关，默认关闭。
移动动画调整（PR #31）：原「原地漂浮踏步 / 原地左转奔跑」重命名为「漂浮踏步 / 左转奔跑」，并归入移动动画参与自动移动。
位置记忆修复（PR #31）：自动移动/物理抛掷/退出不再覆盖手动保存的位置，重启后回到用户最后一次手动放置的位置。
开机自启残留清理（PR #31）：清理所有已知 dsh-pet 自启项，避免旧残留导致“关闭后仍自启”或“开机两个终端/两个桌宠”。
右键菜单稳定性（PR #31/#32）：释放菜单前非阻塞等待图标解码 worker 结束，降低多次右键后崩溃概率。
点击音效打断（开发版）：再次点击桌宠时会先停止上一段点击音效，避免自定义长音效叠放/排队播放。
长文本气泡与主动识屏回复同步（PR #29）：长文本气泡分页自动翻页不再截断；主动识屏回复全文写入日志并同步进 AI 对话会话。
DSH profile 枚举与 thinking 专属气泡（PR #29/#30）：DSH profile 枚举尊重 DSH_HOME 并过滤 node_modules；补全 web_search/read_page 工具名映射，thinking 状态有独立气泡文案，并支持每个 Agent 自定义 thinking 文案。

v4.0.3（紧急修复版）

Windows 透明像素点击穿透（PR #27）：修复 Windows 上透明区域被点击拦截的问题，透明像素鼠标穿透、可见像素正常点击。
DSH 桥接插件自动安装 pnpm（PR #27）：一键安装桥接插件时若缺少 pnpm 会自动安装，避免安装失败。
Windows 官方包中文乱码修复（PR #28，issue #26）：三平台构建强制 PYTHONUTF8=1，新增打包产物中文编码自检，杜绝菜单/气泡/动作名再次乱码。

v4.0.2（修复版）

自定义点击音效支持 MP3/OGG/FLAC/M4A：音效播放器重构——WAV 继续走轻量 winsound（Windows），非 WAV 统一走 QtMultimedia（QMediaPlayer，自带 FFmpeg 后端），不可用时 macOS/Linux 回退系统播放器（afplay/paplay/aplay）；修复自定义 MP3 在 Windows 上被 winsound 用系统提示音"播放"的问题（winsound 只支持 WAV，传入 MP3 会响系统默认音）。Linux/macOS 构建同步补打包 PySide6.QtMultimedia。
动画边缘毛边/暗边修复：帧渲染改为预乘 alpha 缩放（直通 alpha 缩放会让透明像素的 RGB 渗入半透明边缘，产生暗边/彩边）；Windows 上点击命中测试由 setMask 的 1-bit 裁剪改为逐像素命中测试（WM_NCHITTEST + HTTRANSPARENT，透明区域鼠标穿透、可见区域可点击），不再破坏 WA_TranslucentBackground 的逐像素半透明边缘。
Harness 启动兼容旧版 dsh：启动前探测 web --help 是否支持 --no-open（按命令缓存）——旧版 dsh（如 0.1.0-rc.3）没有该选项，强行传参会启动失败；不支持时不传，由 dsh 自己打开浏览器，桌宠不重复打开。
动画帧率精度：视频帧时长按 24fps 精确值（40ms → 42ms = 1000/24）修正，动画播放定时器改用精确定时器（PreciseTimer），消除粗略定时器漂移导致的节奏偏差（当时位移仍走定时插值；后续已改为解码帧驱动，见「屏幕漫游」）。
右键菜单启动提速与避让：动画分类子菜单首次展开才填充动作（根菜单构建不再遍历 106 个动画，首次右键不再卡顿数秒）；菜单弹出位置智能选择——优先角色右侧（子菜单向右展开）、屏幕不够时放左侧并让子菜单向左展开（RTL）、再不行放屏幕远角，根菜单与子菜单都不再遮挡角色；快捷启动应用图标按 (类型, 路径) 缓存（QFileIconProvider 首次取图标慢）。
设置窗口打开期间暂停气泡：新版设置/聊天设置任一打开时，桌宠气泡暂停显示（关闭后恢复），不再盖住设置界面。
macOS/Linux 打包补 integrations 资源（PR #22）：onedir 构建显式打包 integrations/（含 DSH 桥接插件），修复 macOS/Linux 上「启动 DeepSeek Harness → 一键安装桥接插件」因资源缺失而失败的问题；构建后增加断言检查，漏打包直接报错。
Chat 版显式收集 keyring（API Key 系统安全存储）：Windows/Linux/macOS 构建均显式 --collect-all keyring，确保 Chat 版 API Key 走系统凭据存储可用。
安装包卸载流程调整：安装包卸载时不再自动运行 --uninstall-cleanup 清理脚本（卸载更快更直接）；源码运行 python -m pet --uninstall-cleanup 仍可用。

v4.0.1（修复版）

Windows「自动隐藏任务栏」下桌宠随任务栏一起隐藏（PR #18）：开启系统「自动隐藏任务栏」后，最大化窗口会铺满整屏（含任务栏区域），旧的全屏判定只看几何，把它误判为"真全屏"而把桌宠隐藏掉。现在真全屏判定增加无标题栏条件——真全屏的游戏/视频/浏览器 F11 都会去掉标题栏，普通最大化窗口带标题栏（WS_CAPTION）——自动隐藏任务栏下的最大化窗口不再误触发隐藏；已最大化后按 F11 的窗口（应用清掉了标题栏）仍能正确命中隐藏。
副屏位置开机自启不恢复（issue #8，PR #16）：开机自启时副屏可能尚未就绪（显示器唤醒慢于自启），旧逻辑按屏名找不到目标屏就落主屏定型，之后不再回副屏。现在目标屏暂不在线时会先落主屏、记录目标屏并监听屏幕变化（screenAdded 即时触发 + 5 秒轮询兜底），目标屏上线后自动恢复到保存位置（2 分钟超时放弃）；等待期间不把临时落脚坐标/屏名写回配置（防止覆盖副屏保存位置）；用户真正开始拖动或点「回到右下角」会立即撤销自动恢复。
主动识屏恢复后不再重复请求（PR #16）：隐藏/恢复过程中不再清空网络请求标志，避免恢复后与仍在飞的历史请求并发发起第二条视觉请求；迟到答复按代次检查丢弃，不冒泡、不计费、不写记忆。
DSH 桥接插件安装加固（PR #16）：profile 枚举只认含 cordis.yml 的真实目录，过滤 node_modules 等包管理器/误操作残留，避免安装失败触发整体回滚；pet_opacity 配置脏值（手改配置文件出错等）不再导致启动崩溃。

v4.0.0（大版本）

新版右键菜单 / 设置 / AI 对话窗口（现代双 UI）：合并 PR #11（modern desktop pet experience）：紧凑分组线性图标菜单、侧边栏卡片式设置、双栏 AI 对话工作台；PR #13 修复彩蛋弹窗在菜单跟踪结束后才弹出的时序，并加固图片目录回退与 UI 字体懒加载；PR #12 稳定 CI 测试时序。
性能与主动陪伴（PR #7）：桌宠隐藏后暂停全部动画解码与定时器（隐藏 CPU ≈ 0%）、启动懒加载与优先级预热、主动识屏陪伴（白名单/停留门限/每日上限/dry-run）、Agent 联动（DSH 桥接插件 + Claude hooks）。
新增桌宠设置：锁定位置（不可拖动）、SHIFT+左键拖动、不透明度 10%–100%。
托盘菜单同步：鼠标穿透 / 开机自启在设置或右键菜单里改动后，托盘勾选状态弹出前实时刷新。
聊天窗渲染修复：无边框圆角窗口去掉窗外方形背景（深色系统黑框/浅色系统白框）；关闭/最小化/新建/删除等按钮图标改为跟随界面主题的深色图标（深色系统不再白底白图）；鼠标进入窗口后光标不再卡在缩放双箭头（hover 驱动刷新）。
旧版聊天窗补全：新增「重命名当前会话」按钮（含深色主题适配）；会话标题优先显示自定义名称。
设置保存链路：直接点 X 关闭自动保存并立即生效（不再需要点「保存」）；保存前从磁盘重读配置，避免覆盖菜单等外部改动。
深色系统全面适配：设置界面（自绘开关/下拉/选项弹窗）、右键菜单、聊天窗按钮与图标在深色模式下均可读。
会话与流式修复：生成中/结束时快速新建会话不再串写；切换长会话后自动滚到底部；输入法组合中回车不上屏误发；上翻历史不被强制拉回底部。
内存与并发：连续打开菜单不再泄漏（图标线程安全、菜单对象及时销毁）；ChatService 竞态、打字机残留、子进程回收等一批修复。
彩蛋与弹窗：彩蛋图片目录配错/缺失时回退默认图片池；多开彩蛋不错位；气泡不再遮挡右键菜单。

2026-08 上旬（v3.1.1 及更早）

检查更新（新功能）：右键菜单与托盘菜单新增「检查更新」——后台查询 GitHub 最新版本（GitHub API 不可达时自动回退 jsDelivr CDN 镜像），点击后桌宠气泡即时反馈；发现新版本时会提示你到「更新 / 帮助」菜单打开 Release 下载页自行下载。另提供「GitHub 项目页」与「夸克网盘下载」（Windows 备用下载渠道）入口。
AI 对话会话管理增强：新增「重命名」按钮（自定义会话标题，可备注会话内容，下拉列表优先显示）；删除当前会话与「清空全部会话」均带确认框（防误删，适合会话列表太多时整体清理）；会话列表移到聊天窗左下角（重命名按钮紧随其后），自动标题截断从 24 字放宽到 40 字，下拉尽量显示完整；API Key 输入框提示"已保存，留空保持不变"——修改 System Prompt 等设置无需重输 Key。
「看看屏幕」同步到 AI 对话：视觉模型的回复会自动写入当前 AI 会话（一条 [看看屏幕] 前台窗口：… 记录 + 一条回复），可继续追问"你刚才看到什么了"；聊天窗未打开时仅气泡显示、不写入。
点击行为设置（桌宠设置）：可勾选「点击显示 DeepSeek 余额」「点击随机显示一条自定义自言自语」，两个都勾选时自动排队（先余额约 6 秒、隔 1 秒再自言自语）；多次点击会重置序列，只按最后一次点击从头完整显示（防抖，不叠加气泡）。
气泡美化与分页：气泡改为自绘圆角样式 + 底部小箭头（指向角色）+ 柔和阴影；文字超出单页自动分页，点击气泡翻页（页脚显示「1/3 · 点击翻页」）。
主菜单优化：「AI 设置」与「看看屏幕」位置调换；检查更新 / GitHub 项目页 / 夸克网盘下载收进「更新 / 帮助」二级菜单；「开机自启」「全屏时自动隐藏」移入桌宠设置（保存立即生效）；新增「隐藏桌宠」菜单项与「DeepSeek 余额」入口。
点击音效：点击 Q 弹播放短促音效（内置合成音，桌宠设置可开关；可把自定义 click.wav 放到数据目录 sounds/ 替换）；修复关闭音效后仍出声的问题（设置保存后未同步到窗口实例）。
DeepSeek 余额显示：菜单「DeepSeek 余额」查询官方 /user/balance 接口（用当前 API Key），气泡显示"余额 ¥xx（充值 / 赠送）"；30 秒缓存复用，重复查询秒回；桌宠设置可开启自动刷新（分钟级）。实现参考 MeteorNOX/DeepSeek-Balance-Whale-Widget。
右键菜单整理：动画相关（待机/转向/移动/点击回应/随机动作/播放速率）收进「动画」二级菜单；新增「隐藏桌宠」菜单项（托盘菜单/双击托盘图标可恢复显示）。
全屏时自动隐藏开关不保存（真 bug）：配置加载白名单漏掉 auto_hide_fullscreen，保存后重启会被重置为默认。已修复（白名单补齐）；并修复高 DPI（125%/150% 缩放）下最大化窗口被误判为全屏而误隐藏的问题（物理像素与逻辑坐标统一换算）——现在只在真全屏（视频全屏/游戏/F11）时隐藏，最大化窗口不隐藏。
个别电脑启动报错「'NoneType' object has no attribute 'isNull'」（2026-08-25）：根因是杀毒软件隔离/删除了包内的 ffmpeg 视频解码组件，首帧解码失败导致崩溃。现已修复：① 帧对象增加 None 防御，不再崩溃；② 解码失败时降级显示"半透明圆 + 角色首字"的占位画面，桌宠保持可见可交互；③ 启动时自检 ffmpeg 组件，不可用则弹窗明确提示（"可能被杀毒软件隔离，请在杀毒软件中恢复/信任后重启"）；④ 首帧预热并发从 8 降到 3，降低 ffmpeg 进程洪峰与杀软拦截概率。
点击 Q 弹残留上一动画帧 / 透明边缘 / 耳朵被挡（2026-08-25）：① 点击时先切换点击回应动画再启动 Q 弹，压扁的是新动画画面而不是旧帧；② 全部动画首帧在启动时后台预解码，首次点击任何动画都不再有同步解码卡顿与旧帧残留窗口；③ Q 弹不再放大宽度——窗口与 mask 固定尺寸下宽度放大会把角色边缘裁剪成透明；④ Q 弹期间窗口 mask 与压扁画面使用同一几何同步绘制，贴近边缘的耳朵/头顶装饰不再被裁剪，点击穿透区域与可见画面一致。
Windows 置顶稳定性：修复系统事件（资源管理器重启、分辨率/DPI 变更、休眠唤醒、驱动更新）导致的置顶偶发丢失——窗口每次显示时用 Win32 SetWindowPos 原生重设置顶，并每 30 秒自检一次、检测到丢失自动恢复；点击或拖拽桌宠会把它带回置顶最前（不抢键盘焦点）；开启鼠标穿透时气泡提示"无法通过点击唤回置顶"。
macOS 右键/托盘菜单首次点击「AI 设置 / 桌宠设置」无反应（需再点一次或多次才弹出）：macOS 的上下文菜单是原生 NSMenu 跟踪会话，菜单项触发瞬间新建窗口的 show/activate 会被 AppKit 抑制。现统一延迟到菜单关闭后再呈现窗口（含「AI 对话」窗口），右键菜单与托盘菜单均生效。
macOS 「启动 DeepSeek Harness」偶发静默失败（点了没反应、浏览器不打开）：Finder 启动的 .app 环境 PATH 极简，dsh/npx 的 shebang（/usr/bin/env node）在子进程环境里找不到 node。现启动子进程时注入增强 PATH（Homebrew / nvm / volta / bun / pnpm 等常见目录），并将就绪等待从 45s 放宽到 90s；无 npm 环境不再卡顿 15 秒。
macOS 对话报「网络连接失败：[SSL: CERTIFICATE_VERIFY_FAILED]」：发布包此前未内置 CA 证书库（macOS 上 Python 默认 CA 路径为空）。现已将 cacert.pem 打进发布包；AI 设置新增「跳过 SSL 证书验证」选项，用于本地网关 / 自签名证书 / 代理拦截场景（仅建议在可信环境关闭）。
AI 设置「测试连接」按钮：由占位提示改为真实连通性测试（含 TLS 校验，10 秒超时），结果直接显示在对话框内；并修复连续多次点击「测试连接」导致进程崩溃退出的问题（后台线程改用 Python daemon 线程 + 信号回主线程，不再使用 QThread）。
证书错误可操作提示：对话发送与「测试连接」遇到证书类错误时，错误信息会附上「可在 AI 设置中勾选『跳过 SSL 证书验证』后重试」的指引。
macOS 窗口置顶原生兜底的平台防护：[NSWindow setLevel:] 仅在实际 cocoa 平台执行，非 cocoa（offscreen 测试等）环境不再有段错误风险。

已知限制

已知限制

当前发布只提供 WebM 变体（Chat / 无 Chat）；GIF 变体（Windows/macOS/Linux）自 v4.0.0 起不再发布——包体约 800 MB，构建、上传与下载成本过高。确有需要的用户请按「打包发布」一节自行构建（先运行 python scripts/convert_to_gif.py --force --clean 生成素材）。
安装包未做代码签名，首次运行时 SmartScreen 可能出现提示，需手动放行；macOS 同样未签名，需 Gatekeeper 放行（右键打开）。
当前 macOS 发布只提供 Apple Silicon（arm64）的 onedir .app；Intel Mac 请源码运行或自行构建。
Linux 发布只提供 x86_64 的 onedir 目录包（WebM 两个变体），需自行安装少量系统库（见「Linux 使用」一节）；建议在 X11 桌面使用，Wayland 会话下透明/置顶表现取决于桌面合成器。
当前 AI 对话只实现 OpenAI Chat Completions 兼容协议，不实现 Gemini 原生协议。
当前不提供完整 Markdown 渲染、云端同步和编辑历史消息后重发。
自言自语文本是本地配置内容，不由模型自动生成情绪或动作。
本轮重点验证 Windows 发布包；macOS/Linux 保留配置目录和源码运行兼容路径，具体桌面环境仍建议在目标平台单独验证。
角色资源若缺少静态头像，聊天窗使用角色 ID 首字母回退；不会强制从 WebM/GIF 生成头像。
AI 对话默认校验 HTTPS 证书（发布包内置 CA 证书库）。开着代理/梯子（Clash 等）被证书拦截、或使用本地网关（LM Studio / Ollama 代理 / 自签名证书）时，若报「SSL: CERTIFICATE_VERIFY_FAILED」，可在 AI 设置中勾选「跳过 SSL 证书验证」后重试；该选项同时作用于对话、看看屏幕、余额查询与测试连接。仅建议在可信的内网/本地环境中关闭校验。
全屏应用会暂时盖住桌宠：浏览器 F11 全屏、网页/视频全屏、游戏（全屏优化/独占渲染）在 Windows 上是系统级置顶行为，任何置顶窗口都会被其覆盖；退出全屏后桌宠自动恢复。
Windows 上资源管理器重启、分辨率/DPI 变更、休眠唤醒等系统事件偶发导致置顶丢失：程序每 30 秒自检一次，检测到丢失会自动重新置顶（无需手动操作）。
鼠标穿透开启期间桌宠无法被点击，也无法通过点击唤回置顶最前；需要交互时请先关闭「鼠标穿透」（托盘菜单切换，开启时桌宠会气泡提示）。

项目文档

项目文档

docs/INDEX.md：全文档入口索引——53 份文档按领域分组，每条一句话 + 何时必读；想给项目做东西先从这里找相关模块的文档。
AGENTS.md：工程指南与 CI 成本纪律（PR #76 后硬性规矩）。
docs/WINDOW_PY_SPLIT_GUIDE.md：window.py 演进指南、功能驱动拆分流程与架构红线说明。
docs/HANDOVER_2026-09.md：2026-09 性能/结构线交付手册（含后续批次更新说明）。
docs/ONEDIR_PACKAGING.md：onedir 构建、绿色版 zip 与 Inno Setup 安装包流水线。
docs/BUILD_ARTIFACTS-2026-08-22.md：EXE 构建、大小、哈希和启动验证记录。

许可证与致谢

许可证与致谢

本项目采用 MIT License（见仓库根目录 LICENSE），第三方素材与组件授权声明见 THIRD_PARTY_NOTICES.md。

特别感谢：

PC2005-cloud/dsh-pet：参考实现与动画素材基础。
MeteorNOX/DeepSeek-Balance-Whale-Widget：DeepSeek 余额气泡思路参考。
贡献者 ushio2026-alt：贡献了 v4.0.0 的现代桌面体验重构（PR #11：新版右键菜单、新版设置、现代双栏 AI 对话窗口、彩蛋入口、多开孵化）、CI 测试时序稳定（PR #12）与彩蛋弹窗时序/图片回退加固（PR #13）。
贡献者 klxxya：贡献了拖拽物理、全屏自动隐藏、看看屏幕、聊天窗主题背景、裁切取景、文字动画免镜像、置顶看门狗等增强功能（PR #5），以及 v4.0.0 的性能与主动陪伴体系（PR #7：隐藏零功耗、启动懒加载、主动识屏陪伴、Agent 联动、多实例避让）与合并后的加固修复（PR #16：副屏位置开机自启恢复、DSH 桥接安装加固、主动识屏并发修复）。
贡献者 lscatfish123-cell：贡献了 Windows「自动隐藏任务栏」下桌宠误隐藏的修复（PR #18：全屏判定增加标题栏检查）。
Issue 反馈者：Viteyun（图标过小反馈）、Lorin1470（macOS 使用反馈与建议）、YukidokeAzarea（AI 对话报错反馈）、zangxx66（macOS 右键菜单反馈）——感谢你们帮助发现并定位问题。
所有在 Bilibili 上为本项目提供反馈和建议的观众：你们的评论、建议与使用反馈是项目持续改进的重要动力。v4.0.0 中的设置自动保存、深色模式适配、会话滚动、看看屏幕同步、气泡层级、托盘同步、锁定/不透明度等多项修复与功能均来自用户实测反馈。

Searching Database…

1.1K ·GitHub

Dsh-pet-indesktop

这是什么？

一款用 Python 和 PySide6 构建、面向 Windows、Linux 和 macOS 的独立桌面宠物（虚拟宠物）应用。它会在桌面上显示一个会动的“蓝色胖鱼”角色，支持拖拽、系统托盘图标、角色切换和可选的 AI 聊天。

它需要原来的 DSH 运行时才能工作吗？

不需要，它是从 PC2005-cloud/dsh-pet 分叉出来、已与 DSH 运行时彻底解耦的完全独立的桌面应用；它以开箱即用的打包可执行文件形式发布，而不是插件。

运行它需要安装 Python 或其他额外运行时吗？

不需要，安装版和便携版都是预编译的 onedir 包，你无需自行安装 Python。macOS 上的应用未签名，首次使用必须右键点击 .app 并选择“打开”来绕过 Gatekeeper。

Chat 版和 no-Chat 版有什么区别？

两个版本使用同样的 106 段 WebM 动画，但 Chat 版会加载 AI 聊天子系统，而 no-Chat 版不带任何 AI 依赖，因此体积更小、运行更轻。

实际支持哪些平台？

Windows 安装版/便携版是主要发布形式；macOS 版仅支持 Apple Silicon,Linux 版面向 x86_64——macOS 和 Linux 包都由 GitHub Actions 构建。

它能跟踪我的 DeepSeek API 余额吗？

可以——它内置一个受 DeepSeek-Balance-Whale-Widget 启发的轻量余额小组件，可从右键菜单查询 DeepSeek 官方的 /user/balance 端点，并支持可选的自动刷新。

“智能体联动”功能是做什么的？

它通过内置的 DSH 桥接插件和 Claude hooks 安装器，把桌面宠物接入 AI 编程智能体，让宠物用不同的动画和聊天气泡对智能体正在做的事情作出反应。

我能同时运行多只宠物吗？

可以，菜单里的“孵化胖鱼宝宝”选项会生成第二只独立的宠物，拥有自己的位置、配置和聊天会话；较新的版本甚至能在单进程内让多个宠物窗口共享同一个 ffmpeg 解码器以节省内存。

宠物闲置时会占用很多资源吗？

不会——隐藏时会暂停所有动画解码和计时器，CPU 占用接近 0%，长时间运行的内存也保持稳定（3 个独立宠物进程约 270MB;3 个窗口共享一个进程时约 181-197MB）。

What are similar projects?

dsh_desktop, dsh-dafeiyu, dsh-pet, ingetrazo, Bigfish, mygo, CodexPlusPlus, BongoCat

Which topics is it in?

desktop-pet, tray, qt, installer, github-actions, ci, apple-silicon, chatbot, deepseek, animation, customization, claude

Creator: MerZlin
Size: 180.2 MB
Stars: 1.1K
Updated: CommitOct 17 Releasev4.3.3Oct 17
Age: 2mo
Commits · 90 Days