qwencloud-text

Qwen 文本聊天（兼容 OpenAI）

通过兼容 OpenAI 的 API 使用 Qwen 模型生成文本、进行对话、编写代码和调用工具。 此技能是 qwencloud/qwencloud-ai 的一部分。

技能目录

使用此技能的内部文件来执行操作和了解详情。默认路径失效或需要更多信息时，按需加载参考文件。

位置	用途
scripts/text.py	默认执行方式 — 聊天/补全请求、流式传输、保存输出
references/execution-guide.md	备用方式：curl、Python SDK、函数调用、思考模式
references/api-guide.md	API 补充说明和完整代码示例
references/prompt-guide.md	提示词工程：CO-STAR 框架、CoT、少样本示例、任务步骤
references/sources.md	官方文档 URL（仅手动查阅）

安全

绝不可明文输出任何 API 密钥或凭据。 始终使用变量引用（shell 中使用 $QWENCLOUD_API_KEY，Python 中使用 os.environ["QWENCLOUD_API_KEY"]）。脚本依次接受 QWENCLOUD_API_KEY、QWEN_API_KEY 和 DASHSCOPE_API_KEY。检查或检测凭据时必须不以明文显示：只报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不显示可能包含机密的 .env 或配置文件内容。

未配置 API 密钥时，绝不可要求用户直接提供密钥。 应改为帮助用户创建带有占位符的 .env 文件（QWENCLOUD_API_KEY=sk-your-key-here），并指导用户从 QwenCloud 控制台获取实际密钥后替换占位符。只有用户明确要求时，才写入实际密钥值。

密钥兼容性

脚本同时支持标准 QwenCloud API 密钥（sk-...）和 Token Plan 密钥（sk-sp-...）。Token Plan 密钥会自动路由到 Token Plan 端点；支持的模型请参阅 Token Plan 模型目录。如果 CDN 访问失败，请使用本地备用文件。

Token Plan：不要使用 curl；始终使用随附的 Python 脚本。

Coding Plan 密钥（前缀同样为 sk-sp-，但通过 Coding Plan 订阅购买）仅供交互式编码工具使用，在这些脚本中会调用失败。如果已安装 qwencloud-ops-auth，请参阅其 references/codingplan.md，了解密钥类型、端点映射和错误代码的详情。

检测 API 密钥类型，但不要暴露密钥：

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	检测到 Token Plan 密钥（前缀为 sk-sp-）
payg	检测到标准 PAYG 密钥
not-set	环境中未找到 API 密钥

模型选择

🚫 严重警告 — 切勿覆盖用户指定的参数。 如果用户明确指定了模型（在提示词或请求 JSON 中），你必须使用该确切模型。切勿：

• 将其替换为“更适合”或更新的模型（例如，仅因任务“看起来需要推理”，就把用户指定的 qwen3.7-max 换成思考模型）
• 添加用户未要求的参数（enable_thinking、enable_search、风格提示）
• “优化”用户明确指定的任何选项

以下选择指南仅适用于用户未指定模型的情况。

在选择、推荐或设置默认模型之前，请获取并阅读当前的 QwenCloud 文本模型目录。其中包含最新的 Qwen 通用模型、基本信息、推荐模型和默认模型。对于编码、翻译或第三方模型系列，请查阅 qwencloud-model-selector 或 QwenCloud CLI。如果 CDN 访问失败，请使用本地备用文件。

1. 用户指定了模型 → 必须使用该确切模型 — 不要替换，不要“优化”，不要添加未要求的参数。
2. 当模型选择取决于需求、场景或价格时，请查阅 qwencloud-model-selector 技能。
3. 没有明显要求，任务明确 → 使用模型目录中的默认模型。

⚠️ 重要提示：模型目录是特定时间点的快照，可能已过时。模型的可用性 经常变化。在做出模型决策之前，务必查看官方模型列表， 以获取权威且最新的目录。

模型详情：如需了解特定模型的更多信息，请引导用户访问其详情页：https://www.qwencloud.com/models/<model-name>（将 <model-name> 替换为确切的模型 ID，例如 qwen3.6-plus → https://www.qwencloud.com/models/qwen3.6-plus）。切勿修改或猜测 URL 中的模型名称。

动态模型查询：如果可以使用 qwencloud-model-selector 技能或 QwenCloud CLI（qwencloud models info <model>），请使用它获取实时模型数据。CLI 需要身份验证 — 登录流程请参阅 qwencloud-usage 技能。

执行

前提条件

