## 1. 架构设计

```mermaid
graph TD
    A[uTools Plugin Container] --> B[Vue 3 Frontend]
    B --> C[preload/services.js]
    C --> D[Node.js APIs]
    C --> E[File System]
    C --> F[Git Commands]
    
    subgraph "Frontend Layer"
        B --> G[Ant Design Vue Components]
        B --> H[Markdown Editor]
        B --> I[File Tree Component]
        B --> J[Search Component]
    end
    
    subgraph "Node.js Service Layer"
        C --> K[File Operations]
        C --> L[Process Management]
        C --> M[Git Integration]
        C --> N[Data Persistence]
    end
    
    subgraph "System Layer"
        D --> O[fs Module]
        D --> P[path Module]
        F --> Q[git CLI]
    end
```

## 2. 技术描述

* **前端框架**: Vue 3.5.13 + Composition API

* **UI 组件库**: Ant Design Vue 4.2.6

* **构建工具**: Vite 6.0.11

* **初始化工具**: vite-init

* **插件平台**: uTools

* **Markdown 渲染**: markdown-it 14.1.0

* **JSON 编辑器**: jsoneditor 10.4.2

* **进程管理**: tree-kill 1.2.2

* **图标库**: @ant-design/icons-vue 7.0.1

* **后端**: Node.js (集成在 uTools preload 中)

## 3. 路由定义

由于这是 uTools 插件应用，采用单页面应用模式，通过组件状态管理不同功能展示：

| 路由/状态   | 用途                    |
| ------- | --------------------- |
| /editor | 主编辑界面，包含文件树和编辑器       |
| /search | 搜索界面，支持内容和文件搜索        |
| /export | 导出界面，支持 HTML/PDF 导出   |
| /git    | Git 操作界面，显示 Git 状态和操作 |

## 4. 核心模块架构

### 4.1 文件系统模块 (preload/services.js)

```javascript
// 文件操作 API
class FileService {
    // 读取目录结构
    async readDirectory(path)
    
    // 读取文件内容
    async readFile(filePath)
    
    // 写入文件内容
    async writeFile(filePath, content)
    
    // 创建文件夹
    async createDirectory(path)
    
    // 删除文件/文件夹
    async deleteItem(path)
    
    // 重命名文件/文件夹
    async renameItem(oldPath, newPath)
    
    // 复制文件/文件夹
    async copyItem(sourcePath, destPath)
}
```

### 4.2 图片处理模块

```javascript
// 图片处理 API
class ImageService {
    // 处理粘贴的图片
    async handlePastedImage(imageData, mdFilePath)
    
    // 生成图片文件名（时间戳）
    generateImageName()
    
    // 创建图片目录
    createImageDirectory(mdFileName)
    
    // 保存图片到本地
    async saveImage(imageData, directory)
}
```

### 4.3 Git 集成模块

```javascript
// Git 操作 API
class GitService {
    // 检测 Git 仓库
    isGitRepository(path)
    
    // 获取 Git 状态
    async getStatus(path)
    
    // 执行 Git 提交
    async commit(path, message)
    
    // 执行 Git 推送
    async push(path)
    
    // 执行 Git 拉取
    async pull(path)
}
```

### 4.4 搜索模块

```javascript
// 搜索服务 API
class SearchService {
    // 内容搜索
    async searchContent(directory, keyword, useRegex)
    
    // 文件名搜索
    async searchFileName(directory, keyword)
    
    // 正则表达式搜索
    searchWithRegex(content, pattern)
}
```

## 5. 数据模型

### 5.1 文件树数据结构

```javascript
interface FileNode {
    id: string;
    name: string;
    path: string;
    type: 'file' | 'directory';
    children?: FileNode[];
    expanded?: boolean;
    selected?: boolean;
}

interface FileTreeState {
    rootPath: string;
    nodes: FileNode[];
    selectedFile: string | null;
    expandedKeys: string[];
}
```

### 5.2 编辑器状态管理

```javascript
interface EditorState {
    currentFile: string | null;
    content: string;
    originalContent: string;
    mode: 'source' | 'preview' | 'split';
    isDirty: boolean;
    cursorPosition: { line: number; column: number };
}
```

### 5.3 标签页状态管理

```javascript
interface TabState {
    activeTab: string;  // 当前激活的标签页ID
    tabs: Tab[];
    homeTab: HomeTabData;
}

interface Tab {
    id: string;
    type: 'home' | 'file';
    title: string;
    filePath?: string;
    content?: string;
    isDirty?: boolean;
}

interface HomeTabData {
    recentFiles: RecentFile[];
    pinnedFiles: PinnedFile[];
}

interface RecentFile {
    filePath: string;
    fileName: string;
    lastOpened: number;  // 时间戳
}

interface PinnedFile {
    filePath: string;
    fileName: string;
    pinnedAt: number;  // 时间戳
}
```

