从无到有：使用 AI 工具 TRAE 完成批量重命名工具项目

donoot

65人浏览 · 2026-07-10 23:59:58

donoot · 2026-07-10 23:59:58 发布

引言

在软件开发领域，AI 工具正逐渐成为开发者的得力助手，最近开始接触到免费的TRAECN开发工具。本文以一个批量重命名工具项目为例，详细记录如何使用 TRAE AI 工具从无到有完成一个可发布到 GitHub 的完整项目。

项目背景与需求分析

初始需求

我的硬盘里存有大量收集的电子书，网上很多工具软件不符合我的使用习惯，所以希望独自开发一个批量重命名工具，具备以下核心功能：

遍历指定目录下的 epub、pdf 等文件
批量更改文件名，去掉指定字符串
支持增添扩展名类型
可任意设置要更改的前缀、后缀、中间任意字符串

需求演进

随着开发的深入，我发现有些地方还可以改进，随着使用频率不断升高，我也开始不断提出新的需求：

添加 GUI 图形界面
增加撤销/后退功能
增加显示找到文件列表
增加替换指定字符串功能
文件扩展名也可更改
增强前后缀功能
完善异常处理机制

开发流程

阶段一：项目初始化与核心功能开发

需求：创建项目结构，实现基础重命名功能

TRAE 操作：

使用 Write 工具创建项目目录结构
创建核心模块：file_scanner.py、renamer.py、cli.py、main.py
创建测试模块：tests/test_renamer.py、tests/test_scanner.py
创建项目配置文件：pyproject.toml、requirements.txt、.gitignore

关键文件：

file_scanner.py - 文件扫描模块
renamer.py - 重命名核心模块
cli.py - 命令行接口
main.py - 主入口文件

功能实现：

支持移除前缀、后缀、任意字符串
支持自定义扩展名列表
冲突检测与跳过机制
空文件名保护

阶段二：添加 GUI 图形界面

需求：为项目添加友好的图形界面

TRAE 操作：

创建 gui.py 模块，使用 tkinter 构建界面
重构 main.py，实现 CLI 和 GUI 的自动切换
添加多标签页界面（配置、文件列表、预览）

关键文件：

gui.py - 图形界面模块

功能实现：

目录选择对话框
配置参数输入框
文件列表显示
重命名预览表格
执行重命名按钮

阶段三：修复相对导入问题

问题：直接运行 python src/main.py 时出现相对导入错误

TRAE 操作：

修改 main.py，添加双重导入机制
优先使用相对导入，失败时回退到绝对导入

修复代码：

try:
    from .file_scanner import scan_directory
except ImportError:
    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
    from src.file_scanner import scan_directory

阶段四：增加撤销/后退功能

需求：增加恢复原文件名的撤销功能

TRAE 操作：

创建 history.py 模块，实现历史记录管理
修改 main.py，在执行重命名后保存历史记录
在 GUI 和 CLI 中添加撤销入口

关键文件：

history.py - 历史记录管理模块

功能实现：

自动保存重命名历史到 .rename_history.json
支持多次撤销（栈结构）
文件检测与冲突处理
CLI 和 GUI 均支持撤销操作

阶段五：增强文件列表显示与替换功能

需求：增加文件列表显示，增加替换指定字符串功能

TRAE 操作：

在 GUI 中新增"文件列表"标签页
在 renamer.py 中新增 replace_string 函数
在 main.py 中增加 replace 参数
在 CLI 中新增 --replace 参数

功能实现：

选择目录后自动显示匹配文件列表
支持替换字符串（格式：旧字符串:新字符串）
支持多组替换

阶段六：深度优化与功能增强

需求：文件扩展名也可更改，增强前后缀功能，完善异常处理

TRAE 操作：

在 renamer.py 中新增 replace_extension、add_prefix、add_suffix 函数
扩展 generate_new_filename 支持所有新参数
增加正则表达式和忽略大小写选项
增加 Windows 非法字符检测
重构 RenameResult，增加状态字段区分不同情况

功能实现：

扩展名替换（支持替换所有或指定扩展名）
添加前缀/后缀功能
正则表达式支持
忽略大小写匹配
文件名合法性检测（非法字符、保留名称、长度限制）
状态管理（NO_MATCH、NO_CHANGES、HAS_CHANGES、ERROR）

阶段七：修复参数名冲突错误

问题：generate_new_filename 函数中参数名 add_suffix 与函数名冲突

TRAE 操作：

将参数名改为 prefix_to_add 和 suffix_to_add
更新所有调用处

阶段八：修复替换字符串预览问题

问题：GUI 预览时无异常处理，导致程序崩溃

TRAE 操作：

在 gui.py 的 _preview 方法中添加异常处理
在 renamer.py 的正则表达式编译处添加异常处理

