desktop-pet-app 0.3.13 → 0.3.24

package/README.md

@@ -1,245 +1,60 @@
-# Desktop Pet 桌面宠物
+# Desktop Pet
 
-完整的跨 Agent 协作目标架构、协议、P2P、任务状态机、安全与视觉实施清单见 [`docs/cross-agent-implementation-plan.md`](docs/cross-agent-implementation-plan.md)。
+一个可悬浮在桌面的 AI 宠物，支持账号登录、好友协作与 MCP。
 
-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
-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`）
-- **送走这只宠物 / 退出**
-
-拖拽宠物时它会挣扎，落地会弹跳。
-
-### 2. 接入 agent（MCP）
-
-先构建 MCP server：
-
-```bash
-cd app
-npm run build        # 产物在 out/mcp-server/index.js
-```
+# 公网包（发布后）
+npm install --global desktop-pet-app
 
-在 agent 的 MCP 配置中注册（以 CodeBuddy / Claude Code 为例）。MCP 只连本地宠物，**无需**再配 `DESKTOP_PET_SERVER`：
-
-```json
-{
-  "mcpServers": {
-    "desktop-pet": {
-      "command": "node",
-      "args": ["/绝对路径/desktop-pet/app/out/mcp-server/index.js"]
-    }
-  }
-}
+# 或本地 tgz
+npm install --global ./desktop-pet-app-0.1.1.tgz
 ```
 
-**可用工具**
-
-| 工具 | 何时用 | 作用 |
-| --- | --- | --- |
-| `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，并可托管静态页）：
+国内网络若拉不到 Electron 二进制，加镜像：
 
 ```bash
-cd web
-npm install
-npm run build
-
-cd ../server
-go run ./cmd/server -config config.yaml
+ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install --global ./desktop-pet-app-0.1.1.tgz
 ```
 
-本地启动配置已提供在 `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
-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
+desktop-pet
 ```
 
-如果使用已登录账号，分别在两个窗口里登录对应账号。多个 profile 同时登录时，桌宠会把系统错投的 `desktop-pet://` 登录回调自动转发到真正发起认证的实例；两边都需重启到此版本后再测试。如果只是测试 WS 在线状态，可在本地服务器开启 `DESKTOP_PET_ALLOW_INSECURE_WS=1`，再用不同的 `DESKTOP_PET_USER` 启动。测试结束后可删除这两个临时 profile 目录，里面只包含本地 Electron 配置和测试设备凭据。
+客户端默认连接 `https://api.xinbit.top/desktop-pet`（登录/注册门户仍由 `https://deskpalai.com` 提供），会自动推导 WebSocket、登录和更新接口。只有本地开发或私有部署时才需要设置 `DESKTOP_PET_HOST`（可含路径前缀）。应用内更新仅接受 HTTPS 地址。
 
-### 任意 MCP Agent 的“值班”模式
+打包发布时可通过环境变量覆盖官方地址（构建期内联，见 `src/shared/service-addresses.ts`）：`DESKTOP_PET_SERVER_ROOT`（服务根）、`DESKTOP_PET_PORTAL_ORIGIN`（门户）、`DESKTOP_PET_LEGACY_HOSTS`（需无缝迁移的旧服务器 hostname，逗号分隔）。
 
-桌宠不会绑定 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` 将任务标记为失败，并立刻通知双方。
+## 更新
 
-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，无需创建第二个业务任务。帮助邀请和离线提醒走服务器控制通道，以便对方下次上线仍能收到。
-
-## 开发
+通过 npm 安装的 macOS 版本可以直接使用应用内更新，首次更新会安装并切换到 `/Applications/Desktop Pet.app`。也可以继续使用 npm 更新：
 
 ```bash
-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
+npm update --global desktop-pet-app
 ```
 
-脚本会启动相互独立的 A/B MCP stdio session，连续派发并完成三项带唯一校验码的任务，验证 B 在 A 派发前已进入长轮询、A 能显示结构化结果，以及同一个 B MCP 进程在多次回传后仍保持可用。测试脚本结束是显式停止边界。
-
-`npm run e2e:codebuddy:git` 用真实 CodeBuddy 驻守会话验证隔离 worktree 修改、测试、patch 回传和 A 端安全应用；紧接着运行 `npm run e2e:codebuddy:context` 可验证下一轮无需重新读取文件也能使用同一会话的上一轮上下文。
+`desktop-pet` 会比较 npm 包与 `/Applications/Desktop Pet.app` 的版本并启动较新者，同版本优先原生应用。两者共享 `~/Library/Application Support/Desktop Pet` 中的用户数据；该目录不是程序安装目录。npm 不会绕过系统安装器直接写入 `/Applications`。
 
-## 发布 npm 包与应用更新
+如果使用 macOS `.pkg` 或 Windows 安装包安装，桌宠会从服务器的更新接口发现、下载并安装新版本。
 
-当前 Electron 客户端可发布为 npm 包。先在 npmjs.com 创建账号并执行一次 `npm login`，然后：
+## 发布者命令
 
 ```bash
-cd app
-npm install
 npm run typecheck
 npm test
+npm run pack:check
 npm publish
 ```
 
-默认包名为 `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`：
+macOS 原生安装包：
 
 ```bash
-cd app
 npm run package:mac
 ```
 
-构建产物位于 `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 协作状态。
+发布前请为正式包配置 Apple Developer 签名和公证凭据。

package/bin/cli.js

@@ -0,0 +1,173 @@
+#!/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 }