CloudDrive Renamer

一款强大的云盘文件批量重命名工具

支持夸克网盘、阿里云盘(待开发)、百度网盘(待开发)的智能化文件管理

---

📖 目录

• 核心特性
• 快速开始
• 功能详解
• 使用指南
• 技术架构
• 二次开发
• 常见问题
• 许可协议

---

✨ 核心特性

🎯 多平台支持

• 夸克网盘 - 完全支持，可立即使用
• 阿里云盘 - 架构已就绪，扩展中
• 百度网盘 - 架构已就绪，扩展中

🔧 强大的重命名规则

1. 替换规则 (Replace)

批量替换文件名中的特定文本，支持大小写敏感和全局替换。

使用场景：

• 统一修改文件前缀：file-v1 → file-v2
• 替换不规范命名：IMG_ → Photo_

配置参数：

{
  search: string;        // 要查找的文本
  replace: string;       // 替换为的文本
  caseSensitive: boolean; // 是否区分大小写
  global: boolean;       // 是否全局替换
}

2. 前缀规则 (Prefix)

为所有文件添加统一前缀，可自定义分隔符。

使用场景：

• 标记项目归属：添加 Project-A_
• 添加日期标记：添加 2025-01-

配置参数：

{
  prefix: string;    // 前缀文本
  separator: string; // 分隔符，默认为空
}

3. 后缀规则 (Suffix)

为文件名（扩展名之前）添加后缀标记。

使用场景：

• 添加版本标记：document → document_v2
• 标注处理状态：image → image_processed

配置参数：

{
  suffix: string;    // 后缀文本
  separator: string; // 分隔符，默认为空
}

4. 编号规则 (Numbering)

自动为文件添加序号，支持自定义格式。

使用场景：

• 照片整理：photo → photo_001, photo_002
• 文档排序：Chapter → 001_Chapter, 002_Chapter

配置参数：

{
  startNumber: number;              // 起始编号
  digits: number;                   // 位数（补零）
  position: 'prefix' | 'suffix';    // 编号位置
  format: string;                   // 格式化模板
  separator: string;                // 分隔符
}

5. 清理规则 (Sanitize)

清除文件名中的非法字符或特定字符集。

使用场景：

• 移除特殊符号：file@#$ → file
• 清理空格和标点：my file!.txt → myfile.txt

配置参数：

{
  removeChars: string;    // 要移除的字符集
  removeIllegal: boolean; // 是否移除非法字符
}

🚀 智能执行引擎

批量处理系统

• 速率控制：800ms 间隔执行，防止 API 限流
• 重试机制：指数退避算法，自动重试失败操作
• 崩溃恢复：异常中断后可继续未完成的任务
• 幂等性保证：避免重复执行相同操作

实时预览功能

• 应用规则前预览所有变更
• 清晰对比原名称与新名称
• 即时调整规则参数，所见即所得

冲突检测

• 自动检测重名冲突
• 智能提示潜在问题
• 保护文件安全

🔒 隐私保护

• 100% 本地处理：所有重命名操作在浏览器本地完成
• 无数据上传：不收集、不传输任何用户数据
• 透明操作：开源代码，完全可审计

---

🚀 快速开始

前置要求

• Node.js >= 18.0
• npm >= 9.0
• Chrome/Edge 浏览器 >= 110

安装步骤

1. 克隆项目

git clone https:///lhly/cloud-drive-renamer.git
cd cloud-drive-renamer

2. 安装依赖

npm install

3. 构建扩展

# 开发模式（支持热重载）
npm run dev

# 生产构建
npm run build

4. 加载到浏览器

1. 打开 Chrome 浏览器
2. 访问 chrome://extensions/
3. 启用右上角的 "开发者模式"
4. 点击 "加载已解压的扩展程序"
5. 选择项目的 dist 目录
6. 扩展安装完成！

快速验证

访问 夸克网盘，选择文件后应能看到批量重命名按钮。

---

📘 使用指南

基础使用流程

1. 打开云盘页面

访问支持的云盘平台（如夸克网盘）。

2. 选择文件

勾选需要重命名的文件或文件夹。

3. 点击重命名按钮

在工具栏或浮动按钮中找到批量重命名功能。

4. 配置规则

选择重命名规则类型并设置参数。

5. 预览结果

查看预览列表，确认所有变更符合预期。

6. 执行重命名

点击确认按钮，系统自动批量执行。

实战示例

示例 1：整理照片集

场景：为旅行照片添加统一前缀和编号

原名称：IMG_001.jpg, IMG_002.jpg, IMG_003.jpg
规则组合：
  1. 前缀规则：prefix="Tokyo2025_"
  2. 编号规则：startNumber=1, digits=3, position="suffix"
结果：Tokyo2025_001.jpg, Tokyo2025_002.jpg, Tokyo2025_003.jpg

