desktop-pet-app 0.3.4 → 0.3.13

package/README.md

@@ -1,56 +1,245 @@
-# Desktop Pet
+# Desktop Pet 桌面宠物
 
-一个可悬浮在桌面的 AI 宠物，支持账号登录、好友协作与 MCP。
+完整的跨 Agent 协作目标架构、协议、P2P、任务状态机、安全与视觉实施清单见 [`docs/cross-agent-implementation-plan.md`](docs/cross-agent-implementation-plan.md)。
 
-## 安装
+macOS 桌面像素小宠物：悬浮在窗口之上，平时自己溜达、眨眼、打瞌睡；AI agent 通过 MCP 驱动宠物；跨用户协作时 **Agent → MCP → 桌宠 → Go 中转服务器**，由好友的 Agent 接手任务并把结果送回落地。
+
+## 仓库结构
+
+```
+app/     Electron 宠物端（TypeScript，独占 WS）+ MCP server（只连本地宠物）
+server/  Go 中转服务器（WebSocket + 用户门户 API）
+web/     桌宠登录指引页（账号 API 仍由服务端提供给桌宠应用）
+```
+
+## 协作架构
+
+```
+Agent ──MCP stdio──▶ MCP server ──HTTP localhost + session token──▶ Electron 桌宠 ──WebSocket──▶ Go relay
+                                                              ▲
+好友同理：宠物收任务入队并冒泡 ── Agent 说「帮朋友一下」── MCP list/answer ──┘
+```
+
+- MCP **不直连**服务器；同一 `userId` 的 WS 由桌宠独占（避免双连踢线）。
+- Electron 启动时在 `~/.desktop-pet-port` 写入仅当前用户可读写的 JSON 发现信息（端口、PID、随机会话令牌）；MCP 会为每个 localhost 请求附上该令牌。不要手动共享或提交这个文件。
+- v1 任务异步持久化到 PostgreSQL，支持 ACK、lease、取消、过期、断线补拉和离线结果；旧问答工具保留兼容映射。
+
+## 快速开始
+
+### 1. 启动桌面宠物
+
+协作身份与中转地址配置在**宠物进程**（不是 MCP）上：
 
 ```bash
-# 公网包（发布后）
-npm install --global desktop-pet-app
+cd app
+npm install
+npm run dev
+```
+
+正式客户端默认连接 `https://deskpalai.com`，自动推导 WebSocket `wss://deskpalai.com/ws`、登录 API `https://deskpalai.com/api/*` 和更新检查 `https://deskpalai.com/api/updates/check`，普通用户无需配置任何地址。`DESKTOP_PET_HOST` 与旧的 `DESKTOP_PET_SERVER=ws://…/ws` 只保留给本地开发、测试或私有部署；本地服务使用 `DESKTOP_PET_HOST=http://127.0.0.1:8080 npm run dev`。`DESKTOP_PET_SKIN=robot-blue` 可启用蓝色协作机器人。右键桌宠，选择「登录账号」或「注册账号」会使用系统默认浏览器打开服务端网页；网页认证成功后通过 `desktop-pet://` 自动唤回桌宠，并绑定当前这只宠物。刷新令牌和设备签名/加密私钥会由 Electron `safeStorage` 保存到 macOS Keychain 支持的加密存储。`DESKTOP_PET_TOKEN` 仅保留为不落盘的开发覆盖。仅本机演示可在服务端设置 `DESKTOP_PET_ALLOW_INSECURE_WS=1`，不要在公网开启。
+
+宠物出现在桌面右下角。右键宠物打开菜单：
+
+- **切换形象**：Codex 小宠 / Claude 小宠 / 我的世界小宠 / Professor Hoot / 橘猫 / 小狗 / 小鸟 / 狮子 / 老虎 / 蓝鲸 / 企鹅
+- **登录账号 / 注册账号**：用系统默认浏览器完成认证，随后自动回到桌宠并绑定当前桌宠
+- **复制 MCP 配置**：生成并复制当前 Agent 可直接粘贴的 MCP 注册 JSON（多 profile 联调时自动带上 `DESKTOP_PET_PORT_FILE`）
+- **送走这只宠物 / 退出**
 
