dsh-tool-markitdown

DeepSeek Harness（DSH）插件：发送其他格式的文件时，优先转换为大语言模型最容易理解的 Markdown 再交给模型。

转换引擎：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 工具处理图片。
🗂️ 原文件永不丢失：磁盘上的原文件只读、绝不修改或删除；上传的临时副本转换完成后立即清理。

🧩 工作原理

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（只需一次）

pip install "markitdown[all]"

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

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

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

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

方式 B — 下载 Release ZIP

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

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

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

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

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

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

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

第 3 步：安装进 dsh web profile

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

# 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

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

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

🚀 使用说明

1. 上传文件（最常用）

点输入框左侧 📄 → 选择文件 → 转换后的 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：卸载？

dsh plugin --profile web remove dsh-tool-markitdown

然后重启 dsh web。

🤝 贡献

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

📄 License

MIT © dsh-tool-markitdown contributors

dsh-tool-markitdown

DeepSeek Harness（DSH）插件：发送其他格式的文件时，优先转换为大语言模型最容易理解的 Markdown 再交给模型。

转换引擎：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 工具处理图片。
🗂️ 原文件永不丢失：磁盘上的原文件只读、绝不修改或删除；上传的临时副本转换完成后立即清理。

🧩 工作原理

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（只需一次）

pip install "markitdown[all]"

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

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

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

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

方式 B — 下载 Release ZIP

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

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

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

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

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

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

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

第 3 步：安装进 dsh web profile

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

# 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

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

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

🚀 使用说明

1. 上传文件（最常用）

点输入框左侧 📄 → 选择文件 → 转换后的 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：转换需要联网吗？ 不需要。转换完全在本地执行（python -m markitdown）；只有转换 http(s) 链接时才需要下载远程文件。

Q：卸载？

dsh plugin --profile web remove dsh-tool-markitdown

然后重启 dsh web。

🤝 贡献

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

dsh-tool-markitdown

dsh-tool-markitdown

✨ 功能特性

🧩 工作原理

✅ 环境要求

📦 安装（下载方式）

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

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

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

第 3 步：安装进 dsh web profile

第 4 步：重启 dsh web

🚀 使用说明

1. 上传文件（最常用）

2. 拖拽工作区文件

3. 对话中让模型转换

4. 超长文档

⚙️ 配置

🗂 目录结构

❓ 常见问题

🤝 贡献

📄 License

Community comments

dsh-tool-markitdown

dsh-tool-markitdown

✨ 功能特性

🧩 工作原理

✅ 环境要求

📦 安装（下载方式）

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

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

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

第 3 步：安装进 dsh web profile

第 4 步：重启 dsh web

🚀 使用说明

1. 上传文件（最常用）

2. 拖拽工作区文件

3. 对话中让模型转换

4. 超长文档

⚙️ 配置

🗂 目录结构

❓ 常见问题

🤝 贡献

📄 License

Community comments