文档更新项目文档，添加系统托盘、更新日志及功能说明

2026-04-17 23:42:54 +08:00
parent 5ee6ee75f1
commit d184cfef6e
3 changed files with 150 additions and 30 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,23 +20,24 @@ iFlow 设置编辑器是一个基于 Electron + Vue 3 的桌面应用程序，

 ```
 iflow-settings-editor/
-├── main.js              # Electron 主进程 (窗口管理、IPC、文件操作)
+├── main.js              # Electron 主进程 (窗口管理、IPC、文件操作、系统托盘)
 ├── preload.js           # 预加载脚本 (contextBridge API)
 ├── index.html           # HTML 入口
 ├── package.json         # 项目配置
 ├── vite.config.js       # Vite 配置
 ├── src/
 │   ├── main.js         # Vue 入口
-│   └── App.vue         # 主组件 (所有业务逻辑)
+│   └── App.vue         # 主组件 (所有业务逻辑、UI 组件)
 ├── build/               # 构建资源 (图标等)
+├── dist/                # Vite 构建输出
 ├── release/             # 打包输出目录
-└── screenshots/          # 截图资源
+└── screenshots/         # 截图资源
 ```

 ## 核心架构

 ### 进程模型
- **Main Process (main.js)**: Electron 主进程，处理窗口管理、IPC 通信、文件系统操作
+- **Main Process (main.js)**: Electron 主进程，处理窗口管理、IPC 通信、文件系统操作、系统托盘
 - **Preload (preload.js)**: 通过 `contextBridge.exposeInMainWorld` 暴露安全 API
 - **Renderer (Vue)**: 渲染进程，只通过 preload 暴露的 API 与主进程通信

@@ -44,19 +45,29 @@ iflow-settings-editor/
 ```javascript
 // preload.js 暴露的 API
 window.electronAPI = {
+  // 基本设置操作
  loadSettings: () => ipcRenderer.invoke('load-settings'),
  saveSettings: (data) => ipcRenderer.invoke('save-settings', data),
  showMessage: (options) => ipcRenderer.invoke('show-message', options),
+
+  // 窗口控制
+  isMaximized: () => ipcRenderer.invoke('is-maximized'),
+  minimize: () => ipcRenderer.send('window-minimize'),
+  maximize: () => ipcRenderer.send('window-maximize'),
+  close: () => ipcRenderer.send('window-close'),
+
+  // API 配置管理（单文件内多配置）
  listApiProfiles: () => ipcRenderer.invoke('list-api-profiles'),
  switchApiProfile: (profileName) => ipcRenderer.invoke('switch-api-profile', profileName),
  createApiProfile: (name) => ipcRenderer.invoke('create-api-profile', name),
  deleteApiProfile: (name) => ipcRenderer.invoke('delete-api-profile', name),
  renameApiProfile: (oldName, newName) => ipcRenderer.invoke('rename-api-profile', oldName, newName),
-  duplicateApiProfile: (name, newName) => ipcRenderer.invoke('duplicate-api-profile', name, newName),
-  isMaximized: () => ipcRenderer.invoke('is-maximized'),
-  minimize: () => ipcRenderer.send('window-minimize'),
-  maximize: () => ipcRenderer.send('window-maximize'),
-  close: () => ipcRenderer.send('window-close')
+  duplicateApiProfile: (sourceName, newName) => ipcRenderer.invoke('duplicate-api-profile', sourceName, newName),
+
+  // 托盘事件监听
+  onApiProfileSwitched: (callback) => {
+    ipcRenderer.on('api-profile-switched', (event, profileName) => callback(profileName))
+  }
 }
 ```

