前言¶

在 DeepSeek Harness（DSH）裏跑智能體，常見兩類文件相關需求：一是用戶在 Web 對話裏把本地文件交給模型；二是模型需要讀取 PDF、Office 文檔或工作區裏的文本，而不是隻靠擴展名猜格式。內置能力往往只覆蓋其中一環，上傳路徑、視覺圖片和文檔解析通常要分別對接。

下面介紹社區插件 dsh-files。它把上傳 UI、read_document 工具和原生圖片附件串成一行 cordis 配置，面向 dsh web 場景。

這是什麼¶

dsh-files 是 taxueseek 維護的 DeepSeek Harness 雙面插件（dual-face plugin）：前端注入 composer 上傳入口，後端註冊 read_document 工具。當前版本 v0.4.0，MIT 許可，GitHub 約 22 stars。

一句話定位：一個包同時提供會話隔離的文件上傳、彩色文件卡片，以及對 text / PDF / DOCX / XLSX 的內容嗅探讀取與 LRU 緩存；JPEG / PNG / WebP / GIF 則走 harness 核心附件管線，交給支持視覺的模型。

核心功能¶

上傳：三種入口與會話隔離存儲¶

1. 回形針按鈕：composer 工具欄多選文件。
2. 文件夾按鈕：遞歸展平目錄，保留子目錄相對路徑。
3. 拖拽：頁面任意位置拖入文件或文件夾，懸停有遮罩提示。

批量上傳默認 4 路併發，單文件失敗不阻塞其餘任務。文件寫入 <session-workdir>/.dsh-filess/<sessionId>/，agent 的 fs 後端可按路徑解析。

輸入 @ 時，候選列表同時包含本會話已上傳文件（絕對路徑）與會話工作區文件（相對路徑），無需重複上傳即可引用工作區已有文件。

彩色卡片按字節嗅探的真實格式着色（PDF 紅 / DOC 藍 / XLS 綠 / TXT 灰），擴展名僞裝不會誤導展示。上傳響應攜帶 readHint（cost / estimatedChars），便於讀前評估成本。

生命週期方面：默認 TTL 7 天清掃空會話目錄；可選 maxUploadBytesPerSession 配額；sha256 內容去重，同名不同內容只存一份。

原生圖片：走 harness 附件管線¶

柵格圖片不再落成本地路徑讓 read_document 處理，而是經 createDraftImages → addImages → serializeDraftImages，在請求時轉爲 base64 image_url。凡聲明 inputModalities: [text, image] 的模型（DeepSeek 視覺版、Dots3、龍貓、OpenRouter 視覺模型等）均可接收。UI 由官方 conversation.input.attachments rail 渲染縮略圖與預覽。

文檔讀取：read_document 工具¶

支持 text、PDF、DOCX、XLSX。格式判定來自內容嗅探，不信任擴展名；編碼鏈覆蓋 UTF-16 BOM、UTF-8、GB18030、無 BOM UTF-16。

長文檔通過 offset / limit 分頁，字符預算按格式分級（text 滿額，xlsx 3/4，pdf/docx 1/2，見 maxOutputChars）。XLSX 支持 sheet 參數按表讀取，list_sheets 僅列 sheet 名。無文本層的 PDF（掃描件）返回明確提示，而非空串。

解析使用 LRU 緩存（條目數 + 字節雙預算），鍵含內容 sha256，內容變化即失效。讀取走 ctx.fs，繼承會話沙箱；解析依賴 pdfjs-dist、mammoth、read-excel-file，ZIP 探測不展開成員。

安全護欄¶

上傳側做 loopback host + same-origin + sec-fetch-site 三重校驗；公網或反向隧道部署可通過 trustedHosts 放行（語義與 dsh web --trusted-host 一致）。文件名消毒、未知會話 403、併發超限 429、超大請求體提前拒絕。

安裝與啓用¶

在已安裝 DSH 的環境中執行：

dsh plugin --profile web add dsh-files
# 重啓 dsh web

安裝後需在 cordis 配置中保留插件條目（默認 id 爲 upload-toolkit）。通過公網域名訪問時，若上傳無響應，檢查是否需在 trustedHosts 中加入部署域名。

常用配置示例：

- id: upload-toolkit
  name: 'dsh-files'
  config:
    maxFileBytes: 25165824        # 單次文檔讀取字節上限
    readLimit: 800                # 單次返回行數上限
    sheetRowLimit: 200            # 每個 sheet 保留行數
    maxSheets: 5                  # 每個工作簿讀取的 sheet 數
    cacheEntries: 16              # 解析緩存條目數
    cacheMaxBytes: 67108864       # 解析緩存字節預算
    maxOutputChars: 24000         # 單次輸出窗口字符預算
    readTimeoutMs: 120000         # read_document 單次執行超時
    uploadMaxBytes: 25165824      # 單次上傳字節上限
    allowedExtensions: []         # 上傳擴展名白名單（空 = 全部允許）
    uploadTtlMs: 604800000        # 上傳文件保留時長（7 天）
    maxConcurrentUploads: 4       # 併發上傳數
    maxUploadBytesPerSession: 0   # 每會話存儲配額（0 = 不限）
    trustedHosts: []              # 額外信任的上傳 Host

典型用法¶

上傳並對話：在 Web UI 用回形針、文件夾按鈕或拖拽添加文件，彩色卡片掛載後路徑自動注入輸入框，隨消息發送。圖片以原生附件形式呈現，文檔由模型通過 read_document 按需分頁讀取。

引用工作區文件：輸入 @，從雙源候選中選擇會話上傳文件或工作區相對路徑，無需重新上傳。

讀 Excel：先用 list_sheets 探結構，再用 sheet 參數讀取指定工作表；合併讀取默認覆蓋前 5 個 sheet。

公網部署：若回形針點擊無反應，在 trustedHosts 加入實際訪問域名（如 dsh.example.com），與 dsh web --trusted-host 配合使用。

適用場景與注意¶

適合在 dsh web 下需要「用戶上傳 + 模型讀文檔 + 視覺圖片」一體化能力的智能體場景，例如審閱 PDF/Word/Excel、對照本地代碼或配置、向視覺模型提交截圖。

幾點注意：

• 插件以當前 dsh 進程權限運行，安裝前建議閱讀源碼與 MIT 許可證，確認上傳目錄與沙箱策略符合你的部署環境。
• 上傳默認不做擴展名白名單，allowedExtensions 爲空表示全部允許，安全邊界依賴會話沙箱。
• 大 PDF 解析可能耗時，可通過 readTimeoutMs 調大；掃描件無文本層時需 OCR 或其他方案，插件只返回明示提示。
• SkillHub 爲獨立社區目錄，與 DeepSeek / 幻方無官方從屬關係；插件分類爲「模型推理」，屬社區維護生態。

結尾¶

dsh-files 把上傳、文檔讀取和原生圖片三條鏈路收進一個 DSH 插件，減少自行拼裝 UI 與解析器的成本。目錄頁與源碼：

• SkillHub：https://www.skillhub.cn/plugins/taxueseek/dsh-files
• GitHub：https://github.com/taxueseek/dsh-files