示例 2：清理文档命名

场景：移除特殊字符并统一格式

原名称：报告@2024#最终版.docx
规则组合：
  1. 清理规则：removeChars="@#"
  2. 替换规则：search="最终版", replace="Final"
结果：报告2024Final.docx

示例 3：版本管理

场景：为项目文件添加版本后缀

原名称：design.psd, mockup.fig, prototype.xd
规则：后缀规则：suffix="_v2", separator=""
结果：design_v2.psd, mockup_v2.fig, prototype_v2.xd

高级技巧

规则组合使用

多个规则可以叠加应用，执行顺序为配置顺序：

// 组合示例
[
  { type: 'sanitize', params: { removeIllegal: true } },
  { type: 'prefix', params: { prefix: 'Project_' } },
  { type: 'numbering', params: { startNumber: 1, digits: 2 } }
]

格式化模板

编号规则支持自定义格式化：

format: "[{n}]"     // → [001], [002]
format: "No.{n}"    // → No.001, No.002
format: "{n}번"     // → 001번, 002번

---

🏗️ 技术架构

整体架构

┌─────────────────────────────────────────────┐
│           Chrome Extension                  │
├─────────────────────────────────────────────┤
│                                             │
│  ┌─────────────┐      ┌─────────────┐      │
│  │   Popup     │      │  Background │      │
│  │    UI       │◄────►│   Service   │      │
│  └─────────────┘      │   Worker    │      │
│                       └─────────────┘      │
│         ▲                    ▲             │
│         │                    │             │
│         ▼                    ▼             │
│  ┌─────────────────────────────────┐      │
│  │      Content Script              │      │
│  │  ┌────────────┐  ┌────────────┐ │      │
│  │  │ UI Components  Rule Engine │ │      │
│  │  └────────────┘  └────────────┘ │      │
│  │  ┌──────────────────────────┐   │      │
│  │  │   Platform Adapters       │   │      │
│  │  │  • Quark  • Aliyun • Baidu│   │      │
│  │  └──────────────────────────┘   │      │
│  └─────────────────────────────────┘      │
│                   │                        │
└───────────────────┼────────────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │  Cloud Drive API  │
         └──────────────────┘

核心模块

1. 规则引擎 (Rule Engine)

• 职责：规则解析、验证、执行
• 位置：src/rules/
• 关键类：
  • RuleFactory：规则工厂，创建规则实例
  • BaseRule：规则基类，定义通用接口
  • 具体规则实现：ReplaceRule, PrefixRule, 等

2. 平台适配器 (Platform Adapters)

• 职责：封装不同平台的 API 调用
• 位置：src/adapters/
• 设计模式：适配器模式
• 扩展性：新平台只需实现 PlatformAdapter 接口

3. 执行引擎 (Executor)

• 职责：批量任务调度、速率控制、错误处理
• 位置：src/core/executor.ts
• 特性：
  • 任务队列管理
  • 速率限制 (Rate Limiting)
  • 重试策略 (Retry Policy)
  • 崩溃恢复 (Crash Recovery)

4. UI 组件 (UI Components)

• 技术栈：Lit Web Components
• 位置：src/content/components/
• 组件：
  • rename-dialog：主重命名对话框
  • rename-preview：预览列表
  • progress-dialog：进度追踪
  • floating-button：浮动触发按钮

项目结构

src/
├── types/              # TypeScript 类型定义
│   ├── rule.ts         # 规则类型
│   ├── platform.ts     # 平台接口
│   ├── core.ts         # 核心类型
│   └── message.ts      # 消息类型
├── background/         # Background Service Worker
│   └── service-worker.ts
├── content/            # Content Scripts
│   ├── index.ts        # 入口文件
│   └── components/     # Lit Web Components
│       ├── rename-dialog.ts
│       ├── rename-preview.ts
│       ├── progress-dialog.ts
│       └── floating-button.ts
├── adapters/           # 平台适配器
│   ├── base/           # 适配器基类和接口
│   │   └── adapter.interface.ts
│   ├── quark/          # 夸克网盘适配器
│   │   ├── quark.ts
│   │   └── errors.ts
│   ├── aliyun/         # 阿里云盘（规划中）
│   └── baidu/          # 百度网盘（规划中）
├── rules/              # 重命名规则
│   ├── base-rule.ts    # 规则基类
│   ├── rule-factory.ts # 规则工厂
│   ├── replace.ts      # 替换规则
│   ├── prefix.ts       # 前缀规则
│   ├── suffix.ts       # 后缀规则
│   ├── numbering.ts    # 编号规则
│   └── sanitize.ts     # 清理规则
├── core/               # 核心引擎
│   ├── executor.ts     # 批量执行引擎
│   ├── retry.ts        # 重试机制
│   ├── crash-recovery.ts # 崩溃恢复
│   └── conflict-detector.ts # 冲突检测
├── popup/              # Popup 界面
│   ├── popup.ts
│   └── index.html
├── dialog/             # 独立对话框页面
│   └── dialog.ts
└── utils/              # 工具函数
    ├── storage.ts      # 存储抽象
    ├── logger.ts       # 日志系统
    └── helpers.ts      # 辅助函数

