KVTree：您的终极 QuickKV 词库可视化管理器

KVTree (KVT) 是一款强大的桌面端效率工具，专为 QuickKV (QKV) 用户设计。它允许您在任何 Markdown 笔记软件（如 Obsidian、Logseq、Typora）中，通过直观的无序列表（大纲）树来优雅地管理海量词库。

KVT 会在后台静默运行，自动将您笔记中的大纲结构实时编译为 QuickKV 标准词库并输出到指定目录。无论是十几个词条还是百万量级的海量数据，KVTree 都能让您对“词库里到底有什么词”了如指掌。

📖 查看 KVTree 更新日志 (CHANGELOG)

---

✨ 核心特性

• ⚡ 无感热更新：开启自动监控后，您在 Obsidian/Logseq 按下 Ctrl+S 的瞬间，KVTree 会在后台亚秒级完成增量扫描，并将最新词库同步完毕。
• ⚙️ 双引擎过滤控制面板: 独家原创的“内容剔除”与“整行屏蔽”双选面板，取代老旧的繁琐输入框。支持一行一行分离并配置专属正则黑名单，像剥洋葱一样剥除您笔记中的废话！
• 💻 无级平滑体验: 原生级渲染系统支持通过鼠标滚轮无限滑动超大数据集列表，并能在关掉后自动记忆您的偏好窗口大小，无需反复拖拽。
• 🌲 智能 AST 树形解析：摒弃粗暴的正则匹配，采用先进的抽象语法树 (AST) 算法。完美识别 单行、父与子、不包含父 三种复杂的提取逻辑，保证词库结构 100% 还原您的笔记逻辑。
• 🛡️ 生产级数据安全：原子级写入技术确保即便在生成词库的瞬间遭遇突发断电，也绝不会导致词库文件损坏或变成 0KB。
• 🎨 现代化 Fluent 交互设计：完全摒弃传统丑陋的开源脚本界面。全面引入微软 Fluent Design 设计语言，双标签页布局，带有详尽的悬浮提示帮助（Tips），真正实现“小白式”体验。
• 🔎 支持 Logseq md 版键值识别：独家支持页面任意位置的属性键与值扫描（如键 keys:: 和值 [[values]]），让 Logseq 用户的属性键或带双方的值也能瞬间转化为 QKV 高频词条，方便复用 Logseq md的键值。

---

🚀 极速上手指南

一图看懂功能演示V0.5-V0.9版：

第 1 步：标记您的笔记

在任意 .md 笔记的行尾，打上 #KV树-词库名称 格式的标签。

提取模式后缀介绍：

• 默认（无后缀）：仅将当前这一行提取为单条词条。
• -父与子：将当前无序列表节点 及其所有子节点 全部分别提取为词条。
• -不包含父：跳过当前节点，仅将其下方的所有子节点提取为独立词条。

举个例子 待办事项.md：

- 工作项目 #KV树-我的项目-父与子
    - 撰写报告
    - 回复邮件
- 读书清单 #KV树-我的读书-不包含父
    - 聪明的投资者
    - 漫步华尔街

第 2 步：一键生成

1. 运行 kv_tree_app.py 启动 KVT 控制台界面。
2. 添加笔记源：点击“添加文件”或“添加文件夹”，将刚才的 待办事项.md（或您整个笔记库文件夹）加入左侧监控列表。
3. 设置输出目录：建议直接选择 QuickKV 软件本体下的自动载入文件夹。
4. 启动引擎：点击【🚀 立即全量扫描并重建词库】！

不出 2 秒，您的指定目录下就会完美生成两个崭新的纯文本词库文件，它们能被快速输入工具无缝读取：

#KV树-我的项目.md:

- 工作项目
- 撰写报告
- 回复邮件

#KV树-我的读书.md:

- 聪明的投资者
- 漫步华尔街

---

🛠️ 纯净运行环境（官方推荐）

为了避免依赖冲突卡顿和数据污染，KVT 为您配置了标准化的 Python 独立虚拟环境（venv）。

如果您获取了代码源码，请在主目录下使用终端执行此条命令启动，方可获得最沉浸、最稳固的运行体验：

.\venv\Scripts\python kv_tree_app.py

👨‍💻 开发者指南

