故障排查
按症状找。每个页面都写了「你会看到什么 → 为什么 → 怎么修」。
全部故障页
桌宠碎碎念太耗 token / 隐藏后还在扣额度怎么办
区分手动碎碎念和后台自动调用，关闭 whisperEnabled 后核对配置与模型调用记录；附本地模型变慢、生成…
桌宠影响玩游戏 / 抢焦点 / 挡住鼠标点击怎么办
全屏游戏被桌宠切回桌面，或宠物周围透明区域点不动？区分焦点与点击穿透问题，按步骤停用桌面显示并验证。…
桌宠装好了但桌面上不显示？先查这三处
dsh-pet 桌面模式不显示的排查方法：确认 helper 进程是否启动、查看日志找真实报错、区分 ELECT…
显示位置设成「都不显示」后桌宠消失，怎么恢复
dsh-pet 把显示位置设成「都不」再重启后，托盘和桌宠一起消失、界面里找不到入口。对照历史 #239，先核对…
为什么会出现两只大肥鱼桌宠
区分 both 双端渲染、多宿主实例和改大小后的短暂重建；先确认两只分别在哪个界面，再调整。…
桌宠背景是黑的 / 拖动时出现黑框
dsh-pet 黑底有三种成因：iPhone Safari 丢弃 webm alpha、Windows 分层窗口…
余额显示不出来 / 显示 0 / 提示不支持
桌宠余额显示 0 但账户有钱？先核对版本、币种、provider 和登录态。区分历史多钱包解析报告与路由匹配问题…
用拼音打字回车就发送 / 打不出 m
中文输入法与 dsh-pet 快捷键冲突：拼音组合状态下回车被当成发送、m 键被「按住说话」占用。给出可用的绕过…
桌宠安装失败：提示「没有声明组合包」怎么办
先区分输入的是仓库地址还是包名，再确认安装入口与宿主版本；不要反复重装整个 DSH。…
桌面版安装桌宠报 desktop profile 错误怎么办
出现 managed exclusively by the Electron application 时，先查命…
反代后桌宠 404 / 页面卡住怎么办
先分清子路径请求丢前缀与隧道高频请求，两种问题的证据和绕过方法不同。…
更新桌宠后 DSH 启动失败 / 宠物消失怎么办
先区分包更新失败、插件激活失败与旧配置不兼容，保留现场后再恢复。…
DSH 启动提示 /pet 重复注册怎么办
日志出现 duplicate prefix route "/pet" 时，先恢复宿主启动，再定位冲突插件组合。…
Safari / VS Code 里桌宠不显示或动画不动怎么办
用同一实例在独立浏览器做对照，区分素材请求失败、透明视频兼容和嵌入页播放限制。…
Mac / Linux 下载 Electron 后桌宠仍起不来怎么办
把错误平台的运行时与 ZIP 解压失败分开排查；网页正常时先使用仅网页模式。…
无头服务器 / 容器运行桌宠，助手反复崩溃怎么办
没有图形桌面的服务器优先使用网页模式；先停止崩溃循环，再检查磁盘占用。…
多显示器拖不过去、跨屏闪烁或菜单被裁剪
多显示器拖不过去、跨屏闪烁或菜单被裁剪：区分历史报告与当前版本，按症状恢复、复测并保留可用的替代显示方式。…
HiDPI 下右键菜单过大、裁剪或宠物贴不到顶边
HiDPI 下右键菜单过大、裁剪或宠物贴不到顶边：区分历史报告与当前版本，按症状恢复、复测并保留可用的替代显示方…
网页 overlay 拖出窗口后宠物点不到
网页 overlay 拖出窗口后宠物点不到：区分历史报告与当前版本，按症状恢复、复测并保留可用的替代显示方式。…
装了虚拟显示器后网页正常、桌面宠物不显示
装了虚拟显示器后网页正常、桌面宠物不显示：区分历史报告与当前版本，按症状恢复、复测并保留可用的替代显示方式。…
桌面 helper 秒退、无输出或疑似权限受限
桌面 helper 秒退、无输出或疑似权限受限：区分历史报告与当前版本，按症状恢复、复测并保留可用的替代显示方式…
右键菜单被截断、子菜单选不中
宠物靠近屏幕底边或右边时，菜单越界；#270 在 Windows、0.4.0 中还报告子菜单顶部偏移，鼠标斜穿父…
聊天像失忆：历史记录与时间轴
跨天聊天像紧接上一句，或找不到聊天记录入口。#261 的 0.3.8 报告中 memory.json 的消息与 …
手动碎碎念正常，自动不触发
0.3.8、仅桌面模式下，开启碎碎念并设 60 秒，等待六分钟无自动输出，手动点播正常。…
自制角色动画卡顿、提前结束或一直待机
0.3.8 独立模式自制 pet pack 报告动画重复帧、动作播到 4–8 秒提前结束，以及待机占位让随机链不…
桌宠偶尔出现在 Windows 任务栏
Windows 11、Electron 43.3.0、dsh-pet 0.3.8 报告透明宠物窗口偶尔出现任务栏…
配置丢失或保存后不生效
#167 在 0.3.7 中报告选“仅桌面”后网页仍有宠物，刷新设置回到 both；#194 则报告更新后桌面位…
历史图片丢失，生成立即 transport failed
0.3.7 识屏开启、keepShots 为 1 的报告中，共享附件对象被清理，引用图片的会话很快失败，界面显示…
同时装多个桌宠后画面巨大、样式失效
同时启用 dsh-pet 和 dsh-whale-girl-pet 时，视频按原尺寸撑破舞台，图标或气泡尺寸异常…
任务已推进，工作状态气泡仍停在旧步骤
#59 的 0.2.11 报告旧任务文案长期残留；#153 在 0.3.7 多页任务中报告实际已到第 5 页，气…
系统通知不弹、刷屏或过早显示完成
#50 报告测试权限通知可弹但实际会话不弹；#82 报告子代理和 QQ 会话逐轮刷屏；#114 报告 Lead …
右键打开 DSH 弹商店窗口或出现 401
#112 在 Windows 未注册 dsh:// 协议时打开菜单弹商店对话框；#87 则是浏览器打开裸地址后提…
退出 DSH 后桌宠报 write EPIPE 或仍留后台
macOS 的 0.2.9 bridge 模式和 0.2.11 报告宿主退出后 helper 仍在，Electr…
桌面红条 config http 403，网页宠物正常
0.2.2 报告 DSH Desktop advanced 模式下网页 overlay 正常，桌面 helper…
点“解决”后轨迹正常，对话区却空白
报告限定于 Windows 独立版 watchdog 与 dsh-pet-bridge，DSH 0.2.0-rc…
桌宠关掉又出现，怎样停用
先分清插件 helper 与独立应用。关闭窗口不一定停止宿主，隐藏画面也不等于停止后台生成。…
模型未返回文本 / 不支持关闭思考
先保留真实错误，区分模型能力、服务商可用性和网络异常，不把所有“没说话”都当成缺 API key。…