pixivflow 2.16.1 → 2.18.0

package/config/examples/standalone.config.example.json

@@ -0,0 +1,167 @@
+{
+  "_comment": "PixivFlow 完整配置示例 - 包含所有可用选项和详细说明",
+  "_usage": "使用方法：复制此文件为 standalone.config.json 并修改 refreshToken",
+  "_note": "所有以 _ 开头的字段都是注释说明，不会影响程序运行",
+  
+  "logLevel": "info",
+  "_logLevel_note": "日志级别: debug（详细）| info（信息）| warn（警告）| error（错误）",
+  
+  "pixiv": {
+    "_comment": "Pixiv API 认证配置（必需）",
+    "clientId": "MOBrBDS8blbauoSck0ZfDbtuzpyT",
+    "clientSecret": "lsACyCD94FhDUtGTXi3QzcFE2uU1hqtDaKeqrdwj",
+    "deviceToken": "pixiv",
+    "refreshToken": "YOUR_REFRESH_TOKEN",
+    "_refreshToken_note": "重要：请将 YOUR_REFRESH_TOKEN 替换为您的实际 refresh token。运行 pixivflow login 可自动获取",
+    "userAgent": "PixivAndroidApp/5.0.234 (Android 11; Pixel 6)"
+  },
+  
+  "network": {
+    "_comment": "网络配置（可选，有默认值）",
+    "timeoutMs": 30000,
+    "_timeoutMs_note": "请求超时时间（毫秒），默认 30000（30秒）",
+    "retries": 3,
+    "_retries_note": "失败重试次数，默认 3",
+    "retryDelay": 1000,
+    "_retryDelay_note": "重试延迟（毫秒），默认 1000（1秒）",
+    "proxy": {
+      "_comment": "代理配置（可选，如需使用代理请启用）",
+      "enabled": false,
+      "host": "127.0.0.1",
+      "port": 7890,
+      "protocol": "http",
+      "_protocol_note": "支持: http | https | socks4 | socks5",
+      "username": "",
+      "password": ""
+    }
+  },
+  
+  "storage": {
+    "_comment": "存储配置（可选，有默认值）",
+    "databasePath": "./data/pixiv-downloader.db",
+    "_databasePath_note": "SQLite 数据库文件路径，用于记录下载历史",
+    "downloadDirectory": "./downloads",
+    "_downloadDirectory_note": "下载根目录",
+    "illustrationDirectory": "./downloads/illustrations",
+    "_illustrationDirectory_note": "插画保存目录（相对于 downloadDirectory 或绝对路径）",
+    "novelDirectory": "./downloads/novels",
+    "_novelDirectory_note": "小说保存目录（相对于 downloadDirectory 或绝对路径）",
+    "illustrationOrganization": "byDownloadDate",
+    "_illustrationOrganization_note": "插画目录组织方式: flat（扁平）| byAuthor（按作者）| byTag（按标签）| byDate（按作品创建日期-月份）| byDay（按作品创建日期-天）| byDownloadDate（按下载日期-月份，推荐）| byDownloadDay（按下载日期-天）| byAuthorAndTag（按作者和标签）| byDateAndAuthor（按作品创建日期和作者）| byDownloadDateAndAuthor（按下载日期和作者）",
+    "novelOrganization": "byDownloadDate",
+    "_novelOrganization_note": "小说目录组织方式，选项同 illustrationOrganization"
+  },
+  
+  "scheduler": {
+    "_comment": "定时任务配置（可选）",
+    "enabled": false,
+    "_enabled_note": "是否启用定时任务，默认 false",
+    "cron": "0 3 * * *",
+    "_cron_note": "Cron 表达式，默认每天凌晨3点执行。示例：'0 */6 * * *' 表示每6小时执行一次",
+    "timezone": "Asia/Shanghai",
+    "_timezone_note": "时区，默认 Asia/Shanghai",
+    "maxExecutions": null,
+    "_maxExecutions_note": "最大执行次数，null 表示无限制",
+    "minInterval": null,
+    "_minInterval_note": "最小执行间隔（毫秒），null 表示无限制",
+    "timeout": null,
+    "_timeout_note": "单次任务超时时间（毫秒），null 表示无超时",
+    "maxConsecutiveFailures": null,
+    "_maxConsecutiveFailures_note": "最大连续失败次数，超过后停止调度器，null 表示无限制",
+    "failureRetryDelay": null,
+    "_failureRetryDelay_note": "失败后重试延迟（毫秒），null 表示无延迟"
+  },
+  
+  "download": {
+    "_comment": "下载配置（可选，有默认值）",
+    "concurrency": 3,
+    "_concurrency_note": "最大并发下载数，默认 3，建议范围 1-10。数值越大下载越快，但可能触发速率限制",
+    "requestDelay": 500,
+    "_requestDelay_note": "API 请求之间的最小延迟（毫秒），用于避免速率限制，默认 500（0.5秒）",
+    "dynamicConcurrency": true,
+    "_dynamicConcurrency_note": "是否启用动态并发调整。当检测到速率限制（429错误）时，自动降低并发数，默认 true（推荐）",
+    "minConcurrency": 1,
+    "_minConcurrency_note": "动态调整时的最小并发数，不会低于此值，默认 1",
+    "maxRetries": 3,
+    "_maxRetries_note": "每个下载的最大重试次数，默认 3",
+    "retryDelay": 2000,
+    "_retryDelay_note": "重试延迟（毫秒），默认 2000（2秒）",
+    "timeout": 60000,
+    "_timeout_note": "下载超时时间（毫秒），默认 60000（60秒）"
+  },
+  
+  "targets": [
+    {
+      "_comment": "下载目标配置（必需，至少一个）",
+      "_example1": "示例1: 搜索模式 - 下载包含指定标签的插画",
+      "type": "illustration",
+      "_type_note": "类型: illustration（插画）| novel（小说）",
+      "tag": "風景",
+      "_tag_note": "搜索标签，必填。多个标签用空格分隔，如：'原神 風景'",
+      "tagRelation": "and",
+      "_tagRelation_note": "标签关系: and（默认，必须同时包含所有标签）| or（包含任意一个标签即可）",
+      "limit": 20,
+      "_limit_note": "每次运行下载数量限制，建议范围 1-1000",
+      "searchTarget": "partial_match_for_tags",
+      "_searchTarget_note": "搜索模式: partial_match_for_tags（部分匹配，推荐）| exact_match_for_tags（精确匹配）| title_and_caption（标题和说明）",
+      "sort": "date_desc",
+      "_sort_note": "排序方式: date_desc（按日期降序，最新优先）| date_asc（按日期升序）| popular_desc（按收藏数降序，最热门优先）",
+      "restrict": "public",
+      "_restrict_note": "限制: public（公开）| private（私有）",
+      "mode": "search",
+      "_mode_note": "下载模式: search（搜索，默认）| ranking（排行榜）",
+      "minBookmarks": 100,
+      "_minBookmarks_note": "可选，最小收藏数过滤，只下载收藏数大于等于此值的作品",
+      "startDate": null,
+      "_startDate_note": "可选，开始日期过滤（YYYY-MM-DD 格式），只下载此日期之后的作品",
+      "endDate": null,
+      "_endDate_note": "可选，结束日期过滤（YYYY-MM-DD 格式），只下载此日期之前的作品",
+      "random": false,
+      "_random_note": "是否随机选择，true 表示从搜索结果中随机选择"
+    },
+    {
+      "_example2": "示例2: 排行榜模式 - 下载今日排行榜作品",
+      "type": "illustration",
+      "tag": "ranking",
+      "limit": 50,
+      "mode": "ranking",
+      "rankingMode": "day",
+      "_rankingMode_note": "排行榜模式: 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日榜）",
+      "rankingDate": null,
+      "_rankingDate_note": "排行榜日期（YYYY-MM-DD 格式），null 表示今天，也可使用 'YESTERDAY' 占位符",
+      "filterTag": null,
+      "_filterTag_note": "过滤标签（可选），从排名结果中筛选包含此标签的作品，null 表示不过滤"
+    },
+    {
+      "_example3": "示例3: 小说下载 - 下载指定标签的小说",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 10,
+      "searchTarget": "partial_match_for_tags",
+      "mode": "search",
+      "languageFilter": null,
+      "_languageFilter_note": "语言过滤: chinese（仅中文）| non-chinese（非中文）| null（不过滤）",
+      "detectLanguage": true,
+      "_detectLanguage_note": "是否启用语言检测和记录，默认 true"
+    },
+    {
+      "_example4": "示例4: 下载指定小说系列",
+      "type": "novel",
+      "tag": "series",
+      "seriesId": 14690617,
+      "_seriesId_note": "小说系列ID，从URL https://www.pixiv.net/novel/series/14690617 中获取",
+      "limit": null,
+      "_limit_note": "系列下载时 limit 通常设为 null（下载全部）"
+    },
+    {
+      "_example5": "示例5: 下载单个小说",
+      "type": "novel",
+      "tag": "single",
+      "novelId": 26132156,
+      "_novelId_note": "小说ID，从URL https://www.pixiv.net/novel/show.php?id=26132156 中获取"
+    }
+  ],
+  
+  "initialDelay": 0,
+  "_initialDelay_note": "启动延迟（毫秒），用于测试或延迟启动，默认 0"
+}

