前言¶
在 DSH（DeepSeek Harness）里和智能体协作时，经常需要把本地文件交给模型：PDF 报告、表格、截图、代码目录。常见做法是手动复制粘贴内容，或依赖外部脚本先把文档转成文本。前者对大文件和格式复杂的文档不现实，后者又要单独维护转换链路。
dsh-file-upload 是 HongMing-Huang 维护的 DSH 文件消息插件，在 Web 界面提供类似 Claude / Codex 的上传体验，并把文档按需转为 Markdown 供智能体读取。下面介绍它的定位、能力与安装用法。
这是什么¶
dsh-file-upload 是 DeepSeek Harness 的 file-message 插件，面向 Web 端工作流。维护者 HongMing-Huang，当前 npm 版本 0.5.2，MIT 许可证，GitHub 仓库约 14 stars。
插件解决的核心问题：把「拖文件进对话」和「智能体读文档」串成一条零配置链路——上传后消息里出现 @relative/path 引用（类似 OpenAI Codex），智能体通过 read_document 工具按需读取，文档在读取时转为 Markdown，而不是把整份文件原文塞进输入框。
上传与附件展示¶
插件在 composer 工具栏增加回形针按钮，并支持全局拖放 overlay（松手即附加）、粘贴附加、多文件上传。
上传后，小文本文件（默认 8 KB 以内）会直接 inline 进 composer；较大的文档以附件卡片展示，卡片带类型色标（PDF 红、DOC 蓝、XLS 绿、TXT 灰、ZIP 紫、JSON 金），显示文件名与大小，可单独移除。
在 composer 里输入 @ 可弹出已上传文件列表，按相对路径选择后插入 mention，与 Codex 的 @ 引用习惯一致。
文档转 Markdown（内置 MarkItDown）¶
文档读取不依赖用户本机安装 Python 或额外下载。插件内置 Microsoft MarkItDown 的 TypeScript 移植（markitdown-node），覆盖 20+ 格式：PDF、DOCX、PPTX、XLSX、HTML、CSV、JSON、XML、RSS、Atom、ZIP、Jupyter notebook；图片默认走 OCR（Tesseract，110+ 语言）；音频转写需模型凭据。解析在本地完成，无网络调用。
若本机已有官方 MarkItDown CLI，或通过配置指定路径，插件会优先使用 CLI（可额外支持 EPUB 等）；未配置时始终回退到内置引擎。启动日志示例：
[dsh-file-upload] Document → Markdown ready: bundled MarkItDown engine (20+ formats, image OCR) — fully packaged, no downloads, no Python.
可选配置项 markitdownBin 指向 CLI 路径；留空则仅用内置引擎。
图片处理¶
上传时插件会检测当前会话的模型能力，分三条路径：
- 多模态模型（声明
image输入，如 GPT-4o、Qwen-VL、Claude、Gemini）：走官方read_image工具，图片直接进入模型上下文。 - 已安装 vision bridge（如
dsh-vision-proxy，自动检测其路由的 image 输入声明）：同上。 - 纯文本模型（DeepSeek 官方 API 为 text-only）：插件通过 vision discovery chain 自动生成图片描述（「讲解图片」），随消息插入，让文本模型能基于描述推理。
Vision discovery chain 默认顺序：显式配置的 visionEndpoint / visionModel → 本机 Ollama（http://localhost:11434，自动选用 VL 模型如 DeepSeek-VL2，图片不出本机）→ 使用 dsh credentials seam 中 OpenAI 兼容端点的 key。
read_document 工具¶
智能体通过 read_document <path> 读取上传文件。转换后的 Markdown 支持分页（offset / limit，单次最多 2000 行），带行号；有按字节预算的 LRU 解析缓存（文件变更时失效），读取走 ctx.fs，继承沙箱与 fs-observation 策略。
典型用法：
- 点击 composer 回形针，或将文件拖入窗口任意位置；
- 小文本直接出现在输入框，文档显示为附件卡片，消息携带路径引用；
- 智能体执行
read_document <path>，按需分页读取 Markdown 内容。
安全与存储¶
上传路由仅 loopback；文件名经 sanitize；文件存放在会话隔离目录 .dsh-uploads/<sessionId>；内容按 sha256 去重；并发上传有上限（默认 4）；未引用上传默认 7 天 TTL，可按配置定期 sweep。
安装与启用¶
在 DSH Web profile 下安装：
dsh plugin --profile web add dsh-file-upload
# restart dsh web
安装后重启 dsh web 进程即可。插件声明零配置默认可用，无需单独装 Python 或挑选后端。
配置项（可选）¶
默认值已覆盖常见场景，仅在需要时调整。主要字段如下：
| 字段 | 默认值 | 说明 |
|---|---|---|
uploadMaxBytes |
25165824（24 MB） | 单文件上传上限 |
inlineTextLimit |
8192（8 KB） | 直接 inline 进 composer 的文本上限 |
readLimit |
2000 | 单次 read_document 最大行数 |
uploadTtlMs |
604800000（7 天） | 未引用上传存活时间 |
markitdownBin |
'' |
可选 MarkItDown CLI 路径 |
visionEndpoint |
'' |
图片描述用 vision 端点；空则自动发现 |
visionModel |
'' |
Vision 模型 id；空则自动 |
完整配置表见 GitHub README。
适用场景与注意¶
适合在 DSH Web 工作流中需要频繁把本地文档、表格、截图交给智能体分析的场景：代码审查附带 PDF、数据分析附带 XLSX、纯文本模型下仍需理解截图内容等。
使用前注意：插件以当前 dsh 进程权限运行，安装前应阅读源码与 MIT 许可证，确认上传与文件读取范围符合你的安全要求。Node 引擎要求 >=22.6.0。
SkillHub 社区目录（独立站点，与 DeepSeek / 幻方无从属关系）收录了该插件，分类为工作流。仓库与文档：
- 目录页：https://www.skillhub.cn/plugins/HongMing-Huang/dsh-file-upload
- GitHub：https://github.com/HongMing-Huang/dsh-file-upload
