Metadata-Version: 2.4
Name: convert-documents-skill
Version: 0.1.4
Summary: Convert .doc/.docx/.xlsx to Markdown and install as an OpenCode skill (optional .doc -> .docx via pywin32 on Windows)
Author-email: tianji <shibutianji@163.com>
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mammoth
Requires-Dist: pandas
Requires-Dist: openpyxl
Provides-Extra: windows
Requires-Dist: pywin32; platform_system == "Windows" and extra == "windows"
Dynamic: license-file

# convert-documents-skill

这是一个 Python 实现的文档转换工具（以 PyPI 为发布目标）。它将 .doc/.docx 转为 Markdown，并将 .xlsx 转为包含每个 Sheet 的 Markdown。输出会包含同名文件夹、.md 文件以及 <basename>_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 目录。

输出：在源文件同级目录生成一个同名文件夹，里面包含 <basename>.md 和 <basename>_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`，不再静默猜目录。

   推荐先看检测结果：

   ```powershell
   python -m convert_documents_skill_install --list-detected
   ```

   明确指定目录安装：

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

   先预览、不写文件：

   ```powershell
   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`。
