文档整理技能 (document-organizer)

支持批量将旧版 Office 文档（.doc/.xls）高质量转换为 Markdown 并保持目录结构与格式完整。

byteuser1977@byteuser1977

Install

openclaw skills install @byteuser1977/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`	✅ 优秀（文本+表格）

批量处理策略

方案一：分类批量（推荐）

text

批量转换所有 .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

方案二：递归处理

text

扫描目录树，按文件类型分组
分别批量转换每个子目录
保持完整目录结构输出

使用示例

示例 1: 转换单个目录

bash

# 扫描源目录
npx skills run document-organizer --source "G:\历史文档" --output "d:\知识库"

输出结构：

text

知识库/
├── 项目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"

技术架构

text

┌─────────────────┐
│   用户命令       │
│  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

文档整理技能 (document-organizer)

Install

文档整理技能 (document-organizer)

概述

核心能力

✅ 格式转换

✅ 批量处理

✅ 质量保证

快速开始

1. 环境准备

2. 使用方法

3. 配置

详细功能

文档类型处理

批量处理策略

使用示例

示例 1: 转换单个目录

示例 2: 仅处理 Word 文档

示例 3: 处理 PDF 文档

示例 4: 先扫描统计

配置选项

性能参考

常见问题

Q: LibreOffice 找不到？

Q: 转换失败怎么办？

Q: 可以预览而不转换吗？

Q: 如何只转换特定子目录？

技术架构

依赖清单

脚本文件

使用建议

✅ 推荐场景

❌ 不推荐场景

版本历史

Related skills