需要分析图片/视频、OCR、图表读取或视觉推理时，用…

当需要用 Qwen 视觉模型（VL/QVQ）理解图片或视频，包括 OCR、图表/表格读取、多图对比、截图理解、视频理解与链式视觉推理时使用。

适用场景

解决思路

1. 使用技能内文件执行和学习：默认执行 `scripts/analyze.py`，需要视觉推理用 `scripts/reason.py`，需要 OCR 用 `scripts/ocr.py`，共享辅助在 `scripts/vision_lib.py`；当默认路径失败或需要细节时按需加载 `references/execution-guide.md`、`references/curl-examples.md`、`references/visual-reasoning.md`、`references/prompt-guide.md`、`references/ocr.md`、`references/sources.md`。
2. 安全：绝不以明文输出任何 API key 或凭证；shell 中用 `$DASHSCOPE_API_KEY`，Python 中用 `os.environ["DASHSCOPE_API_KEY"]`；凭证检查只报告状态如 set/not set、valid/invalid，不报告值；不显示可能含密钥的 `.env` 或配置文件。
3. API key 未配置时：不要直接要求用户提供 key；帮助创建 `.env`，写入占位符 `DASHSCOPE_API_KEY=sk-your-key-here`，并让用户从 QianWen Console (`https://platform.qianwenai.com/home/api-keys`) 获取实际 key 替换；仅当用户明确要求时才写入实际 key 值。
4. 检测 key 类型且不暴露 key：运行 `python3 -c "import sys; sys.path.insert(0, 'scripts'); from qianwen_lib import detect_api_key_type; print(detect_api_key_type('scripts/qianwen_lib.py'))"`；输出 `token-plan` 表示 Token Plan key，只能用 Token Plan 目录中的模型；`payg` 表示按量付费 key，可用完整模型目录；`not-set` 表示未配置。
5. Token Plan 处理：获取并阅读当前 Token Plan 模型目录 `https://alioth.alicdn.com/skills-info/models/references/qianwen-token-plan-models.md`，使用其中列出的、确切的支持视觉的模型；CDN 失败时用本地回退 `cdn/references/qianwen-token-plan-models.md`；不要猜测或探测模型可用性；当任务默认模型不在 Token Plan 时，从 Qwen 视觉模型目录选择兼容替代。
6. 模型选择前：获取并阅读当前 Qwen 视觉模型目录 `https://alioth.alicdn.com/skills-info/models/references/qianwen-vision-models.md`，其中包含模型列表、基本信息、任务推荐、兼容性说明和默认值；CDN 失败时用本地回退 `cdn/references/qianwen-vision-models.md`。
7. 模型选择规则：用户指定模型则直接使用；模型选择依赖需求/场景/价格时咨询 `qianwen-model-selector` 技能；无信号且任务明确时使用模型目录中的默认模型和任务特定替代模型。
8. 模型目录是时间点快照，可能过期；做模型决策前始终查看官方模型列表 `https://www.qianwenai.com/models` 获取权威最新目录。
9. 模型详情：引导用户访问 `https://www.qianwenai.com/models/<model-name>`，将 `<model-name>` 替换为精确模型 ID，不修改或猜测 ID。
10. 动态模型查询：若 `qianwen-model-selector` 技能或 QianWen CLI 可用，用它们获取实时模型数据，例如 `qianwen models info <model>`；CLI 需要认证，见 `qianwen-usage` 技能了解登录流程。
11. 执行前 API key 检查：使用 Key Compatibility 中的非明文检测器，不要用变量存在性检查替代；无 key 时使用 `qianwen-ops-auth`（若可用）或引导在 `.env` 中配置 `DASHSCOPE_API_KEY`/`QIANWEN_API_KEY`；技能可独立安装。
12. 环境检查：执行前运行 `python3 --version`，必须为 3.9+；找不到时尝试 `python --version` 或 `py -3 --version`；Python 不可用或低于 3.9 时跳到 `references/execution-guide.md` 的 Path 2（curl）。
13. 默认执行脚本：先定位本技能安装目录（包含 SKILL.md 的目录），然后始终用完整绝对路径执行 `scripts/` 子目录下的脚本；不要假设脚本在当前工作目录；执行前不要用 `cd` 切换目录；共享基础设施在 `scripts/vision_lib.py`。
14. 脚本执行：所有脚本在前台运行，等待 stdout，不要后台运行；先运行 `python3 <this-skill-dir>/scripts/analyze.py --help`（或 `reason.py`、`ocr.py`）查看可用参数。
15. 脚本用途：`scripts/analyze.py` 用于图像理解、多图、视频、思考模式、高分辨率，默认模型从模型目录读取；`scripts/reason.py` 用于 QVQ 链式思考视觉推理、视频推理（始终流式），默认模型从模型目录读取；`scripts/ocr.py` 用于从文档、收据、表格提取 OCR 文本，默认模型从模型目录读取。
16. `--request` JSON 中只使用一个输入类型字段：`"image"` 用于单图（URL 或本地路径）；`"images"` 用于多图比较（数组）；`"video"` 用于视频文件（URL 或本地路径）；`"video_frames"` 用于帧数组。不要把视频文件用 `"image"`，要用 `"video"`。
17. 执行图像分析示例：`python3 <this-skill-dir>/scripts/analyze.py --request '{"prompt":"What is in this image?","image":"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"}' --output output/qianwen-vision/result.json --print-response`。
18. 执行视频分析示例：本地文件时 `python3 <this-skill-dir>/scripts/analyze.py --request '{"prompt":"Describe what happens in this video","video":"clip.mp4"}' --upload-files --print-response`；文件 >= 7 MB 时加 `--upload-files`。
19. 执行视觉推理示例：`python3 <this-skill-dir>/scripts/reason.py --request '{"prompt":"Solve this math problem step by step","image":"problem.png"}' --print-response`。
20. 执行 OCR 示例：`python3 <this-skill-dir>/scripts/ocr.py --request '{"image":"invoice.jpg"}' --print-response`。
21. 脚本参数：`--request '{...}'` 传 JSON 请求体；`--file path.json` 从文件加载请求；`--output path` 保存响应 JSON；`--print-response` 打印响应到 stdout；`--stream` 启用流式（思考/QVQ 自动启用）；`--upload-files` 上传本地文件到临时存储（用于 >7 MB 文件）；`--model ID` 覆盖模型（各脚本默认见目录）；`--schema path.json` 用于结构化提取的 JSON Schema。
22. 模型优先级：`--model` CLI 参数 > `--request` JSON 中的 `"model"` 字段 > 内置默认值。
23. 验证结果：退出码 `0` 且输出包含带 `choices` 字段的有效 JSON → 成功；非零退出、HTTP 错误、空响应或带 `"code"`/`"message"` 错误的 JSON → 失败；使用 `--output` 时验证响应 JSON 文件存在且包含预期内容。
24. 强制 stderr 信号检查：确认结果后扫描命令 stderr 输出中的 `[ACTION_REQUIRED]` 或 `[UPDATE_AVAILABLE]`；若有任一信号，必须先按 Update Check 处理再回复用户。
25. 失败处理：脚本失败时用错误输出匹配诊断表；无匹配则读 `references/execution-guide.md` 了解替代路径：curl（Path 2）、代码生成（Path 3）、自主解决（Path 5）；Python 完全不可用时直接跳到 Path 2（curl）。
26. 错误诊断表：`command not found: python3` → Python 不在 PATH，尝试 `python` 或 `py -3`，缺失则安装 Python 3.9+；`Python 3.9+ required` → 版本检查失败，升级 Python；`SyntaxError` near type hints → Python <3.9，升级；`QIANWEN_API_KEY/DASHSCOPE_API_KEY not found` → 从 QianWen Console 获取 key，加入 `.env`：`echo 'DASHSCOPE_API_KEY=sk-...' >> .env`，或运行 `qianwen-ops-auth`（若可用）；`HTTP 401` → 无效或不匹配 key，运行 `qianwen-ops-auth`（仅非明文检查）并验证 key；`SSL: CERTIFICATE_VERIFY_FAILED` → macOS 运行 `Install Certificates.command`，否则设置 `SSL_CERT_FILE`；`URLError`/`ConnectionError` → 检查网络，代理后设置 `HTTPS_PROXY`；`HTTP 429` → 限流，等待并退避重试；`HTTP 5xx` → 服务器错误，退避重试；`PermissionError` → 无法写输出，用 `--output` 指定可写目录。
27. 文件输入：API 接受 HTTP/HTTPS URL、Base64 data URI、`oss://` URL；本地文件路径不直接支持，脚本自动转换；直接传本地路径，无需手工上传步骤。
28. 大文件规则：本地文件 >= 7 MB 时始终加 `--upload-files`；Base64 编码膨胀约 33% 会超过 10 MB API 限制；小文件（包括 <7 MB 短片段视频）可用默认 base64 路径。
29. Token Plan 例外：`--upload-files` 临时上传端点对 `sk-sp-...` key 不可用并会被友好错误阻断；Token Plan 用户本地文件用默认 base64 路径；>=7 MB 文件改传可访问 URL（`https://` 或 `oss://`）而不是 `--upload-files`。
30. 文件输入方式选择：在线 URL 已托管时直接传 URL，大文件首选；Base64（默认）用于 <7 MB 本地文件（图片或短视频），脚本自动转 `data:` URI；临时上传用于 >=7 MB 本地文件，加 `--upload-files` 上传到 DashScope 临时存储（返回 `oss://` URL，48h TTL）。
31. 生产使用：默认临时存储有 48h TTL 和 100 QPS 上传限制，不适合生产、高并发或负载测试；要使用自己的 OSS bucket，在 `.env` 设置 `QWEN_TMP_OSS_BUCKET` 和 `QWEN_TMP_OSS_REGION`，安装 `pip install alibabacloud-oss-v2`，通过 `QWEN_TMP_OSS_AK_ID`/`QWEN_TMP_OSS_AK_SECRET` 或标准 `OSS_ACCESS_KEY_ID`/`OSS_ACCESS_KEY_SECRET` 提供凭证；使用仅具最小权限的 RAM 用户（目标 bucket 上仅 `oss:PutObject` + `oss:GetObject`）；视觉脚本仍需 `--upload-files` 触发上传；若安装 qianwen-ops-auth，看其 `references/custom-oss.md` 的完整设置。
32. 其他技能输入：输入文件来自其他技能输出（如图像生成、视频生成）时，直接传 URL（例如 `"image": "<image_url from image-gen>"`），不要先下载 URL；下载再以本地路径传入会浪费带宽并触发不必要的 base64 编码或 OSS 上传；支持所有 URL 类型 `https://`、`oss://`、`data:`。
33. 思考模式：使用 Qwen 视觉模型目录获取当前思考默认值和模型兼容性；执行细节见 `references/visual-reasoning.md`。
34. OCR：使用 Qwen 视觉模型目录获取当前 OCR 默认模型、替代模型和模型能力；参数和示例见 `references/ocr.md`。
35. 输入限制：图片支持 BMP/JPEG/PNG/TIFF/WEBP/HEIC，边长最小 10px，宽高比 <= 200:1，模型特定大小限制查模型目录；视频支持 MP4/AVI/MKV/MOV/FLV/WMV，模型特定时长和大小限制查模型目录；fps 范围 [0.1, 10]，默认 2.0。
36. HTTP 错误处理：401 无效或缺失 API key，运行 `qianwen-ops-auth`（若可用），否则提示用户设置 key（仅非明文检查）；400 请求格式错误，验证 messages 格式和图片 URL/格式；429 限流，用指数退避重试；5xx 服务器错误，用指数退避重试。
37. 用量与计费：用 `qianwen-usage` 技能检查用量、免费额度、计费；或让用户访问 QianWen console：Usage Analytics `https://platform.qianwenai.com/home/analytics`、Pay-as-you-go Billing `https://platform.qianwenai.com/home/billing/pay-as-you-go`、Token Plan Subscription `https://platform.qianwenai.com/home/billing/subscription/token-plan`；绝不编造、猜测或构造用量/计费/console URL；只提供本技能列出的精确链接，未列出就不要发明。
38. 输出位置：优先当前工作目录，默认子目录 `./output/qianwen-vision/`；禁止把输出文件写入本技能安装目录或任何 `skills/` 层级；所有生成内容写到当前工作目录下的 `output/` 或用户指定路径。
39. 更新检查（强制执行后）：脚本执行后检查 stderr 动作信号并必须处理；用户明确要求检查更新时也适用。
40. 信号 `[ACTION_REQUIRED] qianwen-update-check skill is not installed`：必须向用户展示选项并等待回复再继续：1) 现在安装——运行 `npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y`，然后运行 `python3 <this-skill-scripts-dir>/gossamer.py --dismiss`；2) 暂时跳过——运行 `python3 <this-skill-scripts-dir>/gossamer.py --dismiss` 后继续；3) 不再提醒——运行 `python3 <this-skill-scripts-dir>/gossamer.py --never-install` 后继续；不要静默跳过。
41. 信号 `[UPDATE_AVAILABLE]`：在回复中追加简短更新通知，包含 stderr 输出中的版本信息和更新命令。
42. stderr 无信号：若既无 `[ACTION_REQUIRED]` 也无 `[UPDATE_AVAILABLE]`，无需操作——技能已安装且最新（或 24h 内缓存）。
43. 用户明确要求检查更新：在兄弟技能目录中查找 `qianwen-update-check/SKILL.md`；找到则运行 `python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response` 并报告结果；未找到则展示上述安装选项。
44. 参考文件：`references/execution-guide.md` 备用路径（curl、代码生成、自主）；`references/curl-examples.md` curl 模板（base64、多图、视频、OCR）；`references/api-guide.md` API 补充指南；`references/visual-reasoning.md` QVQ 视觉推理指南；`references/ocr.md` Qwen-VL-OCR 文本提取指南；`references/sources.md` 官方文档 URL。

适用边界 · 注意事项

• 用户想生成/创建图片时（应改用 qianwen-image-generation）或生成视频时（应改用 qianwen-video-generation）。
• 纯文本任务且没有视觉输入，或非 Qwen 视觉任务时。
• 无法配置/获得 Qwen/DashScope API key，或不能使用该特定云服务/付费账号时。