fix(codex): 完善独立运行与文档转换兼容性

plugins/doc/skills/xlsx-to-md/scripts/convert.py

@@ -5,12 +5,10 @@ from __future__ import annotations
 
 import argparse
 import datetime as dt
+import importlib.util
 import sys
 from pathlib import Path
 
-from openpyxl import load_workbook
-
-
 def display(value: object) -> str:
     """将单元格值转换为稳定、可读且适合表格的文本。"""
 
@@ -59,6 +57,9 @@ def render_sheet(title: str, rows: list[list[str]]) -> str:
 def convert(source: Path, output: Path, values_only: bool, merged_mode: str) -> tuple[int, int, int, list[str]]:
     """打开工作簿、转换全部工作表并写入 UTF-8 Markdown。"""
 
+    # 第三方库在真正读取工作簿时才加载，使 --help 和参数校验可在干净环境中执行。
+    from openpyxl import load_workbook
+
     workbook = load_workbook(source, read_only=False, data_only=values_only)
     sections = [f"# {source.stem}"]
     row_count = merged_count = 0
@@ -94,9 +95,26 @@ def main(argv: list[str] | None = None) -> int:
         print("错误：输出文件必须是 Markdown", file=sys.stderr); return 2
     if output.exists() and not args.force:
         print(f"错误：输出文件已存在：{output}", file=sys.stderr); return 1
+    # 在创建输出目录前完成依赖预检，保证缺少运行库时不会留下空目录或半成品。
+    if importlib.util.find_spec("openpyxl") is None:
+        print(
+            "错误：缺少 openpyxl。请使用 Codex 工作区依赖运行时，"
+            "或在已获授权的本地 Python 环境中安装 openpyxl 后重试。",
+            file=sys.stderr,
+        )
+        return 3
     output.parent.mkdir(parents=True, exist_ok=True)
     try:
         sheets, rows, merged, warnings = convert(source, output, args.values, args.merged)
+    except ModuleNotFoundError as error:
+        if error.name == "openpyxl":
+            print(
+                "错误：缺少 openpyxl。请使用 Codex 工作区依赖运行时，"
+                "或在已获授权的本地 Python 环境中安装 openpyxl 后重试。",
+                file=sys.stderr,
+            )
+            return 3
+        raise
     except (OSError, ValueError) as error:
         print(f"错误：{error}", file=sys.stderr); return 1
     print(f"Markdown：{output}")