feat: add doujinshi PDF/ZIP delivery and recoverable revocation (v2.2.0)

AGENTS.md

@@ -8,14 +8,14 @@
 
 ## 项目形态
 
-- 这是一个 AstrBot 随机图片插件，采用 DDD 分层。
+- 这是一个 AstrBot 随机图片与随机本子文件插件，采用 DDD 分层。
 - 管理功能属于 Plugin Pages（统一 dashboard 页面，含会话配置和访问控制标签页）。
 
 主要目录：
 
 - `src/domain/`: 领域实体、值对象、标签解析、访问控制。
 - `src/application/`: 用例、DTO、端口接口、会话配置服务。
-- `src/infrastructure/`: 配置、持久化、provider、sender、AstrBot 适配。
+- `src/infrastructure/`: 配置、持久化、provider、随机本子文件、sender、AstrBot 适配。
 - `src/shared/`: 配置模型、日志、发送缓存。
 - `pages/`: Plugin Pages 前端（统一 dashboard）。
 - `templates/`: 运势卡片 HTML 模板与字体。
@@ -35,6 +35,9 @@
 - 插件运行数据必须通过 `StarTools.get_data_dir(self.name)` 获取，不要硬编码路径。
 - 从插件目录本地调试时，不要创建或使用 `<plugin>/data` 作为运行态目录。
 - 所有用户可见提示必须走 `MessagesConfig` / `resolve_message()`，不要在 handler 内硬编码提示文案。
+- 随机本子由 `infrastructure/doujinshi/` 按配置生成 PDF 或 ZIP；所有平台统一发送普通 `File`，不再包装 `Nodes` 合并转发。OneBot/NapCat 若启用自动撤回，则在发送普通文件时取得消息 ID 并进入统一可恢复撤回队列。
+- 色图与随机本子都必须使用 `application/setu/tag_resolution.py` 解析标签，保持分隔符和别名映射语义一致。
+- `delivery.doujinshi_send_mode` 选择本子文件格式（`pdf` 或 `archive`，默认 `pdf`）；`delivery.auto_revoke_targets` 以单一列表选择色图、今日运势和本子是否进入自动清理，三者共用 `auto_revoke_delay`。OneBot/NapCat 本子普通文件发送若启用自动撤回，必须在发送时取得并立即持久化 `message_id`，避免异步上传可见性导致清理状态丢失。
 - 其他领域值、平台行为和配置边界不要写进本文件，放到 `docs/project/` 或 `docs/dev/`。
 
 ## 文档纪律

CHANGELOG.md

@@ -1,10 +1,29 @@
 # Changelog
 
+## [2.2.0] - 2026-08-14
+
+### Added
+
+- **随机本子文件**：新增 `/随机本子`（`/本子`、`/doujinshi`）命令；调用 Atri 随机本子 API，下载全部页图并支持 PDF/ZIP 两种生成模式。
+- **本子自然语言入口**：支持发送“来份本子”或“来一份本子”触发随机本子。
+- **本子文件发送策略**：新增 `delivery.doujinshi_send_mode`（`pdf`/`archive`）；两种模式在所有平台均直接发送普通 `File`，取消本子合并转发及标题/原始地址节点。
+- **本子文件名与撤回**：PDF/ZIP 使用 API 返回的本子标题作为文件名；OneBot/NapCat 普通文件消息可按统一可恢复队列延迟撤回，不再反查群文件。
+- **统一可恢复撤回队列**：图片自动撤回与 OneBot/NapCat 本子文件消息延迟撤回统一保存到 `revoke_tasks.json`；插件重启后按原到期时间继续执行，旧 `doujinshi_file_cleanup_tasks.json` 会自动迁移。
+- **可配置提示**：新增 `doujinshi_fetching`、`doujinshi_failed` 消息键。
+
+### Changed
+
+- **正则入口收敛**：色图自然语言与纯文本今日运势改由 `main.py` 的单一 regex 路由函数分发。
+- **撤回调度重构**：移除仅在内存存活的撤回调度，所有已登记的 OneBot `delete_msg` 与 `delete_group_file` 任务均使用统一可恢复调度器。
+
+### Fixed
+
+- **OneBot 本子文件 URI**：普通文件直发取得 `message_id` 时，统一将绝对本地路径规范化为 `file://`，避免 NapCat 虽接受 action 但 QQ 客户端打开附件显示下载失败。
+
 ## [2.1.2] - 2026-07-09
 
 ### Fixed
 - **Provider over-return 数量保护**：修复部分上游 API 在请求 `num=1` 时返回多个图片 URL，导致插件连续发送 2 张图片的问题。下载层现在会按本轮缺口裁剪候选 URL，只下载并交付用户请求数量的图片；正常补齐、下载重试、缓存落盘和 sender 发送策略不变。新增回归测试覆盖「请求 1 张但 provider 返回 2 个 URL」场景。
