Office 到 Markdown 转换技能（v2）

描述

将 Office 文档（PDF、DOC、DOCX、PPTX）转换为 Markdown 格式。该技能使用 word-extractor 库支持 .doc 格式，并提供完整的 OpenClaw 集成能力。

适用场景

• 需要从 Office 文档中提取文本时
• 希望将文档转换为可读性强的 Markdown 格式时
• 在 OpenClaw 中分析文档内容时
• 特别适用于处理遗留的 .doc 格式文件时

支持的格式

• PDF（.pdf）：使用 pdf-parse 进行文本提取
• Word（.docx）：使用 mammoth + turndown 保留格式
• 旧版 Word（.doc）：使用 word-extractor 进行文本提取（支持中文编码）
• PowerPoint（.pptx）：使用 python-pptx 进行基础文本提取

依赖项

• Node.js 及其 npm 包：pdf-parse、mammoth、turndown、word-extractor
• Python3 及 python-pptx（用于 PPTX 转换，可选）
• OpenClaw exec 工具执行权限

安装

1. 将技能复制到你的 workspace：

cp -r /root/.openclaw/workspace/office-to-md-v2/office-to-md /path/to/your/workspace/

2. 安装依赖项：

cd /path/to/your/workspace/office-to-md
npm install

3. 启用 PPTX 支持（可选）：

pip3 install python-pptx

在 OpenClaw 中的使用方式

方法 1：直接调用 exec

// 转换任意受支持的文档
const result = await exec(
  'node /path/to/office-to-md/openclaw-skill.js /path/to/document.doc',
  { workdir: '/path/to/workspace', timeout: 60000 }
);

if (result.exitCode === 0) {
  console.log('✅ 文档转换成功');
  // 输出文件路径：/path/to/document.md
} else {
  console.error('❌ 转换失败：', result.stderr);
}

方法 2：使用封装函数

// 导入转换器
const { convertOfficeToMarkdown } = require('/path/to/office-to-md/openclaw-skill.js');

// 转换文档
const conversionResult = await convertOfficeToMarkdown('/path/to/document.pdf');
if (conversionResult.success) {
  console.log(`输出路径：${conversionResult.outputPath}`);
  console.log(`预览内容：${conversionResult.preview}`);
} else {
  console.error(`错误信息：${conversionResult.error}`);
}

方法 3：完整的 OpenClaw 集成函数

async function convertDocumentToMarkdown(filePath) {
  // 验证文件是否存在
  try {
    await read(filePath);
  } catch (error) {
    return { success: false, error: `文件未找到：${filePath}` };
  }
  
  // 检查文件扩展名
  const ext = filePath.toLowerCase().slice(-5);
  const supported = ['.pdf', '.doc', '.docx', '.pptx'];
  if (!supported.some(s => ext.endsWith(s))) {
    return { 
      success: false, 
      error: `不支持的文件类型。支持的格式：${supported.join(', ')}` 
    };
  }
  
  // 使用技能执行转换
  const cmd = `node /path/to/office-to-md/openclaw-skill.js "${filePath}"`;
  const result = await exec(cmd, { 
    workdir: '/path/to/workspace',
    timeout: 120000 // 大型文件最多耗时 2 分钟
  });
  
  if (result.exitCode === 0) {
    const outputPath = filePath.replace(/.[^/.]+$/, '.md');
    return {
      success: true,
      outputPath: outputPath,
      message: `已转换为：${outputPath}`
    };
  } else {
    return {
      success: false,
      error: result.stderr || '转换失败'
    };
  }
}

// 使用示例
const result = await convertDocumentToMarkdown('/path/to/document.doc');
if (result.success) {
  const markdown = await read(result.outputPath);
  console.log(markdown.substring(0, 1000));
}

示例

示例 1：转换并分析文档

// 转换 .doc 文件并分析其内容
const docPath = '/path/to/document.doc';
const convertResult = await exec(
  `node /path/to/office-to-md/openclaw-skill.js "${docPath}"`,
  { workdir: '/path/to/workspace' }
);