• API 密钥：仅通过非明文方式检查 QWENCLOUD_API_KEY、QWEN_API_KEY，然后检查 DASHSCOPE_API_KEY（例如在 shell 中： [ -n "$QWENCLOUD_API_KEY" ]；仅报告“已设置”或“未设置”，绝不要泄露密钥值）。如果未设置：若有 qwencloud-ops-auth 技能，则运行该技能；否则，引导用户从 QwenCloud Console 获取密钥，并通过 .env 文件 （在项目根目录或当前目录运行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量进行设置。 脚本会在当前工作目录和项目根目录中查找 .env。技能可能单独安装 — 不要假定一定存在 qwencloud-ops-auth。 注意：除了任何已导出的环境变量外，脚本还会自动加载当前目录和项目根目录中的 .env。shell 检查显示 $QWENCLOUD_API_KEY“未设置”，并不意味着脚本会失败 — 它仍可能在 .env 中找到密钥。shell 检查仅供参考；权威的测试方法是直接运行脚本（如果在任何位置都找不到密钥，脚本会退出并显示清楚的错误）。
• Python 3.9+（仅使用标准库，运行脚本无需 pip install）

环境检查

首次执行前，请确认 Python 可用：

python3 --version  # must be 3.9+

如果找不到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或版本低于 3.9， PAYG 可以使用路径 2（curl）；Token Plan 则必须安装 Python 3.9+。

默认：运行脚本

脚本路径：脚本位于此技能目录（即包含此 SKILL.md 的目录）下的 scripts/ 子目录中。**你必须先找到此技能的安装目录，然后始终使用绝对路径执行 脚本。**不要假设脚本位于当前工作目录中。执行前不要使用 cd 切换目录。

执行说明：在前台运行所有脚本——等待标准输出；不要在后台运行。

**发现：**先运行 python3 <this-skill-dir>/scripts/text.py --help，查看所有可用参数。

python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.7-plus"}' \
  --output output/qwencloud-text/ --print-response

流式传输（交互使用时推荐）：

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

参数	描述
--request '{...}'	JSON 请求正文
--file path.json	从文件加载请求（--request 的替代方式）
--stream	启用流式输出
--output path	将响应 JSON 保存到指定路径（后缀为 .json 时保存为文件，否则保存为目录）；不同调用请使用不同文件名，以免覆盖
--print-response	将响应打印到标准输出
--model ID	覆盖模型（也可在请求 JSON 中设置）

验证结果

• 退出代码为 0 且输出包含带有 choices 字段的有效 JSON → 成功
• 非零退出、HTTP 错误、空响应或包含 "code"/"message" 错误的 JSON → 失败
• 如果 Agent 无法读取退出代码，请扫描输出中的错误模式（Error、Traceback、401、403）
• 执行后检查：使用 --output 时，请确认响应 JSON 文件存在且包含 choices
• 强制要求 — 检查 stderr 信号：确认结果后，请扫描命令的 stderr 输出，查找 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]。如果出现任一信号，在回复用户前，你必须按照下面 更新检查中的说明操作。

失败时

如果脚本失败，请将错误输出与下方诊断表进行匹配，以确定解决方法。如果没有匹配项， 请阅读 execution-guide.md，了解其他路径：curl 命令（路径 2）、Python SDK 代码 生成（路径 3）和自主解决（路径 5）。

如果完全没有 Python → PAYG 可使用路径 2（curl）；Token Plan 必须按照 execution-guide.md 安装 Python 3.9+ 。

错误模式	诊断	解决方法
command not found: python3	Python 不在 PATH 中	尝试 python 或 py -3；如果未安装，请安装 Python 3.9+
Python 3.9+ required	脚本版本检查失败	将 Python 升级到 3.9+
SyntaxError near type hints	Python 版本低于 3.9	将 Python 升级到 3.9+
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	缺少 API 密钥	从 QwenCloud Console 获取密钥；添加到 .env：echo 'QWENCLOUD_API_KEY=sk-...' >> .env；或者在可用时运行 qwencloud-ops-auth
HTTP 401	密钥无效或不匹配	运行 qwencloud-ops-auth（仅进行非明文检查）；验证密钥是否有效
SSL: CERTIFICATE_VERIFY_FAILED	SSL 证书问题（代理/企业网络）	macOS：运行 Install Certificates.command；否则设置 SSL_CERT_FILE 环境变量
URLError / ConnectionError	网络无法连接	检查互联网连接；如果使用代理，请设置 HTTPS_PROXY
HTTP 429	请求过于频繁	等待后采用退避策略重试
HTTP 5xx	服务端错误	采用退避策略重试
PermissionError	无法写入输出	使用 --output 指定可写目录

快速参考

请求字段

字段	类型	说明
prompt / messages	string | array	用户输入或消息列表
model	string	模型 ID（例如 qwen3.7-plus）
system	string	系统提示词（可选）
temperature	float	0–2，用于控制随机性
max_tokens	int	最大输出 Token 数
tools	array	用于工具调用的函数定义
stream	bool	启用流式输出（交互式使用时推荐）
enable_thinking	bool	覆盖思考模式。不同模型的默认设置可能不同；请查看上方的模型目录。除非用户明确要求更改默认设置，否则不要设置此字段。