技术栈

类别	技术	版本	用途
语言	TypeScript	5.3+	类型安全的开发体验
构建	Vite	5.0+	快速构建和热重载
UI框架	Lit	3.1+	轻量级 Web Components
打包	@crxjs/vite-plugin	2.3+	Chrome 扩展专用打包
测试	Vitest + Playwright	1.6+	单元测试和E2E测试
代码质量	ESLint + Prettier	最新	代码规范和格式化

---

🛠️ 二次开发

开发环境配置

1. 安装依赖

npm install

2. 启动开发模式

npm run dev

开发模式支持热重载，修改代码后自动重新构建。

3. 代码质量检查

# 代码规范检查
npm run lint

# 自动修复代码问题
npm run lint:fix

# 格式化代码
npm run format

# TypeScript 类型检查
npm run typecheck

4. 运行测试

# 单元测试
npm test

# 测试覆盖率
npm run test:coverage

# E2E 测试
npm run test:e2e

# E2E 测试（可视化模式）
npm run test:e2e:ui

扩展新平台

实现平台适配器

1. 在 src/adapters/ 下创建新平台目录
2. 实现 PlatformAdapter 接口

// src/adapters/newplatform/newplatform.ts

import { PlatformAdapter } from '../base/adapter.interface';
import { FileItem } from '../../types/platform';

export class NewPlatformAdapter implements PlatformAdapter {
  // 获取当前选中的文件列表
  async getSelectedFiles(): Promise<FileItem[]> {
    // TODO: 实现文件列表获取逻辑
  }

  // 执行重命名操作
  async renameFile(fileId: string, newName: string): Promise<void> {
    // TODO: 实现重命名 API 调用
  }

  // 验证文件名合法性
  validateFileName(fileName: string): boolean {
    // TODO: 实现文件名验证规则
  }

  // 检测当前是否在目标平台页面
  isCurrentPlatform(): boolean {
    return window.location.hostname === 'newplatform.com';
  }
}

注册平台适配器

在 manifest.json 中添加 content script 配置：

{
  "content_scripts": [
    {
      "matches": ["https://newplatform.com/*"],
      "js": ["src/content/index.ts"],
      "run_at": "document_idle"
    }
  ],
  "host_permissions": [
    "https://newplatform.com/*"
  ]
}

添加新规则

实现规则类

// src/rules/custom-rule.ts

import { BaseRule } from './base-rule';

export interface CustomRuleParams {
  // 定义规则参数
  paramA: string;
  paramB: number;
}

export class CustomRule extends BaseRule {
  constructor(private params: CustomRuleParams) {
    super();
  }

  execute(fileName: string, index: number, total: number): string {
    // TODO: 实现规则逻辑
    return fileName; // 返回处理后的文件名
  }

  validate(config: CustomRuleParams): boolean {
    // TODO: 实现参数验证
    return true;
  }
}

注册到规则工厂

// src/rules/rule-factory.ts

import { CustomRule } from './custom-rule';

export class RuleFactory {
  static create(config: RuleConfig): RuleExecutor {
    switch (config.type) {
      // ... 其他规则
      case 'custom':
        return new CustomRule(config.params as any);
      default:
        throw new Error(`Unknown rule type: ${config.type}`);
    }
  }
}

更新类型定义

// src/types/rule.ts

export type RuleType =
  | 'replace'
  | 'prefix'
  | 'suffix'
  | 'numbering'
  | 'sanitize'
  | 'custom'; // 添加新规则类型

调试技巧

1. Chrome DevTools

// 在代码中添加调试信息
console.log('[CloudDrive Renamer]', data);

在 Chrome DevTools 中可以看到所有日志输出。

2. 使用断点

在 Chrome DevTools 的 Sources 面板中，可以直接在扩展代码中设置断点。

3. 查看扩展状态

访问 chrome://extensions/ 可以查看扩展加载状态、错误信息、权限等。

4. 热重载

开发模式下修改代码后：

1. 代码自动重新构建
2. 在 chrome://extensions/ 点击刷新按钮
3. 刷新目标网页即可看到变更

代码规范

TypeScript 规范

• 所有公共 API 必须有类型注解
• 优先使用 interface 而非 type
• 使用严格的 tsconfig.json 配置

命名规范

• 类名：PascalCase（如 RuleFactory）
• 方法名：camelCase（如 getSelectedFiles）
• 常量：UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）
• 文件名：kebab-case（如 rule-factory.ts）

