前言¶
在 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