-- **NapCat 发送确认超时去重**：修复 OneBot/NapCat `send_group_msg` 返回 retcode `1200` 且 wording 为 NTQQ `sendMsg` 超时时被误判为可重试失败的问题。此类结果现在仅在 OneBot-like 平台且匹配已知 NTQQ `sendMsg` 超时标记时视为 pending delivery，不再继续触发普通发送、stream 或 HTML fallback，避免平台实际已送达但确认丢失时把同一张图片重复发送；非 OneBot 平台和不相关的 retcode `1200` 超时仍按普通失败处理。
 
 ## [2.1.1] - 2026-06-15
 

CLAUDE.md

@@ -1,29 +1,25 @@
-# CLAUDE.md — astrbot_plugin_setu
+# AGENTS.md — astrbot_plugin_setu
 
-本文件只保留 Claude 协作入口规则。业务细节按需阅读 `docs/project/`，开发维护规则优先阅读 `docs/dev/maintenance.md`。
+本文件只保留协作 agent 的入口规则。业务细节按需阅读 `docs/project/`，开发维护规则优先阅读 `docs/dev/maintenance.md`。
 
 ## 沟通语言
 
-必须使用中文与用户交流。
+- 与用户沟通必须使用中文。
 
 ## 项目形态
 
-- **语言**: Python 3.10+
-- **框架**: AstrBot plugin system
-- **架构**: DDD 分层
-- **许可证**: AGPL
+- 这是一个 AstrBot 随机图片与随机本子 PDF 插件，采用 DDD 分层。
+- 管理功能属于 Plugin Pages（统一 dashboard 页面，含会话配置和访问控制标签页）。
 
 主要目录：
 
-```text
-src/domain/          领域实体、值对象、标签解析、访问控制
-src/application/     用例、DTO、端口接口、会话配置服务
-src/infrastructure/  配置、持久化、provider、sender、AstrBot 适配
-src/shared/          配置模型、日志、发送缓存
-pages/               Plugin Pages 前端（统一 dashboard 页面）
-templates/           运势卡片 HTML 模板与字体
-tests/               单元测试、集成测试与测试夹具
-```
+- `src/domain/`: 领域实体、值对象、标签解析、访问控制。
+- `src/application/`: 用例、DTO、端口接口、会话配置服务。
+- `src/infrastructure/`: 配置、持久化、provider、随机本子 PDF、sender、AstrBot 适配。
+- `src/shared/`: 配置模型、日志、发送缓存。
+- `pages/`: Plugin Pages 前端（统一 dashboard）。
+- `templates/`: 运势卡片 HTML 模板与字体。
+- `tests/`: 单元测试、集成测试与测试夹具。
 
 ## 阅读入口
 
@@ -33,23 +29,27 @@ tests/               单元测试、集成测试与测试夹具
 - 修改消息配置、提示文案或占位符时看：`src/shared/config/models.py`
 - 修改 provider 适配或 sender 策略时看：`src/infrastructure/providers/` 和 `src/infrastructure/sending/`
 
-## 技能
-
-如果当前会话可用，修改本插件时优先参考 `astrbot-dev-skill`。它对 AstrBot 命令装饰器、Plugin Pages bridge、统一会话 ID 和平台适配边界有帮助。
-
 ## 硬约束
 
 - 不要把业务逻辑编排塞进 `main.py`；保持注册和路由专注。
 - 插件运行数据必须通过 `StarTools.get_data_dir(self.name)` 获取，不要硬编码路径。
 - 从插件目录本地调试时，不要创建或使用 `<plugin>/data` 作为运行态目录。
 - 所有用户可见提示必须走 `MessagesConfig` / `resolve_message()`，不要在 handler 内硬编码提示文案。
