前言¶
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 / 幻方无官方从属关系。
