# AI Agent 开发指南

本文档为 AI Agent 开发本项目提供详细的规范和模板，帮助快速理解项目结构、技术栈和开发流程。

## 项目概览

- **项目名称**: Thing
- **技术栈**: Tauri 2 + Vue 3 + Vite + Pinia +  shadcn-vue + Rust
- **平台**: Windows
- **包管理**: Bun

## 核心架构

### 模块系统

项目采用统一的模块注册机制。每个模块通过 `src/modules/<name>/index.ts` 导出 `ModuleConfig` 配置，由 `src/modules/registry.ts` 中的 `moduleRegistry` 单例统一管理。

```
src/modules/<module-name>/
├── index.ts              # 模块配置（ModuleConfig）
├── ModuleComponent.vue   # 前端组件
src-tauri/src/            # Rust 后端逻辑（按功能分文件/模块目录）
```

#### 模块配置类型

```typescript
// src/types/module.ts
interface ModuleConfig {
  id: string                    // 唯一标识
  name: string                  // 显示名称
  icon: string                  // 图标标识（对应 icons.ts 中的 key）
  description: string           // 模块描述
  category: ModuleCategory      // 分类：'network' | 'tool' | 'system' | 'media'
  defaultEnabled?: boolean      // 默认是否启用
  builtin?: boolean             // 是否内置模块（不可禁用）
  loader?: () => Promise<{ default: Component }>  // 懒加载
  component?: Component         // 直接组件引用（内置模块）
  searchItems?: SearchIndexItem[]  // 全局搜索项
  process?: ModuleProcessConfig    // 进程配置（需要子进程的模块）
  lifecycle?: ModuleLifecycle      // 生命周期钩子
  order?: number                   // 排序权重
}
```

#### 注册新模块

1. 创建 `src/modules/<name>/index.ts`，导出 `moduleConfig`
2. 在 `src/modules/index.ts` 中添加导入
3. 在 `src/modules/icons.ts` 中添加图标映射

### 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/module'

export const moduleConfig: ModuleConfig = {
  id: 'module-name',
  name: '模块名称',
  icon: 'module-name',       // 需在 icons.ts 中添加映射
  description: '模块描述',
  category: 'tool',           // 'network' | 'tool' | 'system' | 'media'
  defaultEnabled: true,
  loader: () => import('./ModuleComponent.vue'),
  searchItems: [
    {
      title: '功能名称',
      description: '功能描述',
      keywords: ['关键词1', '关键词2']
    }
  ],
  order: 100
}
```

> 注册模块时，还需在 `src/modules/index.ts` 中添加导入，在 `src/modules/icons.ts` 中添加图标映射。

```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/` 中创建模块文件（如 `src-tauri/src/my_module.rs` 或 `src-tauri/src/my_module/` 目录），并在 `lib.rs` 中注册：

```rust
// src-tauri/src/my_module.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 my_module;

use my_module::{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 插件（见 `Cargo.toml`）：

| 插件 | 用途 |
|------|------|
| `tauri-plugin-autostart` | 开机自启 |
| `tauri-plugin-opener` | 打开文件/目录/URL（绕过 IPC scope 限制） |
| `tauri-plugin-dialog` | 文件/目录选择对话框 |

> 系统托盘（tray）和窗口效果（mica/acrylic）是 Tauri 2 内置能力，无需额外插件。日志系统为自建（`src-tauri/src/logger.rs`），未使用 `tauri-plugin-log`。

## 进程管理

对于需要管理外部子进程的模块（如 mihomo），使用内置的 `ProcessManager`。下载器模块使用进程内自建下载引擎（`src-tauri/src/download_engine/`），不涉及外部子进程：

### 架构

- **Rust 端** (`src-tauri/src/process_manager.rs`)：`ProcessManager` 通过 `std::process::Command` 管理子进程，支持启动、停止、崩溃检测和自动重启
- **前端** (`src/stores/processStore.ts`)：Pinia store，通过 `invoke` 调用 Rust 命令，通过 `listen` 接收进程状态变更事件
- **模块配置**：在模块的 `index.ts` 中通过 `ModuleProcessConfig` 声明进程信息

### 模块配置

```typescript
// src/modules/proxy/index.ts
export const moduleConfig: ModuleConfig = {
  // ...
  process: {
    name: 'mihomo',
    executable: '',           // 运行时确定
    args: ['-f', 'config.yaml'],
    autoStart: false,         // 模块启用时是否自动启动
    restartOnCrash: true,     // 崩溃后自动重启
    maxRestarts: 3            // 最大重启次数（0 = 不限制）
  }
}
```

### 前端 API

```typescript
import { useProcessStore } from '@/stores/processStore'

const processStore = useProcessStore()

// 通过模块 ID 启动进程（自动读取模块配置）
await processStore.startByModule('proxy')

// 停止进程
await processStore.stopByModule('proxy')

// 获取进程状态
const status = processStore.getProcessStatus('proxy')

// 监听状态变更（在 main.ts 中已初始化）
// processStore.initListener()
```

### Rust 命令

| 命令 | 参数 | 返回值 |
|------|------|--------|
| `start_process` | `StartProcessParams` | `ProcessInfo` |
| `stop_process` | `id: String` | `()` |
| `get_process_status` | `id: String` | `Option<ProcessInfo>` |
| `get_all_process_status` | - | `Vec<ProcessInfo>` |
| `stop_all_processes` | - | `()` |

### 事件

| 事件名 | 载荷 | 触发时机 |
|--------|------|----------|
| `process-status-changed` | `ProcessInfo` | 进程状态变更（崩溃、重启、停止） |

## 数据存储

### 配置文件

使用 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": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "opener:default",
    "opener:allow-reveal-item-in-dir",
    "opener:allow-open-path",
    "dialog:default",
    "core:window:allow-minimize",
    "core:window:allow-maximize",
    "core:window:allow-close",
    "core:window:allow-toggle-maximize",
    "core:window:allow-hide",
    "core:window:allow-show",
    "core:window:allow-set-focus",
    "core:window:allow-start-dragging",
    "core:window:allow-set-effects",
    "core:window:allow-set-background-color",
    "core:window:allow-set-theme"
  ]
}
```

## 调试指南

### 前端调试

- 使用 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>/`，编写组件和 `index.ts` 配置
2. **注册模块**：在 `src/modules/index.ts` 中添加导入，在 `src/modules/icons.ts` 中添加图标映射
3. **实现 Rust 命令**：在 `src-tauri/src/` 中编写后端逻辑，在 `lib.rs` 中注册命令
4. **配置权限**：更新 `capabilities/default.json`（如需要）
5. **测试**：运行 `bun run tauri dev` 测试
6. **构建**：运行 `bun run tauri build` 构建生产版本

## 模板代码生成

### 快速生成模块

使用以下命令创建新模块结构：

```bash
# 创建前端模块目录
mkdir -p src/modules/new-module

# 创建 Rust 模块文件
touch src-tauri/src/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>
  <div v-if="loading" class="flex items-center justify-center py-8">
    <Loader2 class="animate-spin text-muted-foreground" :size="24" />
  </div>
  <div v-else-if="error" class="text-destructive p-4">{{ error }}</div>
  <div v-else class="content p-5">
    <!-- 内容 -->
  </div>
</template>
```

**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/)
- [shadcn-vue UI Documentation](https://shadcn-vue.com/docs)
- [Rust Documentation](https://doc.rust-lang.org/)