-# 或本地 tgz
-npm install --global ./desktop-pet-app-0.1.1.tgz
+拖拽宠物时它会挣扎，落地会弹跳。
+
+### 2. 接入 agent（MCP）
+
+先构建 MCP server：
+
+```bash
+cd app
+npm run build        # 产物在 out/mcp-server/index.js
 ```
 
-国内网络若拉不到 Electron 二进制，加镜像：
+在 agent 的 MCP 配置中注册（以 CodeBuddy / Claude Code 为例）。MCP 只连本地宠物，**无需**再配 `DESKTOP_PET_SERVER`：
+
+```json
+{
+  "mcpServers": {
+    "desktop-pet": {
+      "command": "node",
+      "args": ["/绝对路径/desktop-pet/app/out/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+**可用工具**
+
+| 工具 | 何时用 | 作用 |
+| --- | --- | --- |
+| `set_pet_state` | 本地表演 | idle / walk / sleep / excited |
+| `show_bubble` | 本地表演 | 头顶冒气泡 |
+| `pet_react` | 本地表演 | 情绪反应 + 吐槽 |
+| `ask_remote_pet` | 「让朋友帮忙 / 问问某某」 | 派发任务（title/question/context/tools），阻塞等结果并要求落地 |
+| `wait_for_remote_task` | 「开始桌宠值班 / 等待朋友任务」 | 接收方 Agent 持续长轮询；完成并回传一项任务后必须继续等待，直到用户明确停止 |
+| `get_pending_questions` | 「帮我朋友一下」 | 列出待办任务与上下文、建议工具 |
+| `answer_question` | 做完好友任务后 | 回传结果（`resultKind`: text/code/patch/markdown/files） |
+| `delegate_task` / `get_task` / `wait_task_result` | v1 异步任务 | 创建、查询并等待持久化任务 |
+| `request_task_context` / `supply_task_context` | 缺少资料 | 在同一任务内补充最小必要上下文 |
+| `submit_task_result` / `cancel_task` / `list_remote_tasks` | v1 生命周期 | 回传结构化结果、取消和筛选任务 |
+| `prepare_task_workspace` / `submit_task_workspace_result` | v1 代码执行 | B 在独立 Git worktree 修改；工具自动审计范围并生成 patch |
+| `upload_task_artifact` / `download_task_artifact` | 大文件 fallback | 端到端加密 relay artifact；下载后校验并安全写入新文件 |
+| `validate_task_result` | 应用结果前 | 校验路径、哈希、大小、patch 基线和符号链接 |
+| `apply_task_patch` | 应用代码结果 | A 校验基线、可写范围、本地冲突及 `git apply --check` 后检查或应用 |
+
+宠物未启动时工具会返回明确错误。提问方默认最长等待约 5 分钟。
+
+### 3. 启动中转服务器与用户门户
+
+先构建门户前端，再启动 Go 服务（同时提供 WebSocket、REST API，并可托管静态页）：
 
 ```bash
-ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install --global ./desktop-pet-app-0.1.1.tgz
+cd web
+npm install
+npm run build
+
+cd ../server
+go run ./cmd/server -config config.yaml
 ```
 
-安装后直接启动：
+本地启动配置已提供在 `server/config.yaml`，其中包含监听地址、门户目录、数据库 DSN、开发 JWT 和实时通信参数。生产环境从 `server/config.example.yaml` 复制后替换实际值，并用 `-config /etc/desktop-pet/config.yaml` 启动。优先级为默认值 < 配置文件 < 环境变量 < 命令行 flag；环境变量可用于覆盖数据库密码、JWT 或 TLS 证书路径。
+
+直接打开网页会显示桌宠登录指引；由桌宠打开的网页会显示登录/注册表单，并在完成后自动回传桌宠。开发联调时可分别起两端：`cd web && npm run dev`（默认 `http://127.0.0.1:4001`，Vite 会把 `/api` 代理到 `:8080`）。
+
+用户、设备、任务、事件和加密 relay artifact 元数据存在 PostgreSQL；首次启动按 `server/internal/store/migrations/` 自动迁移。
+
+跨用户任务派发要求双方先在门户中确认好友关系，再由求助方从桌宠右键菜单发出求助（「请 TA 帮我」）、对方在「要我帮忙」菜单中明确同意；未同意时 MCP 返回 `HELP_NOT_ACCEPTED`。中转服务器会从桌宠 Bearer token 绑定身份，不信任客户端任意上报的 `userId`。
+
+**门户 API**
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `POST` | `/api/auth/register` | 注册 |
+| `POST` | `/api/auth/login` | 登录 |
+| `GET` | `/api/auth/me` | 当前用户（需 Bearer Token） |
+| `POST` | `/api/auth/password` | 修改当前账号密码 |
+| `GET` | `/api/users/search?q=` | 搜索用户 |
+| `GET` | `/api/friends` | 好友与待处理请求 |
+| `POST` | `/api/friends/request` | 发起好友请求 |
+| `POST` | `/api/friends/{id}/accept` | 同意 |
+| `POST` | `/api/friends/{id}/reject` | 拒绝 |
+| `DELETE` | `/api/friends/{id}` | 解除 / 撤销 |
+| `POST/GET/DELETE` | `/api/devices`、`/api/devices/{id}` | 创建设备、列表和撤销 |
+| `POST` | `/api/auth/device-token` | 用一次性刷新凭据换短期设备 WS token |
+| `GET` | `/api/p2p/ice-config` | STUN 与短时 TURN REST 凭据 |
+| `PUT/GET` | `/api/tasks/{taskId}/artifacts/{artifactId}` | 任务参与者上传/下载加密 relay blob |
+
+服务器分层结构：`cmd/`（入口装配）、`internal/config`（配置）、`internal/store`（PostgreSQL 用户与好友）、`internal/auth`（JWT）、`internal/api`（门户 REST）、`internal/hub`（领域路由 + 单测）、`internal/httpserver` + `internal/middleware`（HTTP 装配）、`internal/apperr`（自定义错误码）、`internal/response`（标准输出格式）、`internal/proto`（WS 协议）、`internal/observability`（slog JSON 日志 + Prometheus 指标）。
+
+**可观测性端点**
+
+| 端点 | 说明 |
+| --- | --- |
+| `GET /healthz` / `GET /readyz` | 存活/就绪探针，输出统一格式 `{"code":0,"message":"ok","data":{...}}` |
+| `GET /metrics` | Prometheus 指标：在线连接数、消息数、提问路由结果、HTTP 耗时 |
+
+WS 错误消息带稳定错误码（`{"type":"error","code":"USER_NOT_ONLINE",...}`），客户端可按 `code` 程序化分支。测试：`go test ./...`
+
+### 4. 双机任务协作联调
+
+两边都要：**先开 Go 服务器 → 再开桌宠（不同 `DESKTOP_PET_USER`）→ Agent 挂上 MCP**。
+
+1. 共用一台 `server`（`:8080`）
+2. A：`DESKTOP_PET_USER=alice npm run dev`；B：`DESKTOP_PET_USER=bob npm run dev`
+3. A 对 Agent 说：「让 bob 帮我看这个问题…」（可附上下文）  
+   → Agent 调 `ask_remote_pet`；A 的宠物离场出差
+4. B 的宠物冒泡「有任务了！」；B 对 Agent 说：「帮我朋友一下」  
+   → `get_pending_questions` → 本机完成 → `answer_question`
+5. A 的宠物归来 + 小鱼干；`ask_remote_pet` 返回结构化结果  
+   → A 的 Agent **审查后应用到工作区**（改代码 / 写文件等）
+
+本机同时运行多个桌宠进程时，每个进程必须使用独立的 `DESKTOP_PET_PROFILE`，否则 Electron 的单实例锁会让第二个进程退出。最小测试方式（每条命令使用一个终端）：
 
 ```bash
-desktop-pet
+cd app
+DESKTOP_PET_PROFILE=/tmp/desktop-pet-alice DESKTOP_PET_USER=alice DESKTOP_PET_SKIN=cat npm run dev
+DESKTOP_PET_PROFILE=/tmp/desktop-pet-bob   DESKTOP_PET_USER=bob   DESKTOP_PET_SKIN=dog npm run dev
 ```
 
-客户端默认连接 `https://deskpalai.com`，会自动推导 WebSocket、登录和更新接口。只有本地开发或私有部署时才需要设置 `DESKTOP_PET_HOST`。应用内更新仅接受 HTTPS 地址。
+如果使用已登录账号，分别在两个窗口里登录对应账号。多个 profile 同时登录时，桌宠会把系统错投的 `desktop-pet://` 登录回调自动转发到真正发起认证的实例；两边都需重启到此版本后再测试。如果只是测试 WS 在线状态，可在本地服务器开启 `DESKTOP_PET_ALLOW_INSECURE_WS=1`，再用不同的 `DESKTOP_PET_USER` 启动。测试结束后可删除这两个临时 profile 目录，里面只包含本地 Electron 配置和测试设备凭据。
+
+### 任意 MCP Agent 的“值班”模式
 
