astrbot_plugin_jmdowloads/docs/MIGRATION_HANDOFF.md
2026-07-18 23:44:06 +08:00

18 KiB

JMDownload 项目迁移交接文档

更新日期:2026-07-18

本文用于在迁移项目路径、迁移 Forgejo 仓库地址、或更换 Codex 账号后继续开发 astrbot_plugin_jmdownload。内容尽量保留当前对话中已经确定的背景、设计决策、版本状态和后续注意事项。

1. 当前项目定位

这是一个 AstrBot 插件,用于把原 NoneBot 插件 QuickLAW/nonebot_plugin_JMDownload 的核心功能迁移到 AstrBot,并在此基础上增强:

JM ID -> jmcomic 下载 -> CBZ/PDF 归档 -> Komga 扫描 -> AstrBot 消息反馈

当前目标不是做一个网页或独立服务,而是一个可放入 AstrBot data/plugins 目录的插件。

2. 当前本地路径

当前 Windows 桌面开发路径:

E:\Codex\JMDownload

注意:E:\Codex\JMDownload 只是工作父目录,不是 Git 仓库。真正的插件仓库在:

E:\Codex\JMDownload\astrbot_plugin_jmdownload

同级目录中还有原参考仓库源码:

E:\Codex\JMDownload\nonebot_plugin_JMDownload

原仓库只作为迁移参考,不是当前插件的主仓库。

3. 当前远端仓库

当前插件仓库 Git remote:

origin ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git

历史上曾使用过 HTTP 地址:

http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_jmdowloads.git

仓库名里有一个历史拼写:jmdowloads,少了 n。本地插件目录仍然是正确拼写:

astrbot_plugin_jmdownload

metadata.yaml 里的 repo 字段目前仍写的是 HTTP 地址。如果迁移到新 Forgejo 地址,建议同步更新:

repo: "新的仓库地址"

4. 当前 Git 状态

截至本文写入前,最新功能基线为:

branch: main
feature baseline: b6144d7 S-20 访问控制白名单黑名单
tracking: main...origin/main
workspace: clean

如果本文档被提交为后续版本,git log -1 可能显示文档提交,例如 S-21 迁移交接文档;功能代码仍以上述 S-20 为当前完成基线。

当前已存在的版本 TAG:

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。

推荐后续版本命名继续使用:

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 结构:

<archive_root>/
  <series_name>/
    <series_name> [<JM ID>].cbz

CBZ 内包含:

  • ComicInfo.xml
  • 0001.jpg
  • 0002.jpg
  • 后续页面

S-09 PDF 输出兼容

保留 PDF 输出能力:

  • archive_format=pdf
  • pdf_chunk_size
  • 使用临时 PDF 分块降低大本子转换时的内存占用

S-10 Komga 扫描联动

归档后可自动请求 Komga 扫描:

POST /api/v1/libraries/{libraryId}/scan

支持:

  • komga.api_key
  • 或 komga.username + komga.password

S-11 AstrBot 文件发送

支持在平台允许时,把生成的归档文件发送回聊天:

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 下载代理配置:

jm_proxy.mode: inherit | none | system | clash | v2ray | custom
jm_proxy.proxy_url
jm_proxy.http_proxy
jm_proxy.https_proxy

代理写入 jmcomic:

client.postman.meta_data.proxies

新增手动 AVS Cookie:

jm_avs_cookie

大部分 JM 下载不需要登录;少量敏感或受限内容可能需要登录态。

新增账号密码登录:

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 访问控制白名单黑名单

新增插件级访问控制,默认启用并要求白名单:

access_control.enabled: true
access_control.require_whitelist: true

支持:

  • 平台 ID 白/黑名单
  • OneBot v11 机器人自身 ID 白/黑名单
  • 群聊 ID 白/黑名单
  • 私聊账号 ID 白/黑名单
  • 完整 UMO 白/黑名单
  • 黑名单优先于白名单
  • 拒绝时可静默,也可配置拒绝提示

6. 当前文件结构

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 <id> 下载、归档、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 开发摘要来源:

E:\Codex\Astrbot\ASTRBOT_PLUGIN_DEVELOPMENT_SUMMARY.md

事件对象常用字段:

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 格式:

平台ID:消息类型:会话ID

OneBot v11 / aiocqhttp 识别方式:

群聊消息:
  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号

白名单配置示例:

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 或群号,可以临时配置:

access_control.require_whitelist: false

然后在目标会话里执行:

/jm status

查看输出中的:

  • 当前平台 ID
  • 当前机器人自身 ID
  • 当前群聊 ID
  • 当前私聊/发送者 ID
  • 当前 UMO