### 5.4 搜索状态管理

```javascript
interface SearchState {
    keyword: string;
    searchType: 'content' | 'filename';
    useRegex: boolean;
    results: SearchResult[];
    isSearching: boolean;
}

interface SearchResult {
    filePath: string;
    fileName: string;
    lineNumber?: number;
    content?: string;
    matchPositions: Array<{ start: number; end: number }>;
}
```

## 6. 组件架构

### 6.1 主应用组件结构

```
App.vue
├── FileTree.vue          // 文件树组件
├── TabContainer.vue      // 标签页容器组件（新增）
│   ├── HomeTab.vue       // 首页标签组件（新增）
│   ├── FileTab.vue       // 文件标签组件（新增）
│   └── TabBar.vue        // 标签栏组件（新增）
├── Editor.vue            // 编辑器组件
├── Preview.vue           // 预览组件
├── SearchPanel.vue       // 搜索面板
├── GitPanel.vue          // Git 操作面板
├── Toolbar.vue           // 工具栏
└── StatusBar.vue         // 状态栏
```

### 6.2 核心组件职责

| 组件名称            | 主要职责                  |
| --------------- | --------------------- |
| FileTree.vue    | 显示文件树结构，处理文件选择、右键菜单，支持文件置顶功能 |
| TabContainer.vue | 管理多标签页状态，处理标签页切换、关闭、创建 |
| HomeTab.vue     | 显示最近打开文件列表和置顶文件列表，支持快速打开 |
| FileTab.vue     | 显示单个文件的编辑器和预览面板 |
| TabBar.vue      | 显示标签页标题，支持标签页切换和关闭 |
| Editor.vue      | Markdown 编辑，语法高亮，实时预览 |
| Preview\.vue    | Markdown 渲染，同步滚动      |
| SearchPanel.vue | 搜索输入、结果展示、跳转定位        |
| GitPanel.vue    | Git 状态显示、操作按钮         |
| Toolbar.vue     | 模式切换、导出、搜索等快捷操作       |
| StatusBar.vue   | 显示当前文件、光标位置等状态信息      |

## 7. 状态管理架构

采用 Vue 3 Composition API 的响应式状态管理：

```javascript
// 全局状态管理
const useAppStore = () => {
    const fileTree = reactive(useFileTree());
    const tabs = reactive(useTabs());  // 新增标签页状态管理
    const editor = reactive(useEditor());
    const search = reactive(useSearch());
    const git = reactive(useGit());
    const config = reactive(useConfig());  // 新增配置管理
    
    return {
        fileTree,
        tabs,
        editor,
        search,
        git,
        config
    };
};

// 配置管理模块
const useConfig = () => {
    const configFileName = '.md-helper.json';
    
    const loadConfig = async (rootPath) => {
        // 从当前根目录加载配置文件
        const configPath = path.join(rootPath, configFileName);
        // 读取并解析配置文件
    };
    
    const saveConfig = async (rootPath, configData) => {
        // 保存配置到当前根目录
        const configPath = path.join(rootPath, configFileName);
        // 写入配置文件
    };
    
    return {
        loadConfig,
        saveConfig,
        configFileName
    };
};
```

## 8. 性能优化策略

### 8.1 文件系统优化

* 使用异步文件操作，避免阻塞 UI

* 实现文件内容缓存，减少重复读取

* 大文件采用分块读取策略

### 8.2 搜索优化

* 使用 Web Worker 进行搜索计算

* 实现搜索结果的增量更新

* 添加搜索防抖机制

### 8.3 标签页性能优化

* 标签页内容懒加载，只有激活的标签页才渲染编辑器

* 最近打开文件列表限制数量（最多10个），避免列表过长

* 置顶文件配置使用 Set 数据结构，提高查找效率

* 标签页切换时保留编辑器状态，避免重复初始化

### 8.4 渲染优化

* Markdown 渲染结果缓存

* 虚拟滚动处理长文档

* 图片懒加载机制

## 9. 错误处理机制

### 9.1 文件操作错误

* 权限错误提示

* 文件不存在处理

* 磁盘空间不足警告

### 9.2 Git 操作错误

* 网络错误处理

* 冲突解决提示

* 认证失败处理

### 9.3 用户输入错误

* 文件名非法字符检测

* 路径有效性验证

* 输入格式检查