Add comprehensive tests for CLI, compare/repair operations, GUI batch repair flow, and log capture

- Implemented CLI smoke tests in `test_cli_smoke.py` to validate help command and compare/repair functionalities.
- Created `test_compare_repair.py` to cover various scenarios for comparing and repairing issues, including handling of file metadata and placeholder management.
- Developed `test_gui_batch_repair_flow.py` to simulate user interactions in the GUI for validating, comparing, and repairing files, ensuring the flow works as expected.
- Added `test_gui_log_capture.py` to verify that log messages are captured correctly without recursion during status updates.

Author: buptanswer

AGENTS.md

@@ -0,0 +1,48 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `kb_folder_manager/` contains core logic:
+  - `operations.py` for split/merge/validate/index workflows
+  - `cli.py` and `gui.py` for user interfaces
+  - `config.py`, `validator.py`, `indexer.py`, and `utils.py` for support layers
+- Root entry points: `kb_folder_manager.py` (CLI) and `kb_folder_manager_gui.py` (GUI).
+- `tests/` includes unit tests plus GUI validation scripts.
+- `docs/` contains user/developer guides and release notes.
+- `config.yaml` stores runtime settings (file types, placeholder suffix, hash algorithm).
+
+## Build, Test, and Development Commands
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+python kb_folder_manager.py --help
+python kb_folder_manager_gui.py
+python -m unittest discover tests
+python tests\test_gui.py
+python tests\test_gui_launch.py
+```
+- Use the first three commands to prepare a local dev environment.
+- Use CLI/GUI commands to verify entry points quickly.
+- Run `unittest` for automated regression checks; run GUI scripts for interaction/startup sanity.
+
+## Coding Style & Naming Conventions
+- Target Python 3.10+ and follow PEP 8 with 4-space indentation.
+- Keep line length near 88 characters.
+- Naming: `PascalCase` for classes, `snake_case` for functions/variables, `UPPER_SNAKE_CASE` for constants.
+- Keep interface files thin; place business rules in `kb_folder_manager/operations.py` and related modules.
+- Add type hints and concise docstrings for public functions when practical.
+
+## Testing Guidelines
+- Primary test framework is `unittest` (`tests/test_basic.py`).
+- Name test files `test_*.py` and test methods `test_*`.
+- Prefer `tempfile`-based test data and avoid machine-specific absolute paths.
+- For GUI changes, run both simulation (`tests/test_gui.py`) and launch smoke test (`tests/test_gui_launch.py`).
+
+## Commit & Pull Request Guidelines
+- Current history mixes styles (`feat: ...`, `Add ...`, `Delete ...`). Prefer consistent `type: summary` messages (`feat`, `fix`, `docs`, `test`, `refactor`).
+- Keep commits focused on one change area.
+- PRs should include purpose, key implementation notes, test commands/results, linked issues, and GUI screenshots when UI behavior changes.
+
+## Configuration & Safety Tips
+- Treat `placeholder_suffix` in `config.yaml` as a reserved marker.
+- Test split/merge workflows on copied data before running against critical knowledge-base folders.

CHANGELOG.md

@@ -4,6 +4,40 @@
 
 完整的发布说明请查看：[docs/release-notes/](./docs/release-notes/)
 
+## [3.2.0] - 2026-02-12
+
+### 新增
+- **Compare 批量修复闭环工作流** 🎯
+  - GUI 新增 `Repair` 标签页，支持在 `Validate -> Compare` 后直接跳转修复
+  - 支持按问题类型筛选、批量多选路径、选择策略后一键修复
+  - 支持的核心修复策略：
+    - `mtime differs but hash same`：old->new / new->old 对齐 mtime
+    - `content mismatch`（统一 size/hash）：old 覆盖 new / new 覆盖 old
+    - `missing file in new`、`extra file in new`：复制补齐或按基准删除
+    - `missing/extra dir`、`missing/extra placeholder`：创建对应目录或删除空目录
+  - 扩展到 `Validate(mutual/class2)` 与 `Split/Merge` 失败场景：可自动生成修复建议并跳转 Repair
+
+### 改进
+- **Compare 结构化问题模型** 🧩
+  - 新增结构化 Compare issue 收集逻辑，统一日志输出与 GUI 修复入口
+  - Compare 问题新增目录与占位符差异的逐项记录
+- **Repair 交互细节打磨**
+  - 修复列表增加两侧 `size / mtime / hash` 摘要列
+  - 新增单条问题详情区与策略建议，减少手动切到资源管理器比对
+  - 修复完成后即时移除当前已修复项（不强制重跑 Compare）
+  - Compare 的 mtime 判断增加 1 秒容差，降低亚秒级误报
+  - Compare 阶段补充进行中动画和开始日志，避免“点击后无反馈”
+  - 新增 `doc/res` 修复策略：错侧文件搬移、缺失占位符补齐、孤立占位符删除
+  - 新增 `complete` 修复策略：占位符后缀命名清理、符号链接删除
+  - `doc/res` 根目录名不一致改为“提示并确认后可继续”，并统一为 Doc 侧名称作为合并输出目录名
+- **GUI 线程结果能力增强**
+  - 后台任务结果支持携带结构化返回值，便于执行后续自动流程（如跳转修复页）
+
+### 测试
+- 新增 `tests/test_compare_repair.py`
+  - 覆盖 Compare 问题识别
+  - 覆盖批量修复（mtime 对齐、覆盖修复、缺失/多余修复）
+
 ## [3.1.0] - 2026-02-11
 
 ### 改进

README.md

@@ -1,19 +1,20 @@
 # KB Folder Manager
 
-一个为个人知识库整理和管理而设计的 Windows/Python 工具，提供文件夹分割、合并、校验和索引功能。**v3.1.0 引入并行加速，显著提升大目录处理速度。**
+一个为个人知识库整理和管理而设计的 Windows/Python 工具，提供文件夹分割、合并、校验、索引与批量修复功能。**v3.2.0 新增“校验后批量修复”闭环工作流。**
 
-📖 **文档导航**: [用户指南](./docs/user-guide.md) | [开发者指南](./docs/developer-guide.md) | [发布说明](./docs/release-notes/v3.1.0.md) | [更新日志](./CHANGELOG.md)
+📖 **文档导航**: [用户指南](./docs/user-guide.md) | [开发者指南](./docs/developer-guide.md) | [发布说明](./docs/release-notes/v3.2.0.md) | [更新日志](./CHANGELOG.md)
 
 ## 功能特性
 
 - **Split（拆分）** - 将 Complete 目录拆分成 Doc（文档）和 Res（资源）两个独立目录
 - **Merge（合并）** - 将 Doc 和 Res 目录合并回 Complete 目录
 - **Validate（校验）** - 验证文件夹结构是否符合规范
+- **Repair（修复）** - 对 Compare、Validate、Split/Merge 前置校验发现的共性问题进行批量修复
 - **Index（索引）** - 生成带哈希值和元数据的索引文件
 
 ## 核心设计原则
 
-- **Complete 目录严格只读** - 保护原始数据完整性
+- **默认保护原目录** - 所有修复都要求用户显式选择策略并确认后执行
 - **占位符机制** - 使用空文件夹作为占位符，标记被移走的文件
 - **闭环操作流程** - 预检 → 用户确认 → 执行 → 后检
 - **哈希校验** - 支持多种哈希算法（默认 SHA256）
@@ -24,7 +25,7 @@
 
 - Python 3.10 或更高版本
 - Windows 操作系统
-- 7-Zip（可选，用于压缩功能）
+- 7-Zip（可选，当前核心流程不依赖）
 
 ### 安装
 
@@ -92,6 +93,11 @@ python kb_folder_manager_gui.py
 
 命令行适合脚本自动化和批量处理。
 
+全局参数（如 `--yes`、`--config`）需要放在子命令前，例如：
+```powershell
+python kb_folder_manager.py --yes split --source "D:\Data\MyKB" --output-root "D:\Output\SplitRun"
+```
+
 #### 拆分（Split）
 将知识库拆分为文档和资源：
 ```powershell
