semantic_* 分析器警告（缺 API key）

你会遇到什么

skillspector --version 或 scan 时，输出 WARNING [skillspector.graph] Skipping analyzer semantic_developer_intent: required API key is missing。你以为是配置坏了、或者功能不全——其实没配 key 时自动跳过是正常行为，不是错误。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

LLM 语义分析器需要 OPENAI_API_KEY（或 SKILLSPECTOR_PROVIDER 配置）才能跑；没有 key 时它自动跳过，只输出一条 WARNING：

警告不影响退出码与报告生成（本市场实测：3 条语义跳过警告，exit 0，扫描正常）。

skillspector 的扫描器是两级架构：规则检测（YARA/模式匹配）在本地跑，不依赖外部服务；语义分析（semantic_*）要调用 LLM——它把“这段技能内容有没有恶意意图”交给大模型判断，而调用 LLM 需要 API key。没有 key 时的行为是降级而非报错：扫描器检测到没 key，跳过语义分析器、打一条 WARNING、继续跑完规则检测。

这是“可选依赖”的标准设计：核心功能（规则检测）不依赖外部服务，增强功能（语义分析）按可用性启用。

WARNING 不是错误——退出码和报告都正常生成，只是报告里少了语义分析的维度。判断“扫描结果完整吗”也有固定口径：看 WARNING 说的是什么（跳过的是增强项还是核心项）——跳过语义分析不影响规则检测的结论，但如果你依赖语义分析（比如要判断恶意意图），就得先配 key 再扫。

一步步来

1. 不配 key：静态扫描完全可用 — 必做

skillspector scan <目标目录> --no-llm

规则检测（YARA/模式）不依赖 LLM，该检出的照样检出。

2. 要语义分析：配 key — 排查

export OPENAI_API_KEY=你的key

或按项目文档设置 SKILLSPECTOR_PROVIDER。

3. 警告可安全忽略 — 必做

WARNING 不影响退出码与报告生成；--version 和 scan 照常工作（实测 exit 0）。

怎么确认修好了

扫描正常完成（实测输出形态）：

skillspector scan <目录>
→ 3 条 semantic 跳过警告 + 扫描结果正常输出，exit 0

或配 key 后警告消失，semantic 分析器参与评分。

其它环境的表现

症状

skillspector --version / scan 输出：

WARNING [skillspector.graph] Skipping analyzer semantic_developer_intent: required API key is missing

原因

LLM 语义分析器需要 OPENAI_API_KEY（或 SKILLSPECTOR_PROVIDER 配置）；没 key 时自动跳过——不是错误。

解法

1. 不配 key：静态扫描完全可用（--no-llm），规则检测（YARA/模式）不依赖 LLM。
2. 要语义分析：配 OPENAI_API_KEY 环境变量或按文档设 SKILLSPECTOR_PROVIDER。
3. 警告可安全忽略，不影响退出码与报告生成。

本市场实测安装 / 卸载（2026-08-28）

安装（manifest install.cmd，隔离 venv /tmp/l34-sp/venv，Python 3.14.4）：

[install] curl -sL wheel（gh-proxy，468K）→ pip install -i 清华镜像 skillspector-2.10.0-py3-none-any.whl
依赖：boto3/httpx/langchain-*/langgraph/openai/pydantic/yara-python（源码构建成功）等 60+ 包
SkillSpector v2.10.0（3 条 semantic 跳过警告，exit 0）
[install] exit=0

卸载（manifest uninstall.cmd + 修正后的 verify）：

[uninstall] pip uninstall -y skillspector → Successfully uninstalled skillspector-2.10.0
[uninstall] 验证: skillspector removed: OK（fresh shell，verify exit=0）

• 完整日志：实测记录（本地留存）。
• PyPI 缺失排查：实测记录（本地留存）。
• 扫描冒烟：实测记录（本地留存）（构造样本检出 2 个 HIGH，只读扫描确认）。
• 未能实测：MCP server 模式实跑、LLM 语义分析（无 API key）、baseline 命令。

冲突标注

• possible-compatible（推断态）：全部收录条目——skillspector 只读扫描（扫描前后目录零新增）、无 daemon、无配置写面、无端口；CLI 面与任何条目共存无共享写面（矩阵对子）。
• 备注：LLM 语义分析如需与其它工具共用 API key 环境变量，属配置面注意项（非写面冲突）。

名称混淆

• 大小写：项目名 SkillSpector（NVIDIA 开源），命令 skillspector。
• 渠道：PyPI 上无此包（见症状 1），检索/安装认准 GitHub 仓库 NVIDIA/SkillSpector 与 release 资产。
• 与其它技能安全/检查类工具区分（如 agent-skills 等技能包，功能不同）。

判据（验证状态）

• 症状清单：
• [x] pip install 找不到包 → 发行渠道 = GitHub Release wheel（本市场三路复核 + 闭环实测）
• [x] Failed building wheel for yara-python → build-essential python3-dev（CSDN 文库 2026-07；本市场源码构建路径实测）
• [x] 可选 mcp 依赖缺失导致 stdio 挂起（Issue #199）
• [x] 依赖版本冲突警告（CSDN 文库 2026-07；venv 隔离解法实测）
• [x] 风险评分>50 输出 DO NOT INSTALL（CSDN 2026-06；评分逻辑说明）
• [x] semantic_* 分析器缺 key 警告（本市场实测）
• 实测步骤：
• [x] 安装验证（manifest install.cmd 修正后：wheel 直装 + 依赖走镜像 → SkillSpector v2.10.0 exit 0）
• [x] 卸载验证（manifest uninstall.cmd：pip uninstall → verify 零残留 exit 0）
• [x] 网络/镜像场景（gh-proxy wheel 下载 + 清华镜像依赖；）
• [x] 未能实测项：MCP 模式实跑、LLM 语义分析（无 key）、baseline

验收

• [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（6 症状）
• [x] 名称混淆已点名（大小写；PyPI 无包；渠道认准 GitHub）
• [x] check-words HARD 0
• [x] validate 通过
• [x] 未碰 GitHub / 未用任何账号