dsh-file-path

English

一个 DeepSeek Harness（dsh）插件：让 Web 输入框接受 dsh 内置附件不支持的文件和文件夹 ——PDF、压缩包、Office 文档、大文件、整个目录——把它们的绝对路径作为纯文本插入， 而不是作为消息附件上传。

这是一个社区插件，不是 DeepSeek 官方插件，与 DeepSeek 无关联、也未获得其背书。

为什么需要它

dsh 第一版附件只接受 PNG、JPEG、WebP、GIF。把 PDF 拖进输入框时，目前会提示 “仅支持图片”并丢弃文件。浏览器出于安全原因不会把拖入文件的真实磁盘路径暴露给网页 ——即使这个网页由本地 CLI 提供也不行。

dsh-file-path 利用 dsh 本身就是本地进程这一事实，把原始绝对路径反查回来：

1. 把非图片文件拖入或粘贴进输入框；
2. 浏览器端计算文件 SHA-256，调用本地 dsh 进程上的 filePathBridge/resolvePath RPC；
3. 宿主端在工作区与配置的搜索根目录（默认 ~）里查找 同名、同大小、同内容哈希的文件，返回它的原始绝对路径；不写任何东西；
4. 输入框直接插入该绝对路径。若在搜索范围内没找到（例如文件在别的盘上）， 对话框会请你手动填写绝对路径，并提供一个显式的“复制到工作区”备选按钮， 绝不会自动复制。

输入框工具行还有一个回形针按钮：打开对话框手动输入绝对路径或相对当前工作区的路径。

安装

打包并安装构建产物：

npm run build
npm pack
dsh plugin --profile web add ./dsh-file-path-0.1.x.tgz

或安装已发布的 npm 版本：

dsh plugin --profile web add dsh-file-path

或从 git 安装（prepare 脚本会现场构建；pnpm ≥10 首次会要求你允许执行构建脚本， dsh 会打印需要复制的 allowBuilds 片段）：

dsh plugin --profile web add github:<you>/dsh-file-path#<commit-sha>

然后照常启动：

dsh --profile web --port 3080

web profile 自带 Web 应用组合包。自定义 profile 需要保证 dsh.profile.bundles 中在 dsh-file-path 之前有 @deepseek-ai/dsh-web-app。

使用

• 拖入或粘贴非图片文件：插件按“文件名 + 大小 + 头尾各 64KB 的 SHA-256 指纹” 查找原始绝对路径，找到后直接插入，不复制文件。大文件从不整读，800MB 的压缩包 也只是毫秒级。
• 拖入文件夹（Chromium/Edge 的 File System Access）：插件递归枚举目录构建 目录指纹，匹配后直接插入文件夹绝对路径，不复制任何内容。
• 原始路径在搜索范围外时，对话框请你手动填写绝对路径；未解析的文件另有 “复制到工作区”按钮，但只在手动点击时执行，绝不自动复制。
• 点击输入框工具行的回形针按钮：手动输入路径并插入（绝对路径或相对工作区路径均可）。
• 受支持的图片（PNG/JPEG/WebP/GIF）保持 dsh 原有图片行为；混合拖入时，图片照常走 默认图片通道，只有非图片部分进入路径解析。
• 接管拖放后会向默认输入框补发 dragend，清除 dsh 的全屏拖放遮罩，不会卡在 “图片拖到此处可添加”界面。

配置

组合包补丁插入一行宿主插件。可在 profile 的 cordis.patch.yml 或任何更后的层覆盖：

- id: file-path
  config:
    importSubdir: .dsh-files          # 显式“复制到工作区”的落点
    maxFileBytes: 104857600           # 显式复制的单文件字节上限
    searchRoots:                      # 原始绝对路径的搜索根目录
      - '~'
      # - /mnt
    searchMaxEntries: 50000           # 单次查找最多访问的目录条目数
    searchSkipNames:                  # 跳过的基础目录名
      - .git
      - node_modules
      - .npm
      - .cache
      - .dsh
      - .Trash
    maxResolveBytes: 4294967296        # 参与哈希查找的单文件大小上限

• searchRoots 必须是绝对路径或 ~ 开头；会话工作区始终最先搜索，符号链接不跟随。
• importSubdir 必须是单个相对目录名（不能含 /、\、..）；非法值会在插件 加载时响亮失败。
• searchMaxEntries 和 maxResolveBytes 都是每次调用的上限，防止查找失控。

实现结构

• 宿主端（lib/index.js）：自包含的 Cordis 服务，注册为 ctx.filePathBridge。 它为 filePathBridge/resolvePath、filePathBridge/importFile 和 filePathBridge/describe 注册严格的 Typert Remote 描述符，线缆输入在两侧都经过 schema 校验。resolvePath 在搜索根目录中查找内容完全相同的文件并返回绝对路径； importFile 只是显式备选，解码 base64 后用临时文件加 rename 写入 importSubdir 之下。
• 浏览器端（lib/client.js）：一个 dsh.client 模块，挂载三个 Remote 方法、 注册双语词典，并向 conversation.input.right 槽位贡献一个按钮。捕获阶段的 document 监听器接管包含非图片文件的拖放与纯文件粘贴；纯图片批处理完全放行， 混合批处理中的图片会重新派发给默认输入框监听器，并补发 dragend 清除拖放遮罩。

安全说明

• resolvePath 只返回内容与浏览器所拖文件完全一致（哈希匹配）的路径；它从不写入， 也不会返回与拖入内容不匹配的路径。
• 显式“复制到工作区”只写入当前活跃会话自己的工作区，且限制在配置的单个 importSubdir 目录段内；文件名中的路径穿越字符会被剥离。
• dsh Web 传输的 loopback/浏览器信任防线同样作用于 /api/filePathBridge/*。
• 安装插件意味着允许其代码在本地 dsh 进程内执行。和安装任何插件一样，请审阅源码 并锁定版本。

开发

需要 Node >=22.19。

npm install
npm run check        # typecheck + 测试 + 构建
npm test             # 宿主服务与输入框控件测试
npm pack             # 构建后的 tarball

构建脚本（scripts/build.mjs）产出 ESM 宿主端和 window.__ModuleLoader__.load CJS 工厂形式的浏览器端；tsc 在 lib/types 下产出声明文件。

许可证

MIT