# file-tools

**Repository Path**: Firoly_li/file-tools

## Basic Information

- **Project Name**: file-tools
- **Description**: 常用的文件处理功能集合
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件页数统计工具 v2.9.8

一个用于统计 Word、Excel、PowerPoint 和 PDF 文件页数的 Python 工具。Windows 上通过 Office/WPS COM 实现**精确打印页数**；macOS/Linux 支持 PDF，以及 docx/pptx 缓存页数与 LibreOffice（Writer/Impress）。

## 项目特点

- ✅ **绝对精确**：使用Office COM API获取真实页数，拒绝任何估算
- ✅ **GUI 模式（v2.5.0 新增）**：双击 exe 即弹出图形界面，点选目录/文件、选格式、一键统计并打开报告；界面即命令行参数的可视化，非程序员零门槛
- ✅ **支持多种格式**：Word (.docx, .doc)、WPS (.wps)、Excel (.xlsx, .xls)、PowerPoint (.pptx, .ppt)、PDF (.pdf)
- ✅ **批量处理**：支持目录遍历和批量文件处理
- ✅ **多种输出格式**：Excel（含汇总统计）、JSON、HTML（交互式树形报告）、DOCX（《总目录册》模板风格，封面+索引+层级目录）
- ✅ **多格式一次导出（v2.6.0）**：一次扫描可同时生成多种报告（如 `-o excel,json,docx`）；GUI 格式卡片支持多选
- ✅ **count 增量缓存（v2.6.2）**：同一目录再次统计时，未改动文件复用 `.filestats-cache.json`，跳过 Office 打开
- ✅ **清单文件体检（v2.6.2）**：ls 高级选项「文件体检」（默认关）；SHA256 内容筛重 + PDF/Office 轻量损坏检查
- ✅ **Excel 转 PDF（v2.6.1）**：GUI 第三模式或命令行 `tools/excel_to_pdf.py`（见下文 [Excel 转 PDF](#excel-转-pdf)）
- ✅ **COM 崩溃自恢复**：高频调用 Office 进程异常时自动重建实例并重试，批量统计不中断
- ✅ **双后端支持**：只装 WPS 的电脑也能用——未检测到 Microsoft Office 时自动回退到 WPS COM（KWPS/KET/KWPP），`--backend` 可强制指定
- ✅ **损坏 PDF 兜底**：文件截断等无法解析的 PDF 自动降级为流式扫描页对象估算页数，不再直接标失败
- ✅ **结构化日志**：详细的处理日志和错误追踪
- ✅ **完善测试**：单元测试和集成测试覆盖

## 项目结构

```
filestats/                        # 仓库目录名以本地克隆为准（如 files_tuils）
├── src/                          # 主程序代码
│   ├── cli.py                    # CLI 入口（count / ls）
│   ├── core/                     # ParseResult、ParserRegistry、errors、com_manager
│   ├── parsers/                  # 扩展名 → FileType（页数委托 backends）
│   ├── backends/                 # 页数后端链、Excel→PDF 引擎（COM / LO / PDF）
│   ├── jobs/                     # Phase 1 编排：count、ls、pdf_runner
│   ├── outputs/                  # Phase 2 多格式导出（registry + export_batch）
│   ├── gui/                      # pywebview GUI（app、bridge、task_runner、gui.html）
│   ├── platform/                 # 打包路径、环境探测、非 Win 守卫
│   ├── config/settings.py        # YAML 配置加载
│   └── utils/                    # 扫描、count 缓存、日志、Excel 辅助等
├── config/default.yaml           # 默认配置
├── run_cli.py                    # 打包入口：无参 GUI，有参 CLI
├── filestats.spec / filestats_mac.spec
├── scripts/                      # check.sh、Gitee 打包与 CI 脚本
├── tests/unit · tests/integration
├── docs/
│   ├── architecture.md           # 架构总览（维护者首选）
│   ├── development.md            # 开发/发版流程
│   ├── cross_platform_design.md  # 跨平台页数设计（历史决策见文首说明）
│   ├── multi_format_output_design.md
│   ├── page_count_analysis.md
│   └── 用户操作手册.md
├── examples/
├── requirements.txt              # 运行时
├── requirements-dev.txt          # 开发 / CI / 打包
├── pyproject.toml
├── AGENTS.md
└── README.md
```

更完整的分层与数据流见 [docs/architecture.md](docs/architecture.md)。

## 安装

### 环境要求

- Python 3.9+
- **Windows 10/11**（Office/Excel 精确页数）：Microsoft Office 2016+ 或 WPS Office
- **macOS / Linux**：PDF 全支持；docx/pptx/xlsx 可用内嵌缓存或 LibreOffice；**Excel 经 LibreOffice Calc UNO 统计**（与 Windows Office 排版可能有差异）

### 安装依赖

```bash
# 只跑 CLI/GUI
pip install -r requirements.txt

# 开发、跑测试、打包（与 CI 一致）
pip install -r requirements-dev.txt
```

## 使用方法

### 新版CLI（推荐）

```bash
# 基本用法
python -m src.cli count <路径> [选项]

# 统计当前目录（3层深度）
python -m src.cli count .

# 统计所有层
python -m src.cli count . --depth 0

# 输出为JSON格式
python -m src.cli count . --output json

# 一次扫描同时输出多种格式（逗号分隔）
python -m src.cli count . -o excel,json,docx --output-file "统计_{date}"

# 输出为交互式HTML报告（树形目录+类型筛选+搜索+层级汇总页数）
python -m src.cli count . --output html

# 输出为DOCX目录册（《总目录册》模板风格：封面+索引+层级章节+点线页数）
python -m src.cli count . --output docx --output-file "统计_{date}"

# 使用自定义配置文件
python -m src.cli count . --config custom_config.yaml

# 详细输出
python -m src.cli count . --verbose
```

### 目录清单模式（ls，不统计页数）

只清点目录结构与文件名（含大小、修改日期），**不调用 Office、不统计页数，秒级完成**。适合档案清点、文件移交清单等不需要页数的场景。

```bash
# 列出目录与文件名（默认列出全部文件，含 mp4/7z/图片等非 Office 文件）
python -m src.cli ls -d 0 -o docx --output-file "第二类文件清单_{date}" "目标目录"

# 只列指定扩展名（可多次）
python -m src.cli ls -d 0 -o json --ext docx --ext pdf "目标目录"

# 输出 Excel / HTML 同理（-o excel / -o html）
```

| 选项 | 说明 | 默认 |
|------|------|--------|
| `--ext` | 只列出指定扩展名（可多次，如 `--ext docx --ext pdf`，不带点） | 全部文件 |
| `--output-file` | 输出文件名 | 文件清单 |

清单自动排除本次输出文件自身，避免把报告算进清单；旧版报告文件（如上次生成的清单）不会被自动排除，清点前留意。

## Excel 转 PDF

与 **页数统计（count）** 独立：只做 Excel 打印预处理 + 导出 PDF，配置段为 `config/default.yaml` 里的 `excel_to_pdf`（**不要**与 count 的 `--page-engine` 混用）。

| 场景 | 推荐入口 |
|------|----------|
| 图形界面、打包后的 exe/app | 无参数启动 → 选择 **「Excel 转 PDF」** |
| 命令行、脚本、自动化 | **`python tools/excel_to_pdf.py`**（仓库根目录执行） |

```bash
# 单文件（默认先预处理分页再转 PDF）
python tools/excel_to_pdf.py --in=./数据.xlsx

# 指定输出、目录批量、按 sheet 拆分等
python tools/excel_to_pdf.py --in=./表格目录 --out=./pdf_out --recursive
python tools/excel_to_pdf.py --in=./数据.xlsx --split-sheets --out=./pdf_out
python tools/excel_to_pdf.py --help
```

- **程序内集成**（二次开发）：调用 `src.jobs.pdf_runner.run_pdf_job`，不要把 `src/utils/excel_to_pdf.py` 当命令行入口。
- 设计细节：[docs/excel_to_pdf_design.md](docs/excel_to_pdf_design.md)

## 命令行选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--depth, -d` | 遍历深度（0表示全部） | 3 |
| `--output, -o` | 输出格式，逗号分隔可多选（excel/json/html/docx）；省略时读配置 `default_formats` | excel |
| `--page-engine` | 统计方式（auto/com/libreoffice/cached） | auto |
| `--backend` | COM 后端（auto/ms/wps，仅 page-engine 含 com 时生效） | auto |
| `--config, -c` | 配置文件路径 | 使用默认配置 |
| `--verbose, -v` | 详细输出 | false |
| `--output-file` | 输出文件名；省略时读配置 `output.filename` | 统计结果 |

## 配置文件

创建 `config.yaml` 文件自定义配置：

```yaml
application:
  name: "文件页数统计工具"
  version: "2.3.1"

parsers:
  min_file_size: 1000
  timeout: 30

processing:
  default_depth: 3
  skip_temp_files: true

output:
  default_format: excel
  filename: "统计结果"
  directory: "."

logging:
  level: INFO
  file: "filestats.log"
  console: true
```

## 输出格式

### Excel输出

生成包含3个工作表的Excel文件：

1. **统计结果** - 所有文件的详细信息
   - 文件名
   - 文件类型
   - 页数
   - 路径
   - 处理时间
   - 状态

2. **汇总统计** - 整体统计信息
   - 处理文件数
   - 成功/失败数
   - 总页数
   - 按类型分组统计

3. **失败文件** - 失败文件清单（如果有）
   - 文件名
   - 文件类型
   - 错误信息

### DOCX输出

以《二维码项目总目录册》为模板风格，生成可当目录册浏览的 Word 文档：

1. **封面** - 方正小标宋 22pt 大标题 + 副信息（楷体_GB2312 16pt）
2. **索引页** - 各大类一行（分级编码 + 文件数/页数汇总）+ 二级明细
3. **正文** - 按目录层级分章节，标题与条目带分级编码（1 / 1.1 / 1.1.1，`docx.hierarchical_numbering` 可关）；大类之间分页、类内连续排版；文件条目 = 仿宋_GB2312 16pt + 点线制表位 + "N页"（异常条目标注 空文件/过小/统计失败）
4. **附录** - 三段式（存在才显示）：一、空目录清单；二、空/过小文件；三、统计失败文件（均含完整路径）

分页规则：仅 封面 / 索引 / 每个大类 / 附录 各起新页。纸张 A4、四周 2.7cm 边距，与模板版式一致。

### JSON输出

结构化的JSON数据：

```json
{
  "summary": {
    "total_files": 10,
    "success_files": 9,
    "failed_files": 1,
    "total_pages": 245,
    "by_type": {
      "word": {"count": 3, "pages": 80},
      "excel": {"count": 4, "pages": 120},
      "pdf": {"count": 2, "pages": 45}
    }
  },
  "results": [...]
}
```

## 测试

```bash
# 运行所有测试
pytest

# 运行单元测试
pytest tests/unit/

# 运行集成测试
pytest tests/integration/

# 查看测试覆盖率
pytest --cov=src tests/
```

## 用户操作手册

面向非开发人员的傻瓜式使用说明，详见 [docs/用户操作手册.md](docs/用户操作手册.md)，包含：
- 可照抄的命令模板（Excel / DOCX / HTML / 单文件统计）
- 输出结果各部分的含义
- 常见问题排查对照表（漏文件、找不到产物、自引用、PDF 损坏等）

## 辅助工具（tools/）

| 脚本 | 用途 |
|---|---|
| `analyze_docx_skeleton.py` | DOCX 骨架分析器：打印段落的样式/字体/字号/加粗/对齐，支持两文件并排对比、`--meta` 只看页面设置与样式分布。用于对齐 DOCX 模板 |
| `create_test_pdf.py` / `create_test_pdf_simple.py` | 生成测试用 PDF |
| `create_test_word.py` / `create_test_excel.py` / `create_test_ppt.py` | 生成测试用 Office 文档 |

```bash
# 对比模板与生成产物的结构差异
python tools/analyze_docx_skeleton.py 模板.docx 产物.docx 40

# 只看页面设置、页眉页脚、样式分布
python tools/analyze_docx_skeleton.py 产物.docx --meta
```

## 开发指南

详见 [AGENTS.md](AGENTS.md) 文件，包含：
- 构建和测试命令
- 代码风格指南
- 命名约定
- 错误处理规范

## 架构文档

详见 [docs/architecture.md](docs/architecture.md) 文件，包含：
- 系统架构设计
- 核心组件说明
- 扩展指南

## 注意事项

- Word 统计使用 `ComputeStatistics(2)`（精确排版页数），同时支持 `.wps`（金山老式 OLE2 格式：有 Word 时内容识别打开，仅装 WPS 时由 WPS 文字 KWPS 原生打开）
- Excel 统计使用每个 sheet 的 `PageSetup.Pages.Count`（精确打印页数）
- PowerPoint 使用 `Slides.Count`（幻灯片数，与打印页数口径不同）
- PDF 统计使用 pypdf 库（页树节点数）；文件损坏无法解析时自动降级为流式扫描 `/Type /Page` 页对象数估算（无对象流的截断文件有效）
- WPS 后端：本机无 Microsoft Office 时自动改用 WPS COM（KWPS/KET/KWPP，旧版 WPS/ET/WPP），页数接口与 MS 同名同义；不同后端的排版口径可能存在细微差异，正式交付前建议用已知页数的文件抽样比对
- 缓存与日志（v2.9.8 资源治理）：页数缓存位于用户缓存目录（Windows `%LOCALAPPDATA%\filestats\page_cache\`），**超过 30 天未用自动回收**；运行日志自动轮转（5MB × 3）；LibreOffice 引擎（显式启用时）使用独立 profile（`…\filestats\lo_profile`）并在任务结束优雅关闭 daemon；GUI 运行数据位于 `…\filestats\webview`（仅 Windows）
- 升级提示：v2.9.5 之前版本在扫描目录内留下的旧 `.filestats-cache.json` 不再被读写，可手动清理（工具不代删用户档案目录内文件）
- 使用建议：不要用 GUI 与 CLI 同时对同一批目录执行统计（两者共享 LibreOffice 端口与缓存，先结束的一方可能关闭共享组件）

## 打包为可执行文件（PyInstaller）

### macOS（桌面应用 `.app`）

```bash
./scripts/build_mac.sh
```

产物：`dist_mac/filestats.app`（双击打开图形界面，与 Windows exe 同源 GUI）。

```bash
# 可选：命令行
dist_mac/filestats.app/Contents/MacOS/filestats count -d 0 -o json /path/to/folder
```

**说明：**

- 使用系统 **WebKit**（pywebview），无需 WebView2
- **不打包 LibreOffice**；统计 Office/Excel 需本机已安装 LibreOffice
- Gatekeeper 拦截时：`xattr -cr dist_mac/filestats.app` 或右键「打开」

### Windows（文件夹 + GUI）

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build_win.ps1
```

产物：`dist_win/filestats/`（**onedir**：`filestats.exe` 与 `_internal` 必须放在一起）。不要再用单文件 exe——启动解压到 `%TEMP%` 时会被杀毒锁 `python312.dll`。

配置文件随包内置（`config/default.yaml`），打包入口为 `run_cli.py`，与 `python -m src.cli` 等价。

**打包注意事项：**

- **不要加 `--clean`**：它会删除 `build/` 触发批量删除保护而中止。改用全新 `--workpath` 目录达到同样效果
- **整夹分发**：只复制 `filestats.exe` 无法运行；发布 zip 应含整个 `filestats/` 目录
- **发版只改 `src/version.py` 一处**，再跑 `pytest tests/unit/test_gui_version.py`；改版本后须重新打包（`--version` 读打包时嵌入的值）
- **GUI（v2.5.0 起）**：spec 已含 `webview.platforms.*` hiddenimports 与 `src/gui/gui.html` data；运行依赖系统 WebView2 运行时（Win10/11 一般自带），缺失时程序给出中文引导而非闪退

**打包后必做冒烟测试**：

```bash
dist_win/filestats/filestats.exe --version
dist_win/filestats/filestats.exe count -d 0 -o docx --output-file "t_{date}" "测试目录"
dist_win/filestats/filestats.exe count -d 0 -o json --output-file "t" "单个文件.docx"
dist_win/filestats/filestats.exe
```

验证要点：文件数/页数与源码版一致、docx 有册编号与页脚页码、COM 类文件（Word/Excel/PPT）不报失败。

## 版本历史

### v2.7.0 (2026-09-13)

- **DOCX 条目页码恢复**：count 模式文件条目重新输出"文件名 …… N页"点线目录样式（长文件名自动降字号不截断）
- **DOCX 分级编码**：标题/条目/索引带 1 / 1.1 / 1.1.1 编号（`docx.hierarchical_numbering` 可关）
- **分页规则收敛**：仅 封面/索引/大类/附录 分页，类内连续排版（第二层目录不再强制分页）
- **空目录贯通 count**：四格式列空目录完整路径；无文件但有空目录时输出仅结构报告
- **空/过小文件单列**：与统计失败分离（Excel 状态列+独立表、DOCX 附录三段、HTML 标注、JSON status/file_size）；"失败"口径全链路收窄为真实解析失败
- **非 Office 文件披露**：count 模式不再静默丢弃，汇总披露计数与样例；0 字节非 Office 文件按空文件纳入
- **缺陷修复**：ls 模式「跳过隐藏」计数随空目录扫描翻倍的问题

### v2.6.8 (2026-09-11)

- **Excel → PDF**：默认整本合并 PDF；A4 横向打印预处理（表头、分块打印区域）；xlsx 通用兼容（PrintTitleRows、WPS sheetPr）
- **LibreOffice**：转换超时按 sheet 数与体积动态放大，避免大工作簿边界超时
- **GUI / CLI**：PDF 模式与 `tools/excel_to_pdf.py` 共用配置与超时策略

### v2.6.5 (2026-09-11)

- **Excel → PDF**：默认逐 sheet 拆分；目录批量拆分 + 递归子目录；修复批量拆分 `sheets` 参数错误；COM 引擎不再强制关闭拆分
- **ls 体检重复组**：HTML/Excel/DOCX 重复组完整路径与说明
- **Mac 打包**：`package_mac.sh` 选取最新版本 app

### v2.6.4 (2026-09-11)

- **Windows 长路径**：`\\?\` 扩展路径，改善超长路径下 PDF/Office 扫描与打开失败
- **隐藏项**：跳过时 Excel/JSON/GUI 汇总与样例；纳入统计时标记「隐藏」（不修改磁盘属性）
- **GUI**：「下载运行日志」；界面日志去重，去掉内部 INFO 与事件推送诊断

### v2.6.3 (2026-09-11)

- **PPT（.pptx）count 默认不启动 PowerPoint**：从 OOXML 统计幻灯片张数，避免批量统计时弹出「可尝试修复」对话框；COM 兜底修正 `DisplayAlerts` / `OpenAndRepair`

### v2.6.2 (2026-09-11)

- **count 增量缓存**：扫描根目录 `.filestats-cache.json`；未改动文件直接复用页数；失败项下次自动重试
- **Windows 打包改为 onedir**：发布物为 `filestats/` 文件夹（exe + `_internal`），避免单文件解压到 Temp 被杀毒锁 DLL
- **ls 文件体检**：CLI `--inspect` / GUI「文件体检」（默认关）；内容 SHA256 筛重、PDF/Office 损坏与加密轻量检查

### v2.6.1 (2026-09-10)

- **Excel → PDF**：整合 `excel_prep_pages` + `excel2pdf`；横向/一页宽/重复表头/页脚页码预处理
- **GUI「Excel 转 PDF」模式**：源路径、输出目录、引擎选择（auto/COM/LibreOffice）、批量与递归
- **跨平台引擎**：Windows 优先 Excel/WPS COM 导出；无 Office 时回退 LibreOffice；Mac/Linux 使用 LO
- **CLI**：`tools/excel_to_pdf.py`（`--pdf-engine`、`--backend`、`--split-sheets` 等）

### v2.6.0 (2026-09-10)

- **多格式输出架构**：扫描/解析只做一次（`run_processing`），导出按格式列表投影（`export_batch`）；CLI `-o excel,json` 与 GUI 多选格式共用同一流水线
- **配置生效**：`output.default_formats`、`output.filename` 在 CLI 未传 `-o` / `--output-file` 时生效（v2.5 及以前为死键）
- **产物自排除（行为变更）**：count 模式启用自排除；ls/count 仅排除**已选格式**对应扩展名（不再固定排除四种）
- **部分成功**：某一格式导出失败不阻断其余格式；终态列出成功路径与 `export_errors`
- **Mac 稳定性（v2.5.5 起）**：GUI 嵌入式 HTML、ATS 放行、LibreOffice 子进程替代 LibreOfficePython
- **DOCX 总目录册**：对齐终验模板（L1–L4 层级、封面/索引版式）

### v2.5.0 (2026-09-04)

- **GUI 模式**：双击 exe（无参数）即弹出图形界面；带任何参数时走原 CLI，命令行行为零变化
  - 统计页数 / 目录清单两模式全参数可视化：路径、深度、格式、引擎（auto/ms/wps）、扩展名过滤、保存位置、报告文件名（{date} 预览）、verbose、配置文件（-c）
  - 执行中实时进度条 + 日志流，完成后摘要卡片（处理/成功/失败/页数/耗时）+ 失败清单 + 一键打开报告/所在文件夹
  - 高级选项按五组折叠，徽章实时显示"已自定义 N 项"；界面默认值未修改时沿用配置文件（与 `-c` 语义一致）
- 技术实现：pywebview（WebView2）内嵌 HTML；GUI 编排层与 CLI 同积木同参数，一致性测试保证同参数产物一致
- 环境引导：WebView2 运行时缺失时给中文安装引导；CLI 模式不受任何影响
- 待接线配置（对 GUI 不可见，走 -c 也不生效于 CLI）：`parsers.timeout`、`output.excel.*`、`output.json.*` 等，见技术方案"待接线清单"

### v2.4.0 (2026-09-04)

- **WPS 后端支持**：未安装 Microsoft Office 的电脑自动回退到 WPS COM（文字 KWPS/WPS、表格 KET/ET、演示 KWPP/WPP），命令完全不变；Office 与 WPS 双装时优先使用 Office（统计口径基准）
- 全部后端不可用时给出可读报错（含尝试过的 ProgID 清单与安装建议），替代晦涩的 COM 错误码元组
- `count` 新增 `--backend auto|ms|wps`：双装机器可强制指定后端（排查口径差异用）
- 演示类组件免隐藏特判改为按 ProgID 集合判断（修复 KWPP/WPP 被误设 Visible 的隐患）；COM 属性赋值统一容错（WPS 对个别属性支持不同）
- COM 层新增 mock 隔离单测（回退链/缓存/特判/错误传播），测试增至 39 例

### v2.3.1 (2026-09-04)

- `ls` 模式保留空目录：文件夹下无任何文件时不再被忽略，四种产物均体现——DOCX/HTML 树中显示为目录节点（尾部标注"（空）"），Excel 追加「空目录」工作表，JSON 增加 `empty_dirs` 字段
- 空目录判定：整棵子树无任何文件（沿用 ls 的深度/临时文件过滤语义），与 `--ext` 等文件过滤无关；空的根目录只输出目录结构
- 该行为取代 v2.2.0 的"空目录不再输出"（后者仅适用于 count 精确统计模式，ls 模式自本版起保留目录结构完整性）
- 修复 config 中 application.version 与 CLI 版本号不一致（2.3.0 → 2.3.1）

### v2.3.0 (2026-09-04)

- 新增 `ls` 子命令（目录清单模式）：只清点目录结构与文件名（含大小、修改日期），不统计页数、不调用 Office，秒级完成
- `ls` 默认列出全部文件（含非 Office），支持 `--ext` 扩展名白名单过滤（可多次）；自动排除本次输出文件自身
- 四种输出格式同步支持清单模式：DOCX（复用总目录册公文版式，文件行尾部为"大小 日期"、封面"文件目录清单"）、Excel（文件清单+汇总两表）、HTML（交互树，叶子带大小/日期）、JSON（type=catalog，无页数字段）
- 新增 `FileItem` 轻量条目模型（src/core/base.py）与大小格式化工具（src/utils/format.py）
- 修复 config 中 application.version 与 CLI 版本号不一致（2.0.0 → 2.3.0）

### v2.2.0 (2026-09-01)

- DOCX 输出新增「册编号」层（第01册/第02册…），一级子目录自增，每册从新页开始
- 索引页补 root 总览行，修正统计单个大类时汇总行缺失的层级错位
- 长文件名自适应：按制表位可用宽度降字号 16→14→12pt，超出后自动换行（不截断，保证文件名完整）
- 页脚居中页码（PAGE 域），封面不显示（titlePg）
- 行距公文固定值 28pt（标题 32pt），标题 keep_with_next 防孤行，空目录不再输出
- 新增 `tools/analyze_docx_skeleton.py`（DOCX 骨架分析器，用于对齐模板）

### v2.1.0 (2026-09-01)

- DOCX 输出严格对齐《总目录册》模板字体：正文条目/子类目仿宋_GB2312 16pt、Heading 1 方正小标宋、索引页楷体/黑体、A4 + 2.7cm 边距
- COM 进程崩溃自动恢复（COMManager.reset/retry），高频调用不再因 RPC 失败连错
- PDF 解析 PyPDF2 → pypdf，损坏/截断文件自动降级流式扫描估算页数
- FileScanner 支持单文件路径参数
- 纳管 run_cli.py 与 filestats.spec（PyInstaller 打包配置）

### v2.0.0 (2024-01-08)

- 全面重构，采用模块化架构
- 实现COM对象统一管理
- 新增PowerPoint文件支持
- 支持Excel实际打印页数统计
- 支持JSON输出格式
- 新增HTML交互式报告（树形目录+类型筛选+层级实时汇总页数）
- 添加结构化日志
- 完善单元测试和集成测试
- 使用Click框架重构CLI

### v1.0.0

- 初始版本
- 支持Word/Excel/PDF基础统计
- 命令行接口

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！