# 桌面模式（预览版）

桌面应用与 DSH 插件共用人物、动画、气泡和设置组件。浏览器插件仍按原有一行 DSH 命令安装，Electron 不进入插件的运行依赖，也不会在安装插件时自动启动或下载。

v0.2.0 开始提供可选桌面预览包。请在 [GitHub Release](https://github.com/YuluoY/dsh-kujira/releases/tag/v0.2.2) 的附件中选择与系统和架构匹配的文件；仅以实际列出的附件为准。桌面预览包未签名，跨平台构建成功不等同于各系统的实机验收。

## 安装与运行

开发工作区：

```sh
npm run desktop:install
npm run desktop:start
```

生成本机安装包：

```sh
npm run desktop:build
```

产物位于 `output/desktop/`。Windows 使用 NSIS 安装程序；macOS 将 Kujira.app 拖入 Applications；Linux 使用 AppImage 或 deb。桌面包单独分发，浏览器插件不附带 Electron。

首次运行无需启动 DSH。人物菜单及托盘提供「打开 DSH」，已有服务则连接，未运行时按设置启动。DSH CLI 和对应 profile 需事先安装，桌宠不静默安装或替换 DSH。连接设置支持本机地址、profile、通过文件选择器指定 CLI。

首次安装或本轮更新了 DSH 宿主路由后，必须在任务结束后正常重启一次 DSH。旧宿主在未重启前继续显示网页人物，并提示桌面模块尚未加载；不为更新而中断任务。

## 默认值与选择

| 设置 | 默认值 | 行为 |
| --- | --- | --- |
| 网页插件显示位置 | 浏览器 | 安装桌面应用后可以接管 |
| 桌面应用保持置顶 | 开启 | 普通浮动层，不覆盖系统安全界面 |
| 透明区域穿透 | 开启 | 人物/控件可点击，透明区域让出鼠标 |
| 登录后启动 | 关闭 | 仅安装版可设置，不启动 DSH |
| 所有桌面显示 | 关闭 | 仅 macOS 显示该选项 |
| 初始显示器 | 记住上次位置 | 可选主显示器、鼠标所在显示器 |
| 节能模式 | 平衡 | 可选静态陪伴；锁屏/休眠暂停 |
| DSH 启动方式 | 点击时按需启动 | 可选仅连接、不启动 |
| 关闭窗口时 | 退出桌宠 | 可选隐藏到托盘 |
| DSH 地址 | http://127.0.0.1:3080 | 只接受本机 HTTP origin |
| DSH profile | web | 可自定义有效配置名 |
| DSH 程序路径 | 自动查找 | 可通过系统文件选择器指定 |
| Linux 窗口兼容 | 自动，优先 X11 | XWayland 可用时使用 X11；可改 Wayland，重启生效 |

原有国家/地区、语言、主题、大小、不透明度、锁定位置、动作点播、气泡与进展等设置继续保留。浏览器/桌面切换同步外观和本地养成快照；库存、奖励及调度仍由 DSH 服务负责，离线不伪造交易或排队执行任务控制。

## 三系统边界

| 平台 | 实现路径 | 限制与验证 |
| --- | --- | --- |
| macOS 13+，Apple Silicon / Intel | 透明窗口、浮动层、穿透、Spaces、系统登录项 | 本机 Apple Silicon 实际运行验证；Intel 配置构建矩阵，未在本机实测 |
| Windows 10/11，x64 / ARM64 | 透明窗口、置顶、穿透、系统登录项、NSIS | Windows 路径与 cmd shim 注入边界有单元测试；需要 Windows 实机验证 DPI/全屏 |
| Linux x64，X11 / XWayland | 透明窗口、穿透、窗口定位、XDG 登录启动 | 需要合成器与托盘支持；不同桌面环境需实机验证 |
| Linux 原生 Wayland | 带系统边框的窗口模式 | 不声称支持置顶、全局坐标或透明穿透；保留人物与全部面板，拖动系统标题栏 |

Electron 44 不支持 macOS 12、Windows ia32 或 Linux armv7l。本项目不通过旧内核或关闭沙箱来绕过平台限制。Linux ARM64 可由构建工具生成，但未列入本轮已验证目标。

## 生命周期与恢复

- 桌面单实例。反复点击启动不会产生多个桌宠进程。
- 桌面首段视频就绪才申请 12 秒租约；3 秒续期。网页只在有效接管后卸载人物。
- 返回浏览器时，网页确认人物视频就绪，桌面才隐藏；退出/崩溃后租约过期恢复网页人物。
- 关闭浏览器不退出桌宠。关闭或退出桌宠不结束 DSH，不重启、不重提任务。
- 启动请求合并，30 秒内等待具有正确插件身份的服务就绪；陌生端口、旧插件、命令缺失、失败和超时分别反馈。启动超时不会持续自动重试。
- 程序以独立进程启动 DSH，标准输出不接桌宠的管道或无限增长日志文件，退出桌宠不影响子服务。
- 屏幕拔插和工作区尺寸变化重新约束人物与窗口位置。桌面窗口最大 820×740 DIP，不创建覆盖所有显示器的全屏透明画布。

## 性能与连接安全

素材本地读取、不依赖 CDN；保持两个视频缓冲并在过渡后暂停旧片段，不预加载全部 130 个动作。任务信息由现有插件提供，桌面不进入模型请求或工具执行链路。

透明穿透只传递最多 32 个 UI 矩形；鼠标位于窗口外约每 300ms 检查，窗口内约每 80ms 检查，隐藏时降低检查频率；不逐帧扫描视频像素。断线探测退避至 30 秒；数据响应有大小上限和超时，离线事务直接失败，数据不被重新标为实时。

本地渲染使用独立协议、沙箱与上下文隔离；渲染器不获得 Node 权限、任意 shell 或 API Key。数据代理只允许明确的插件路由，拒绝重定向和远程地址。跨浏览器存储并不天然共享，因此显示接管时同步外观和本地养成，服务端账目保持唯一来源。

运行成本必须以实际进程、GPU、长时间内存变化和对 DSH 吞吐的对照测量判断；不承诺零 CPU/内存开销。桌面应用安装体积明显大于纯插件，不影响只安装网页插件的用户。

## 发布前验收

本轮本地验证和跨平台逻辑测试不等同于 Windows/Linux 实机验收。发布前须分别验证：高 DPI、多屏拔插、透明视频、拖动、面板边缘、任务联动、开机启动、默认浏览器打开、退出不终止 DSH、隐藏后恢复、8 小时资源稳定性。

工作流仅在明确手动触发时构建，不自动发布。macOS 分发需要 Developer ID 签名与公证；Windows 分发应配置签名。当前本地包无发行证书，不应宣传为已签名正式版本。

参考：[Electron 窗口与 Wayland 边界](https://www.electronjs.org/docs/latest/api/browser-window)、[Electron 44 支持平台变化](https://www.electronjs.org/blog/electron-44-0)、[Electron 安全指南](https://www.electronjs.org/docs/latest/tutorial/security)、[跨平台构建](https://www.electron.build/docs/features/multi-platform-build/)。

### 已有网页与任务跳转

桌宠优先复用已经连接到同一 DSH 服务的网页。文件、消息、子代理及返回操作在该网页中完成；桌宠不复制聊天页面，也不会重新提交任务。更新插件后，请刷新已有 DSH 网页，让它登记新的导航能力。

导航先等待指定网页确认操作完成，再通过短时标题标记定位对应窗口；完成后移除标记，保留宿主期间更新的标题。导航失败或未收到回执时不激活无关窗口，未响应的已有网页不会被新建的标签页替代。

macOS 对 Chrome、Edge、Safari 同时匹配本机 DSH origin 与本次导航标记，再选择标签页；首次使用可能需要系统授权。Windows 枚举允许的浏览器窗口并匹配标记，检查实际前台窗口后才返回成功，不再选择同名浏览器的第一个窗口。Linux X11/XWayland 使用 `wmctrl` 匹配窗口标记，再通过 `xprop` 检查活动窗口。所需工具缺失、系统拒绝激活、Windows/Linux 的目标标签页隐藏在其他标签后面，或浏览器使用原生 Wayland 时，可能需要用户手动切换；保持现有页面并明确提示。尚未完成 Windows/Linux 桌面环境的实机验证。

### 今日花费与设置反馈

余额面板的“今日花费”按 DSH 所在电脑的本机日历日统计本服务可读取的 DeepSeek 用量，包含子代理并排除继承记录的重复计费。数字是费用预估，不代表其他应用的账户扣费。打开余额时，服务在空闲状态按需补读当天相关历史；不启动任务、不重发历史补给，无法补全时明确提示统计不完整。显示两位小数，悬停金额可看更高精度；切换地区沿用显示汇率换算。

设置采用统一的紧凑控件和分组间距，原生配置仅对正在保存的字段显示禁用反馈。点击桌面其他位置失焦时，菜单与面板自动收起；选择程序的系统文件对话框不触发这一收起行为。投喂、摸头、陪玩和舒展各提供多条本地随机回应，并避免紧邻重复，不调用模型。

## 打开 DSH 的状态处理

点击发散菜单的“打开 DSH”时，先探测本机服务：未启动则按“点击时启动”设置后台启动并等待就绪；已启动则复用服务。然后检查已注册的浏览器标签页，有页面则切到该浏览器和标签页，没有页面才打开一次地址。启动阶段不提前打开网页，连续点击合并为同一次请求，避免冷启动打开两页。仅连接模式保留不自动启动服务的明确设置。

已有浏览器无法被激活时显示错误，不把导航回执当成成功切换，也不偷偷另开重复页面。更新服务和历史版本接口可通过桌面连接访问；没有启动 DSH 时，版本服务明确显示未连接。

## 启动与版本管理的跨平台规则

- Windows 按不区分大小写的 `Path` 和分号分隔查找 CLI，支持 npm 用户目录、`PNPM_HOME`、LocalAppData pnpm、Node 安装目录与 `NVM_SYMLINK`。子进程只传一份 PATH，支持中文和空格路径；拒绝相对搜索路径。
- Windows 更新支持独立 `pnpm.exe`、npm/pnpm 标准 `.cmd` 安装及 Corepack。标准 shim 使用对应已安装的 Node CLI 文件执行，不把更新参数拼成 shell 命令；无法识别的自定义包装脚本保持不支持。
- macOS/Linux 查找 PATH、Node 所在目录以及常用全局安装目录；Unix 可执行文件必须具有执行权限，Node CLI 文件必须存在且是普通文件。
- 多套 Node/包管理器并存时逐个探测全局目录，以解析后的实际包路径匹配正在运行的 DSH；不更新其他安装。Corepack 全局操作不采用当前工作项目的包管理器版本设置。
- 升级与回退共用上述已确认的执行入口、官方固定版本和安装后版本校验。源码安装、临时 npx 安装、权限不足不自动提权或改用另一套安装。
- 已取消的请求不启动包管理器。Windows 安装超时或取消时先终止进程树；`taskkill` 失败时回退到终止安装子进程。

`npm run test:platform` 覆盖工具发现、安装归属、启动 PATH、导航应答、激活失败以及节假日/货币共享逻辑。相关代码推送或创建 PR 后，三系统逻辑工作流执行这些测试；手动触发的桌面构建矩阵也运行它们。模拟测试验证代码分支，CI 运行记录和实际桌面验收仍需分别确认。