-首次启动后，在宠物右键菜单中选择“登录账号”或“注册账号”。
+桌宠不会绑定 Codex、Cursor、CodeBuddy 或其他某一家 Agent。接收方在任意支持 MCP tools 的 Agent 中说一次「开始桌宠值班」，Agent 调用 `wait_for_remote_task` 等待任务；拿到任务后，使用**它自身已有**的读文件、编辑、终端等能力完成，再回传结构化结果。值班是持续模式：回传每项任务后以及每次长轮询超时后，Agent 都应立即再次调用 `wait_for_remote_task`，直到用户明确要求停止。本机桌宠短暂重启或端口凭据轮换时，当前等待会在预算内自动重新发现连接；整轮仍未恢复也会返回可继续轮询的正常结果，而不是用工具错误终止 Agent 会话。
 
-## 更新
+设备开箱即用地声明协议词汇表中的能力标签（`filesystem.read,filesystem.write,shell,network,browser,document.create`），无需用户配置环境变量；MCP 客户端初始化后会自动上报宿主与协议信息。能力标签只用于任务匹配，不等于任意写权限：每项任务仍受 `writableScopes`、网络策略和审批模式限制。任务无法派发时，发起方会在 `task.created` 中收到 `warning`，接收方桌宠也会显示缺失能力及“安装或启用对应 Agent 工具后重新连接”的提示；如果 Agent 领取后才发现工具不可用，它会调用 `report_task_capability_gap` 将任务标记为失败，并立刻通知双方。
 
-通过 npm 安装的 macOS 版本可以直接使用应用内更新，首次更新会安装并切换到 `/Applications/Desktop Pet.app`。也可以继续使用 npm 更新：
+Git 代码任务采用隔离交付链路：B 先调用 `prepare_task_workspace`，只能在返回的 detached worktree 中修改和测试；`submit_task_workspace_result` 从该 worktree 自动生成与 `baseCommit` 绑定的 patch，并拒绝任何超出 `writableScopes` 的改动。A 的原工作区在此期间不变；A 收到结果后调用 `apply_task_patch`，只有 artifact 哈希、基线、范围、目标文件无本地冲突及 `git apply --check` 全部通过才会应用。`approvalMode=manual` 时还必须显式确认。已接受的定向帮助授权采用 24 小时滑动有效期，每次成功授权任务都会续期，避免活跃的长期值守会话在执行中突然失效。
+
+代码写入任务不能再用通用 `submit_task_result` 直接完成：MCP 与服务端都会在落终态前检查 `requireTests`、产物类型/大小以及代码 patch/file 是否存在，失败会返回具体原因且任务保持运行。超过本地消息阈值的自动 patch 会加密上传为 relay artifact，`apply_task_patch` 会自动下载、验哈希并继续相同的范围与 `git apply --check` 校验。这样不会因一次缺字段的诊断提交把任务锁成“已完成但没有文件”。
+
+每个宠物窗口都有常驻身份徽标：`本机主宠` 或 `好友 @用户名`。收到远端任务时，同一好友只保留一个来访形象；右键菜单会同时区分来访好友身份和本机登录账号，皮肤不再被当作账号身份。
+
+MCP 工具不能在 Agent 完全未启动、没有会话时强行唤醒它；这种无人值守体验需要额外的、按 Agent 产品实现的可选启动适配器。基础值班模式不依赖该适配器。
+
+如需显式启用首个无人值守试点，可设置 `DESKTOP_PET_RUNNER_ADAPTERS=1` 和 `DESKTOP_PET_RUNNER_WORKSPACE=/绝对工作区`。当前 adapter 使用已安装且自行管理凭据的 Codex CLI；未检测到 CLI 或运行失败时继续保留通用 MCP 值班模式。P2P 数据面默认开启，可设置 `DESKTOP_PET_P2P=0` 关闭；已确认好友之间的简单聊天优先建立 WebRTC 直连，建连失败时自动使用中转消息或加密 relay artifact，无需创建第二个业务任务。帮助邀请和离线提醒走服务器控制通道，以便对方下次上线仍能收到。
+
+## 开发
 
 ```bash
-npm update --global desktop-pet-app
+cd app
+npm run typecheck   # 类型检查
+npm run build       # 构建 Electron 三端 + MCP server
+
+cd server
+go build ./...      # 构建 Go 服务器
+```
+
+真实双 session 值班链路可在服务器和两只已登录桌宠运行时重复验证：
+
+```bash
+cd app
+ASKER_PORT_FILE=/tmp/desktop-pet-ceshi.port \
+DUTY_PORT_FILE=/tmp/desktop-pet-ceshi2.port \
+DUTY_USER=ceshi2 \
+npm run e2e:duty
 ```
 
