convert-documents-skill 0.1.3

Convert .doc/.docx/.xlsx to Markdown and install as an OpenCode skill (optional .doc -> .docx via pywin32 on Windows)

convert-documents-skill

这是一个 Python 实现的文档转换工具（以 PyPI 为发布目标）。它将 .doc/.docx 转为 Markdown，并将 .xlsx 转为包含每个 Sheet 的 Markdown。输出会包含同名文件夹、.md 文件以及 _images/ 图片文件夹。并且它可以被安装为 OpenCode 的自定义 skill，以 slash 命令形式直接调用。

使用（推荐 Python 方式）

1. 在虚拟环境中安装依赖：

   python -m venv .venv .venv\Scripts\activate # Windows pip install -r requirements.txt

2. 运行转换：

   python convert_documents_skill.py path/to/file.docx

说明：

• 支持 .docx（默认）和 .xlsx（Sheet -> Markdown）。
• 额外支持：.doc（需要 Windows + MS Word + pywin32）。脚本会尝试通过 COM 将 .doc 转为 .docx 后再处理；若未安装 pywin32 或 MS Word，会输出友好的报错信息。
• 还支持安装为 OpenCode skill：安装包后优先执行 python -m convert_documents_skill_install，会把 SKILL.md 写入 OpenCode 全局 skill 目录。

输出：在源文件同级目录生成一个同名文件夹，里面包含 .md 和 _images/。

注意事项

• 若要转换 .doc（旧格式），请在 Windows 上安装 Microsoft Word 并 pip install pywin32。脚本会在转换失败时打印明确错误。
• 如果你的文档很复杂，mammoth 的转换结果可能需要人工校对。

Publishing

To publish to PyPI:

1. Ensure pyproject.toml and setup.cfg are updated with your metadata.
2. Build distributions: python -m build
3. Upload: python -m twine upload dist/*

在 OpenCode 中使用本 skill（推荐方式）

1. 安装 Python 包

   pip install convert-documents-skill

2. 安装为 OpenCode 全局 skill

   python -m convert_documents_skill_install

   如果你的系统 PATH 已包含 Python Scripts 目录，也可以使用：

   install-convert-documents-skill

   这会把 SKILL.md 写入 OpenCode 全局 skill 目录。安装器会优先探测你机器上已经存在的 OpenCode skills 根目录（例如 ~/.config/opencode/skills），避免写到 OpenCode 实际不读取的位置。完成后，重启或重新加载 OpenCode。

3. 在 OpenCode 中直接使用 slash 命令

   /convert-documents

   然后提供文件路径，例如：

   请把 D:\\docs\\策划案.docx 转成 Markdown。

   Skill 会优先使用安装时对应的 Python 解释器去执行：

   python -m convert_documents_skill "<file-path>"

4. 如果只想使用 CLI，也可以直接运行：

   convert-docs /workspace/input/design.docx

5. OpenCode 集成注意事项

   • 若只处理 .docx/.xlsx，Linux 容器即可；若需要处理 .doc（旧格式），必须在 Windows 且安装 MS Word + pywin32。
   • 推荐在 OpenCode 流程中只传入 .docx/.xlsx；若仍需支持 .doc，请在预处理步骤中把 .doc 转为 .docx，或在 Windows 节点执行。
   • 若 OpenCode 中调用失败，通常是因为运行环境与安装包所在 Python 环境不一致；重新在 OpenCode 使用的同一环境中执行 pip install convert-documents-skill 与 python -m convert_documents_skill_install。