fix: PR Review 修复

Author: hect0x7

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

@@ -54,7 +54,7 @@ download_album('123', option, extra=Feature.export_pdf + Feature.export_zip)
 
 # 也支持列表语法，|语法
 download_album('123', option, extra=[Feature.export_pdf, Feature.export_zip])
-download_album('123', option, extra=Feature.export_pdf ｜ Feature.export_zip)
+download_album('123', option, extra=Feature.export_pdf | Feature.export_zip)
 ```
 
 效果同pdf，会在本子下载完以后，额外在当前工作目录下，生成包含所有本子图片的 PDF 文件和 ZIP 文件：

src/jmcomic/jm_feature.py

@@ -16,8 +16,6 @@
     download_album(id, option, extra=[Feature.export_pdf, Feature.export_zip])
     download_album(id, option, extra=Feature.export_pdf + Feature.export_zip)
 """
-from typing import LiteralString
-
 from .jm_plugin import *
 
 
@@ -81,8 +79,6 @@ class PluginFeature(Feature):
     def __init__(self, plugin_key, **kwargs):
         self.plugin_key = plugin_key
         self.kwargs = kwargs
-        # 用户通过 __call__ 显式传入的参数名，这些参数不会被 _adapt_kwargs 动态适配
-        self._user_keys: set = set()
 
     def should_invoke(self, feature_from: str, when: str) -> bool:
         """
@@ -100,8 +96,6 @@ def __call__(self, **kwargs):
         new_kwargs = self.kwargs.copy()
         new_kwargs.update(kwargs)
         new_instance = PluginFeature(self.plugin_key, **new_kwargs)
-        # 记录用户显式传入的参数名，这些参数不被动态适配
-        new_instance._user_0keys = set(kwargs.keys())
         return new_instance
 
     def invoke(self, option: JmOption, feature_from: str, when: str, **extra):

src/jmcomic/jm_option.py

@@ -344,6 +344,29 @@ def _migrate_zip_level(cls, plugins: dict):
         level 已废弃，打包粒度由所在钩子的上下文自动推导。
         迁移规则：level='album' → 确保在 after_album；其他 → 确保在 after_photo。
         """
+
+        def log_advice(reason, plugins):
+            import yaml
+            # 意图聚焦：建议配置中只展示相关的 zip 插件，剔除其他无关插件的干扰
+            advice_plugins = {}
+            for g, plist in plugins.items():
+                zips = [p for p in plist if p.get('plugin') == 'zip']
+                if zips:
+                    advice_plugins[g] = zips
+
+            if not advice_plugins:
+                return
+
+            plugins_yml = yaml.dump({'plugins': advice_plugins}, default_flow_style=False, indent=2, sort_keys=False).strip()
+
+            jm_log('option.migrate',
+                   f'[zip 插件迁移] level 参数已过时，建议直接删除。'
+                   f'{reason}，建议参考如下的等价新写法：\n'
+                   f'```yml\n'
+                   f'{plugins_yml}\n'
+                   f'```'
+                   )
+
         for group in ['after_album', 'after_photo']:
             plugin_list = plugins.get(group)
             if not isinstance(plugin_list, list):
@@ -365,18 +388,18 @@ def _migrate_zip_level(cls, plugins: dict):
                     # after_album + level=photo → 等价迁移到 after_photo
                     plugins.setdefault('after_photo', []).append(pinfo)
                     plugin_list.pop(i)
-                    jm_log('option.migrate',
-                           f'[zip 插件迁移] level 参数已过时，建议删除level参数。'
-                           f'你的当前配置为，在本子下载完毕后按章节压缩，建议改为如下的等价新写法：\n'
-                           f'plugins:\n'
-                           f'  after_photo:\n'
-                           f'    - plugin: {pinfo["plugin"]}\n'
-                           f'      kwargs: {pinfo["kwargs"]}\n'
-                           )
+                    log_advice('你的当前配置为：在本子下载完毕后按章节压缩', plugins)
+
+                elif group == 'after_photo' and level == 'album':
+                    # after_photo + level=album → 等价迁移到 after_album
+                    plugins.setdefault('after_album', []).append(pinfo)
+                    plugin_list.pop(i)
+                    log_advice('你的当前配置为：在单章节下载完毕后对全本进行压缩', plugins)
+
                 else:
                     if level != 'photo':
                         jm_log('option.migrate',
-                               f'[zip 插件迁移] level 参数已过时，你可以直接删除该参数，不会有任何影响')
+                               '[zip 插件迁移] level 参数已过时，你可以直接删除该参数，不会有任何影响')
                     i += 1
 
     def deconstruct(self) -> Dict:

tests/test_jmcomic/test_jm_feature.py

@@ -62,27 +62,29 @@ def invoke(self, option, **kwargs):
 
     def test_adapt_kwargs(self):
         """测试 PluginFeature 参数动态适配"""
-        # download_album 模式：P前缀 → A前缀, level → album
+        when = 'after_album'
+        
         pdf = Feature.export_pdf
         adapted = pdf._adapt_plugin_kwargs('download_album', when)
-        self.assertEqual(adapted['filename_rule'], 'Atitle')  # A开头不变
+        self.assertEqual(adapted['filename_rule'], '[JM{Aid}]{Atitle}')
 
         zip_f = Feature.export_zip
         adapted = zip_f._adapt_plugin_kwargs('download_album', when)
-        self.assertEqual(adapted['filename_rule'], 'Atitle')  # Ptitle → Atitle
+        self.assertEqual(adapted['filename_rule'], '[JM{Aid}]{Atitle}')
 
         long_img = Feature.export_long_img
         adapted = long_img._adapt_plugin_kwargs('download_album', when)
-        self.assertEqual(adapted['filename_rule'], 'Aid')  # Pid → Aid
+        self.assertEqual(adapted['filename_rule'], '[JM{Aid}]{Atitle}')
 
-        # download_photo 模式：A前缀 → P前缀, level → photo
+        # download_photo 模式
+        when = 'after_photo'
         adapted = pdf._adapt_plugin_kwargs('download_photo', when)
-        self.assertEqual(adapted['filename_rule'], 'Ptitle')  # Atitle → Ptitle
+        self.assertEqual(adapted['filename_rule'], '[JM{Pid}]{Ptitle}')
 
-        # 用户显式传入的参数不被动态适配
+        # 用户显式传入的参数不被动态适配 (通过 kwargs 机制自带)
         custom = Feature.export_zip(filename_rule='Ptitle')
         adapted = custom._adapt_plugin_kwargs('download_album', when)
-        self.assertEqual(adapted['filename_rule'], 'Ptitle')  # 用户显式指定，不适配
+        self.assertEqual(adapted['filename_rule'], 'Ptitle')  # 用户显式指定，不被 setdefault 覆盖
 
     def test_download_use_feature(self):
         album_id = '438516'