pixivflow 2.20.5 → 2.21.0

package/README.en.md

@@ -2,41 +2,51 @@
 
 **Language / 语言:** [中文](README.md) · English
 
-Pixiv batch download and scheduled collection tool. Bulk-download
-illustrations and novels, search by tag, filter by bookmarks and dates,
-and run recurring collection jobs on a schedule. CLI and WebUI included.
-Built with TypeScript and Node.js; runs on Windows, macOS, Linux and Docker.
+**Pixiv downloader, filter and automatic collection tool.**
+
+Download a single Pixiv artwork (illustration, novel, ugoira) directly, or batch-collect
+by tag, ranking, publish date and bookmark count, and let the scheduler keep collecting
+on a cron. Results stay on your disk, or get delivered reliably over HTTP to another
+service — downstreams are optional, PixivFlow alone covers
+discover → filter → download → save.
 
 [![Version](https://img.shields.io/npm/v/pixivflow?style=flat-square)](https://www.npmjs.com/package/pixivflow)
 [![Node](https://img.shields.io/badge/Node.js-22.13%2B_LTS-green.svg?style=flat-square&logo=node.js)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 [![Documentation](https://img.shields.io/badge/Docs-redtidev1918.github.io-6366f1?style=flat-square)](https://redtidev1918.github.io/PixivFlow/)
 
-## Install
+## Typical scenarios
 
-Requires Node.js 22.13 or later; use a currently supported LTS release in production.
+**1. Download one link.** Paste any Pixiv link — artwork, novel, series, or user
+profile are all recognized:
 
 ```bash
-npm install -g pixivflow
-pixivflow --help
+pixivflow download --url https://www.pixiv.net/artworks/123456789
 ```
 
-For servers, prefer the Docker Compose setup described in
-[DOCKER.md](docs/DOCKER.md). To compose PixivFlow with TelePost, use the optional
-[pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy)
-deployment and operations kit. To build from source:
+**2. Batch download by conditions.** Define what to collect in your config (tag,
+ranking, date range, minimum bookmarks) and run it in one pass. Downloaded items are
+tracked in SQLite and skipped, so re-running never re-downloads. See
+[Filtering and targets](#filtering-and-targets).
 
-```bash
-git clone https://github.com/redtidev1918/PixivFlow.git
-cd PixivFlow
-npm install
-npm run build
-```
+**3. Collect on a schedule and deliver.** Run it under cron: discover, download, and
+optionally hand files to another service — the local copy is deleted only after the
+receiver confirms.
 
-Termux / Android: see [TERMUX_INSTALL.md](docs/TERMUX_INSTALL.md).
+```text
+Pixiv ──► PixivFlow ──┬──► local, permanent (persistent)
+                      └──► HTTP delivery (cache) ──► TelePost / any compatible service
+```
 
 ## Quick start
 
+Requires Node.js 22.13 or later; use a currently supported LTS release in production.
+
+```bash
+npm install -g pixivflow
+pixivflow --help
+```
+
 Sign in to your Pixiv account (creates OAuth credentials, one time):
 
 ```bash
@@ -58,22 +68,27 @@ pixivflow download
 pixivflow scheduler             # long-running cron collection
 ```
 
-### Multiple schedules and atomic hot reload
+Prefer not to hand-write config? The interactive wizard `pixivflow setup` generates it.
+For a GUI, run `pixivflow webui` (frontend:
+[pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui)).
 
-`schedules[]` hosts independently timed target groups in one Node process.
-Plans share Pixiv authentication, SQLite, and file services, while a bounded
-serial queue prevents overlapping downloads from producing memory spikes.
-The active config is watched by default: replace it over SSH and PixivFlow
-fully validates the new snapshot before swapping the entire cron table. An
-invalid edit leaves the previous schedules running. In-flight work finishes
-on its old snapshot; the next run sees the new one.
+Downloading Pixiv ugoira additionally needs `python3` and `ffmpeg`: frames are
+composited into a looping GIF by per-frame delay, ready to be delivered as an animation.
+The official Docker image includes both — see
+[configuration notes](docs/CONFIG.md#pixiv-动图ugoira).
 
-Legacy single-`scheduler` configs remain supported. `schedules`, `targets`,
-`delivery`, and `download` are hot-reloadable; changes to `pixiv`, `network`,
-or `storage` require a process restart. See the ready-to-edit
-[`config/fly-two-bots.example.json`](config/fly-two-bots.example.json) template.
+Build from source:
+
+```bash
+git clone https://github.com/redtidev1918/PixivFlow.git
+cd PixivFlow
+npm install
+npm run build
+```
 
-## Download targets
+Termux / Android: see [TERMUX_INSTALL.md](docs/TERMUX_INSTALL.md).
+
+## Filtering and targets
 
 Define what to collect in the `targets` section of your config. Conditions
 combine:
@@ -88,32 +103,44 @@ combine:
 
 Downloaded items are tracked in a SQLite database and skipped automatically;
 files that exist without a database record are reconciled, so the two never
-conflict.
+conflict. Illustration tasks with `mode: "topic"` keep a bounded hotness candidate
+pool: if the top item is already downloaded, the next undownloaded one is promoted by
+hotness instead of the run coming back empty.
+
+## Persistent and cache delivery modes
 
-### Persistent and cache delivery modes
+Each target (one tag / schedule) can use one of two storage modes:
 
-Each target can use `storageMode: "persistent"` (the default, keep files) or
-`storageMode: "cache"` (send files to a named delivery target and delete them
-only after success). The delivery layer is service-independent;
+- **`persistent`** (the default): keep files forever.
+- **`cache`**: send files to a named delivery target and delete the local copy only
+  after the receiver confirms — saves disk.
+
+A "delivery target" is just configuration: which URL to POST to and which fields to
+send. It is not bound to any service and can point at any compatible HTTP endpoint;
 [TelePost](https://github.com/redtidev1918/TelePost) and
-[telepress](https://github.com/redtidev1918/telepress) are example downstreams,
-not dependencies. This example merely translates an HTTP multipart submission API into configuration:
+[telepress](https://github.com/redtidev1918/telepress) are example downstreams. Example:
 
 ```json
 {
   "delivery": {
+    "outboxRetryBaseMs": 300000,
+    "outboxRetryMaxMs": 21600000,
     "targets": {
       "sharing-api": {
         "type": "httpMultipart",
-        "url": "https://example.test/submissions",
-        "readinessUrl": "https://example.test/ready",
-        "notificationUrl": "https://example.test/notifications",
+        "url": "https://your-domain.example/api/bot1/v1/submissions",
+        "readinessUrl": "https://your-domain.example/ready",
+        "notificationUrl": "https://your-domain.example/api/bot1/v1/notifications",
         "headers": { "Authorization": "Bearer ${SHARING_TOKEN}" },
         "fileField": "files",
         "fields": { "title": "{{title}}" },
-        "success": { "statuses": [201], "jsonPath": "ok", "equals": true }
+        "success": { "statuses": [201], "jsonPath": "ok", "equals": true },
+        "arrayFormat": "comma",
+        "maxAttempts": 3,
+        "retryDelayMs": 2000
       }
-    }
+    },
+    "deleteAfterDelivery": true
   },
   "targets": [
     { "type": "illustration", "tag": "archive", "storageMode": "persistent" },
@@ -130,20 +157,89 @@ not dependencies. This example merely translates an HTTP multipart submission AP
 }
 ```
 
-Headers and URLs accept arbitrary `${ENV_NAME}` interpolation. Cache-mode
-illustration delivery also sends an optional, one-to-one Pixiv preview in the
-`previews` multipart field while retaining the original as the authoritative
-artifact. Failed delivery keeps both files in the SQLite outbox; the worker
-retries the same intent after restart. Final no-match
-notifications use the same durable outbox, so a restart or a temporary review
-endpoint outage does not silently lose the alert.
+Headers and URLs accept `${ENV_NAME}` interpolation (never hard-code tokens). Cache-mode
+illustration delivery also sends an optional, one-to-one Pixiv preview in the `previews`
+multipart field while retaining the original as the authoritative artifact; a generic
+receiver may ignore that field.
+
+Operational notifications can point `notificationUrl` at an
+[Apprise API](docs/APPRISE.md) instance, which fans out to Email, Telegram, Discord,
+ntfy and more; PixivFlow does not implement those notification protocols itself.
+
+- The `url` above is any compatible HTTP submission endpoint; the example uses
+  TelePost's `/api/botN/v1/submissions` (put the `tp_...` from `/gen_token` into
+  `SHARING_TOKEN` — that is the example service's own auth scheme).
+- The same target can point at [telepress](https://github.com/redtidev1918/telepress)'s
+  `/publish/gallery` to publish illustrations as a Telegra.ph gallery, see the
+  "Telegraph (telegra.ph) gallery upload" section of [CONFIG.md](docs/CONFIG.md).
+
+## Automation and reliability
+
+### Multiple schedules and atomic hot reload
+
+`schedules[]` hosts independently timed target groups in one Node process.
+Plans share Pixiv authentication, SQLite, and file services, while a bounded
+serial queue prevents overlapping downloads from producing memory spikes. This runs
+comfortably on small machines — measured with `topic` discovery, selection and
+download inside a 256 MB cgroup: peak RSS ≈ 106 MB, heapUsed ≈ 33 MB, no OOM
+(see [DOCKER.md](docs/DOCKER.md)).
+The active config is watched by default: replace it over SSH and PixivFlow
+fully validates the new snapshot before swapping the entire cron table. An
+invalid edit leaves the previous schedules running. In-flight work finishes
+on its old snapshot; the next run sees the new one.
+
+```json
+{
+  "scheduler": { "enabled": false, "cron": "0 3 * * *" },
+  "schedules": [
+    { "id": "bot1", "enabled": true, "cron": "10 5 * * *", "targetIds": ["bot1-art", "bot1-novel"] },
+    { "id": "bot2", "enabled": true, "cron": "30 5 * * *", "targetIds": ["bot2-art", "bot2-novel"] }
+  ],
+  "targets": [
+    { "id": "bot1-art", "type": "illustration", "mode": "ranking", "rankingDate": "YESTERDAY" },
+    { "id": "bot1-novel", "type": "novel", "mode": "ranking", "rankingDate": "YESTERDAY" }
+  ]
+}
+```
+
+Legacy single-`scheduler` configs remain supported. `schedules`, `targets`,
+`delivery`, and `download` are hot-reloadable; changes to `pixiv`, `network`,
+or `storage` require a process restart. See the ready-to-edit
+[`config/fly-two-bots.example.json`](config/fly-two-bots.example.json) template.
 
-When `readinessUrl` is configured, a non-2xx readiness response defers the row
-without incrementing its attempt count. Use `pixivflow outbox list`,
-`inspect <id>`, `retry <id>` / `retry --dead`, and `cancel <id>` for recovery;
-`run-once` is not an outbox replay command.
+### Durable delivery outbox
+
+Delivery is transactional (a SQLite outbox): at-least-once execution with
+effectively-once visible effects. Every external side effect (one content delivery,
+one notification) becomes a row with an idempotency key and a row-level lease; an
+independent worker pumps it right away and retries with exponential backoff (5 minutes
+up to 6 hours by default), and rows that exceed `maxAttempts` go dead and are recorded
+as `failed` in the delivery ledger. After a crash or machine hang, expired `processing`
+leases are taken over by the next process, which retries the same idempotent intent — a
+downstream converges via `idempotent_replay` (same key, lost ACK) or
+`duplicate_existing` (historical duplicate), so the channel still shows exactly one
+message. Legacy file-based `delivery-outbox/*.json` manifests are migrated into SQLite
+once at startup, idempotently. "Nothing to publish today" notifications share that table
+but are pumped independently, so a temporarily unavailable review endpoint cannot block
+content delivery.
+
+When `readinessUrl` is configured, a non-2xx readiness response returns the row to
+pending without incrementing its attempt count — strictly separate from `/live`'s
+"process is alive" meaning. Dead letters are recovered through first-class CLI:
 
-Interactive configuration wizard: `pixivflow setup`.
+```bash
+pixivflow outbox list --status dead
+pixivflow outbox inspect <id>
+pixivflow outbox retry <id>   # only accepts dead rows, keeps the idempotency key
+pixivflow outbox retry --dead
+pixivflow outbox cancel <id>  # cancels rows that have not run yet
+```
+
+`run-once` re-runs the download plan; it is not an outbox replay, and you should not
+hand-edit SQLite's `next_attempt_at`. For long-running hosts, use `pixivflow doctor`
+(stuck slot/outbox leases, pending deliveries, dead rows; `--repair` converges) and
+`pixivflow reconcile` (record downstream-confirmed historical duplicates in the delivery
+ledger; dry-run by default).
 
 ## Common commands
 
@@ -153,16 +249,31 @@ Interactive configuration wizard: `pixivflow setup`.
 | `pixivflow download --url <url>` | Direct download via URL |
 | `pixivflow random` | Random popular artwork |
 | `pixivflow scheduler` | Start scheduled jobs |
+| `pixivflow webui` | Start the WebUI |
 | `pixivflow config` | Manage config (view / edit / backup / restore) |
 | `pixivflow status` | Download stats and recent records |
 | `pixivflow health` | Health check: config, directories, connectivity |
+| `pixivflow doctor` | Reliability check: stuck slot/outbox leases, pending deliveries, dead rows; `--repair` converges |
+| `pixivflow reconcile` | Record downstream-confirmed historical duplicates (dry-run by default, `--repair` writes) |
+| `pixivflow outbox` | List, inspect, replay dead letters, or cancel durable intents that have not run |
 | `pixivflow tags discover <seed>` | Discover related tags (Pixiv autocomplete + tag co-occurrence); lists candidates only |
 | `pixivflow tags apply <manifest> --target <id> --select <tag1,tag2>` | Atomically write chosen tags into config after manual confirmation, then hot-reload |
+| `pixivflow topic resolve <topic>` | Inspect the derived tag space for a topic (`--type illustration\|novel`, `--refresh`) |
+| `pixivflow topic test <topic> --date YESTERDAY` | Dry-run the candidates and Top N for one day, without downloading |
 
 `tags discover` calls the Pixiv autocomplete endpoint and samples recent illustrations/novels to count co-occurring tags, caching results for 7 days; it **never** changes active plans. After reviewing candidates, run `tags apply` to explicitly select tags: it validates the whole config, writes a backup and atomically replaces the file so a running scheduler hot-reloads it.
 
 More commands in [USAGE.md](docs/USAGE.md); see the [migration guide](docs/MIGRATION.md) for upgrading from v1 to v2.
 
+## Deployment
+
+- **Docker / long-running server**: see [DOCKER.md](docs/DOCKER.md).
+- **Android / Termux**: see [TERMUX_INSTALL.md](docs/TERMUX_INSTALL.md).
+- **Composing with TelePost**: PixivFlow and TelePost are both usable on their own.
+  Only if you want to deploy the two together as one workflow do you need the
+  [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy)
+  deployment and operations kit.
+
 ## Documentation
 
 Full tutorial site: <https://redtidev1918.github.io/PixivFlow/>
@@ -183,6 +294,18 @@ Full tutorial site: <https://redtidev1918.github.io/PixivFlow/>
 
 Chinese version: [README.md](README.md).
 
+## Related projects
+
+PixivFlow is fully standalone. These are the related projects in the same author's
+ecosystem, and what each one owns:
+
+| Project | What it is | When you need it |
+| --- | --- | --- |
+| [TelePost](https://github.com/redtidev1918/TelePost) | Telegram channel submission, moderation and automated publishing platform | When you want downloads to land in a Telegram channel for human review before publishing — configure it as a delivery downstream. This is an optional composition; PixivFlow does not depend on it |
+| [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy) | Deployment and operations kit for PixivFlow + TelePost (Docker / VPS / cloud) | When you want to deploy and operate both projects together. Running PixivFlow alone does not need it |
+| [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui) | WebUI frontend for PixivFlow | When you want a GUI to manage downloads and schedules |
+| [pixiv-token-getter](https://github.com/redtidev1918/pixiv-token-getter) | PKCE OAuth login library and CLI (`ptg`) | PixivFlow's login dependency; also usable on its own to obtain Pixiv tokens |
+
 ## Feedback
 
 Bugs and feature requests go to

package/README.md

@@ -2,41 +2,46 @@
 
 **语言 / Language:** 中文 · [English](README.en.md)
 
-Pixiv 批量下载与定时收集工具。支持插画和小说的批量下载、标签搜索、
-多维度筛选和 Cron 定时任务，提供命令行与 WebUI 两种使用方式。
-基于 TypeScript 和 Node.js，可在 Windows、macOS、Linux 及 Docker 中运行。
+**Pixiv 下载、筛选与自动收集工具。**
+
+可以直接下载单个 Pixiv 作品（插画、小说、动图），也可以按标签、热度、日期和收藏数
+批量筛选，并通过 scheduler 定时自动收集。结果既能永久保存在本地，也能按需通过 HTTP
+可靠交付给其他服务——下游是可选的，PixivFlow 自己就能跑完「发现 → 筛选 → 下载 → 保存」
+的完整链路。
 
 [![Version](https://img.shields.io/npm/v/pixivflow?style=flat-square)](https://www.npmjs.com/package/pixivflow)
 [![Node](https://img.shields.io/badge/Node.js-22.13%2B_LTS-green.svg?style=flat-square&logo=node.js)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 [![Documentation](https://img.shields.io/badge/Docs-redtidev1918.github.io-6366f1?style=flat-square)](https://redtidev1918.github.io/PixivFlow/)
 
-## 安装
+## 典型场景
 
-需要 Node.js 22.13 或更高版本；生产环境请使用仍受支持的 LTS。
-下载 Pixiv 动图（ugoira）还需要 `python3` 和 `ffmpeg`：程序按逐帧延迟合成循环 GIF，
-可直接交给 TelePost 作为动画发送。官方 Docker 镜像已包含两者，详见 [配置说明](docs/CONFIG.md#pixiv-动图ugoira)。
+**1. 下载一个链接。** 直接粘贴任意 Pixiv 链接——插画、小说、系列、用户主页都能识别：
 
 ```bash
-npm install -g pixivflow
-pixivflow --help
+pixivflow download --url https://www.pixiv.net/artworks/123456789
 ```
 
-服务器部署见 [DOCKER.md](docs/DOCKER.md)。需要把 PixivFlow 与 TelePost 组合运行时，再使用
-[pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy)；
-它是可选的部署与运维套件。
-从源码构建：
+**2. 按条件批量下载。** 在配置里定义要收集什么（标签、榜单、发布日期、收藏数下限），
+一次跑完；已下载的作品由 SQLite 记录并自动跳过，重复运行不会重复拉取。
+见[筛选与下载目标](#筛选与下载目标)。
 
-```bash
-git clone https://github.com/redtidev1918/PixivFlow.git
-cd PixivFlow
-npm install
-npm run build
+**3. 定时自动收集并交付。** 用 cron 长期挂机：定时发现、下载，再按需把内容投递给
+其他服务——对方确认收到后才删除本地副本。
+
+```text
+Pixiv ──► PixivFlow ──┬──► 本地永久保存（persistent）
+                      └──► HTTP 交付（cache）──► TelePost / 其他兼容服务
 ```
 
-Termux / Android 环境见 [TERMUX_INSTALL.md](docs/TERMUX_INSTALL.md)。
+## 快速开始
 
-## 快速上手
+需要 Node.js 22.13 或更高版本；生产环境请使用仍受支持的 LTS。
+
+```bash
+npm install -g pixivflow
+pixivflow --help
+```
 
 登录 Pixiv 账号（生成 OAuth 凭据，只需一次）：
 
@@ -58,35 +63,25 @@ pixivflow download
 pixivflow scheduler             # 按 cron 配置长期挂机自动收集
 ```
 
-### 单进程多计划与配置热重载
+不想手写配置？运行交互式向导 `pixivflow setup` 一步步生成。图形界面用
+`pixivflow webui`（前端见 [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui)）。
 
-`schedules[]` 可以为不同 target 组设置各自的 Cron。所有计划由一个 Node
-进程托管，共享 Pixiv 客户端、SQLite 与文件服务；执行阶段使用有界串行队列，
-适合 512 MiB 小内存机器（实测：`topic` 发现/采集/下载全程在 256 MB cgroup 限制下
-稳定运行，峰值 RSS ≈ 106 MB、heapUsed ≈ 33 MB，无 OOM，见 [DOCKER.md](docs/DOCKER.md)）。配置文件默认被监听，SSH/同步工具替换文件后会先完整
-校验，再一次性替换全部调度项；无效 JSON、错误 Cron 或未知 target id 不会破坏
-当前运行中的计划。正在执行的任务继续使用旧快照，下一次任务使用新快照。
+下载 Pixiv 动图（ugoira）还需要 `python3` 和 `ffmpeg`：程序按逐帧延迟合成循环 GIF，
+可直接作为动画交付给下游。官方 Docker 镜像已包含两者，详见
+[配置说明](docs/CONFIG.md#pixiv-动图ugoira)。
 
-```json
-{
-  "scheduler": { "enabled": false, "cron": "0 3 * * *" },
-  "schedules": [
-    { "id": "bot1", "enabled": true, "cron": "10 5 * * *", "targetIds": ["bot1-art", "bot1-novel"] },
-    { "id": "bot2", "enabled": true, "cron": "30 5 * * *", "targetIds": ["bot2-art", "bot2-novel"] }
-  ],
-  "targets": [
-    { "id": "bot1-art", "type": "illustration", "mode": "ranking", "rankingDate": "YESTERDAY" },
-    { "id": "bot1-novel", "type": "novel", "mode": "ranking", "rankingDate": "YESTERDAY" }
-  ]
-}
+从源码构建：
+
+```bash
+git clone https://github.com/redtidev1918/PixivFlow.git
+cd PixivFlow
+npm install
+npm run build
 ```
 
-旧的单 `scheduler` 配置继续兼容。`pixiv`、`network`、`storage` 涉及长生命周期
-连接或路径，修改后需要重启；`schedules`、`targets`、`delivery`、`download` 可以
-热重载。完整双 Bot 缓存投递模板见
-[`config/fly-two-bots.example.json`](config/fly-two-bots.example.json)。
+Termux / Android 环境见 [TERMUX_INSTALL.md](docs/TERMUX_INSTALL.md)。
 
-## 下载目标
+## 筛选与下载目标
 
 在配置文件的 `targets` 中定义要收集的内容，多个条件可以组合：
 
@@ -102,7 +97,7 @@ pixivflow scheduler             # 按 cron 配置长期挂机自动收集
 两者互不冲突。`mode: "topic"` 的插画任务会保留一个有界热度候选池：同一发布日期
 重复执行时若第一名已经下载，会按热度自动递补下一部未下载作品，而不是空跑。
 
-### 本地留存与缓存交付
+## 本地留存与缓存交付
 
 每个 target（一个 tag / 计划）有两种保存方式：
 
@@ -120,12 +115,12 @@ pixivflow scheduler             # 按 cron 配置长期挂机自动收集
     "outboxRetryBaseMs": 300000,
     "outboxRetryMaxMs": 21600000,
     "targets": {
-      "tg-example": {
+      "sharing-api": {
         "type": "httpMultipart",
         "url": "https://your-domain.example/api/bot1/v1/submissions",
         "readinessUrl": "https://your-domain.example/ready",
         "notificationUrl": "https://your-domain.example/api/bot1/v1/notifications",
-        "headers": { "Authorization": "Bearer ${TG_SUBMIT_TOKEN}" },
+        "headers": { "Authorization": "Bearer ${SHARING_TOKEN}" },
         "fileField": "files",
         "fields": { "title": "{{title}}" },
         "success": { "statuses": [201], "jsonPath": "ok", "equals": true },
@@ -143,7 +138,7 @@ pixivflow scheduler             # 按 cron 配置长期挂机自动收集
       "tag": "更新",
       "storageMode": "cache",
       "delivery": {
-        "target": "tg-example",
+        "target": "sharing-api",
         "fields": { "tags": ["公告", "更新"], "anonymous": false }
       }
     }
@@ -155,6 +150,49 @@ pixivflow scheduler             # 按 cron 配置长期挂机自动收集
 插画 cache 投递会在 multipart 的 `previews` 字段携带 Pixiv 的低分辨率预览（与 `files`
 一一对应），原图仍是权威素材；通用接收端可以忽略该可选字段。
 
+运维通知可直接把 `notificationUrl` 指向 [Apprise API](docs/APPRISE.md)，由 Apprise 统一发送
+Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协议。
+
+- 上面的 `url` 指向任意兼容的 HTTP 投稿接口；示例里用的是 TelePost 的
+  `/api/botN/v1/submissions`（把 `/gen_token` 得到的 `tp_...` 放进 `SHARING_TOKEN` 即可，
+  这是示例服务自己的鉴权方式）。
+- 同一目标也可指向 [telepress](https://github.com/redtidev1918/telepress) 的 `/publish/gallery`，
+  把插画自动发布成 Telegra.ph 相册，见 [CONFIG.md](docs/CONFIG.md) 的
+  「Telegraph（telegra.ph）相册上传」。
+
+## 自动化与可靠性
+
+### 单进程多计划与配置热重载
+
+`schedules[]` 可以为不同 target 组设置各自的 Cron。所有计划由一个 Node
+进程托管，共享 Pixiv 客户端、SQLite 与文件服务；执行阶段使用有界串行队列，
+适合 512 MiB 小内存机器（实测：`topic` 发现/采集/下载全程在 256 MB cgroup 限制下
+稳定运行，峰值 RSS ≈ 106 MB、heapUsed ≈ 33 MB，无 OOM，见 [DOCKER.md](docs/DOCKER.md)）。
+配置文件默认被监听，SSH/同步工具替换文件后会先完整校验，再一次性替换全部调度项；
+无效 JSON、错误 Cron 或未知 target id 不会破坏当前运行中的计划。正在执行的任务
+继续使用旧快照，下一次任务使用新快照。
+
+```json
+{
+  "scheduler": { "enabled": false, "cron": "0 3 * * *" },
+  "schedules": [
+    { "id": "bot1", "enabled": true, "cron": "10 5 * * *", "targetIds": ["bot1-art", "bot1-novel"] },
+    { "id": "bot2", "enabled": true, "cron": "30 5 * * *", "targetIds": ["bot2-art", "bot2-novel"] }
+  ],
+  "targets": [
+    { "id": "bot1-art", "type": "illustration", "mode": "ranking", "rankingDate": "YESTERDAY" },
+    { "id": "bot1-novel", "type": "novel", "mode": "ranking", "rankingDate": "YESTERDAY" }
+  ]
+}
+```
+
+旧的单 `scheduler` 配置继续兼容。`pixiv`、`network`、`storage` 涉及长生命周期
+连接或路径，修改后需要重启；`schedules`、`targets`、`delivery`、`download` 可以
+热重载。完整双 Bot 缓存投递模板见
+[`config/fly-two-bots.example.json`](config/fly-two-bots.example.json)。
+
+### 投递事务发件箱
+
 投递是**事务发件箱（SQLite outbox）**式的，at-least-once 执行、effectively-once
 可见效果：每个外部副作用（一次内容投递、一条通知）在 `outbox` 表落一行，带幂等键和
 行级租约，独立 worker 立即泵送、指数退避重试（默认 5 分钟起步、最长 6 小时），超过
@@ -177,15 +215,9 @@ pixivflow outbox cancel <id>  # 只取消尚未执行的 row
 ```
 
 `run-once` 会重新执行下载计划，不等价于 outbox replay；不要手改 SQLite 的
-`next_attempt_at`。
-
-运维通知可直接把 `notificationUrl` 指向 [Apprise API](docs/APPRISE.md)，由 Apprise 统一发送
-Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协议。
-
-- 上面的示例是投稿给一个 HTTP 接口：把 `/gen_token` 得到的 `tp_...` 放进 `TG_SUBMIT_TOKEN` 即可（这是示例服务自己的鉴权方式）。
-- 同一目标也可指向 [telepress](https://github.com/redtidev1918/telepress) 的 `/publish/gallery`，把插画自动发布成 Telegra.ph 相册，见 [CONFIG.md](docs/CONFIG.md) 的「Telegraph（telegra.ph）相册上传」。
-
-不想手写配置？运行交互式向导 `pixivflow setup` 一步步生成。
+`next_attempt_at`。长期运行环境的体检与收敛用 `pixivflow doctor`（卡住的 slot/outbox
+租约、pending 投递、dead 行，`--repair` 收敛）与 `pixivflow reconcile`（把下游已确认的
+历史重复登记进投递账本，默认 dry-run）。
 
 ## 常用命令
 
@@ -195,6 +227,7 @@ Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协
 | `pixivflow download --url <url>` | 通过 URL 直接下载 |
 | `pixivflow random` | 随机下载热门作品 |
 | `pixivflow scheduler` | 启动定时任务 |
+| `pixivflow webui` | 启动 WebUI |
 | `pixivflow config` | 配置管理（查看 / 编辑 / 备份 / 恢复） |
 | `pixivflow status` | 下载统计与最近记录 |
 | `pixivflow health` | 健康检查：配置、目录可写性、连通性 |
@@ -210,6 +243,15 @@ Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协
 
 其他用法见 [USAGE.md](docs/USAGE.md)；从 v1 升级到 v2 见 [迁移指南](docs/MIGRATION.md)。
 
+## 部署
+
+- **Docker / 服务器长期挂机**：见 [DOCKER.md](docs/DOCKER.md)。
+- **Android / Termux**：见 [TERMUX_INSTALL.md](docs/TERMUX_INSTALL.md)。
+- **与 TelePost 组合部署**：PixivFlow 与 TelePost 都可以独立使用；只有当你希望把两者
+  组合成一套完整工作流时，才需要
+  [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy)
+  这个部署与运维套件。
+
 ## 文档
 
 完整教程站点：<https://redtidev1918.github.io/PixivFlow/>
@@ -230,6 +272,17 @@ Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协
 
 English version: [README.en.md](README.en.md).
 
+## 相关项目
+
+PixivFlow 可以完全独立使用。下面是同一作者生态里与它相关的项目，以及各自负责什么：
+
+| 项目 | 是什么 | 什么时候需要 |
+| --- | --- | --- |
+| [TelePost](https://github.com/redtidev1918/TelePost) | Telegram 频道投稿、审核与自动化发布平台 | 想把下载结果投进 Telegram 频道、先人工审核再发布时，把它配成 delivery 下游即可。这只是可选组合，PixivFlow 不依赖它 |
+| [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy) | PixivFlow + TelePost 的部署与运维套件（Docker / VPS / 云平台） | 想一次性把上面两个项目部署并运维起来时。只跑 PixivFlow 不需要它 |
+| [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui) | PixivFlow 的 WebUI 前端 | 想用图形界面管理下载与计划 |
+| [pixiv-token-getter](https://github.com/redtidev1918/pixiv-token-getter) | PKCE OAuth 登录库与 CLI（`ptg`） | PixivFlow 的登录依赖；也可以单独用于获取 Pixiv token |
+
 ## 问题反馈
 
 Bug 与功能建议请提交到