# pdfManager

**Repository Path**: liu_yizhe/pdf-manager

## Basic Information

- **Project Name**: pdfManager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-29
- **Last Updated**: 2026-01-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# PDFer - 轻量级 PDF 标签管理器

** Warnning **
所有代码都是ai写的，这个readme除了这句话也是ai写的，有的地方可能在瞎说。

**目标**：通过给 PDF 打多个标签来快速整理与检索文档，支持 AND/OR 检索；
## 🆕 新增功能亮点

### 1. Markdown 描述支持
- PDF 描述现在支持 **Markdown 格式**
- 在列表中自动渲染为富文本显示
- 支持多行描述和格式化文本

### 2. 批量操作增强
- **多选支持**：可同时选中多个 PDF 进行批量操作
- **批量标签管理**：为多个 PDF 同时添加/移除标签
- **批量描述编辑**：同时编辑多个 PDF 的描述

### 3. 标签筛选
- 支持复杂的布尔搜索表达式：
  - `标签1 AND 标签2` - 同时包含两个标签
  - `标签1 OR 标签2` - 包含任意一个标签
  - `(标签1 OR 标签2) AND 标签3` - 支持括号优先级
  - 引号支持：`"带空格的标签名"`

### 4. 增强的上下文菜单
- 右键点击 PDF 或目录提供丰富操作：
  - 查看完整描述（支持 Markdown 渲染）
  - 编辑描述（多选支持）
  - 导出目录标签
  - 从库移除（不删除文件）

### 5. 改进的用户界面
- 描述列自动适应内容高度
- 更好的工具提示支持
- 更直观的目录树展示

## 技术栈选择
- **语言**: Python 3.10+
- **GUI**: PySide6（Qt for Python），开箱即用、跨平台、社区活跃
- **PDF 读取**: pypdf（纯 Python，轻量）
- **数据库**: SQLite（内嵌、零运维）
- **文件监听（可选）**: watchdog（后续可增量监听目录变化）

## 主要能力
- 多标签：一个 PDF 可绑定多个标签
- 标签检索：支持图形化多选标签 + AND/OR 模式切换；支持复杂布尔表达式搜索
- 稳健识别：使用多信号指纹（PDF Trailer `/ID`、页数、首页文本哈希等）识别同一文档，重命名/迁移不丢数据
- 路径历史：同一 PDF 的历史路径可追溯，标记当前有效路径
- **Markdown 描述**：支持富文本描述，提升文档管理体验
- **批量操作**：支持多选PDF进行批量标签和描述管理

## 运行
```bash
python -m pip install -r requirements.txt
python -m src.app
```

首次运行后，点击界面中的"扫描目录"，选择需要纳入管理的目录。

Windows PowerShell 快速启动（推荐）：
```powershell
python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt
.\.venv\Scripts\python -m src.app
```

## 架构概览
- `src/db.py`：SQLite 初始化与 CRUD（PDF、标签、路径、检索）
- `src/pdf_id.py`：PDF 指纹提取（/ID、页数、首页文本哈希、文件特征）
- `src/scanner.py`：目录扫描、入库、路径维护
- `src/search.py`：**布尔表达式解析并执行（AND/OR/括号）**
- `src/gui.py`：PySide6 界面（标签多选 + AND/OR、按目录分组树、编辑标签、打开文件、**Markdown 渲染**）
- `src/app.py`：应用入口，组装 GUI 与后端
- `src/manifest.py`：目录标签清单导入导出

## 指纹设计（稳健识别）
优先使用 PDF Trailer `/ID` 作为强标识；辅以以下弱标识形成组合指纹：
- 页数（page_count）
- 首页提取文本的哈希（strip 后 sha1）
- 文件大小与修改时间（作为辅证；不直接用于严格判等）

入库时：
1. 若存在相同 `/doc_id`，更新记录与路径。
2. 否则尝试弱指纹匹配（页数相同且首页文本哈希相同）以合并。
3. 若均无匹配，创建新 PDF 记录。

## 如何使用新功能

### Markdown 描述
1. 右键点击 PDF 选择"编辑描述"
2. 使用 Markdown 语法编写描述：
   ```markdown
   # 重要论文
   - 作者：张三
   - 发表年份：2024
   - **关键词**：机器学习、深度学习
   ```
3. 保存后描述会自动渲染为富文本

### 批量操作
1. 按住 `Ctrl` 键点击多个 PDF 进行多选
2. 右键选择"添加标签"或"移除标签"进行批量管理
3. 选择"编辑描述"可同时为多个 PDF 设置相同描述

### 高级搜索
在顶部搜索框使用布尔表达式：
- `机器学习 AND 深度学习` - 查找同时包含两个标签的文档
- `论文 OR 报告` - 查找包含任一标签的文档  
- `(CV OR 计算机视觉) AND 2024` - 使用括号组合条件

## 数据库存放
默认位于用户目录 `~/AppData/Local/pdf-manager/pdfer.db`（Windows）。

## 常见问题
- 无法读取某些加密 PDF：pypdf 对受保护 PDF 支持有限，解密后再扫描。
- 识别失败：不同编辑器可能重写 `/ID`。本工具依赖多信号弱指纹以尽量合并，请通过"合并标签"或重新指定扫描目录修正。
- Markdown 渲染问题：某些复杂 Markdown 语法可能不支持，建议使用基础格式。

## 界面操作指南

### 列表展示与常用操作
- 右侧列表按所在目录分组为可折叠树，展开目录可查看文件；支持滚动。
- 目录节点加粗并带文件夹图标；文件节点展示 PDF 图标、文件名、标签、**Markdown 渲染的描述**、页数与"自适应单位"的大小（KB/MB/GB）。
- 选中某个 PDF 后：
  - "添加标签"可输入逗号分隔的多个标签
  - "移除标签"可批量移除
  - "打开"将使用系统默认程序打开该 PDF
  - 双击 PDF 节点可直接打开
  - 右键菜单：打开、重命名、添加标签、移除标签、**查看完整描述**、**编辑描述**、从库移除（不删文件）

### 目录级标签清单（跨机保留标签）
- 导出：在界面点击"导出目录标签"，选择某个目录后生成 `.pdfer-tags.json`。
- 导入：在另一台电脑上，把整个目录拷贝后，用"扫描目录"扫描该目录，程序会自动读取 `.pdfer-tags.json` 并为匹配的 PDF 写回标签。

清单文件格式（示例）：
```json
{
  "version": 1,
  "directory": "D:/Docs/Papers",
  "entries": [
    {
      "filename": "cv/2024-survey.pdf",
      "tags": ["cv", "survey"],
      "description": "# 重要调研\n**计算机视觉**领域最新进展",
      "doc_id": "a1b2c3...",
      "page_count": 18,
      "first_page_text_sha1": "12ab..."
    }
  ]
}
```