package/config/examples/standalone.config.novel-chinese.json

@@ -0,0 +1,124 @@
+{
+  "_comment": "PixivFlow 中文小说下载配置示例",
+  "_usage": "使用方法：",
+  "_usage1": "  1. 复制此文件: cp config/standalone.config.novel-chinese.json config/standalone.config.json",
+  "_usage2": "  2. 修改 refreshToken（运行 pixivflow login 获取）",
+  "_usage3": "  3. 根据需要修改 targets 数组中的标签",
+  "_usage4": "  4. 运行下载: pixivflow download",
+  
+  "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": 2,
+    "requestDelay": 1000,
+    "dynamicConcurrency": true,
+    "minConcurrency": 1,
+    "maxRetries": 3,
+    "retryDelay": 2000,
+    "timeout": 60000
+  },
+  "targets": [
+    {
+      "_comment": "示例1: 下载包含'オリジナル'标签的中文小说，按热门程度排序",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 20,
+      "mode": "search",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "languageFilter": "chinese",
+      "detectLanguage": true
+    },
+    {
+      "_comment": "示例2: 下载最近7天发布的中文小说（使用时间范围过滤）",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 30,
+      "mode": "search",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "date_desc",
+      "startDate": "LAST_7_DAYS",
+      "_startDate_note": "使用 'LAST_7_DAYS' 占位符表示最近7天，程序会自动计算日期",
+      "endDate": "YESTERDAY",
+      "_endDate_note": "使用 'YESTERDAY' 占位符表示昨天",
+      "languageFilter": "chinese",
+      "detectLanguage": true
+    },
+    {
+      "_comment": "示例3: 下载指定日期范围内的中文小说",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 50,
+      "mode": "search",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "startDate": "2024-01-01",
+      "_startDate_note": "指定开始日期（YYYY-MM-DD 格式）",
+      "endDate": "2024-01-31",
+      "_endDate_note": "指定结束日期（YYYY-MM-DD 格式）",
+      "languageFilter": "chinese",
+      "detectLanguage": true
+    },
+    {
+      "_comment": "示例4: 下载非中文小说（日语、英语等）",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 20,
+      "mode": "search",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "languageFilter": "non-chinese",
+      "detectLanguage": true
+    },
+    {
+      "_comment": "示例5: 下载所有语言的小说（不过滤语言）",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 20,
+      "mode": "search",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "detectLanguage": true,
+      "_note": "不设置 languageFilter 或设为 null 表示不过滤语言"
+    }
+  ],
+  "_说明": {
+    "languageFilter": "语言过滤选项: chinese（仅中文）| non-chinese（非中文）| null（不过滤，下载所有语言）",
+    "detectLanguage": "是否启用语言检测和记录，默认 true。启用后会在日志中显示检测到的语言",
+    "startDate": "开始日期过滤，格式：YYYY-MM-DD 或使用占位符 'LAST_7_DAYS'（最近7天）",
+    "endDate": "结束日期过滤，格式：YYYY-MM-DD 或使用占位符 'YESTERDAY'（昨天）",
+    "sort": "排序方式: popular_desc（按收藏数降序，最热门优先）| date_desc（按日期降序，最新优先）| date_asc（按日期升序）",
+    "limit": "下载数量限制",
+    "tag": "搜索标签，可以修改为你感兴趣的标签"
+  }
+}

