Qwen 文本聊天（兼容 OpenAI）

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

Skill 目录

使用此 skill 的内部文件执行操作和学习。当默认路径不可用或你 需要详细信息时，按需加载参考文件。

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

安全

禁止以明文输出任何 API 密钥或凭据。 始终使用变量引用（shell 中使用 $DASHSCOPE_API_KEY， os.environ["DASHSCOPE_API_KEY"] 则在 Python 中使用）。任何凭据检查或检测都必须采用非明文方式：仅报告 状态（例如“已设置” / “未设置”、“有效” / “无效”），不得报告值。禁止显示 .env 或可能包含机密信息的配置 文件的内容。

未配置 API 密钥时，禁止直接要求用户提供该密钥。 而应帮助创建一个包含占位符（DASHSCOPE_API_KEY=sk-your-key-here）的 .env 文件，并指导用户用从千问AI平台控制台获取的实际密钥替换该占位符。仅当用户明确要求时，才写入实际密钥值。

密钥兼容性

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，请使用 qianwen-model-selector 中的确切模型，或查阅 qianwen-ops-auth/references/tokenplan.md。如果不可用，请使用：

• 个人版: https://platform.qianwenai.com/docs/token-plan/personal/token-plan-personal-overview.md
• 团队版: https://platform.qianwenai.com/docs/token-plan/team/token-plan-team-overview.md

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

模型选择

| 模型 | 使用场景 | |--------------------|-------------------------------------------------------------------------| | qwen3.8-max | 最强旗舰模型 — 2.4T MoE，原生视觉语言能力，混合思考（默认开启），1M 上下文，内置工具。最适合复杂推理和编码。 | | qwen3.8-flash | 快速版 Qwen3.8 — 多模态（文本+图像+视频），混合思考（默认开启），1M 上下文。速度快且经济高效。 | | qwen3.7-max | 旗舰 agent 模型 — 1M 上下文、思考模式、函数调用、内置工具、结构化输出。 | | qwen3.7-plus | 推荐默认模型 — 多模态视觉语言能力，增强的 Agent 执行和编码能力，1M 上下文，默认开启思考。 | | qwen3.7-flash | 新一代轻量级模型 — 多模态（文本+图像+视频），1M 上下文，以更低成本提供全部功能。 | | qwen3.6-plus | 多模态（文本+图像+视频），1M 上下文，默认开启思考，编码能力强，具备通用识别能力 | | qwen3.5-plus | 性能、成本和速度均衡，1M 上下文，默认开启思考 | | qwen3.5-flash | 速度快、成本低，1M 上下文 | | qwen3-max | 旧版最强能力，内置工具（网络搜索、代码解释器） | | qwen-plus | 通用型 | | qwen-turbo | 成本低、延迟低 | | qwen3-coder-next | 推荐代码模型 — 质量、速度和成本的最佳平衡；Agent 式编码 | | qwen3-coder-plus | 代码生成 — 复杂任务质量最高 | | qwen3-coder-flash| 代码生成 — 响应快、成本更低 | | qwq-plus | 推理 / 思维链 | | qwen-mt-plus | 机器翻译 — 质量最佳，支持 92 种语言 | | qwen-mt-flash | 机器翻译 — 速度快、成本低，支持 92 种语言 | | qwen-mt-lite | 机器翻译 — 实时聊天，速度最快，支持 31 种语言 | | qwen-plus-character | 角色扮演 — 角色还原、共情对话 | | qwen-flash-character | 角色扮演 — 速度快、成本更低 |

1. 用户指定了模型 → 直接使用。
2. 当模型选择取决于需求、场景或定价时，请咨询 qianwen-model-selector skill。
3. 无明确信号、任务清晰 → qwen3.7-plus（默认）。如需最强推理/编码能力 → qwen3.8-max。

回退方案：如果模型选择器不可用，则采用上表中的默认值。

⚠️ 重要提示：上述模型列表是特定时间点的快照，可能已过时。模型可用性