+- 随机本子 PDF 由 `infrastructure/doujinshi/` 生成；OneBot/NapCat 使用 `Nodes` 合并转发并按消息 ID 进入统一可恢复撤回，其他平台直接发送 `File`。
+- 色图与随机本子都必须使用 `application/setu/tag_resolution.py` 解析标签，保持分隔符和别名映射语义一致。
+- `delivery.auto_revoke_targets` 以单一列表选择色图、今日运势和本子是否进入自动清理；三者共用 `auto_revoke_delay`，本子合并转发必须在发送时取得并立即持久化 `message_id`，避免异步上传可见性导致清理状态丢失。
 - 其他领域值、平台行为和配置边界不要写进本文件，放到 `docs/project/` 或 `docs/dev/`。
 
 ## 文档纪律
 
-- 文档是改动的一部分。代码改动导致现有说明失真时，必须在同一 patch 中更新相关 `docs/`。
-- 命令行为、Plugin Pages 行为、配置语义、provider、sender、消息配置、访问控制变化时，通常需要更新文档。
-- repo-wide 约束或 agent 入口说明变化时，同步更新 `AGENTS.md` 和 `CLAUDE.md`。
+- 文档不是可选收尾。行为、边界、入口、配置、流程或维护约定变化时，必须同步更新对应 `docs/`。
+- 下列变化默认必须同步文档：
+  - 命令行为或参数变化
+  - Plugin Pages 交互变化
+  - 配置项、默认值或兼容规则变化
+  - provider、sender、消息配置算法变化
+  - 访问控制判定逻辑变化
+- 如果修改 repo-wide 维护规则或 agent 入口约定，同步更新 `AGENTS.md` 和 `CLAUDE.md`。
 
 ## 测试与检查命令
 
@@ -70,9 +70,9 @@ uv run ruff format data/plugins/astrbot_plugin_setu
 uv run ruff check data/plugins/astrbot_plugin_setu
 ```
 
-## 维护
+## 更新策略
 
-当架构、命令面、发送策略、配置路径或测试 / lint 流程变化时，同步更新 `AGENTS.md` 和 `CLAUDE.md`。
+当架构、命令面、发送策略、配置路径或测试 / lint 流程变化时，同步更新 `CLAUDE.md` 和 `AGENTS.md`。
 
 ## 篇幅约束
 

README.md

@@ -4,7 +4,7 @@
 
 <img src="https://count.getloli.com/@astrbot_plugin_setu?name=astrbot_plugin_setu&theme=rule34&padding=7&offset=0&align=top&scale=1&pixelated=1&darkmode=auto" alt="Moe Counter">
 
-**一个支持多平台、可自定义、带防审核机制的随机色图插件，支持多 API、会话级配置、LLM 工具调用。**
+**一个支持多平台、可自定义、带防审核机制的随机色图插件，支持多 API、随机本子 PDF/ZIP、会话级配置、LLM 工具调用。**
 
 [![License: AGPL](https://img.shields.io/badge/License-AGPL-blue.svg)](https://opensource.org/licenses/agpl-3.0)
 ![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)
@@ -55,7 +55,8 @@
 - 🖼️ **HTML 卡片包装** - 防止平台审核，支持自定义样式
 - 🤖 **LLM 工具调用** - 可通过大模型自动获取色图
 - 🏷️ **标签搜索** - 支持多标签、中文标签、模糊匹配
-- 🔄 **多种发送模式** - 直接发送、合并转发、文件封装
+- 🔄 **多种色图发送模式** - 直接发送、合并转发、文件封装
+- 📚 **随机本子文件** - 获取 API 返回的全部页图，可配置封装为 PDF 或 ZIP；OneBot/NapCat 普通文件消息可按统一可恢复队列延迟撤回
 - 🛡️ **防审核机制** - HTML 卡片 fallback、NapCat 流式上传、延迟撤回、Docx 封装
 - ⚡ **性能优化** - 磁盘缓存、自动补图、httpx、可观测下载重试
 - 🌐 **多平台适配** - 兼容 AstrBot 支持的所有平台
@@ -91,12 +92,15 @@
 来9份白丝 萝莉色图
 /setu 白丝 萝莉
 /setu 3 白丝
+来份本子
+/随机本子
 /session_config set setu.content_mode r18
 ```
 
 - 数量范围支持中文数字
 - 标签支持空格、逗号、顿号分隔
 - `/session_config` 统一管理当前会话的覆盖配置
