dsh-plugin-docstudio

为 DeepSeek Harness 提供的 DocumentStudio 工具插件：把 docstudio 这个「双向、以 Markdown 为中心的文档转换器」以模型可调用工具 的形式接入 Harness，让 Agent 在对话中直接完成文档格式转换。

A DeepSeek Harness plugin that wraps the docstudio CLI as five model-facing tools for bidirectional, Markdown-centric document conversion.

---

功能总览 / Features

插件注册 5 个工具，全部通过 shell 服务调用 docstudio CLI，并遵循会话沙箱策略：

工具	能力	说明
docstudio_convert	双向转换	X → Markdown 与 Markdown → X，核心工具
docstudio_formats	能力发现	列出支持的输入/输出格式与内置模板
docstudio_template	模板库	取回 6 个开箱即用的 Markdown 模板
docstudio_merge_pdfs	工具箱	合并多个 PDF 为一个
docstudio_extract_images	工具箱	抽取文档内嵌图片

1. docstudio_convert —— 双向转换

• 反向 X → Markdown（让文档可被模型阅读）： pdf · docx · pptx · xlsx · epub · html · csv · tsv · json · zip · image（图片 OCR 需 tesseract 或视觉模型）
• 正向 Markdown → X（生成交付物）： html · docx · latex · epub · xlsx · text · pdf （pdf 需要一个后端：pandoc + xelatex、weasyprint 或 playwright）
• 支持可选 toc：在转换前自动插入 Markdown 目录（基于 ##/### 标题）
• 非 Markdown 输入在正向导出时会先自动转为 Markdown，例如 scan.pdf → docx

2. docstudio_formats —— 能力发现

返回运行时实际支持的输入格式、输出格式和模板清单（JSON），供模型在调用前确认。

3. docstudio_template —— 模板库

内置 6 个中文模板：academic（学术论文）· techdoc（技术文档）· minutes（会议纪要）· readme（README）· weekly（周报）· blog（博客文章）。

4. docstudio_merge_pdfs / 5. docstudio_extract_images —— 工具箱

• 合并 PDF：按给定顺序拼接（需 pypdf）
• 抽取图片：从 PDF / DOCX / PPTX / XLSX / EPUB 中导出内嵌图片，返回文件路径列表

---

安装 / Install

1. 安装 Python 依赖（docstudio 本身）

本插件是 docstudio CLI 的薄封装，需要先安装 docstudio（要求 Python ≥ 3.9）：

pip install "docstudio[office,pdf]"     # 核心 + Office/PDF 支持
# 可选：
#   pip install "docstudio[ocr]"          # 图片/扫描 PDF OCR
#   pip install "docstudio[pdf-weasy]"    # Markdown→PDF 的 weasyprint 后端

若想用 Markdown → PDF 的最高保真度，建议再装 pandoc 与 TeX 引擎：

sudo apt install pandoc texlive-xetex

2. 安装本插件（npm）

npm install dsh-plugin-docstudio

3. 挂载到组合（composition）

在你的 cordis.yml（或 agent preset）中加一行：

plugins:
  - dsh-plugin-docstudio

如需指定非 PATH 上的 docstudio（例如虚拟环境里），可传配置：

plugins:
  - name: dsh-plugin-docstudio
    config:
      bin: /path/to/venv/bin/docstudio
      python: /path/to/venv/bin/python   # 仅用于元数据发现
      timeoutMs: 180000

也可用环境变量 DOCSTUDIO_BIN / DOCSTUDIO_PYTHON 覆盖。

---

使用示例 / Examples

以下为真实运行结果。

反向：Excel → Markdown

输入 revenue.xlsx：

季度营收：DocStudio 120/156/210/287，MarkItDown 90/95/101/118，Pandoc 60/72/88/95

调用 docstudio_convert(input="…/revenue.xlsx") 返回：

## 季度营收

| 产品 | Q1 | Q2 | Q3 | Q4 |
| --- | --- | --- | --- | --- |
| DocStudio | 120 | 156 | 210 | 287 |
| MarkItDown | 90 | 95 | 101 | 118 |
| Pandoc | 60 | 72 | 88 | 95 |

正向：Markdown → Word

调用 docstudio_convert(input="…/weekly.md", to="docx")，返回输出路径：

Converted …/weekly.md → …/weekly.docx (docx)

插入目录

调用 docstudio_convert(input="…/weekly.md", toc=true)：

# 项目周报

## 目录

- 本周完成
- 下周计划
- 数据表

## 本周完成
…

其它

docstudio_merge_pdfs(inputs=["a.pdf","b.pdf"], output="all.pdf")   # → all.pdf
docstudio_extract_images(input="report.pdf", output_dir="imgs/")   # → 图片路径列表
docstudio_template(name="academic")                                 # → 学术论文 Markdown

---

演示 / Demo

仓库 docs/demo.html 是一个自包含的演示页面，可视化展示 5 个工具与一次真实转换，可直接用浏览器打开并截图。

---

与 markitdown 的关系

markitdown 擅长 X → Markdown；DocumentStudio 复用了这个方向（存在时可委托），并补齐了缺失的一半—— 把 Markdown 转回高保真的 PDF / Word / LaTeX / EPUB / Excel，以及图片与扫描 PDF 的视觉识别路径。

---

许可证 / License

MIT © 与 docstudio 保持一致。