iFlow-Settings-Editor-GUI/AGENTS.md

iFlow Settings Editor - Agent 文档

项目概述

iFlow 设置编辑器是一个基于 Electron + Vue 3 的桌面应用程序，用于编辑 C:\Users\<USER>\.iflow\settings.json 配置文件。

技术栈

技术	版本	用途
Electron	^28.0.0	桌面应用框架
Vue	^3.4.0	前端框架 (组合式 API)
Vite	^8.0.8	构建工具
@icon-park/vue-next	^1.4.2	图标库
@vitejs/plugin-vue	^6.0.6	Vue 插件
concurrently	^8.2.2	并发执行工具
electron-builder	^24.13.3	应用打包工具
vitest	^4.1.4	单元测试框架
@vue/test-utils	^2.5.0	Vue 组件测试工具
happy-dom	Latest	浏览器环境模拟

项目结构

iflow-settings-editor/
├── main.js              # Electron 主进程 (窗口管理、IPC、文件操作、系统托盘)
├── preload.js           # 预加载脚本 (contextBridge API)
├── index.html           # HTML 入口
├── package.json         # 项目配置
├── vite.config.js       # Vite 配置
├── vitest.config.js      # Vitest 测试配置
├── src/
│   ├── main.js         # Vue 入口
│   ├── components/     # 可复用组件
│   │   ├── ApiProfileDialog.vue
│   │   ├── Footer.vue
│   │   ├── InputDialog.vue
│   │   ├── MessageDialog.vue
│   │   ├── ServerPanel.vue
│   │   ├── SideBar.vue
│   │   └── TitleBar.vue
│   ├── views/         # 页面视图组件
│   │   ├── ApiConfig.vue
│   │   ├── GeneralSettings.vue
│   │   └── McpServers.vue
│   └── styles/        # 全局样式
│       └── global.less
├── build/               # 构建资源 (图标等)
├── dist/                # Vite 构建输出
├── release/             # 打包输出目录
└── screenshots/         # 截图资源

核心架构

进程模型

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

IPC 通信

// 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: (sourceName, newName) => ipcRenderer.invoke('duplicate-api-profile', sourceName, newName),

  // 托盘事件监听
  onApiProfileSwitched: (callback) => {
    ipcRenderer.on('api-profile-switched', (event, profileName) => callback(profileName))
  }
}

窗口配置

• 窗口尺寸: 1100x750，最小尺寸: 900x600
• 无边框窗口 (frame: false)，自定义标题栏
• 开发模式加载 http://localhost:5173，生产模式加载 dist/index.html
• 关闭窗口时隐藏到系统托盘，双击托盘图标可重新显示

系统托盘

• 托盘图标显示应用状态
• 右键菜单支持：
  • 显示主窗口
  • 切换 API 配置（显示所有配置列表，当前配置带勾选标记）
  • 退出应用
• 双击托盘图标显示主窗口

API 配置切换

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

可用命令

npm install              # 安装依赖
npm run dev              # 启动 Vite 开发服务器
npm run build            # 构建 Vue 应用到 dist 目录
npm start                # 运行 Electron (需先build)
npm run electron:dev     # 同时运行 Vite + Electron (开发模式)
npm run electron:start   # 构建 + 运行 Electron (生产模式)
npm run pack             # 打包应用（不生成安装包）
npm run build:win        # 构建 Windows 安装包
npm run build:win64      # 构建 Windows x64 安装包
npm run build:win32      # 构建 Windows x86 安装包
npm run build:win-portable  # 构建可移植版本
npm run build:win-installer  # 构建 NSIS 安装包
npm run dist             # 完整构建和打包
npm run test            # 运行所有测试（监听模式）
npm run test:run        # 运行测试一次
npm run test:ui          # 运行测试 UI 界面
npm run test:coverage   # 生成测试覆盖率报告

功能模块

1. 常规设置 (General)

• 语言: zh-CN / en-US / ja-JP
• 主题: Xcode / Dark / Light / Solarized Dark
• 启动动画: 已显示 / 未显示
• 检查点保存: 启用 / 禁用

2. API 配置 (API)

