You've already forked iFlow-Settings-Editor-GUI
234 lines
6.6 KiB
Markdown
234 lines
6.6 KiB
Markdown
# iFlow Settings Editor - AI Context
|
||
|
||
## 项目概述
|
||
|
||
**iFlow 设置编辑器** 是一个用于编辑 iFlow CLI 配置文件 (`~/.iflow/settings.json`) 的桌面应用程序，采用 Electron + Vue 3 技术栈构建。
|
||
|
||
### 技术栈
|
||
|
||
| 类别 | 技术 |
|
||
|------|------|
|
||
| 框架 | Electron 28 + Vue 3.4 |
|
||
| 构建工具 | Vite 8 |
|
||
| CSS 预处理器 | Less |
|
||
| 国际化 | vue-i18n 9 |
|
||
| 测试框架 | Vitest 4 + happy-dom |
|
||
| 打包工具 | electron-builder 24 |
|
||
| 图标库 | @icon-park/vue-next |
|
||
|
||
### 核心架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Electron 主进程 │
|
||
│ main.js - 窗口管理、系统托盘、IPC 通信、文件读写 │
|
||
│ preload.js - 安全桥接 (contextBridge) │
|
||
└─────────────────────────────────────────────────────┘
|
||
↕ IPC
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Vue 3 渲染进程 │
|
||
│ src/App.vue - 根组件 │
|
||
│ ├── TitleBar.vue - 自定义标题栏 │
|
||
│ ├── SideBar.vue - 侧边导航 │
|
||
│ ├── Footer.vue - 底部栏 │
|
||
│ └── views/ │
|
||
│ ├── GeneralSettings.vue - 基础设置 │
|
||
│ ├── ApiConfig.vue - API 配置管理 │
|
||
│ └── McpServers.vue - MCP 服务器管理 │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 配置文件
|
||
|
||
- **路径**: `~/.iflow/settings.json`
|
||
- **编码**: UTF-8 JSON
|
||
- **备份**: 自动生成 `.bak` 备份文件
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式 (Vite Dev Server)
|
||
npm run dev
|
||
|
||
# Electron 开发模式 (并行启动 Vite + Electron)
|
||
npm run electron:dev
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 打包 Windows 安装包 (x64)
|
||
npm run build:win
|
||
|
||
# 打包 Windows 便携版
|
||
npm run build:win-portable
|
||
|
||
# 打包 Windows 安装程序 (NSIS)
|
||
npm run build:win-installer
|
||
|
||
# 运行测试
|
||
npm run test
|
||
|
||
# 测试 UI 模式
|
||
npm run test:ui
|
||
|
||
# 测试覆盖率
|
||
npm run test:coverage
|
||
|
||
# 单次运行测试
|
||
npm run test:run
|
||
```
|
||
|
||
## 设计规范
|
||
|
||
### Windows 11 Fluent Design
|
||
|
||
项目采用 Windows 11 Fluent Design 设计系统，核心规范：
|
||
|
||
| 属性 | 规范 |
|
||
|------|------|
|
||
| 字体 | Segoe UI Variable, Segoe UI, system-ui |
|
||
| 等宽字体 | Cascadia Code, Consolas |
|
||
| 圆角 | 4px (sm) / 6px / 8px (lg) / 12px (xl) |
|
||
| 阴影 | 四级层次 (sm///lg/xl) |
|
||
| 过渡动画 | 0.1-0.2s ease, 0.15s cubic-bezier(0.4, 0, 0.2, 1) |
|
||
|
||
### 主题系统
|
||
|
||
支持两种主题：`Light` (浅色) / `Dark` (深色)
|
||
|
||
CSS 变量定义在 `src/styles/global.less`，包括：
|
||
- `--bg-primary/secondary/elevated` - 背景层级
|
||
- `--text-primary/secondary/tertiary` - 文本层级
|
||
- `--accent` - 主题色 (Windows Blue)
|
||
- `--success/warning/danger/info` - 状态色
|
||
|
||
### 亚克力效果
|
||
|
||
支持可调节透明度的 Mica-inspired 亚克力效果：
|
||
- 背景透明度随 `acrylicIntensity` (0-100) 变化
|
||
- 深色/浅色主题有独立的透明度计算逻辑
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── main.js # Vue 应用入口
|
||
├── App.vue # 根组件
|
||
├── components/
|
||
│ ├── TitleBar.vue # 标题栏 (窗口控制按钮)
|
||
│ ├── SideBar.vue # 侧边导航栏
|
||
│ ├── Footer.vue # 底部栏
|
||
│ ├── InputDialog.vue # 输入对话框
|
||
│ ├── MessageDialog.vue # 消息对话框
|
||
│ ├── ApiProfileDialog.vue # API 配置弹窗
|
||
│ └── ServerPanel.vue # 服务器编辑面板
|
||
├── views/
|
||
│ ├── GeneralSettings.vue # 常规设置视图
|
||
│ ├── ApiConfig.vue # API 配置视图
|
||
│ └── McpServers.vue # MCP 服务器视图
|
||
├── locales/
|
||
│ ├── index.js # 中文 (zh-CN)
|
||
│ ├── en-US.js # 英文
|
||
│ └── ja-JP.js # 日文
|
||
└── styles/
|
||
└── global.less # 全局样式 (Windows Fluent Design)
|
||
```
|
||
|
||
## 关键模块
|
||
|
||
### IPC 通信
|
||
|
||
**preload.js** 暴露的 API：
|
||
|
||
```javascript
|
||
// 设置操作
|
||
window.electronAPI.loadSettings()
|
||
window.electronAPI.saveSettings(data)
|
||
|
||
// 窗口控制
|
||
window.electronAPI.minimize()
|
||
window.electronAPI.maximize()
|
||
window.electronAPI.close()
|
||
window.electronAPI.isMaximized()
|
||
|
||
// API 配置管理
|
||
window.electronAPI.listApiProfiles()
|
||
window.electronAPI.switchApiProfile(name)
|
||
window.electronAPI.createApiProfile(name)
|
||
window.electronAPI.deleteApiProfile(name)
|
||
window.electronAPI.renameApiProfile(oldName, newName)
|
||
window.electronAPI.duplicateApiProfile(sourceName, newName)
|
||
```
|
||
|
||
### API 配置管理
|
||
|
||
配置文件内使用 `apiProfiles` 对象存储多个配置：
|
||
|
||
```json
|
||
{
|
||
"currentApiProfile": "default",
|
||
"apiProfiles": {
|
||
"default": { "apiKey": "...", "baseUrl": "..." },
|
||
"production": { "apiKey": "...", "baseUrl": "..." }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 系统托盘
|
||
|
||
- 窗口关闭时隐藏到托盘而非退出
|
||
- 托盘菜单支持快速切换 API 配置
|
||
- 双击托盘图标显示主窗口
|
||
|
||
## 代码风格
|
||
|
||
### Vue 3 Composition API
|
||
|
||
使用 `<script setup>` 语法：
|
||
|
||
```vue
|
||
<script setup>
|
||
import { ref, computed, watch, onMounted } from 'vue'
|
||
|
||
const settings = ref({})
|
||
const modified = computed(() => ...)
|
||
|
||
const updateSettings = () => { ... }
|
||
|
||
watch(settings, () => { ... }, { deep: true })
|
||
|
||
onMounted(async () => { ... })
|
||
</script>
|
||
```
|
||
|
||
### 样式规范
|
||
|
||
- 使用 Less 预处理器
|
||
- 通过 CSS 变量 (`var(--xxx)`) 使用主题色
|
||
- 组件样式使用 BEM-like 命名或直接使用功能类名
|
||
- 动画使用 `@keyframes` 定义
|
||
|
||
### 测试规范
|
||
|
||
- 测试文件命名: `*.test.js` 或 `*.spec.js`
|
||
- 使用 Vitest + @vue/test-utils
|
||
- DOM 测试环境: happy-dom
|
||
- 覆盖范围排除: node_modules, dist, release, build
|
||
|
||
## 快捷键与交互
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 窗口关闭 | 隐藏到系统托盘 |
|
||
| 双击托盘 | 显示主窗口 |
|
||
| Ctrl+S | 自动保存设置 (通过 watch 监听) |
|
||
|
||
## 常见问题
|
||
|
||
1. **图标不显示**: 检查 `build/icon.ico` 是否存在
|
||
2. **配置不保存**: 确认 `~/.iflow/settings.json` 目录可写
|
||
3. **亚克力效果异常**: 检查 `acrylicIntensity` 值是否在 0-100 范围内
|