Windows 上带桌宠¶

后端为应用启动入口，桌宠为可选外壳。模型密钥配置见安装与配置。本文适用于 Windows 10/11；把项目放在 C 盘以外，外壳会检查运行时根目录。桌宠默认关闭，开启前先准备前端依赖。

安装 Node 依赖并构建¶

在项目根用 PowerShell 分别执行：

node --version
npm --version
npm ci
npm run build

锁文件中的 Vite 与 electron-vite 要求 Node ^20.19.0 || >=22.12.0。例如使用 22.12.0 或更新的 22 系列版本，可满足这两个构建工具的约束。 npm ci 按锁文件安装，失败时先处理终端给出的版本、下载或原生依赖错误。构建成功后应有 out/main/index.js、out/renderer/ 和 out/webui/index.html。脚本与依赖见 package.json、package-lock.json。面板与外壳产物各有用途，复制面板目录不会同时安装桌宠。

开启与启动¶

编辑 config/bot.toml 的已有段，避免追加同名表：

[desktop_pet]
enabled = true

保存后从 PowerShell 运行：

uv run bot.py

后端建立监听后启动外壳；托盘图标和角色窗口应正常显示。「WebUI 已就绪」仅表示后端监听成功，外壳启动结果须结合窗口状态及错误提示确认。外壳只连接已运行的后端，连接不上会提示启动 Python。切换桌宠总开关需要重启应用。

外壳启动方式的选择条件¶

本地条件，按优先级判断	实际启动方式
存在 `node_modules/electron-vite/package.json`	通过 PATH 中的 npm 运行 `npm run dev`
没有上述标记，但有 `out/main/index.js`	使用 `node_modules/.bin/electron.cmd` 运行项目
两种条件都不满足	输出无法启动桌宠的错误及安装提示

开发依赖在场时优先开发外壳，即使刚完成 npm run build 也一样。开发形态以该标记文件是否存在为判据，不以 node_modules 目录本身为判据。构建形态仍依赖本地 Electron 可执行文件，仅复制 out/ 无法满足启动条件。缺 npm、Electron 或入口文件时，后端报告问题并继续提供 QQ 与面板服务。

需要独立启动外壳时，在一个终端运行 uv run bot.py --no-shell，另一个终端在同一项目运行 npm run dev。后端使用自定义数据或配置目录时，手动外壳也要使用相同目录。由 Python 启动时，这些路径会自动传给外壳。

托盘入口¶

右键托盘图标展开菜单，左键单击图标直接切换角色显隐。

入口	行为
显示／隐藏月璃	切换角色窗口；显示时不抢当前输入焦点
跟月璃说话	打开输入栏并聚焦；角色隐藏时不可用
让月璃看着屏幕	切换持续视觉采样，仍受视觉配置约束
看月璃的日记	打开独立日记窗口，隐藏角色后仍能查看
设置	打开本机配置窗口
重启月璃	请求后端重启以应用配置
搬回原位	将角色移回主屏工作区右下角，必要时显示窗口
开机自启	设置当前 Electron 应用的登录启动项
退出	结束外壳，是否同时退出后端取决于启动来源

菜单中的名字跟随 Bot 名称。隐藏角色不等于停止后端或关闭所有采集，见功能配置。 Python 入口在桌宠关闭时不启动外壳，因此没有托盘。若手动单开外壳且桌宠关闭，仍有托盘，但没有说话、显隐、屏幕和位置入口。

点击、拖动与穿透¶

在角色实体上按下左键，横向和纵向位移都小于 4 像素时，松开视为点击并开合输入栏。任一方向达到 4 像素时进入拖动；拖动结束不会再触发点击。透明像素区域默认鼠标穿透，输入栏等交互控件仍可点击。角色窗口移出屏幕后，可通过托盘「搬回原位」恢复，无需修改配置或删除窗口数据。

开机自启与退出边界¶

勾选「开机自启」写入外壳的系统登录启动项，没有为 Python 创建启动任务。外壳自身只连接后端，因此不能据此认定重启电脑后整套应用一定会启动。当前菜单没有传入项目路径或 Python 启动参数；源码安装时应实际注销登录验证。后端未运行时先启动 uv run bot.py；不需要自启时取消菜单勾选。

由 Python 启动的外壳点「退出」，会请求后端关闭，后端继续完成整套收尾。手动运行 npm run dev 打开的外壳点「退出」，只关闭该客户端，后端继续运行。角色窗口收到 Ctrl+Shift+Q 时也会退出外壳；这不是系统全局快捷键。后端关闭请求失败时会输出错误；托盘消失不代表后端进程已退出。终端仍运行时可用 Ctrl+C 正常关闭。

实现边界见开发手册：桌面外壳。