dsh-plugin-office-markdown
在 DeepSeek Harness 读取 Office / PDF 之前，先把它们转成 Markdown ——
进入模型上下文的是一个文件路径，而不是整份文件的原始内容。
中文 ｜ English
安装 ｜
使用 ｜
转换器 ｜
文档 ｜
更新日志
---
> 🤖 **本项目的代码与文档主要由 AI 生成** —— 由 DeepSeek Harness 里的编码 agent 撰写，经维护者审阅后发布。
> 配置项、HTTP 路由、转换器链与文件清单等内容都**逐项对照过源码**；但文档仍可能落后于实现，
> 或存在表述不准、细节缺失，**请以代码为准**。详见[文末说明](#关于本文档)。
转换在**本机**完成，不联网（可选的 MarkItDown 首次下载除外）、不修改原文件、
不消耗 API 额度，插件本身**没有任何 npm 依赖**。
## 安装
在 DSH 的 **设置 → 插件 → 安装** 里填一行，回车，然后**重启 DSH**。
**① 从 npm 安装（推荐）** —— npm 上从 1.2.2 起有正式发布：
```
dsh-plugin-office-markdown
```
要锁版本就在后面加 `@版本`：`dsh-plugin-office-markdown@<版本>`，`<版本>` 形如 `1.2.2`。
> ⚠️ **框里只填包名。** 下面那条 `dsh plugin …` 是终端命令，**整行粘进框里不认**。
**② 从 GitHub 安装** —— npm 不可达时用这条：
```
github:Z8906/dsh-plugin-office-markdown
```
要锁 tag 就在末尾加 `#`：`github:Z8906/dsh-plugin-office-markdown#`，
`` 形如 `v1.2.2`（见 [Releases](https://github.com/Z8906/dsh-plugin-office-markdown/releases)）。
**③ 离线 / 没有 git** —— 用 Releases 里的 `.tgz`，在安装框里填它的**绝对路径**；
也可以填本地克隆目录的路径（`file:` 前缀或绝对路径）。
习惯命令行的话，`dsh plugin` 会把参数转发给 profile 目录里的 pnpm —— `--profile` 按你用的是哪个版本填：
```sh
# Web 版 DSH
dsh plugin --profile web add dsh-plugin-office-markdown
# 桌面版 DSH（profile 名是 desktop）
dsh plugin --profile desktop add dsh-plugin-office-markdown
```
> ⚠️ **`--profile` 必须填你实际在用的那个。** 填错**不会报错** —— DSH 会按模板新建一个 profile，
> 插件装进那里，而你的界面读的是另一个，结果「装好了却看不到」。
全部安装方式、手工装法与升级步骤见 **[安装文档](docs/installation.md)**。
> **升级不要走「卸载 → 重新安装」。** 本插件在真正被卸载时会清理它自己登记过的 Python 包
> （见 [卸载文档](docs/uninstall.md)），那条路的结果是「插件更新了、Python 环境却没了」。
> 正确做法：`pnpm update dsh-plugin-office-markdown`，或在插件市场里点更新，
> 或直接在安装框里再 add 一次同一个地址。
## 怎么用
装好之后不需要记命令，直接说「读取并总结这个 xlsx」即可 —— 插件注册的技能会让模型先调用转换工具：
```
read_office_as_markdown({ path: "报表.xlsx" })
```
返回值里有转换后 `.md` 的路径、体积、行数，以及一份结构索引（章节 / 工作表 / 幻灯片的标题与大致行号），
并给出读取建议：先读前 200 行看结构，再用 grep 在同一个 `.md` 里定位。
**产物本身不会被裁剪** —— 交给模型的是一个完整的 Markdown 文件。
工具的其他用法：批量（`paths`，或把目录交给 `path`）、只要结构索引（`action: "outline"`，
不触发转换）、清理同一源文件的旧产物（`action: "clean"`，默认先干跑）、查看当前转换器
（`action: "status"`）。全部参数见 **[使用文档](docs/usage.md)**。
## 转换器
按顺序探测，第一个可用的胜出。下表对照 `lib/convert.js`：
| 顺序 | 转换器 | 保真度 | 需要 |
| --- | --- | --- | --- |
| 1 | `uvx markitdown`（临时运行） | 高 | `uv` + 网络（首次） |
| 2 | 本机 `markitdown` 命令 | 高 | 已安装 markitdown |
| 3 | `python -m markitdown` | 高 | Python + markitdown |
| 4 | 插件内置 Python 兜底（`lib/fallback.py`） | 有限 | 任意 Python 3，可选库能提升效果 |
| 5 | 插件内置 Node 兜底（`lib/fallback-node.js`） | 有限 | 无 |
**第 5 级不需要 Python、也不需要网络**：它用 Node 内置的 `zlib` 直接解析 OOXML
（`.docx` / `.xlsx` / `.pptx` 本身就是 zip + xml）。支持 `.docx` `.docm` `.xlsx` `.xlsm` `.pptx` `.pptm`；
`.pdf` 与旧版二进制格式（`.doc` `.xls` `.ppt`）需要 MarkItDown 或第 4 级。
每份产物的第一行记录它是谁转的；命中缓存时插件从这一行读回**真实的**转换器与保真度，
而不是无条件声称「高保真」：
```
```
想要高保真：打开 **设置 → Office 转换**，点「一键配置 MarkItDown 环境」。
**安装脚本不会替你装任何 Python 包**，装到哪个解释器由你在页面上选。
细节见 **[转换器文档](docs/converters.md)**。
## 设置页
**设置 → Office 转换** 提供：当前转换器、本机 Python 环境探测、一键配置 / 卸载 MarkItDown、
插件登记的环境记录、以及「试转一个文件」（不进模型、不走缓存，直接在本机跑一遍转换链看结果）。
页面上的按钮走插件自己的 HTTP 路由 `/office-markdown/api/*`，路由清单见 [使用文档](docs/usage.md)。
## 卸载
在 **设置 → 插件** 里点卸载即可。插件会先确认自己**真的被移除**（而不是被禁用 / 关闭 / 重启），
再派一个脱离宿主的看门狗进程，把它登记过的 Python 包 `pip uninstall` 掉。
**禁用、关闭、重启都不会触发清理，也不会留下任何常驻进程。**
清理范围严格限定在插件自己的环境记录里：DSH 运行时自带的包、被其它组件依赖的包、
以及你自己装的包，一个都不动。细节见 **[卸载文档](docs/uninstall.md)**。
## 依赖与兼容
- **Node ≥ 18**，只用内置模块（`fs` / `path` / `os` / `zlib` / `crypto` / `child_process` / `string_decoder`），
**0 个 npm 依赖**，不需要 `npm install`。
- **Python 与 MarkItDown 全部可选**：两者都没有时走第 5 级 Node 兜底。
- 除宿主提供的 `@deepseek-ai/dsh-tools`（用于 `defineTool`）外，不 import 任何宿主包。
- 只支持 DeepSeek Harness。profile 没有 `webServer` 服务时（例如 CLI profile），
设置页不会出现，工具与技能不受影响。
## 文档
| 文档 | 内容 |
| --- | --- |
| [安装](docs/installation.md) | 四种安装方式、手工安装、升级、验证 |
| [使用](docs/usage.md) | 工具参数、技能、`read` 守卫、设置页、HTTP 路由 |
| [转换器](docs/converters.md) | 转换器链、保真度、多个 Python 环境 |
| [配置](docs/configuration.md) | 配置项与默认值（对照 `lib/index.js` 的 `DEFAULTS`） |
| [产物与文件](docs/artifacts.md) | `.md` 放在哪、插件会留下哪些文件 |
| [卸载](docs/uninstall.md) | 启用 / 禁用 / 卸载与清理范围 |
| [故障排查](docs/troubleshooting.md) | 常见现象与处理 |
| [开发](docs/development.md) | 包内文件、本地开发、发布 |
| [更新日志](CHANGELOG.md) | 每个版本改了什么 |
## 关于本文档
本仓库的 README、`docs/`、`CHANGELOG.md` 以及各版本的 Release 说明，**主要由 AI 生成**
（DeepSeek Harness 里的编码 agent 撰写），由维护者审阅后发布。
其中配置项、HTTP 路由、转换器链、文件清单等内容都**逐项对照过源码**；但文档仍可能落后于实现，
或存在表述不准、细节缺失之处，**请以代码为准**。发现问题欢迎提 issue。
文档中**不写没有实测依据的数字**（例如「能省多少 token」「占用多少内存」）——
这类断言缺少可复现的测量过程，因此不列出。
## 许可证
[MIT](LICENSE) © 2026 dsh-plugin-office-markdown contributors