FileBrowser Skill

执行入口

uv run --project {SKILL_DIR}/scripts filebrowser --non-interactive <command>

配置查找顺序为：当前工作目录、skill 目录、当前 Git 项目根目录、~/.agents/agent_config.toml。也可以用全局 --config PATH 显式指定；显式路径不存在时直接停止。

FileBrowser 配置见 references/configuration.md。S3/CDN 配置与上传 语义见相邻 object-storage Skill。不要输出 FileBrowser token、S3 secret 或包含它们的异常详情。

upload、list、doctor 和 cdn 会查找独立 object-storage Skill。优先读取 OBJECT_STORAGE_SKILL_DIR，否则查找项目或用户 Skills 目录以及当前 Skills 仓库中的相邻目录。 未安装时停止并说明安装位置；纯 FileBrowser 的 get、put 和文件管理命令不依赖它。

服务端：FileBrowser Quantum

所有 source 指向的都是 FileBrowser Quantum（gtsteffaniak/filebrowser fork），不是上游 filebrowser/filebrowser。两者的 REST API 不兼容，查阅或调试接口时必须以 Quantum 为准（可从 服务端 GET /swagger/doc.json 取当前部署的 swagger 定义），不要套用上游 filebrowser 的 API 文档。已知差异：

• 移动/重命名/复制：PATCH /api/resources 要求 JSON body——items 数组逐项携带 fromSource/fromPath/toSource/toPath，顶层为 action（copy|move|rename）与 overwrite。 上游的 query-string 形式（from/destination）会被以 400 拒绝。
• 搜索：GET /api/tools/search，必须提供 sources（逗号分隔）或 scope（格式 sourceName:relativePath）。搜索基于服务端实时索引，新建文件可能尚未入索引；带 scope 时返回的 path 是相对 scope 的路径。
• 预览：GET /api/resources/preview，必须带 source 参数，否则 400；size 仅支持 small（默认）/large/xlarge/original。
• 目录列表：直接子项分列在响应的 folders 与 files 两个键中，某一类为空时该键整体缺席。
• 媒体元数据：GET /api/media/metadata（参数 source + path）返回与 /api/resources 相同的目录列表，但每个音视频文件额外带 metadata.duration（整数秒，来自服务端媒体索引）。 这是界面显示视频时长的数据来源，无需下载文件体。索引可能滞后于新上传/覆盖的文件； duration 只精确到整秒，需要亚秒精度仍须下载后用 ffprobe 实测。
• 打包下载：GET /api/resources/download 用重复 file 参数 + algo（zip|tar.gz）； 当前部署没有旧版的 /api/raw 端点。
• 资源元数据滞后：list-dir / info 返回的 size 来自服务端索引，文件被同名覆盖或 删除重传后可能长期不更新——无 reindex API、不会自愈（实测差值数千字节且数小时后 仍不恢复），modified 也可能停留在上一次写入。判断远端内容是否变化时禁止用列表 size 比对，必须以 get 实际下载的 Content-Length / 哈希为准；get/put 自身的 字节校验走真实响应，不受索引影响。

安全语义差异：Quantum 的 PATCH 处理器不校验 overwrite，目标冲突时可能自动加版本后缀 （如 name (1).mp4）而不是报错。本 skill 的 move 因此在客户端预检目标存在性：目标已存在 且未加 --overwrite 时直接拒绝。不要绕过 CLI 直接调 PATCH API 复制/移动，否则会绕过这层 幂等保护。

子命令总览

按职责分两组。所有命令都支持 --source <name> 切换 FileBrowser source，省略时用 [filebrowser] default_source。

文件管理（FileBrowser 自身操作）

传输分发（跨存储 / CDN）

文件管理示例

# 1) 读 SRT 内容（漫剧翻译场景）
filebrowser info --source 项目 --path /虎澈漫剧/C01字幕/英文/孤岛05.srt --content --json

# 2) 创建多语种字幕目录（已存在则直接返回原路径，不会重复创建）
filebrowser mkdir --source 项目 --path /虎澈漫剧/C01字幕/巴西葡萄牙语SRT/ --json

# 3) 写回翻译后的 SRT（注意 --override）
cat outputs/tmp/.../巴西葡萄牙语SRT/孤岛05.srt \
  | filebrowser update --source 项目 --path /虎澈漫剧/C01字幕/巴西葡萄牙语SRT/孤岛05.srt --override --json

# 4) 搜索远端文件
filebrowser search --source 项目 --query 孤岛 --scope /虎澈漫剧 --json

# 5) 打包下载一个项目的成片 + 字幕
filebrowser download-files --source 项目 \
  --files "项目::/虎澈漫剧/B06.../成片/EP01.mp4||项目::/虎澈漫剧/B06.../字幕/EP01.srt" \
  --algo zip --output /tmp/B06.zip --json

# 6) 重命名 / 复制（--action rename|copy）
filebrowser move --source 项目 --from /虎澈漫剧/B06/old.mp4 --destination /虎澈漫剧/B06/new.mp4 \
  --action rename --json

# 7) 不下载读某目录全部视频时长并求和
filebrowser duration --source 项目 --path /虎澈漫剧/B06/成片/480p/ --json

