diff --git a/AI_DEV_GUIDE.md b/AI_DEV_GUIDE.md new file mode 100644 index 0000000..eac390a --- /dev/null +++ b/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// # 前端模块 +src-tauri/src/commands/.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//` 目录,包含以下文件: + +```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 + + + + + + +``` + +### Rust 命令模板 + +创建 `src-tauri/src/commands/.rs`: + +```rust +// commands/module_name.rs +use serde::Serialize; +use tauri::State; + +#[derive(Serialize)] +pub struct CommandResult { + pub success: bool, + pub data: Option, + pub error: Option, +} + +#[tauri::command] +pub async fn module_get_data() -> CommandResult> { + 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 { + 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, Box> { + // 实现逻辑 + Ok(vec![]) +} + +fn save_data(data: &str) -> Result<(), Box> { + // 实现逻辑 + 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//` 和 `src-tauri/src/commands/.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 + + + + + +``` + +**Rust 命令模板**: + +```rust +#[tauri::command] +pub async fn new_module_action() -> Result { + // 实现逻辑 + 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/) diff --git a/README.md b/README.md index 22c5677..31b99ba 100644 --- a/README.md +++ b/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