+- `/随机本子`（别名 `/本子`、`/doujinshi`）按 `delivery.doujinshi_send_mode` 生成并发送随机本子 PDF 或 ZIP；所有平台均直接发送文件，不再使用合并转发；OneBot 群聊可按配置延迟撤回对应的普通文件消息
 
 完整的命令说明见 [`docs/usage/commands.md`](./docs/usage/commands.md)。
 
@@ -145,7 +149,9 @@
 | 配置项 | 说明 | 默认值 |
 |--------|------|--------|
 | `api_type` | API 类型（lolicon / atri / sexnyan / custom / all） | `lolicon` |
-| `send_mode` | 发送模式（auto / image / forward） | `auto` |
+| `send_mode` | 色图发送模式（auto / image / forward） | `auto` |
+| `doujinshi_send_mode` | 本子文件格式（pdf / archive） | `pdf` |
+| `doujinshi_max_page` | 随机本子最大页数（`0` 表示不限） | `0` |
 | `content_mode` | 内容模式（sfw / r18 / mix） | `sfw` |
 | `max_count` | 单次最大图片数（1-10） | `10` |
 | `max_replenish_rounds` | 下载暂时失败时的同 URL 确认尝试次数/补图轮次 | `3` |
@@ -158,13 +164,17 @@
 |--------|------|--------|
 | `html_card_strategy` | HTML 卡片策略（never / fallback / always） | `fallback` |
 | `platform_transports` | 平台传输模板列表，可添加 NapCat 模板 | `[]` |
+| `auto_revoke_targets` | 自动撤回内容列表（`setu` / `fortune` / `doujinshi`） | `["doujinshi"]` |
 | `auto_revoke_scope` | 自动撤回范围（none / sfw / r18 / all） | `none` |
+| `auto_revoke_delay` | 已启用内容共用的自动清理延迟（秒，`0` 全部关闭） | `30` |
 | `r18_docx_mode` | R18 是否使用 Docx 封装 | `true` |
 
 图片下载遇到短暂网络错误时会先按 `max_replenish_rounds` 对同一 URL 做确认重试；发送接口超时或 OneBot/NapCat 类适配器未返回 message id 时会标记为可能仍在送达，不会立刻触发降级重复发图。旧版 `auto_revoke_r18` 会在启动时迁移为 `auto_revoke_scope`，迁移后不再作为公开配置项展示。
 
 NapCat stream 上传的分块内容按 NapCat 协议仍为 base64 字符串；若 AstrBot 与 NapCat 共享同一图片目录，可在 `platform_transports` 添加 NapCat 模板，将共享目录加入 `local_file_allowed_roots` 并把 `local_file_mode` 设为 `always` 或 `fallback`，让直发模式通过 raw OneBot `file://` 路径绕过 AstrBot 标准链路的 base64 转换。
 
+`auto_revoke_targets` 是单一内容列表，默认只含 `doujinshi`，因此色图和今日运势默认不撤回；按需加入 `setu` 或 `fortune`。色图加入后还须命中 `auto_revoke_scope`。三类内容共享 `auto_revoke_delay` 和 OneBot 可恢复队列；设置 `1800` 即为 30 分钟，设为 `0` 会关闭全部自动清理。随机本子无论选择 PDF 还是 ZIP 都以普通文件消息发送；OneBot/NapCat 群聊发送成功后会直接登记消息 ID，到期调用 `delete_msg`，不再反查群文件。所有任务保存于插件运行数据目录的 `revoke_tasks.json`，插件重启后仍按原到期时间继续执行。
+
 ### 模板覆盖
 
 | 配置项 | 说明 |

_conf_schema.json

