Skip to content

Releases: buptanswer/KB-Folder-Manager

KB Folder Manager v3.2.1 发布说明

14 Feb 03:39
@buptanswer buptanswer
v3.2.1
6c5cf5e

Choose a tag to compare

View all tags
KB Folder Manager v3.2.1 发布说明 Latest
Latest

KB Folder Manager v3.2.1 发布说明

发布日期: 2026-02-14
版本号: v3.2.1
类型: Bug 修复版本

重点修复：Mutual Validation 树形视图显示问题

v3.2.1 专注于修复一个在 v3.2.0 中引入的严重 GUI 显示 bug，该 bug 导致 Mutual (Doc/Res Consistency) 验证后的批量修复功能完全不可用。

问题描述

症状

在执行 Mutual (Doc/Res Consistency) 验证时：

  • ✅ 系统能够成功检测到 Doc/Res 不一致问题
  • ✅ 自动跳转到 Repair 标签页
  • ❌ "Issue Comparison" 树形视图完全空白
    • 看不到任何数据行
    • 看不到列标题
    • 看不到任何界面元素
    • 键盘导航（方向键、Ctrl+A）完全无响应

影响范围

  • Mutual 验证: 批量修复功能完全不可用（高严重度）
  • Compare 验证: 工作正常（未受影响）

根本原因

tkinter Widget Parent 层级设置错误

# ❌ 问题代码 (v3.2.0)
self.repair_tree = ttk.Treeview(
    list_frame,  # 1. 树先创建在 list_frame
    columns=tree_columns,
    ...
)
...
tree_container = ttk.Frame(list_frame)  # 2. 后创建中间容器
tree_container.grid(row=0, column=0, sticky=NSEW)
...
self.repair_tree.pack(in_=tree_container, ...)  # 3. 用 in_ 参数尝试改变 parent

问题本质:

  • tkinter 的 widget 必须在创建时就明确唯一的 parent
  • 事后通过 pack(in_=...) 或 grid(in_=...) 改变 parent 关系会导致渲染系统失效
  • 虽然不会抛出异常，但会导致控件无法正确渲染

解决方案

修正控件创建顺序，确保 parent 层级清晰

# ✅ 修复代码 (v3.2.1)
# 1. 先创建容器
tree_container = ttk.Frame(list_frame)
tree_container.grid(row=0, column=0, sticky=NSEW)

# 2. 树直接在容器中创建
self.repair_tree = ttk.Treeview(
    tree_container,  # parent 明确为 tree_container
    columns=tree_columns,
    show="headings",
    ...
)

# 3. 滚动条也在同一容器中
scrollbar = ttk.Scrollbar(tree_container, orient=VERTICAL, ...)
h_scrollbar = ttk.Scrollbar(tree_container, orient=HORIZONTAL, ...)

# 4. pack 布局不需要 in_ 参数
self.repair_tree.pack(side=LEFT, fill=BOTH, expand=YES)
scrollbar.pack(side=RIGHT, fill=Y)
h_scrollbar.pack(side=BOTTOM, fill=X)

调试过程

本次 bug 的修复经历了六个诊断阶段：

  1. 数据流验证 - 检查是否数据未传递 → 数据正常
  2. 数据详情验证 - 检查是否缺少 size/mtime/hash → 详情完整
  3. UI 更新机制验证 - 尝试强制刷新 → 无效
  4. Tab 可见性验证 - 改变加载顺序 → 无效
  5. Widget 几何信息诊断 - 检查渲染状态 → 发现 bbox 异常但非根因
  6. Widget Parent 层级检查 - 发现 parent 设置混乱 → 问题解决！

完整的诊断过程和技术细节请查看：MUTUAL_VALIDATION_TREEVIEW_FIX.md

配套修改

