dsh-tool-markitdown

Readme

# dsh-tool-markitdown

> DeepSeek Harness（DSH）插件：发送其他格式的文件时，**优先转换为大语言模型最容易理解的 Markdown** 再交给模型。
>
> 转换引擎：[Microsoft MarkItDown](https://github.com/microsoft/markitdown) — 本地执行，文件不离开你的电脑。

| | |
| --- | --- |
| 适用平台 | dsh web（DeepSeek Harness Web GUI，Windows / macOS / Linux） |
| 转换格式 | PDF、Word、Excel、PPT、HTML、CSV、EPUB、ODT/ODS/ODP、RTF、JSON/XML、ipynb、图片 OCR 等 |
| 插件形态 | 宿主半区（Node）+ 浏览器半区（Web），纯 JavaScript，**无需构建** |
| License | MIT |

---

## ✨ 功能特性

- **📄 输入框一键转换**：点输入框工具行的 📄 按钮选文件，MarkItDown 立即转成 Markdown 并插入输入框草稿，发送给模型的就是 Markdown 正文（可先编辑再发送）。
- **🔄 发送时自动转换**：从右侧文件面板把文件拖进输入框后发送，插件自动识别"一整行就是一个文件路径"的草稿行（如 `docs/报告.pdf`），先转换再发送。
- **🤖 模型侧 `markitdown` 工具**：对话里提到本地路径、http(s) 链接或上传后的 `attachmentId`，模型会优先调用工具转换后再阅读。
- **✂️ 超长内容截断 + 全文可取回**：默认单次返回 120,000 字符，超出后截断并返回 `attachmentId`；模型可用该 id 取回完整内容（`/markitdown/raw/<id>`）。
- **⚙️ 可视化配置**：「设置 > 插件配置 > markitdown」可调 Python 命令、文件大小上限、输出字符上限、超时、发送时自动转换开关，改动即时生效。
- **🖼️ 图片不冲突**：图片保持原样，继续优先走视觉识别（如 `describe_image`）；需要 OCR 时可让模型用 `markitdown` 工具处理图片。
- **🗂️ 原文件永不丢失**：磁盘上的原文件只读、绝不修改或删除；上传的临时副本转换完成后立即清理。

## 🧩 工作原理

```mermaid
flowchart LR
    A[用户点 📄 按钮 / 拖入文件路径] --> B[浏览器半区 lib/client.js]
    B -->|POST /markitdown/attach 或 /convert-path| C[宿主半区 lib/routes.js]
    C --> D[MarkItDown 子进程 python -m markitdown]
    D --> E[Markdown 文本]
    E --> F[插入输入框草稿 / 替换发送内容]
    F --> G[大语言模型直接读懂 Markdown]
```

- **浏览器半区**（`lib/client.js`）：输入框 📄 按钮、发送时路径自动转换、草稿拼接。
- **宿主半区**（`lib/index.js` + `lib/routes.js` + `lib/convert.js`）：`markitdown` 工具注册、`/markitdown/*` 路由、MarkItDown 子进程封装、结果注册表（内存，最多 256 条，重启清空）。

## ✅ 环境要求

| 依赖 | 说明 |
| --- | --- |
| DeepSeek Harness | 已安装且 `dsh web` 可正常启动 |
| Python 3.9+ | 运行 MarkItDown；Windows 下也可用 `py -3` |
| markitdown | 见下方安装命令，安装一次即可 |

## 📦 安装（下载方式）

### 第 0 步：安装 MarkItDown（只需一次）

```bash
pip install "markitdown[all]"
```

> 验证：`python -m markitdown --version` 能输出版本号即可。可运行 `node scripts/smoke.mjs` 做一次端到端自检。

### 第 1 步：获取插件代码（任选一种）

**方式 A — GitHub 克隆（推荐，方便后续更新）**

```bash
git clone https://github.com/jiavenzhong/dsh-tool-markitdown.git
cd dsh-tool-markitdown
```

**方式 B — 下载 Release ZIP**

1. 到本仓库 **Releases** 页面下载最新版 zip；
2. 解压到任意目录（例如 `D:/plugins/dsh-tool-markitdown`）。

**方式 C — npm（发布后可用）**

```bash
dsh plugin --profile web add dsh-tool-markitdown
```

### 第 2 步：安装插件自身依赖

插件是独立目录，DSH 加载器会按插件真实路径解析依赖，因此需要在本目录安装运行时依赖（schemastery）：

```bash
cd dsh-tool-markitdown
pnpm install        # 或 npm install
```

> `node scripts/install.mjs` 会自动检测并完成这一步，无需手动执行。

### 第 3 步：安装进 dsh web profile

在插件目录里执行（方式 A / B 通用）：

```bash
# Windows PowerShell / CMD（在插件目录内）
node scripts/install.mjs

# 或者手动执行（Windows）
dsh plugin --profile web add link:D:/plugins/dsh-tool-markitdown

# 或者手动执行（macOS / Linux）
dsh plugin --profile web add link:$(pwd)
```

> `node scripts/install.mjs` 会自动处理 Windows 下常见的 pnpm store 目录不一致问题（`ERR_PNPM_UNEXPECTED_STORE`）。若 `dsh` 不在 PATH（例如从源码仓库运行 DSH），可设置 `DSH_BIN` 指向 dsh CLI，或手动执行：`cd <deepseek-harness仓库> && pnpm dsh plugin --profile web add link:<插件绝对路径>`。

### 第 4 步：重启 dsh web

```bash
dsh web
# 从源码仓库运行时：
# cd <deepseek-harness仓库> && pnpm dsh web
```

重启后输入框工具行会出现 **📄** 按钮；「设置 > 插件配置」出现 **markitdown** 配置项，即安装成功。

## 🚀 使用说明

### 1. 上传文件（最常用）

点输入框左侧 **📄** → 选择文件 → 转换后的 Markdown 自动插入草稿（带 `<!-- 📄 已由 MarkItDown 转换为 Markdown：文件名 -->` 注释头）→ 可编辑后发送。

### 2. 拖拽工作区文件

从右侧「文件」面板把文件拖进输入框（已有功能）→ 发送时插件自动把该路径行替换为转换后的 Markdown。

### 3. 对话中让模型转换

直接说：

```
把 docs/报告.docx 转成 markdown 分析一下
```

或把本地绝对路径 / http(s) 链接交给模型，模型会自动调用 `markitdown` 工具（工具描述要求"非文本文件先转换再阅读"）。

### 4. 超长文档

内容超过上限（默认 120,000 字符）时自动截断，并在结尾给出：

```
<!-- ⚠️ 内容过长已截断（共 N 字符）。如需完整内容，请使用 markitdown 工具并传入 attachmentId："sha256:…" -->
```

模型再次调用 `markitdown` 并传入该 `attachmentId` 即可读取全文。

## ⚙️ 配置

位置：**设置 > 插件配置 > markitdown**

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `pythonCommand` | `python` | MarkItDown 所在 Python 解释器；找不到时自动尝试 `py -3` |
| `pythonModule` | `markitdown` | MarkItDown CLI 模块名 |
| `maxInputBytes` | 52428800（50 MB） | 上传 / 下载文件字节上限 |
| `maxOutputChars` | 120000 | 单次返回 Markdown 字符上限（超出截断，可凭 `attachmentId` 取全文） |
| `timeoutMs` | 120000 | 单次转换超时（毫秒） |
| `autoConvertOnSend` | `true` | 发送时是否自动转换草稿中的文件路径行 |

## 🗂 目录结构

```
dsh-tool-markitdown/
├── lib/
│   ├── index.js       # 宿主入口：markitdown 工具 + 设置项
│   ├── convert.js     # MarkItDown 子进程封装、URL 下载、结果注册表
│   ├── routes.js      # /markitdown/attach · /convert-path · /raw/:id
│   └── client.js      # 浏览器半区：📄 按钮 + 发送时自动转换
├── scripts/
│   ├── install.mjs    # 一键安装到 web profile
│   └── smoke.mjs      # 转换引擎自检（无需 dsh）
├── cordis.patch.yml   # DSH bundle patch 清单
├── package.json
└── README.md
```

## ❓ 常见问题

**Q：图片会转成 Markdown 吗？**
默认不会。📄 按钮的 `accept` 和发送时自动转换都不包含图片格式，图片继续优先走视觉识别（如 `describe_image`）。需要图片 OCR 时，可让模型调用 `markitdown` 工具处理图片路径（MarkItDown 支持图片文字提取）。

**Q：原文件还在吗？会不会被改动？**
原文件永远保留。本地路径转换只读；上传转换使用临时副本，转换完成后立即删除。进入模型上下文的只有 Markdown 文本。

**Q：转换需要联网吗？**
不需要。转换完全在本地执行（`python -m markitdown`）；只有转换 http(s) 链接时才需要下载远程文件。

**Q：会额外消耗 API 额度吗？**
📄 按钮和发送时自动转换在本地完成，不调用任何大模型 API；只有模型主动调用 `markitdown` 工具时，转换结果才作为工具输出计入上下文。

**Q：报错 `MarkItDown 不可用`？**
先执行 `pip install "markitdown[all]"`，确认 `python -m markitdown --version` 可用；若 Python 不在 PATH，在插件配置里设置 `pythonCommand`（例如 `C:/Python312/python.exe`）。

**Q：Windows 下安装报 `ERR_PNPM_UNEXPECTED_STORE`？**
用 `node scripts/install.mjs` 安装（会自动带 `--store-dir` 重试）；或手动执行 `dsh plugin --profile web add --store-dir C:/Users/<你>/.pnpm/store link:<插件路径>`（以 pnpm 报错信息中的 store 路径为准，去掉末尾的 `v11`）。

**Q：启动报错 `Cannot find package 'schemastery'`？**
插件是 `link:` 方式安装、物理位置在 profile 之外时，必须让插件目录自带依赖。在插件目录执行 `pnpm install`（或 `npm install`）后重启即可；用 `node scripts/install.mjs` 安装会自动处理。

**Q：卸载？**
```bash
dsh plugin --profile web remove dsh-tool-markitdown
```
然后重启 `dsh web`。

## 🤝 贡献

欢迎 Issue 与 PR。本项目为纯 JavaScript，无构建步骤，直接修改 `lib/` 下的文件即可；提交前请运行 `node scripts/smoke.mjs` 确认转换链路正常。

## 📄 License

[MIT](LICENSE) © dsh-tool-markitdown contributors