pixivflow 2.17.0 → 2.18.0

package/{README_EN.md → README.en.md}

@@ -1,6 +1,6 @@
 # PixivFlow
 
-**English** | [中文](https://github.com/redtidev1918/PixivFlow/blob/master/README.md)
+**Language / 语言:** [中文](README.md) · English
 
 Pixiv batch download and scheduled collection tool. Bulk-download
 illustrations and novels, search by tag, filter by bookmarks and dates,
@@ -8,13 +8,13 @@ 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.
 
 [![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.12%2B_LTS-green.svg?style=flat-square&logo=node.js)](https://nodejs.org/)
+[![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
 
-Requires Node.js 22.12 or later; use a currently supported LTS release in production.
+Requires Node.js 22.13 or later; use a currently supported LTS release in production.
 
 ```bash
 npm install -g pixivflow
@@ -157,7 +157,7 @@ Interactive configuration wizard: `pixivflow setup`.
 
 `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 [CLI_MIGRATION_SUMMARY.md](docs/CLI_MIGRATION_SUMMARY.md).
+More commands in [USAGE.md](docs/USAGE.md); see the [migration guide](docs/MIGRATION.md) for upgrading from v1 to v2.
 
 ## Documentation
 
@@ -165,14 +165,16 @@ Full tutorial site: <https://redtidev1918.github.io/PixivFlow/>
 
 | Document | Description |
 | --- | --- |
+| [📥 Download](docs/download.md) | Prebuilt packages, npm and Docker |
 | [QUICKSTART](docs/QUICKSTART.md) | Get running in three minutes |
 | [CONFIG](docs/CONFIG.md) | All configuration options |
 | [USAGE](docs/USAGE.md) | Feature reference |
 | [LOGIN](docs/LOGIN.md) | Account sign-in details |
 | [DOCKER](docs/DOCKER.md) | Container deployment |
 | [ARCHITECTURE](docs/ARCHITECTURE.md) | Architecture notes |
+| [MIGRATION](docs/MIGRATION.md) | Upgrade from v1 to v2 |
 | [RELEASING](docs/RELEASING.md) | npm release workflow |
-| [CHANGELOG](docs/project/CHANGELOG.md) | Version history |
+| [CHANGELOG](CHANGELOG.md) | Version history |
 | [ACKNOWLEDGMENTS](docs/ACKNOWLEDGMENTS.md) | Credits and references |
 
 Chinese version: [README.md](README.md).
@@ -183,7 +185,7 @@ Bugs and feature requests go to
 [Issues](https://github.com/redtidev1918/PixivFlow/issues); please run
 `pixivflow health` first and include its output (strip tokens and other
 secrets before sharing). Security issues are handled privately — see
-[SECURITY.md](SECURITY.md).
+[SECURITY.en.md](SECURITY.en.md).
 
 ## Acknowledgments
 

package/README.md

@@ -1,19 +1,19 @@
 # PixivFlow
 
-[English](https://github.com/redtidev1918/PixivFlow/blob/master/README_EN.md) | **中文**
+**语言 / Language:** 中文 · [English](README.en.md)
 
 Pixiv 批量下载与定时收集工具。支持插画和小说的批量下载、标签搜索、
 多维度筛选和 Cron 定时任务，提供命令行与 WebUI 两种使用方式。
 基于 TypeScript 和 Node.js，可在 Windows、macOS、Linux 及 Docker 中运行。
 
 [![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.12%2B_LTS-green.svg?style=flat-square&logo=node.js)](https://nodejs.org/)
+[![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.12 或更高版本；生产环境请使用仍受支持的 LTS。
+需要 Node.js 22.13 或更高版本；生产环境请使用仍受支持的 LTS。
 下载 Pixiv 动图（ugoira）还需要 `python3` 和 `ffmpeg`：程序按逐帧延迟合成循环 GIF，
 可直接交给 TelePost 作为动画发送。官方 Docker 镜像已包含两者，详见 [配置说明](docs/CONFIG.md#pixiv-动图ugoira)。
 
@@ -207,7 +207,7 @@ Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协
 
 `tags discover` 会调用 Pixiv 标签联想接口，并抽样最近插画 / 小说统计共同出现的标签，结果缓存 7 天；它**不会**改动任何下载计划。确认候选后用 `tags apply` 显式选择，应用前会整份校验配置、自动备份并原子替换，运行中的 scheduler 经配置热重载生效。
 
-其他用法见 [CLI_MIGRATION_SUMMARY.md](docs/CLI_MIGRATION_SUMMARY.md)。
+其他用法见 [USAGE.md](docs/USAGE.md)；从 v1 升级到 v2 见 [迁移指南](docs/MIGRATION.md)。
 
 ## 文档
 
@@ -215,17 +215,19 @@ Email、Telegram、Discord、ntfy 等渠道；PixivFlow 不实现这些通知协
 
 | 文档 | 说明 |
 | --- | --- |
+| [📥 下载](docs/download.md) | 各平台安装包、npm 与 Docker 获取方式 |
 | [QUICKSTART](docs/QUICKSTART.md) | 三分钟上手 |
 | [CONFIG](docs/CONFIG.md) | 全部配置项说明 |
 | [USAGE](docs/USAGE.md) | 功能详解 |
 | [LOGIN](docs/LOGIN.md) | 账号登录相关 |
 | [DOCKER](docs/DOCKER.md) | 容器化部署方案 |
 | [ARCHITECTURE](docs/ARCHITECTURE.md) | 架构与技术实现 |
+| [MIGRATION](docs/MIGRATION.md) | 从 v1 升级到 v2 |
 | [RELEASING](docs/RELEASING.md) | npm 发版流程 |
-| [CHANGELOG](docs/project/CHANGELOG.md) | 版本更新日志 |
+| [CHANGELOG](CHANGELOG.md) | 版本更新日志 |
 | [ACKNOWLEDGMENTS](docs/ACKNOWLEDGMENTS.md) | 参考与致谢:灵感来源、核心依赖与规范声明 |
 
-English version: [README_EN.md](README_EN.md).
+English version: [README.en.md](README.en.md).
 
 ## 问题反馈
 

package/config/examples/README.md

@@ -0,0 +1,218 @@
+# 示例配置文件说明
+
+本目录包含 PixivFlow 的各种配置文件示例。根据你的需求选择合适的配置文件。
+
+## 📁 配置文件列表
+
+### 1. `standalone.config.example.json` - 完整配置示例
+**推荐用于：** 需要了解所有配置选项的详细说明
+
+- ✅ 包含所有可用配置选项
+- ✅ 每个选项都有详细的中文注释说明
+- ✅ 包含多个实际使用示例
+- ✅ 适合学习和参考
+
+**使用方法：**
+```bash
+cp config/examples/standalone.config.example.json config/standalone.config.json
+# 然后修改 refreshToken
+```
+
+---
+
+### 2. `standalone.config.simple.json` - 简化快速开始 ⭐
+**推荐用于：** 快速开始使用，不需要复杂配置
+
+- ✅ 配置简洁明了
+- ✅ 只包含最常用的选项
+- ✅ 适合新手快速上手
+- ✅ 包含一个基础的下载示例
+
+**使用方法：**
+```bash
+cp config/examples/standalone.config.simple.json config/standalone.config.json
+# 运行 pixivflow login 获取 refreshToken
+# 修改配置文件中的 refreshToken
+# 根据需要修改 targets 中的标签
+```
+
+---
+
+### 3. `standalone.config.ranking.json` - 排行榜下载示例
+**推荐用于：** 主要下载排行榜作品
+
+- ✅ 包含各种排行榜模式的示例
+- ✅ 日榜、周榜、月榜配置示例
+- ✅ 男性向、女性向、AI作品排行榜示例
+- ✅ 排行榜筛选标签的配置方法
+
+**使用方法：**
+```bash
+cp config/examples/standalone.config.ranking.json config/standalone.config.json
+# 修改 refreshToken
+# 根据需要修改 targets 数组
+```
+
+**支持的排行榜类型：**
+- `day` - 日榜
+- `week` - 周榜
+- `month` - 月榜
+- `day_male` - 男性向日榜
+- `day_female` - 女性向日榜
+- `day_ai` - AI作品日榜
+- `week_original` - 原创周榜
+- `week_rookie` - 新人周榜
+- `day_r18` - R18日榜
+- `day_male_r18` - 男性向R18日榜
+- `day_female_r18` - 女性向R18日榜
+
+---
+
+### 4. `specific-download.example.json` - 特定下载任务示例
+**推荐用于：** 需要实现特定下载场景
+
+- ✅ 包含10个实际使用场景的配置示例
+- ✅ 随机下载、质量过滤、时间范围等场景
+- ✅ 小说系列下载、单作品下载示例
+- ✅ 语言过滤、多标签OR关系等高级用法
+
+**使用方法：**
+```bash
+cp config/examples/specific-download.example.json config/standalone.config.json
+# 修改 refreshToken
+# 根据需要选择或修改 targets 中的场景
+```
+
+**包含的场景：**
+1. 随机下载 - 测试或获取随机作品
+2. 排行榜筛选 - 从排行榜中筛选特定标签
+3. 质量过滤 - 只下载高收藏数作品
+4. 时间范围 - 下载指定时间段的作品
+5. 多标签OR - 包含任意一个标签即可
+6. 系列下载 - 下载整个小说系列
+7. 单作品下载 - 下载指定ID的小说
+8. 语言过滤 - 只下载中文小说
+9. 特殊排行榜 - 原创周榜
+10. 特殊排行榜 - 新人周榜
+
+---
+
+### 5. `standalone.config.novel-chinese.json` - 中文小说下载示例
+**推荐用于：** 主要下载中文小说
+
+- ✅ 包含中文小说下载的各种配置示例
+- ✅ 语言过滤配置（仅中文、非中文、不过滤）
+- ✅ 时间范围过滤示例
+- ✅ 按热门程度或日期排序
+
+**使用方法：**
+```bash
+cp config/examples/standalone.config.novel-chinese.json config/standalone.config.json
+# 修改 refreshToken
+# 根据需要修改 targets 数组中的标签
+```
+
+**语言过滤选项：**
+- `chinese` - 仅下载中文小说
+- `non-chinese` - 仅下载非中文小说（日语、英语等）
+- `null` 或不设置 - 下载所有语言的小说
+
+**时间范围占位符：**
+- `LAST_7_DAYS` - 最近7天（程序自动计算日期）
+- `YESTERDAY` - 昨天
+
+---
+
+## 🚀 快速使用示例
+
+以下示例文件可以直接使用，无需复制到根目录：
+
+### `yesterday-popular-novel.zh.json` - 昨日热门中文小说
+**功能：** 下载昨日热门中文小说 Top 10
+
+- 搜索模式 + `popular_desc` 排序 + `YESTERDAY` 日期
+- 标签：`オリジナル`（通用原创标签）
+- 语言过滤：仅中文
+
+**使用方法：**
+```bash
+# 方式 1：命令行参数
+pixivflow download --config "$(pwd)/config/examples/yesterday-popular-novel.zh.json"
+
+# 方式 2：环境变量
+export PIXIV_DOWNLOADER_CONFIG="$(pwd)/config/examples/yesterday-popular-novel.zh.json"
+pixivflow download
+```
+
+---
+
+### `yesterday-ranking-illustration.json` - 昨日日榜插画
+**功能：** 下载昨日日榜插画 Top 10
+
+- 排行榜模式
+- 不依赖标签，直接按 Pixiv 日榜抓取
+
+**使用方法：**
+```bash
+pixivflow download --config "$(pwd)/config/examples/yesterday-ranking-illustration.json"
+```
+
+---
+
+### `multi-tag-or-limit.zh.json` - 多标签并集 + 中文过滤
+**功能：** 多标签并集（任意一个标签即可）+ 总量限制 10 + 中文过滤 + 昨天
+
+- 标签：`風景 イラスト オリジナル`（通用常见标签）
+- `tagRelation: "or"` - 任意一个标签命中即可
+- 语言过滤：仅中文
+- 日期：昨天
+
+**使用方法：**
+```bash
+pixivflow download --config "$(pwd)/config/examples/multi-tag-or-limit.zh.json"
+```
+
+---
+
+## 💡 使用提示
+
+### 直接使用示例文件
+
+所有示例文件都可以直接使用，无需复制：
+
+```bash
+# 使用命令行参数
+pixivflow download --config "$(pwd)/config/examples/yesterday-popular-novel.zh.json"
+
+# 或使用环境变量（对所有命令生效）
+export PIXIV_DOWNLOADER_CONFIG="$(pwd)/config/examples/yesterday-popular-novel.zh.json"
+pixivflow download
+```
+
+### 登录并写入配置
+
+如果示例文件中的 `YOUR_REFRESH_TOKEN` 还未替换，可以运行：
+
+```bash
+# 登录并自动写入 refresh token 到指定配置文件
+pixivflow login --config "$(pwd)/config/examples/yesterday-popular-novel.zh.json"
+```
+
+该命令会把登录获取的 refresh token 自动写入对应配置文件。
+
+---
+
+## ⚠️ 注意事项
+
+1. **所有示例文件中的 `YOUR_REFRESH_TOKEN` 都需要替换为实际值**
+2. **或使用 `pixivflow login --config <配置文件路径>` 自动填充**
+3. **配置文件使用 JSON 格式，注意语法正确性**
+4. **修改配置后建议先测试少量下载，确认配置正确**
+
+---
+
+## 📚 更多信息
+
+- 配置文件说明：查看 [../README.md](../README.md)
+- 详细配置说明：查看 `docs/CONFIG.md`
+- 项目文档：查看 `docs/` 目录

package/config/examples/multi-tag-or-limit.zh.json

@@ -0,0 +1,49 @@
+{
+  "logLevel": "info",
+  "pixiv": {
+    "clientId": "MOBrBDS8blbauoSck0ZfDbtuzpyT",
+    "clientSecret": "lsACyCD94FhDUtGTXi3QzcFE2uU1hqtDaKeqrdwj",
+    "deviceToken": "pixiv",
+    "refreshToken": "YOUR_REFRESH_TOKEN",
+    "userAgent": "PixivAndroidApp/5.0.234 (Android 11; Pixel 6)"
+  },
+  "network": {
+    "timeoutMs": 30000,
+    "retries": 3,
+    "retryDelay": 1000
+  },
+  "storage": {
+    "databasePath": "./data/pixiv-downloader.db",
+    "downloadDirectory": "./downloads"
+  },
+  "scheduler": {
+    "enabled": false,
+    "cron": "0 3 * * *",
+    "timezone": "Asia/Shanghai"
+  },
+  "download": {
+    "concurrency": 3,
+    "requestDelay": 500,
+    "dynamicConcurrency": true,
+    "minConcurrency": 1,
+    "maxRetries": 3,
+    "retryDelay": 2000,
+    "timeout": 60000
+  },
+  "targets": [
+    {
+      "type": "novel",
+      "mode": "search",
+      "tag": "風景 イラスト オリジナル",
+      "tagRelation": "or",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "limit": 10,
+      "startDate": "YESTERDAY",
+      "endDate": "YESTERDAY",
+      "languageFilter": "chinese",
+      "detectLanguage": true
+    }
+  ],
+  "initialDelay": 0
+}

package/config/examples/specific-download.example.json

@@ -0,0 +1,173 @@
+{
+  "_comment": "PixivFlow 特定下载任务配置示例",
+  "_note": "此配置文件展示了各种实际使用场景的配置方法",
+  "_usage": "使用方法：",
+  "_usage1": "  1. 复制此文件: cp config/specific-download.example.json config/standalone.config.json",
+  "_usage2": "  2. 修改 refreshToken（如果还没有登录，先运行: pixivflow login）",
+  "_usage3": "  3. 根据需要修改 targets 数组中的配置",
+  "_usage4": "  4. 运行下载: pixivflow download",
+  "_principle": "核心理念：所有任务都通过配置文件实现，无需修改源代码！",
+  
+  "logLevel": "info",
+  "pixiv": {
+    "clientId": "MOBrBDS8blbauoSck0ZfDbtuzpyT",
+    "clientSecret": "lsACyCD94FhDUtGTXi3QzcFE2uU1hqtDaKeqrdwj",
+    "deviceToken": "pixiv",
+    "refreshToken": "YOUR_REFRESH_TOKEN",
+    "userAgent": "PixivAndroidApp/5.0.234 (Android 11; Pixel 6)"
+  },
+  "network": {
+    "timeoutMs": 30000,
+    "retries": 3,
+    "retryDelay": 1000,
+    "proxy": {
+      "enabled": false,
+      "host": "127.0.0.1",
+      "port": 7890,
+      "protocol": "http",
+      "username": "",
+      "password": ""
+    }
+  },
+  "storage": {
+    "databasePath": "./data/pixiv-downloader.db",
+    "downloadDirectory": "./downloads",
+    "illustrationDirectory": "./downloads/illustrations",
+    "novelDirectory": "./downloads/novels",
+    "illustrationOrganization": "byDownloadDate",
+    "novelOrganization": "byDownloadDate"
+  },
+  "scheduler": {
+    "enabled": false
+  },
+  "download": {
+    "concurrency": 3,
+    "requestDelay": 500,
+    "dynamicConcurrency": true,
+    "minConcurrency": 1,
+    "maxRetries": 3,
+    "retryDelay": 2000,
+    "timeout": 60000
+  },
+  "targets": [
+    {
+      "_comment": "场景1: 下载一张随机的原神图片",
+      "type": "illustration",
+      "tag": "原神",
+      "limit": 1,
+      "searchTarget": "partial_match_for_tags",
+      "restrict": "public",
+      "mode": "search",
+      "random": true
+    },
+    {
+      "_comment": "场景2: 下载昨天排名最高的明日方舟相关作品",
+      "type": "illustration",
+      "tag": "アークナイツ",
+      "limit": 10,
+      "mode": "ranking",
+      "rankingMode": "day",
+      "rankingDate": "YESTERDAY",
+      "filterTag": "アークナイツ"
+    },
+    {
+      "_comment": "场景3: 下载收藏数超过500的風景插画，按热门程度排序",
+      "type": "illustration",
+      "tag": "風景",
+      "limit": 30,
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "minBookmarks": 500,
+      "mode": "search"
+    },
+    {
+      "_comment": "场景4: 下载2024年1月发布的原神插画",
+      "type": "illustration",
+      "tag": "原神",
+      "limit": 50,
+      "searchTarget": "partial_match_for_tags",
+      "mode": "search",
+      "startDate": "2024-01-01",
+      "endDate": "2024-01-31"
+    },
+    {
+      "_comment": "场景5: 下载包含'原神'或'Genshin'标签的插画（OR关系）",
+      "type": "illustration",
+      "tag": "原神 Genshin",
+      "tagRelation": "or",
+      "limit": 20,
+      "searchTarget": "partial_match_for_tags",
+      "mode": "search"
+    },
+    {
+      "_comment": "场景6: 下载指定小说系列的所有作品",
+      "type": "novel",
+      "tag": "series",
+      "seriesId": 14690617,
+      "_seriesId_note": "从URL https://www.pixiv.net/novel/series/14690617 中获取系列ID",
+      "limit": null
+    },
+    {
+      "_comment": "场景7: 下载单个小说",
+      "type": "novel",
+      "tag": "single",
+      "novelId": 26132156,
+      "_novelId_note": "从URL https://www.pixiv.net/novel/show.php?id=26132156 中获取小说ID"
+    },
+    {
+      "_comment": "场景8: 下载中文小说",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 20,
+      "searchTarget": "partial_match_for_tags",
+      "mode": "search",
+      "languageFilter": "chinese",
+      "detectLanguage": true
+    },
+    {
+      "_comment": "场景9: 下载本周原创周榜前50名",
+      "type": "illustration",
+      "tag": "week-original",
+      "limit": 50,
+      "mode": "ranking",
+      "rankingMode": "week_original"
+    },
+    {
+      "_comment": "场景10: 下载新人周榜前30名",
+      "type": "illustration",
+      "tag": "week-rookie",
+      "limit": 30,
+      "mode": "ranking",
+      "rankingMode": "week_rookie"
+    },
+    {
+      "_comment": "场景11: 下载单个插画",
+      "type": "illustration",
+      "tag": "single",
+      "illustId": 12345678,
+      "_illustId_note": "从URL https://www.pixiv.net/artworks/12345678 中获取插画ID"
+    },
+    {
+      "_comment": "场景12: 下载用户的所有作品",
+      "type": "illustration",
+      "tag": "user",
+      "userId": "123456",
+      "limit": 100,
+      "_userId_note": "从URL https://www.pixiv.net/users/123456 中获取用户ID，下载该用户的所有插画（最多100个）"
+    }
+  ],
+  "_场景说明": {
+    "场景1": "随机下载 - 适合测试或获取随机作品",
+    "场景2": "排行榜筛选 - 从排行榜中筛选特定标签",
+    "场景3": "质量过滤 - 只下载高收藏数作品",
+    "场景4": "时间范围 - 下载指定时间段的作品",
+    "场景5": "多标签OR - 包含任意一个标签即可",
+    "场景6": "系列下载 - 下载整个小说系列",
+    "场景7": "单作品下载 - 下载指定ID的小说",
+    "场景8": "语言过滤 - 只下载中文小说",
+    "场景9": "特殊排行榜 - 原创周榜",
+    "场景10": "特殊排行榜 - 新人周榜",
+    "场景11": "单插画下载 - 下载指定ID的插画",
+    "场景12": "用户作品下载 - 下载指定用户的所有作品"
+  }
+}