@@ -64,12 +75,22 @@ window.electronAPI = {
 - 窗口尺寸: 1100x750，最小尺寸: 900x600
 - 无边框窗口 (frame: false)，自定义标题栏
 - 开发模式加载 `http://localhost:5173`，生产模式加载 `dist/index.html`
+- **关闭窗口时隐藏到系统托盘**，双击托盘图标可重新显示
+
+### 系统托盘
+- 托盘图标显示应用状态
+- 右键菜单支持：
+  - 显示主窗口
+  - 切换 API 配置（显示所有配置列表，当前配置带勾选标记）
+  - 退出应用
+- 双击托盘图标显示主窗口

 ### API 配置切换
 - 支持多环境配置: 默认配置、开发环境、预发布环境、生产环境
 - 配置文件管理: 支持创建、编辑、复制、删除、重命名
 - 单独保存每个环境的 API 配置到 `apiProfiles` 对象
 - 切换配置时直接应用新配置，无需确认
+- 支持从系统托盘快速切换配置

 ## 可用命令

@@ -98,9 +119,9 @@ npm run dist             # 完整构建和打包
 - **检查点保存**: 启用 / 禁用

 ### 2. API 配置 (API)
- **配置列表**: 显示所有可用的 API 配置文件
+- **配置列表**: 显示所有可用的 API 配置文件，带彩色图标和状态标记
 - **配置切换**: 点击配置卡片直接切换，无需确认
- **创建配置**: 新建 API 配置文件
+- **创建配置**: 新建 API 配置文件（支持设置认证方式、API Key、Base URL 等）
 - **编辑配置**: 修改现有配置的认证方式、API Key、Base URL 等
 - **复制配置**: 基于现有配置创建新配置
 - **删除配置**: 删除非默认配置
@@ -112,8 +133,9 @@ npm run dist             # 完整构建和打包
 - **CNA**: CNA 标识

 ### 3. MCP 服务器管理 (MCP)
- 服务器列表展示
+- 服务器列表展示（带描述信息）
 - 添加/编辑/删除服务器
+- 侧边面板编辑界面
 - 服务器配置: 名称、描述、命令、工作目录、参数(每行一个)、环境变量(JSON)

 ## 关键实现细节
@@ -144,6 +166,12 @@ if (fs.existsSync(SETTINGS_FILE)) {
 - `currentServerName` - 当前选中的 MCP 服务器
 - `currentApiProfile` - 当前使用的 API 配置名称
 - `apiProfiles` - 可用的 API 配置列表
+- `isLoading` - 加载状态标志
+
+### API 配置字段
+```javascript
+const API_FIELDS = ['selectedAuthType', 'apiKey', 'baseUrl', 'modelName', 'searchApiKey', 'cna'];
+```

 ### 数据初始化
 在 `loadSettings` 函数中确保所有字段都有默认值：
@@ -151,7 +179,7 @@ if (fs.existsSync(SETTINGS_FILE)) {
 - `theme`: 'Xcode'
 - `bootAnimationShown`: true
 - `checkpointing`: { enabled: true }
- `selectedAuthType`: 'iflow'
+- `selectedAuthType`: 'openai-compatible'
 - `apiKey`: ''
 - `baseUrl`: ''
 - `modelName`: ''
@@ -159,23 +187,25 @@ if (fs.existsSync(SETTINGS_FILE)) {
 - `cna`: ''
 - `apiProfiles`: { default: {} }
 - `currentApiProfile`: 'default'
+- `mcpServers`: {}

 ## 开发注意事项

 1. **修改检测**: 通过 `watch(settings, () => { modified.value = true }, { deep: true })` 深度监听
-2. **服务器编辑**: 使用 DOM 操作收集表单数据 (`collectServerData`)
+2. **服务器编辑**: 使用侧边面板 (Side Panel) 收集表单数据
 3. **MCP 参数**: 每行一个参数，通过换行分割
 4. **环境变量**: 支持 JSON 格式输入
 5. **窗口控制**: 通过 IPC 发送指令，主进程处理实际窗口操作
 6. **API 配置切换**: 多个环境配置存储在 `settings.apiProfiles` 对象中
 7. **序列化问题**: IPC 通信使用 `JSON.parse(JSON.stringify())` 避免 Vue 响应式代理问题
 8. **默认值处理**: 加载配置时检查 `undefined` 并应用默认值，防止界面显示异常
+9. **托盘切换事件**: 监听 `onApiProfileSwitched` 处理托盘发起的配置切换

 ## 图标使用

 使用 `@icon-park/vue-next` 图标库:
 ```javascript
-import { Refresh, Save, Config, Key, Server, Globe, Setting, Robot, Search, Add, Edit, Delete, Exchange, Copy } from '@icon-park/vue-next';
+import { Save, Config, Key, Server, Globe, Setting, Add, Edit, Delete, Exchange, Copy } from '@icon-park/vue-next';
 ```

 ## 打包配置
@@ -187,10 +217,38 @@ import { Refresh, Save, Config, Key, Server, Globe, Setting, Robot, Search, Add,
  - 允许修改安装目录
  - 允许提升权限
  - 创建桌面和开始菜单快捷方式
-  - 支持中文和英文界面
+  - 支持中文和英文界面 (zh_CN, en_US)
  - 卸载时保留用户数据

 ### 输出目录
 - `release/` - 所有打包输出的根目录
 - 安装包命名: `iFlow Settings Editor-${version}-${arch}-setup.${ext}`
 - 可移植版本命名: `iFlow Settings Editor-${version}-portable.${ext}`
+
+## UI 组件
+
+### 对话框类型
+- **输入对话框**: 用于重命名、复制等需要文本输入的场景
+- **确认对话框**: 用于删除等需要确认的操作
+- **消息对话框**: 显示 info/success/warning/error 四种类型，带图标
+
+### 侧边面板
+- MCP 服务器编辑使用侧边面板 (从右侧滑入)
+- API 配置编辑使用模态对话框
+
+### 主题变量
+```css
+:root {
+  --bg-primary: #f8fafc;
+  --bg-secondary: #ffffff;
+  --bg-tertiary: #f1f5f9;
+  --text-primary: #0f172a;
+  --text-secondary: #475569;
+  --text-tertiary: #94a3b8;
+  --accent: #3b82f6;
+  --accent-hover: #2563eb;
+  --border: #e2e8f0;
+  --success: #10b981;
+  --danger: #ef4444;
+}
+```
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,7 @@
 # 更新日志

+所有重要的版本更新都会记录在此文件中。
+
 ## [1.5.1] - 2026-04-17

 ### 新增
@@ -7,7 +9,54 @@
  - 窗口关闭时最小化到托盘而非退出应用
  - 托盘右键菜单：显示主窗口、切换 API 配置、退出
  - 双击托盘图标恢复显示主窗口
-  - 从托盘快速切换 API 配置
+  - 从托盘快速切换 API 配置（自动保存当前配置）

 ### 优化
 - API 配置编辑对话框的数据回填逻辑，使用 `(profile && profile.xxx) || fallback` 模式
+- 改进 API 配置保存逻辑，确保切换配置时自动同步保存
+- 移除 API 配置切换时的未保存更改确认弹窗
+- 保存机制，在编辑、创建和删除时自动保存配置
+
+### 修复
+- MCP 服务器保存及消息对话框被遮挡问题
+- 基础设置下拉框初始值缺失问题
+- API 配置编辑功能，确保编辑按钮显示正确的配置数据
+- 弹框点击空白处误关闭的问题
+
+## [1.5.0] - 2026-04-16
+
+### 新增
+- **API 配置重命名功能**
+- **自定义消息对话框组件**，支持 info/success/warning/error 四种类型
+- **应用窗口图标支持**
+- **Windows 平台编译打包配置**
+
+### 优化
+- MCP 服务器添加交互改为侧边面板一步操作
+- 整体 UI 样式和交互动画效果
+- 配置文件图标使用渐变色
+- **架构变更**: API 配置管理从多文件改为单文件内 `apiProfiles` 对象管理
+
+### 修复
+- API 配置初始化时配置名称和认证方式显示为空的问题
+- 对话框取消逻辑
+
+## [1.4.0] - 2026-04-14
+
+### 新增
+- **配置文件多管理功能**
+  - 支持多环境配置文件（apiProfiles）
+  - 创建、编辑、复制、删除 API 配置
+  - 配置文件切换无需确认，直接应用
+
+## [1.0.0] - 2026-04-14
+
+### 新增
+- 项目初始化
+- Electron + Vue 3 基础架构
+- 基础 UI 样式
+- 设置文件读取和保存功能
+- 基础 IPC 通信
+- 无边框窗口
+- 自定义标题栏
+- 最小化、最大化、关闭按钮
--- a/README.md
+++ b/README.md
@@ -17,17 +17,18 @@

 ```
 iflow-settings-editor/
-├── main.js              # Electron 主进程 (窗口管理、IPC、文件操作)
-├── preload.js           # 预加载脚本 (IPC 通信)
+├── main.js              # Electron 主进程 (窗口管理、IPC、文件操作、系统托盘)
+├── preload.js           # 预加载脚本 (contextBridge API)
 ├── index.html           # HTML 入口
 ├── package.json         # 项目配置
 ├── vite.config.js       # Vite 配置
 ├── src/
 │   ├── main.js         # Vue 入口
-│   └── App.vue       # 主组件 (所有业务逻辑)
+│   └── App.vue         # 主组件 (所有业务逻辑、UI 组件)
 ├── build/               # 构建资源 (图标等)
+├── dist/                # Vite 构建输出
 ├── release/             # 打包输出目录
-└── screenshots/          # 截图资源
+└── screenshots/         # 截图资源
 ```

 ## 快速开始
@@ -61,7 +62,8 @@ npm run build:win        # 构建 Windows 安装包 (NSIS)
 npm run build:win64      # 构建 Windows x64 安装包
 npm run build:win32      # 构建 Windows x86 安装包
 npm run build:win-portable  # 构建可移植版本
-npm run build:dist       # 完整构建和打包
+npm run build:win-installer  # 构建 NSIS 安装包
+npm run dist             # 完整构建和打包
 ```

 ## 功能模块
@@ -81,7 +83,7 @@ npm run build:dist       # 完整构建和打包

 管理多个环境的 API 配置：

- **配置列表**: 显示所有可用的 API 配置文件
+- **配置列表**: 显示所有可用的 API 配置文件，带彩色图标和状态标记
 - **配置切换**: 点击配置卡片直接切换
 - **创建配置**: 新建 API 配置文件
 - **编辑配置**: 修改现有配置的认证方式、API Key、Base URL 等
@@ -98,9 +100,9 @@ npm run build:dist       # 完整构建和打包

 管理 Model Context Protocol 服务器配置：

- **服务器列表**: 显示所有已配置的服务器
+- **服务器列表**: 显示所有已配置的服务器，带描述信息
 - **添加服务器**: 创建新的 MCP 服务器配置
- **编辑服务器**: 修改现有服务器的配置
+- **编辑服务器**: 通过侧边面板修改现有服务器配置
 - **删除服务器**: 移除服务器配置
 - **服务器配置项**:
  - 名称
@@ -113,7 +115,7 @@ npm run build:dist       # 完整构建和打包
 ## 核心架构

 ### 进程模型
- **Main Process (main.js)**: Electron 主进程，处理窗口管理、IPC 通信、文件系统操作
+- **Main Process (main.js)**: Electron 主进程，处理窗口管理、IPC 通信、文件系统操作、系统托盘
 - **Preload (preload.js)**: 通过 `contextBridge.exposeInMainWorld` 暴露安全 API
 - **Renderer (Vue)**: 渲染进程，只通过 preload 暴露的 API 与主进程通信

@@ -121,6 +123,15 @@ npm run build:dist       # 完整构建和打包
 - 窗口尺寸: 1100x750，最小尺寸: 900x600
 - 无边框窗口 (frame: false)，自定义标题栏
 - 开发模式加载 `http://localhost:5173`，生产模式加载 `dist/index.html`
+- **关闭窗口时隐藏到系统托盘**，双击托盘图标可重新显示
+
+### 系统托盘
+- 托盘图标显示应用状态
+- 右键菜单支持：
+  - 显示主窗口
+  - 切换 API 配置（显示所有配置列表，当前配置带勾选标记）
+  - 退出应用
+- 双击托盘图标显示主窗口

 ### 安全配置
 - `contextIsolation: true` - 隔离上下文
@@ -136,7 +147,7 @@ npm run build:dist       # 完整构建和打包
  - 允许修改安装目录
  - 允许提升权限
  - 创建桌面和开始菜单快捷方式
-  - 支持中文和英文界面界面
+  - 支持中文和英文界面 (zh_CN, en_US)
  - 卸载时保留用户数据

 ### 输出目录
@@ -150,17 +161,19 @@ npm run build:dist       # 完整构建和打包
 - 保存设置时会自动创建备份 (`settings.json.bak`)
 - MCP 服务器参数每行一个，环境变量支持 JSON 格式
 - API 配置切换时会直接应用新配置，未保存的更改会被替换
+- 关闭窗口时应用会隐藏到系统托盘，不会退出应用

 ## 开发注意事项

 1. **修改检测**: 通过 `watch(settings, () => { modified.value = true }, { deep: true })` 深度监听
-2. **服务器编辑**: 使用 DOM 操作收集表单数据
+2. **服务器编辑**: 使用侧边面板 (Side Panel) 收集表单数据
 3. **MCP 参数**: 每行一个参数，通过换行分割
 4. **环境变量**: 支持 JSON 格式输入
 5. **窗口控制**: 通过 IPC 发送指令，主进程处理实际窗口操作
 6. **API 配置切换**: 多个环境配置存储在 `settings.apiProfiles` 对象中
 7. **序列化问题**: IPC 通信使用 `JSON.parse(JSON.stringify())` 避免 Vue 响应式代理问题
 8. **默认值处理**: 加载配置时检查 `undefined` 并应用默认值，防止界面显示异常
+9. **托盘切换事件**: 监听 `onApiProfileSwitched` 处理托盘发起的配置切换

 ## 许可证