qianwen-text

Qwen 文本聊天（兼容 OpenAI）

通过兼容 OpenAI 的 API 使用 Qwen 模型生成文本、进行对话、编写代码和调用工具。 此技能是 QianWen-AI/qianwen-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 中的 $DASHSCOPE_API_KEY， Python 中的 os.environ["DASHSCOPE_API_KEY"]）。任何凭据检查或检测都必须采用非明文方式：只报告状态 （例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不显示可能包含机密的 .env 或配置 文件内容。

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

密钥兼容性

支持 PAYG（sk-ws-...；旧版 sk-...）和 Token Plan（sk-sp-...）密钥。检测 API 密钥类型时，不要暴露密钥：

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 密钥——仅使用下方 Token Plan 目录中的模型。
payg	按量付费密钥——可使用完整模型目录。
not-set	未配置密钥。

对于 Token Plan，请获取并阅读当前的 Token Plan 模型目录，然后使用其中精确列出的模型。如果 CDN 无法访问，请使用本地备用文件。

Token Plan 仅支持特定模型——必须严格使用上述参考资料中列出的模型；不要猜测或探测模型是否可用。对于 PAYG，请继续阅读下文。

模型选择

在选择、推荐或设定默认模型之前，请获取并阅读当前的 Qwen 文本模型目录。其中包含模型列表、模型基本信息、推荐选项和默认模型。如果 CDN 无法访问，请使用本地备用版本。

1. 用户指定了模型 → 直接使用。
2. 当模型选择取决于需求、场景或定价时 → 查阅 qianwen-model-selector skill。
3. 没有明确指示，任务清晰 → 使用模型目录中的默认模型。对于要求最高的推理或编码任务，使用其中推荐的高性能选项。

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

模型详情：如需了解特定模型的更多信息，请引导用户访问 https://www.qianwenai.com/models/<model-name>。将 <model-name> 替换为准确的模型 ID；切勿修改或猜测该 ID。

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

执行

前置条件

• API 密钥：使用 Key Compatibility 中的非明文检测器；不要将其替换为变量存在性检查。如果未找到密钥，在可用时使用 qianwen-ops-auth，或指导用户在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。技能可以独立安装。
• Python 3.9+（仅使用标准库，执行脚本无需安装 pip 包）

环境检查

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

python3 --version  # must be 3.9+

如果未找到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或版本低于 3.9，请跳转到 execution-guide.md 中的* *路径 2（curl）**。

默认方式：运行脚本

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

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

**查看可用参数：**先运行 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/qianwen-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 时保存为文件，否则保存为目录）；多次调用时使用不同的文件名，以免覆盖
--print-response	将响应打印到 stdout
--model ID	覆盖模型（也可在请求 JSON 中设置）

模型优先级：--model CLI 标志 > --request JSON 中的 "model" 字段 > 内置默认值。

验证结果

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

失败时

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

如果完全无法使用 Python → 直接跳转到 execution-guide.md 中的路径 2（curl）。

错误模式	诊断	解决方法
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+
QIANWEN_API_KEY/DASHSCOPE_API_KEY not found	缺少 API 密钥	从 QianWen Console 获取密钥；添加到 .env：echo 'DASHSCOPE_API_KEY=sk-...' >> .env；或在可用时运行 qianwen-ops-auth
HTTP 401	密钥无效或不匹配	运行 qianwen-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: [...]	定义供工具使用的函数
上下文缓存	对重复前缀自动启用；或显式使用基于会话的方式	降低重复上下文的成本
部分模式	最后一条消息：{"role": "assistant", "content": "prefix…", "partial": true}	继续或补全前缀
批量推理	使用 JSONL 输入的异步批量 API	费用优惠 50%

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

错误处理

错误	原因	操作
401 Unauthorized	API 密钥无效或缺失	如果可用，运行 qianwen-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）；或使用脚本（纯标准库）

用量与账单：使用 qianwen-usage 技能直接检查用量、免费额度和账单。或者，用户可以访问 QianWen 控制台： 用量分析 | 按量付费账单 | Token 计划订阅

绝不要编造、猜测或拼接用量、账单或控制台 URL。 仅提供此技能中列出的准确链接。如果此处未列出某个 URL，请勿编造。

输出位置

所有输出优先保存到当前工作目录。使用 --output 时的默认子目录： ./output/qianwen-text/。

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

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

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

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

当 stderr 中出现此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。不得悄悄跳过此步骤。

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

1. 立即安装 — 我会为你运行安装命令
2. 暂时跳过 — 本次不做任何操作
3. 不再提醒 — 永久关闭此提示

用户回复后：

• 用户选择 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，然后正常继续

信号：[UPDATE_AVAILABLE]

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

stderr 中没有信号

如果 stderr 中既没有 [ACTION_REQUIRED]，也没有 [UPDATE_AVAILABLE]，则无需采取任何操作——该技能已安装且为最新版本（或缓存时间在 24 小时内）。

用户明确请求

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

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

参考资料

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