本项目欢迎社区开发者参与贡献。以下是深入了解并参与 KVTree 开发的快速指南。

🛠️ 技术栈 (Tech Stack)

• 核心语言: Python 3.10+
• GUI 框架: Flet (基于 Flutter 的现代 Python UI 框架，提供精美的 Fluent Design 交互体验)
• 文件监控系统: watchdog (实现毫秒级的无感热更新)
• 数据管理层: 标准化抽象语法树 (AST) 与本地缓存策略
• 打包工具: PyInstaller

💡 核心技术点 (Core Technical Points)

1. 智能 AST 树形解析 (src/logic/ast_parser.py): 摒弃脆弱的单纯正则匹配，采用自构建的多叉树（AST）模型精确还原 Markdown 无序列表的层级关系，精准支持提取“单节点”、“父与子”和“不包含父”等复杂逻辑。
2. 多源多态数据处理 (src/logic/logseq_parser.py): 支持各类标准 Markdown 语法的通用解析，同时深度兼容 Logseq 的 keys:: 页面属性范式，自动去重与过滤系统属性。
3. 响应式状态管理 (src/core/app_state.py): 彻底将底层业务轮询状态与界面的渲染解耦，通过集中化的事件派发器 (task_dispatcher.py)，保证在扫描海量节点库时 UI 始终保持丝滑响应，避免主线程卡死阻塞。
4. 亚秒级无感监控 (src/logic/file_monitor.py): 借助硬件级别的系统文件操作事件订阅（替代高开销的轮询），实现用户触发 Ctrl+S 时即刻增量更新目标词库。

📁 项目结构 (Project Structure)

目前 src 源码的推荐阅读顺序如下：

KVTree/
├── kv_tree_app.py        # 程序入口文件（包含主运行逻辑）
├── README.md             # 项目说明文档
├── CHANGELOG.md          # 更新日志
└── src/                  # 核心源代码目录
    ├── core/             # 核心应用状态机与总线（起点）
    │   ├── app_state.py      # 全局状态字典与管理器
    │   └── task_dispatcher.py# 任务异步分发与生命周期调度
    ├── ui/               # 用户交互界面层（视图层）
    │   ├── main_window.py    # 主窗体与双标签页视图入口
    │   ├── components.py     # 可复用的 Fluent UI 按钮面板等控件
    │   └── tray_icon.py      # 系统托盘与后台常驻模块
    ├── logic/            # 业务逻辑与数据处理层（核心引擎）
    │   ├── ast_parser.py     # 抽象语法树构建与解析器
    │   ├── logseq_parser.py  # Logseq 专属属性解析特化处理
    │   ├── file_monitor.py   # 后台文件修改热更新监控
    │   ├── cache_manager.py  # 增量扫描缓存机制（防抖与提速）
    │   └── config_manager.py # 用户配置的持久化与读取读写
    └── utils/            # 通用基础工具类
        └── file_utils.py     # 安全的文件读写落地与防损方案

🧩 构建可执行文件 (Build EXE)

如果您想将其完全便携化发给朋友，在没有 Python 环境的电脑上绿色运行：

1. 激活项目中自带的虚拟环境：

   .\venv\Scripts\Activate.ps1

2. 安装编译插件（如果尚未安装）：

   pip install pyinstaller

3. 使用项目自带的 spec 文件一键构建（文件夹模式）：

   pyinstaller KVTree.spec --noconfirm

4. 构建完成后，产物位于 dist/KVTree/ 目录：

   dist/KVTree/
   ├── KVTree.exe      ← 双击即启动，秒开！
   └── _internal/      ← 运行时依赖（请勿删除）
   

5. 分发时，将整个 KVTree/ 文件夹打包为 ZIP 即可。收到的人解压后双击 KVTree.exe 即可无痛运行。

Caution

请勿使用 --onefile 单文件模式构建！ 单文件模式会将所有依赖打包进一个巨型 EXE，每次启动时需解压到临时目录。在 Windows 10/11 下，Windows Defender 实时保护会对这些新解压出的 .dll / .pyd 文件逐一扫描，导致首次启动延迟 1~5 分钟，严重影响用户体验。文件夹模式（onedir）仅首次构建时写入文件，后续启动无需解压，可实现秒级冷启动。