taxueseek/dsh-files

English | 简体中文

dsh-files

一个 DeepSeek Harness 插件，文件在会话里的三段生命周期各补一块官方空白：

• 进：回形针旁的文件夹按钮（+ 菜单里另有同名命令入口）——浏览器递归展平（过滤 Office 锁文件、.DS_Store、.env 等系统/隐藏文件），逐文件进入官方原生附件管线
• 读：read_document 工具——读内置 read 工具拒绝的二进制文档（PDF / DOC / DOCX / XLSX）与增强文本读取（编码回退、分页、sheet 级访问）
• 管：attachment_list / export_attachment 工具——附件库对模型可见（文件名/大小/sha），一键拷贝进工作区供 read/edit/bash 再加工
• 取：附件库面板（输入卡下方官方坞位，收起为一枚官方胶囊）+ 下载/导出路由 + @ 附件源——附件库对用户可见可下载（远程/LAN 把文件拉回本机），@ 菜单插入官方 handle 行（与上传时模型所见一致）

上传、图片、@ 工作区引用自 0.5.0 起移除——harness 0.1.3 起原生提供（任意文件上传、图片视觉管线、@file/@session 统一引用），且更强。本插件是踏雪寻仙插件矩阵的一员，主打 argo。

为什么需要它

harness 0.1.3 的原生上传把文件存为字节对象，模型拿到一行 handle（文件名、大小、摘要、只读路径）后用文件工具读取——而内置 read 对二进制内容直接报 FS_NOT_TEXT。PDF / DOC / DOCX / XLSX 的结构化文本提取、附件库的清单与导出（官方 GC 在 roadmap、模型侧完全不可见）都是官方留白，这个插件补上它们。

能力

• 内容嗅探：PDF 头 / OLE Compound File（Word 97-2003）/ ZIP 中央目录成员 / UTF-8（fatal）/ UTF-16 BOM / GB18030，全部从字节判定，扩展名伪装（exe 改 .pdf）一律拒绝；格式 hint 仅作字节完全未知时的兜底
• .doc 老格式：macOS 走系统 textutil（金标对照中正文与日期段最完整），其他平台回退纯 JS word-extractor
• 编码链：UTF-16 BOM → UTF-8（fatal，拒 NUL）→ GB18030（fatal）→ UTF-16 无 BOM（高置信度守卫），中文 GBK 与无 BOM UTF-16 均可读
• 分页读取：行号 + offset/limit 翻页；窗口字符预算按格式差异化（text 满额、xlsx 3/4、pdf/doc/docx 1/2），超限显式标记剩余行数
• 行号策略：text（代码/配置）带行号供精确定位；PDF/DOC/DOCX/XLSX 段落流不带行号（省 token）
• XLSX sheet 级读取：list_sheets 先列名，sheet 参数读全量单表（不受行截断限制），越界报错附带可用 sheet 列表

English | 简体中文

dsh-files

一个 DeepSeek Harness 插件，文件在会话里的三段生命周期各补一块官方空白：

• 进：回形针旁的文件夹按钮（+ 菜单里另有同名命令入口）——浏览器递归展平（过滤 Office 锁文件、.DS_Store、.env 等系统/隐藏文件），逐文件进入官方原生附件管线
• 读：read_document 工具——读内置 read 工具拒绝的二进制文档（PDF / DOC / DOCX / XLSX）与增强文本读取（编码回退、分页、sheet 级访问）
• 管：attachment_list / export_attachment 工具——附件库对模型可见（文件名/大小/sha），一键拷贝进工作区供 read/edit/bash 再加工
• 取：附件库面板（输入卡下方官方坞位，收起为一枚官方胶囊）+ 下载/导出路由 + @ 附件源——附件库对用户可见可下载（远程/LAN 把文件拉回本机），@ 菜单插入官方 handle 行（与上传时模型所见一致）

上传、图片、@ 工作区引用自 0.5.0 起移除——harness 0.1.3 起原生提供（任意文件上传、图片视觉管线、@file/@session 统一引用），且更强。本插件是踏雪寻仙插件矩阵的一员，主打 argo。

为什么需要它

harness 0.1.3 的原生上传把文件存为字节对象，模型拿到一行 handle（文件名、大小、摘要、只读路径）后用文件工具读取——而内置 read 对二进制内容直接报 FS_NOT_TEXT。PDF / DOC / DOCX / XLSX 的结构化文本提取、附件库的清单与导出（官方 GC 在 roadmap、模型侧完全不可见）都是官方留白，这个插件补上它们。

