@filebox/cli

FileBox 命令行工具，用于管理工作区、驱动配置和文件传输任务。

安装

pnpm add -g @filebox/cli

使用

filebox --help
filebox init
filebox config --add
filebox list
filebox market search video
filebox market view netflix-player
filebox market install netflix-player
filebox market install ./my-plugin.fbpkg
filebox market install https://example.com/webdav.driver.js
filebox market uninstall netflix-player
filebox sync webdav /photos/ myaliyun /backup/
filebox sync webdav /photos/ myaliyun /backup/ --dry-run

常用命令：

• init：初始化当前工作区。
• config：管理驱动配置。
• auth：管理认证信息。
• list / tree / stat：查看文件。
• upload / download：上传和下载。
• copy / move / rename / remove / mkdir：文件操作。
• sync：两个驱动之间同步文件。
• webdav / ftp / http：启动本地服务。
• market：查询、安装、卸载和更新插件或驱动，支持包 ID、本地文件和 URL。

默认读取当前目录下的 data/filebox.json。 插件市场地址可写入 filebox.json 的 marketplace.registry，也可以用 --registry 临时指定。

Upload 命令

filebox upload mydrive /backup/ ./photos -j 3

目录按层处理：扫描当前目录、创建对应的远程目录、按 -j 并发上传本目录文件， 完成后再处理子目录；不会预先创建整棵目录树。默认保留空目录，--skip-dirs 可跳过。 已有远程目录直接复用；是否存在以公共文件接口的目录列表为准，不依赖驱动报错文案。 --depth 1 只上传根目录内的文件，不进入或创建下一层目录。

上传界面默认显示成功、失败、跳过、处理中及待处理数量，以及累计进度（含进行中）、 已完成文件的字节数、合计速度和耗时。文件数随按层扫描更新，未遍历完时标记为“已发现／扫描中”， 不把它当作整个任务的最终总数，也不会为了显示总数先遍历完整棵目录树。 按 d 展开任务信息和完整文件名，按 b 转到后台、按 q 停止；-v 仍是文件校验选项。 交互终端使用彩色分区：顶部汇总、两行式文件进度卡片、底部快捷键，任务间保留留白。 文件名与进度条分行，进度和速度保持固定列宽；小终端自动换行，重定向输出保持纯文本，并遵守 NO_COLOR。

速度按最近约 2 秒的驱动进度计算，不按单个数据块的回调间隔计算；无进展时降到零， 采样不足显示“采样中”，传输进度已满但任务尚未返回时显示“待确认”。 115 的回调统计推流进度，并不提供云端逐字节确认量；仅返回一次完成回调的秒传不计算网络速度。 “累计进度／已完成／平均处理”包括秒传等逻辑文件进度，不代表网卡实际流量。

目录查询仍经过 core 缓存。CLI 只保留当前父目录本轮遍历的列表快照，供连续的兄弟目录共用， 避免 core 缓存关闭、过期或大目录分页被淘汰时反复扫描；它不替换 core，也没有新增持久化缓存。

core 目录缓存默认关闭。在 data/filebox.json 的 drives 中，给对应挂载项添加 "ttl": 300000 可启用 5 分钟缓存；它与 userConfig 同级，单位为毫秒，省略或设为 0 关闭。 缓存保存在当前进程内，重启任务会重建；修改配置后，新启动或恢复的任务生效。 上传结束后刷新目标目录及其分页列表，保留父目录、兄弟目录和子目录的缓存，减少重复的路径查询。 其他客户端的修改可能在缓存过期后才可见；115 的统一请求限频仍然有效。

驱动通过 HTTP 状态码 429 明确返回限流时，当前任务共用等待时间，自动退避并最多重试 3 次，优先遵守 Retry-After。持续限流或目录创建失败会停止继续调度；正常上传没有额外固定间隔。

后台任务与恢复

filebox up mydrive /backup/ ./photos --background
filebox task ls
filebox task attach <任务ID>
filebox task stop <任务ID>
filebox task resume <任务ID>
filebox task resume <任务ID> --background

resume 支持恢复已取消、失败或进程意外退出的上传、下载任务，沿用原任务 ID、 工作目录和命令参数。默认进入进度界面，--background 只恢复后台执行。 运行中的任务不能重复启动；已成功完成的任务无需恢复。

新版 CLI 会在文件传输成功后立即保存完成记录。恢复时跳过已记录完成且本地文件未变化的文件， 失败和未完成的文件重新传输；单个文件从头开始，不承诺字节级断点续传。 恢复时重新扫描来源，新增、修改过的文件也会处理。已成功上传并由 --delete 删除的独立源文件可跳过。 已完成文件的 hook、下载链接生成和本地删除等后续动作不会在恢复时重放。

统计按本次执行重新计算，之前已完成的文件计入“跳过”。恢复不会额外查询云端来猜测完成情况， 仍遵守驱动的统一限频；修改 115 的限频参数不会使完成记录失效。 仅支持新版 CLI 创建的任务。task clear 会一并删除恢复记录，清理后不能继续恢复。

Sync 命令

