refactor: 废弃 zip 插件的 level 参数，打包粒度由所在钩子自动推导

- ZipPlugin: level 默认值改为 None，根据上下文自动推导（有 album 则合并，只有 photo 则单章）
- Feature: export_zip 不再传递 level，_adapt_kwargs 移除 level 适配逻辑
- JmOption: compatible_with_old_versions 中新增 _migrate_zip_level，自动将旧 yaml 中的 level 配置等价迁移到正确的钩子位置
- 文档: 更新 option_file_syntax.md 和 13_export_and_feature.md 中 level 相关说明

Author: hect0x7

assets/docs/sources/option_file_syntax.md

@@ -226,14 +226,19 @@ plugins:
   after_album:
     - plugin: zip # 压缩文件插件
       kwargs:
-        level: photo # 按照章节，一个章节一个压缩文件
-        # level 也可以配成 album，表示一个本子对应一个压缩文件，该压缩文件会包含这个本子的所有章节
+        # ⚠ level 参数已在 v2.6.19 废弃，打包粒度由插件所在的钩子自动推导：
+        #   配置在 after_album 下 → 整本合并为一个压缩文件
+        #   配置在 after_photo  下 → 每个章节各一个压缩文件
+        # 旧配置会自动等价迁移，无需手动修改配置文件。
+        # 迁移示例：
+        #   旧：after_album + level: photo  →  等价于：after_photo（不写 level）
+        #   旧：after_album + level: album  →  等价于：after_album（不写 level）
 
         filename_rule: Ptitle # 压缩文件的命名规则
         # 请注意⚠ [https://github.com/hect0x7/JMComic-Crawler-Python/issues/223#issuecomment-2045227527]
-        # filename_rule和level有对应关系
-        # 如果level=[photo], filename_rule只能写Pxxx
-        # 如果level=[album], filename_rule只能写Axxx
+        # filename_rule和所在钩子有对应关系
+        # 如果配置在 after_photo 下, filename_rule只能写Pxxx
+        # 如果配置在 after_album 下, filename_rule只能写Axxx
 
         zip_dir: D:/jmcomic/zip/ # 压缩文件存放的文件夹
 
@@ -245,7 +250,7 @@ plugins:
         # dir_rule: # 新配置项，可取代旧的zip_dir和filename_rule
         #   base_dir: D:/jmcomic-zip
         #   rule: 'Bd / {Atitle} / [{Pid}]-{Ptitle}.zip'  # 设置压缩文件夹规则，中间Atitle表示创建一层文件夹，名称是本子标题。[{Pid}]-{Ptitle}.zip 表示压缩文件的命名规则(需显式写出后缀名)
-        # 使用此方法指定压缩包存储路径则无需和level对应
+        # 使用此方法指定压缩包存储路径则无需和所在钩子对应
 
         delete_original_file: true # 压缩成功后，删除所有原文件和文件夹
 

assets/docs/sources/tutorial/13_export_and_feature.md

@@ -89,7 +89,7 @@ download_photo('456', option, extra=Feature.export_pdf)
 
 ### 2.5 智能适配规则
 
-内置的导出 Feature 会根据调用的 API **自动适配**参数（命名规则、打包级别等）：
+内置的导出 Feature 会根据调用的 API **自动适配**参数（命名规则、打包粒度等）：
 
 | 调用方式 | Feature.export_pdf | Feature.export_zip | Feature.export_long_img |
 |---------|-------------------|-------------------|----------------------|

src/jmcomic/jm_feature.py

@@ -106,7 +106,7 @@ def __call__(self, **kwargs):
     def invoke(self, option, feature_from=None, **context):
         """
         执行此 Feature 对应的插件。
-        根据 feature_from 动态适配 filename_rule 和 level 等参数。
+        根据 feature_from 动态适配 filename_rule 等参数。
         """
         pclass = JmModuleConfig.REGISTRY_PLUGIN.get(self.plugin_key)
         if pclass is None:
@@ -127,29 +127,24 @@ def _adapt_kwargs(self, feature_from):
         """
         根据 feature_from 动态适配参数：
         - filename_rule 前缀：download_album → A前缀，download_photo → P前缀
-        - level：download_album → 'album'，download_photo → 'photo'
 
         注意：用户通过 __call__ 显式传入的参数（记录在 _user_keys 中）不会被适配。
         """
         kwargs = self.kwargs.copy()
 
         if feature_from == 'download_album':
-            # album 模式：P前缀规则 → A前缀规则, level → album
+            # album 模式：P前缀规则 → A前缀规则
             if 'filename_rule' not in self._user_keys and 'filename_rule' in kwargs:
                 rule = kwargs['filename_rule']
                 if rule and rule[0] == 'P':
                     kwargs['filename_rule'] = 'A' + rule[1:]
