v2.6.10: 文件夹名称支持繁简转换，dir_rule增加normalize_zh配置 (#486) (#485)

Author: hect0x7

README.md

@@ -142,7 +142,7 @@ jmcomic 123
 
   - 不配置也能使用，十分方便
   - 配置可以从配置文件生成，支持多种文件格式
-  - 配置点有：`请求域名` `客户端实现` `是否使用磁盘缓存` `同时下载的章节/图片数量` `图片格式转换` `下载路径规则` `请求元信息（headers,cookies,proxies）`
+  - 配置点有：`请求域名` `客户端实现` `是否使用磁盘缓存` `同时下载的章节/图片数量` `图片格式转换` `下载路径规则` `请求元信息（headers,cookies,proxies)` `中文繁/简转换` 
     等
 - **可扩展性强**
 

assets/docs/sources/option_file_syntax.md

@@ -115,6 +115,17 @@ dir_rule:
   # rule: Bd / Aauthor / (JM{Aid}-{Pindex})-{Pname}
   # {}大括号里的内容同样是写 Axxx 或 Pxxx，其他语法自行参考python f-string的语法
   # 另外，rule开头的Bd可忽略不写，因为程序会自动插入Bd
+
+  # normalize_zh: 可选。控制是否对目录/文件名中的中文进行繁简体规范化。
+  #   - None（默认）：不做任何转换，保持历史行为
+  #   - zh-cn：将中文文本规范为简体
+  #   - zh-tw：将中文文本规范为繁体
+  # 该功能依赖可选库 `zhconv`（非必需），若未安装或转换失败，程序会回退到原字符串并继续工作，不会影响下载流程。
+  # 示例：
+  # dir_rule:
+  #   base_dir: D:/a/b/c/
+  #   rule: Bd / Ptitle
+  #   normalize_zh: zh-cn
 ```
 
 ## 3. option插件配置项

assets/docs/sources/tutorial/4_module_custom.md

@@ -102,6 +102,8 @@ def custom_album_photo_image_detail_class():
     dir_rule:
         base_dir: ${workspace}
         rule: Bd_Acustom_Pcustom
+        # 可选：对目录名进行繁/简体规范化（None/zh-cn/zh-tw），默认不启用
+        # normalize_zh: zh-cn
     
     上面的Acustom，Pcustom都是自定义字段
     如果你想要使用这种自定义字段，你就需要替换默认的实体类，方式如下

assets/docs/sources/tutorial/9_custom_download_dir_name.md

@@ -58,6 +58,26 @@ D:/a/b/c/ddd/00003.webp
 除了Pxxx，你还可以写Axxx，表示这个章节所在的本子的属性xxx，详见本子实体类 JmAlbumDetail。
 
 
+## 1.1 简繁体统一（normalize_zh）
+
+在一些源站中，同一作品或章节名称可能存在简体/繁体差异，导致在不同环境下生成重复或不一致的文件夹名。v2.6.10 引入了 `dir_rule.normalize_zh` 配置，用于可选地对目录名进行繁/简体规范化。
+
+示例用法：
+
+```yaml
+dir_rule:
+  base_dir: D:/a/b/c/
+  rule: Bd / Ptitle
+  normalize_zh: zh-cn # 可选值：None（默认，不转换）/ zh-cn / zh-tw
+```
+
+说明：
+
+- 当 `normalize_zh` 为 `zh-cn` 时，会把目录名中的中文规范为简体；为 `zh-tw` 时规范为繁体；为 `None` 或不配置时维持历史行为（不转换）。
+
+- 该功能依赖可选库 `zhconv`（非必需），若未安装或转换失败，系统会回退为原始字符串并继续下载，不会导致失败。
+
+
 ## 2. 自定义字段名
 
 上述例子使用了title字段，如果你想自定义一个字段，然后在DirRule中使用自定义字段，该怎么做？

assets/option/option_test_api.yml

@@ -1,6 +1,7 @@
 # GitHub Actions 测试用
 # 移动端配置
 dir_rule:
+  normalize_zh: zh-cn
   rule: Bd_Aauthor_Aid_Pindextitle
 
 client:

src/jmcomic/__init__.py

@@ -2,7 +2,7 @@
 # 被依赖方 <--- 使用方
 # config <--- entity <--- toolkit <--- client <--- option <--- downloader
 
-__version__ = '2.6.9'
+__version__ = '2.6.10'
 
 from .api import *
 from .jm_plugin import *

src/jmcomic/jm_config.py

@@ -411,7 +411,7 @@ def new_postman(cls, session=False, **kwargs):
 
     DEFAULT_OPTION_DICT: dict = {
         'log': None,
-        'dir_rule': {'rule': 'Bd_Pname', 'base_dir': None},
+        'dir_rule': {'rule': 'Bd_Pname', 'base_dir': None, 'normalize_zh': None},
         'download': {
             'cache': True,
             'image': {'decode': True, 'suffix': None},

src/jmcomic/jm_option.py

@@ -60,10 +60,16 @@ def enable_client_cache_on_condition(cls,
 class DirRule:
     RULE_BASE_DIR = 'Bd'
 
-    def __init__(self, rule: str, base_dir=None):
+    def __init__(self, rule: str, base_dir=None, normalize_zh=None):
+        """
+        :param rule: DSL rule
+        :param base_dir: base directory
+        :param normalize_zh: 'zh-cn'|'zh-tw'| or None. 控制是否以及如何进行繁简体归一化，默认 None
+        """
         base_dir = JmcomicText.parse_to_abspath(base_dir)
         self.base_dir = base_dir
         self.rule_dsl = rule
+        self.normalize_zh = normalize_zh
         self.parser_list: List[Tuple[str, Callable]] = self.get_rule_parser_list(rule)
 
     def decide_image_save_dir(self,
@@ -88,7 +94,9 @@ def apply_rule_to_path(self, album, photo, only_album_rules=False) -> str:
                 jm_log('dir_rule', f'路径规则"{rule}"的解析出错: {e}, album={album}, photo={photo}')
                 raise e
             if parser != self.parse_bd_rule:
-                path = fix_windir_name(str(path)).strip()
+                # 根据配置 normalize_zh 进行繁简体统一
+                conv_path = JmcomicText.to_zh(str(path), self.normalize_zh)
+                path = fix_windir_name(conv_path).strip()
 
             path_ls.append(path)
 
@@ -201,6 +209,7 @@ def copy_option(self):
             dir_rule={
                 'rule': self.dir_rule.rule_dsl,
                 'base_dir': self.dir_rule.base_dir,
+                'normalize_zh': self.dir_rule.normalize_zh,
             },
             download=self.download.src_dict,
             client=self.client.src_dict,
@@ -326,6 +335,7 @@ def deconstruct(self) -> Dict:
             'dir_rule': {
                 'rule': self.dir_rule.rule_dsl,
                 'base_dir': self.dir_rule.base_dir,
+                'normalize_zh': self.dir_rule.normalize_zh,
             },
             'download': self.download.src_dict,
             'client': self.client.src_dict,

src/jmcomic/jm_toolkit.py

@@ -329,8 +329,34 @@ def find_right_pair(left_pair, i):
 
     @classmethod
     def to_zh_cn(cls, s):
-        import zhconv
-        return zhconv.convert(s, 'zh-cn')
+        # 兼容旧接口，默认转换为简体
+        return cls.to_zh(s, 'zh-cn')
+
+    @classmethod
+    def to_zh(cls, s, target=None):
+        """
+        通用的繁简体转换接口。
+
+        :param s: 待转换字符串
+        :param target: 目标编码: 'zh-cn'（简体）, 'zh-tw'（繁体），或 None 表示不转换
+        :return: 转换后的字符串（若转换失败或未安装 zhconv，返回原始字符串）
+        """
+        if s is None:
+            return s
+
+        if not target:
+            return s
+
+        try:
+            import zhconv
+            return zhconv.convert(s, target)
+        except ImportError as e:
+            jm_log('zhconv.error', '繁简转换失败，未安装zhconv，请先使用命令安装: [pip install zhconv]')
+            return s
+        except Exception as e:
+            # 如果 zhconv 不可用或转换失败，则回退原字符串
+            jm_log('zhconv.error', f'error: [{e}], s: [{s}]')
+            return s
 
     @classmethod
     def try_mkdir(cls, save_dir: str):