在多个驱动之间同步文件，例如把 WebDAV 里的文件同步到天翼云盘。

基本用法

# 单向同步（源驱动 → 目标驱动）
filebox sync <sourceDrive> <sourcePath> <targetDrive> [targetPath]

# 示例：把 webdav 的 /photos/ 同步到 myaliyun 的 /backup/photos/
filebox sync webdav /photos/ myaliyun /backup/

# 同驱动不同路径
filebox sync mydrive /photos/ mydrive /backup/

# 仅预览，不实际执行
filebox sync webdav /photos/ myaliyun /backup/ --dry-run

源路径是目录时会保留目录名，例如 /photos/ + /backup/ 的实际目标为 /backup/photos/。如果目标已经写成 /backup/photos/，不会重复追加。

同步模式（--mode）

| 模式 | 说明 | |------|------| | one-way（默认） | 单向：源 → 目标，目标端多余的文件不动 | | mirror | 镜像：源 → 目标，目标端多余的文件会被删除 | | two-way | 双向：两端文件互相补齐，处理修改冲突 |

# 镜像模式（目标端多余文件会被删除）
filebox sync webdav /photos/ myaliyun /backup/ --mode=mirror --delete

# 双向同步
filebox sync webdav /photos/ myaliyun /backup/ --mode=two-way

比对策略（--compare）

| 策略 | 速度 | 准确性 | 说明 | |------|------|--------|------| | size（默认） | 快 | 中 | 先按相对路径/文件名匹配，再按字节大小比对 | | mtime | 快 | 低 | 先按相对路径/文件名匹配，再按修改时间比对 | | checksum | 慢 | 高 | 按哈希比对（sha1/md5/quickHash） |

# 用哈希精确比对
filebox sync webdav /photos/ myaliyun /backup/ --compare=checksum

冲突处理（--conflict，双向同步时）

| 策略 | 说明 | |------|------| | skip（默认） | 跳过冲突文件 | | source-wins | 源端覆盖目标端 | | target-wins | 保留目标端 | | newest | 保留修改时间较新的 |

迁移模式（--remove-source）

同步完成后删除源端文件，用于"搬家"场景：

# WebDAV → 天翼云盘，同步后删除 WebDAV 里的原文件
filebox sync webdav /photos/ myaliyun /backup/ --remove-source

文件类型过滤

只同步指定扩展名，或排除不需要的扩展名。扩展名不区分大小写，多个值用逗号分隔，也可以带点：

# 只同步 mp4 和 mkv
filebox sync webdav /Youth3_/ 115 /recordings/ --include-extensions mp4,mkv

# 排除临时文件和字幕文件
filebox sync webdav /Youth3_/ 115 /recordings/ --exclude-extensions tmp,srt

下载和上传并发

下载和上传可以分别限流。未单独指定时，两者都使用 -j 的值：

# 最多同时下载 2 个文件、上传 1 个文件
filebox sync webdav /Youth3_/ 115 /recordings/ \
  --download-concurrent 2 \
  --upload-concurrent 1

使用 aria2 下载

aria2 必须能把文件写入运行 FileBox 的本机临时目录。FileBox 会通过 RPC 等待下载完成并校验文件大小，然后才开始上传：

# 使用默认 RPC 地址 http://127.0.0.1:6800
filebox sync webdav /Youth3_/ 115 /recordings/ --use-aria2

# 使用自定义本机端口
filebox sync webdav /Youth3_/ 115 /recordings/ \
  --use-aria2 http://127.0.0.1:16800

RPC 密钥可以通过 --aria2-secret 或环境变量 ARIA2_RPC_SECRET 提供。

代理设置

可分别给源端和目标端指定不同的代理：

# WebDAV 下载走代理，A网盘上传不走代理
filebox sync webdav /photos/ myaliyun /backup/ \
  --source-proxy http://127.0.0.1:7890

# 两边都走同一个代理
filebox sync webdav /photos/ myaliyun /backup/ \
  --proxy http://127.0.0.1:7890

# 源端和目标端用不同代理
filebox sync webdav /photos/ myaliyun /backup/ \
  --source-proxy http://127.0.0.1:7890 \
  --target-proxy http://127.0.0.1:1080

代理优先级：--source-proxy / --target-proxy > --proxy > 不使用代理。

传输实现

sync 只负责扫描、比对和编排，文件传输统一复用 CLI/runtime 已有的 copy/move 传输层，不另外实现上传协议：

1. 同驱动：调用驱动原生 copy。
2. 同 provider：传输层支持时使用 share → save 服务端转存。
3. 跨驱动兜底：使用统一下载/上传 transport；本地文件元数据由 runtime 生成（包含 absolutePath），同步成功后才执行 --remove-source。

扫描、比对、每个文件开始、下载/上传进度、完成与失败都会实时输出。

其他选项

| 选项 | 说明 | |------|------| | -j, --concurrent <num> | 并发传输数量，默认 3 | | --depth <num> | 目录遍历深度，默认不限 | | --delete | 配合 --mode=mirror 删除目标端多余文件 |

License

MIT