-如果使用 macOS `.pkg` 或 Windows 安装包安装，桌宠会从服务器的更新接口发现、下载并安装新版本。
+脚本会启动相互独立的 A/B MCP stdio session，连续派发并完成三项带唯一校验码的任务，验证 B 在 A 派发前已进入长轮询、A 能显示结构化结果，以及同一个 B MCP 进程在多次回传后仍保持可用。测试脚本结束是显式停止边界。
+
+`npm run e2e:codebuddy:git` 用真实 CodeBuddy 驻守会话验证隔离 worktree 修改、测试、patch 回传和 A 端安全应用；紧接着运行 `npm run e2e:codebuddy:context` 可验证下一轮无需重新读取文件也能使用同一会话的上一轮上下文。
+
+## 发布 npm 包与应用更新
 
-## 发布者命令
+当前 Electron 客户端可发布为 npm 包。先在 npmjs.com 创建账号并执行一次 `npm login`，然后：
 
 ```bash
+cd app
+npm install
 npm run typecheck
 npm test
-npm run pack:check
 npm publish
 ```
 
-macOS 原生安装包：
+默认包名为 `desktop-pet-app`。发布前请先在 npm Registry 确认该名称归你所有；若需改为你的 scope（例如 `@你的账号/desktop-pet`），先修改 `app/package.json` 的 `name`，用户安装与更新命令也使用这个新名称。
+
+用户使用 npm 安装和更新：
 
 ```bash
+npm install --global desktop-pet-app
+desktop-pet
+npm update --global desktop-pet-app
+```
+
+npm 包用于开发者/命令行分发；桌宠内置“请求下载 → 安装并重启”使用平台原生安装包。在 macOS 上，两种分发方式共享 `~/Library/Application Support/Desktop Pet` 中的账号、缓存和单实例状态，但程序文件仍分别位于 npm 全局目录与 `/Applications/Desktop Pet.app`。`desktop-pet` 会校验原生 bundle 身份并比较两边版本，始终启动版本较高的一份，同版本优先启动原生应用；因此 npm 更新和应用内更新可以交替使用，不会切回旧版本。旧版 npm 数据目录会在首次启动时原子迁移。
+
+macOS 构建 `.pkg`：
+
+```bash
+cd app
 npm run package:mac
 ```
 
-发布前请为正式包配置 Apple Developer 签名和公证凭据。
+构建产物位于 `app/release.noindex/`。PKG 固定安装到 `/Applications` 且禁止重定位，更新 helper 会在重启前再次核对固定路径中的 bundle ID 与目标版本。正式发给用户前必须配置 Apple Developer 签名与公证，并通过 `DESKTOP_PET_UPDATE_PUBLIC_KEYS_JSON` 内嵌 manifest 验签公钥。
+
+生产更新由独立 `update-service` 负责：PostgreSQL 保存版本控制面和审计记录，安装包位于对象存储/CDN，Electron 校验 Ed25519 manifest 签名、文件大小和 SHA-256。它支持多渠道、多平台、确定性灰度、强更、暂停和回滚。发布新版本只需上传安装包并运行 `server/cmd/releasectl`，不再修改 Helm/Dockerfile，也不再重启 relay。完整的密钥初始化、部署和日常发布命令见 [企业级桌面应用更新系统](docs/in-app-update-design.md)。relay 原有配置文件方式仅作为私有部署兼容层保留。
+
+## 新增皮肤
+
+在 `app/src/renderer/skins/` 下新增字符皮肤或高分辨率精灵皮肤并在注册表登记。精灵皮肤可参考 `robot-blue.ts`：支持透明 PNG/WebP、平滑缩放、自适应窗口、气泡/地面/特效锚点，以及 working/success/failed 协作状态。