package/config/examples/standalone.config.ranking.json

@@ -0,0 +1,135 @@
+{
+  "_comment": "PixivFlow 排行榜下载配置示例",
+  "_usage": "使用方法：",
+  "_usage1": "  1. 复制此文件: cp config/standalone.config.ranking.json config/standalone.config.json",
+  "_usage2": "  2. 修改 refreshToken（运行 pixivflow login 获取）",
+  "_usage3": "  3. 根据需要修改 targets 数组中的配置",
+  "_usage4": "  4. 运行下载: pixivflow download",
+  
+  "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",
+    "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: 下载今日日榜前50名（不筛选标签）",
+      "type": "illustration",
+      "tag": "ranking-day",
+      "limit": 50,
+      "mode": "ranking",
+      "rankingMode": "day"
+    },
+    {
+      "_comment": "示例2: 从今日日榜中筛选包含'風景'标签的作品，下载前20个",
+      "type": "illustration",
+      "tag": "風景",
+      "limit": 20,
+      "mode": "ranking",
+      "rankingMode": "day",
+      "filterTag": "風景"
+    },
+    {
+      "_comment": "示例3: 下载昨日日榜前30名",
+      "type": "illustration",
+      "tag": "ranking-yesterday",
+      "limit": 30,
+      "mode": "ranking",
+      "rankingMode": "day",
+      "rankingDate": "YESTERDAY"
+    },
+    {
+      "_comment": "示例4: 下载本周周榜前100名",
+      "type": "illustration",
+      "tag": "ranking-week",
+      "limit": 100,
+      "mode": "ranking",
+      "rankingMode": "week"
+    },
+    {
+      "_comment": "示例5: 下载男性向日榜前30名",
+      "type": "illustration",
+      "tag": "ranking-male",
+      "limit": 30,
+      "mode": "ranking",
+      "rankingMode": "day_male"
+    },
+    {
+      "_comment": "示例6: 下载女性向日榜前30名",
+      "type": "illustration",
+      "tag": "ranking-female",
+      "limit": 30,
+      "mode": "ranking",
+      "rankingMode": "day_female"
+    },
+    {
+      "_comment": "示例7: 下载AI作品日榜前50名",
+      "type": "illustration",
+      "tag": "ranking-ai",
+      "limit": 50,
+      "mode": "ranking",
+      "rankingMode": "day_ai"
+    },
+    {
+      "_comment": "示例8: 下载原创周榜前50名",
+      "type": "illustration",
+      "tag": "ranking-original",
+      "limit": 50,
+      "mode": "ranking",
+      "rankingMode": "week_original"
+    },
+    {
+      "_comment": "示例9: 下载新人周榜前30名",
+      "type": "illustration",
+      "tag": "ranking-rookie",
+      "limit": 30,
+      "mode": "ranking",
+      "rankingMode": "week_rookie"
+    },
+    {
+      "_comment": "示例10: 从本周周榜中筛选包含'オリジナル'标签的小说，下载前10个",
+      "type": "novel",
+      "tag": "オリジナル",
+      "limit": 10,
+      "mode": "ranking",
+      "rankingMode": "week",
+      "filterTag": "オリジナル"
+    }
+  ],
+  "_说明": {
+    "mode": "ranking - 使用排行榜模式下载（可选：search - 搜索模式，默认）",
+    "rankingMode": "排行榜类型: 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日榜）",
+    "rankingDate": "排行榜日期，格式：YYYY-MM-DD（如 '2024-01-15'），或使用 'YESTERDAY' 占位符表示昨天，不填则使用今天",
+    "filterTag": "可选，从排名结果中筛选包含此标签的作品。不填则下载排名中的所有作品",
+    "limit": "最终下载的数量限制",
+    "tag": "用于日志记录和文件组织的标签名称，可以自定义"
+  }
+}