为了使 Mutual 验证能够提供完整的问题详情用于修复，还进行了以下配套修改：

  1. execute_validate() 调用修改

    • Mutual 模式改为调用 analyze_doc_res_repair_operation
    • 替代原来的 validate_mutual_operation（后者只返回日志，不返回结构化问题数据）

  2. check_operation_results() 结果处理

    • 新增 validate_mutual 返回 CompareAnalysisResult 的处理分支
    • 与 Compare 验证保持一致的修复流程

验证结果

修复前 (v3.2.0)

用户操作: 执行 Mutual 验证 → 发现问题 → 自动跳转 Repair 标签页
结果: 树形视图完全空白
  - 看不到列标题
  - 看不到数据行
  - 无法选择或导航
  - Selected: 1/1 显示正确，但界面无任何可见元素

修复后 (v3.2.1)

用户操作: 执行 Mutual 验证 → 发现问题 → 自动跳转 Repair 标签页
结果: 树形视图正常显示
  ✅ 列标题可见
  ✅ 数据行正确渲染（路径、size、mtime、hash、hint）
  ✅ 滚动条正常工作
  ✅ 选择和导航功能正常
  ✅ 批量修复功能完全可用

代码质量改进

本次版本还清理了修复过程中产生的调试代码：

移除的调试代码

  • 所有 print("[DEBUG] ...") 日志语句
  • 不必要的 update_idletasks(), update(), see() 调用
  • 冗余的几何信息检查代码

删除的临时测试文件

  • test_gui_actual_run.py
  • test_gui_deep_debug.py
  • test_gui_fix_verification.py
  • test_gui_full_simulation.py
  • test_gui_mapping.py
  • test_instructions.py
  • test_mutual_issue.py
  • test_treeview_simple.py

经验总结

tkinter Widget 创建的正确模式

# ✅ 正确: 父容器 → 子控件 → 布局
parent_container = ttk.Frame(root)
parent_container.grid(row=0, column=0, sticky=NSEW)  # 父容器先布局

child_widget = ttk.Widget(parent_container)  # 子控件明确指定 parent
child_widget.pack(side=LEFT, fill=BOTH, expand=YES)  # 子控件布局
# ❌ 错误: 先创建子控件，后改变 parent
child_widget = ttk.Widget(wrong_parent)
correct_container = ttk.Frame(root)
child_widget.pack(in_=correct_container)  # 企图改变 parent - 可能导致渲染失败

关键教训

  1. Widget 的 parent 关系必须在创建时确定，不能事后修改
  2. 对照实验很重要：Compare 工作但 Mutual 不工作 → 说明是 Mutual 特有的代码问题
  3. 分层诊断：从数据流 → UI 更新 → 布局层级，逐层排查
  4. 几何信息诊断：winfo_*() 和 bbox() 方法是定位渲染问题的有力工具

受益功能

修复后，以下功能完全可用：

  • ✅ Mutual (Doc/Res Consistency) 验证的问题检测
  • ✅ Mutual 验证结果的可视化展示
  • ✅ Doc/Res 不一致问题的批量修复
  • ✅ 问题类型筛选和策略选择
  • ✅ 修复操作的 preview 和应用

升级建议

强烈建议所有 v3.2.0 用户升级到 v3.2.1

如果您在使用 v3.2.0 时遇到以下情况，请立即升级：

  • Mutual 验证后看不到任何问题列表
  • Repair 标签页的树形视图为空
  • 无法使用 Doc/Res 不一致问题的批量修复功能

相关文档

发布团队: buptanswer
发布日期: 2026-02-14

Assets 2
Loading

KB Folder Manager v3.2.0 发布说明

12 Feb 17:07
@buptanswer buptanswer
v3.2.0
7f4b321

Choose a tag to compare

View all tags
KB Folder Manager v3.2.0 发布说明

KB Folder Manager v3.2.0 发布说明

发布日期: 2026-02-12
版本号: v3.2.0
类型: 工作流增强版本

重点更新：校验后批量修复

v3.2.0 将原先“仅检查问题”的流程升级为“检查 + 批量修复”的闭环。