package/package.json

@@ -1,14 +1,8 @@
 {
   "name": "desktop-pet-app",
-  "version": "0.3.4",
+  "version": "0.3.13",
   "description": "AI desktop pet with MCP support and a self-hosted relay server",
   "license": "MIT",
-  "keywords": [
-    "desktop-pet",
-    "electron",
-    "mcp",
-    "ai-agent"
-  ],
   "engines": {
     "node": ">=20"
   },
@@ -23,53 +17,6 @@
     "bin",
     "out"
   ],
-  "scripts": {
-    "dev": "electron-vite dev",
-    "build": "electron-vite build && npm run build:mcp",
-    "build:mcp": "esbuild src/mcp-server/index.ts --bundle --platform=node --format=esm --packages=external --outfile=out/mcp-server/index.js && node -e \"require('fs').writeFileSync('out/mcp-server/package.json', JSON.stringify({ type: 'module' }))\"",
-    "e2e:duty": "node scripts/e2e-duty-sessions.mjs",
-    "e2e:codebuddy:git": "node scripts/e2e-codebuddy-git-task.mjs",
-    "e2e:codebuddy:context": "node scripts/e2e-codebuddy-context-round.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "package:mac": "npm run build && electron-builder --mac pkg --publish never",
-    "pack:check": "npm pack --dry-run",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm test && npm run pack:check"
-  },
-  "build": {
-    "appId": "com.xinshu.desktoppet",
-    "productName": "Desktop Pet",
-    "directories": {
-      "output": "release"
-    },
-    "files": [
-      "out/**",
-      "bin/**",
-      "package.json"
-    ],
-    "pkg": {
-      "installLocation": "/Applications",
-      "isRelocatable": false,
-      "isVersionChecked": true
-    },
-    "mac": {
-      "category": "public.app-category.utilities",
-      "target": [
-        "pkg"
-      ]
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/ws": "^8.18.1",
-    "electron": "^33.2.0",
-    "electron-builder": "^26.15.3",
-    "electron-vite": "^2.3.0",
-    "typescript": "^5.6.3",
-    "vite": "^5.4.8",
-    "vitest": "^3.2.7"
-  },
   "peerDependencies": {
     "electron": "^33.2.0"
   },
@@ -78,4 +25,4 @@
     "ws": "^8.21.3",
     "zod": "^4.5.4"
   }
-}
+}

package/bin/cli.js

