🧰 技能依赖诊断工具

与 openclaw doctor 互补 — doctor 检查网关/配置/服务；
本工具检查技能运行时依赖（二进制文件、版本、库、字体）。

使用此工具可在技能运行时失败前检测缺失或损坏的依赖。

检查内容

• - 🔎 二进制文件存在性 — 扫描 skills/*/SKILL.md 中声明的 requires.bins 与 $PATH 对比
• 📌 版本约束 — 支持 node>=18、python3>=3.10 语法并进行实际版本探测
• 🧩 共享库 — 通过 ldconfig 检查 Playwright/Chromium 原生依赖（Linux）
• 🔤 中日韩字体 — 通过 fc-list 防止 PDF 出现方块字（□）
• 🔗 传递性原生依赖 — 例如 playwright → 13 个 .so 库
• 📦 项目预设 通过 --check-dir：

- Node（package.json）、Python（pyproject.toml / requirements.txt）、Docker（Dockerfile） - 交叉引用 npm/pip 包与系统依赖提示

• - 🎚️ Playwright 探测 — Node + Python 检测及 Chromium 无头启动冒烟测试
• 📦 依赖配置文件 — --profile slidev、--profile whisper、--profile pdf-export
• 🔌 插件系统 — 通过 Python 入口点的第三方检查器

安装

bash
pip install skill-deps-doctor

为兼容性保留旧命令 skill-deps-doctor。

使用方法

基本检查

bash
skill-deps-doctor --skills-dir /path/to/workspace/skills

扫描项目目录（带探测）

bash
skill-deps-doctor --skills-dir ./skills --check-dir ./project --probe

单体仓库递归扫描

bash
skill-deps-doctor --skills-dir ./skills --check-dir ./monorepo --recursive

依赖配置文件

bash
skill-deps-doctor --skills-dir ./skills --profile slidev --profile pdf-export
skill-deps-doctor --skills-dir ./skills --list-profiles

生成修复脚本

bash
skill-deps-doctor --skills-dir ./skills --fix > fix.sh

依赖关系图

bash
skill-deps-doctor --skills-dir ./skills --graph tree
skill-deps-doctor --skills-dir ./skills --graph dot | dot -Tsvg -o deps.svg

跨平台修复矩阵

bash
skill-deps-doctor --skills-dir ./skills --platform-matrix

JSON 输出（CI）

bash
skill-deps-doctor --skills-dir ./skills --json

环境快照 + 基线回归门控

bash

保存基线

skill-deps-doctor --skills-dir ./skills --snapshot baseline.json

对新问题设置门控

skill-deps-doctor --skills-dir ./skills --baseline baseline.json --fail-on-new

退出码：0 = 通过，2 = 错误，3 = 发现与基线不同的新问题

验证提示模式与插件契约

bash
skill-deps-doctor --skills-dir ./skills --validate-hints
skill-deps-doctor --skills-dir ./skills --validate-plugins

自定义提示覆盖

bash
skill-deps-doctor --skills-dir ./skills --hints-file my-hints.yaml

详细程度

bash
skill-deps-doctor --skills-dir ./skills -v # 显示所有（包括信息）
skill-deps-doctor --skills-dir ./skills -q # 仅显示错误
skill-deps-doctor --skills-dir ./skills --no-plugins # 跳过第三方插件

回退包装器（仓库/开发布局）

bash
python {baseDir}/scripts/skill-deps-doctor.py --skills-dir ./skills

注意事项

• - Linux：通过 ldconfig 检查共享库；通过 fc-list 检查字体；自动将 apt 提示适配为主机包管理器（dnf / yum / apk / pacman）。
• macOS / Windows：二进制文件、版本和字体检查均可工作；Playwright 检查依赖探测（--probe）。
• CI 集成：使用 --json 获取机器可读输出，使用 --snapshot + --baseline --fail-on-new 进行回归门控。