新增 Repair 标签页

  • 在 GUI 执行 Validate -> Compare 后，若发现问题，会自动切换到 Repair 页
  • Validate(mutual/class2)、Split/Merge 前置校验失败时，也会自动生成可修复问题并切换到 Repair
  • 可按问题类型查看并批量多选路径
  • 为选中项指定统一修复策略并一次性执行

支持的批量修复策略

  • mtime differs but hash same
    • 用文件夹1时间对齐文件夹2
    • 用文件夹2时间对齐文件夹1
  • content mismatch（统一覆盖原 size/hash mismatch）
    • 用文件夹1覆盖文件夹2
    • 用文件夹2覆盖文件夹1
  • missing file in new / extra file in new
    • 复制补齐到另一侧
    • 或按基准侧删除选中项
  • missing/extra dir 与 missing/extra placeholder
    • 按侧创建目录
    • 删除空目录
  • doc/res 修复
    • 错侧文件搬移并补对应占位符
    • 缺失占位符补齐
    • 孤立占位符删除
  • complete 修复
    • 去除占位符后缀命名（重命名）
    • 删除符号链接

后端升级

  • 新增 Compare 结构化问题模型，支持 GUI 直接消费问题列表
  • 新增批量修复引擎与修复日志输出（Repair.log）
  • Compare 中 mtime 比对增加 1 秒容差，避免仅亚秒抖动导致误报
  • Compare 索引阶段恢复细粒度进度日志（避免“长时间无反馈”）
  • Logger 增加线程安全写入，保证并行索引日志稳定

GUI 一致性优化

  • Split / Merge / Validate / Repair / Index 均提供“当前页内联日志框”
  • 统一底部状态与活动动画显示；修复状态回调递归导致的卡顿风险
  • Repair 列表改为左右并排展示 size / mtime / hash 字段，便于快速决策
  • doc/res 根目录名不一致时不再强制改名：Merge（以及 CLI 的 Mutual）改为“风险提示 + 用户确认”后可继续
  • 当名称不一致且继续合并时，输出目录默认采用 Doc 侧名称，行为可预期

测试与验证

新增自动化测试：

  • tests/test_compare_repair.py
    • 验证 Compare 问题识别（mtime/hash/size/missing/extra）
    • 验证批量修复后再次 Compare 可消除对应问题
  • tests/test_gui_batch_repair_flow.py
    • 模拟用户在 GUI 中执行 Compare -> Repair 的批量修复点击流程
    • 覆盖 Validate(mutual) 与 Split 前置校验失败后自动跳转 Repair
  • tests/test_gui_log_capture.py
    • 覆盖状态回调递归风险，确保 GUI 进度/活动动画稳定
  • tests/test_cli_smoke.py
    • 覆盖 CLI 帮助、compare 阻断错误码、index 成功路径

本次完整回归（2026-02-12）执行并通过：

  • python -m unittest discover tests -v
  • python tests/test_gui_launch.py
  • python tests/test_gui.py
  • python tests/test_gui_batch_repair_flow.py
  • python tests/test_progress_feedback.py

发布团队: buptanswer
发布日期: 2026-02-12

Loading

KB Folder Manager v3.1.0 发布说明

11 Feb 14:15
@buptanswer buptanswer
v3.1.0
1b44ed6

Choose a tag to compare

View all tags
KB Folder Manager v3.1.0 发布说明

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）：

$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

Loading

KB Folder Manager v3.0 发布说明

30 Jan 12:45
@buptanswer buptanswer
v3.0
e661b01

Choose a tag to compare

View all tags
KB Folder Manager v3.0 发布说明

KB Folder Manager v3.0 发布说明

发布日期: 2026-01-30
版本号: v3.0
类型: 重大功能更新

🎉 重大更新：图形用户界面（GUI）

KB Folder Manager v3.0 的最大亮点是全新的图形用户界面，让知识库管理变得前所未有的简单！

新增功能

1. 现代化 GUI 界面

  • ✨ 基于 ttkbootstrap 的精美界面设计
  • 🎨 多种主题可选（深色/浅色）
  • 📊 实时进度条和状态显示
  • 📝 可视化日志输出