package/config/examples/standalone.config.simple.json

@@ -0,0 +1,52 @@
+{
+  "_comment": "PixivFlow 简化配置 - 快速开始使用",
+  "_usage": "使用方法：",
+  "_usage1": "  1. 运行 pixivflow login 获取 refreshToken",
+  "_usage2": "  2. 将下面的 YOUR_REFRESH_TOKEN 替换为登录后获取的 token",
+  "_usage3": "  3. 根据需要修改 targets 数组中的标签和数量",
+  "_usage4": "  4. 运行 pixivflow download 开始下载",
+  
+  "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",
+    "illustrationDirectory": "./downloads/illustrations",
+    "novelDirectory": "./downloads/novels",
+    "illustrationOrganization": "byDownloadDate",
+    "novelOrganization": "byDownloadDate"
+  },
+  "scheduler": {
+    "enabled": false
+  },
+  "targets": [
+    {
+      "_comment": "示例：下载包含'風景'标签的插画，每次下载20张",
+      "type": "illustration",
+      "tag": "風景",
+      "limit": 20,
+      "searchTarget": "partial_match_for_tags",
+      "sort": "date_desc"
+    }
+  ],
+  "download": {
+    "concurrency": 3,
+    "requestDelay": 500,
+    "dynamicConcurrency": true,
+    "minConcurrency": 1,
+    "maxRetries": 3,
+    "retryDelay": 2000,
+    "timeout": 60000
+  }
+}