阶段九：修复移除字符串分隔符问题

问题：使用逗号作为分隔符时，无法输入包含逗号的字符串

TRAE 操作：

将分隔符从逗号 , 改为分号 ;
更新 GUI 标签提示

阶段十：修复移除字符串后空格处理问题

问题：移除字符串后，原字符串周围的空格未清理

TRAE 操作：

在 remove_string 函数中添加空格清理逻辑
将多个连续空格合并为一个，去掉首尾空格

技术架构设计

项目结构

ChangeFileName/
├── src/                    # 源代码目录
│   ├── __init__.py         # 包初始化
│   ├── file_scanner.py     # 文件扫描模块
│   ├── renamer.py          # 重命名核心模块
│   ├── cli.py              # 命令行接口
│   ├── gui.py              # 图形界面模块
│   ├── history.py          # 历史记录管理
│   └── main.py             # 主入口文件
├── tests/                  # 单元测试目录
│   ├── __init__.py
│   ├── test_renamer.py
│   ├── test_scanner.py
│   └── test_history.py
├── docs/                   # 文档目录
│   └── USAGE.md            # 使用说明手册
├── .gitignore              # Git 忽略文件
├── LICENSE                 # MIT 开源许可证
├── README.md               # 项目说明文档
├── pyproject.toml          # Python 项目配置
└── requirements.txt        # Python 依赖文件

核心模块职责

模块	职责	关键功能
`file_scanner.py`	扫描目录中的文件	根据扩展名过滤文件
`renamer.py`	重命名核心逻辑	移除/替换字符串、添加前后缀、扩展名替换
`cli.py`	命令行接口	参数解析、命令行交互
`gui.py`	图形界面	用户界面、预览、执行
`history.py`	历史记录管理	保存、加载、撤销历史
`main.py`	主入口	调用核心逻辑、协调 CLI/GUI

关键设计决策

模块化架构：将功能拆分为独立模块，便于维护和扩展
纯函数设计：核心重命名逻辑使用纯函数，便于测试和复用
状态管理：使用 RenameResult 数据类统一返回结果
双重入口：支持 CLI 和 GUI 两种运行模式
历史持久化：使用 JSON 文件保存历史记录
异常处理：全面的异常捕获和错误提示

遇到的问题与解决方案

问题 1：相对导入错误

现象：直接运行 python src/main.py 时出现 ImportError: attempted relative import with no known parent package

解决方案：使用双重导入机制，优先相对导入，失败时回退到绝对导入

问题 2：参数名与函数名冲突

现象：generate_new_filename 函数中参数名 add_suffix 与函数名 add_suffix 冲突，导致 'str' object is not callable

解决方案：将参数名改为 suffix_to_add，避免命名冲突

问题 3：分隔符冲突

现象：使用逗号作为分隔符时，无法输入包含逗号的字符串

解决方案：将分隔符改为分号 ;

问题 4：空格清理

现象：移除字符串后，原字符串周围的空格保留，导致文件名中出现多余空格

解决方案：使用正则表达式将多个连续空格合并为一个，并去掉首尾空格

问题 5：异常未处理

现象：GUI 预览时遇到异常直接崩溃，没有错误提示

解决方案：在关键操作处添加 try-except 块，弹出友好的错误对话框

GitHub 项目结构规范

必须包含的文件

README.md - 项目说明文档，包含项目介绍、安装方法、使用说明
LICENSE - 开源许可证，推荐使用 MIT License
.gitignore - Git 忽略规则，排除临时文件、编译产物等
pyproject.toml - Python 项目配置，支持 pip 安装
requirements.txt - Python 依赖列表

目录结构规范

代码质量保证

单元测试：覆盖核心功能，确保代码正确性
类型提示：使用 Python 类型提示，提高代码可读性
文档字符串：为函数和类添加详细的文档字符串
异常处理：全面的异常捕获和错误处理

使用说明

安装方式

# 克隆项目
git clone https://github.com/yourusername/ChangeFileName.git

# 安装到本地
cd ChangeFileName
pip install .

# 直接使用命令
batch-rename /path/to/directory -p "前缀_"

命令行使用

# 基本用法
batch-rename /path/to/directory -p "前缀_" -s "_后缀" -r "需要移除的字符串"

# 替换字符串
batch-rename /path/to/directory --replace "旧名称:新名称"

# 替换扩展名
batch-rename /path/to/directory --replace-ext pdf:epub

# 添加前缀/后缀
batch-rename /path/to/directory --add-prefix "2024_" --add-suffix "_final"

# 使用正则表达式
batch-rename /path/to/directory -p "^[0-9]+_" --regex

# 忽略大小写
batch-rename /path/to/directory --replace "Old:New" --ignore-case

# 撤销操作
batch-rename /path/to/directory -u