# 文枢

**Repository Path**: deepin20/FileNexus

## Basic Information

- **Project Name**: 文枢
- **Description**: 文枢（FileNexus）是一款基于PySide6的智能桌面归档工具，旨在帮助用户自动整理桌面文件。它结合关键词规则与机器学习，将文件按「年份/大类/小类」自动归档，并提供实时监控、定时调度、主动学习等高级功能，大幅提升文件管理效率。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文枢 (FileNexus) — 智能桌面归档工具 v2.2.0

**文枢**，一款专为机关、团体、企事业单位打造的智能桌面归档工具。基于 PySide6 构建，支持**多级分类**、**关键词+机器学习双引擎**、**文件监控**与**自动调度**，让文件管理从此优雅高效。

---

## 📖 目录

- [项目简介](#项目简介)
- [版本新特性](#版本新特性)
- [功能特性](#功能特性)
- [安装与运行](#安装与运行)
- [使用教程](#使用教程)
- [规则配置详解](#规则配置详解)
- [机器学习分类](#机器学习分类)
- [常见问题](#常见问题)
- [贡献与反馈](#贡献与反馈)
- [许可证](#许可证)

---

## 项目简介

在日常办公中，桌面文件堆积如山，查找困难、归类混乱是普遍痛点。**文枢 (FileNexus)** 应运而生——它通过**关键词规则匹配**与**机器学习分类**双引擎驱动，自动将桌面文件按“年份/分类树路径”归档到指定目录，同时提供**文件监控**（新文件自动归档）、**定时调度**（定期执行归档任务）和**主动学习**（用户纠错反馈，持续优化分类准确率）三大能力，真正解放双手，让文件管理变得优雅高效。

**版本**：v2.2.0

---

## 版本新特性

- **通用分类体系**：重新设计档案分类规则，适配党委、政府、人大、政协、公检法、企业、事业单位等全场景，符合国家档案局《机关档案管理规定》的规范。
- **多级分类支持**：规则编辑器支持无限层级树形分类，轻松构建“门类 → 属类 → 业务类 → 小类”的精细分类结构。
- **分类确认对话框优化**：支持树形选择任意深度叶子节点，用户反馈更精准。
- **新增专业档案门类**：涵盖信访、审计、统计、自然资源、民政、教育、公安、税务、交通、城管、市监、乡镇等十余个行业。
- **精简一级门类**：合并为文书、科技、会计、专业、声像、电子、实物七大档案门类，管理更清晰。
- **界面全面适配多级分类**：规则管理、分类确认、归档路径均支持多级结构。

---

## 功能特性

| 模块 | 说明 |
|------|------|
| **智能分类引擎** | 支持文件名+文件内容（`.docx`/`.xlsx`/`.pdf`/`.txt`）关键词匹配，权重可调 |
| **机器学习分类** | 基于 TF‑IDF + 逻辑回归，从已归档文件中学习分类模式，准确率持续提升 |
| **主动学习反馈** | 低置信度时弹窗请用户确认，修正记录自动用于模型增量训练 |
| **多级分类体系** | 支持任意层级分类树（如：文书档案 → 党政综合 → 党委会议 → 党委会议记录） |
| **多种归档模式** | 移动 / 复制 / 硬链接 / 符号链接，灵活应对不同备份需求 |
| **文件监控** | 基于 `watchdog`，桌面新文件自动归档，实现“零操作”体验 |
| **自动调度** | 支持每日/每周/每月定时触发归档任务，下班后自动整理 |
| **图形化规则管理** | 树形编辑分类、关键词、权重、匹配逻辑（OR/AND）、正则表达式，实时生效 |
| **归档报告与回滚** | 统计归档记录、类别占比，支持一键回滚到原始位置 |
| **无边框现代界面** | 基于 PySide6 自定义标题栏，支持拖拽、最大化/还原，美观流畅 |
| **归档设置持久化** | 所有配置自动保存至 `~/.config/filenexus/`，重启不丢失 |

---

## 安装与运行

### 环境要求
- Python 3.8 或更高版本
- 支持 Linux / Windows / macOS（推荐 Linux 桌面，如 deepin）

### 方式一：从源码运行（推荐开发/尝鲜）

```bash
# 1. 克隆仓库
git clone https://gitee.com/deepin20/FileNexus.git
cd FileNexus

# 2. 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate      # Linux/macOS
# 或 venv\Scripts\activate   # Windows

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

# 4. 启动
bash start.sh                 # Linux/macOS
# 或 python -m filenexus
```

> **Linux 额外系统依赖**（deepin/Ubuntu/Debian）：
> ```bash
> sudo apt-get install libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxcb-xv0
> ```

### 方式二：安装 DEB 包（推荐 deepin 用户）

```bash
# 在 Releases 页面下载 .deb 包后执行
sudo dpkg -i filenexus_2.2.0_all.deb
sudo apt-get install -f      # 补全依赖
```

安装完成后，可在应用菜单中找到“文枢”，或直接在终端输入 `filenexus` 启动。

---

## 使用教程

### 第一步：首次启动与路径配置

启动软件后，进入 **归档设置** 标签页：

1. **桌面路径**：选择您需要整理的桌面文件夹（默认为 `~/Desktop`）。
2. **归档根目录**：选择归档文件的目标根目录（默认为 `~/Desktop/文件归档`）。
3. **规则文件**：选择分类规则 JSON 文件（首次启动会自动创建默认规则，包含七大门类及多级分类）。

> 💡 **提示**：默认规则已包含“文书档案 / 科技档案 / 会计档案 / 专业档案 / 声像档案 / 电子档案 / 实物档案”七大一级门类，以及“党政综合、行政综合、人事管理、纪检监察、财务管理、业务管理、后勤管理”等二级属类，可直接使用。

### 第二步：设置归档选项

根据需求勾选以下选项：

- **归档模式**：移动 / 复制 / 硬链接 / 符号链接
- **递归处理子文件夹**：是否扫描桌面下的子文件夹
- **保留原始相对路径结构**：在归档目录中重建子文件夹结构
- **归档后删除空文件夹**：移动文件后清理原空目录
- **启用文件内容分析**：解析文档内容辅助分类（支持 `.docx`/`.xlsx`/`.pdf`/`.txt`）
- **启用机器学习分类**：使用训练好的模型进行预测（需先训练）

### 第三步：管理分类规则

进入 **规则管理** 标签页，支持多级树形分类：

- **新建大类**：在根下创建一级门类（如“文书档案”）
- **新建子类**：在选中节点下创建子分类（支持无限层级嵌套，如“文书档案 → 党政综合 → 党委会议”）
- **删除选中**：删除当前节点及其所有子节点
- **编辑关键词**：选中叶子节点后，在右侧添加关键词并设置权重（1~10）
- **匹配逻辑**：选择“任意匹配 (OR)”或“全部匹配 (AND)”
- **保存规则**：将修改写入规则文件

> 💡 **关键词权重说明**：权重越高，匹配该关键词时得分越高。建议核心词汇（如“党委会”、“招商引资”）设 3，一般词汇设 1~2。

### 第四步：预览分类效果

点击 **预览分类** 按钮，软件会模拟运行，在日志中输出每个文件的预测目标路径，不会实际移动文件。**建议在正式归档前先执行预览**，确认分类效果符合预期。

### 第五步：执行归档

确认预览结果无误后，点击 **开始归档**，软件将按照当前设置将桌面文件移动到归档目录。进度条和状态栏会实时反馈进度。

### 第六步：文件监控（零操作归档）

在归档设置中勾选 **启用桌面文件监控**，此后桌面上新增的任何文件都会被自动归档，无需手动操作。监控基于 `watchdog` 实现，资源占用极低。

### 第七步：自动调度

勾选 **启用定时归档**，设置频率（每日/每周/每月）和时间，软件会在后台按计划自动执行归档任务，适合下班后自动整理。

### 第八步：查看归档报告

进入 **归档报告** 标签页，可查看：

- 总归档记录、文件数、成功/失败统计
- 各类别占比（进度条可视化）
- 历史归档记录表格（时间、文件数、源/目标路径）
- **撤销选中记录**：一键回滚指定归档批次的所有文件

### 第九步：主动学习（提升分类准确率）

当分类置信度低于阈值时，软件会自动弹出**分类确认对话框**，您可以通过树形分类器选择正确的类别，修正记录会自动保存到 `~/.config/filenexus/feedback.jsonl`，用于后续模型增量训练，持续提升准确率。

---

## 规则配置详解

### 规则文件结构（JSON）

```json
{
  "version": "2.0",
  "content_match_threshold": 1,
  "categories": {
    "文书档案": {
      "党政综合": {
        "党委会议": {
          "keywords": ["党委会", "党委扩大会议", "党委会议记录"],
          "weight": 3,
          "logic": "or",
          "regex": false,
          "note": "党委会议相关文件"
        }
      }
    }
  },
  "default_category": {
    "major": "其他文档",
    "sub": "未分类"
  }
}
```

| 字段 | 说明 |
|------|------|
| `version` | 规则版本号 |
| `content_match_threshold` | 文件名匹配得分阈值，≥此值则跳过内容分析 |
| `categories` | 分类树根节点，支持任意层级嵌套 |
| `keywords` | 关键词列表（叶子节点必填） |
| `weight` | 匹配权重（叶子节点必填） |
| `logic` | 匹配逻辑：`or`（任意匹配）或 `and`（全部匹配） |
| `regex` | 是否启用正则表达式匹配 |
| `note` | 备注说明（可选） |
| `default_category` | 无匹配时的默认分类 |

### 关键词匹配规则

- 不区分大小写
- 文件名匹配优先；若得分 ≥ `content_match_threshold`，则不再进行内容分析
- 内容分析支持 `.docx`、`.xlsx`、`.pdf`、`.txt` 格式
- 最终得分 = 命中关键词权重之和，取最高分分类

---

## 机器学习分类

### 训练模型

1. 先用规则匹配归档一批文件到 `归档根目录/年份/分类路径/` 下（每个叶子类别至少 2 个文件）。
2. 在“归档设置” → “分类增强”中勾选 **启用机器学习分类**。
3. 点击 **训练分类器**，软件自动扫描归档目录提取特征并训练模型。
4. 训练完成后，勾选 **启用机器学习分类** 并调整 **ML置信度阈值**（默认 0.6）。

### 主动学习

当分类置信度低于阈值时，软件会自动弹出**分类确认对话框**，您可以通过树形分类器选择正确的类别，修正记录会自动保存并用于后续模型增量训练，持续提升准确率。

---

## 常见问题

### Q1：启动时报错 `libxcb-cursor0` 相关

**原因**：缺少 Qt 依赖库。  
**解决**：执行 `sudo apt-get install libxcb-cursor0`，并安装所有相关 xcb 库（见上文“安装与运行”）。

### Q2：规则保存后重启消失

**检查**：
1. 确保规则文件路径正确且可写（`~/.config/filenexus/rules/default.json`）。
2. 修改规则后务必点击 **保存规则** 按钮。
3. 查看“运行日志”标签页是否有错误提示。

### Q3：归档设置保存后重启恢复默认

**检查**：
1. 确保 `~/.config/filenexus/app_config.json` 文件存在且可写。
2. 修改设置后点击 **保存设置** 按钮。
3. 若仍无效，可手动编辑 `app_config.json` 文件。

### Q4：扫描时程序卡顿或崩溃

**建议**：
1. 在“归档设置”中暂时取消勾选“递归处理子文件夹”和“启用文件内容分析”。
2. 检查桌面是否存在超大文件或损坏的 `.docx` 文件（软件已增加异常处理，但仍建议排查）。
3. 关闭其他占用内存的应用。

### Q5：机器学习训练失败

**检查**：
1. 归档目录中至少需要 2 个已分类文件。
2. 规则文件已正确加载，且分类结构完整。
3. 查看“运行日志”获取详细错误信息。

### Q6：如何恢复默认规则？

```bash
rm ~/.config/filenexus/rules/default.json
# 重启软件，会自动从内置模板复制
```

### Q7：多级分类如何正确归类？

软件会自动将文件归到最末级叶子节点（即包含 `keywords` 的节点）。在规则管理界面，叶子节点会在右侧显示关键词编辑区，中间节点仅显示名称。确保您需要归类的分类都是叶子节点。

---

## 贡献与反馈

- **开发者**：温暖断章
- **邮箱**：180227211@qq.com
- **项目主页**：[https://gitee.com/deepin20/FileNexus](https://gitee.com/deepin20/FileNexus)
- **问题反馈**：欢迎在 Gitee 仓库提交 Issue，或发送邮件至开发者邮箱。

---

## 许可证

本项目采用 **MIT 许可证**，详情请见 [LICENSE](LICENSE) 文件。

---

**让文件管理变得优雅而高效** ✨