文档整理技能 (document-organizer)

# 文档整理技能 (document-organizer) ## 概述 专业的文档批量处理技能，支持旧版 Office 文档（.doc/.xls）高质量转换为 Markdown，保持格式结构完整。 --- ## 核心能力 ### ✅ 格式转换 - **Word 文档**: `.doc` → `.md`（LibreOffice 直接转换） - **Word 文档**: `.docx` → `.md`（LibreOffice 直接转换） - **Excel 表格**: `.xls` → `.xlsx` → `.md`（保留表格结构） - **PowerPoint**: `.ppt` → `.pptx` → `.md`（可选支持） - **现代格式**: `.xlsx`/`.pptx` → `.md`（MarkItDown 直接处理） ### ✅ 批量处理 - 支持按目录批量转换 - 自动保持原目录结构 - 分类处理不同类型文件 - 错误自动记录，不中断流程 ### ✅ 质量保证 - 完美保留标题层级（H1-H6） - 表格结构完整（Markdown 表格） - 加粗/斜体样式保留 - 列表有序/无序完整 - 中文无乱码（UTF-8 编码） --- ## 快速开始 ### 1. 环境准备 ```bash # 安装 LibreOffice（系统级） # 下载: https://zh-cn.libreoffice.org/ # 安装 Python 依赖 pip install markitdown[docx,xlsx] ``` ### 2. 使用方法 ```bash # 交互模式（推荐） npx skills run document-organizer # 命令行参数 npx skills run document-organizer --source "源目录" --output "输出目录" --type doc,xls ``` ### 3. 配置 首次运行会检测 LibreOffice 路径，默认： - Windows: `D:\Program Files\LibreOffice\program\soffice.exe` - Linux: `/usr/bin/soffice` - macOS: `/Applications/LibreOffice.app/Contents/MacOS/soffice` --- ## 详细功能 ### 文档类型处理 | 源格式 | 转换流程 | 输出格式 | 质量 | |--------|---------|---------|------| | `.doc` | LibreOffice → Markdown | `.md` | ✅ 完美 | | `.docx` | LibreOffice → Markdown | `.md` | ✅ 完美 | | `.xls` | LibreOffice → .xlsx → MarkItDown → .md | `.md` | ✅ 完美 | | `.xlsx` | MarkItDown → .md | `.md` | ✅ 完美 | | `.ppt` | LibreOffice → .pptx → MarkItDown → .md | `.md` | ✅ 良好 | | `.pptx` | MarkItDown → .md | `.md` | ✅ 良好 | | `.pdf` | MarkItDown → .md | `.md` | ✅ 优秀（文本+表格）| ### 批量处理策略 **方案一：分类批量（推荐）** ``` 批量转换所有 .doc 文件: soffice --convert-to md *.doc 批量转换所有 .docx 文件: soffice --convert-to md *.docx 批量转换所有 .xls 文件: soffice --convert-to xlsx *.xls → markitdown *.xlsx 批量转换所有 .ppt 文件: soffice --convert-to pptx *.ppt → markitdown *.pptx ``` **方案二：递归处理** ``` 扫描目录树，按文件类型分组 分别批量转换每个子目录 保持完整目录结构输出 ``` --- ## 使用示例 ### 示例 1: 转换单个目录 ```bash # 扫描源目录 npx skills run document-organizer --source "G:\历史文档" --output "d:\知识库" ``` 输出结构： ``` 知识库/ ├── 项目A/ │ ├── 需求文档.md │ └── 设计文档.md └── 项目B/ └── 会议记录.md ``` ### 示例 2: 仅处理 Word 文档 ```bash npx skills run document-organizer --source "G:\docs" --output "d:\md" --filter .doc,.docx ``` ### 示例 3: 处理 PDF 文档 ```bash npx skills run document-organizer --source "G:\pdfs" --type pdf --output "d:\pdf_md" ``` ### 示例 4: 先扫描统计 ```bash npx skills run document-organizer --scan-only "G:\docs" # 输出: 文件统计，不执行转换 ``` --- ## 配置选项 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `--source` | string | 必需 | 源目录路径 | | `--output` | string | `./output` | 输出目录 | | `--type` | string | `doc,xls,docx,xlsx,ppt,pptx,pdf` | 处理的文件类型（逗号分隔） | | `--soffice-path` | string | 自动检测 | LibreOffice soffice.exe 路径 | | `--log-file` | string | `conversion.log` | 日志文件路径 | | `--dry-run` | bool | `false` | 仅模拟，不实际转换 | --- ## 性能参考 **测试环境**: i5 CPU, 16GB RAM, SSD | 操作 | 数量 | 耗时 | 吞吐 | |------|------|------|------| | .doc → .md (LibreOffice) | 1,000 | ~30 秒 | 33 个/秒 | | .xls → .xlsx (LibreOffice) | 2,000 | ~1.5 分钟 | 22 个/秒 | | .xlsx → .md (MarkItDown) | 2,000 | ~2 分钟 | 17 个/秒 | | .ppt → .pptx (LibreOffice) | 500 | ~30 秒 | 17 个/秒 | | .pptx → .md (MarkItDown) | 500 | ~1 分钟 | 8 个/秒 | | .pdf → .md (MarkItDown) | 500 | ~2 分钟 | 4 个/秒 | | **总计** (3,000文件) | 3,000 | **~10-12 分钟** | - | --- ## 常见问题 ### Q: LibreOffice 找不到？ A: 确保安装并添加到 PATH，或通过 `--soffice-path` 指定： ```bash npx skills run document-organizer --soffice-path "C:\Program Files\LibreOffice\program\soffice.exe" ``` ### Q: 转换失败怎么办？ A: 检查错误日志，常见原因： - 源文件损坏 - 临时文件（`~$` 开头）自动跳过 - 权限不足（以管理员运行） ### Q: 可以预览而不转换吗？ A: 使用 `--dry-run` 参数： ```bash npx skills run document-organizer --source "docs" --dry-run # 输出: 将转换 X 个文件，Y 个目录，跳过 Z 个 ``` ### Q: 如何只转换特定子目录？ A: 结合 `--filter` 和路径模式： ```bash npx skills run document-organizer --source "docs" --filter "00_模板/*.doc" ``` --- ## 技术架构 ``` ┌─────────────────┐ │ 用户命令 │ │ npx skills ... │ └────────┬────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 文档整理技能 (Python) │ │ • 扫描目录树 │ │ • 按类型分组 (doc/xls/docx/xlsx) │ │ • 调用 LibreOffice 批量转换 │ │ • 调用 MarkItDown 结构化转换 │ │ • 保持目录结构 + 重命名 │ │ • 错误处理 + 日志记录 │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────┐ ┌──────────────────┐ │ LibreOffice │ │ MarkItDown │ │ (格式转换) │ │ (结构化输出) │ └─────────────────┘ └──────────────────┘ │ │ └───────────┬───────────┘ ▼ ┌─────────────┐ │ .md 文件 │ │ (可搜索) │ └─────────────┘ ``` --- ## 依赖清单 | 工具 | 版本要求 | 用途 | |------|---------|------| | LibreOffice | 7.0+ | .doc → .docx / .xls → .xlsx | | Python | 3.10+ | 脚本运行 | | markitdown | 0.1.5+ | .docx/.xlsx → .md | | pywin32 | (可选) | Windows COM 自动化（备用）| --- ## 脚本文件 本技能包含以下脚本： | 文件 | 说明 | |------|------| | `scripts/batch_convert.py` | 主脚本 - 批量文档转换（支持 .doc/.xls/.docx/.xlsx/.ppt/.pptx/.pdf）| --- ## 使用建议 ### ✅ 推荐场景 - 批量转换旧版 Office 文档（.doc/.xls） - 构建可搜索的知识库 - 文档数字化归档 - 保留原始格式和结构 ### ❌ 不推荐场景 - 仅需提取纯文本（用 `strings` 命令即可） - 扫描图片型 PDF（需 OCR 专用工具） - 在线实时转换（需启动办公软件） --- ## 版本历史 - **v1.0.4** (2026-03-12) - 修复：移除对不存在的外部 convert-markdown 目录和脚本的依赖 - 修复：移除对特定路径虚拟环境的依赖 - 优化：直接使用 markitdown 命令行工具进行转换 - 优化：增加 markitdown 命令的自动检测逻辑 - **v1.0.3** (2026-03-12) - 修复：移除不存在的 `--temp-dir` 参数 - 更新：完善所有支持的文件类型说明 - 优化：文档与实际脚本保持一致 - **v1.0.2** (2026-03-11) - 优化：移除临时目录，直接生成 .md 文件 - 新增：.docx 文件 LibreOffice 直接转换 - 优化：convert_modern 支持参数调用 - 优化：批量转换逻辑，提高速度 - 优化：--dry-run 模式跳过 LibreOffice 检查 - **v1.0.0** (2026-03-11) - 初始版本 - 支持 .doc/.xls 批量转换 - 优化：LibreOffice 直接转 Markdown - 分类处理，保持目录结构 --- **最后更新**: 2026-03-12 **适用平台**: Windows/Linux/macOS (需 LibreOffice) **许可证**: MIT