feat: release v3.1.0 with performance optimizations

- Enhanced parallel processing for indexing and file operations.
- Introduced environment variable `KBFM_MAX_WORKERS` for configurable concurrency.
- Updated documentation and release notes for v3.1.0.
- Fixed GUI title and test outputs to reflect the new version.
- Improved logging and error handling during file operations.

Author: buptanswer

CHANGELOG.md

@@ -4,6 +4,23 @@
 
 完整的发布说明请查看：[docs/release-notes/](./docs/release-notes/)
 
+## [3.1.0] - 2026-02-11
+
+### 改进
+- **核心性能并行化优化** 🚀
+  - `build_index` 引入多线程并行哈希计算，自动按 CPU 核心数分配 worker
+  - `split` / `merge` 文件复制改为并行执行，提升大文件夹处理效率
+  - `doc/res`、`old/new` 等双目录索引改为并行构建，缩短等待时间
+  - 索引输出改为按路径排序，保证并行执行下结果稳定可复现
+- **并行度可配置**
+  - 新增环境变量 `KBFM_MAX_WORKERS`，支持手动限制或放大 worker 数
+- **版本一致性**
+  - 新增包级版本常量 `kb_folder_manager.__version__`
+  - GUI 标题和测试输出改为统一读取版本常量
+
+### 修复
+- 修复索引完成日志不可达的问题（`build_index` 返回前日志丢失）
+
 ## [3.0.1] - 2026-01-30
 
 ### 改进

README.md

@@ -1,8 +1,8 @@
 # KB Folder Manager
 
-一个为个人知识库整理和管理而设计的 Windows/Python 工具，提供文件夹分割、合并、校验和索引功能。**v3.0 新增精美的图形用户界面（GUI）！**
+一个为个人知识库整理和管理而设计的 Windows/Python 工具，提供文件夹分割、合并、校验和索引功能。**v3.1.0 引入并行加速，显著提升大目录处理速度。**
 
-📖 **文档导航**: [用户指南](./docs/user-guide.md) | [开发者指南](./docs/developer-guide.md) | [发布说明](./docs/release-notes/v3.0.md) | [更新日志](./CHANGELOG.md)
+📖 **文档导航**: [用户指南](./docs/user-guide.md) | [开发者指南](./docs/developer-guide.md) | [发布说明](./docs/release-notes/v3.1.0.md) | [更新日志](./CHANGELOG.md)
 
 ## 功能特性
 
@@ -180,7 +180,7 @@ KB-Folder-Manager/
 ### 主要文档
 - **[用户指南](./docs/user-guide.md)** - 完整的用户使用手册（含安装、配置、GUI、CLI）
 - **[开发者指南](./docs/developer-guide.md)** - 开发文档（含架构、测试、贡献指南）
-- **[发布说明 v3.0](./docs/release-notes/v3.0.md)** - v3.0 版本更新详情
+- **[发布说明 v3.1.0](./docs/release-notes/v3.1.0.md)** - v3.1.0 版本更新详情
 - **[更新日志](./CHANGELOG.md)** - 完整的版本更新记录
 
 ### 历史文档
