# 桌面客户端架构
**本文引用的文件**
- [ai-electron/package.json](file://ai-electron/package.json)
- [ai-electron/electron/main.ts](file://ai-electron/electron/main.ts)
- [ai-electron/electron/preload/index.ts](file://ai-electron/electron/preload/index.ts)
- [ai-electron/electron/preload/bridge.ts](file://ai-electron/electron/preload/bridge.ts)
- [ai-electron/electron/preload/lifecycle.ts](file://ai-electron/electron/preload/lifecycle.ts)
- [ai-electron/electron/config/windowOptions.ts](file://ai-electron/electron/config/windowOptions.ts)
- [ai-electron/electron/config/config.default.ts](file://ai-electron/electron/config/config.default.ts)
- [ai-electron/electron/controller/windowCtl.ts](file://ai-electron/electron/controller/windowCtl.ts)
- [ai-electron/frontend/src/main.ts](file://ai-electron/frontend/src/main.ts)
- [ai-electron/frontend/src/App.vue](file://ai-electron/frontend/src/App.vue)
- [ai-electron/frontend/vite.config.ts](file://ai-electron/frontend/vite.config.ts)
- [ai-electron/frontend/src/core/settings/serverSetting.ts](file://ai-electron/frontend/src/core/settings/serverSetting.ts)
- [ai-electron/frontend/src/core/utils/map/offlineMap.ts](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts)
- [ai-electron/frontend/src/ai/api/sse.ts](file://ai-electron/frontend/src/ai/api/sse.ts)
- [ai-electron/frontend/src/ai/store/chatStream.ts](file://ai-electron/frontend/src/ai/store/chatStream.ts)
- [ai-electron/frontend/src/ai/api/chatApi.ts](file://ai-electron/frontend/src/ai/api/chatApi.ts)
- [ai-electron/cmd/builder.json](file://ai-electron/cmd/builder.json)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [关键组件详解](#关键组件详解)
6. [依赖关系分析](#依赖关系分析)
7. [性能与体验特性](#性能与体验特性)
8. [常见问题排查](#常见问题排查)
9. [从启动到发起 Agent 请求的最小路径](#从启动到发起-agent-请求的最小路径)
10. [结论](#结论)
## 简介
本项目是一个基于 Electron + ee-core 的桌面客户端,前端工程使用 Vite + Vue 3 + Ant Design Vue + TypeScript。主进程通过 `ee-core.ElectronEgg` 管理应用生命周期、窗口、托盘与安全服务;渲染进程负责主题、国际化、水印、授权、地图和 SSE Agent 对话。后端 `ai-server` 独立部署,客户端在运行时动态绑定其地址,并可选择加载本地 `china.pmtiles` 离线地图。
## 项目结构
桌面端代码主要位于 `ai-electron` 下,可划分为三层:
| 层级 | 目录 | 职责 |
|---|---|---|
| 主进程层 | `electron/main.ts`、`electron/preload/*`、`electron/config/*`、`electron/controller/*`、`electron/service/*` | 应用生命周期、窗口控制、系统托盘、安全策略、IPC 控制器 |
| 渲染进程层 | `frontend/src/*` | Vue 3 应用、路由、状态、UI、SSE Agent、离线地图、设置 |
| 构建与打包层 | `package.json`、`cmd/builder.json`、`frontend/vite.config.ts` | 开发脚本、Vite 配置、Electron Builder 产物 |
```mermaid
graph TB
subgraph "主进程"
M["main.ts
注册生命周期与 preload"]
L["preload/lifecycle.ts
ready / windowReady / beforeClose"]
P["preload/index.ts
创建托盘与安全服务"]
C["controller/windowCtl.ts
跨窗口 IPC"]
W["config/windowOptions.ts
webPreferences"]
D["config/config.default.ts
默认窗口与静态资源路径"]
end
subgraph "渲染进程"
FMain["frontend/src/main.ts
启动引导、健康检查、路由守卫"]
AppVue["App.vue
主题/国际化/水印/授权单元"]
ServerCfg["serverSetting.ts
动态绑定 ai-server 地址"]
OfflineMap["offlineMap.ts
china.pmtiles 离线地图"]
ChatStore["chatStream.ts
会话与流式状态机"]
Sse["sse.ts
SSE 解析与 fetch 流读取"]
ChatApi["chatApi.ts
非流式聊天接口"]
end
M --> L
M --> P
M --> W
M --> D
M --> C
FMain --> AppVue
FMain --> ServerCfg
FMain --> ChatStore
ChatStore --> ChatApi
ChatStore --> Sse
AppVue --> ServerCfg
AppVue --> OfflineMap
```
**图示来源**
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
- [ai-electron/electron/config/windowOptions.ts:1-41](file://ai-electron/electron/config/windowOptions.ts#L1-L41)
- [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50)
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85)
- [ai-electron/frontend/src/core/settings/serverSetting.ts:1-200](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L1-L200)
- [ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/frontend/src/ai/store/chatStream.ts:1-200](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80)
**章节来源**
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/frontend/vite.config.ts:1-40](file://ai-electron/frontend/vite.config.ts#L1-L40)
## 核心组件
本节聚焦主进程与渲染进程的职责边界。
### 主进程入口与生命周期
`main.ts` 是 Electron 入口,使用 `ee-core.ElectronEgg` 创建应用实例,注册 `ready`、`electron-app-ready`、`window-ready`、`before-close` 生命周期钩子,并注册 `preload`。它不直接管理业务逻辑,而是把能力交给生命周期类和预加载模块。
关键点:
- 单例应用:`new ElectronEgg()` 后调用 `app.run()`。
- 生命周期由 `Lifecycle` 类实现,集中处理窗口居中、显示策略、二次启动激活等。
- `preload` 模块在窗口创建前执行,负责创建系统托盘和安全服务。
**章节来源**
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
### 预加载桥与 IPC 暴露
`preload/index.ts` 是框架级预加载入口,用于初始化托盘与安全服务;`preload/bridge.ts` 则在启用上下文隔离时通过 `contextBridge.exposeInMainWorld('electron', ...)` 向渲染进程暴露 `ipcRenderer`。当前窗口配置关闭了上下文隔离,因此渲染进程可直接访问 Node/Electron API,但 bridge 仍保留为扩展点。
安全模型要点:
- 默认 `contextIsolation: false`、`nodeIntegration: true`,便于现有渲染代码直接使用 Electron API。
- 若未来开启上下文隔离,应通过 `contextBridge` 暴露最小化 API,而不是直接把全部 Electron API 抛给渲染进程。
- 跨窗口状态同步通过主进程 `WindowCtl` 统一转发,避免渲染进程直接枚举所有窗口。
**章节来源**
- [ai-electron/electron/preload/bridge.ts:1-10](file://ai-electron/electron/preload/bridge.ts#L1-L10)
- [ai-electron/electron/config/windowOptions.ts:10-20](file://ai-electron/electron/config/windowOptions.ts#L10-L20)
- [ai-electron/electron/controller/windowCtl.ts:1-123](file://ai-electron/electron/controller/windowCtl.ts#L1-L123)
### 渲染进程启动引导
`frontend/src/main.ts` 是 Vue 应用的 bootstrap 入口,承担以下职责:
- 初始化全局组件、国际化、路由、Pinia store、错误处理。
- 判断是否缺少后端服务地址;若缺失则进入授权/服务地址页。
- 对未绑定地址的场景执行最多 10 次、每次约 3 秒的后端健康检查。
- 健康检查通过后执行授权校验与登录门禁。
- 智能工作台窗口与普通主窗口的行为分支。
```mermaid
flowchart TD
Start["渲染进程启动"] --> Init["初始化 Store、路由、国际化、全局组件"]
Init --> CheckServer{"是否已绑定 ai-server 地址?"}
CheckServer -->|否| GoAuth["跳转到授权/服务地址页"]
CheckServer -->|是| Probe["健康检查:最多 10 次 × 3 秒"]
Probe --> Ready{"后端就绪?"}
Ready -->|否| ShowReconnect["显示重连与服务地址操作"]
Ready -->|是| AuthCheck["校验授权与登录态"]
AuthCheck --> Route["计算最终路由并挂载 App"]
```
**图示来源**
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/main.ts:201-399](file://ai-electron/frontend/src/main.ts#L201-L399)
**章节来源**
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/main.ts:201-399](file://ai-electron/frontend/src/main.ts#L201-L399)
### App.vue:主题、国际化、水印与授权单元
`App.vue` 是根组件,负责:
- 通过 Ant Design Vue 的 `StyleProvider` 和 `ConfigProvider` 注入主题与语言。
- 使用 `useLocale` 获取中文语言包。
- 使用 `useRootSetting` 获取深色模式与主题色。
- 使用 `useWatermark` 根据授权单元设置页面水印。
- 首次挂载时尝试调用授权信息接口,将授权单元写入用户缓存并驱动水印。
注意:如果尚未绑定服务端地址,或 `/sys/info` 失败,会清空水印,避免展示过期或错误的授权单元。
**章节来源**
- [ai-electron/frontend/src/App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85)
## 架构总览
下图展示从 Electron 主进程到前端 AI Agent 请求的整体调用链。
```mermaid
sequenceDiagram
participant EE as "ElectronEgg"
participant Main as "main.ts"
participant Life as "lifecycle.ts"
participant Pre as "preload/index.ts"
participant Win as "BrowserWindow"
participant Vue as "frontend main.ts"
participant Api as "serverSetting.ts"
participant SSE as "sse.ts"
participant Stream as "chatStream.ts"
participant Server as "ai-server"
EE->>Main: 创建应用
Main->>Life: 注册 ready / electron-app-ready / window-ready / before-close
Main->>Pre: 注册 preload
Main->>EE: run()
EE->>Win: 创建主窗口
Pre->>Pre: 创建托盘与安全服务
Life->>Win: 设置窗口大小与显示时机
Vue->>Api: getApiOrigin()
Vue->>Vue: waitForBackendReady()
Vue->>Server: GET /js/a/sys/health
Server-->>Vue: 健康响应
Vue->>Vue: resolveStartupRoute()
Vue->>Stream: 初始化会话与消息状态
Stream->>SSE: streamChat(url, params, handlers)
SSE->>Server: POST 事件流请求
Server-->>SSE: text/event-stream
SSE-->>Stream: intent / thinking / tool_call / token / done / error
```
**图示来源**
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/core/settings/serverSetting.ts:1-200](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/frontend/src/ai/store/chatStream.ts:1-200](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L200)
## 关键组件详解
### 主进程生命周期与窗口行为
`Lifecycle` 类封装了四个关键阶段:
- `ready`:ee-core 应用已加载。
- `electronAppReady`:处理双击图标时恢复已打开窗口,优先拉回智能工作台窗口。
- `windowReady`:主窗口按屏幕工作区尺寸按比例居中,并根据配置延迟显示。
- `beforeClose`:应用关闭前的清理钩子。
窗口共享配置集中在 `sharedWebPreferences`,包含 `contextIsolation: false` 和 `nodeIntegration: true`,确保主窗口与智能工作台窗口行为一致。
**章节来源**
- [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73)
- [ai-electron/electron/config/windowOptions.ts:10-41](file://ai-electron/electron/config/windowOptions.ts#L10-L41)
- [ai-electron/electron/config/config.default.ts:10-35](file://ai-electron/electron/config/config.default.ts#L10-L35)
### 跨窗口 IPC 控制器
`windowCtl.ts` 提供统一的窗口管理 IPC:
- `openSmartWindow`:打开或聚焦智能工作台窗口。
- `closeSmartWindow`:关闭智能工作台窗口。
- `isSmartWindowOpen`:查询智能窗口是否打开。
- `focusMainWindow`:登录失效等场景下把主窗口拉到前台。
- `getWindowRole`:让渲染进程知道自己属于主窗口还是智能工作台。
- `syncState`:向除发送者外的所有窗口广播语义事件,通道名为 `app:state`。
该控制器返回 `{ success, data|message }`,失败时记录日志但不抛出到 Electron 层,便于渲染进程统一处理。
**章节来源**
- [ai-electron/electron/controller/windowCtl.ts:1-123](file://ai-electron/electron/controller/windowCtl.ts#L1-L123)
### 动态绑定 ai-server 地址
`serverSetting.ts` 是客户端与后端地址绑定的核心:
- 地址保存在原始 localStorage 键 `SERVER_BASE_URL__` 中,不参与 AES 快照,客户端升级后复用。
- 最近成功绑定的地址保存在 `SERVER_BASE_URL_HISTORY__`,最多保留 5 条。
- `normalizeServerOrigin` 只接受协议、主机和端口,拒绝携带 `/js`、`/a` 等路径。
- `getApiOrigin` 优先取运行时绑定地址,其次取构建期环境变量。
- `buildHealthCheckUrl` 构造 `/js/a/sys/health` 健康检查地址。
- `testServerConnection` 使用原生 `fetch` 测试连接,超时、跨域、HTTP 非 200 都会给出明确错误信息。
- `reloadToAppRoot` 切换地址后回到应用根路径并重新加载。
```mermaid
flowchart TD
Input["用户输入服务地址"] --> Normalize["normalizeServerOrigin 规范化"]
Normalize --> Valid{"格式合法?"}
Valid -->|否| Error["返回错误信息"]
Valid -->|是| Save["保存到 SERVER_BASE_URL__"]
Save --> Remember["加入最近使用历史"]
Remember --> Health["testServerConnection 健康检查"]
Health --> Ok{"连接成功?"}
Ok -->|否| ShowError["提示网络、端口、跨域或服务问题"]
Ok -->|是| Reload["reloadToAppRoot 回到根路径并重载"]
```
**图示来源**
- [ai-electron/frontend/src/core/settings/serverSetting.ts:1-200](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L1-L200)
- [ai-electron/frontend/src/core/settings/serverSetting.ts:201-248](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L201-L248)
**章节来源**
- [ai-electron/frontend/src/core/settings/serverSetting.ts:1-248](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L1-L248)
### 离线地图 china.pmtiles
`offlineMap.ts` 提供两种 PMTiles 数据源:
- `ElectronPmtilesSource`:通过主进程 IPC 读取本机绝对路径下的 `china.pmtiles`,按需分块读取二进制范围。
- `HttpPmtilesSource`:对内置静态资源 `resource/map/china.pmtiles` 使用 HTTP Range 请求。
离线地图目录保存在 `OFFLINE_MAP_DIR__`,支持 Windows 盘符、UNC 路径、POSIX 绝对路径和本地协议。样式 JSON 也可从本机路径读取,否则回退到内置样式。
```mermaid
classDiagram
class ElectronPmtilesSource {
+string filePath
+getKey() string
+getBytes(offset, length) ArrayBuffer
}
class HttpPmtilesSource {
+string url
+getKey() string
+getBytes(offset, length) ArrayBuffer
}
class OfflineMap {
+getOfflineMapDir() string
+getOfflineMapPmtilesPath() string
+resolveOfflinePmtilesSources() Array
+readOfflineMapStyleText() Promise~string~
+isValidOfflineMapPath(value) boolean
+setOfflineMapDir(path) void
}
OfflineMap --> ElectronPmtilesSource : "本地路径时使用"
OfflineMap --> HttpPmtilesSource : "内置静态资源时使用"
```
**图示来源**
- [ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L200)
**章节来源**
- [ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L200)
### SSE Agent 对话流程
Agent 对话分为两层:
- `chatApi.ts`:封装非流式聊天接口,如会话列表、消息列表、发送消息等。
- `sse.ts`:通用 SSE 解析器与 `streamSse` 流式请求实现,支持 `intent`、`thinking`、`tool_call`、`tool_input`、`tool_result`、`token`、`done`、`error` 等事件。
- `chatStream.ts`:AI 对话流式状态机,维护会话、消息、工具步骤、思考过程、意图与建议项,并做增量解析节流。
```mermaid
sequenceDiagram
participant UI as "AI 对话界面"
participant Store as "chatStream.ts"
participant Api as "chatApi.ts"
participant SSE as "sse.ts"
participant Server as "ai-server"
UI->>Store: 发送消息
Store->>Api: createSession / listMessages / sendMessage
Store->>SSE: streamChat(url, params, handlers)
SSE->>Server: POST 带 x-token 的事件流请求
Server-->>SSE: intent / thinking / tool_call / token / done
SSE-->>Store: 分发事件
Store->>Store: 更新消息、工具步骤、思考文本、建议项
Store-->>UI: 增量渲染
```
**图示来源**
- [ai-electron/frontend/src/ai/api/chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/frontend/src/ai/store/chatStream.ts:1-200](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L200)
**章节来源**
- [ai-electron/frontend/src/ai/api/chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/frontend/src/ai/store/chatStream.ts:1-200](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L200)
### 前端工程结构与 Vite 配置
前端工程位于 `ai-electron/frontend`,采用:
- Vite 作为构建工具。
- Vue 3 作为视图框架。
- Ant Design Vue 作为 UI 组件库。
- TypeScript 作为类型系统。
- UnoCSS 与自定义 less 作为样式方案。
`vite.config.ts` 中:
- 通过 `loadEnv` 加载环境配置。
- 设置 `base`、`define`、`plugins`、`server`、`esbuild`、`build`、`css`、`resolve.alias`。
- `@` 指向 `src`,`@build` 指向 `build`。
**章节来源**
- [ai-electron/frontend/vite.config.ts:1-40](file://ai-electron/frontend/vite.config.ts#L1-L40)
## 依赖关系分析
```mermaid
graph LR
Package["package.json
ee-core / electron-updater"]
Main["electron/main.ts"]
Lifecycle["electron/preload/lifecycle.ts"]
Preload["electron/preload/index.ts"]
Bridge["electron/preload/bridge.ts"]
WindowOpts["electron/config/windowOptions.ts"]
DefaultCfg["electron/config/config.default.ts"]
WindowCtl["electron/controller/windowCtl.ts"]
FrontMain["frontend/src/main.ts"]
AppVue["frontend/src/App.vue"]
ServerCfg["frontend/src/core/settings/serverSetting.ts"]
OfflineMap["frontend/src/core/utils/map/offlineMap.ts"]
SSE["frontend/src/ai/api/sse.ts"]
ChatStore["frontend/src/ai/store/chatStream.ts"]
ChatApi["frontend/src/ai/api/chatApi.ts"]
Package --> Main
Main --> Lifecycle
Main --> Preload
Main --> Bridge
DefaultCfg --> WindowOpts
Main --> WindowCtl
FrontMain --> AppVue
FrontMain --> ServerCfg
AppVue --> ServerCfg
AppVue --> OfflineMap
ChatStore --> ChatApi
ChatStore --> SSE
```
**图示来源**
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
- [ai-electron/electron/preload/bridge.ts:1-10](file://ai-electron/electron/preload/bridge.ts#L1-L10)
- [ai-electron/electron/config/windowOptions.ts:1-41](file://ai-electron/electron/config/windowOptions.ts#L1-L41)
- [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50)
- [ai-electron/electron/controller/windowCtl.ts:1-123](file://ai-electron/electron/controller/windowCtl.ts#L1-L123)
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85)
- [ai-electron/frontend/src/core/settings/serverSetting.ts:1-200](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L1-L200)
- [ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/frontend/src/ai/store/chatStream.ts:1-200](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80)
**章节来源**
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
## 性能与体验特性
- **启动健康检查**:最多 10 次、每次约 3 秒探测后端,loading 页实时显示重试次数,避免长时间阻塞且给用户明确反馈。
- **授权前置**:授权校验优先于登录态检查,授权过期时直接跳转授权页并携带过期原因。
- **登录门禁**:无 token 时跳转授权/服务地址页,同时保留来源路由以便登录后回跳。
- **流式输出**:SSE 事件按真实顺序下发,前端维护时序链,避免长回答重复扫描导致的 O(n²) 卡顿。
- **离线地图**:本机路径走 IPC 分块读取,内置静态资源走 HTTP Range,减少后端压力。
- **地址持久化**:服务地址存储在原始 localStorage 键中,客户端升级后无需重复绑定。
[本节为通用优化说明,不直接分析具体代码片段]
## 常见问题排查
| 现象 | 可能原因 | 排查位置 |
|---|---|---|
| 启动后一直显示“后端服务连接失败” | ai-server 未启动、地址绑定错误、跨域被拦截、防火墙阻止 | `frontend/src/main.ts` 的健康检查逻辑 |
| 授权页显示服务不可达 | 绑定地址后首次健康检查失败 | `frontend/src/core/settings/serverSetting.ts` 的 `testServerConnection` |
| 地图不显示或瓦片空白 | 本机离线地图目录无效、`china.pmtiles` 不存在、Range 请求失败 | `frontend/src/core/utils/map/offlineMap.ts` |
| Agent 没有流式输出 | 后端未返回 `text/event-stream`、token 失效、请求被代理或网关拦截 | `frontend/src/ai/api/sse.ts` |
| 登录后跳转异常 | 入口路由处理、hash/history 模式差异、来源路由丢失 | `frontend/src/main.ts` 的路由解析与登录门禁 |
| 智能工作台窗口行为异常 | 窗口角色识别错误或 IPC 事件未正确转发 | `electron/controller/windowCtl.ts` |
| 打包后找不到静态资源 | Vite `base`、Electron 静态资源路径、asar 打包影响 | `frontend/vite.config.ts`、`electron/config/config.default.ts` |
**章节来源**
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/core/settings/serverSetting.ts:1-248](file://ai-electron/frontend/src/core/settings/serverSetting.ts#L1-L248)
- [ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/electron/controller/windowCtl.ts:1-123](file://ai-electron/electron/controller/windowCtl.ts#L1-L123)
- [ai-electron/frontend/vite.config.ts:1-40](file://ai-electron/frontend/vite.config.ts#L1-L40)
- [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50)
## 从启动到发起 Agent 请求的最小路径
以下路径描述最小可运行流程,不包含完整 UI 交互细节:
1. Electron 主进程启动:
- 加载 `main.ts`。
- 注册生命周期与 `preload`。
- 调用 `app.run()` 创建主窗口。
2. 预加载模块初始化:
- 创建托盘与安全服务。
- 可选通过 `bridge.ts` 暴露 `ipcRenderer`。
3. 渲染进程引导:
- 初始化 Vue、Store、路由、国际化。
- 检测是否缺少 ai-server 地址;缺失则进入授权/服务地址页。
- 若地址存在,执行最多 10 次健康检查。
4. 授权与登录:
- 校验授权,过期则跳转授权页。
- 无 token 则跳转授权/登录入口。
5. 发起 Agent 请求:
- 用户在 AI 对话界面发送消息。
- `chatStream.ts` 调用 `chatApi.ts` 创建或查询会话。
- `sse.ts` 使用 `fetch` 发起事件流请求,携带 `x-token`。
- 解析 `intent`、`thinking`、`tool_call`、`token`、`done`、`error` 等事件。
- 更新流式消息并渲染到界面。
```mermaid
flowchart TD
A["Electron 主进程启动"] --> B["注册生命周期与 preload"]
B --> C["创建主窗口"]
C --> D["渲染进程 main.ts 初始化"]
D --> E["检查 ai-server 地址"]
E --> F["健康检查后端"]
F --> G["授权与登录校验"]
G --> H["AI 对话界面发送消息"]
H --> I["chatStream.ts 调用 chatApi.ts"]
I --> J["sse.ts 发起 SSE 流式请求"]
J --> K["解析事件并更新消息"]
```
**图示来源**
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/ai/api/chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80)
- [ai-electron/frontend/src/ai/api/sse.ts:1-200](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L200)
- [ai-electron/frontend/src/ai/store/chatStream.ts:1-200](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L200)
## 结论
本桌面客户端以 `ee-core.ElectronEgg` 为主进程骨架,通过生命周期钩子和预加载模块组织启动流程;渲染进程以 Vue 3 为核心,完成主题、国际化、授权、地图与 SSE Agent 对话。ai-server 地址在运行时绑定,离线地图通过 PMTiles 和本机路径读取;跨窗口状态通过主进程统一转发。整体架构清晰分离主进程与渲染进程职责,适合继续扩展安全加固、自动更新与更多桌面能力。
[本节为总结性内容,不直接分析具体文件]