前言¶
在 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 核心附件管线，交给支持视觉的模型。
核心功能¶
上传：三种入口与会话隔离存储¶
- 回形针按钮：composer 工具栏多选文件。
- 文件夹按钮：递归展平目录，保留子目录相对路径。
- 拖拽：页面任意位置拖入文件或文件夹，悬停有遮罩提示。
批量上传默认 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
