add debug log

Author: licyk

README.md

@@ -59,6 +59,7 @@ _✨一站式鼠标指针转换与管理工具_
     - [从系统中卸载 ImageMagick](#从系统中卸载-imagemagick)
   - [更新 Ani2xcur CLI](#更新-ani2xcur-cli)
   - [查看 Ani2xcur CLI 使用的环境变量](#查看-ani2xcur-cli-使用的环境变量)
+  - [调试日志](#调试日志)
   - [查看 Ani2xcur CLI 版本信息](#查看-ani2xcur-cli-版本信息)
 - [使用的项目](#使用的项目)
 - [许可证](#许可证)
@@ -253,6 +254,22 @@ ani2xcur env
 ```
 
 
+## 调试日志
+临时排查转换、安装或桌面刷新问题时，可以使用全局 `--debug` 选项输出关键链路日志：
+
+```bash
+ani2xcur --debug cursor set size 32 > log.txt 2>&1
+```
+
+也可以继续使用环境变量开启 debug 日志：
+
+```bash
+ANI2XCUR_LOGGER_LEVEL=10 ani2xcur cursor set theme Blue > log.txt 2>&1
+```
+
+调试日志会记录命令、会话类型、Xcursor 相关环境变量和转换摘要，不会输出完整环境变量或光标文件二进制内容。
+
+
 ## 查看 Ani2xcur CLI 版本信息
 ```bash
 ani2xcur version

ani2xcur/cli/app.py

@@ -1,7 +1,9 @@
 """入口文件"""
 
+import logging
 import sys
 import traceback
+from typing import Annotated
 
 import typer
 from click.exceptions import Abort, ClickException, Exit
@@ -44,13 +46,34 @@
 )
 
 
+def _enable_debug_logging() -> None:
+    """启用调试日志输出。"""
+    logging.getLogger(LOGGER_NAME).setLevel(logging.DEBUG)
+    logger.debug("已启用 debug 日志")
+
+
 def get_app() -> typer.Typer:
     """获取 Ani2xcur 命令行应用
 
     Returns:
         typer.Typer: Ani2xcur 命令行应用
     """
     app = typer_factory("鼠标指针转换、管理和 ImageMagick 辅助管理的命令行工具")
+
+    @app.callback()
+    def _main_callback(
+        debug: Annotated[
+            bool,
+            typer.Option(
+                "--debug",
+                help="输出调试日志, 便于排查转换、安装和桌面刷新问题",
+            ),
+        ] = False,
+    ) -> None:
+        """处理全局命令行选项。"""
+        if debug:
+            _enable_debug_logging()
+
     app.command(help="显示 Ani2xcur 和其他组件的当前版本", name="version")(version)
     app.command(help="更新 Ani2xcur", name="update")(update)
     app.command(help="列出 Ani2xcur 所使用的环境变量", name="env")(env)

ani2xcur/cmd.py

@@ -59,6 +59,15 @@
     color=LOGGER_COLOR,
 )
 
+DEBUG_ENV_KEYS = (
+    "DISPLAY",
+    "WAYLAND_DISPLAY",
+    "XDG_SESSION_TYPE",
+    "XCURSOR_THEME",
+    "XCURSOR_SIZE",
+)
+"""命令调试日志中允许展示的环境变量键。"""
+
 
 def preprocess_command(
     command: list[str] | str,
@@ -89,6 +98,40 @@ def preprocess_command(
         return command
 
 
+def _debug_env_summary(
+    env: dict[str, str],
+) -> dict[str, str]:
+    """提取命令调试日志中允许展示的环境变量。
+
+    Args:
+        env (dict[str, str]): 进程环境变量。
+    Returns:
+        dict[str, str]: 允许写入日志的环境变量摘要。
+    """
+    return {key: env[key] for key in DEBUG_ENV_KEYS if key in env}
+
+
+def _debug_text_summary(
+    text: str | None,
+    limit: int = 500,
+) -> str | None:
+    """生成命令输出的短摘要。
+
+    Args:
+        text (str | None): 命令输出内容。
+        limit (int): 最大保留长度。
+    Returns:
+        str | None: 输出摘要。
+    """
+    if text is None:
+        return None
+
+    text = text.strip()
+    if len(text) <= limit:
+        return text
+    return f"{text[:limit]}...<已截断 {len(text) - limit} 个字符>"
+
+
 def run_cmd(
     command: str | list[str],
     custom_env: dict[str, str] | None = None,
@@ -132,9 +175,23 @@ def run_cmd(
     if not live:
         kwargs["stdout"] = kwargs["stderr"] = subprocess.PIPE
 
-    logger.debug("执行命令的参数: %s", kwargs)
+    logger.debug(
+        "执行命令: command=%s, cwd=%s, shell=%s, live=%s, check=%s, env=%s",
+        command_to_exec,
+        cwd,
+        shell,
+        live,
+        check,
+        _debug_env_summary(custom_env),
+    )
 
     result: subprocess.CompletedProcess[str] = subprocess.run(**kwargs)  # pylint: disable=subprocess-run-check
+    logger.debug(
+        "命令执行完成: returncode=%s, stdout=%r, stderr=%r",
+        result.returncode,
+        _debug_text_summary(result.stdout),
+        _debug_text_summary(result.stderr),
+    )
 
     if check and result.returncode != 0:
         errors = [

ani2xcur/cursor_conversion/convert.py

@@ -109,6 +109,12 @@ def win_cursor_to_x11(
 
         # 转换鼠标指针文件
         logger.debug("要进行转换的鼠标指针列表: %s", win2x_path_list)
+        logger.debug(
+            "Windows -> Linux 转换计划: convert=%s, complete=%s, links=%s",
+            len(win2x_path_list),
+            len(completed_cursor_list),
+            len(link_file_list),
+        )
         for name, src, dst in tqdm(win2x_path_list, desc="转换鼠标指针文件"):
             win2x_args["input_file"] = src
             win2x_args["output_path"] = cursors_dir
@@ -206,18 +212,43 @@ def _normalize_xcursor_theme_files(
         xcursor_sizes (list[int] | None): 目标名义尺寸列表。
     """
     target_sizes = DEFAULT_XCURSOR_SIZES if xcursor_sizes is None else xcursor_sizes
+    normalized_count = 0
+    skipped_count = 0
+    logger.debug("开始补齐主题 Xcursor 尺寸: cursors_dir='%s', target_sizes=%s", cursors_dir, target_sizes)
     for cursor_file in cursors_dir.iterdir():
-        if cursor_file.is_symlink() or not cursor_file.is_file():
+        if cursor_file.is_symlink():
+            skipped_count += 1
+            logger.debug("跳过 Xcursor 尺寸补齐软链接: '%s'", cursor_file)
+            continue
+        if not cursor_file.is_file():
+            skipped_count += 1
+            logger.debug("跳过 Xcursor 尺寸补齐非文件路径: '%s'", cursor_file)
             continue
 
         try:
             frames = parse_blob(cursor_file.read_bytes())
+            source_sizes = sorted({cursor.nominal for frame in frames for cursor in frame.images})
             normalize_xcursor_sizes(frames, target_sizes)
         except ValueError as e:
+            skipped_count += 1
             logger.debug("跳过无法补齐尺寸的光标文件: '%s', 原因: %s", cursor_file, e)
             continue
 
         cursor_file.write_bytes(to_xcursor(frames))
+        normalized_count += 1
+        target_summary = sorted({cursor.nominal for frame in frames for cursor in frame.images})
+        logger.debug(
+            "补齐 Xcursor 文件尺寸完成: '%s', source_sizes=%s, target_sizes=%s",
+            cursor_file,
+            source_sizes,
+            target_summary,
+        )
+    logger.debug(
+        "主题 Xcursor 尺寸补齐完成: cursors_dir='%s', normalized=%s, skipped=%s",
+        cursors_dir,
+        normalized_count,
+        skipped_count,
+    )
 
 
 def x11_cursor_to_win(
@@ -262,6 +293,7 @@ def x11_cursor_to_win(
 
         # 转换鼠标指针文件
         logger.debug("要进行转换的鼠标指针列表: %s", x2win_path_list)
+        logger.debug("Linux -> Windows 转换计划: convert=%s", len(x2win_path_list))
         for name, src, dst in tqdm(x2win_path_list, desc="转换鼠标指针文件"):
             x2win_args["input_file"] = src
             x2win_args["output_path"] = cursors_dir

ani2xcur/cursor_conversion/native_cursor/parsers.py

@@ -9,7 +9,15 @@
 
 from PIL import Image
 
+from ani2xcur.config import LOGGER_COLOR, LOGGER_LEVEL, LOGGER_NAME
 from ani2xcur.cursor_conversion.native_cursor.models import CursorFrame, CursorImage
+from ani2xcur.logger import get_logger
+
+logger = get_logger(
+    name=LOGGER_NAME,
+    level=LOGGER_LEVEL,
+    color=LOGGER_COLOR,
+)
 
 CUR_MAGIC = b"\x00\x00\x02\x00"
 PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
@@ -41,10 +49,13 @@ def parse_blob(blob: bytes) -> list[CursorFrame]:
         ValueError: 光标文件格式不受支持或文件内容损坏时抛出。
     """
     if blob.startswith(CUR_MAGIC):
+        logger.debug("识别到 Windows CUR 光标文件")
         return parse_cur(blob)
     if _is_ani(blob):
+        logger.debug("识别到 Windows ANI 光标文件")
         return parse_ani(blob)
     if blob.startswith(XCURSOR_MAGIC):
+        logger.debug("识别到 Xcursor 光标文件")
         return parse_xcursor(blob)
     raise ValueError("Unsupported cursor file format")
 
@@ -67,6 +78,7 @@ def parse_cur(blob: bytes) -> list[CursorFrame]:
         raise ValueError("Not a CUR file")
     if image_count <= 0:
         raise ValueError("CUR file does not contain images")
+    logger.debug("解析 CUR 文件: image_count=%s", image_count)
 
     entries_start = ICON_DIR.size
     entries_end = entries_start + image_count * ICON_DIR_ENTRY.size
@@ -94,6 +106,7 @@ def parse_cur(blob: bytes) -> list[CursorFrame]:
             )
         )
 
+    logger.debug("CUR 文件解析完成: sizes=%s", [image.image.size for image in images])
     return [CursorFrame(images=images)]
 
 
@@ -147,6 +160,8 @@ def parse_ani(blob: bytes) -> list[CursorFrame]:
 
     frame_count = frame_count or len(icon_frames)
     step_count = step_count or frame_count
+    has_order_chunk = order is not None
+    has_delay_chunk = delays is not None
     order = list(range(frame_count)) if order is None else order
     delays = [display_rate for _ in range(step_count)] if delays is None else delays
 
@@ -155,6 +170,14 @@ def parse_ani(blob: bytes) -> list[CursorFrame]:
     if len(delays) != step_count:
         raise ValueError(f"Wrong animation rate size: {len(delays)}, expected {step_count}")
 
+    logger.debug(
+        "解析 ANI 文件: frame_count=%s, step_count=%s, icon_frames=%s, has_seq=%s, has_rate=%s",
+        frame_count,
+        step_count,
+        len(icon_frames),
+        has_order_chunk,
+        has_delay_chunk,
+    )
     sequence: list[CursorFrame] = []
     for frame_index, delay in zip(order, delays):
         if frame_index >= len(icon_frames):
@@ -163,6 +186,7 @@ def parse_ani(blob: bytes) -> list[CursorFrame]:
         frame.delay = delay / 60
         sequence.append(frame)
 
+    logger.debug("ANI 文件解析完成: sequence_frames=%s", len(sequence))
     return sequence
 
 
@@ -194,6 +218,7 @@ def parse_xcursor(blob: bytes) -> list[CursorFrame]:
     for _ in range(toc_size):
         chunks.append(XCURSOR_TOC_CHUNK.unpack_from(blob, offset))
         offset += XCURSOR_TOC_CHUNK.size
+    logger.debug("解析 Xcursor 文件: toc_size=%s", toc_size)
 
     images_by_size: dict[int, list[tuple[CursorImage, float]]] = defaultdict(list)
     for chunk_type, chunk_subtype, position in chunks:
@@ -224,6 +249,7 @@ def parse_xcursor(blob: bytes) -> list[CursorFrame]:
 
     if not images_by_size:
         raise ValueError("Xcursor file does not contain images")
+    logger.debug("Xcursor 文件尺寸集合: %s", sorted(images_by_size))
 
     frame_counts = {len(images) for images in images_by_size.values()}
     if len(frame_counts) != 1:
@@ -238,6 +264,7 @@ def parse_xcursor(blob: bytes) -> list[CursorFrame]:
             raise ValueError("Xcursor animations must use the same delay for every size in a frame")
         frames.append(CursorFrame(images=images, delay=frame_items[0][1]))
 
+    logger.debug("Xcursor 文件解析完成: frame_count=%s", len(frames))
     return frames