需要经 QwenCloud 调用…

当用户要求用 QwenCloud（含 Qwen 及 deepseek/kimi/glm 等第三方模型）做文本生成、对话、写代码、函数调用时，用这份 OpenAI 兼容接口的可执行流程完成鉴权、选模型、执行、校验与错误恢复。

适用场景

解决思路

1. 安全底线：绝不把任何 API key 或凭证以明文输出，shell 里用 $QWENCLOUD_API_KEY，Python 里用 os.environ["QWENCLOUD_API_KEY"]；所有凭证检查必须非明文，只报告状态（如 set/not set、valid/invalid），绝不报告值，也绝不显示可能含密钥的 .env 或配置文件内容。
2. 当 API key 未配置时，绝不要求用户直接提供 key；而是帮用户创建含占位符的 .env 文件（QWENCLOUD_API_KEY=sk-your-key-here），并指引用户到 QwenCloud Console（https://home.qwencloud.com/api-keys）把占位符换成真实 key；只有用户明确要求时才写入真实 key 值。
3. 检测 API key 类型（不暴露 key）：运行 python3 -c "import sys; sys.path.insert(0, 'scripts'); from qwencloud_lib import detect_api_key_type; print(detect_api_key_type('scripts/qwencloud_lib.py'))"，输出含义为 token-plan（sk-sp- 前缀）、payg（标准按量付费 key）、not-set（环境未找到 key）。
4. Token Plan key 不要用 curl，始终使用本 skill 捆绑的 Python 脚本；Coding Plan key（同为 sk-sp- 前缀但来自 Coding Plan 订阅）只适用于交互式编码工具，在这些脚本上会失败，应改用标准 PAYG key 或 Token Plan key。
5. Token Plan 行为处理：Token Plan key + 受支持模型 → 自动路由到 Token Plan 端点（token-plan.ap-southeast-1.maas.aliyuncs.com）正常执行；Token Plan key + 不受支持模型 → 请求可能失败，先查 Token Plan 模型目录，再建议换受支持模型或改用 PAYG key。
6. 绝不覆盖用户显式指定的参数：如果用户在 prompt 或请求 JSON 中明确指定了模型，必须原样使用该模型，不得替换成“更合适/更新”的模型、不得添加用户没要的参数（如 enable_thinking、enable_search、风格提示）、不得对用户的显式选择做任何“优化”。
7. 用户未指定模型时，先获取并阅读最新的 QwenCloud text 模型目录（https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-text-models.md）；若 CDN 访问失败，使用本地 fallback（cdn/references/qwencloud-text-models.md）。
8. 模型选择依赖需求、场景或价格时，查阅 qwencloud-model-selector skill；没有任何信号且任务明确时，使用模型目录里的默认模型。
9. 模型目录只是时间点快照，可能过时；做模型决策前始终以官方模型列表 https://www.qwencloud.com/models 为准。
10. 查看具体模型信息时，把用户引导到详情页 https://www.qwencloud.com/models/<model-name>，用精确的模型 ID 替换 <model-name>（如 qwen3.6-plus），绝不要修改或猜测 URL 中的模型名。
11. 需要动态模型数据时，若 qwencloud-model-selector skill 或 QwenCloud CLI（qwencloud models info <model>）可用就用它；CLI 需要认证，登录流程见 qwencloud-usage skill。
12. 前置检查 API key：按 QWENCLOUD_API_KEY → QWEN_API_KEY → DASHSCOPE_API_KEY 顺序做非明文检查（如 shell 中 [ -n "$QWENCLOUD_API_KEY" ]，只报告 set / not set）。若未设置：优先运行 qwencloud-ops-auth skill（若已安装），否则引导用户从 QwenCloud Console 获取 key，并通过 .env（在项目根目录或当前目录执行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量设置。注意脚本会自动从当前目录和项目根目录加载 .env，shell 检查显示 not set 不代表脚本会失败，权威测试就是直接运行脚本（找不到 key 时会以明确错误退出）。
13. 环境要求：Python 3.9+，仅用标准库，脚本执行无需 pip install。首次执行前用 python3 --version 验证版本（必须 3.9+）；若无 python3，试 python --version 或 py -3 --version；若 Python 不可用或低于 3.9，PAYG 可走 Path 2（curl），Token Plan 必须安装 Python 3.9+。
14. 执行脚本前先定位本 skill 的安装目录（含 SKILL.md 的目录），始终用完整绝对路径执行 scripts/ 下的脚本；不要假设脚本在当前工作目录，也不要在执行前用 cd 切换目录。
15. 所有脚本都在前台运行，等待 stdout 输出，不要放到后台。
16. 先运行 python3 <this-skill-dir>/scripts/text.py --help 查看所有可用参数。
17. 默认执行示例：python3 <this-skill-dir>/scripts/text.py --request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.7-plus"}' --output output/qwencloud-text/ --print-response。
18. 交互式使用推荐加 --stream 流式输出，例如：python3 <this-skill-dir>/scripts/text.py --request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.7-plus"}' --stream --print-response。
19. 脚本参数：--request '{...}' 传 JSON 请求体；--file path.json 从文件加载请求；--stream 开启流式输出；--output path 保存响应 JSON（.json 后缀视为文件，否则视为目录，多次调用要用不同文件名避免覆盖）；--print-response 打印响应到 stdout；--model ID 覆盖模型（也可写在请求 JSON 里）。
20. 验证结果：退出码 0 且输出含 choices 字段的合法 JSON 视为成功；非零退出、HTTP 错误、空响应、或含 "code"/"message" 错误的 JSON 视为失败；若 agent 读不到退出码，就在输出里扫描 Error、Traceback、401、403 等错误特征；使用 --output 后要确认响应 JSON 文件存在且包含 choices。
21. 执行后强制检查 stderr：扫描是否出现 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]，出现任何一个都必须在回复用户前按 Update Check 章节处理。
22. 失败时用错误输出匹配诊断表处理；若无匹配，读 references/execution-guide.md 走替代路径：curl 命令（Path 2）、Python SDK 代码生成（Path 3）、自主解决（Path 5）。
23. 按诊断表处理常见错误：command not found: python3 → 试 python 或 py -3，缺则安装 Python 3.9+；Python 3.9+ required 或类型标注附近 SyntaxError → 升级到 3.9+；缺少 QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY → 从 QwenCloud Console 获取 key 并 echo 'QWENCLOUD_API_KEY=sk-...' >> .env，或运行 qwencloud-ops-auth（若可用）；HTTP 401 → 运行 qwencloud-ops-auth（只做非明文检查）并验证 key 有效；SSL: CERTIFICATE_VERIFY_FAILED → macOS 运行 Install Certificates.command，否则设置 SSL_CERT_FILE 环境变量；URLError/ConnectionError → 检查网络，走代理时设 HTTPS_PROXY；HTTP 429 → 等待并退避重试；HTTP 5xx → 退避重试；PermissionError → 用 --output 指定可写目录。
24. 用请求参数启用高级特性（都走同一个 chat/completions 端点）：结构化输出 response_format: {"type": "json_schema", "json_schema": {...}}；联网搜索 enable_search: true；深度思考 enable_thinking: true（只在用户要求时）；函数调用 tools: [...]；上下文缓存（重复前缀自动生效，或显式基于 session）；partial_mode: "prefix" 续写/补全前缀；批推理用 JSONL 输入的异步 batch API（5 折费用）。细节见 references/api-guide.md 和 references/sources.md。
25. 请求字段按下表填写：prompt/messages、model、system、temperature（0–2）、max_tokens、tools、stream（交互推荐开启）、enable_thinking（除非用户明确要求改默认值，否则不要设置此字段）；响应字段含 text、model、usage（prompt_tokens / completion_tokens）、tool_calls。
26. 错误处理表：401 Unauthorized → 运行 qwencloud-ops-auth（若可用），否则提示用户设置 key（只做非明文检查）；429 Too Many Requests → 退避重试；500/502/503 → 重试并查看状态页；Invalid model → 对照模型目录核实 ID；Invalid parameter → 校验 JSON 与字段类型；TypeError: ...proxies → pip install --upgrade openai (>=1.55.0) 或改用纯标准库脚本。
27. 用量与账单：用 qwencloud-usage skill 查用量、免费额度与账单，或让用户访问本 skill 列出的确切链接（Usage Analytics https://home.qwencloud.com/analytics、按量付费账单 https://home.qwencloud.com/billing/pay-as-you-go、Coding Plan 账单 https://home.qwencloud.com/billing/coding-plan）；绝不编造、猜测或构造用量/账单/控制台 URL，只提供这里列出的链接。
28. 输出位置：所有输出优先放在当前工作目录；使用 --output 时默认子目录为 ./output/qwencloud-text/。严禁把输出文件写入本 skill 的安装目录或任何 skills/ 层级，所有生成内容必须放到当前工作目录下的 output/ 或用户指定路径。
29. Token Plan 请求会自动带上 User-Agent: qwencloud-skills 头，无需手动处理。
30. 收到 [ACTION_REQUIRED] qwencloud-update-check skill is not installed 信号时，必须向用户呈现三个选项并等待回复后才能继续：1) 现在安装 → 运行 npx skills add QwenCloud/qwencloud-ai --skill qwencloud-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 后继续正常流程。绝不静默跳过。
31. 收到 [UPDATE_AVAILABLE] 信号时，必须在回复末尾追加简短更新提示，包含版本信息和 stderr 中给出的更新命令；若 stderr 两个信号都没有，则无需任何操作（表示已安装且最新，或 24 小时内已缓存）。
32. 用户明确要求检查更新时：先在兄弟 skill 目录中查找 qwencloud-update-check/SKILL.md；找到则运行 python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response 并报告结果；未找到则按上面的三个安装选项提示用户。

适用边界 · 注意事项

• 使用非 QwenCloud 平台时（直连 OpenAI API、Google Gemini API 等）不适用。
• 与 QwenCloud 无关的一般编码问题不适用。
• 图像/视频理解（改用 qwencloud-vision）以及图像/视频/音频生成不适用；Coding Plan key 用于交互式编码工具，也不适用于这些脚本。