变化频繁。**在做出模型决策前，请始终查阅官方模型列表，

以获取权威且最新的模型目录。**

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

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

执行

前提条件

• API 密钥：使用密钥兼容性中的非明文检测器；不得将其替换为

变量存在性检查。如果未找到密钥，请在 qianwen-ops-auth 可用时使用它，或指导用户在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。 Skills 可独立安装。

• Python 3.9+（仅使用标准库，执行脚本无需 pip install）

环境检查

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

python3 --version  # must be 3.9+

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

默认：运行脚本

脚本路径：脚本位于此 skill 目录下的 scripts/ 子目录中（即包含此 SKILL.md 的目录）。必须先找到此 skill 的安装目录，然后始终使用完整的绝对路径执行 脚本。 不得假定脚本位于当前工作目录。执行前 不得使用 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 保存到路径（后缀为 .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]。如果出现任一信号，你 必须 在回复用户之前按照 下方[更新检查](#update-check-mandatory-post-execution)中的说明操作。

失败处理

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

如果完全无法使用 Python → 直接跳至路径 2（curl）， 详见 [execution-guide.md](references/execution-guide.md)。

| 错误模式 | 诊断 | 解决方案 | |----------------------------------|----------------------------------|------------------------------------------------------------------------------| | command not found: python3 | Python 不在 PATH 中 | 尝试运行 python 或 py -3；如果缺失，请安装 Python 3.9+ | | Python 3.9+ required | 脚本版本检查失败 | 将 Python 升级到 3.9+ | | 类型提示附近出现 SyntaxError | Python < 3.9 | 将 Python 升级到 3.9+ | | QIANWEN_API_KEY/DASHSCOPE_API_KEY not found | 缺少 API 密钥 | 从千问AI平台控制台获取密钥；将其添加到 .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 | 字符串 \| 数组 | 用户输入或消息列表 | | model | 字符串 | 模型 ID（例如 qwen3.7-plus） | | system | 字符串 | 系统提示词（可选） | | temperature | 浮点数 | 0–2，控制随机性 | | max_tokens | 整数 | 最大输出 Token 数量 | | tools | 数组 | 用于工具调用的函数定义 | | stream | 布尔值 | 启用流式输出（建议用于交互式场景） | | enable_thinking | 布尔值 | 启用思考模式。以模型默认设置为准：qwen3.8-max/qwen3.8-flash/qwen3.7-max/qwen3.7-plus/qwen3.7-flash/qwen3.6-plus/qwen3.6-flash/qwen3.5-plus/qwen3.5-flash 的思考模式默认开启。仅当用户请求深度思考或需要为 flash 模型禁用思考模式时，才显式设置。会增加实时任务的延迟。 |

响应字段

| 字段 | 说明 | |--------------|------------------------------------------------| | 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](references/api-guide.md) 和 [sources.md](references/sources.md)。

错误处理

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

用量与计费：使用 qianwen-usage skill 直接查询用量、免费额度和计费信息。或者，用户可以访问千问AI平台控制台：

用量分析 |

按量付费账单 |

Token Plan 订阅

禁止伪造、猜测或构造用量、计费或控制台 URL。 只能提供此 skill 中列出的准确链接。如果此处未列出某个 URL，不得虚构。

输出位置

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

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

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

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

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

当 stderr 包含此信号时，你必须向用户提供以下选项，并且必须等待用户回复 后再继续。不得静默跳过此步骤。

更新检查 skill 尚未安装。它可让你及时了解 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]，则无需执行任何操作——该 skill 已安装 且为最新版本（或检查结果已在 24h 内缓存）。

用户明确请求

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

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

参考资料

• [execution-guide.md](references/execution-guide.md) — 备用路径（curl、SDK、自主解决）、函数调用、

思考模式

• [api-guide.md](references/api-guide.md) — 包含完整代码示例的 API 补充指南
• [sources.md](references/sources.md) — 官方文档 URL