响应字段

字段	描述
text	生成的文本内容
model	使用的模型
usage	Token 用量（prompt_tokens、completion_tokens）
tool_calls	工具调用请求（如果使用了工具）

高级功能

这些是通过请求参数支持的 API 级功能。所有功能均使用同一个 chat/completions 端点。

功能	启用方式	说明
结构化输出	response_format: {"type": "json_schema", "json_schema": {...}}	强制输出符合架构的 JSON
网页搜索	enable_search: true	增强响应的实时网页搜索
深度思考	enable_thinking: true	扩展推理；仅在用户请求时启用
函数调用	tools: [...]	定义供工具使用的函数
上下文缓存	对重复前缀自动启用；或显式按会话启用	降低重复上下文的成本
部分模式	partial_mode: "prefix"	继续或补全前缀
批量推理	使用 JSONL 输入的异步批量 API	费用优惠 50%

各项功能的详细用法，请参阅 api-guide.md 和 sources.md。

错误处理

错误	原因	操作
401 Unauthorized	API 密钥无效或缺失	如果有，请运行 qwencloud-ops-auth；否则提示用户设置密钥（仅进行非明文检查）
429 Too Many Requests	超出速率限制	退避后重试
500 / 502 / 503	服务端错误	重试；查看状态页面
Invalid model	找不到模型 ID	对照上方的模型目录验证 ID
Invalid parameter	请求正文有误	验证 JSON 和字段类型
TypeError: ...proxies	openai SDK 与 httpx 不兼容	pip install --upgrade openai (>=1.55.0)；或使用脚本（纯标准库）

用量与计费：使用 qwencloud-usage 技能直接查看用量、免费套餐额度和计费信息。用户也可以访问 QwenCloud 控制台： 用量分析 | 按需付费计费 | 编码计划计费

切勿编造、猜测或构造用量、计费或控制台 URL。 仅提供此技能中列出的确切链接。如果此处未列出某个 URL，请勿虚构。

输出位置

所有输出优先写入当前工作目录。使用 --output 时的默认子目录： ./output/qwencloud-text/。

禁止写入：绝 NEVER 将输出文件写入此技能的安装目录或任何 skills/ 层级。所有生成内容必须写入当前工作目录下的 output/，或用户指定的路径。

Token Plan 支持

完全支持 Token Plan 密钥（sk-sp-...）。检测到 Token Plan 密钥时，脚本会自动路由到 Token Plan 端点（token-plan.ap-southeast-1.maas.aliyuncs.com）。

支持的模型

获取并阅读最新的 Token Plan 模型目录，然后使用目录中精确列出的、支持文本的模型。如果 CDN 访问失败，请使用本地备用文件。

行为

• Token Plan 密钥 + 支持的模型 → 自动路由到 Token Plan 端点，正常运行
• Token Plan 密钥 + 不支持的模型 → 请求可能在 TP 端点失败；请查阅上方目录，然后建议切换到支持的模型或使用 PAYG 密钥
• Coding Plan 密钥 → 脚本不是编码 Agent；调用会失败。请改用标准 PAYG 密钥或 Token Plan 密钥。

必需的请求头

所有请求都会自动包含 User-Agent: qwencloud-skills。

更新检查（执行后必须进行）

脚本执行后，检查 stderr 中的操作信号。脚本会自动检测更新状态并发出结构化信号。你必须根据这些信号采取行动。本节也适用于用户明确要求检查更新的情况。

信号：[ACTION_REQUIRED] qwencloud-update-check skill is not installed

当 stderr 包含此信号时，你必须向用户提供以下选项，并在继续之前等待用户回复。不要默默跳过。

更新检查技能尚未安装。它会让你及时了解 qwencloud/qwencloud-ai 的新功能和错误修复。

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，然后正常继续

信号：[UPDATE_AVAILABLE]

当 stderr 包含此信号时，你必须在回复中附上一则简短的更新通知，其中包含版本信息和 stderr 输出中显示的更新命令。

stderr 中没有信号

如果 stderr 中既不包含 [ACTION_REQUIRED]，也不包含 [UPDATE_AVAILABLE]，则无需采取行动——该技能已安装且为最新版本（或缓存时间在 24 小时内）。

用户明确要求

当用户明确要求检查更新（例如“检查更新”“检查版本”）时：

1. 在同级技能目录中查找 qwencloud-update-check/SKILL.md。
2. 如果找到 — 运行：python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response，并报告结果。
3. 如果未找到 — 提供上述安装选项。

参考资料

• execution-guide.md — 备用路径（curl、SDK、自主执行）、函数调用、思考模式
• api-guide.md — API 补充指南，包含完整代码示例
• sources.md — 官方文档 URL