# 8) 只统计某前缀（如 99 开头）的视频时长；--pattern 为 fnmatch 通配符
filebrowser duration --source 项目 --path /虎澈游戏/A07末日公路/成片/480p/ --pattern '99*' --json

传输分发工作流

1. 首次操作或配置变化后运行：

   filebrowser --config /path/agent_config.toml doctor --json
   

2. 上传前先 dry-run，确认 source、target 和 object key：

   filebrowser upload "/项目/成片/demo.mp4" \
     --source production --target archive --dry-run --json
   

3. 用户确认目标后执行上传：

   filebrowser upload "/项目/成片/demo.mp4" \
     --source production --target archive --json
   

4. 要覆盖但只在内容变化时写入，使用 --overwrite --if-changed。相同文件会跳过上传， --json 输出中的 unchanged_files 会列出每个相同文件的源路径、对象 key、大小和 SHA-256：

   filebrowser upload "/项目/成片/demo.mp4" \
     --source production --target archive --overwrite --if-changed --json
   

5. 默认保留 FileBrowser 完整相对路径作为 S3 key，并由 object-storage 添加 target 的 prefix。需要改 key 时使用 --key。

上传本地文件回 FileBrowser

put 不依赖 S3 target，适合把 media-use 生成的成片传回主视频同目录。上传前先 dry-run 确认本地文件、source 和目标远端路径：

filebrowser put /local/output_480p_branded.mp4 \
  "/项目/成片/output_480p_branded.mp4" --source production --dry-run --json

确认后执行：

filebrowser put /local/output_480p_branded.mp4 \
  "/项目/成片/output_480p_branded.mp4" --source production --json

大文件按 upload_chunk_bytes 流式分块发送，上传后读取远端元数据并校验字节数。默认 拒绝覆盖，只有用户明确要求替换既有文件时才添加 --overwrite。

下载 FileBrowser 文件到本地

get 将单个远端文件流式下载至一个不存在的本地路径，完成后校验下载字节数。适合在 品牌视频处理前取回主视频、Logo 与片尾：

filebrowser get "/项目/成片/demo.mp4" /local/demo.mp4 \
  --source production --json

品牌视频回传流程

主视频、Logo、片尾先下载到本地临时目录；使用 media-use 的 ffmpeg_brand 输出成片， 再以 put 上传至主视频所在目录。filebrowser 只处理下载和回传，水印、片尾、分辨率 和帧率参数由 media-use 处理，避免两个 skill 的职责混杂。

安全规则

• 一次只上传一个文件；目录会被拒绝。
• S3 已存在同 key 对象时默认拒绝。只有用户明确要求覆盖时才添加 --overwrite。
• --if-changed 必须与 --overwrite 同时使用。上传对象带 SHA-256 元数据；启用后只有大小和 SHA-256 都一致才跳过，并在结果的 unchanged_files 明确列出相同文件。旧对象缺少该元数据时会 上传一次以补齐，不以 ETag 判断内容。跳过上传时不会执行 CDN 刷新。
• put 的远端路径必须是绝对路径且不能包含 ..；若目标已存在，默认拒绝覆盖。
• get 的本地目标路径必须不存在，避免无意覆盖已有文件。
• FileBrowser 路径必须是绝对路径且不能包含 ..；S3 key 必须是相对路径且不能包含 ..。
• mkdir 不会覆盖已存在的目录，已存在则返回原路径。
• update 默认 override=false，需要覆盖时显式加 --override。
• move 默认 overwrite=false，需要覆盖时显式加 --overwrite。
• 下载采用流式写入临时文件，不把大文件完整载入内存；优先使用下载响应的 Content-Length 校验字节数，缺失时才回退至资源元数据；无论成功或失败都会清理临时目录。
• max_transfer_bytes = 0 表示不设 skill 级大小上限；生产配置建议设置明确上限。
• dry-run 只验证配置和路径，不连接 FileBrowser 或 S3，也不解析凭据链；key 解析委托给 object-storage。

CDN 缓存管理

为 object-storage target 配置可选的 [object-storage.targets.<name>.cdn] 子表后，可通过 FileBrowser 兼容命令管理腾讯云 CDN 缓存：

filebrowser cdn purge-url --target archive --keys "path/file.mp4"
filebrowser cdn purge-path --target archive --paths "https://cdn.example.com/path/" --flush-type flush
filebrowser cdn prefetch --target archive --urls "https://cdn.example.com/path/file.mp4" --area mainland

设 purge_on_upload = true 时 upload 成功后自动刷新该文件 URL（失败不影响上传）。 凭据复用 target 的 AK/SK，但需在腾讯云 CAM 授予 cdn:PurgeUrlsCache/PurgePathCache/ PushUrlsCache 权限。cdn.base_url 是 CDN 域名，与源站域名 public_base_url 不同。详见 相邻 object-storage/references/configuration.md。

结果

转存 S3 成功时报告 source、FileBrowser 路径、target、bucket、object key、字节数、SHA-256 和可用的公开 URL。内容相同而跳过时，skipped_unchanged 为 true，且 unchanged_files 必须逐项列出相同文件；不要把该情况表述为已重新上传。S3 上传校验由 object-storage 完成。put 成功时报告 source、本地路径、FileBrowser 路径和字节数。