811 行
18 KiB
Markdown
811 行
18 KiB
Markdown
|
|
# 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
|
|||
|
|
<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 扫描:
|
|||
|
|
|
|||
|
|
```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 <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 开发摘要来源:
|
|||
|
|
|
|||
|
|
```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://<user>@192.168.31.210:<ssh-port>/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 <task_id>`
|
|||
|
|
- 更完整的 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 联调,或按用户新需求继续开发。
|
|||
|
|
```
|