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

plugins/doc/skills/xlsx-to-md/SKILL.md

@@ -13,7 +13,8 @@ description: 将 Excel .xlsx 工作簿转换为 Markdown，按工作表提取表
 - 默认保留公式文本；只有用户希望读取工作簿内已有缓存值时才使用 `--values`。转换器不会计算公式。
 - 合并单元格默认将锚点值填充到合并区域，可用 `--merged anchor` 仅保留左上角值。
 - 默认在输入文件旁生成同名 `.md`，已存在时停止；覆盖必须获得用户确认并传入 `--force`。
-- 不提取宏、图表、批注、数据验证、条件格式或图片，也不自动安装依赖。
+- 转换依赖 Python 包 `openpyxl`。优先使用 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}")