@@ -192,7 +192,7 @@ KB-Folder-Manager/
 详细问题解答请参考 [用户指南 - 常见问题章节](./docs/user-guide.md#常见问题)。
 
 **快速答案**：
-- **如何处理大量文件？** - 可以分批处理，或使用 `--force` 参数
+- **如何处理大量文件？** - v3.1.0 已支持并行加速；可通过 `KBFM_MAX_WORKERS` 调整并发度
 - **占位符的作用？** - 标记原始位置，避免合并时出现问题
 - **如何验证正确性？** - 查看生成的 `.kb_index.json` 索引文件
 - **其他操作系统？** - 主要针对 Windows，Linux/Mac 可尝试但需调整
@@ -221,6 +221,16 @@ Created by buptanswer
 
 ## 更新日志
 
+### v3.1.0 (2026-02-11)
+- 🚀 **并行性能优化（CPU 利用率提升）**
+  - 索引阶段支持多线程并行哈希计算，自动按 CPU 核心数分配 worker
+  - Split/Merge 文件复制改为并行执行，提升大批量文件吞吐
+  - 双目录索引场景（Doc/Res、Compare）改为并行构建
+  - 新增 `KBFM_MAX_WORKERS` 环境变量，可手动控制并行度
+- 🧩 **版本管理优化**
+  - 新增统一版本常量 `kb_folder_manager.__version__`
+  - GUI 标题与测试输出改为引用统一版本号
+
 ### v3.0 (2026-01-30)
 - 🎉 **新增图形用户界面 (GUI)**
   - 基于 ttkbootstrap 的现代化界面设计
@@ -248,4 +258,4 @@ Created by buptanswer
 
 ---
 
-**最后更新：** 2026年1月30日 | **版本：** v3.0
+**最后更新：** 2026年2月11日 | **版本：** v3.1.0

docs/README.md

@@ -14,7 +14,8 @@ KB-Folder-Manager/
 │   ├── user-guide.md               # 完整用户指南（整合）
 │   ├── developer-guide.md          # 开发者指南
 │   └── release-notes/
-│       └── v3.0.md                 # 版本发布说明
+│       ├── v3.0.md                 # 版本发布说明（历史）
+│       └── v3.1.0.md               # 最新版本发布说明
 └── KB-Folder-Manager项目文档/      # 历史文档（保留）
     └── ...
 ```

docs/developer-guide.md

@@ -2,7 +2,7 @@
 
 > 完整的开发文档，涵盖架构、测试、贡献指南
 
-**版本**: 3.0 | **更新日期**: 2026-01-30
+**版本**: 3.1.0 | **更新日期**: 2026-02-11
 
 ---
 
@@ -122,7 +122,8 @@ KB-Folder-Manager/
 │   ├── user-guide.md           # 用户指南
 │   ├── developer-guide.md      # 开发者指南（本文档）
 │   └── release-notes/          # 发布说明
-│       └── v3.0.md
+│       ├── v3.0.md
+│       └── v3.1.0.md
 ├── CHANGELOG.md                # 更新日志
 └── README.md                   # 项目说明
 ```
@@ -496,16 +497,18 @@ Docs: 更新安装文档
 
 ### 性能考虑
 
-- 大文件哈希计算：使用流式读取（8KB 块）
+- 大文件哈希计算：使用流式读取（1MB 块）+ 多线程并行哈希
 - GUI 线程模型：后台线程避免界面冻结
-- 日志输出：使用队列缓冲，避免频繁刷新
+- Split/Merge 复制：使用线程池并行复制
+- 双目录索引：支持并行构建（doc/res、old/new）
+- 并行度控制：支持环境变量 `KBFM_MAX_WORKERS`
 
 ### 已知限制
 
 1. **平台支持**: 主要针对 Windows 优化
 2. **大文件**: 超大文件（>10GB）哈希计算较慢
-3. **并发**: 不支持并行处理多个文件夹
+3. **I/O 设备限制**: 机械硬盘或网络盘可能成为性能瓶颈
 
 ---
 
-**最后更新**: 2026-01-30 | **版本**: 3.0
+**最后更新**: 2026-02-11 | **版本**: 3.1.0

docs/release-notes/v3.1.0.md

@@ -0,0 +1,57 @@
+# KB Folder Manager v3.1.0 发布说明
+
+**发布日期**: 2026-02-11  
+**版本号**: v3.1.0  
+**类型**: 性能优化版本
+
+---
+
+## 🚀 重点更新：并行性能优化
+
+v3.1.0 聚焦于大目录处理性能，目标是提升 CPU 利用率并缩短整体处理时长。
+
+### 核心优化项
+
+#### 1. 索引并行化
+- `build_index` 新增多线程并行哈希计算
+- 自动按 CPU 核心数分配 worker
+- 索引结果按路径排序，确保并行场景输出稳定
+
+#### 2. Split / Merge 复制并行化
+- 文件复制由串行改为线程池并行执行
+- 在大量小文件和混合文件场景下显著提升吞吐
+
+#### 3. 双目录索引并行构建
+- `doc/res`、`old/new` 等场景支持并行索引
+- 缩短预检和对比阶段等待时间
+
+#### 4. 并行度可配置
+- 新增环境变量 `KBFM_MAX_WORKERS`
+- 可按设备能力手动调整并发度
+
+示例（PowerShell）：
+```powershell
+$env:KBFM_MAX_WORKERS=16
+python kb_folder_manager.py split --source "D:\Data\MyKB" --output-root "D:\Output\SplitRun"
+```
+
+---
+
+## 🧩 工程化改进
+
+- 新增包级版本常量 `kb_folder_manager.__version__`
+- GUI 标题与测试输出统一读取版本常量
+- 修复索引完成日志不可达问题
+
+---
+
+## 📝 升级建议
+
+1. 先直接使用默认并发配置（自动按 CPU 核心数）
+2. 若磁盘是机械盘，可适当降低 `KBFM_MAX_WORKERS`
+3. 若是 NVMe SSD 且 CPU 核心数较多，可逐步提高 `KBFM_MAX_WORKERS` 做压测
+
+---
+
+**发布团队**: buptanswer  
+**发布日期**: 2026-02-11

docs/user-guide.md

@@ -2,7 +2,7 @@
 
 > 完整的用户使用手册，涵盖安装、配置、GUI 和 CLI 使用
 
-**版本**: 3.0 | **更新日期**: 2026-01-30
+**版本**: 3.1.0 | **更新日期**: 2026-02-11
 
 ---
 
@@ -514,7 +514,7 @@ A: 大文件操作时，GUI 使用后台线程保持响应，查看进度条确
 
 **Q: 操作很慢？**
 
-A: 正常现象，文件拷贝和哈希计算需要时间，查看日志确认进度
+A: v3.1.0 已引入并行加速。可先确认使用最新版；如需手动调优，可设置环境变量 `KBFM_MAX_WORKERS`（例如 PowerShell：`$env:KBFM_MAX_WORKERS=16`）
 
 ---
 
@@ -546,4 +546,4 @@ A: 正常现象，文件拷贝和哈希计算需要时间，查看日志确认
 
 ---
 
-**最后更新**: 2026-01-30 | **版本**: 3.0
+**最后更新**: 2026-02-11 | **版本**: 3.1.0

kb_folder_manager/__init__.py

@@ -1 +1,3 @@
-__all__ = []
+__version__ = '3.1.0'
+
+__all__ = ['__version__']