dsh-webfile

English | 中文

S3, FDS & FTP file tools for DeepSeek Harness: 8 agent tools (list, stat, mkdir, delete, move, copy, download, upload) — approval-gated mutations, transfer jobs with progress & cancel.

让 Agent 在对话中直接浏览与操作 S3(含 MinIO 等兼容对象存储)、小米 FDS 与 FTP/FTPS 上的文件:

• 只读直通:webfile_list / webfile_stat 免审批;
• 变更逐次审批:其余 6 个工具每次调用都经用户确认,拒绝即零副作用;
• 传输走后台任务:下载/上传在 Jobs 面板流式展示进度,可随时取消;
• 凭据只存引用:密钥值永不进入配置或会话日志,轮换后下一次调用即生效。

安装

dsh plugin --profile <name> add dsh-webfile

插件声明了 dsh.bundle,安装后自动挂载进该 profile 的 layer 栈(无需手写任何挂载行)。升级:

dsh plugin --profile <name> update

配置

在 profile 的 cordis.patch.yml($DSH_HOME/profiles/<name>/cordis.patch.yml)中按 id 覆盖配置:

- id: dsh-webfile
  config:
    connections:
      prod-logs:
        protocol: s3
        endpoint: https://oss.example.com   # 省略走 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
        userRef: FTP_USER
        passwordRef: FTP_PASSWORD
        tls: explicit                       # none | explicit | implicit
      mi-fds:
        protocol: fds
        endpoint: https://cnbj2.fds.api.xiaomi.com   # 最小配置:endpoint + bucket + ak/sk
        bucket: mi-bucket
        accessKeyRef: FDS_ACCESS_KEY        # 必填:FDS 没有环境凭据链
        secretKeyRef: FDS_SECRET_KEY
        # region: cnbj2                     # 不想写完整 endpoint 时,可用 region 推导域名
        # https: false                      # 默认 true;明文 HTTP 时置 false
    maxTransferBytes: 2147483648            # 单文件传输上限,默认 2 GiB
    multipartThresholdBytes: 67108864       # S3/FDS 分片上传阈值,默认 64 MiB

连接字段

patch 语义要点

• 按 id 定位:不带 id 的 patch 行会被跳过并告警;
• 整体替换:config 浅覆盖整份替换,未写字段回落插件默认值;
• 不要重复挂载:不要在用户层再 insert 同名行,配置一律走 id 覆盖;
• 禁用:- id: dsh-webfile / disabled: true 可在该 profile 关闭插件;
• 热生效:web 等长生命周期表面监视该文件,保存即经 HMR 事务性重载,无需重启;解析失败响亮报错并保留上一份好的配置。

凭据

配置中只写凭据引用名(环境变量名,POSIX 标识符),密钥值放在 $DSH_HOME/.credentials.yaml:

OSS_ACCESS_KEY: AKIAxxxxxxxx
OSS_SECRET_KEY: xxxxxxxxxxxx
FDS_ACCESS_KEY: 你的 FDS Access Key   # dev.mi.com / 小米融合云控制台创建
FDS_SECRET_KEY: 你的 FDS Secret Key
FTP_USER: logbot
FTP_PASSWORD: xxxxxxxx

• 四层优先级:进程环境 > 凭据文件 > 项目 .env > 用户 .env;进程环境只读且遮蔽同名文件条目;
• 热发布:凭据文件被监视(100 ms 去抖),外部编辑后下一次工具调用即用新值,轮换零重启;
• 格式:严格 引用名: 字符串值 映射(不是 dotenv 语法);值必须非空;文件权限必须 0600;
• 密钥值永不进入配置面或会话日志。

工具一览

行为语义

• S3 没有真目录:目录 = key 前缀聚合;mkdir 写零字节 key/ 标记对象;stat 对无对象但有子项的前缀合成目录。
• FDS 与 S3 同模型:FDS 同样以 / 模拟目录;协议差异在 provider 内部消化(见下节 FDS 细节)。
• 列表分页:结果截断时返回 truncated: true 与 nextToken(S3 ContinuationToken / FDS marker 透传),把 nextToken 传回即可续页;FTP 无服务端续页,截断时改大 maxEntries 重试。
• 覆盖保护:overwrite 默认 false,目标已存在时报 WEBBUF_EXISTS 并提示显式开启。
• 递归保护:delete 对非空目录默认报 WEBBUF_DIR_NOT_EMPTY;recursive: true 删除整棵子树。
• 传输上限:maxTransferBytes(默认 2 GiB)操作前前置校验,超限报 WEBBUF_TOO_LARGE 且不产生任何远端副作用。
• S3/FDS 大上传:≥ multipartThresholdBytes(默认 64 MiB)自动走 multipart,进度单调上报。
• 取消:传输中在 Jobs 面板 kill → 中止、清理本地半成品、job 终态 killed。
• S3 目录 move/copy:逐对象 copy(+delete),大目录耗时且中断可能留下半成品——工具描述与审批文案中已明示。
• FDS 目录 move/copy:同样逐对象 copy+批量删除,原因见下节;单文件 move 走原生 rename,零拷贝开销。
• FTP 符号链接:list/stat 以 type=link 呈现;递归删除只删链接自身、绝不跟随;copy 遇链接整体拒绝。

