156 lines
10 KiB
Markdown
156 lines
10 KiB
Markdown
# 客户端依赖（服务）安装、升级与启动流程
|
||
|
||
> 本文档梳理 Electron 客户端应用**依赖安装**（初始化 / 手动）、**升级**、**启动时同步**以及**安装或升级后的服务停止与重启**全流程，便于维护与排查。
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
- **必需依赖**：由 `SETUP_REQUIRED_DEPENDENCIES` 定义，不随应用打包，需在「初始化」或「依赖 Tab」中安装到 `~/.qimingclaw/`（或项目配置的数据目录）下的 `node_modules`。
|
||
- **版本判定**：以**当前已真实安装的版本**为准；用户可在依赖 Tab 下手动升级，已安装版本 ≥ 配置的 `installVersion` 即视为就绪，**不降级**。
|
||
- **安装/升级后**：在主界面下（含重装流程和依赖 Tab），依赖安装或升级成功后会调用 `services.restartAll()` 重启所有服务，使新二进制生效。初始化向导中的依赖安装不触发重启（此时服务尚未启动，向导完成后由自动重连流程启动服务）。
|
||
|
||
---
|
||
|
||
## 2. 必需依赖列表（SETUP_REQUIRED_DEPENDENCIES）
|
||
|
||
| 名称 | 显示名 | 类型 | 说明 | 固定版本(installVersion) |
|
||
|------|--------|------|------|--------------------------|
|
||
| uv | uv | bundled | Python 包管理器（已集成） | minVersion: 0.5.0 |
|
||
| pnpm | pnpm 包管理器 | npm-local | Node 包管理器 | 10.30.3 |
|
||
| qiming-file-server | 文件服务 | npm-local | 工作目录文件远程管理 | 1.2.2 |
|
||
| qimingcode | Agent 引擎 | bundled | 应用内集成 Agent 执行引擎 | 1.1.68 |
|
||
| qiming-mcp-stdio-proxy | MCP 服务 | npm-local | MCP 协议聚合代理 | 1.4.6 |
|
||
| claude-code-acp-ts | ACP 协议 | npm-local | 引擎统一适配 | 0.16.1 |
|
||
|
||
- **配置位置**：`src/main/services/system/dependencies.ts` 中的 `SETUP_REQUIRED_DEPENDENCIES`。
|
||
- **检测**：`checkAllDependencies()` 仅检查上述列表，返回每项状态：`installed` | `bundled` | `missing` | `outdated` | `error`。
|
||
|
||
---
|
||
|
||
## 3. 依赖状态与版本判定
|
||
|
||
- **installed / bundled**：已就绪，无需操作。
|
||
- **missing**：未安装，需要安装。
|
||
- **outdated**：已安装但当前版本 < 配置的 `installVersion`，可升级；**不强制**进入全屏依赖安装（用户可在依赖 Tab 自行升级）。
|
||
- **error**：检测或安装过程出错。
|
||
|
||
**版本比较约定**：
|
||
|
||
- 以**当前已安装版本**与配置的 `installVersion` 比较。
|
||
- 仅当「未安装」或「已装版本 < installVersion」时标记为需安装/升级；已装 ≥ 目标则视为已就绪，不降级。
|
||
- 实现见 `dependencies.ts` 中 `checkAllDependencies` 的 `compareVersions(installed, target)` 逻辑。
|
||
|
||
---
|
||
|
||
## 4. 初始化安装（首次 / 向导内）
|
||
|
||
### 4.1 入口与流程
|
||
|
||
- **入口**：应用启动后若 `setupService.isSetupCompleted()` 为 false，渲染**初始化向导**（`SetupWizard`）。
|
||
- **向导阶段 1**：依赖检测与安装（`SetupDependencies`）。
|
||
- 调用 `dependencies.checkAll()`，若有任一项非 `installed`/`bundled`（包括 `outdated`），则进入依赖安装 UI。
|
||
- **注意**：向导内 `outdated` 也会触发安装阶段（确保首次设置时所有依赖都是最新），而主界面下 `outdated` 不触发全屏重装（见 section 5.1）。
|
||
- 先检查系统依赖（如 uv）；若缺失则提示并阻塞。
|
||
- 对 npm-local 等可安装项自动或手动安装，全部就绪后进入下一步。
|
||
- **完成回调**：`SetupDependencies` 的 `onComplete` 由 `SetupWizard.handleDepsComplete` 处理：置 `dependenciesReady = true`，然后进入「基础设置」步骤或快捷初始化（Quick Init）。
|
||
|
||
### 4.2 与 Quick Init 的关系
|
||
|
||
- 若依赖已全部就绪且存在快捷初始化配置，会优先走 Quick Init，不再重复安装依赖。
|
||
- 依赖步骤**不可跳过**：必须先完成依赖检测/安装，再进入基础设置与登录。
|
||
|
||
---
|
||
|
||
## 5. 主界面下「必需依赖缺失」触发的重装流程
|
||
|
||
### 5.1 触发条件
|
||
|
||
- 用户已进入主界面（`isSetupComplete === true`）。
|
||
- 应用在进入主界面后执行一次 `dependencies.checkAll()`。
|
||
- **仅当**存在状态为 `missing` 或 `error` 的必需依赖时，置 `needsRequiredDepsReinstall = true`。
|
||
- **outdated 不触发**：已安装但版本低于配置时，不强制全屏依赖安装，用户可在依赖 Tab 自行升级。
|
||
|
||
### 5.2 流程
|
||
|
||
1. 渲染层：`needsRequiredDepsReinstall === true` 时，全屏展示 `SetupDependencies`（与向导内为同一组件）。
|
||
2. 用户完成依赖安装后，`onComplete` 被调用：
|
||
- 先 `setNeedsRequiredDepsReinstall(false)`，回到主界面。
|
||
- 再调用 `restartAllServices()`（内部先停后启），使新依赖生效。
|
||
3. 不改变 `isSetupComplete`，不重新走向导的账号登录等步骤。
|
||
|
||
### 5.3 涉及代码
|
||
|
||
- `App.tsx`：`needsRequiredDepsReinstall` 状态、`checkRequiredDeps` 的 `useEffect`、全屏 `SetupDependencies` 的 `onComplete` 与 `restartAllServices()`。
|
||
|
||
---
|
||
|
||
## 6. 依赖 Tab 下手动安装 / 升级
|
||
|
||
### 6.1 入口
|
||
|
||
- 主界面 → 依赖 Tab（`DependenciesPage`）。
|
||
- 可对单项点击「安装」/「升级」，或使用「全部安装」/「全部升级」/「安装并升级」。
|
||
|
||
### 6.2 行为
|
||
|
||
- **单项**：调用 `dependencies.installPackage(name, options?)`，可选 `options.version`（如 `installVersion`）；成功后调用 `restartServicesAfterDepChange()`。
|
||
- **批量**：遍历需安装/升级的依赖依次安装；若有任意一项成功，则调用 `restartServicesAfterDepChange()`。
|
||
- **restartServicesAfterDepChange**：内部调用 `services.restartAll()`（主进程内先停后启），并提示「正在重启服务…」「服务已重启」或失败提示。
|
||
|
||
### 6.3 版本与文案
|
||
|
||
- 以当前已安装版本为准；`outdated` 时按钮为「升级」，否则为「安装」。
|
||
- 批量时按缺失/过期组合显示「全部安装」「全部升级」或「安装并升级」；完成提示区分「依赖安装完成」「依赖升级完成」「依赖安装并升级完成」。
|
||
|
||
---
|
||
|
||
## 7. 应用启动时的依赖同步（syncInitDependencies）
|
||
|
||
- **目的**：应用升级后，若配置中的 `installVersion` 或应用版本发生变化，将依赖同步到新版本。
|
||
- **触发**：主进程启动任务（`bootstrap/startup.ts`）中，通过 `getInitDepsState()` 读取上次同步状态，与当前 `app.getVersion()` 及各包 `installVersion` 逐一比较。满足以下任一条件即触发 `syncInitDependencies()`：
|
||
- 应用版本（`appVersion`）与上次记录不同（含首次无记录）；
|
||
- 任一包的 `installVersion` 与上次记录的对应值不同（含上次无该包记录）。
|
||
- **行为**：对 `SETUP_REQUIRED_DEPENDENCIES` 中带 `installVersion` 的 npm-local 包，若未安装或已装版本低于配置，则安装到指定版本，并写回 `~/.qimingclaw/.init-deps-state.json`（或当前数据目录下的同名文件）。
|
||
- **不降级**：已安装版本 ≥ `installVersion` 的包不会被执行安装，避免覆盖用户手动升级的更高版本。
|
||
|
||
---
|
||
|
||
## 8. 安装或升级后的服务停止与重启
|
||
|
||
以下任一场景在「依赖安装或升级成功」后，都会执行**先停止再重启**所有相关服务，使新二进制生效：
|
||
|
||
| 场景 | 位置 | 行为 |
|
||
|------|------|------|
|
||
| 主界面重装依赖完成 | `App.tsx` 全屏 `SetupDependencies` 的 `onComplete` | `setNeedsRequiredDepsReinstall(false)` 后调用 `restartAllServices()`（即 `services.restartAll()`） |
|
||
| 依赖 Tab 单项安装/升级成功 | `DependenciesPage.handleInstallSingleDep` | 调用 `restartServicesAfterDepChange()` → `services.restartAll()` |
|
||
| 依赖 Tab 批量安装/升级且至少成功一项 | `DependenciesPage.handleInstallAllDeps` | 同上 `restartServicesAfterDepChange()` |
|
||
|
||
- **restartAll**：主进程 `processHandlers.ts` 中 `services:restartAll` IPC handler 的实现会先停止 Agent、ComputerServer、FileServer、Lanproxy（**不停 MCP**），再按顺序启动 MCP → Agent → ComputerServer → FileServer → Lanproxy。MCP 在 restartAll 中只做 start/verify，不先停。
|
||
- **stopAll**：主进程 `processHandlers.ts` 中 `services:stopAll` IPC handler 会停止所有服务**包括 MCP**。
|
||
- **用户登出**：渲染进程 `ClientPage.handleLogout` 在停止 agent/fileServer/lanproxy/mcp 后，会单独调用 `computerServer.stop()`，避免登出后进程残留导致端口冲突；详见 [认证机制与 SavedKey 生命周期](./auth-savedkey-lifecycle.md#退出登录)。
|
||
- **serviceManager.ts**：`serviceManager.restartAllServices()` 是另一套实现（供 `main.ts` 内部和 Tray 菜单使用），行为与 IPC `restartAll` 略有不同：会先停 MCP 再启动，且不包含 ComputerServer。渲染进程通过 `window.electronAPI.services.restartAll()` 调用的是 `processHandlers.ts` 中的 IPC handler 版本。
|
||
- **无需单独 stopAll**：`restartAll` 内部已包含停止逻辑（Agent / ComputerServer / FileServer / Lanproxy）；若需停止所有服务（含 MCP）且不重启，可调用 `services.stopAll()`。
|
||
|
||
---
|
||
|
||
## 9. 涉及文件与入口汇总
|
||
|
||
| 类型 | 路径 / 说明 |
|
||
|------|------------------|
|
||
| 依赖配置与检测 | `src/main/services/system/dependencies.ts`：`SETUP_REQUIRED_DEPENDENCIES`、`checkAllDependencies`、`installNpmPackage`、`installMissingDependencies`、`syncInitDependencies`、`compareVersions` |
|
||
| 启动同步 | `src/main/bootstrap/startup.ts`：启动后根据 `getInitDepsState` 与版本比较调用 `syncInitDependencies` |
|
||
| IPC | `src/main/ipc/dependencyHandlers.ts`：`dependencies:checkAll`、`dependencies:installPackage` 等；`processHandlers.ts`：`services:stopAll`、`services:restartAll` |
|
||
| 服务管理器 | `src/main/window/serviceManager.ts`：`restartAllServices`、`stopAllServices`（供 main.ts / Tray 使用，行为与 IPC handler 略有不同，见 section 8） |
|
||
| 初始化向导 | `src/renderer/components/setup/SetupWizard.tsx`、`SetupDependencies.tsx`：向导内依赖步骤与完成回调 |
|
||
| 主界面重装 | `src/renderer/App.tsx`：`needsRequiredDepsReinstall`、全屏 `SetupDependencies`、`checkRequiredDeps`、`restartAllServices` |
|
||
| 依赖 Tab | `src/renderer/components/pages/DependenciesPage.tsx`：单项/批量安装与 `restartServicesAfterDepChange` |
|
||
| 持久化 | `~/.qimingclaw/.init-deps-state.json`（或当前数据目录）：应用版本与各包上次同步版本，读写在 `dependencies.ts` 的 `getInitDepsState` / `setInitDepsState` |
|
||
|
||
---
|
||
|
||
## 10. 相关文档
|
||
|
||
- [依赖版本固定与安装/升级行为](./dependency-version-pinning.md) — installVersion、同步、文案与不降级约定。
|
||
- [Quick Init](./QUICK-INIT.md) — 快捷初始化与依赖步骤不可跳过的约定。
|