故障排查¶
命令或选项被拒绝¶
根选项必须放在命令组之前：
使用 shodan-skill GROUP ACTION --help 查看已安装版本的参数契约。程序有意拒绝长选项缩写。已弃用的下划线命令名可能发出兼容性警告。
认证失败，退出码 3¶
检查 SHODAN_API_KEY、~/.shodan/api_key 或 ~/.config/shodan/api_key 是否包含预期密钥。诊断时不要打印密钥。如果两个文件都存在，旧的 .shodan 路径优先。
授权失败，退出码 4¶
账户已经认证，但缺少权限。常见情况包括全局数据流、Trends、数据集、组织成员和互联网范围扫描。使用 shodan-skill account api-info 确认账户套餐。
积分失败，退出码 5¶
检查账户余额和请求操作。消耗积分的 GET 不会自动重试。在审阅服务结果和账户状态前，不要假定失败请求可以安全重复。
网络或超时失败，退出码 6 和 8¶
CLI 忽略环境代理。网络确实需要代理时，设置经过审阅的 SHODAN_PROXY 或根选项 --proxy。只有在预期服务行为确有需要时才调整有限的连接、读取或数据流超时。
数据流在达到 --limit 前正常 EOF 仍属于网络失败。需要继续时使用有界重连。
下载或完整性失败，退出码 7¶
需要续传时保留 .part 文件；只有在可以接受替换时才使用 --overwrite。大小或 SHA-1 不匹配会阻止最终完成。除非明确接受风险且元数据确实不适用，否则不要使用 --no-verify。
严格模式门禁，退出码 2¶
添加完整的 --confirm 或 --yes。扫描和监控网络还需要完整的 --acknowledge-authorization。如果预期策略是默认 direct 模式，也可以恢复 direct。
报告问题¶
提供版本、平台、移除秘密信息后的命令结构、退出码和脱敏 stderr。不得附带 API Key、代理凭据、签名 URL、通知器秘密信息、账户响应或未审阅的主机数据集。安全问题应通过仓库安全策略私下报告。