@@ -1,173 +0,0 @@
-#!/usr/bin/env node
-
-const { execFileSync, spawn } = require('node:child_process')
-const fs = require('node:fs')
-const os = require('node:os')
-const path = require('node:path')
-
-const manifest = require('../package.json')
-
-const MAC_APP_PATH = '/Applications/Desktop Pet.app'
-const MAC_BUNDLE_ID = 'com.xinshu.desktoppet'
-const TAKEOVER_TIMEOUT_MS = 5_000
-
-function parseVersion(value) {
-  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value)
-  if (!match) return undefined
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4]
-  }
-}
-
-function compareVersions(a, b) {
-  const left = parseVersion(a)
-  const right = parseVersion(b)
-  if (!left || !right) throw new Error(`无效版本号：${!left ? a : b}`)
-  for (const key of ['major', 'minor', 'patch']) {
-    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1
-  }
-  if (!left.prerelease && right.prerelease) return 1
-  if (left.prerelease && !right.prerelease) return -1
-  if (!left.prerelease || !right.prerelease) return 0
-  return left.prerelease.localeCompare(right.prerelease, undefined, { numeric: true })
-}
-
-function selectLaunchTarget(npmVersion, nativeApp, forceNpm = false) {
-  if (!forceNpm && nativeApp && compareVersions(nativeApp.version, npmVersion) >= 0) {
-    return { kind: 'native', version: nativeApp.version, appPath: nativeApp.appPath }
-  }
-  return { kind: 'npm', version: npmVersion }
-}
-
-function readPlistValue(plistPath, key) {
-  return execFileSync('/usr/libexec/PlistBuddy', ['-c', `Print :${key}`, plistPath], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'ignore']
-  }).trim()
-}
-
-function installedMacApp() {
-  const plistPath = path.join(MAC_APP_PATH, 'Contents', 'Info.plist')
-  const executablePath = path.join(MAC_APP_PATH, 'Contents', 'MacOS', 'Desktop Pet')
-  try {
-    if (!fs.existsSync(executablePath)) return undefined
-    if (readPlistValue(plistPath, 'CFBundleIdentifier') !== MAC_BUNDLE_ID) return undefined
-    const version = readPlistValue(plistPath, 'CFBundleShortVersionString')
-    if (!parseVersion(version)) return undefined
-    return { version, appPath: MAC_APP_PATH }
-  } catch {
-    return undefined
-  }
-}
-
-function runningDesktopPet() {
-  const endpointPath = process.env.DESKTOP_PET_PORT_FILE?.trim() || path.join(os.homedir(), '.desktop-pet-port')
-  try {
-    const endpoint = JSON.parse(fs.readFileSync(endpointPath, 'utf8'))
-    if (!Number.isSafeInteger(endpoint.pid) || endpoint.pid < 1) return undefined
-    process.kill(endpoint.pid, 0)
-    return {
-      pid: endpoint.pid,
-      version: typeof endpoint.appVersion === 'string' && parseVersion(endpoint.appVersion)
-        ? endpoint.appVersion
-        : undefined
-    }
-  } catch {
-    return undefined
-  }
-}
-
-function shouldReplaceRunningVersion(targetVersion, runningVersion) {
-  return runningVersion === undefined || compareVersions(targetVersion, runningVersion) > 0
-}
-
-function processIsDesktopPet(pid) {
-  if (process.platform === 'win32') return false
-  try {
-    const command = execFileSync('/bin/ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' })
-    return /desktop[- ]pet/i.test(command)
-  } catch {
-    return false
-  }
-}
-
-function processIsRunning(pid) {
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch {
-    return false
-  }
-}
-
-function stopOlderRuntime(targetVersion) {
-  const running = runningDesktopPet()
-  if (!running || !shouldReplaceRunningVersion(targetVersion, running.version) || !processIsDesktopPet(running.pid)) return
-
-  try {
-    process.kill(running.pid, 'SIGTERM')
-  } catch {
-    return
-  }
-
-  const deadline = Date.now() + TAKEOVER_TIMEOUT_MS
-  while (Date.now() < deadline && processIsRunning(running.pid)) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100)
-  }
-  if (processIsRunning(running.pid)) {
-    try {
-      process.kill(running.pid, 'SIGKILL')
-    } catch {}
-  }
-}
-
-function npmElectronPath() {
-  try {
-    return require('electron')
-  } catch (error) {
-    console.error('未找到 electron 包，请重新安装 desktop-pet-app。')
-    console.error('若在国内网络安装失败，可先设置镜像再重装：')
-    console.error('  ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install --global <包路径或包名>')
-    console.error(error instanceof Error ? error.message : String(error))
-    process.exit(1)
-  }
-}
-
-function launch() {
-  const appPath = path.join(__dirname, '..')
-  const forceNpm = Boolean(process.env.DESKTOP_PET_PROFILE?.trim()) || process.platform !== 'darwin'
-  const target = selectLaunchTarget(
-    manifest.version,
-    process.platform === 'darwin' ? installedMacApp() : undefined,
-    forceNpm
-  )
-  stopOlderRuntime(target.version)
-
-  let command
-  let args
-  let env = process.env
-  if (target.kind === 'native') {
-    command = '/usr/bin/open'
-    args = ['-n', target.appPath, '--args', ...process.argv.slice(2)]
-  } else {
-    command = npmElectronPath()
-    if (typeof command !== 'string' || !fs.existsSync(command)) {
-      console.error('electron 已安装但二进制缺失，请用镜像重装：')
-      console.error('  ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install --global --force <包路径或包名>')
-      process.exit(1)
-    }
-    args = [appPath, ...process.argv.slice(2)]
-    env = { ...process.env, DESKTOP_PET_NPM_DISTRIBUTION: '1' }
-  }
-
-  const child = spawn(command, args, { stdio: 'ignore', detached: true, env })
-  child.on('error', (error) => console.error(`Desktop Pet 启动失败：${error.message}`))
-  child.unref()
-}
-
-if (require.main === module) launch()
-
-module.exports = { compareVersions, selectLaunchTarget, shouldReplaceRunningVersion }