文档整理技能 (document-organizer)

核心用法

文档整理技能是一款面向企业数字化转型的专业文档转换工具，核心能力是将历史遗留的旧版Office文档（.doc/.xls/.ppt）及现代格式（.docx/.xlsx/.pptx/.pdf）批量转换为Markdown格式。使用流程为：安装LibreOffice → 运行npx skills run document-organizer → 指定源目录与输出目录 → 自动完成批量转换。

转换链路：

• .doc/.docx → LibreOffice 直接转 Markdown
• .xls → LibreOffice 转 .xlsx → MarkItDown 转 Markdown
• .xlsx/.pptx/.pdf → MarkItDown 直接处理

支持按目录递归批量处理，自动保持原目录结构，错误自动记录不中断流程。

显著优点

1. 格式保真度高：完美保留标题层级（H1-H6）、表格结构、加粗/斜体样式、列表层级
2. 中文支持优秀：UTF-8编码确保无乱码
3. 批量处理高效：实测1000个.doc文件约30秒完成，3000个混合类型文件10-12分钟处理完毕
4. 旧版格式兼容：专门解决.doc/.xls等历史格式无法直接读取的问题
5. 目录结构保持：转换后自动重建原始目录层级
6. 可搜索知识库：输出Markdown文件天然支持全文检索，便于构建企业知识库

潜在缺点与局限性

1. 外部依赖必需：必须安装LibreOffice（~300MB）和Python环境，无法纯浏览器运行
2. 复杂排版损失：复杂图文混排、嵌套表格、特殊字体可能转换不完美
3. PPT支持有限：幻灯片转换质量标注为"良好"而非"完美"
4. 图片型PDF不支持：扫描件/OCR需求需额外工具
5. Windows路径依赖：部分默认路径针对Windows优化，Linux/macOS需手动配置
6. 无实时预览：必须完成转换后才能查看结果

适合人群

• 企业IT/档案管理员：需要批量数字化历史文档
• 知识管理工程师：构建可搜索的Markdown知识库
• 开发者/技术写作者：将旧文档迁移到现代文档系统（GitBook/Docusaurus等）
• 合规审计人员：需要提取可审计的纯文本记录

常规风险

• 文件覆盖风险：同名文件可能覆盖，建议先用--dry-run模拟
• LibreOffice崩溃：极少数损坏文档可能导致转换进程中断，但错误隔离机制会记录并继续
• 编码异常：极少数非标准编码（GBK等）文档可能出现乱码
• 权限问题：系统级Office安装可能需要管理员权限运行

版本与维护

当前版本v1.0.4（2026-03-12），近期修复了外部脚本依赖问题，改为直接使用markitdown命令行工具，降低了部署复杂度。

核心功能与定位

document-organizer 是一款面向企业文档数字化的专业批量转换工具，核心功能是将旧版 Office 文档（.doc/.xls）及现代格式（.docx/.xlsx/.ppt/.pptx/.pdf）高质量转换为 Markdown 格式，同时完整保留标题层级、表格结构、样式标记等文档元数据。

该工具采用"LibreOffice + MarkItDown"双引擎架构：LibreOffice 负责旧格式预处理（如 .doc → .docx），MarkItDown 负责最终结构化输出。支持递归目录扫描、分类批量处理、原目录结构保持等生产级特性，实测 3,000 文件批量处理可在 10-12 分钟内完成。

显著优点

1. 格式覆盖全面：罕见地支持 .doc/.xls 等已淘汰格式，解决历史文档数字化痛点
2. 质量保障机制：承诺"完美保留"标题层级、表格结构、中文编码，非纯文本提取
3. 工程化设计：批量错误记录不中断流程、--dry-run 预览模式、300-600 秒超时控制
4. 无网络依赖：纯本地处理，符合敏感文档离线处理场景

局限性与注意事项

1. 外部工具依赖重：必须预装 LibreOffice（~300MB）和 Python markitdown 包，供应链安全风险由用户承担
2. PPT 转换质量降级：文档自评 .ppt/.pptx 仅为"良好"，复杂排版可能丢失
3. 无 OCR 能力：图片型 PDF 无法处理，需配合专用 OCR 工具
4. 个人开发者维护（T3）：无 GitHub 仓库公开，长期维护可持续性存疑

适用人群

• 企业知识管理/档案部门：历史文档批量数字化归档
• 技术写作者/文档工程师：构建可搜索的技术文档库
• 法律/金融合规岗位：敏感文档离线格式转换（需自行审计）

常规风险提示

| 风险类型 | 具体说明 | 缓解建议 |

|---------|---------|---------|

| 供应链风险 | 依赖 LibreOffice 和 markitdown，若被篡改可导致代码执行 | 务必从官网/PyPI 官方渠道安装，验证签名 |

| 文件覆盖风险 | 输出目录若与源目录重叠可能意外覆盖 | 始终使用独立输出目录（--output） |

| 敏感信息残留 | 临时目录 ./temp_batch 异常中断时可能残留 | 定期检查清理，或在安全环境运行 |

| 转换质量风险 | 复杂 Office 特性（宏、嵌套对象、特殊字体）可能丢失 | 关键文档建议抽样验证后再批量处理 |

安全认证摘要

CLS-Certify 评估为 A 级 / 78 分：subprocess 调用外部工具为功能必需，已实施超时控制；无网络通信；文件操作限定用户指定范围。主要扣分项为外部依赖透明度（DEPS 70 分）。

---

> 使用建议：作为一次性/周期性批处理工具而非服务部署，处理前务必使用 --dry-run 预览，并在外部依赖验证可信后执行转换。