ming-tomarkdown 0.1.1__tar.gz

ming_tomarkdown-0.1.1/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local credentials and generated output
+.env
+.env.*
+!.env.example
+results/
+.DS_Store
+
+# test
+test

ming_tomarkdown-0.1.1/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: ming-tomarkdown
+Version: 0.1.1
+Summary: Convert documents and folders to Markdown with vision OCR
+Project-URL: Repository, https://github.com/MingWangD/ToMarkdown
+Project-URL: Issues, https://github.com/MingWangD/ToMarkdown/issues
+Requires-Python: >=3.12
+Requires-Dist: markitdown-ocr>=0.1.0
+Requires-Dist: markitdown[all]>=0.1.5
+Requires-Dist: openai>=3.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# Ming ToMarkdown
+
+将 PDF、Word、Excel、PowerPoint、图片和文本文件转换为 Markdown 的 Python 包，支持终端命令和 Python 调用。
+
+安装包名为 `ming-tomarkdown`，终端命令和 Python 导入名仍为 `tomarkdown`。GitHub 仓库名称保持 `ToMarkdown`。
+
+默认开启图片 OCR：正文文字直接提取，图片交给视觉模型识别，再合并为 Markdown。支持单文件和混合格式文件夹，批量转换会保留输入文件夹名称。
+
+## 安装
+
+需要 Python 3.12 或更高版本。在已有虚拟环境中，可用 uv 直接安装 GitHub 发布版本，无需 Git：
+
+```bash
+uv pip install "https://github.com/MingWangD/ToMarkdown/releases/download/v0.1.1/ming_tomarkdown-0.1.1-py3-none-any.whl"
+```
+
+尚未创建虚拟环境时，先执行 `uv venv --python 3.12` 并激活环境。macOS / Linux 使用 `source .venv/bin/activate`，Windows PowerShell 使用 `.venv\Scripts\Activate.ps1`。
+
+也可以通过 pip 从 GitHub 源码安装：
+
+```bash
+python -m pip install "ming-tomarkdown @ git+https://github.com/MingWangD/ToMarkdown.git@v0.1.1"
+```
+
+这种安装方式需要本机已有 Git。也可以从仓库的 [Releases](https://github.com/MingWangD/ToMarkdown/releases) 下载 `.whl`，直接安装，无需 Git：
+
+```bash
+python -m pip install ./ming_tomarkdown-0.1.1-py3-none-any.whl
+```
+
+仅使用终端命令，也可以用 uv 安装：
+
+```bash
+uv tool install "https://github.com/MingWangD/ToMarkdown/releases/download/v0.1.1/ming_tomarkdown-0.1.1-py3-none-any.whl"
+```
+
+当前通过 GitHub 分发，尚未发布到 PyPI，请使用以上安装地址。
+
+旧版 GitHub 包的安装名为 `tomarkdown`，升级前请在对应环境运行 `uv pip uninstall tomarkdown`（或 `python -m pip uninstall tomarkdown`），再安装新包。两者提供相同的导入模块和命令，不应同时安装。
+
+## 快速开始
+
+无需模型配置即可先验证普通转换：
+
+```bash
+tomarkdown "/路径/文档.pdf" --no-ocr
+```
+
+配置好下一节的 OCR 服务后，直接运行：
+
+```bash
+# 单个文件
+tomarkdown "/路径/论文.pdf"
+
+# 混合格式文件夹：PDF、Word、Excel 等
+tomarkdown "/路径/资料"
+```
+
+终端命令不需要先 `import`。如果终端找不到 `tomarkdown`，可以用安装该包的 Python 运行：
+
+```bash
+python -m tomarkdown "/路径/资料"
+```
+
+## 通用 OCR 配置
+
+使用支持图片输入、兼容 OpenAI Chat Completions 接口的模型服务。在运行命令的目录创建 `.env`：
+
+```dotenv
+OPENAI_API_KEY=服务提供的_API_Key
+OPENAI_MODEL=服务支持的视觉模型名称
+OPENAI_BASE_URL=服务提供的_OpenAI_兼容接口基础地址
+```
+
+`OPENAI_` 是变量名称，不限定模型提供商。密钥、模型和接口地址需要对应同一个服务；接口地址不要追加 `/chat/completions`。也可以直接设置系统环境变量，同名系统环境变量优先于 `.env`。
+
+配置优先级：
+
+- 模型：显式参数 → `MODEL` → `OPENAI_MODEL` → `GEMINI_MODEL` → `gemini-3.8-flash-high`。
+- 密钥：Python 调用的 `api_key` 参数 → `GEMINI_API_KEY` → `OPENAI_API_KEY`。
+- 接口：显式参数 → `OPENAI_BASE_URL` → `http://127.0.0.1:8045/v1`。
+
+最后的模型名和接口地址沿用原项目默认值，不代表你的服务一定提供该模型。使用通用配置时，应填写实际服务信息，并清除不再使用的 `MODEL`、`GEMINI_API_KEY` 等旧值。
+
+### 一个具体例子
+
+假设本地服务已在 `http://127.0.0.1:8045/v1` 启动，提供名为 `vision-model` 的视觉模型。在当前目录的 `.env` 中填写：
+
+```dotenv
+OPENAI_API_KEY=你的本地服务密钥
+OPENAI_MODEL=vision-model
+OPENAI_BASE_URL=http://127.0.0.1:8045/v1
+```
+
+`vision-model` 和密钥需要替换为实际值。然后运行：
+
+```bash
+tomarkdown "/路径/论文.pdf"
+```
+
+结果保存在当前目录下的 `results/论文.md`。
+
+## 在 Python 中调用
+
+```python
+from tomarkdown import convert
+
+# 默认开启 OCR，读取当前工作目录的 .env
+result = convert("/路径/资料")
+
+for path in result.files:
+    print("已保存：", path)
+
+for source, error in result.errors.items():
+    print("转换失败：", source, error)
+```
+
+也可以直接传入配置：
+
+```python
+import os
+from tomarkdown import convert
+
+result = convert(
+    "/路径/论文.pdf",
+    api_key=os.environ["OPENAI_API_KEY"],
+    model="你的视觉模型名称",
+    base_url="http://127.0.0.1:8045/v1",
+    show_progress=True,
+)
+```
+
+关闭 OCR：
+
+```python
+result = convert("/路径/报告.docx", ocr=False)
+```
+
+`convert()` 返回 `ConversionResult`：`files` 是成功输出的 `Path` 列表，`errors` 是输入路径到错误信息的字典。单个文件转换失败后会继续处理其他文件；无效输入路径、缺少密钥等配置错误会直接抛出异常。
+
+Python 调用默认不显示终端进度，可用 `show_progress=True` 开启；也可通过 `results_dir="/路径/results"` 指定结果根目录。
+
+## 输出规则
+
+安装包后，命令及 Python 调用默认将结果写入**当前工作目录**的 `results/`，不会写进包的安装目录。所需目录会自动创建。
+
+```text
+单文件输入：/路径/论文.pdf
+输出：      results/论文.md
+
+文件夹输入：/路径/资料/
+            ├── 论文.pdf
+            ├── 报告.docx
+            └── 数据.xlsx
+输出：      results/资料/
+            ├── 论文.md
+            ├── 报告.md
+            └── 数据.md
+```
+
+保留源文件名，只把扩展名改为 `.md`，例如 `报告.v2.pdf` → `报告.v2.md`。同一输出目录下的同名结果会覆盖，`报告.pdf` 与 `报告.docx` 也会写入同一个 `报告.md`。
+
+文件夹只处理当前层，按文件名排序逐个转换，不进入子文件夹，跳过不支持的扩展名。终端显示文件序号、耗时及成功/失败数量，不显示页数或百分比；存在转换失败时命令以非零状态退出。
+
+## 命令参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `file` | 文件或文件夹路径，必填 |
+| `--model` | 指定视觉模型，覆盖环境变量 |
+| `--base-url` | 指定 OpenAI 兼容接口基础地址，覆盖环境变量 |
+| `--no-ocr` | 关闭 OCR，不调用模型；默认开启 OCR |
+| `-h`、`--help` | 查看帮助 |
+
+```bash
+tomarkdown "/路径/文档.pdf" --model "你的视觉模型名称"
+tomarkdown "/路径/资料" --no-ocr
+tomarkdown --help
+```
+
+## 支持的内容与处理流程
+
+支持 PDF、Word（`.docx`）、Excel（`.xlsx`、`.xls`）、PowerPoint（`.pptx`）、图片、HTML，以及 TXT、CSV、JSON、XML 等文本格式。旧版 Word `.doc` 不在批量处理范围内。
+
+```text
+这一页 PDF
+├── 文字层 → 直接提取
+└── 图片   → LLM 识别
+                ↓
+          合并成 Markdown
+```
+
+扫描件中的正文通常属于图片，需要 OCR。复杂排版、表格和公式的还原取决于文件内容、MarkItDown 插件及模型。JSON、XML 等文本主要保留原文。OCR 插件内部未抛出的识别错误不会计入失败数量。
+
+## 从源码运行与构建
+
+```bash
+git clone https://github.com/MingWangD/ToMarkdown.git
+cd ToMarkdown
+uv sync
+
+# 安装包后的命令入口
+uv run tomarkdown "/路径/资料"
+
+# 保留原有脚本入口：读取项目 .env，结果固定保存到项目 results/
+uv run python to_md.py "/路径/资料"
+
+# 生成 wheel 和源码包，输出到 dist/
+uv build --no-sources
+```
+
+核心代码位于 `src/tomarkdown/`。根目录的 `to_md.py` 和 `ui.py` 保留为原有用法的兼容入口。发布包不包含 `.env`、转换结果或本地样例文件。
+
+## 维护者：首次发布到 PyPI
+
+仓库提供 `.github/workflows/publish.yml`，通过 GitHub Actions 可信发布，无需配置 PyPI API Token。
+
+首次使用时，登录 PyPI 并打开[账号的 Publishing 页面](https://pypi.org/manage/account/publishing/)，添加 GitHub 待发布项目，填写：
+
+| 字段 | 值 |
+| --- | --- |
+| PyPI Project Name | `ming-tomarkdown` |
+| Owner | `MingWangD` |
+| Repository name | `ToMarkdown` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+保存后，在 GitHub Actions 的 **Publish to PyPI** 流程中选择 **Run workflow**，勾选 **Publish to PyPI after building** 即可发布；不勾选时仅检查构建。此后发布新的 GitHub Release 也会自动触发 PyPI 发布。发布新版本前需先更新 `pyproject.toml` 中的版本号及依赖锁定文件。
+
+首次发布成功后，其他人就可以用 `uv pip install ming-tomarkdown` 安装。

ming_tomarkdown-0.1.1/README.md

@@ -0,0 +1,230 @@
+# Ming ToMarkdown
+
+将 PDF、Word、Excel、PowerPoint、图片和文本文件转换为 Markdown 的 Python 包，支持终端命令和 Python 调用。
+
+安装包名为 `ming-tomarkdown`，终端命令和 Python 导入名仍为 `tomarkdown`。GitHub 仓库名称保持 `ToMarkdown`。
+
+默认开启图片 OCR：正文文字直接提取，图片交给视觉模型识别，再合并为 Markdown。支持单文件和混合格式文件夹，批量转换会保留输入文件夹名称。
+
+## 安装
+
+需要 Python 3.12 或更高版本。在已有虚拟环境中，可用 uv 直接安装 GitHub 发布版本，无需 Git：
+
+```bash
+uv pip install "https://github.com/MingWangD/ToMarkdown/releases/download/v0.1.1/ming_tomarkdown-0.1.1-py3-none-any.whl"
+```
+
+尚未创建虚拟环境时，先执行 `uv venv --python 3.12` 并激活环境。macOS / Linux 使用 `source .venv/bin/activate`，Windows PowerShell 使用 `.venv\Scripts\Activate.ps1`。
+
+也可以通过 pip 从 GitHub 源码安装：
+
+```bash
+python -m pip install "ming-tomarkdown @ git+https://github.com/MingWangD/ToMarkdown.git@v0.1.1"
+```
+
+这种安装方式需要本机已有 Git。也可以从仓库的 [Releases](https://github.com/MingWangD/ToMarkdown/releases) 下载 `.whl`，直接安装，无需 Git：
+
+```bash
+python -m pip install ./ming_tomarkdown-0.1.1-py3-none-any.whl
+```
+
+仅使用终端命令，也可以用 uv 安装：
+
+```bash
+uv tool install "https://github.com/MingWangD/ToMarkdown/releases/download/v0.1.1/ming_tomarkdown-0.1.1-py3-none-any.whl"
+```
+
+当前通过 GitHub 分发，尚未发布到 PyPI，请使用以上安装地址。
+
+旧版 GitHub 包的安装名为 `tomarkdown`，升级前请在对应环境运行 `uv pip uninstall tomarkdown`（或 `python -m pip uninstall tomarkdown`），再安装新包。两者提供相同的导入模块和命令，不应同时安装。
+
+## 快速开始
+
+无需模型配置即可先验证普通转换：
+
+```bash
+tomarkdown "/路径/文档.pdf" --no-ocr
+```
+
+配置好下一节的 OCR 服务后，直接运行：
+
+```bash
+# 单个文件
+tomarkdown "/路径/论文.pdf"
+
+# 混合格式文件夹：PDF、Word、Excel 等
+tomarkdown "/路径/资料"
+```
+
+终端命令不需要先 `import`。如果终端找不到 `tomarkdown`，可以用安装该包的 Python 运行：
+
+```bash
+python -m tomarkdown "/路径/资料"
+```
+
+## 通用 OCR 配置
+
+使用支持图片输入、兼容 OpenAI Chat Completions 接口的模型服务。在运行命令的目录创建 `.env`：
+
+```dotenv
+OPENAI_API_KEY=服务提供的_API_Key
+OPENAI_MODEL=服务支持的视觉模型名称
+OPENAI_BASE_URL=服务提供的_OpenAI_兼容接口基础地址
+```
+
+`OPENAI_` 是变量名称，不限定模型提供商。密钥、模型和接口地址需要对应同一个服务；接口地址不要追加 `/chat/completions`。也可以直接设置系统环境变量，同名系统环境变量优先于 `.env`。
+
+配置优先级：
+
+- 模型：显式参数 → `MODEL` → `OPENAI_MODEL` → `GEMINI_MODEL` → `gemini-3.8-flash-high`。
+- 密钥：Python 调用的 `api_key` 参数 → `GEMINI_API_KEY` → `OPENAI_API_KEY`。
+- 接口：显式参数 → `OPENAI_BASE_URL` → `http://127.0.0.1:8045/v1`。
+
+最后的模型名和接口地址沿用原项目默认值，不代表你的服务一定提供该模型。使用通用配置时，应填写实际服务信息，并清除不再使用的 `MODEL`、`GEMINI_API_KEY` 等旧值。
+
+### 一个具体例子
+
+假设本地服务已在 `http://127.0.0.1:8045/v1` 启动，提供名为 `vision-model` 的视觉模型。在当前目录的 `.env` 中填写：
+
+```dotenv
+OPENAI_API_KEY=你的本地服务密钥
+OPENAI_MODEL=vision-model
+OPENAI_BASE_URL=http://127.0.0.1:8045/v1
+```
+
+`vision-model` 和密钥需要替换为实际值。然后运行：
+
+```bash
+tomarkdown "/路径/论文.pdf"
+```
+
+结果保存在当前目录下的 `results/论文.md`。
+
+## 在 Python 中调用
+
+```python
+from tomarkdown import convert
+
+# 默认开启 OCR，读取当前工作目录的 .env
+result = convert("/路径/资料")
+
+for path in result.files:
+    print("已保存：", path)
+
+for source, error in result.errors.items():
+    print("转换失败：", source, error)
+```
+
+也可以直接传入配置：
+
+```python
+import os
+from tomarkdown import convert
+
+result = convert(
+    "/路径/论文.pdf",
+    api_key=os.environ["OPENAI_API_KEY"],
+    model="你的视觉模型名称",
+    base_url="http://127.0.0.1:8045/v1",
+    show_progress=True,
+)
+```
+
+关闭 OCR：
+
+```python
+result = convert("/路径/报告.docx", ocr=False)
+```
+
+`convert()` 返回 `ConversionResult`：`files` 是成功输出的 `Path` 列表，`errors` 是输入路径到错误信息的字典。单个文件转换失败后会继续处理其他文件；无效输入路径、缺少密钥等配置错误会直接抛出异常。
+
+Python 调用默认不显示终端进度，可用 `show_progress=True` 开启；也可通过 `results_dir="/路径/results"` 指定结果根目录。
+
+## 输出规则
+
+安装包后，命令及 Python 调用默认将结果写入**当前工作目录**的 `results/`，不会写进包的安装目录。所需目录会自动创建。
+
+```text
+单文件输入：/路径/论文.pdf
+输出：      results/论文.md
+
+文件夹输入：/路径/资料/
+            ├── 论文.pdf
+            ├── 报告.docx
+            └── 数据.xlsx
+输出：      results/资料/
+            ├── 论文.md
+            ├── 报告.md
+            └── 数据.md
+```
+
+保留源文件名，只把扩展名改为 `.md`，例如 `报告.v2.pdf` → `报告.v2.md`。同一输出目录下的同名结果会覆盖，`报告.pdf` 与 `报告.docx` 也会写入同一个 `报告.md`。
+
+文件夹只处理当前层，按文件名排序逐个转换，不进入子文件夹，跳过不支持的扩展名。终端显示文件序号、耗时及成功/失败数量，不显示页数或百分比；存在转换失败时命令以非零状态退出。
+
+## 命令参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `file` | 文件或文件夹路径，必填 |
+| `--model` | 指定视觉模型，覆盖环境变量 |
+| `--base-url` | 指定 OpenAI 兼容接口基础地址，覆盖环境变量 |
+| `--no-ocr` | 关闭 OCR，不调用模型；默认开启 OCR |
+| `-h`、`--help` | 查看帮助 |
+
+```bash
+tomarkdown "/路径/文档.pdf" --model "你的视觉模型名称"
+tomarkdown "/路径/资料" --no-ocr
+tomarkdown --help
+```
+
+## 支持的内容与处理流程
+
+支持 PDF、Word（`.docx`）、Excel（`.xlsx`、`.xls`）、PowerPoint（`.pptx`）、图片、HTML，以及 TXT、CSV、JSON、XML 等文本格式。旧版 Word `.doc` 不在批量处理范围内。
+
+```text
+这一页 PDF
+├── 文字层 → 直接提取
+└── 图片   → LLM 识别
+                ↓
+          合并成 Markdown
+```
+
+扫描件中的正文通常属于图片，需要 OCR。复杂排版、表格和公式的还原取决于文件内容、MarkItDown 插件及模型。JSON、XML 等文本主要保留原文。OCR 插件内部未抛出的识别错误不会计入失败数量。
+
+## 从源码运行与构建
+
+```bash
+git clone https://github.com/MingWangD/ToMarkdown.git
+cd ToMarkdown
+uv sync
+
+# 安装包后的命令入口
+uv run tomarkdown "/路径/资料"
+
+# 保留原有脚本入口：读取项目 .env，结果固定保存到项目 results/
+uv run python to_md.py "/路径/资料"
+
+# 生成 wheel 和源码包，输出到 dist/
+uv build --no-sources
+```
+
+核心代码位于 `src/tomarkdown/`。根目录的 `to_md.py` 和 `ui.py` 保留为原有用法的兼容入口。发布包不包含 `.env`、转换结果或本地样例文件。
+
+## 维护者：首次发布到 PyPI
+
+仓库提供 `.github/workflows/publish.yml`，通过 GitHub Actions 可信发布，无需配置 PyPI API Token。
+
+首次使用时，登录 PyPI 并打开[账号的 Publishing 页面](https://pypi.org/manage/account/publishing/)，添加 GitHub 待发布项目，填写：
+
+| 字段 | 值 |
+| --- | --- |
+| PyPI Project Name | `ming-tomarkdown` |
+| Owner | `MingWangD` |
+| Repository name | `ToMarkdown` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+保存后，在 GitHub Actions 的 **Publish to PyPI** 流程中选择 **Run workflow**，勾选 **Publish to PyPI after building** 即可发布；不勾选时仅检查构建。此后发布新的 GitHub Release 也会自动触发 PyPI 发布。发布新版本前需先更新 `pyproject.toml` 中的版本号及依赖锁定文件。
+
+首次发布成功后，其他人就可以用 `uv pip install ming-tomarkdown` 安装。

ming_tomarkdown-0.1.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "ming-tomarkdown"
+version = "0.1.1"
+description = "Convert documents and folders to Markdown with vision OCR"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "python-dotenv>=1.0.0",
+    "markitdown-ocr>=0.1.0",
+    "markitdown[all]>=0.1.5",
+    "openai>=3.31.0",
+]
+
+[project.scripts]
+tomarkdown = "tomarkdown.cli:main"
+
+[project.urls]
+Repository = "https://github.com/MingWangD/ToMarkdown"
+Issues = "https://github.com/MingWangD/ToMarkdown/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tomarkdown"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/tomarkdown", "/README.md", "/pyproject.toml", "/to_md.py", "/ui.py"]

ming_tomarkdown-0.1.1/src/tomarkdown/__init__.py

@@ -0,0 +1,5 @@
+"""将文件或文件夹转换为 Markdown。"""
+
+from .core import ConversionResult, convert
+
+__all__ = ["ConversionResult", "convert"]

ming_tomarkdown-0.1.1/src/tomarkdown/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ming_tomarkdown-0.1.1/src/tomarkdown/cli.py

@@ -0,0 +1,31 @@
+"""tomarkdown 命令入口。"""
+
+import argparse
+from pathlib import Path
+
+from .core import convert
+
+
+def main(*, results_dir: Path | None = None) -> int:
+    parser = argparse.ArgumentParser(description="将文件或文件夹转换为 Markdown，默认开启图片 OCR。")
+    parser.add_argument("file", type=Path, help="文件或文件夹路径（文件夹只处理当前层）")
+    parser.add_argument("--no-ocr", action="store_true", help="仅进行常规提取，不调用模型")
+    parser.add_argument("--model", help="视觉模型名称；默认读取 MODEL、OPENAI_MODEL 或 GEMINI_MODEL")
+    parser.add_argument("--base-url", help="OpenAI 兼容接口地址，也可设置 OPENAI_BASE_URL")
+    args = parser.parse_args()
+    try:
+        result = convert(
+            args.file,
+            ocr=not args.no_ocr,
+            model=args.model,
+            base_url=args.base_url,
+            results_dir=results_dir,
+            show_progress=True,
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        parser.error(str(exc))
+    if not result.files and not result.errors:
+        print("文件夹中没有可转换的文件。")
+    else:
+        print(f"处理结束：成功 {len(result.files)} 个，失败 {len(result.errors)} 个。")
+    return 1 if result.errors else 0

ming_tomarkdown-0.1.1/src/tomarkdown/core.py

@@ -0,0 +1,103 @@
+"""文件转换与批量转换，可独立于命令行使用。"""
+
+import os
+import sys
+from contextlib import ExitStack, nullcontext
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+from markitdown import MarkItDown
+from openai import OpenAI
+
+from .ui import progress
+
+SUPPORTED_EXTENSIONS = {
+    ".pdf", ".docx", ".xlsx", ".xls", ".pptx",
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tif", ".tiff", ".webp",
+    ".html", ".htm", ".txt", ".csv", ".json", ".xml",
+}
+
+
+@dataclass
+class ConversionResult:
+    """files 为成功保存的路径，errors 为输入路径与错误信息的对应关系。"""
+
+    files: list[Path] = field(default_factory=list)
+    errors: dict[Path, str] = field(default_factory=dict)
+
+
+def convert(
+    source: str | Path,
+    *,
+    ocr: bool = True,
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    results_dir: str | Path | None = None,
+    show_progress: bool = False,
+) -> ConversionResult:
+    """转换文件或文件夹，默认写入当前目录的 results；批量时保留文件夹名。
+
+    默认读取当前目录的 .env。显式参数优先于环境变量。
+    配置和输入路径错误会抛出异常；单文件转换错误记录在返回值的 errors 中，
+    批量处理会继续。默认不显示终端进度。
+    """
+    load_dotenv(Path.cwd() / ".env")
+    input_path = Path(source).expanduser().resolve()
+    output_dir = Path(results_dir).expanduser().resolve() if results_dir is not None else Path.cwd() / "results"
+    if input_path.is_dir():
+        output_dir /= input_path.name
+        sources = sorted(
+            path for path in input_path.iterdir()
+            if path.is_file() and path.suffix.lower() in SUPPORTED_EXTENSIONS
+        )
+    elif input_path.is_file():
+        sources = [input_path]
+    else:
+        raise FileNotFoundError(f"输入路径不存在或不是文件/文件夹：{input_path}")
+
+    result = ConversionResult()
+    if not sources:
+        return result
+
+    model = model or os.getenv("MODEL") or os.getenv("OPENAI_MODEL") or os.getenv("GEMINI_MODEL") or "gemini-3.8-flash-high"
+    api_key = api_key or os.getenv("GEMINI_API_KEY") or os.getenv("OPENAI_API_KEY")
+    base_url = base_url or os.getenv("OPENAI_BASE_URL", "http://127.0.0.1:8045/v1")
+    if ocr and not api_key:
+        raise ValueError("OCR 需要 API Key，请配置 OPENAI_API_KEY 或传入 api_key。")
+
+    with ExitStack() as stack:
+        if ocr:
+            client = stack.enter_context(OpenAI(base_url=base_url, api_key=api_key))
+            converter = MarkItDown(
+                enable_plugins=True,
+                llm_client=client,
+                llm_model=model,
+                llm_prompt=(
+                    "提取图片中所有文字，保留原文语言、阅读顺序、标题、表格和公式。"
+                    "以 Markdown 输出，公式使用 LaTeX。"
+                    "只返回提取的内容，不添加解释，不用代码块包裹全文。"
+                ),
+            )
+        else:
+            converter = MarkItDown()
+
+        for index, path in enumerate(sources, start=1):
+            output = output_dir / f"{path.stem}.md"
+            try:
+                if path == output:
+                    raise ValueError("输入文件不能与输出文件相同。")
+                status = progress(f"[{index}/{len(sources)}] 正在转换 {path.name}") if show_progress else nullcontext()
+                with status:
+                    converted = converter.convert(str(path))
+                    output.parent.mkdir(parents=True, exist_ok=True)
+                    output.write_text(converted.text_content + "\n", encoding="utf-8")
+                result.files.append(output)
+                if show_progress:
+                    print(f"已保存：{output}")
+            except Exception as exc:
+                result.errors[path] = str(exc)
+                if show_progress:
+                    print(f"转换失败：{path.name}：{exc}", file=sys.stderr)
+    return result

ming_tomarkdown-0.1.1/src/tomarkdown/ui.py

@@ -0,0 +1,42 @@
+"""终端进度显示：转换期间显示动画和耗时，不估算完成百分比。"""
+
+import sys
+import time
+from contextlib import contextmanager
+from itertools import cycle
+from threading import Event, Thread
+from typing import Iterator
+
+
+@contextmanager
+def progress(message: str) -> Iterator[None]:
+    """在终端显示等待动画；重定向输出时只打印开始和结束状态。"""
+    started = time.monotonic()
+    stopped = Event()
+    terminal = sys.stderr.isatty()
+
+    def animate() -> None:
+        for frame in cycle("|/-\\"):
+            elapsed = time.monotonic() - started
+            print(f"\r{frame} {message}（{elapsed:.1f}s）", end="", file=sys.stderr, flush=True)
+            if stopped.wait(0.1):
+                break
+
+    worker = Thread(target=animate, daemon=True) if terminal else None
+    if worker:
+        worker.start()
+    else:
+        print(message, file=sys.stderr)
+
+    completed = False
+    try:
+        yield
+        completed = True
+    finally:
+        stopped.set()
+        if worker:
+            worker.join()
+        status = "处理完成" if completed else "处理未完成"
+        prefix = "\r\033[2K" if terminal else ""
+        elapsed = time.monotonic() - started
+        print(f"{prefix}{status}，耗时 {elapsed:.1f}s", file=sys.stderr, flush=True)

ming_tomarkdown-0.1.1/to_md.py

@@ -0,0 +1,11 @@
+"""兼容原有脚本用法，结果仍保存到本项目的 results 文件夹。"""
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+from tomarkdown.cli import main
+
+if __name__ == "__main__":
+    project_dir = Path(__file__).resolve().parent
+    load_dotenv(project_dir / ".env")
+    raise SystemExit(main(results_dir=project_dir / "results"))

ming_tomarkdown-0.1.1/ui.py

@@ -0,0 +1,5 @@
+"""兼容原有进度显示导入方式。"""
+
+from tomarkdown.ui import progress
+
+__all__ = ["progress"]