product/iFlow-Settings-Editor-GUI
1
0
Fork 0
Code Issues 3 Pull Requests Projects Releases 2 Activity
Files
20b065af5b10681fc877bf03c275f3a5d28a875b
iFlow-Settings-Editor-GUI/AGENTS.md

13 KiB
Raw Blame History

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.4.6 Vue 组件测试工具
happy-dom ^20.9.0 浏览器环境模拟
vue-i18n ^9.14.5 国际化支持
less ^4.6.4 CSS 预处理器

项目结构

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 入口
│   ├── App.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
│   └── locales/         # 国际化资源
│       ├── index.js
│       ├── en-US.js
│       └── ja-JP.js
├── 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))
  },

  // 语言切换通知
  notifyLanguageChanged: () => ipcRenderer.send('language-changed')
}

窗口配置

  • 窗口尺寸: 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 / 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: {}

设计系统

Windows UI Kit - Fluent Design

本项目采用 Windows 11 Fluent Design 设计规范，实现统一的视觉效果。

主题变量

Light 模式：

:root {
  --bg-primary: rgba(243, 243, 243, 0.85);
  --bg-secondary: rgba(255, 255, 255, 0.70);
  --bg-tertiary: #ebebeb;
  --bg-elevated: rgba(255, 255, 255, 0.95);
  --text-primary: #1a1a1a;
  --text-secondary: #5d5d5d;
  --accent: #0078d4;
  --accent-hover: #106ebe;
  --border: #e0e0e0;
  --control-fill: rgba(249, 249, 249, 0.85);
}

Dark 模式：

.dark {
  --bg-primary: #1f1f1f;
  --bg-secondary: #2d2d2d;
  --text-primary: #ffffff;
  --accent: #60cdff;
  --control-fill: #333333;
}

Solarized Dark 模式：

.solarized-dark {
  --bg-primary: #002b36;
  --bg-secondary: #073642;
  --text-primary: #839496;
  --accent: #268bd2;
}

设计原则

  • Mica -inspired 层次感: 使用半透明背景和分层深度
  • 圆角系统: 4px / 6px / 8px / 12px 四级圆角
  • 阴影层次: sm / md / lg / xl 四级阴影
  • 过渡动画: 0.1s-0.2s 流畅曲线
  • Segoe UI Variable 字体: Windows 11 原生字体

测试框架 (Vitest)

测试配置：

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

测试文件结构：

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

测试命令：

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

开发注意事项

  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 处理托盘发起的配置切换
  10. 样式系统: 使用 Windows UI Kit 设计系统，所有变量在 global.less 中定义

图标使用

使用 @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 配置编辑使用模态对话框

版本历史

版本 日期 主要变更
1.6.0 2026-04-18 架构：重构样式系统，采用 Windows 11 Fluent Design 规范
1.5.1 2026-04-17 新增系统托盘功能，托盘快速切换 API 配置
1.5.0 2026-04-16 新增自定义消息对话框，API 配置重命名
1.4.0 2026-04-14 新增多环境配置文件管理
1.0.0 2026-04-14 项目初始化