ShowDoc MCP Server

---
alwaysApply: true
---

# 批量文件操作优化规则

> 当需要复制、移动或处理大量文件（如图片、资源文件等）时，优先创建批处理脚本，而不是逐个操作文件，以提高效率。

## 核心原则

### 性能优化策略

当用户需要处理大量文件时（如图片、资源文件、批量复制等），应该：

1. **优先创建批处理脚本**
   - 使用 Python、PowerShell 或 Bash 脚本批量处理文件
   - 避免在 Cursor 中逐个操作文件（效率低）

2. **脚本执行方式**
   - 先创建脚本文件
   - 让用户确认脚本内容
   - 然后执行脚本完成批量操作

3. **适用场景**
   - 复制大量图片或资源文件
   - 批量重命名文件
   - 批量移动文件
   - 批量处理文件内容
   - 其他需要操作多个文件的任务

## 实现流程

### 步骤 1：识别批量操作需求

当用户要求处理多个文件时，自动识别为批量操作：

- "复制这些图片"
- "把这些文件移动到..."
- "批量处理这些文件"
- 用户提供了多个文件或文件夹

### 步骤 2：创建批处理脚本

根据操作系统和项目类型选择合适的脚本语言：

- **Windows**：PowerShell (`.ps1`) 或 Python (`.py`)
- **Linux/Mac**：Bash (`.sh`) 或 Python (`.py`)
- **跨平台**：优先使用 Python

### 步骤 3：脚本内容示例

#### Python 脚本示例（跨平台）

```python
import shutil
import os
from pathlib import Path

# 批量复制文件
def batch_copy_files(source_dir, dest_dir, file_pattern="*"):
    source = Path(source_dir)
    dest = Path(dest_dir)
    dest.mkdir(parents=True, exist_ok=True)
    
    for file in source.glob(file_pattern):
        if file.is_file():
            shutil.copy2(file, dest / file.name)
            print(f"已复制: {file.name}")

# 使用示例
if __name__ == "__main__":
    batch_copy_files("source_folder", "dest_folder", "*.png")
```

#### PowerShell 脚本示例（Windows）

```powershell
# 批量复制文件
$sourceDir = "source_folder"
$destDir = "dest_folder"

Get-ChildItem -Path $sourceDir -Filter "*.png" | ForEach-Object {
    Copy-Item $_.FullName -Destination $destDir
    Write-Host "已复制: $($_.Name)"
}
```

### 步骤 4：执行流程

1. **创建脚本文件**
   - 在项目根目录或临时目录创建脚本文件
   - 使用描述性文件名（如 `batch_copy_images.py`）

2. **展示脚本内容**
   - 向用户展示脚本内容
   - 说明脚本的功能和操作路径

3. **用户确认**
   - 等待用户确认脚本内容
   - 如有需要，根据用户反馈修改脚本

4. **执行脚本**
   - 执行脚本完成批量操作
   - 显示执行结果和处理的文件数量

5. **清理脚本（可选）**
   - 询问用户是否保留脚本文件
   - 如果不需要，删除临时脚本文件

## 最佳实践

### 脚本设计原则

1. **错误处理**
   - 检查源文件是否存在
   - 检查目标目录是否可写
   - 处理文件权限问题
   - 提供清晰的错误信息

2. **进度反馈**
   - 显示处理进度（如：已处理 10/100 个文件）
   - 显示处理结果（成功/失败）

3. **日志记录**
   - 记录操作日志
   - 记录失败的文件和原因

4. **可恢复性**
   - 支持断点续传（如需要）
   - 支持撤销操作（如需要）

### 性能优化

1. **批量操作**
   - 使用批量 API 而不是逐个操作
   - 减少文件系统调用次数

2. **并行处理**
   - 对于大量文件，考虑使用多线程/多进程
   - 注意文件系统限制

3. **内存管理**
   - 对于大文件，使用流式处理
   - 避免一次性加载所有文件到内存

## 使用示例

### 示例 1：批量复制图片

```
用户：帮我复制这些图片到 assets/images/ 目录
AI：检测到需要批量复制文件，我将创建一个 Python 脚本来完成这个任务。
AI：[创建 batch_copy_images.py 脚本]
AI：脚本已创建，将复制 50 张图片到 assets/images/ 目录。是否执行？
用户：执行
AI：[执行脚本]
AI：✅ 已成功复制 50 张图片到 assets/images/ 目录
```

### 示例 2：批量移动资源文件

```
用户：把这些资源文件移动到 res/ 目录
AI：我将创建一个批处理脚本来批量移动这些文件。
AI：[创建 batch_move_resources.py 脚本]
AI：脚本已创建，将移动 30 个资源文件。是否执行？
用户：执行
AI：[执行脚本]
AI：✅ 已成功移动 30 个资源文件
```

### 示例 3：批量处理文件内容

```
用户：批量替换这些文件中的文本
AI：我将创建一个脚本来批量处理文件内容。
AI：[创建 batch_replace_text.py 脚本]
AI：脚本已创建，将处理 100 个文件。是否执行？
用户：执行
AI：[执行脚本]
AI：✅ 已成功处理 100 个文件
```

## 注意事项

1. **文件安全**
   - 批量操作前，建议先备份重要文件
   - 确认操作路径和文件列表

2. **权限问题**
   - 检查文件读写权限
   - 处理权限不足的情况

3. **路径处理**
   - 使用绝对路径或相对于项目根目录的路径
   - 处理不同操作系统的路径差异

4. **脚本清理**
   - 临时脚本执行完成后，询问用户是否保留
   - 避免在项目中留下不必要的脚本文件

## 与 Cursor 的协作

### 何时使用脚本

- **大量文件操作**：超过 10 个文件的操作
- **重复性操作**：需要重复执行的操作
- **复杂操作**：需要条件判断、循环等逻辑的操作

### 何时直接操作

- **少量文件**：1-5 个文件可以直接操作
- **简单操作**：单次、简单的文件操作
- **交互式操作**：需要用户实时反馈的操作

---

**说明**：此规则适用于所有项目类型，旨在提高文件操作的效率和可靠性。