@@ -100,7 +106,7 @@ python kb_folder_manager.py split --source "D:\Data\MyKB" --output-root "D:\Outp
 
 **可选参数：**
 - `--force` - 输出目录非空时继续执行（需谨慎）
-- `--yes` - 跳过确认提示，直接执行
+- `--yes` - 全局参数，跳过确认提示（需写在子命令前）
 
 **输出结构：**
 ```
@@ -116,19 +122,24 @@ OutputRoot/
 #### 合并（Merge）
 将拆分的文档和资源合并回 Complete 目录：
 ```powershell
-python kb_folder_manager.py merge --doc-root "D:\Output\doc" --res-root "D:\Output\res" --output-root "D:\Output\MergeRun"
+python kb_folder_manager.py merge --doc "D:\Output\doc\MyKB" --res "D:\Output\res\MyKB" --output-root "D:\Output\MergeRun"
 ```
 
+**说明：**
+- Doc/Res 根目录名建议一致；若不一致会先提示并要求确认，确认后仍可继续
+- 名称不一致时，输出 `complete/<FolderName>` 默认使用 `doc` 侧文件夹名
+- 交互确认可输入 `y` 或 `yes`；可加全局参数 `--yes` 跳过确认提示
+
 #### 校验（Validate）
 检查文件夹结构是否合规：
 ```powershell
