前言¶
在 DeepSeek Harness（DSH）的 Web 对话里，若要把本地 PDF、代码或整棵文件夹交给 Agent，常见做法是手动复制路径或依赖零散的上传入口，输入框里也难以像成熟产品那样用「气泡」表达引用。WorkBuddy 一类客户端把拖拽、粘贴和 @ 检索连成一条链路：松手即在光标处出现可整体删除的引用块，发送后在对话区还能看到文件卡片。
dsh-workbuddy-files 是社区维护的 DSH 插件，目标是在浏览器侧尽量对齐上述体验：统一接管拖拽与粘贴，走 Host 落盘与 Client 气泡管线，并在 Host 注册 read_document 供 Agent 消费引用。下文介绍它的定位、能力、安装方式与使用时的注意点。
这是什么¶
- 仓库： miaoxintechnology/dsh-workbuddy-files
- 维护者： miaoxintechnology
- 分类： 客户端（Cordis Host + Client 双半侧；
package.json当前版本 0.2.4，许可证 MIT） - 目录页： SkillHub 插件条目
插件把「拖入 / 粘贴 → 全屏接收遮罩 → 输入框原生引用气泡（File Pill）→ 发送后对话区文件卡片」串成固定流程；引用附带落盘后的绝对路径（默认落在 ~/.dsh-drops/<批次>/<相对路径>），Agent 可通过 read_document 或其它读取工具处理。
README 还说明仓库存在两种形态：可安装的正式插件包，以及会话内动态 Cordis 演示版（pluginId 为 wbdrop-1），行为与正式包一致，便于不动安装包先体验拖拽与 @。
核心功能¶
以下能力均来自项目 README 的功能对照与架构说明。
拖拽、粘贴与文件夹¶
- 任意文件拖入输入区域： 在
window捕获阶段接管拖拽，显示全屏「松开以接收文件」遮罩（与 DSH 原生图片拖放遮罩互斥，避免两套遮罩叠加或页面卡住）。 - Ctrl+V 粘贴： 图片与文件类粘贴统一走气泡管线；拖入或粘贴时在确定路径后即可插入气泡，文件在后台异步写入缓存目录。
- 文件夹： 通过
webkitGetAsEntry递归遍历；顶层以一个文件夹气泡呈现，目录树按原结构落盘。
输入框与对话区¶
insertReference： 通过 DSH 输入状态机铸造原生 occurrence 气泡（文件名 + 类型图标），Backspace/Delete 一次删除整段，撤销/重做与官方@引用一致。@菜单： 工作区文件仍由 DSH 官方@源提供；插件追加「文件缓存」分组，可搜索并插入已拖入过的条目。- 轮次尾部卡片： 在
conversation.chat.turnTail槽按轮次渲染「消息引用的文件」卡片，点击经openFile打开。
Host 侧¶
- 私有 RPC /
webServer路由负责save、list、stat、home等，将二进制写入配置的 drops 目录。 read_document工具： 文本返回内容，目录返回树结构，图片/二进制/大文件返回元数据与建议。
设计取舍上，v1 曾尝试 Chromium FS Access API「零上传直引」；为保证拖入可用、发送不因落地失败而中断，当前统一为「拖入即缓存 + 真实绝对路径」。单文件上限在正式包中可通过配置调整（默认 256MB）。
安装与启用¶
前置条件： Node 18+、pnpm（dsh plugin 内部会转发给 pnpm）。安装或更新后需执行 dsh web 重启 Web 界面。
从 npm registry 安装（README 推荐在其他设备上使用）¶
npm i -g pnpm
# 若尚未安装 DSH：npm i -g @deepseek-ai/dsh
dsh plugin --profile web add dsh-workbuddy-files
dsh web
从 GitHub 安装（registry 不可达时）¶
仓库自带 lib/ 构建产物，README 写明无需本地构建即可安装：
dsh plugin --profile web add "github:miaoxintechnology/dsh-workbuddy-files"
dsh web
本地开发与 link¶
在插件源码目录执行 npm install、npm run bundle 后，可用符号链接安装以便改代码后重新 bundle 并重启 DSH：
dsh plugin --profile web add link:..\dsh-workbuddy-files
dsh web
也可使用 file:<绝对路径> 做拷贝安装。卸载命令：
dsh plugin --profile web remove dsh-workbuddy-files
更新到指定版本示例（README 给出 0.1.5 作为显式版本号写法）：
dsh plugin --profile web add dsh-workbuddy-files@0.1.5
dsh plugin add 会在 $DSH_HOME/profiles/web 中通过 pnpm 引入包，并因包声明了 dsh.bundle.patch 自动把该 bundle 加入 profile 的 dsh.profile.bundles 层栈，可在 ~/.dsh/profiles/web/package.json 中核对。
可选配置¶
Host 半侧配置写在 cordis.patch.yml 的 config 段；浏览器半侧当前走代码默认值：
config:
dropsDir: '~/.dsh-drops'
maxFileBytes: 268435456
可按需把 dropsDir 指到工作区内路径，以便在偏严的沙箱策略下仍能写入缓存。
典型用法（验收步骤摘要）¶
README 列出了可逐条复现的验收流程，下面摘录几条便于快速对照。
- 从资源管理器拖入
report.pdf→ 出现本插件全屏遮罩（非原生图片遮罩）→ 松手后输入框出现 PDF 气泡，同时~/.dsh-drops/drop-*下应有对应文件。 - 在句子中间停住光标再拖入文件 → 气泡插在光标处，而非总是追加到末尾。
- 复制
.py文件后在输入框 Ctrl+V → 出现代码类型气泡；截图粘贴同样走统一管线。 - 拖入含子目录的文件夹 → 单个文件夹气泡，落盘保留目录树。
- 输入
@→ 除官方工作区文件外，可见「文件缓存」分组；发送带引用的消息后，轮次尾部应出现文件卡片。
发送时 codec.serialize 为恒等设计，消息不应因文件尚未写完而发送失败；若极大文件刚拖入就立刻让 Agent 读取，Host 可能对未完成路径返回明确错误，稍候重试即可。
适用场景与注意¶
适合谁： 主要在 DSH Web 界面里对话、希望用拖拽/粘贴/@ 快速把本地文件和文件夹交给 Agent，并希望在对话区保留可点击文件卡片的开发者。
权限与安全： 正式插件包的 Host 半侧使用 node:fs 直写 drops 目录，README 写明其不经过沙箱化 shell/fs 约束插件自身 Node 代码——插件以当前 DSH 进程权限运行。安装前应阅读源码与 MIT 许可证，确认缓存目录（默认用户主目录下 .dsh-drops）是否符合本机数据策略。动态演示版在部分沙箱环境下可能需要与会话文件策略一致的写盘权限，或将 dropsDir 配置到 workspace 内。
生态说明： DSH 奉行「一切皆插件」； SkillHub 等为社区目录站点，与 DeepSeek / 幻方无官方从属关系。本条目 GitHub 星标数为 2（以目录页/仓库当时展示为准）。
结尾¶
dsh-workbuddy-files 把 WorkBuddy 风格的文件引用体验落到 DSH Web：拖入即路径、气泡即引用、发送即卡片，Host 侧再用 read_document 闭合 Agent 读取链路。若你正在补齐 Web 端的文件交互，可从 npm 或 GitHub 命令安装，按 README 验收清单走一遍即可确认行为是否与预期一致。
- 目录页： https://www.skillhub.cn/plugins/miaoxintechnology/dsh-workbuddy-files
- 源码与完整文档： https://github.com/miaoxintechnology/dsh-workbuddy-files