package/config/examples/yesterday-popular-novel.zh.json

@@ -0,0 +1,48 @@
+{
+  "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": "オリジナル",
+      "searchTarget": "partial_match_for_tags",
+      "sort": "popular_desc",
+      "limit": 10,
+      "startDate": "YESTERDAY",
+      "endDate": "YESTERDAY",
+      "languageFilter": "chinese",
+      "detectLanguage": true
+    }
+  ],
+  "initialDelay": 0
+}

package/config/examples/yesterday-ranking-illustration.json

@@ -0,0 +1,43 @@
+{
+  "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": "illustration",
+      "mode": "ranking",
+      "rankingMode": "day",
+      "rankingDate": "YESTERDAY",
+      "limit": 10
+    }
+  ],
+  "initialDelay": 0
+}

package/dist/auth/PixivAuth.d.ts

@@ -1,5 +1,17 @@
 import { NetworkConfig, PixivCredentialConfig } from '../config';
 import { Database } from '../storage/Database';
+/**
+ * Read-only auth: never exchange a refresh token, never persist one.
+ *
+ * Two processes can share one refresh token, but Pixiv's rotation behaviour on
+ * `grant_type=refresh_token` is a server detail a client cannot prove. If it
+ * rotates, a second process that refreshes can invalidate the first one's token —
+ * and a long-running daemon never re-reads the token from disk, so it cannot
+ * recover without a restart. In this mode the only accepted credential is an
+ * access token already present in the local cache; anything else fails loudly
+ * instead of silently rotating a credential someone else is using.
+ */
+export declare function isAuthReadOnly(): boolean;
 export declare class PixivAuth {
     private readonly credentials;
     private readonly network;

package/dist/auth/PixivAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PixivAuth.d.ts","sourceRoot":"","sources":["../../src/auth/PixivAuth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAoB,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAmBjE,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGT,WAAW,EAAE,qBAAqB,EAClC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,QAAQ,EACnC,UAAU,CAAC,EAAE,MAAM;IAKR,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAU9C;;;OAGG;IACG,2BAA2B,IAAI,OAAO,CAAC,MAAM,CAAC;YAKtC,kBAAkB;IA2IhC,OAAO,CAAC,kBAAkB;CAI3B"}
+{"version":3,"file":"PixivAuth.d.ts","sourceRoot":"","sources":["../../src/auth/PixivAuth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAoB,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAmBjE;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAGxC;AAED,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGT,WAAW,EAAE,qBAAqB,EAClC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,QAAQ,EACnC,UAAU,CAAC,EAAE,MAAM;IAKR,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAiB9C;;;OAGG;IACG,2BAA2B,IAAI,OAAO,CAAC,MAAM,CAAC;YAKtC,kBAAkB;IAoJhC,OAAO,CAAC,kBAAkB;CAI3B"}

package/dist/auth/PixivAuth.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PixivAuth = void 0;
+exports.isAuthReadOnly = isAuthReadOnly;
 const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:timers/promises");
 const logger_1 = require("../logger");
@@ -41,6 +42,21 @@ const login_helper_1 = require("../utils/login-helper");
 const errors_1 = require("../utils/errors");
 const TOKEN_CACHE_KEY = 'pixiv_access_token';
 const REFRESH_TOKEN_CACHE_KEY = 'pixiv_refresh_token';
+/**
+ * Read-only auth: never exchange a refresh token, never persist one.
+ *
+ * Two processes can share one refresh token, but Pixiv's rotation behaviour on
+ * `grant_type=refresh_token` is a server detail a client cannot prove. If it
+ * rotates, a second process that refreshes can invalidate the first one's token —
+ * and a long-running daemon never re-reads the token from disk, so it cannot
+ * recover without a restart. In this mode the only accepted credential is an
+ * access token already present in the local cache; anything else fails loudly
+ * instead of silently rotating a credential someone else is using.
+ */
+function isAuthReadOnly() {
+    const value = process.env.PIXIV_AUTH_READONLY?.trim().toLowerCase();
+    return value === '1' || value === 'true' || value === 'yes';
+}
 class PixivAuth {
     credentials;
     network;
@@ -57,6 +73,10 @@ class PixivAuth {
         if (cached && cached.accessToken && cached.expiresAt > Date.now() + 60_000) {
             return cached.accessToken;
         }
+        if (isAuthReadOnly()) {
+            throw new errors_1.AuthenticationError('Read-only auth (PIXIV_AUTH_READONLY) refuses to refresh: no usable access token is cached. ' +
+                'Seed the access-token cache with a token that is still valid, or run with its own credential.');
+        }
         const refreshed = await this.refreshAccessToken();
         return refreshed.accessToken;
     }
@@ -69,6 +89,12 @@ class PixivAuth {
         return stored.accessToken;
     }
     async refreshAccessToken() {
+        // Single guard for every refresh caller: the persistence block below writes a
+        // rotated token to the database, a file and the config, in this process only.
+        if (isAuthReadOnly()) {
+            throw new errors_1.AuthenticationError('Read-only auth (PIXIV_AUTH_READONLY) must never call the token endpoint: ' +
+                'refreshing may rotate a refresh token another process is using.');
+        }
         const url = 'https://oauth.secure.pixiv.net/auth/token';
         let lastError;
         for (let attempt = 0; attempt < (this.network.retries ?? 3); attempt++) {