convert-documents-skill 0.1.4

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

   从 v0.1.4 开始，安装器采用保守策略：

   • 如果你显式传入 --skills-dir PATH，就只写入这个 skills 根目录。
   • 如果未显式指定，安装器只会在“已知候选目录里恰好检测到 1 个现有 skills 根目录”时自动安装。
   • 如果检测到 0 个或多个候选目录，安装器会停止并提示你使用 --skills-dir，不再静默猜目录。

   推荐先看检测结果：

   python -m convert_documents_skill_install --list-detected
   

   明确指定目录安装：

   python -m convert_documents_skill_install --skills-dir "$env:USERPROFILE\.config\opencode\skills"
   

   先预览、不写文件：

   python -m convert_documents_skill_install --skills-dir "$env:USERPROFILE\.config\opencode\skills" --dry-run
   

   安装器会把 SKILL.md 写入解析出的 skills 根目录下的 convert-documents/SKILL.md，并把安装时的 Python 解释器路径写进 skill 模板。完成后，重启或重新加载 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。
   • 不同 OpenCode 运行形态（桌面版、终端、扩展、远程/容器集成）可能对应不同的 skills 根目录。若自动检测失败或出现多个候选目录，请总是显式传 --skills-dir。
   • --skills-dir 应该传入 OpenCode 的 skills 根目录，而不是最终的 convert-documents 子目录；安装器会自动在其下创建 convert-documents/SKILL.md。