上上周在火车上用 OpenCode 加字节的 Seed2.0-pro 模型，vibe coding 出一个小软件，用于办公文件的存档及历史版本管理。起了个名字叫做 Kit 文件存档助手。

它可以帮助用户针对指定目录中的文件进行一键存档、版本控制、忽略监视和历史回溯。适合非程序员、写作者、设计师、以及需要频繁修改文件的场景使用。

主要功能

• 一键存档
  
  : 快速将工作目录中的当前状态保存为一个版本，自动排除临时文件和无用目录及忽视文件列表中的文件及目录。
• 版本历史与日志
  
  :
• 自动编制递增的版本号。
• 支持为版本添加 Markdown格式 的修改说明和自定义标签。
• 清晰显示每次存档的时间和备注，随时查看历史操作记录。
• 文件回溯
  
  : 轻松选中历史版本，一键安全恢复，将工作目录还原到指定状态。
• 状态监视
  
  : 在图形界面中高亮显示工作目录各文件的实时状态（新增、修改、删除、不变）。支持手动刷新和后台自动监视。
• 忽视文件规则
  
  : 类似 Git 的 .gitignore，可自定义需要忽略的文件或目录，避免存档不必要文件，支持通配符。
• 存储空间优化
  
  : 使用 硬链接 (Hard Links) 技术处理不同版本中未发生改变的文件。无论你存了多少个版本，只要文件没变，就不会造成额外的硬盘空间开销。
• 格式通用
  
  : 适用于绝大多数文件类型，无论是文本代码还是图片、音频等二进制文件，均可存档。

安装与运行

本工具的 GitHub 库：https://github.com/tsingkk/kit-fvaa

你可以通过以下两种方式之一运行本程序：

方式一：直接运行可执行文件（Windows 用户）

无需安装 Python 环境，直接下载单文件可执行程序即可运行：

1. 从 github 仓库 release 下载最新版本的 kit-fvaa-xxx.exe，存放至指定目录中；

2. 双击运行即可。

注意：程序运行后会在同一目录下生成 fvaa_config.json 文件，此为程序所需文件，记录打开目录的历史，需保留。

方式二：从源码运行

本工具用 Python 开发，用 Python 环境直接运行程序脚本既可使用。

1. 克隆本仓库或下载源码:

   git clone https://github.com/tsingkk/kit-fvaa.git  cd kit-fvaa

2. 安装必要的 Python 依赖库，执行以下命令安装依赖：

   pip install ttkbootstrap markdown tkhtmlview

3. 运行程序:

   python main.py

程序界面

使用指南

1. 选择工作目录:

• 点击“选择目录”按钮，指定你需要进行版本管理的本地文件夹。

• 历史记录: 软件会自动记住最近打开过的 5 个目录，你可以直接通过下拉列表快速切换。

2. 状态刷新与监视:

• 自动监视: 选择目录后，软件会自动开启后台监视，并根据文件变动实时刷新状态。

• 手动控制: 你可以点击“停止监视”来暂停自动更新，或点击“开始监视”重新开启；点击“刷新状态”可随时手动触发一次全量比对。

• 忽视文件: 点击“忽视文件”按钮，可以设置不需要存档和监视的文件规则（支持 *.log 等通配符，配置保存在 .fvaa/.fvaaignore 中）。

3. 编辑说明与存档:

• 点击“编辑存档说明”，可以使用 Markdown 编写本次存档的详细日志。

• 点击“一键存档”生成新版本，存档文件会安全地存放在工作目录下的 .fvaa 隐藏文件夹中。

4. 版本管理与回溯:

• 在右侧“版本历史”面板中，可以查看所有的存档版本。

• 添加标签: 在标签输入框填入文本并点击“添加标签”，可为选中的重要版本打上标记（如 Release v1.0）。

• 查看说明: 点击版本列表中的“说明”列，可弹窗查看渲染后的 Markdown 文档。

• 恢复版本: 选中需要恢复的历史版本，点击“恢复版本”即可将工作目录一键还原到该版本状态。

5. 操作历史:

• 左侧面板会记录每一次成功的存档和恢复操作，点击相应的历史记录可以快速回顾过去的操作流程。

• 存档记录以绿色高亮，恢复记录以棕色高亮，方便区分。

工作原理与文件结构

• 差异比对: 核心类 VersionControl 会遍历目录并计算文件的 MD5 哈希值，结合文件修改时间精准判断文件变更状态。对于设为“忽视”的文件夹，程序将直接跳过遍历，保障检索速度。

• 本地存储机制: 所有的版本数据及配置全部集中保存在工作目录下的 .fvaa/ 隐藏文件夹中，按需生成，不会污染系统的其他地方。

• .fvaa/versions/ : 按版本号（1, 2, 3…）分别存储不同时期的文件副本。

• .fvaa/manifest.json : 存储版本元数据、标签映射表以及完整的操作历史日志。

• .fvaa/cache.json : 当前工作区文件的状态缓存，用于快速对比。

• .fvaa/.fvaaignore : 用户自定义的忽视文件配置列表。

• 硬链接优化策略: 每次新建存档时，如果文件与上一个版本相比 MD5 相同（即未发生变化），系统会优先使用操作系统底层的 os.link 为文件创建硬链接，直接指向上一版本的文件位置。这避免了重复拷贝，极大提高了运行效率并节约了磁盘空间。

欢迎关注本号：