-python kb_folder_manager.py validate --path "D:\Data\MyKB"
+python kb_folder_manager.py validate --mode class1 --target "D:\Data\MyKB" --role complete --log-dir "D:\Output\logs"
 ```
 
 #### 索引（Index）
 为指定目录生成索引：
 ```powershell
-python kb_folder_manager.py index --path "D:\Data\MyKB" --output "index.json"
+python kb_folder_manager.py index --target "D:\Data\MyKB" --output "D:\Output\index.json" --log-dir "D:\Output\logs"
 ```
 
 ## 配置文件
@@ -145,14 +156,14 @@ placeholder_suffix: "(在百度网盘)"
 # 哈希算法选择
 hash_algorithm: "sha256"
 
-# 是否使用 7-Zip 进行压缩操作
+# 是否启用 7-Zip 相关扩展（当前核心流程未使用）
 use_7zip: true
 ```
 
 **重要提示：**
 - `specified_types` 必须为小写并包含点号前缀（如 `.pdf`）
 - `placeholder_suffix` 是保留标记，真实目录名严禁以该后缀结尾
-- 修改配置后重启程序生效
+- CLI 场景修改配置后需重启；GUI 可在 `Settings` 标签页点击重载配置
 
 ## 项目结构
 
@@ -163,24 +174,33 @@ KB-Folder-Manager/
 │   ├── cli.py                 # 命令行接口
 │   ├── config.py              # 配置管理
 │   ├── indexer.py             # 索引生成
-│   ├── operations.py          # 核心操作（split/merge/validate）
+│   ├── operations.py          # 核心操作（split/merge/validate/repair）
 │   ├── utils.py               # 工具函数
 │   └── validator.py           # 校验逻辑
 ├── tests/
-│   └── test_basic.py          # 基础测试
+│   ├── test_basic.py
+│   ├── test_compare_repair.py
+│   ├── test_gui_batch_repair_flow.py
+│   ├── test_gui.py
+│   └── test_gui_launch.py
+├── docs/
+│   ├── user-guide.md
+│   ├── developer-guide.md
+│   └── release-notes/
 ├── kb_folder_manager.py       # 入口文件
+├── kb_folder_manager_gui.py   # GUI 入口文件
 ├── requirements.txt           # 依赖列表
 ├── config.yaml                # 配置文件