2. 多标签页设计

GUI 包含 5 个功能标签页：

  • Split（拆分） - 将 Complete 目录拆分为 Doc 和 Res
  • Merge（合并） - 将 Doc 和 Res 合并回 Complete
  • Validate（校验） - 验证文件夹结构合规性（4 种模式）
  • Index（索引） - 生成文件夹索引和哈希值
  • Settings（设置） - 配置文件管理

3. 启动方式

# 方法 1：脚本启动（推荐）
python kb_folder_manager_gui.py

# 方法 2：模块方式（需要设置 PYTHONPATH）
$env:PYTHONPATH = "$PWD"
python -m kb_folder_manager.gui

技术实现

新增文件

  • kb_folder_manager/gui.py (873 行) - 完整的 GUI 实现
  • kb_folder_manager_gui.py - GUI 入口脚本
  • tests/test_gui.py (432 行) - 自动化 GUI 测试

新增依赖

ttkbootstrap>=1.20.0  # 现代 GUI 框架
pillow>=10.0.0        # 图像支持

🔧 Bug 修复

  • ScrolledText 导入错误 - 修复 GUI 启动失败问题

📦 依赖变更

新增依赖

  • ttkbootstrap >= 1.20.0 - 提供现代化 GUI 组件
  • pillow >= 10.0.0 - GUI 图像支持

现有依赖

  • PyYAML >= 6.0（保持不变）

📝 重要说明

向后兼容

  • ✅ 完全向后兼容 v2.8
  • ✅ CLI 功能保持不变
  • ✅ 配置文件格式不变

使用建议

  • 🆕 新用户：推荐从 GUI 开始
  • 🔧 高级用户：建议使用 CLI 进行自动化
  • 📊 大批量处理：推荐 CLI + 脚本

🚀 升级指南

# 拉取最新代码
git pull origin main

# 安装新依赖
pip install -r requirements.txt --upgrade

# 测试 GUI
python kb_folder_manager_gui.py

发布团队: buptanswer
发布日期: 2026-01-30

Loading

KB Folder Manager v2.8

30 Jan 09:12
@buptanswer buptanswer
v2.8
74e8c0f

Choose a tag to compare

View all tags
KB Folder Manager v2.8

KB Folder Manager v2.8

首次公开发布版本

✨ 主要功能

  • Split（拆分） - 将知识库拆分为文档和资源
  • Merge（合并） - 将拆分的内容合并回原目录
  • Validate（校验） - 验证文件夹结构是否合规
  • Index（索引） - 生成带哈希值的索引文件

🎯 核心特性

  • ✅ Complete 目录严格只读保护
  • ✅ 占位符机制保留原始结构
  • ✅ 闭环操作流程（预检 → 确认 → 执行 → 后检）
  • ✅ SHA256 哈希校验
  • ✅ 支持 7-Zip 压缩
  • ✅ YAML 灵活配置
  • ✅ 详细的中文文档

🚀 快速开始

安装

git clone https://github.com/buptanswer/KB-Folder-Manager.git
cd KB-Folder-Manager
pip install -r requirements.txt

基本使用

# 拆分知识库
python kb_folder_manager.py split --source "D:\MyKB" --output-root "D:\Output"

# 合并回原位置
python kb_folder_manager.py merge --doc-root "D:\Output\doc" --res-root "D:\Output\res" --output-root "D:\FinalOutput"

# 校验文件夹结构
python kb_folder_manager.py validate --path "D:\MyKB"

# 生成索引
python kb_folder_manager.py index --path "D:\MyKB" --output "index.json"

📚 文档

💻 系统要求

  • Python 3.10 或更高版本
  • Windows 操作系统
  • 7-Zip（可选，用于压缩功能）

📝 版本说明

这是首个公开发布的稳定版本，包含完整的核心功能和详细文档。

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

发布日期：2026-01-30

Loading