feat: add agent-friendly ufile CLI

2026-09-21 00:45:35 -07:00
parent f0c29e4832
commit a58990ce66
17 changed files with 1684 additions and 3 deletions
@@ -10,7 +10,36 @@
 ./build.sh
 ```

-也可以运行 `make build`。构建脚本会先安装并编译前端，再通过 `go:embed` 将产物写入最终的 `ufile` 二进制；SQLite 使用纯 Go 驱动，不依赖 CGO。
+也可以运行 `make build`。构建脚本会先安装并编译前端，再通过 `go:embed` 将产物写入最终的 `ufile` 二进制，同时构建 `ufile-cli`；SQLite 使用纯 Go 驱动，不依赖 CGO。
+
+## ufile-cli
+
+`ufile-cli` 面向自动化和 Agent，成功结果统一输出 JSON，错误 JSON 输出到 stderr，并使用稳定退出码。常用选项提供短参数，危险或低频选项保留语义明确的长参数；服务地址支持 `-H`、`--host` 和 `--server`。
+
+```bash
+# 密码不会进入命令参数或配置文件
+printf '%s\n' "$UFILE_PASSWORD" | \
+  ./ufile-cli -H https://ufile.example.com auth login -U agent --password-stdin
+
+# 默认自动生成并回显 6 位取件码
+./ufile-cli upload ./result.zip -R 1d -D 5
+
+# 只有显式指定 --no-pickup-code 才创建公开分享
+./ufile-cli upload ./public.txt --no-pickup-code
+
+# 下载不会额外调用取件校验接口
+./ufile-cli download Ab3dE8xP -C 123456 -O ./result.zip
+```
+
+运行 `ufile-cli help` 查看输出契约、环境变量和退出码，运行 `ufile-cli help upload` 或 `ufile-cli help download` 查看权限要求及操作副作用。
+
+多平台构建：
+
+```bash
+make cli-dist
+```
+
+产物位于 `dist/`，覆盖 Linux、macOS 和 Windows 的 amd64/arm64，并附带 `checksums.txt`。推送 `v*` 标签会通过 Gitea Actions 创建 Release；需要预先配置具有仓库发布权限的 `RELEASE_TOKEN` secret。

 ## 运行