-├── README.md                  # 本文件
-└── 用户手册.md                # 详细用户手册
+├── CHANGELOG.md               # 更新日志
+└── README.md                  # 本文件
 ```
 
 ## 文档
 
 ### 主要文档
 - **[用户指南](./docs/user-guide.md)** - 完整的用户使用手册（含安装、配置、GUI、CLI）
 - **[开发者指南](./docs/developer-guide.md)** - 开发文档（含架构、测试、贡献指南）
-- **[发布说明 v3.1.0](./docs/release-notes/v3.1.0.md)** - v3.1.0 版本更新详情
+- **[发布说明 v3.2.0](./docs/release-notes/v3.2.0.md)** - v3.2.0 版本更新详情
 - **[更新日志](./CHANGELOG.md)** - 完整的版本更新记录
 
 ### 历史文档
@@ -193,6 +213,7 @@ KB-Folder-Manager/
 
 **快速答案**：
 - **如何处理大量文件？** - v3.1.0 已支持并行加速；可通过 `KBFM_MAX_WORKERS` 调整并发度
+- **发现大量一致性问题如何快速处理？** - 无论是 Compare、Mutual/Class2 校验失败，还是 Split/Merge 前置校验失败，都可自动进入 `Repair` 批量处理
 - **占位符的作用？** - 标记原始位置，避免合并时出现问题
 - **如何验证正确性？** - 查看生成的 `.kb_index.json` 索引文件
 - **其他操作系统？** - 主要针对 Windows，Linux/Mac 可尝试但需调整
@@ -201,7 +222,20 @@ KB-Folder-Manager/
 
 ### 运行测试
 ```bash
+# 单元测试（含 CLI 烟雾）
 python -m unittest discover tests
+
+# GUI 启动烟雾
+python tests/test_gui_launch.py
+
+# GUI 功能模拟（Split/Merge/Validate/Index）
+python tests/test_gui.py
+
+# GUI Compare->Repair 批量修复全流程模拟
+python tests/test_gui_batch_repair_flow.py
+
+# 进度与状态反馈验证
+python tests/test_progress_feedback.py
 ```
 
 ### 更多开发信息
@@ -221,6 +255,28 @@ Created by buptanswer
 
 ## 更新日志
 
+### v3.2.0 (2026-02-12)
+- 🔧 **新增 Compare 批量修复工作流**
+  - `Validate -> Compare` 后自动进入 `Repair` 标签页
+  - 支持按问题类型筛选与多选路径批量修复
+  - Repair 列表直接展示两侧 `size / mtime / hash` 列与提示信息，便于就地决策
+  - 修复完成后即时移除当前已修复项（不强制重跑 Compare）
+  - 支持 `mtime differs but hash same` 的双向 mtime 对齐
+  - 将 `size/hash` 统一为单一 `content mismatch` 错误并支持双向覆盖修复
+  - 支持 `missing/extra` 的补齐复制或按基准侧删除
+  - 支持 `missing/extra dir` 与 `missing/extra placeholder` 的目录创建/删除修复
+  - 扩展到非 Compare 流程：`Validate(mutual/class2)` 与 `Split/Merge` 失败时自动生成 Repair 方案并跳转
+  - 新增 Doc/Res 纠偏修复（错侧文件搬移、缺失占位符可补齐或删除对应文件、孤立占位符删除、目录差异按侧创建/删除空目录）
+  - 新增 Complete 预检修复（占位符后缀命名清理、符号链接删除）
+- 🧱 **后端能力升级**
+  - 新增结构化 Compare 问题模型（供 GUI 与自动化逻辑复用）
+  - 新增批量修复 API 与修复日志
+- 🖥️ **GUI 体验一致性优化**
+  - Split / Merge / Validate / Repair / Index 全部提供当前页内联日志框
+  - 比较索引阶段恢复细粒度进度输出（不再长时间无反馈）
+  - 长耗时阶段在无新日志时追加轻量 `running...` 心跳提示
+  - 修复日志回调递归风险，确保进度与状态动画稳定显示
+
 ### v3.1.0 (2026-02-11)
 - 🚀 **并行性能优化（CPU 利用率提升）**
   - 索引阶段支持多线程并行哈希计算，自动按 CPU 核心数分配 worker
@@ -258,4 +314,4 @@ Created by buptanswer
 
 ---
 
-**最后更新：** 2026年2月11日 | **版本：** v3.1.0
+**最后更新：** 2026年2月12日 | **版本：** v3.2.0

docs/README.md

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