规划

AI_DEV_GUIDE.md

@@ -0,0 +1,416 @@
+# AI Agent 开发指南
+
+本文档为 AI Agent 开发本项目提供详细的规范和模板，帮助快速理解项目结构、技术栈和开发流程。
+
+## 项目概览
+
+- **项目名称**: Thing
+- **技术栈**: Tauri 2 + Vue 3 + Vite + Pinia + Naive UI + Rust
+- **平台**: Windows
+- **包管理**: Bun
+
+## 核心架构
+
+### 模块系统
+
+项目采用模块化架构，每个模块包含前端组件和 Rust 后端命令：
+
+```
+src/modules/<module-name>/        # 前端模块
+src-tauri/src/commands/<name>.rs  # Rust 命令
+```
+
+### IPC 通信
+
+前端通过 Tauri API 调用 Rust 命令：
+
+```typescript
+import { invoke } from '@tauri-apps/api/core'
+
+// 调用 Rust 命令
+const result = await invoke('module_command', { param: 'value' })
+```
+
+### 状态管理
+
+使用 Pinia 管理全局状态，每个模块可拥有独立的 store：
+
+```typescript
+// src/stores/moduleName.ts
+import { defineStore } from 'pinia'
+
+export const useModuleStore = defineStore('moduleName', {
+  state: () => ({
+    // 状态定义
+  }),
+  actions: {
+    // 操作方法
+  }
+})
+```
+
+## 开发规范
+
+### 命名规范
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 组件 | PascalCase | `ProxyManager.vue` |
+| 函数 | camelCase | `getSystemProxy()` |
+| 文件 | kebab-case | `proxy-manager.ts` |
+| 常量 | UPPER_CASE | `MAX_HISTORY_COUNT` |
+| Rust 模块 | snake_case | `proxy.rs` |
+| Tauri 命令 | snake_case | `get_system_proxy` |
+
+### 代码风格
+
+- **TypeScript**: 使用 ESLint，配置在 `.eslintrc.cjs`
+- **Rust**: 使用 `cargo fmt` 格式化
+- **提交信息**: Conventional Commits 格式
+
+## 模块开发模板
+
+### 前端模块模板
+
+创建 `src/modules/<module-name>/` 目录，包含以下文件：
+
+```typescript
+// index.ts - 模块注册
+import type { ModuleConfig } from '@/types'
+import ModuleComponent from './ModuleComponent.vue'
+
+export const moduleConfig: ModuleConfig = {
+  id: 'module-name',
+  name: '模块名称',
+  icon: 'icon-name',
+  component: ModuleComponent
+}
+```
+
+```vue
+<!-- ModuleComponent.vue - 主组件 -->
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+import { useModuleStore } from '@/stores/moduleName'
+
+const store = useModuleStore()
+
+// 组件逻辑
+const data = ref(null)
+
+const loadData = async () => {
+  // 调用 Rust 命令
+}
+
+onMounted(() => {
+  loadData()
+})
+
+onUnmounted(() => {
+  // 清理资源
+})
+</script>
+
+<template>
+  <div class="module-container">
+    <!-- 模块内容 -->
+  </div>
+</template>
+
+<style scoped>
+.module-container {
+  padding: 20px;
+}
+</style>
+```
+
+### Rust 命令模板
+
+创建 `src-tauri/src/commands/<name>.rs`：
+
+```rust
+// commands/module_name.rs
+use serde::Serialize;
+use tauri::State;
+
+#[derive(Serialize)]
+pub struct CommandResult<T> {
+    pub success: bool,
+    pub data: Option<T>,
+    pub error: Option<String>,
+}
+
+#[tauri::command]
+pub async fn module_get_data() -> CommandResult<Vec<String>> {
+    match fetch_data() {
+        Ok(data) => CommandResult {
+            success: true,
+            data: Some(data),
+            error: None,
+        },
+        Err(e) => CommandResult {
+            success: false,
+            data: None,
+            error: Some(e.to_string()),
+        },
+    }
+}
+
+#[tauri::command]
+pub async fn module_set_data(data: String) -> CommandResult<bool> {
+    match save_data(&data) {
+        Ok(_) => CommandResult {
+            success: true,
+            data: Some(true),
+            error: None,
+        },
+        Err(e) => CommandResult {
+            success: false,
+            data: None,
+            error: Some(e.to_string()),
+        },
+    }
+}
+
+fn fetch_data() -> Result<Vec<String>, Box<dyn std::error::Error>> {
+    // 实现逻辑
+    Ok(vec![])
+}
+
+fn save_data(data: &str) -> Result<(), Box<dyn std::error::Error>> {
+    // 实现逻辑
+    Ok(())
+}
+```
+
+### 注册 Rust 命令
+
+在 `src-tauri/src/lib.rs` 中注册命令：
+
+```rust
+// lib.rs
+mod commands;
+
+use commands::module_name::{module_get_data, module_set_data};
+
+#[tauri::command]
+fn greet(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .invoke_handler(tauri::generate_handler![
+            greet,
+            module_get_data,
+            module_set_data
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+## 常用 Tauri 插件
+
+| 插件 | 用途 | 安装命令 |
+|------|------|----------|
+| `tauri-plugin-autostart` | 开机自启 | `cargo add tauri-plugin-autostart` |
+| `tauri-plugin-tray` | 系统托盘 | `cargo add tauri-plugin-tray` |
+| `tauri-plugin-log` | 日志系统 | `cargo add tauri-plugin-log` |
+| `tauri-plugin-shell` | 执行命令 | `cargo add tauri-plugin-shell` |
+| `tauri-plugin-clipboard-manager` | 剪贴板 | `cargo add tauri-plugin-clipboard-manager` |
+| `tauri-plugin-window-state` | 窗口状态 | `cargo add tauri-plugin-window-state` |
+
+## 进程管理
+
+对于需要管理外部进程的模块（如 mihomo、aria2），使用 `tauri-plugin-shell`：
+
+```rust
+use tauri_plugin_shell::ShellExt;
+
+#[tauri::command]
+pub fn start_process(app: tauri::AppHandle) -> Result<(), String> {
+    let mut cmd = app.shell().command("path/to/executable");
+    cmd.arg("--config").arg("config.yaml");
+    
+    let child = cmd.spawn().map_err(|e| e.to_string())?;
+    
+    // 保存进程句柄
+    Ok(())
+}
+```
+
+## 数据存储
+
+### 配置文件
+
+使用 JSON 格式存储在应用数据目录：
+
+```rust
+// 获取应用数据目录
+let app_dir = app.path().app_data_dir()?;
+let config_path = app_dir.join("config.json");
+```
+
+### SQLite
+
+对于需要查询的数据（如剪贴板历史），使用 `rusqlite` crate：
+
+```toml
+# Cargo.toml
+rusqlite = { version = "0.30", features = ["bundled"] }
+```
+
+## 权限配置
+
+在 `src-tauri/capabilities/default.json` 中配置权限：
+
+```json
+{
+  "$schema": "../node_modules/@tauri-apps/cli/schemas/desktop-capability.json",
+  "identifier": "default",
+  "description": "Default capabilities for the app",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "shell:allow-execute",
+    "shell:allow-spawn",
+    "path:allow-app-data-dir",
+    "path:allow-read",
+    "path:allow-write"
+  ]
+}
+```
+
+## 调试指南
+
+### 前端调试
+
+- 使用 Chrome DevTools：`Ctrl+Shift+I`
+- 打印日志：`console.log()`
+
+### Rust 调试
+
+- 使用 `println!()` 输出到终端
+- 使用 `dbg!()` 宏调试变量
+- 使用 Visual Studio Code 的 Rust 调试插件
+
+### 构建问题排查
+
+1. **Rust 编译错误**：检查 `Cargo.toml` 依赖版本
+2. **前端构建错误**：检查 `package.json` 依赖和 TypeScript 类型
+3. **Tauri 配置错误**：检查 `tauri.conf.json` 路径和权限配置
+
+## 常见问题
+
+### Windows 路径问题
+
+使用 `std::path::Path` 处理路径，避免硬编码分隔符：
+
+```rust
+let path = Path::new("data").join("config.json");
+```
+
+### Tauri 2 权限问题
+
+确保在 `capabilities` 中声明所需权限，否则命令调用会失败。
+
+### WebView2 兼容性
+
+确保用户安装了 Microsoft Edge WebView2 Runtime：
+- 安装包：https://developer.microsoft.com/zh-cn/microsoft-edge/webview2/
+
+## 开发流程
+
+1. **创建模块目录**：`src/modules/<module-name>/` 和 `src-tauri/src/commands/<name>.rs`
+2. **实现前端组件**：创建 Vue 组件和 Pinia store
+3. **实现 Rust 命令**：编写后端逻辑和命令
+4. **注册命令**：在 `lib.rs` 中注册新命令
+5. **配置权限**：更新 `capabilities/default.json`
+6. **测试**：运行 `bun run tauri dev` 测试
+7. **构建**：运行 `bun run tauri build` 构建生产版本
+
+## 模板代码生成
+
+### 快速生成模块
+
+使用以下命令创建新模块结构：
+
+```bash
+# 创建前端模块目录
+mkdir -p src/modules/new-module
+
+# 创建 Rust 命令文件
+touch src-tauri/src/commands/new_module.rs
+```
+
+### 模板文件
+
+复制以下模板快速开始：
+
+**前端组件模板**:
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const loading = ref(false)
+const error = ref('')
+
+const fetchData = async () => {
+  loading.value = true
+  try {
+    // 调用 Rust 命令
+  } catch (e) {
+    error.value = (e as Error).message
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(() => {
+  fetchData()
+})
+</script>
+
+<template>
+  <n-spin :show="loading">
+    <div v-if="error" class="error">{{ error }}</div>
+    <div v-else class="content">
+      <!-- 内容 -->
+    </div>
+  </n-spin>
+</template>
+
+<style scoped>
+.error { color: #f56c6c; padding: 10px; }
+.content { padding: 20px; }
+</style>
+```
+
+**Rust 命令模板**:
+
+```rust
+#[tauri::command]
+pub async fn new_module_action() -> Result<serde_json::Value, String> {
+    // 实现逻辑
+    Ok(serde_json::json!({}))
+}
+```
+
+## 注意事项
+
+1. **避免阻塞主线程**：Rust 命令使用 `async` 避免阻塞
+2. **资源清理**：在组件卸载时清理定时器和事件监听器
+3. **错误处理**：所有操作都应有错误处理和用户提示
+4. **安全考虑**：避免执行未验证的用户输入作为命令参数
+5. **性能优化**：对于高频更新的数据使用 `watch` 和 `computed`
+
+## 参考资源
+
+- [Tauri 2 Documentation](https://v2.tauri.app/)
+- [Vue 3 Documentation](https://vuejs.org/)
+- [Pinia Documentation](https://pinia.vuejs.org/)
+- [Naive UI Documentation](https://www.naiveui.com/)
+- [Rust Documentation](https://doc.rust-lang.org/)

README.md

@@ -1,2 +1,187 @@
-# Thing WIN效率工具
+# Thing
 
+一个基于 Tauri 2 + Vue 3 的 Windows 工具集，集成多个实用功能模块。
+
+## 技术栈
+
+| 层次 | 技术 | 版本 |
+|------|------|------|
+| 框架 | Tauri | 2.x |
+| 前端 | Vue | 3.x |
+| 前端构建 | Vite | 6.x |
+| 状态管理 | Pinia | 2.x |
+| UI 组件 | Naive UI | 2.x |
+| 语言 | TypeScript | 5.x |
+| 后端 | Rust | 2021 Edition |
+| 包管理 | Bun | latest |
+
+## 项目结构
+
+```
+Thing/
+├── public/                    # 静态资源
+├── src/
+│   ├── assets/                # 前端资源
+│   ├── components/            # 通用组件
+│   │   ├── Layout/            # 布局组件
+│   │   └── UI/                # UI 组件
+│   ├── modules/               # 功能模块
+│   │   ├── proxy/             # 代理管理模块
+│   │   ├── clipboard/         # 剪贴板增强模块
+│   │   ├── screenshot/        # 截图模块
+│   │   ├── monitor/           # 硬件监控模块
+│   │   ├── downloader/        # 下载器模块
+│   │   └── finder/            # 文件搜索模块
+│   ├── stores/                # Pinia 状态管理
+│   ├── utils/                 # 工具函数
+│   ├── App.vue                # 主应用组件
+│   ├── main.ts                # 入口文件
+│   └── style.css              # 全局样式
+├── src-tauri/
+│   ├── capabilities/          # Tauri 权限配置
+│   ├── icons/                 # 应用图标
+│   ├── src/
+│   │   ├── commands/          # Rust 命令
+│   │   │   ├── proxy.rs       # 代理相关命令
+│   │   │   ├── clipboard.rs   # 剪贴板相关命令
+│   │   │   ├── screenshot.rs  # 截图相关命令
+│   │   │   ├── monitor.rs     # 监控相关命令
+│   │   │   ├── downloader.rs  # 下载器相关命令
+│   │   │   └── finder.rs      # 文件搜索相关命令
+│   │   ├── modules/           # Rust 模块逻辑
+│   │   ├── utils/             # Rust 工具函数
+│   │   ├── main.rs            # Rust 入口
+│   │   └── lib.rs             # Rust 库入口
+│   ├── Cargo.toml             # Rust 依赖配置
+│   └── tauri.conf.json        # Tauri 配置
+├── package.json               # 前端依赖配置
+├── tsconfig.json              # TypeScript 配置
+└── vite.config.ts             # Vite 配置
+```
+
+## 开发进程规划
+
+### 第一阶段：主体架构（当前阶段）
+
+- [x] 项目初始化
+- [ ] 主界面布局（左侧模块导航 + 右侧内容区域）
+- [ ] 基础设置模块（主题切换、开机自启、语言设置）
+- [ ] 系统托盘（Tray）
+- [ ] 日志系统（Log）
+- [ ] 进程管理架构（子进程生命周期管理）
+- [ ] 模块注册机制
+
+### 第二阶段：核心模块开发
+
+#### 🌐 代理管理
+- [ ] 内置 mihomo (Clash.Meta) 内核集成
+- [ ] 系统代理切换
+- [ ] 规则配置管理
+- [ ] 延迟测速
+- [ ] 订阅管理
+
+#### 📋 剪贴板增强
+- [ ] 剪贴板历史记录
+- [ ] 搜索功能
+- [ ] 固定常用条目
+- [ ] 多格式预览（文本、图片、文件）
+- [ ] SQLite 存储
+
+#### 📸 截图
+- [ ] 区域截图
+- [ ] 窗口截图
+- [ ] 全屏截图
+- [ ] 滚动截图
+- [ ] 图片编辑工具
+
+#### 📊 硬件监控
+- [ ] CPU 使用率监控
+- [ ] GPU 使用率监控
+- [ ] 内存使用率监控
+- [ ] 硬盘温度及使用率
+- [ ] 传感器数据可视化
+
+#### ⬇️ 下载器
+- [ ] HTTP 下载支持
+- [ ] BT/磁力链接支持（aria2）
+- [ ] 下载任务管理
+- [ ] 速度限制
+- [ ] 断点续传
+
+#### 🔍 文件 / 程序搜索
+- [ ] 快速搜索弹窗（快捷键触发）
+- [ ] 文件搜索（Everything SDK）
+- [ ] 应用程序搜索
+- [ ] 拼音模糊匹配
+- [ ] 正则表达式支持
+
+### 第三阶段：优化与完善
+
+- [ ] 性能优化
+- [ ] 错误处理与日志完善
+- [ ] 用户体验优化
+- [ ] 自动更新机制
+- [ ] 打包发布
+
+## 模块管理架构
+
+项目采用模块化架构，每个模块独立开发，通过统一的注册机制接入主界面：
+
+1. **左侧导航栏**：显示所有已注册模块的名称和图标
+2. **右侧内容区域**：显示当前选中模块的详细设置和功能界面
+3. **模块注册**：通过配置文件或代码注册模块信息（名称、图标、组件路径、权限等）
+
+## 构建与运行
+
+### 前置依赖
+
+- Node.js >= 18
+- Rust >= 1.75
+- Bun（推荐）或 npm/yarn
+- Windows SDK（用于 Tauri 构建）
+
+### 开发模式
+
+```bash
+# 安装依赖
+bun install
+
+# 启动开发服务器
+bun run tauri dev
+```
+
+### 生产构建
+
+```bash
+# 构建前端
+bun run build
+
+# 构建应用
+bun run tauri build
+```
+
+## 开发规范
+
+### 代码风格
+
+- TypeScript 代码遵循 ESLint 规则
+- Rust 代码遵循 `cargo fmt` 规范
+- 提交信息使用 Conventional Commits 格式
+
+### 命名规范
+
+- 组件：PascalCase（如 `ProxyManager.vue`）
+- 函数：camelCase（如 `getSystemProxy()`）
+- 文件：kebab-case（如 `proxy-manager.ts`）
+- 常量：UPPER_CASE（如 `MAX_HISTORY_COUNT`）
+
+### 分支策略
+
+- `main`：主分支，稳定版本
+- `develop`：开发分支，整合各模块开发
+- `feature/*`：功能分支，单个模块开发
+- `bugfix/*`：修复分支，bug 修复
+
+## 许可证
+
+MIT License