复制到白名单后,再重新开启:

access_control.require_whitelist: true

9. 当前配置项总览

来自 _conf_schema.json。

基础配置:

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

访问控制:

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 代理:

jm_proxy.mode
jm_proxy.proxy_url
jm_proxy.http_proxy
jm_proxy.https_proxy

JM 登录:

jm_login.enabled
jm_login.username
jm_login.password
jm_login.impl
jm_avs_cookie

Komga:

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

推荐安装路径:

AstrBot/
  data/
    plugins/
      astrbot_plugin_jmdownload/

使用 Git:

cd AstrBot/data/plugins
git clone <新的仓库地址> astrbot_plugin_jmdownload

如果继续使用当前 Forgejo SSH alias:

git clone ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git astrbot_plugin_jmdownload

如果使用 HTTP:

git clone http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_jmdowloads.git astrbot_plugin_jmdownload

安装依赖:

pip install -r requirements.txt

依赖列表:

jmcomic>=0.3.0
PyYAML>=6.0
Pillow>=9.0.0
httpx>=0.27.0
PyPDF2>=2.0.0

然后在 AstrBot WebUI 中重载插件。

12. 迁移 Git 远端地址

如果只是迁移项目路径,不换仓库地址:

git clone ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git astrbot_plugin_jmdownload

如果要迁移到新 Forgejo 仓库:

cd E:\Codex\JMDownload\astrbot_plugin_jmdownload
git remote -v
git remote set-url origin <新的仓库地址>
git push origin HEAD:main
git push origin --tags

如果想保留旧远端并新增新远端:

git remote rename origin old-origin
git remote add origin <新的仓库地址>
git push origin HEAD:main
git push origin --tags

推荐推送分支时使用显式 ref:

git push origin HEAD:main

之前 HTTP remote 曾出现凭据问题:

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 线程上下文
  • 本地运行时缓存

建议新账号接手后先做:

cd <新的工作目录>\astrbot_plugin_jmdownload
git status --short --branch
git remote -v
git log -1 --oneline --decorate
git tag --points-at HEAD

如果 remote 是:

ssh://forgejo-codex/YokiiroBW/astrbot_plugin_jmdowloads.git

需要确认新系统或新账号的 SSH 配置里有 forgejo-codex host alias。否则可以改成明确地址,例如:

git remote set-url origin ssh://<user>@192.168.31.210:<ssh-port>/YokiiroBW/astrbot_plugin_jmdowloads.git

具体 SSH 端口以 Forgejo 部署为准。如果不确定,先在旧账号里查看:

Get-Content $env:USERPROFILE\.ssh\config

不要把私钥或 token 写入仓库。

14. 测试命令

当前使用 bundled Python 跑过测试:

& "C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" -m unittest discover -s tests

也可以在正常 Python 环境中运行:

python -m unittest discover -s tests

当前测试数量:

22 tests

额外检查:

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. 临时配置:
access_control.require_whitelist: false
admin_only: false
  1. 在目标 OneBot v11 群聊或私聊执行:
/jm status
  1. 复制输出中的平台 ID、机器人自身 ID、群聊 ID、私聊/发送者 ID、UMO。
  2. 填入白名单。
  3. 恢复:
access_control.require_whitelist: true
admin_only: true
  1. 配置 Komga:
archive_root
komga.enabled
komga.base_url
komga.library_id
komga.api_key
  1. 如果目标网络需要代理,配置:
jm_proxy.mode: custom
jm_proxy.proxy_url: 127.0.0.1:7890
  1. 用一个小 JM ID 做真实下载测试。
  2. 确认归档文件落在 Komga library 根目录。
  3. 确认 Komga 自动扫描后能识别新书。

17. 后续开发建议

docs/ROADMAP.md 中还保留以下可推进项:

  • 批量下载 /jm batch
  • 任务队列查看 /jm queue
  • 未开始任务取消 /jm cancel <task_id>
  • 更完整的 JM 元数据写入 ComicInfo.xml
  • Komga 健康检查 /jm komga
  • 按 JM ID 去重与重命名模板
  • 下载请求审计日志
  • 真实 AstrBot + OneBot v11 + Komga 环境联调

建议下一版优先做:

S-21 真实环境联调修正

原因:S-18 到 S-20 已经引入代理、登录、访问控制,最好先在真实 AstrBot 会话中验证命令触发、ID 识别、jmcomic 下载和 Komga 扫描,再继续做批量任务系统。

18. 给新 Codex 会话的起始提示

迁移后可以把下面这段交给新的 Codex 会话:

当前项目是 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 联调,或按用户新需求继续开发。