From bae1381480f55e0cf07f363e24b6ab455612259a Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 18 Jul 2026 23:44:06 +0800 Subject: [PATCH] =?UTF-8?q?S-21=20=E8=BF=81=E7=A7=BB=E4=BA=A4=E6=8E=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + docs/MIGRATION_HANDOFF.md | 810 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 812 insertions(+) create mode 100644 docs/MIGRATION_HANDOFF.md diff --git a/README.md b/README.md index 7095d55..2734971 100644 --- a/README.md +++ b/README.md @@ -71,4 +71,6 @@ python -m unittest discover -s tests 详细部署步骤见 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。 +项目迁移和 Codex 账号交接见 [docs/MIGRATION_HANDOFF.md](docs/MIGRATION_HANDOFF.md)。 + 后续增强计划见 [docs/ROADMAP.md](docs/ROADMAP.md)。 diff --git a/docs/MIGRATION_HANDOFF.md b/docs/MIGRATION_HANDOFF.md new file mode 100644 index 0000000..5f61669 --- /dev/null +++ b/docs/MIGRATION_HANDOFF.md @@ -0,0 +1,810 @@ +# JMDownload 项目迁移交接文档 + +更新日期:2026-07-18 + +本文用于在迁移项目路径、迁移 Forgejo 仓库地址、或更换 Codex 账号后继续开发 `astrbot_plugin_jmdownload`。内容尽量保留当前对话中已经确定的背景、设计决策、版本状态和后续注意事项。 + +## 1. 当前项目定位 + +这是一个 AstrBot 插件,用于把原 NoneBot 插件 `QuickLAW/nonebot_plugin_JMDownload` 的核心功能迁移到 AstrBot,并在此基础上增强: + +```text +JM ID -> jmcomic 下载 -> CBZ/PDF 归档 -> Komga 扫描 -> AstrBot 消息反馈 +``` + +当前目标不是做一个网页或独立服务,而是一个可放入 AstrBot `data/plugins` 目录的插件。 + +## 2. 当前本地路径 + +当前 Windows 桌面开发路径: + +```text +E:\Codex\JMDownload +``` + +注意:`E:\Codex\JMDownload` 只是工作父目录,不是 Git 仓库。真正的插件仓库在: + +```text +E:\Codex\JMDownload\astrbot_plugin_jmdownload +``` + +同级目录中还有原参考仓库源码: + +```text +E:\Codex\JMDownload\nonebot_plugin_JMDownload +``` + +原仓库只作为迁移参考,不是当前插件的主仓库。 + +## 3. 当前远端仓库 + +当前插件仓库 Git remote: + +```text +origin ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git +``` + +历史上曾使用过 HTTP 地址: + +```text +http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_jmdowloads.git +``` + +仓库名里有一个历史拼写:`jmdowloads`,少了 `n`。本地插件目录仍然是正确拼写: + +```text +astrbot_plugin_jmdownload +``` + +`metadata.yaml` 里的 `repo` 字段目前仍写的是 HTTP 地址。如果迁移到新 Forgejo 地址,建议同步更新: + +```yaml +repo: "新的仓库地址" +``` + +## 4. 当前 Git 状态 + +截至本文写入前,最新功能基线为: + +```text +branch: main +feature baseline: b6144d7 S-20 访问控制白名单黑名单 +tracking: main...origin/main +workspace: clean +``` + +如果本文档被提交为后续版本,`git log -1` 可能显示文档提交,例如 `S-21 迁移交接文档`;功能代码仍以上述 S-20 为当前完成基线。 + +当前已存在的版本 TAG: + +```text +S-01-插件骨架固化 +S-04-jmcomic配置接入修正 +S-03-下载器核心迁移 +S-08-CBZ归档完善 +S-10-Komga扫描联动 +S-11-AstrBot文件发送 +S-09-PDF输出兼容 +S-12-错误模型统一 +S-13-清理策略 +S-14-单元测试 +S-15-集成测试 +S-16-部署文档 +S-17-后续增强规划 +S-18-JM代理与登录配置 +S-19-JM账号登录自动Cookie +S-20-访问控制白名单黑名单 +``` + +用户要求:每个版本都要提交、推送到局域网 Forgejo,并使用中文 TAG。 + +推荐后续版本命名继续使用: + +```text +commit: S-21 <中文说明> +tag: S-21-<中文说明> +``` + +## 5. 已完成版本概要 + +### S-01 插件骨架固化 + +建立 AstrBot 插件最小骨架: + +- `main.py` +- `metadata.yaml` +- `requirements.txt` +- `_conf_schema.json` +- 基础服务目录 `services/` + +### S-03 下载器核心迁移 + +接入 `jmcomic` 下载: + +- 使用 `jmcomic.create_option_by_file(...)` +- 使用 `jmcomic.download_album(...)` +- 下载任务放入插件工作目录 +- 提取下载结果标题 +- 收集图片文件 + +### S-04 jmcomic 配置接入修正 + +修正 jmcomic 配置文件生成方式,保证下载目录、域名和批次配置可以通过插件设置写入。 + +### S-08 CBZ 归档完善 + +实现 Komga 友好的 CBZ 结构: + +```text +/ + / + [].cbz +``` + +CBZ 内包含: + +- `ComicInfo.xml` +- `0001.jpg` +- `0002.jpg` +- 后续页面 + +### S-09 PDF 输出兼容 + +保留 PDF 输出能力: + +- `archive_format=pdf` +- `pdf_chunk_size` +- 使用临时 PDF 分块降低大本子转换时的内存占用 + +### S-10 Komga 扫描联动 + +归档后可自动请求 Komga 扫描: + +```text +POST /api/v1/libraries/{libraryId}/scan +``` + +支持: + +- `komga.api_key` +- 或 `komga.username` + `komga.password` + +### S-11 AstrBot 文件发送 + +支持在平台允许时,把生成的归档文件发送回聊天: + +```text +send_archive_file: true +``` + +不同平台对文件消息支持不一致;即使发送失败,归档文件仍会保存在 `archive_root`。 + +### S-12 错误模型统一 + +统一插件内可预期错误模型: + +- 配置错误 +- 下载错误 +- 归档错误 +- Komga 扫描错误 + +### S-13 清理策略 + +支持临时下载目录清理: + +- 归档成功后默认删除本次工作目录 +- `/jm cleanup` 清理历史临时目录 +- `cleanup_retention_days=0` 表示清理全部历史工作目录 + +### S-14 单元测试 + +建立基础单元测试: + +- 配置解析 +- 归档生成 +- 图片排序/收集 +- 清理安全边界 + +### S-15 集成测试 + +补充归档与 Komga 扫描的集成测试。 + +### S-16 部署文档 + +新增 `docs/DEPLOYMENT.md`,记录安装、配置、Komga 联动、命令和故障排查。 + +### S-17 后续增强规划 + +新增 `docs/ROADMAP.md`,规划批量下载、任务状态、元数据增强、Komga 健康检查、去重策略、权限审计和真实环境联调。 + +### S-18 JM 代理与登录配置 + +新增 JM 下载代理配置: + +```text +jm_proxy.mode: inherit | none | system | clash | v2ray | custom +jm_proxy.proxy_url +jm_proxy.http_proxy +jm_proxy.https_proxy +``` + +代理写入 jmcomic: + +```text +client.postman.meta_data.proxies +``` + +新增手动 AVS Cookie: + +```text +jm_avs_cookie +``` + +大部分 JM 下载不需要登录;少量敏感或受限内容可能需要登录态。 + +### S-19 JM 账号登录自动 Cookie + +新增账号密码登录: + +```text +jm_login.enabled +jm_login.username +jm_login.password +jm_login.impl: api | html +``` + +实现方式: + +- 使用 jmcomic 自带 `plugins.after_init -> login` 插件 +- 登录后由 jmcomic 更新请求 Cookie +- 插件在 jmcomic 初始化完成后尽量删除含账号密码或 AVS 的临时 `jmcomic.yml` + +安全注意: + +- 不建议通过聊天命令输入密码 +- 密码应放 AstrBot 插件配置 +- 配置文件中的 `password` 字段已设为 `invisible` + +### S-20 访问控制白名单黑名单 + +新增插件级访问控制,默认启用并要求白名单: + +```text +access_control.enabled: true +access_control.require_whitelist: true +``` + +支持: + +- 平台 ID 白/黑名单 +- OneBot v11 机器人自身 ID 白/黑名单 +- 群聊 ID 白/黑名单 +- 私聊账号 ID 白/黑名单 +- 完整 UMO 白/黑名单 +- 黑名单优先于白名单 +- 拒绝时可静默,也可配置拒绝提示 + +## 6. 当前文件结构 + +```text +astrbot_plugin_jmdownload/ + _conf_schema.json + main.py + metadata.yaml + requirements.txt + README.md + docs/ + DEPLOYMENT.md + MIGRATION_HANDOFF.md + ROADMAP.md + services/ + __init__.py + access.py + archive.py + download.py + errors.py + images.py + komga.py + settings.py + tests/ + helpers.py + test_access_control.py + test_archive.py + test_cleanup.py + test_images.py + test_integration_archive_komga.py + test_jmcomic_config.py + test_settings.py +``` + +## 7. 关键代码说明 + +### `main.py` + +AstrBot 插件入口: + +- 注册 `/jm` 命令组 +- `/jm download ` 下载、归档、Komga 扫描、可选发送文件 +- `/jm status` 显示配置状态和当前事件 ID +- `/jm scan` 手动触发 Komga 扫描 +- `/jm cleanup` 清理临时工作目录 +- `_deny_request(...)` 统一访问控制和管理员校验 + +### `services/settings.py` + +解析 AstrBot WebUI 插件配置: + +- `PluginSettings` +- `AccessControlSettings` +- `JmProxySettings` +- `JmLoginSettings` +- `KomgaSettings` + +### `services/access.py` + +插件级白名单/黑名单: + +- `EventIdentity.from_event(event)` 提取 AstrBot 事件身份 +- `AccessControl.check(event)` 返回允许/拒绝和原因 +- 支持 `平台ID:ID` scoped 写法 +- 支持完整 `unified_msg_origin` + +### `services/download.py` + +jmcomic 下载: + +- 动态生成 `jmcomic.yml` +- 写入下载目录、JM 域名、批次大小 +- 写入代理 `client.postman.meta_data.proxies` +- 写入手动 `cookies.AVS` +- 写入账号登录插件 `plugins.after_init` +- 初始化后尽量删除敏感临时配置 + +### `services/archive.py` + +归档输出: + +- CBZ +- PDF +- `ComicInfo.xml` +- Komga 友好的目录结构 + +### `services/komga.py` + +Komga library scan: + +- API Key +- Basic Auth +- 扫描超时 + +## 8. AstrBot / OneBot v11 ID 识别 + +AstrBot 开发摘要来源: + +```text +E:\Codex\Astrbot\ASTRBOT_PLUGIN_DEVELOPMENT_SUMMARY.md +``` + +事件对象常用字段: + +```python +event.get_sender_id() +event.get_group_id() +event.get_self_id() +event.get_platform_name() +event.get_platform_id() +event.unified_msg_origin +event.is_private_chat() +event.is_admin() +``` + +AstrBot `unified_msg_origin` 格式: + +```text +平台ID:消息类型:会话ID +``` + +OneBot v11 / aiocqhttp 识别方式: + +```text +群聊消息: + get_group_id() -> 群号 + get_sender_id() -> 发送者 QQ 号 + get_self_id() -> 机器人 QQ 号 + UMO -> 平台ID:GroupMessage:群号 + +私聊消息: + get_group_id() -> 空字符串 + get_sender_id() -> 对方 QQ 号 + get_self_id() -> 机器人 QQ 号 + UMO -> 平台ID:FriendMessage:QQ号 +``` + +白名单配置示例: + +```text +access_control.allow_group_ids: + - 123456789 + - qq-main:123456789 + +access_control.allow_private_user_ids: + - 10001 + - qq-main:10001 + +access_control.allow_self_ids: + - 30003 + - qq-main:30003 + +access_control.allow_unified_origins: + - qq-main:GroupMessage:123456789 + - qq-main:FriendMessage:10001 +``` + +首次迁移时如果不知道平台 ID 或群号,可以临时配置: + +```text +access_control.require_whitelist: false +``` + +然后在目标会话里执行: + +```text +/jm status +``` + +查看输出中的: + +- 当前平台 ID +- 当前机器人自身 ID +- 当前群聊 ID +- 当前私聊/发送者 ID +- 当前 UMO + +复制到白名单后,再重新开启: + +```text +access_control.require_whitelist: true +``` + +## 9. 当前配置项总览 + +来自 `_conf_schema.json`。 + +基础配置: + +```text +archive_root +archive_format: cbz | pdf +pdf_chunk_size +admin_only +send_archive_file +overwrite_existing +delete_work_dir_after_archive +cleanup_retention_days +download_timeout_seconds +download_retry_count +progress_interval_seconds +max_concurrent_tasks +jm_batch_count +jm_domains +``` + +访问控制: + +```text +access_control.enabled +access_control.require_whitelist +access_control.allow_platform_ids +access_control.allow_self_ids +access_control.allow_group_ids +access_control.allow_private_user_ids +access_control.allow_unified_origins +access_control.deny_platform_ids +access_control.deny_self_ids +access_control.deny_group_ids +access_control.deny_private_user_ids +access_control.deny_unified_origins +access_control.deny_message +``` + +JM 代理: + +```text +jm_proxy.mode +jm_proxy.proxy_url +jm_proxy.http_proxy +jm_proxy.https_proxy +``` + +JM 登录: + +```text +jm_login.enabled +jm_login.username +jm_login.password +jm_login.impl +jm_avs_cookie +``` + +Komga: + +```text +komga.enabled +komga.base_url +komga.library_id +komga.username +komga.password +komga.api_key +komga.scan_timeout_seconds +``` + +## 10. 敏感配置迁移注意事项 + +以下值不应该写入 Git: + +- JM 密码:`jm_login.password` +- JM AVS Cookie:`jm_avs_cookie` +- Komga 密码:`komga.password` +- Komga API Key:`komga.api_key` +- 真实代理地址如果不方便公开,也不要写入仓库文档 + +迁移 Codex 账号或迁移机器时,需要在 AstrBot WebUI 里重新填写这些值。 + +如果迁移的是 AstrBot 整体数据目录,可以检查 AstrBot 的插件配置存储位置;本插件仓库本身不保存运行时配置。 + +## 11. 安装到 AstrBot + +推荐安装路径: + +```text +AstrBot/ + data/ + plugins/ + astrbot_plugin_jmdownload/ +``` + +使用 Git: + +```bash +cd AstrBot/data/plugins +git clone <新的仓库地址> astrbot_plugin_jmdownload +``` + +如果继续使用当前 Forgejo SSH alias: + +```bash +git clone ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git astrbot_plugin_jmdownload +``` + +如果使用 HTTP: + +```bash +git clone http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_jmdowloads.git astrbot_plugin_jmdownload +``` + +安装依赖: + +```bash +pip install -r requirements.txt +``` + +依赖列表: + +```text +jmcomic>=0.3.0 +PyYAML>=6.0 +Pillow>=9.0.0 +httpx>=0.27.0 +PyPDF2>=2.0.0 +``` + +然后在 AstrBot WebUI 中重载插件。 + +## 12. 迁移 Git 远端地址 + +如果只是迁移项目路径,不换仓库地址: + +```powershell +git clone ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git astrbot_plugin_jmdownload +``` + +如果要迁移到新 Forgejo 仓库: + +```powershell +cd E:\Codex\JMDownload\astrbot_plugin_jmdownload +git remote -v +git remote set-url origin <新的仓库地址> +git push origin HEAD:main +git push origin --tags +``` + +如果想保留旧远端并新增新远端: + +```powershell +git remote rename origin old-origin +git remote add origin <新的仓库地址> +git push origin HEAD:main +git push origin --tags +``` + +推荐推送分支时使用显式 ref: + +```powershell +git push origin HEAD:main +``` + +之前 HTTP remote 曾出现凭据问题: + +```text +remote: 凭据不正确或已过期 +fatal: Authentication failed +``` + +解决方式: + +- 使用 SSH remote,例如 `ssh://forgejo-codex/...` +- 或使用 Forgejo Personal Access Token 作为 HTTP 密码 +- 或清理 Windows Git Credential Manager 中旧凭据后重试 + +## 13. Codex 账号迁移注意事项 + +迁移 Codex 账号后,新账号通常不会继承旧账号的: + +- 本地审批规则 +- SSH agent 状态 +- Forgejo SSH host alias +- Git credential cache +- Codex 线程上下文 +- 本地运行时缓存 + +建议新账号接手后先做: + +```powershell +cd <新的工作目录>\astrbot_plugin_jmdownload +git status --short --branch +git remote -v +git log -1 --oneline --decorate +git tag --points-at HEAD +``` + +如果 remote 是: + +```text +ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git +``` + +需要确认新系统或新账号的 SSH 配置里有 `forgejo-codex` host alias。否则可以改成明确地址,例如: + +```powershell +git remote set-url origin ssh://@192.168.31.210:/YokiiroBW/astrbot_plugin_jmdowloads.git +``` + +具体 SSH 端口以 Forgejo 部署为准。如果不确定,先在旧账号里查看: + +```powershell +Get-Content $env:USERPROFILE\.ssh\config +``` + +不要把私钥或 token 写入仓库。 + +## 14. 测试命令 + +当前使用 bundled Python 跑过测试: + +```powershell +& "C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" -m unittest discover -s tests +``` + +也可以在正常 Python 环境中运行: + +```bash +python -m unittest discover -s tests +``` + +当前测试数量: + +```text +22 tests +``` + +额外检查: + +```powershell +python -c "import json, pathlib; json.loads(pathlib.Path('_conf_schema.json').read_text(encoding='utf-8')); print('json ok')" +python -m compileall -q . +``` + +注意:`compileall` 会生成 `__pycache__`,这些文件被 Git 忽略,不应提交。 + +## 15. 当前已知限制 + +- 默认启用白名单且白名单为空时,任何会话都会被拒绝,包括 `/jm status`。首次部署不知道 ID 时,临时关闭 `access_control.require_whitelist`。 +- `admin_only=true` 时,下载、扫描、清理仍要求 AstrBot 管理员身份;访问白名单通过后还要过管理员校验。 +- jmcomic 下载是同步库调用,超时后底层线程无法强杀,只能停止后续归档流程。 +- 部分平台不支持文件消息,`send_archive_file=true` 也可能发送失败,但归档仍会落盘。 +- PDF 归档只是兼容输出;Komga 推荐使用 CBZ。 +- jmcomic 域名、代理和登录状态可能受目标环境网络影响,迁移后要重新验证。 +- JM 账号密码登录依赖 jmcomic 的 `login` 插件行为;如果 `api` 不可用,可改 `jm_login.impl=html`。 + +## 16. 推荐迁移后验证流程 + +1. 克隆仓库或移动目录。 +2. 确认 `git status --short --branch` 干净。 +3. 安装依赖。 +4. 在 AstrBot WebUI 重载插件。 +5. 临时配置: + +```text +access_control.require_whitelist: false +admin_only: false +``` + +6. 在目标 OneBot v11 群聊或私聊执行: + +```text +/jm status +``` + +7. 复制输出中的平台 ID、机器人自身 ID、群聊 ID、私聊/发送者 ID、UMO。 +8. 填入白名单。 +9. 恢复: + +```text +access_control.require_whitelist: true +admin_only: true +``` + +10. 配置 Komga: + +```text +archive_root +komga.enabled +komga.base_url +komga.library_id +komga.api_key +``` + +11. 如果目标网络需要代理,配置: + +```text +jm_proxy.mode: custom +jm_proxy.proxy_url: 127.0.0.1:7890 +``` + +12. 用一个小 JM ID 做真实下载测试。 +13. 确认归档文件落在 Komga library 根目录。 +14. 确认 Komga 自动扫描后能识别新书。 + +## 17. 后续开发建议 + +`docs/ROADMAP.md` 中还保留以下可推进项: + +- 批量下载 `/jm batch` +- 任务队列查看 `/jm queue` +- 未开始任务取消 `/jm cancel ` +- 更完整的 JM 元数据写入 `ComicInfo.xml` +- Komga 健康检查 `/jm komga` +- 按 JM ID 去重与重命名模板 +- 下载请求审计日志 +- 真实 AstrBot + OneBot v11 + Komga 环境联调 + +建议下一版优先做: + +```text +S-21 真实环境联调修正 +``` + +原因:S-18 到 S-20 已经引入代理、登录、访问控制,最好先在真实 AstrBot 会话中验证命令触发、ID 识别、jmcomic 下载和 Komga 扫描,再继续做批量任务系统。 + +## 18. 给新 Codex 会话的起始提示 + +迁移后可以把下面这段交给新的 Codex 会话: + +```text +当前项目是 AstrBot 插件 astrbot_plugin_jmdownload,仓库路径为 <你的新路径>\astrbot_plugin_jmdownload。 +请先阅读 docs/MIGRATION_HANDOFF.md、README.md、docs/DEPLOYMENT.md、docs/ROADMAP.md。 +当前最新功能基线应为 S-20 访问控制白名单黑名单,提交 b6144d7,TAG 为 S-20-访问控制白名单黑名单;如果 docs/MIGRATION_HANDOFF.md 已提交,则可能还有 S-21 迁移交接文档提交。 +开发规则:每个完成版本都要 commit、推送到 Forgejo,并使用中文 TAG。 +不要提交任何 JM 密码、AVS Cookie、Komga API Key 或本地代理敏感配置。 +下一步建议做真实 AstrBot + OneBot v11 + Komga 联调,或按用户新需求继续开发。 +```