前言¶
在 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
