配置和排查 QwenCloud API 认证（API…

在设置 QWEN_API_KEY/DASHSCOPE_API_KEY、遇到 401 认证错误或缺少凭证时，配置并验证 QwenCloud API 认证。

适用场景

解决思路

1. 绝不输出任何 API Key 或 OSS 凭证的明文；所有凭证检查只报告状态（如 set/not set、valid/invalid、HTTP 状态码），不报告 key 值。
2. 当 API Key 未配置或脚本报告缺少凭证时，绝不要求用户直接提供 API Key，也不要提示用户粘贴 key。
3. 帮助创建带占位符的 .env 文件：运行 `echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env`，然后告诉用户将 `sk-your-key-here` 替换为从 QwenCloud Console（https://home.qwencloud.com/api-keys）获取的真实 key。
4. 或者解释如何配置环境变量：`export DASHSCOPE_API_KEY='sk-...'` 并提供控制台 URL。
5. 只有当用户明确坚持要求由 agent 代为写入时，才把真实 key 值写入 .env。
6. 按凭证优先级链加载（先匹配者优先）：1) 环境变量 `DASHSCOPE_API_KEY`（或别名 `QWEN_API_KEY`）；2) 当前工作目录再仓库根目录（通过 `.git` 或 `skills/` 目录检测）中的 `.env` 文件；已存在的环境变量不会被覆盖。
7. 使用环境变量：`DASHSCOPE_API_KEY`（必需）、`QWEN_API_KEY`（别名，若两者都设置则优先）、`QWEN_BASE_URL`（可选，覆盖默认端点）、`QWEN_TMP_OSS_BUCKET`（自定义 OSS bucket）、`QWEN_TMP_OSS_REGION`（设置 bucket 时必需）、`QWEN_TMP_OSS_AK_ID`/`AK_SECRET`（OSS 凭证，使用最小权限 RAM 用户：`oss:PutObject` + `oss:GetObject`，未设置时回退到 `OSS_ACCESS_KEY_ID`/`OSS_ACCESS_KEY_SECRET`）。
8. 区分三种互斥的 key/plan 类型：标准（按量付费）`sk-xxxxx` 用于脚本/应用/工具，端点 `dashscope-intl.aliyuncs.com`；Token Plan `sk-sp-xxxxx` 用于带 User-Agent 头的交互式 AI 工具，端点 `token-plan.ap-southeast-1.maas.aliyuncs.com`；Coding Plan `sk-sp-xxxxx` 仅用于交互式 AI 编码工具（Cursor、Claude Code、Qwen Code），端点 `coding-intl.dashscope.aliyuncs.com`。
9. 注意所有 qwencloud/qwencloud-ai 脚本需要标准 key（`sk-`）；Coding Plan key（`sk-sp-`）在标准端点会产生 `401 invalid_api_key`；Token Plan key（`sk-sp-`）会被脚本自动路由到 Token Plan 端点。
10. 在 Token Plan 请求前，获取并阅读当前 Token Plan 模型目录（https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-token-plan-models.md）并传入目录中精确列出的模型；若 CDN 访问失败，使用本地回退（cdn/references/qwencloud-token-plan-models.md）。
11. 若用户 key 以 `sk-sp-` 开头，先查 tokenplan.md 了解 Token Plan 详情和上述 CDN 目录的模型覆盖，再查 codingplan.md 了解 Coding Plan 细节；若需要其 plan 之外的模型，引导用户从控制台获取标准 key。
12. 查看账单时使用 qwencloud-usage 技能查询用量、免费额度与计费，或使用控制台账单页：标准（按量付费）https://home.qwencloud.com/billing/pay-as-you-go；Token Plan 个人 https://home.qwencloud.com/analytics/token-plan/individual；Token Plan 团队 https://home.qwencloud.com/analytics/token-plan/team；Coding Plan https://home.qwencloud.com/billing/coding-plan；用量分析 https://home.qwencloud.com/analytics。
13. 绝不编造、猜测或构造用量/账单/控制台 URL；只提供本技能列出的确切链接，未列出的 URL 不要发明。
14. 获取 API Key：1) 打开 QwenCloud Console（https://home.qwencloud.com/api-keys）；2) 用 QwenCloud 账号登录；3) 在 API Key 管理区创建或复制 API key；4) 标准 key 以 `sk-` 开头（不是仅用于 Coding Plan 的 `sk-sp-`）。
15. 安全最佳实践：绝不在源码或提交到版本控制的配置文件中硬编码 API key；使用环境变量或 `.env` 文件（并把 `.env` 加入 `.gitignore`）；定期轮换 key 并立即吊销泄露的 key；使用最小权限，尽可能为特定应用创建专用 key。
16. 在项目根目录或当前工作目录创建 `.env`：`echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env`；脚本会自动从当前工作目录和项目根目录（通过 `.git` 或 `skills/` 目录检测）加载 `.env`，已存在的环境变量不会被 `.env` 值覆盖。
17. `.gitignore` 示例条目：`.env`、`.env.local`、`*.env`。
18. 除非明确说明，本技能提到的任何脚本或任务都在前台运行——等待标准输出，不要作为后台任务运行。
19. 验证：仅 PAYG 用简单 curl 请求测试认证：`curl -sS -X POST "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" -H "Authorization: Bearer $DASHSCOPE_API_KEY" -H "Content-Type: application/json" -d '{"model":"qwen-turbo","messages":[{"role":"user","content":"Hi"}]}'`；成功响应返回含 `choices` 和 `message.content` 的 JSON。Token Plan 不要用 curl，改用目标技能自带的 Python 脚本验证。
20. 认证错误处理：当任何子技能收到 `401` 且非明文检查显示 key 已设置（如 `[ -n "$DASHSCOPE_API_KEY" ]`，不要输出 key 值）时触发。
21. PAYG 探测命令：`curl -sS -o /dev/null -w "%{http_code}" -X POST "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" -H "Authorization: Bearer $DASHSCOPE_API_KEY" -H "Content-Type: application/json" -d '{"model":"qwen-turbo","messages":[{"role":"user","content":"hi"}]}'`；Token Plan 模式不要用 curl，运行目标技能自带的 Python 脚本。
22. 若 PAYG 探测返回 401，按顺序执行：Step 1 确认 key 来源（提示用户：1. key 创建于 home.qwencloud.com（QwenCloud 控制台）→ 重新验证 key；2. key 可能无效 → 在 home.qwencloud.com/api-keys 创建新 key）；Step 2 按用户选择执行（来自 QwenCloud 控制台 → 重新运行验证确认 key 可用；可能无效 → 引导用户在 `home.qwencloud.com/api-keys` 创建新 key）；Step 3 重新运行验证；Step 4 若仍 401，则 key 本身无效——引导用户从 QwenCloud 控制台（https://home.qwencloud.com/api-keys）创建新 key。
23. 验证：PAYG 运行上述 curl 验证，Token Plan 运行目标技能自带的 Python 脚本；通过标准为 HTTP 200 且输出有效；将证据保存到 `output/qwencloud-ops-auth/`。
24. 输出与证据：将验证结果和任何诊断输出保存到 `output/qwencloud-ops-auth/`；保留成功认证测试的记录以便排查。
25. 输出位置：优先当前工作目录，默认子目录 `./output/qwencloud-ops-auth/`；禁止将输出文件写入本技能安装目录或任何 `skills/` 层级；所有生成内容必须放到当前工作目录下的 `output/` 或用户指定路径。
26. 更新检查（执行后强制）：当用户要求检查更新（如 "check for updates"、"check version"、"is there a new version"、"update skills"）时：1) 在兄弟技能目录中查找 `qwencloud-update-check/SKILL.md`；2) 若找到——运行 `python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response` 并报告结果，用户要求强制检查时用 `--force`；3) 若未找到——必须展示以下选项并等待用户响应：1) 立即安装——运行安装命令；2) 暂时跳过——本次不做任何事；3) 不再提醒——永久抑制此提示。用户响应后：选 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` 后正常继续。

适用边界 · 注意事项

• 非认证类的 Qwen 任务（如一般 API 使用问题）不触发。
• Token Plan 模式不要用 curl 验证，应使用目标技能自带的 Python 脚本。
• 不要编造、猜测或构造用量/账单/控制台 URL，只使用本技能列出的确切链接。