FDS 实现细节

• 协议与签名:FDS 是自有 REST API,不是 S3 线上协议。请求带 Authorization: Galaxy-V2 {AK}:{Sig},Sig = Base64(Hmac-SHA1(SK, StringToSign)),签名字符串覆盖 Method / Content-MD5 / Content-Type / Date(必填,请保持系统时钟与 FDS 同步)与规范化后的 x-xiaomi-* 头和 subresource(acl/quota/uploads/partNumber/uploadId/storageAccessToken/metadata)。
• 端点:缺省 {region}.fds.api.xiaomi.com;可用 endpoint 覆盖(内网 xxx-fds.api.xiaomi.net);https: false 走明文。
• 原生能力:单文件 move 使用 renameTo(服务端重命名,无需 copy+delete);目录递归删除使用 deleteObjects 批量端点。
• 分片上传:片大小固定 16 MiB(FDS 要求单片 5–50 MiB、片号连续);取消时 best-effort 调 abort 避免残留分片计费。
• 平台限制:对象最大 100 GiB(cnbj2 等,cnbj0 已停用仅 2 GiB);Bucket 名 3–63 字节、域名规则;目录下文件多时 FDS 无 S3 式原子性保证,请知悉。

Web 传输卡片

在 Web GUI 中,每次 download / upload 会在对话流里生成一张传输卡片(webfile-transfer conversation node):方向、label、实时状态点(传输中带活动动画)、耗时、起止路径与终态结果。数据分两层:

• 持久层:host 半边在传输起止时向会话日志记录 webfile/transfer-start / webfile/transfer-end 事件对,卡片据此在消息流中定位,并在 job 被 registry 丢弃后仍可回放终态。
• 实时层:客户端渲染器从 jobsBySession 镜像读取该 job 的实时状态、时间戳与终态 detail,registry 丢弃后回落到持久事件数据。

卡片随 dsh.client 声明(package.json → dsh.client + exports["./client"])由浏览器端插件提供;pnpm build 产出 lib/client.js。它只在使用方 profile 组合了本包、且 Web 服务重启并刷新页面后生效(客户端插件表在启动时扫描);未组合进 Web 树时零影响——事件照常记录、模型侧 Jobs 面板不受影响。

安全说明

• 逐次授权:每个变更操作独立审批,无会话级豁免;allowed-once 是唯一放行态。
• 失败关闭:无审批通道(如纯 headless 未挂 answerer)或会话策略 approval/policy: never 时,变更工具一律拒绝,绝不默认放行。
• 会话日志:工具参数(连接 id、remotePath 等)会随调用进入会话日志——路径敏感时请留意;密钥值永不进入。
• S3 CopyObject 不可中止:服务端复制一旦发出无法取消,涉及大目录 move/copy 时请知悉。
• 下载落盘:一律经 ctx.fs 写入工作区,受 DSH 文件沙箱策略管控。

错误码

兼容性

• Node:^22.19.0 || >=24.0.0(与 DeepSeek Harness 对齐)。
• S3:任何实现 ListObjectsV2 / HeadObject / GetObject / PutObject / DeleteObject(s) / CopyObject / multipart 接口的对象存储(AWS、MinIO、各类 S3 兼容服务)。
• FDS:小米 Galaxy FDS 的 cnbj2 / awsbj0 / awsusor0 / awssgp0 / awsde0 / ksyru0-eco / awsind0-eco 区域(原生 REST + Galaxy-V2 签名,密钥在 dev.mi.com 创建)。
• FTP/FTPS:支持 MLSD 的服务器字段最全(修改时间精确);仅支持 LIST 的老服务器可用但时间字段缺失、目录类型靠权限推断;TLS 支持显式与隐式两种模式。
• 每操作短连接(v1 无连接池),超大规模高频场景见后续版本。

开发

仓库提交的 manifest 和 lockfile 统一使用 registry 包,确保本地开发与 CI 解析同一套依赖:

pnpm install
pnpm check   # build + lint + 测试

跨仓库联调时,使用 pnpm link <package-dir>... 在 node_modules 中替换指定包,不要修改 package.json 或 pnpm-lock.yaml。

提交规范:<type>(<scope>): <summary>。执行 pnpm exec lefthook install 后,lefthook commit-msg hook 会校验本地提交;CI 使用同一规则校验 PR 标题。

发布:完全自动化,由 semantic-release 驱动——每次合入 main 都会分析符合规范的提交历史,自动 bump 版本(fix → patch,feat → minor,如 0.1.1 → 0.2.0)、发布到 npm、推送版本 tag,并按提交自动生成 GitHub Release 的 release notes。源码中的 manifest 有意保持 0.0.0;Git tag 是版本记录。

首次发布需要在 GitHub Actions 的 NPM_TOKEN secret 中配置 granular automation token。包创建后,为 modestoma/dsh-webfile 和 ci.yml 配置 npm Trusted Publishing,再删除该 secret 以及工作流中的环境变量。后续发布使用短期 OIDC 凭据,并自动携带 npm provenance 证明。

License

[MIT](LICENSE) © 2026 modesto