-            if 'level' not in self._user_keys and 'level' in kwargs and kwargs['level'] == 'photo':
-                kwargs['level'] = 'album'
 
         elif feature_from == 'download_photo':
-            # photo 模式：A前缀规则 → P前缀规则, level → photo
+            # photo 模式：A前缀规则 → P前缀规则
             if 'filename_rule' not in self._user_keys and 'filename_rule' in kwargs:
                 rule = kwargs['filename_rule']
                 if rule and rule[0] == 'A':
                     kwargs['filename_rule'] = 'P' + rule[1:]
-            if 'level' not in self._user_keys and 'level' in kwargs and kwargs['level'] == 'album':
-                kwargs['level'] = 'photo'
 
         return kwargs
 
@@ -187,9 +182,8 @@ def __repr__(self):
 
 
 # 预定义特性（用插件类的 plugin_key 引用，附带默认参数）
-# filename_rule 和 level 会根据 feature_from 在 invoke 时动态适配：
-#   download_album → A前缀 + level=album
-#   download_photo → P前缀 + level=photo
+# filename_rule 会根据 feature_from 在 invoke 时动态适配 A/P 前缀
+# zip 的打包粒度由插件根据上下文（album/photo）自动推导，无需 level 参数
 Feature.export_pdf = PluginFeature(Img2pdfPlugin.plugin_key, pdf_dir='./', filename_rule='Atitle')
-Feature.export_zip = PluginFeature(ZipPlugin.plugin_key, level='photo', zip_dir='./', filename_rule='Ptitle')
+Feature.export_zip = PluginFeature(ZipPlugin.plugin_key, zip_dir='./', filename_rule='Ptitle')
 Feature.export_long_img = PluginFeature(LongImgPlugin.plugin_key, img_dir='./', filename_rule='Pid')

src/jmcomic/jm_option.py

@@ -330,6 +330,52 @@ def compatible_with_old_versions(cls, dic):
         if 'plugin' in dic:
             dic['plugins'] = dic.pop('plugin')
 
+        # 3: zip 插件 level 参数迁移
+        # level 已废弃，打包粒度由所在钩子上下文自动推导
+        plugins = dic.get('plugins', {})
+        if isinstance(plugins, dict):
+            cls._migrate_zip_level(plugins)
+
+    @classmethod
+    def _migrate_zip_level(cls, plugins: dict):
+        """
+        zip 插件 level 参数迁移。
+
+        level 已废弃，打包粒度由所在钩子的上下文自动推导。
+        迁移规则：level='album' → 确保在 after_album；其他 → 确保在 after_photo。
+        """
+        for group in ['after_album', 'after_photo']:
+            plugin_list = plugins.get(group)
+            if not isinstance(plugin_list, list):
+                continue
+            i = 0
+            while i < len(plugin_list):
+                pinfo = plugin_list[i]
+                if pinfo.get('plugin') != 'zip':
+                    i += 1
+                    continue
+                kwargs = pinfo.get('kwargs') or {}
+                if 'level' not in kwargs:
+                    # 旧版本默认值是 'photo'
+                    level = 'photo'
+                else:
+                    level = kwargs.pop('level')
+
+                if group == 'after_album' and level != 'album':
+                    # after_album + level=photo → 等价迁移到 after_photo
+                    plugins.setdefault('after_photo', []).append(pinfo)
+                    plugin_list.pop(i)
+                    jm_log('option.migrate',
+                           f'[zip 插件迁移] level 参数已废弃，打包粒度由所在钩子自动推导。'
+                           f'已自动将 after_album 下的 zip(level={level!r}) 等价迁移到 after_photo。'
+                           f'等价写法：将 zip 插件从 after_album 移至 after_photo 并删除 level 配置项。')
+                else:
+                    if level != 'photo':
+                        jm_log('option.migrate',
+                               f'[zip 插件迁移] level 参数已废弃，已自动移除。'
+                               f'打包粒度由所在钩子自动推导（{group} → {level}）。')
+                    i += 1
+
     def deconstruct(self) -> Dict:
         return {
             'version': JmModuleConfig.JM_OPTION_VER,

src/jmcomic/jm_plugin.py

@@ -321,7 +321,7 @@ def invoke(self,
                album: JmAlbumDetail = None,
                photo: JmPhotoDetail = None,
                delete_original_file=False,
-               level='photo',
+               level=None,
                filename_rule='Ptitle',
                suffix='zip',
                zip_dir='./',
@@ -332,6 +332,9 @@ def invoke(self,
         from .jm_downloader import JmDownloader
         downloader: JmDownloader
         self.downloader = downloader
+        # level 自动推导：有 album 则合并打包，只有 photo 则单章打包
+        if level is None:
+            level = 'album' if album is not None else 'photo'
         self.level = level
         self.delete_original_file = delete_original_file