OpenSkillIndex← back to search
claude-code

bruce-doc-converter

双向文档转换工具，将 Word (.docx)、Excel (.xlsx)、PowerPoint (.pptx) 和 PDF (.pdf) 转换为 AI 友好的 Markdown 格式，或将 Markdown (.md) 转换为 Word (.docx) 格式。当用户请求以下操作时使用：(1) 明确请求文档转换，包括任何包含"转换"、"转为"、"转成"、"convert"、"导出"、"export"等词汇的请求（例如："转换文档"、"把这个文件转为docx"、"convert to markdown"、"导出为Word"）；(2) 需要 AI 理解文档内容（"帮我分析这个 Word 文件"、"读取这个 PDF"、"总结这个 Excel"）；(3) 上传文档文件并询问内容（"这是什么"、"帮我看看"）；(4) 任何涉及 .docx、.xlsx、.pptx、.pdf、.md 文件格式转换的请求。

install
source · Clone the upstream repo
git clone https://github.com/bruc3van/bruce-doc-converter
Claude Code · Install into ~/.claude/skills/
git clone --depth=1 https://github.com/bruc3van/bruce-doc-converter ~/.claude/skills/bruc3van-bruce-doc-converter-bruce-doc-converter
manifest: SKILL.md
source content

Bruce Doc Converter

双向文档转换工具，将 Word (.docx)、Excel (.xlsx)、PowerPoint (.pptx) 和 PDF (.pdf) 转换为 AI 友好的 Markdown 格式，或将 Markdown (.md) 转换为 Word (.docx) 格式。

Quick Reference

Linux/macOS:

操作命令输出位置
Office/PDF → Markdown
bash convert.sh <file>
同目录 
Markdown/
Markdown → Word
bash convert.sh <file.md>
同目录 
Word/
批量转换
bash convert.sh --batch <dir>
同上

Windows: 见下方 跨平台执行方式

工作流程

用户请求转换 → 直接运行 bash convert.sh → 解析 JSON 输出 → 处理结果

关键原则：

  1. 不要预先检查任何依赖（Python 库、Node.js 等）
  2. 直接执行转换命令
  3. 只在转换失败（
    success: false
    ）时才根据错误信息处理

执行命令

跨平台执行方式

重要：根据运行环境选择正确的执行方式：

环境推荐命令说明
Linux/macOS
bash convert.sh <file>
使用 bash 执行（无需执行权限）
Windows PowerShell
powershell.exe -Command "cd '<skill-dir>' && .\convert.ps1 '<file>'"
推荐方式，支持 UTF-8 编码
Windows Git Bash
powershell.exe -Command "cd '<skill-dir>' && .\convert.ps1 '<file>'"
在 Git Bash 中调用 PowerShell
Windows CMD
convert.bat <file>
传统方式，可能有编码问题

Claude Code 中的最佳实践：

  • 在 Windows 环境（包括 Git Bash）中，始终使用 PowerShell 执行： 
    powershell.exe -Command "Set-Location '<skill-dir>'; .\convert.ps1 'c:\path\to\file.docx'"
  • 路径中包含空格时，使用单引号包裹
  • 使用 
    Set-Location
    而不是 
    cd
    ，避免 PowerShell 语法错误
  • <skill-dir>
    替换为实际的 skill 目录路径（例如 
    C:\Users\<YourName>\.claude\skills\bruce-doc-converter-skill
    ）

命令示例

# 单文件转换（依赖自动安装）
bash convert.sh /path/to/document.docx

# 自定义输出目录
bash convert.sh /path/to/file.pdf true /custom/output

# 批量转换
bash convert.sh --batch /path/to/documents

解析输出

脚本返回 JSON，关键字段：

{
  "success": true,
  "output_path": "/path/to/output.md",
  "markdown_content": "# 转换后的内容..."
}

  • success
    : 转换是否成功
  • output_path
    : 输出文件路径
  • markdown_content
    : Markdown 内容（方便直接分析）
  • error
    : 错误信息（失败时）

错误处理

仅在转换失败时（返回 

success: false
）才处理错误：

错误类型处理方法
Python 依赖缺失脚本会自动安装，如失败则运行 
pip install --user xxx
未找到 Node.js
仅在 MD→DOCX 转换失败且报此错误时，才提示安装 Node.js
Node.js 依赖未安装
脚本会自动安装到用户级共享目录；失败时在 
scripts/md_to_docx
或共享目录运行 
npm install
文件不存在
提示用户验证文件路径
不支持的文件格式: .doc
提示用户先转换为 .docx
文件过大
提示超过 100MB 限制

支持的格式

格式转换方向质量
.docx↔优秀
.xlsx→优秀
.pptx→良好
.pdf→取决于 PDF 类型
.md↔优秀

注意事项

重要：

  • 绝对不要在执行转换前检查任何依赖（包括 Python、Node.js、npm 包等）
  • 直接执行转换命令，让脚本自己检测和处理依赖
  • 只在转换失败时才根据返回的错误信息采取行动

其他：

  • Python 依赖会自动安装到用户目录
  • Node.js 依赖会自动安装到用户级共享目录（可用 
    BRUCE_DOC_CONVERTER_NODE_HOME
    指定）
  • 默认共享目录：macOS/Linux 
    ~/.bruce-doc-converter/node/md_to_docx
    ，Windows 
    %LOCALAPPDATA%\BruceDocConverter\node\md_to_docx
  • .doc/.xls/.ppt 旧格式需先转换为对应的新格式