前言¶
DeepSeek Harness（DSH）的理念是「一切皆插件」。一旦想讓智能體幫你搬運日誌、同步文件，就繞不開遠端存儲：S3、小米 Galaxy FDS，或者還在跑的 FTP 服務器。常見的做法是把密鑰直接寫進配置，再讓模型在 shell 裏調命令行工具——密鑰會進入配置與會話日誌，刪除、覆蓋這類操作也沒有攔截。dsh-webfile 針對這個問題：把三類存儲封裝成 8 個 agent 工具，讀操作免審批，變更操作逐次請求批准，大文件傳輸走後臺任務、可隨時取消。下面介紹這個插件。
這是什麼¶
dsh-webfile 是 DeepSeek Harness 的文件類插件，維護者是 modestoma，以 MIT 許可發佈，當前 package 版本爲 0.0.0，Node 引擎要求 ^22.19.0 || >=24.0.0。
它支持三類存儲：S3（含 MinIO 及兼容對象存儲）、小米 Galaxy FDS、FTP/FTPS，提供 8 個工具：webfile_list、webfile_stat、webfile_mkdir、webfile_delete、webfile_move、webfile_copy、webfile_download、webfile_upload。智能體可以在會話裏直接瀏覽和管理這些存儲上的文件，而不需要你把憑證攤開在明面上。
核心功能¶
8 個工具：讀免審批，變更逐次批准¶
8 個工具裏，webfile_list 和 webfile_stat 是純只讀，調用不需要審批；其餘 6 個（含 webfile_download / webfile_upload）屬於變更類，每次調用前都要用戶批准，拒絕即零副作用。
webfile_list 的 maxEntries 默認 200、上限 1000；結果被截斷時返回 truncated: true 與 nextToken，把它傳回去即可繼續翻頁。nextToken 是 S3 ContinuationToken / FDS marker 的透傳；FTP 沒有服務端續頁，遇到截斷需要用更大的 maxEntries 重試。
變更類工具有兩道默認保護：
1、webfile_move / webfile_copy / webfile_upload 的 overwrite 默認 false，目標已存在時報 WEBBUF_EXISTS；
2、webfile_delete 遇到非空目錄報 WEBBUF_DIR_NOT_EMPTY，只有顯式傳 recursive: true 纔會刪除整棵子樹。
傳輸以後臺任務運行，可隨時取消¶
webfile_download / webfile_upload 以後臺任務運行，進度流入 Jobs 面板，可隨時取消。取消時會中止流、刪除本地半成品文件，並把任務標記爲 killed。
傳輸前有上限檢查：maxTransferBytes 默認 2 GiB，超限報 WEBBUF_TOO_LARGE，且零遠程副作用。S3/FDS 的大文件上傳達到 multipartThresholdBytes（默認 64 MiB）時改用 multipart 上傳。
憑證按引用名配置，密鑰不進會話¶
配置裏只寫憑證引用名（即環境變量名），密鑰值不進入配置與會話日誌；輪換密鑰後，下次調用即生效。優先級從高到低共四層：進程環境 > 憑證文件 > 項目 .env > 用戶 .env。
憑證文件是 $DSH_HOME/.credentials.yaml，帶 100ms 防抖熱發佈，外部編輯後同樣在下次調用生效。
目錄是合成的：S3/FDS 沒有真實目錄¶
S3 和 FDS 都沒有真實目錄，目錄只是 key 前綴的聚合：webfile_mkdir 實際寫入一個零字節的 key/ 標記對象；webfile_stat 對有子對象的前綴會合成目錄結果。理解這一點，做目錄相關操作時纔不容易誤判。
安裝與啓用¶
1、安裝插件：
dsh plugin --profile <name> add dsh-webfile
包聲明瞭 dsh.bundle，安裝時會自動掛載到 profile 層棧，無需手動添加掛載行。
2、後續升級：
dsh plugin --profile <name> update
典型配置¶
經過上面的步驟，插件已掛載到 profile 層棧，接下來配置連接。
按 id 覆蓋插件配置¶
先在 profile 的 $DSH_HOME/profiles/<name>/cordis.patch.yml 裏定位到 id: dsh-webfile，再寫 config 覆蓋。下面是一個同時定義 S3、FTP、FDS 三類連接的示例：
- id: dsh-webfile
config:
connections:
prod-logs:
protocol: s3
endpoint: https://oss.example.com # 自建端點（MinIO 等）；AWS 公有云可省略
region: cn-north-1
bucket: prod-logs
pathStyle: true # MinIO 需要 true
accessKeyRef: OSS_ACCESS_KEY
secretKeyRef: OSS_SECRET_KEY
legacy-ftp:
protocol: ftp
host: ftp.example.com
port: 21 # 默認 21；implicit FTPS 用 990
userRef: FTP_USER
passwordRef: FTP_PASSWORD
tls: explicit # none | explicit | implicit，必填
mi-fds:
protocol: fds
endpoint: https://cnbj2.fds.api.xiaomi.com
bucket: mi-bucket
accessKeyRef: FDS_ACCESS_KEY # FDS 沒有環境憑證鏈，ak/sk 必填
secretKeyRef: FDS_SECRET_KEY
maxTransferBytes: 2147483648 # 單文件傳輸上限，默認 2 GiB
multipartThresholdBytes: 67108864 # S3/FDS multipart 閾值，默認 64 MiB
兩個協議差異要注意：FDS 沒有環境憑證鏈，accessKeyRef / secretKeyRef 爲必填；FTP 僅支持被動模式（passive 默認 true），tls 必填。
憑證文件¶
連接裏的 accessKeyRef 等只是引用名，密鑰值寫在 $DSH_HOME/.credentials.yaml。格式是嚴格的 reference: string value 映射（不是 dotenv 語法），值必須非空，文件權限須爲 0600：
OSS_ACCESS_KEY: AKIAxxxxxxxx
OSS_SECRET_KEY: xxxxxxxxxxxx
FDS_ACCESS_KEY: your FDS access key
FDS_SECRET_KEY: your FDS secret key
FTP_USER: logbot
FTP_PASSWORD: xxxxxxxx
補丁語義與熱重載¶
按 id 覆蓋配置時，有三條語義要先知道：
1、沒有 id 的補丁行會被跳過並告警；
2、config 是淺替換整個值，省略的字段回退到 schema 默認；
3、不要在用戶層 insert 同名行重新掛載，統一通過 id 覆蓋。
要臨時停用插件，把對應補丁行設爲 disabled: true 即可：
- id: dsh-webfile
disabled: true
配置支持熱重載：保存 cordis.patch.yml 後，補丁經 HMR 事務性回放，無需重啓。
適用場景與注意¶
適合的場景：需要讓 DSH 智能體在會話裏瀏覽、搬運 S3 / FDS / FTP 文件，同時在意密鑰暴露和誤操作——讀免審批、變更逐次批准、傳輸可取消，這套門控正是爲此設計的。
使用前注意：
1、插件以當前 dsh 進程的權限運行，安裝前請先檢查源碼與許可證（本項目爲 MIT）；
2、憑證文件權限務必設爲 0600；
3、webfile_list 單次最多返回 1000 條，FTP 遇到截斷要用更大的 maxEntries 重試；
4、變更類操作的默認值偏保守（overwrite: false、recursive: false），需要覆蓋或遞歸時必須顯式傳參。
結尾¶
dsh-webfile 做的事情不復雜：把 S3、FDS、FTP 包成 8 個工具，用審批門控和憑證引用壓住風險，再用後臺任務讓大文件傳輸可控、可停。如果你的 DSH 工作流裏有遠端文件操作，值得一試。
- 插件目錄頁：https://www.skillhub.cn/plugins/modestoma/dsh-webfile
- GitHub 倉庫：https://github.com/modestoma/dsh-webfile
需要說明：目錄頁來自社區插件目錄，該站點獨立運營，與 DeepSeek / 幻方無官方從屬關係。