• 配置列表: 显示所有可用的 API 配置文件，带彩色图标和状态标记
• 配置切换: 点击配置卡片直接切换，无需确认
• 创建配置: 新建 API 配置文件（支持设置认证方式、API Key、Base URL 等）
• 编辑配置: 修改现有配置的认证方式、API Key、Base URL 等
• 复制配置: 基于现有配置创建新配置
• 删除配置: 删除非默认配置
• 认证方式: iFlow / API Key / OpenAI 兼容
• API Key: 密码输入框
• Base URL: API 端点
• 模型名称: AI 模型标识
• 搜索 API Key: 搜索服务认证
• CNA: CNA 标识

3. MCP 服务器管理 (MCP)

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

关键实现细节

设置文件路径

const SETTINGS_FILE = path.join(app.getPath('home'), '.iflow', 'settings.json');

保存时自动备份

if (fs.existsSync(SETTINGS_FILE)) {
  const backupPath = SETTINGS_FILE + '.bak';
  fs.copyFileSync(SETTINGS_FILE, backupPath);
}

安全配置

• contextIsolation: true - 隔离上下文
• nodeIntegration: false - 禁用 Node.js
• webSecurity: false - 仅开发环境解决 CSP 问题

Vue 组件状态管理

• settings - 当前设置 (ref)
• originalSettings - 原始设置 (用于检测修改)
• modified - 是否已修改 (computed/diff)
• currentSection - 当前显示的板块
• currentServerName - 当前选中的 MCP 服务器
• currentApiProfile - 当前使用的 API 配置名称
• apiProfiles - 可用的 API 配置列表
• isLoading - 加载状态标志

API 配置字段

const API_FIELDS = ['selectedAuthType', 'apiKey', 'baseUrl', 'modelName', 'searchApiKey', 'cna'];

数据初始化

在 loadSettings 函数中确保所有字段都有默认值：

• language: 'zh-CN'
• theme: 'Xcode'
• bootAnimationShown: true
• checkpointing: { enabled: true }
• selectedAuthType: 'openai-compatible'
• apiKey: ''
• baseUrl: ''
• modelName: ''
• searchApiKey: ''
• cna: ''
• apiProfiles: { default: {} }
• currentApiProfile: 'default'
• mcpServers: {}

8. 测试框架 (Vitest)

测试配置：

• 使用 Vitest 作为测试运行器
• 使用 @vue/test-utils 进行 Vue 组件测试
• 使用 happy-dom 作为浏览器环境模拟
• 配置文件：vitest.config.js
• 全局变量启用：globals: true
• 覆盖率工具：v8
• 覆盖率报告格式：text、json、html

测试文件结构：

src/
├── components/
│   ├── Footer.test.js      # Footer 组件测试 (5 个测试)
│   ├── SideBar.test.js     # 侧边栏测试 (10 个测试)
│   └── TitleBar.test.js     # 标题栏测试 (8 个测试)
└── views/
    ├── ApiConfig.test.js        # API 配置测试 (15 个测试)
    ├── GeneralSettings.test.js   # 常规设置测试 (8 个测试)
    └── McpServers.test.js       # MCP 服务器测试 (12 个测试)

测试覆盖范围：

• 视图组件：
  • GeneralSettings - 常规设置页面
  • ApiConfig - API 配置管理
  • McpServers - MCP 服务器管理
• UI 组件：
  • Footer - 状态栏
  • TitleBar - 窗口标题栏
  • SideBar - 侧边导航栏

测试命令：

npm run test            # 运行所有测试（监听模式）
npm run test:run        # 运行测试一次
npm run test:ui          # 运行测试 UI 界面 (http://localhost:51204/__vitest__/)
npm run test:coverage   # 生成测试覆盖率报告

测试统计：

• 总测试文件：6 个
• 总测试用例：58 个
• 测试执行时间：约 5-6 秒
• 覆盖率：可查看 HTML 报告

测试策略：

• 使用 mock 函数模拟外部 API（如 window.electronAPI）
• 测试组件渲染、事件触发、状态管理
• 验证用户交互流程
• 测试边界情况和错误处理

开发注意事项

1. 修改检测: 通过 watch(settings, () => { modified.value = true }, { deep: true }) 深度监听
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 图标库:

import { Save, Config, Key, Server, Globe, Setting, Add, Edit, Delete, Exchange, Copy } from '@icon-park/vue-next';

打包配置

Windows 平台

• NSIS 安装包: 支持 x64 架构
• 可移植版本: 无需安装的独立可执行文件
• 安装器特性:
  • 允许修改安装目录
  • 允许提升权限
  • 创建桌面和开始菜单快捷方式
  • 支持中文和英文界面 (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 配置编辑使用模态对话框

主题变量

: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;
}