注释规范

/**
 * 规则工厂类
 * 负责根据配置创建对应的规则实例
 */
export class RuleFactory {
  /**
   * 创建规则实例
   * @param config - 规则配置对象
   * @returns 规则执行器实例
   * @throws {Error} 当规则类型未知时抛出错误
   */
  static create(config: RuleConfig): RuleExecutor {
    // ...
  }
}

测试指南

单元测试示例

// src/rules/__tests__/prefix-rule.test.ts

import { describe, it, expect } from 'vitest';
import { PrefixRule } from '../prefix';

describe('PrefixRule', () => {
  it('should add prefix to filename', () => {
    const rule = new PrefixRule({ prefix: 'test_' });
    const result = rule.execute('file.txt', 0, 1);
    expect(result).toBe('test_file.txt');
  });

  it('should add prefix with separator', () => {
    const rule = new PrefixRule({
      prefix: 'test',
      separator: '-'
    });
    const result = rule.execute('file.txt', 0, 1);
    expect(result).toBe('test-file.txt');
  });
});

E2E 测试示例

// tests/e2e/rename.spec.ts

import { test, expect } from '@playwright/test';

test('should rename files on Quark drive', async ({ page }) => {
  await page.goto('https://pan.quark.cn/list#/list/all');

  // 选择文件
  await page.click('.file-checkbox');

  // 打开重命名对话框
  await page.click('.rename-button');

  // 配置规则
  await page.fill('#prefix-input', 'test_');

  // 预览
  await page.click('.preview-button');
  await expect(page.locator('.preview-item')).toContainText('test_');

  // 执行
  await page.click('.execute-button');
  await expect(page.locator('.success-message')).toBeVisible();
});

贡献指南

我们欢迎各种形式的贡献！

提交 Issue

• Bug 报告：详细描述复现步骤和环境信息
• 功能建议：说明使用场景和预期效果
• 文档改进：指出不清楚或有误的地方

提交 Pull Request

1. Fork 项目仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交变更：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

PR 要求：

• 通过所有测试：npm test
• 代码规范检查：npm run lint
• 添加必要的测试用例
• 更新相关文档

---

❓ 常见问题

安装和使用

Q: 为什么安装后找不到重命名按钮？

A: 请检查：

1. 扩展是否正确加载（访问 chrome://extensions/ 确认）
2. 是否访问了支持的网盘平台
3. 是否选中了文件
4. 刷新页面后重试

Q: 为什么重命名失败？

A: 可能的原因：

1. 网络连接问题
2. 新文件名与现有文件冲突
3. 文件名包含非法字符
4. 云盘 API 限流

解决方案：扩展会自动重试，如果持续失败，请查看浏览器控制台日志。

Q: 是否支持文件夹重命名？

A: 目前版本支持文件和文件夹的批量重命名。

隐私和安全

Q: 扩展会上传我的文件名或数据吗？

A: 不会。所有处理都在本地完成，不会向任何第三方服务器发送数据。

Q: 为什么需要存储权限？

A: 用于保存用户的规则配置和崩溃恢复数据，所有数据存储在浏览器本地。

Q: 为什么需要访问云盘网站的权限？

A: 扩展需要在云盘页面注入 UI 组件和调用云盘 API，这些都在浏览器沙箱环境中运行。

开发相关

Q: 如何添加对新云盘平台的支持？

A: 请参考 扩展新平台 章节。

Q: 如何贡献代码？

A: 请参考 贡献指南 章节。

Q: 遇到 Bug 如何报告？

A: 请在 GitHub Issues 中提交，包含：

• 浏览器版本
• 扩展版本
• 复现步骤
• 错误截图或日志

---

🗺️ 路线图

当前版本 (v0.1.0)

• ✅ 夸克网盘支持
• ✅ 5 种基础重命名规则
• ✅ 实时预览功能
• ✅ 批量执行引擎

计划中 (v0.2.0)

• 🔄 阿里云盘完整支持
• 🔄 百度网盘完整支持
• 🔄 规则模板保存与分享
• 🔄 历史记录和撤销功能

未来展望 (v1.0.0+)

• 📋 正则表达式规则
• 📋 条件规则（基于文件类型/大小）
• 📋 批量任务调度

---

📄 许可协议

本项目基于 MIT License 开源。

---

🙏 致谢

感谢所有贡献者和用户的支持！

特别感谢：

• Lit - 出色的 Web Components 框架
• Vite - 极速构建工具
• CRXJS - Chrome 扩展开发利器

---

📞 联系我们

• 问题反馈：GitHub Issues
• 功能建议：GitHub Discussions
• 邮件联系：lhlyzh@qq.com

---

如果这个项目对你有帮助，请给我们一个 ⭐️

Made with ❤️ by 冷火凉烟