mirror of
https://github.com/krau/SaveAny-Bot.git
synced 2026-07-18 03:01:27 +08:00
feat(docs): add CLI subcommands documentation and file naming strategies
- Introduced new documentation for CLI subcommands: `upload` and `watch`, detailing their usage, flags, and examples. - Added a section on file naming and conflict strategies, explaining how users can customize file names and handle duplicates via `/config` and `/fnametmpl` commands. - Translated the new documentation into Chinese for broader accessibility.
This commit is contained in:
krau
90
docs/content/zh/usage/cli.md
Normal file
90
docs/content/zh/usage/cli.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: "命令行子命令"
|
||||
weight: 21
|
||||
---
|
||||
|
||||
# 命令行子命令
|
||||
|
||||
除了直接运行 `./saveany-bot` (不带子命令) 启动 Telegram Bot 外, 这个二进制文件还提供两个把本地文件上传到存储后端的辅助子命令: `upload` (一次性) 和 `watch` (持续监听).
|
||||
|
||||
这些子命令会读取与 Bot 相同的 `config.toml`, 初始化数据库和缓存, 然后执行任务. 它们**不会**启动 Telegram Bot 本身, 但 `telegram` 类型的存储会在需要上传时临时启动 Bot 客户端来执行上传.
|
||||
|
||||
## `upload` — 上传单个文件
|
||||
|
||||
```
|
||||
saveany-bot upload -f <文件> -s <存储名> [-d <目录>] [--no-progress]
|
||||
```
|
||||
|
||||
参数:
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `-f, --file` | 是 | 待上传的本地文件路径 |
|
||||
| `-s, --storage` | 是 | 目标存储名 (必须存在于 `config.toml`) |
|
||||
| `-d, --dir` | 否 | 存储中的目标目录, 默认使用存储的 `base_path` |
|
||||
| `--no-progress` | 否 | 关闭终端进度条 |
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
# 上传文件到 "MyAlist" 的默认目录
|
||||
./saveany-bot upload -f ./movie.mp4 -s MyAlist
|
||||
|
||||
# 上传到指定子目录
|
||||
./saveany-bot upload -f ./movie.mp4 -s MyAlist -d movies/2026
|
||||
|
||||
# 通过 Telegram 存储上传并关闭进度条
|
||||
./saveany-bot upload -f ./photo.jpg -s MyChannel --no-progress
|
||||
```
|
||||
|
||||
## `watch` — 监听目录并自动上传
|
||||
|
||||
`watch` 子命令持续监听一个本地目录, 将新建或修改的文件上传到存储后端, 并保留相对监听根目录的子目录结构.
|
||||
|
||||
```
|
||||
saveany-bot watch -p <路径> -s <存储名> [-d <目录>] [选项]
|
||||
```
|
||||
|
||||
参数:
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|---|---|---|
|
||||
| `-p, --path` | *(必填)* | 要监听的本地目录 |
|
||||
| `-s, --storage` | *(必填)* | 目标存储名 |
|
||||
| `-d, --dir` | 存储的 `base_path` | 存储中的目标目录 |
|
||||
| `-r, --recursive` | `false` | 是否递归监听子目录 |
|
||||
| `--overwrite` | `false` | 覆盖存储上已有的文件, 而非跳过 |
|
||||
| `--initial-scan` | `false` | 启动时将目录中已存在的文件也上传 |
|
||||
| `--debounce` | `2s` | 文件最后一次写入后, 等待多久再上传 |
|
||||
| `--upload-workers` | `config.workers` | 并发上传数 |
|
||||
| `--retry-delay` | `3s` | 上传重试之间的延迟 |
|
||||
|
||||
{{< hint info >}}
|
||||
写入完成检测: 监听器会按文件做防抖处理, 仅当文件大小在一个 debounce 窗口内保持不变时才上传, 因此不会上传未写完的半成品文件.
|
||||
<br />
|
||||
若某文件在上传过程中又被修改, 它会在当前上传完成后再上传一次, 而不是被重复排队.
|
||||
{{< /hint >}}
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
# 递归监听 ./inbox 并且把新文件上传到 "MyAlist"
|
||||
./saveany-bot watch -p ./inbox -s MyAlist -r
|
||||
|
||||
# 自定义目标目录并覆盖已有文件
|
||||
./saveany-bot watch -p ./inbox -s MyAlist -d backup --overwrite
|
||||
|
||||
# 启动时把 ./inbox 中已有的内容也一并上传
|
||||
./saveany-bot watch -p ./inbox -s MyAlist --initial-scan
|
||||
```
|
||||
|
||||
### 行为说明
|
||||
|
||||
- 相对子目录结构会被保留: 以 `--path ./inbox` 为例, 写入 `./inbox/sub/file.txt` 的文件会被上传到 `<目标目录>/sub/file.txt`.
|
||||
- `watch` 会一直运行直到被中断 (如 `Ctrl-C` / `SIGINT`), 退出前会等待所有进行中的上传完成.
|
||||
- 重试次数遵循 `config.toml` 中的全局 `retry` 值, 各次重试之间间隔 `--retry-delay`.
|
||||
- `telegram` 类型的存储会自动启动 Bot 客户端来执行上传.
|
||||
|
||||
{{< hint warning >}}
|
||||
`watch` 子命令与 Bot 内的 `/watch` 命令 (监听 Telegram 聊天) 无关. 本子命令监听的是**本地文件系统目录**, 不依赖 Telegram.
|
||||
{{< /hint >}}
|
||||
75
docs/content/zh/usage/config.md
Normal file
75
docs/content/zh/usage/config.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: "文件命名与重名策略"
|
||||
weight: 11
|
||||
---
|
||||
|
||||
# 文件命名与重名策略
|
||||
|
||||
SaveAny-Bot 支持在 Telegram 中通过 `/config` 和 `/fnametmpl` 命令自定义保存文件的命名方式, 以及处理与已存在文件重名时的冲突策略.
|
||||
|
||||
## `/config` — 用户配置
|
||||
|
||||
`/config` 命令会弹出一个内联菜单, 你可以在其中修改以下两项用户级设置:
|
||||
|
||||
- **文件名策略** — 保存文件的命名方式
|
||||
- **重名文件保存策略** — 目标存储中已存在同名文件时的处理方式
|
||||
|
||||
设置按用户分别保存, 对该用户后续所有的保存/转存任务生效.
|
||||
|
||||
### 文件名策略
|
||||
|
||||
| 选项 | 行为 |
|
||||
|---|---|
|
||||
| `默认` | 使用媒体原始文件名, 没有原始文件名时使用生成名 |
|
||||
| `优先从消息生成` | 优先根据消息内容 (如 caption、文本) 生成文件名, 而非原始文件名 |
|
||||
| `自定义模板` | 使用 `/fnametmpl` 设置的自定义模板渲染文件名 |
|
||||
|
||||
### 重名文件保存策略
|
||||
|
||||
| 选项 | 行为 |
|
||||
|---|---|
|
||||
| `始终重命名` (默认) | 保留已有文件, 将新文件以另一个名字保存 |
|
||||
| `每次询问` | 每次遇到重名时通过内联按钮提示你选择 |
|
||||
| `始终覆盖` | 用新文件替换已有文件 |
|
||||
| `始终跳过` | 对重名文件不做处理 |
|
||||
|
||||
{{< hint info >}}
|
||||
重名策略仅在能够检测文件是否已存在的存储后端生效. 不支持检测文件是否存在的存储后端会退化为覆盖行为.
|
||||
{{< /hint >}}
|
||||
|
||||
## `/fnametmpl` — 自定义文件名模板
|
||||
|
||||
当文件名策略设置为 `自定义模板` 时, SaveAny-Bot 会用 `/fnametmpl` 配置的模板来渲染所保存文件的文件名.
|
||||
|
||||
```
|
||||
/fnametmpl [模板]
|
||||
```
|
||||
|
||||
- 不带参数运行 `/fnametmpl` 会显示当前模板以及帮助说明
|
||||
- 带模板字符串运行则会把它设为你的文件名模板
|
||||
|
||||
模板使用 Go [`text/template`](https://pkg.go.dev/text/template) 语法. 可用变量如下:
|
||||
|
||||
| 变量 | 说明 |
|
||||
|---|---|
|
||||
| `{{.msgid}}` | Telegram 消息 ID |
|
||||
| `{{.msgtags}}` | 消息中的标签, 以 `_` 连接输出 |
|
||||
| `{{.msggen}}` | 根据消息生成的文件名 |
|
||||
| `{{.msgdate}}` | 消息日期, 格式 `YYYY-MM-DD_HH-MM-SS` |
|
||||
| `{{.msgraw}}` | 消息的原始文本内容 (不做处理) |
|
||||
| `{{.origname}}` | 媒体的原始文件名 (如有) |
|
||||
| `{{.chatid}}` | 消息所在聊天的 ID |
|
||||
|
||||
示例:
|
||||
|
||||
```
|
||||
# 固定前缀 + 消息 ID + 日期
|
||||
/fnametmpl 图片_{{.msgid}}_{{.msgdate}}.jpg
|
||||
|
||||
# 优先使用原始文件名, 没有则用生成名
|
||||
/fnametmpl {{.origname}}
|
||||
```
|
||||
|
||||
{{< hint warning >}}
|
||||
模板仅在文件名策略设置为 `自定义模板` 时生效. 如果模板解析失败, SaveAny-Bot 会回退到默认的文件名生成逻辑.
|
||||
{{< /hint >}}
|
||||
@@ -27,6 +27,45 @@ weight: 3
|
||||
|
||||
此外, 规则中的存储名若使用 "CHOSEN" , 则表示存储到点击按钮选择的存储端的路径下
|
||||
|
||||
你也可以使用 `/rule switch` 来开关规则模式. 关闭规则模式时, 所有文件都将保存到默认存储.
|
||||
|
||||
## 预设规则
|
||||
|
||||
为常见文件类型手动编写正则规则比较繁琐, 因此 Bot 内置了一组预设分类 (视频、图片、音频、文档、压缩包), 可以通过一条命令批量导入:
|
||||
|
||||
```
|
||||
/rule preset <存储名> [基础路径]
|
||||
```
|
||||
|
||||
参数:
|
||||
|
||||
- `存储名`: 目标存储名 (必须存在且你有权访问)
|
||||
- `基础路径`: 可选. 各预设分类的子目录会创建在此路径下; 若不填则直接使用默认分类目录名
|
||||
|
||||
示例:
|
||||
|
||||
```
|
||||
# 导入预设规则到 "MyAlist", 使用默认目录布局
|
||||
/rule preset MyAlist
|
||||
|
||||
# 在自定义基础路径 "downloads/sorted" 下导入预设规则
|
||||
/rule preset MyAlist downloads/sorted
|
||||
```
|
||||
|
||||
此命令会为每个分类创建 `FILENAME-REGEX` 规则, 将匹配的文件路由到 `基础路径` 下对应的子目录:
|
||||
|
||||
| 分类 | 匹配的扩展名 | 默认目录 |
|
||||
|---|---|---|
|
||||
| 视频 | mp4, mkv, ts, avi, flv, mov, webm, wmv, rmvb, m2ts | `视频` |
|
||||
| 图片 | jpg, jpeg, png, gif, webp, bmp | `图片` |
|
||||
| 音频 | mp3, flac, wav, aac, m4a, ogg | `音频` |
|
||||
| 文档 | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, md, csv, epub, mobi, azw3, chm | `文档` |
|
||||
| 压缩包 | zip, rar, 7z, tar, gz, bz2, xz, ... | `压缩包` |
|
||||
|
||||
{{< hint info >}}
|
||||
导入后的预设规则就是普通的 `FILENAME-REGEX` 规则. 你可以像其他规则一样通过 `/rule` 查看或用 `/rule del <id>` 单独删除/编辑它们.
|
||||
{{< /hint >}}
|
||||
|
||||
规则类型:
|
||||
|
||||
## FILENAME-REGEX
|
||||
|
||||
Reference in New Issue
Block a user