if (convertResult.exitCode === 0) {
  const mdPath = docPath.replace('.doc', '.md');
  const content = await read(mdPath);
  
  // 分析内容
  const wordCount = content.split(/s+/).length;
  const lines = content.split('n').length;
  const hasChinese = /[u4e00-u9fff]/.test(content);
  
  console.log(`文档分析结果：`);
  console.log(`- 词数：${wordCount}`);
  console.log(`- 行数：${lines}`);
  console.log(`- 是否含中文：${hasChinese}`);
  console.log(`- 预览（前 200 字符）：${content.substring(0, 200)}...`);
}

示例 2：批量转换

// 批量转换多种格式的文档
const documents = [
  '/path/to/report.pdf',
  '/path/to/legacy.doc',
  '/path/to/modern.docx',
  '/path/to/presentation.pptx'
];

const results = [];
for (const doc of documents) {
  console.log(`正在转换 ${doc}...`);
  const result = await exec(
    `node /path/to/office-to-md/openclaw-skill.js "${doc}"`,
    { workdir: '/path/to/workspace', timeout: 90000 }
  );
  
  const success = result.exitCode === 0;
  results.push({
    file: doc,
    success: success,
    error: success ? null : result.stderr
  });
  
  console.log(success ? '✅ 成功' : '❌ 失败');
}

// 汇总统计
const successful = results.filter(r => r.success).length;
console.log(`n转换汇总：${successful}/${results.length} 个成功`);

API 参考

convertOfficeToMarkdown(filePath)

返回一个 Promise，其解析值为：

{
  success: boolean,
  outputPath?: string,
  markdown?: string,
  preview?: string,
  fileType?: string,
  message?: string,
  stats?: {
    lines: number,
    characters: number,
    words: number
  },
  error?: string,
  stack?: string
}

配置

超时设置

• 小文件（<1MB）：30 秒
• 中等文件（1–10MB）：60 秒
• 大文件（>10MB）：120 秒

内存限制

• 默认 Node.js 内存限制对大多数文档已足够
• 对于极大文件，可能需提升内存限制：

  node --max-old-space-size=4096 openclaw-skill.js large-file.doc
  

故障排查

常见问题

1. “文件未找到”

   • 检查文件路径及读取权限
   • 建议使用绝对路径以提高可靠性

2. “不支持的文件类型”

   • 确认文件扩展名是否正确
   • 验证文件实际格式是否与声明一致

3. .doc 文件转换出错

   • 文件可能已损坏或采用非标准格式
   • 建议先在 Word 中打开并另存为 .docx 格式再尝试转换

4. 中文显示为乱码

   • word-extractor 应能自动处理中文编码
   • 若仍存在问题，可能是文件采用了特殊编码

5. 超时错误

   • 针对大文件适当增加 timeout 值
   • 检查系统资源（CPU、内存）是否充足

调试模式

通过设置环境变量启用调试日志：

DEBUG=office-to-md node openclaw-skill.js document.doc

性能表现

• PDF：较快，取决于文件大小
• DOCX：快至中等，格式保留效果良好
• DOC：中等，需进行二进制解析
• PPTX：较慢，依赖 Python 及外部库

限制条件

• 文档中的图片不会被提取
• 复杂格式可能无法完全保留
• 表格转为 Markdown 时可能存在失真
• 极老旧或已损坏的 .doc 文件可能转换失败
• 不支持密码保护的文件

更新日志

v2.0.0（2026-02-15）

• 新增基于 word-extractor 的完整 .doc 支持
• 修复 pptConverter 的 ESM 兼容性问题
• 增强 OpenClaw 集成能力
• 优化中文文本提取能力
• 新增结构化输出，包含统计信息

v1.0.0（初始版本）

• 基础 PDF、DOCX、PPTX 支持
• 简易转换功能，不支持 .doc

许可证

本技能按“原样”提供。所依赖的底层库各自拥有独立许可证：

• pdf-parse：MIT
• mammoth：BSD-2-Clause
• turndown：MIT
• word-extractor：MIT
• python-pptx：MIT