@@ -238,11 +238,24 @@
         "items": {
             "send_mode": {
                 "type": "string",
-                "description": "发送模式",
-                "hint": "auto 在图片数量>1且平台支持时使用合并转发（仅 aiocqhttp/OneBot 类平台支持，其它平台自动回退直发）；image 始终直发；forward 始终尝试合并转发。",
+                "description": "色图发送模式",
+                "hint": "仅作用于色图：auto 在图片数量>1且平台支持时使用合并转发（仅 aiocqhttp/OneBot 类平台支持，其它平台自动回退直发）；image 始终直发；forward 始终尝试合并转发。",
                 "default": "auto",
                 "options": ["image", "forward", "auto"]
             },
+            "doujinshi_send_mode": {
+                "type": "string",
+                "description": "随机本子文件格式",
+                "hint": "pdf=将全部页图封装为 PDF；archive=将原始页图按顺序打包为 ZIP。两种模式都以普通文件发送，不使用合并转发。",
+                "default": "pdf",
+                "options": ["pdf", "archive"]
+            },
+            "doujinshi_max_page": {
+                "type": "int",
+                "description": "随机本子最大页数",
+                "hint": "限制随机本子最多包含的页数，超过该页数的本子会被 API 过滤；0 表示不限制（不传 max_page 参数）。",
+                "default": 0
+            },
             "r18_docx_mode": {
                 "type": "bool",
                 "description": "R18 Docx 打包模式",
@@ -252,14 +265,21 @@
             "auto_revoke_scope": {
                 "type": "string",
                 "description": "自动撤回范围",
-                "hint": "none=不撤回；sfw=仅撤回全年龄图片；r18=仅撤回 R18 图片/文件；all=全部 Setu 图片都会撤回。",
+                "hint": "none=不撤回；sfw=仅撤回全年龄图片；r18=仅撤回 R18 图片/文件；all=全部 Setu 图片都会撤回。仅在自动撤回内容含 setu 时生效。",
                 "default": "none",
                 "options": ["none", "sfw", "r18", "all"]
             },
+            "auto_revoke_targets": {
+                "type": "list",
+                "description": "自动撤回内容",
+                "hint": "每行填写一个：setu（色图）、fortune（今日运势）、doujinshi（随机本子）。默认仅 doujinshi；色图还须命中自动撤回范围。",
+                "default": ["doujinshi"],
+                "options": ["setu", "fortune", "doujinshi"]
+            },
             "auto_revoke_delay": {
                 "type": "int",
-                "description": "撤回延迟时间(秒)",
-                "hint": "命中自动撤回范围后多久撤回，默认 30 秒。",
+                "description": "自动清理延迟时间(秒)",
+                "hint": "同时用于自动撤回内容列表中启用的 Setu 图片、今日运势消息和 OneBot/NapCat 随机本子文件消息。默认 30 秒；设为 0 可关闭全部自动清理，填 1800 即为 30 分钟。",
                 "default": 30
             },
             "platform_transports": {
@@ -455,6 +475,8 @@
                                     "count_out_of_range",
                                     "fetch_timeout",
                                     "fetch_failed",
+                                    "doujinshi_fetching",
+                                    "doujinshi_failed",
                                     "no_result",
                                     "empty_payload",
                                     "r18_docx_failed",

docs/dev/testing.md

@@ -40,6 +40,7 @@
 - [ ] HTML 卡片 fallback 在原图发送失败时仍能触发。
 - [ ] 运势卡片渲染失败时降级为纯文本。
 - [ ] 会话配置读写不锁死（并发安全）。
-- [ ] `auto_revoke_scope` 的 `none` / `sfw` / `r18` / `all` 覆盖正确，旧 `setu.auto_revoke` 与 `auto_revoke_r18` 只通过迁移保留。
+- [ ] `auto_revoke_targets` 默认仅含 `doujinshi`，并能分别将 `setu`、`fortune`、`doujinshi` 传递到对应链路；`auto_revoke_scope` 的 `none` / `sfw` / `r18` / `all` 仅过滤已启用的色图。
+- [ ] OneBot 图片、今日运势和本子普通文件消息均使用 `auto_revoke_delay` 写入统一持久化消息任务；本子通过原始 `send_group_msg` 取得 `message_id` 并在到期后调用 `delete_msg`，旧字段与旧队列均可迁移；删除任务连续失败三次后会移除持久化记录。
 - [ ] `tests/conftest.py` 固定的 `ASTRBOT_ROOT` 仍能阻止插件目录污染。
 - [ ] 访问控制黑白名单互斥逻辑正常。