能力

• 内容嗅探：PDF 头 / OLE Compound File（Word 97-2003）/ ZIP 中央目录成员 / UTF-8（fatal）/ UTF-16 BOM / GB18030，全部从字节判定，扩展名伪装（exe 改 .pdf）一律拒绝；格式 hint 仅作字节完全未知时的兜底
• .doc 老格式：macOS 走系统 textutil（金标对照中正文与日期段最完整），其他平台回退纯 JS word-extractor
• 编码链：UTF-16 BOM → UTF-8（fatal，拒 NUL）→ GB18030（fatal）→ UTF-16 无 BOM（高置信度守卫），中文 GBK 与无 BOM UTF-16 均可读
• 分页读取：行号 + offset/limit 翻页；窗口字符预算按格式差异化（text 满额、xlsx 3/4、pdf/doc/docx 1/2），超限显式标记剩余行数
• 行号策略：text（代码/配置）带行号供精确定位；PDF/DOC/DOCX/XLSX 段落流不带行号（省 token）
• XLSX sheet 级读取：list_sheets 先列名，sheet 参数读全量单表（不受行截断限制），越界报错附带可用 sheet 列表

安装

要求 harness ≥ 0.1.3-alpha.1。

curl -fsSL https://raw.githubusercontent.com/taxueseek/dsh-files/main/install.sh | sh
# 重启 dsh web

手动等价命令：

dsh plugin --profile web add git+https://github.com/taxueseek/dsh-files.git
# 重启 dsh web

npm 上名为 dsh-files 的包是无关第三方占位包，请勿用裸 npm 包名安装。

版本支持

dsh-files	Harness	说明
0.5.3	0.1.7-alpha.1（已验证）	当前版。@deepseek-ai/dsh-fs/dsh-tools/dsh-client-ui-primitives 锁定 0.1.7-alpha.1；客户端图标跟随宿主 Regular/Medium 命名。
0.5.x	≥ 0.1.3-alpha.1	旧 SDK pin（0.1.0-rc.x）；附件面板与 @ 源早于宿主 conversation.composer.dock 槽位。
0.6.x	—	从未发布（已并入 0.5.2/0.5.3），请勿使用。

本插件跟随维护者本地运行的 alpha 线（0.1.7-alpha.1）；npm latest（撰写时为 0.1.5-rc.3）反而更旧，请用上面的 git 方式安装，勿用仓库版本。

配置

- id: files-toolkit
  name: 'dsh-files'
  config:
    maxFileBytes: 25165824        # 单次文档读取字节上限
    readLimit: 2000               # 单次返回行数上限（翻页成本低）
    sheetRowLimit: 200            # 每个 sheet 保留行数
    maxSheets: 5                  # 每个工作簿读取的 sheet 数
    maxOutputChars: 24000         # 单次输出窗口字符预算（超限截断并标记）
    readTimeoutMs: 120000         # 单次执行超时（大 PDF 解析可加大）
    # attachmentsDir: /path/to/attachments/v1  # 附件库根；留空按 DSH_HOME / ~/.dsh 自动探测
    attachmentsEnabled: true      # 附件闭环（面板/下载/导出/@ 源）总开关
    maxDownloadBytes: 209715200   # 单次附件下载/导出字节上限（超限 413）
    trustedHosts: []              # 非回环 host[:port] 授权；LAN/域名部署必配（语义同官方 --trusted-host）

安全

• 解析依赖均为只读维护中库：pdfjs-dist（Mozilla 官方）、mammoth、read-excel-file、word-extractor（.doc 兜底）
• ZIP 中央目录探测不展开任何成员，恶意归档安全拒绝
• 文件读取与导出落盘走 ctx.fs，继承会话沙箱，与内置 read 工具同权；附件库扫描由宿主进程只读执行，路径全部内部拼接
• 附件下载/导出除经官方 AttachmentStore.readFileStream（内容完整性校验、不暴露绝对路径），外再叠 Host 信任栅栏 + sha256: 引用白名单 + 尺寸上限；无任何删除路由（内容寻址对象可能被历史消息引用，删除留给官方未来 retention）
• 面板与 @ 源均为 UI 层数据：不注入 systemPrompt、不注册模型工具，零 token

开发

pnpm install
pnpm test
pnpm build
npx tsc --noEmit

许可

MIT