qwencloud-text
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAgent setup: If your agent doesn't auto-load skills (e.g. Claude Code), see agent-compatibility.md once per session.
Agent 设置: 如果你的Agent不会自动加载技能(例如Claude Code), 每次会话请先查看一次 agent-compatibility.md。
Qwen Text Chat (OpenAI-Compatible)
Qwen 文本聊天(兼容OpenAI协议)
Generate text, conduct conversations, write code, and invoke tools using Qwen models through the OpenAI-compatible API.
This skill is part of qwencloud/qwencloud-ai.
你可以通过兼容OpenAI的API,使用Qwen模型生成文本、开展对话、编写代码以及调用工具。
本技能隶属于 qwencloud/qwencloud-ai 套件。
Skill directory
技能目录
Use this skill's internal files to execute and learn. Load reference files on demand when the default path fails or you
need details.
| Location | Purpose |
|---|---|
| Default execution — chat/completions request, streaming, output save |
| Fallback: curl, Python SDK, function calling, thinking mode |
| API supplement and full code examples |
| Prompt engineering: CO-STAR framework, CoT, few-shot, task steps |
| Official documentation URLs (manual lookup only) |
| Agent self-check: register skills in project config for agents that don't auto-load |
使用本技能的内部文件来执行操作和学习。当默认路径失效或你需要详细信息时,请按需加载参考文件。
| 位置 | 用途 |
|---|---|
| 默认执行入口 — 聊天/补全请求、流式输出、结果保存 |
| 备用方案:curl、Python SDK、函数调用、思考模式 |
| API补充说明与完整代码示例 |
| Prompt工程:CO-STAR框架、思维链、少样本提示、任务步骤 |
| 官方文档URL(仅手动查询使用) |
| Agent自检:针对不会自动加载技能的Agent,在项目配置中注册技能 |
Security
安全须知
NEVER output any API key or credential in plaintext. Always use variable references ( in shell,
in Python). Any check or detection of credentials must be non-plaintext: report
only status (e.g. "set" / "not set", "valid" / "invalid"), never the value. Never display contents of or config
files that may contain secrets.
$DASHSCOPE_API_KEYos.environ["DASHSCOPE_API_KEY"].envWhen the API key is not configured, NEVER ask the user to provide it directly. Instead, help create a file with a placeholder () and instruct the user to replace it with their actual key from the QwenCloud Console. Only write the actual key value if the user explicitly requests it.
.envDASHSCOPE_API_KEY=sk-your-key-here绝对不要明文输出任何API密钥或凭证。 始终使用变量引用(Shell中使用,Python中使用)。任何凭证检查或检测都必须非明文:仅返回状态(例如“已设置”/“未设置”、“有效”/“无效”),绝对不要返回凭证值。永远不要展示可能包含密钥的或配置文件内容。
$DASHSCOPE_API_KEYos.environ["DASHSCOPE_API_KEY"].env当API密钥未配置时,绝对不要直接要求用户提供密钥。 你应该帮助用户创建一个带占位符的文件(),并指导用户前往QwenCloud控制台获取实际密钥替换占位符。仅当用户显式要求时,才写入实际密钥值。
.envDASHSCOPE_API_KEY=sk-your-key-hereKey Compatibility
密钥兼容性说明
Scripts require a standard QwenCloud API key (). Coding Plan keys () cannot be used for direct
API calls — they are designed exclusively for interactive coding tools (Cursor, Claude Code, Qwen Code) and do not work
on QwenCloud API endpoints. The script detects keys at startup and prints a warning. If qwencloud-ops-auth is installed,
see its for details on key types, endpoint mapping, and error codes.
sk-...sk-sp-...sk-sp-references/codingplan.md脚本需要标准QwenCloud API密钥(格式)。编码计划密钥()无法用于直接API调用——它们专门为交互式编码工具(Cursor、Claude Code、Qwen Code)设计,无法在QwenCloud API端点使用。脚本启动时会自动检测格式密钥并输出警告。如果已安装qwencloud-ops-auth,可查看其了解密钥类型、端点映射和错误码的详细信息。
sk-...sk-sp-...sk-sp-references/codingplan.mdModel Selection
模型选择
| Model | Use Case |
|---|---|
| Recommended default — balanced performance, cost, speed, 1M context |
| Fast, low-cost, 1M context |
| Strongest capability |
| General purpose |
| Cheapest, low latency |
| Recommended code model — best balance of quality, speed, cost; agentic coding |
| Code generation — highest quality for complex tasks |
| Code generation — fast responses, lower cost |
| Reasoning / chain-of-thought |
| Machine translation — best quality, 92 languages |
| Machine translation — fast, low cost, 92 languages |
| Machine translation — real-time chat, fastest, 31 languages |
| Role-playing — recommended for Singapore |
| Role-playing — character restoration, empathetic dialog |
| Role-playing — fast, lower cost |
- User specified a model → use directly.
- Consult the qwencloud-model-selector skill when model choice depends on requirement, scenario, or pricing.
- No signal, clear task → (default).
qwen3.5-plus
Fallback: if model-selector is unavailable, the defaults in the table above apply.
⚠️ Important: The model list above is a point-in-time snapshot and may be outdated. Model availability changes frequently. Always check the official model list for the authoritative, up-to-date catalog before making model decisions.
| 模型 | 适用场景 |
|---|---|
| 推荐默认使用 — 性能、成本、速度均衡,支持1M上下文 |
| 速度快、成本低,支持1M上下文 |
| 能力最强的模型 |
| 通用场景 |
| 成本最低、延迟低 |
| 推荐代码模型 — 质量、速度、成本均衡性最佳;支持智能编码 |
| 代码生成 — 复杂任务下质量最高 |
| 代码生成 — 响应速度快、成本更低 |
| 推理/思维链场景 |
| 机器翻译 — 质量最佳,支持92种语言 |
| 机器翻译 — 速度快、成本低,支持92种语言 |
| 机器翻译 — 实时聊天场景,速度最快,支持31种语言 |
| 角色扮演 — 推荐新加坡地区使用 |
| 角色扮演 — 人设还原度高、对话共情能力强 |
| 角色扮演 — 速度快、成本更低 |
- 用户指定了模型 → 直接使用。
- 当模型选择需要根据需求、场景或定价决定时,请调用qwencloud-model-selector技能。
- 无明确指示、任务清晰 → 默认使用。
qwen3.5-plus
备用方案:如果model-selector不可用,则使用上表中的默认值。
⚠️ 重要提示:上表的模型列表是当前时间点的快照,可能已过时。模型的可用性会频繁变化。在确定使用的模型之前,请始终查阅官方模型列表获取权威、最新的目录。
Execution
执行指南
Prerequisites
前置条件
- API Key: Check that (or
DASHSCOPE_API_KEY) is set using a non-plaintext check only (e.g. in shell:QWEN_API_KEY; report only "set" or "not set", never the key value). If not set: run the * qwencloud-ops-auth* skill if available; otherwise guide the user to obtain a key from QwenCloud Console and set it via[ -n "$DASHSCOPE_API_KEY" ]file (.envin project root or current directory) or environment variable. The script searches forecho 'DASHSCOPE_API_KEY=sk-your-key-here' >> .envin the current working directory and the project root. Skills may be installed independently — do not assume qwencloud-ops-auth is present..env - Python 3.9+ (stdlib only, no pip install needed for script execution)
- API密钥:仅通过非明文方式检查(或
DASHSCOPE_API_KEY)是否已设置(例如在Shell中使用QWEN_API_KEY;仅报告“已设置”或“未设置”,永远不要输出密钥值)。如果未设置:如果有可用的qwencloud-ops-auth技能则运行该技能;否则指导用户前往QwenCloud控制台获取密钥,并通过[ -n "$DASHSCOPE_API_KEY" ]文件(在项目根目录或当前目录执行.env)或环境变量设置密钥。脚本会在当前工作目录和项目根目录下搜索echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env文件。技能可能是独立安装的——不要假定qwencloud-ops-auth已安装。.env - Python 3.9+(仅需标准库,执行脚本无需安装pip依赖)
Environment Check
环境检查
Before first execution, verify Python is available:
bash
python3 --version # must be 3.9+If is not found, try or . If Python is unavailable or below 3.9, skip to *
Path 2 (curl)* in execution-guide.md.
python3python --versionpy -3 --version首次执行前,请验证Python是否可用:
bash
python3 --version # 必须为3.9及以上版本如果找不到,请尝试或。如果Python不可用或版本低于3.9,请跳转至execution-guide.md中的路径2(curl)。
python3python --versionpy -3 --versionDefault: Run Script
默认方式:运行脚本
Script path: Scripts are in the subdirectory of this skill's directory (the directory containing this
SKILL.md). You MUST first locate this skill's installation directory, then ALWAYS use the full absolute path to execute
scripts. Do NOT assume scripts are in the current working directory. Do NOT use to switch directories before
execution.
scripts/cdExecution note: Run all scripts in the foreground — wait for stdout; do not background.
Discovery: Run first to see all available arguments.
python3 <this-skill-dir>/scripts/text.py --helpbash
python3 <this-skill-dir>/scripts/text.py \
--request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.5-plus"}' \
--output output/qwencloud-text/ --print-responseFor streaming (recommended for interactive use):
bash
python3 <this-skill-dir>/scripts/text.py \
--request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.5-plus"}' \
--stream --print-response| Argument | Description |
|---|---|
| JSON request body |
| Load request from file (alternative to |
| Enable streaming output |
| Save response JSON to directory |
| Print response to stdout |
| Override model (also settable in request JSON) |
脚本路径:脚本位于本技能目录(包含本SKILL.md的目录)的子目录下。你必须先定位到本技能的安装目录,然后始终使用完整绝对路径执行脚本。 不要假定脚本位于当前工作目录。执行前不要使用切换目录。
scripts/cd执行注意事项:在前台运行所有脚本——等待标准输出;不要后台运行。
功能查询:先运行查看所有可用参数。
python3 <this-skill-dir>/scripts/text.py --helpbash
python3 <this-skill-dir>/scripts/text.py \
--request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.5-plus"}' \
--output output/qwencloud-text/ --print-response如需流式输出(推荐交互式场景使用):
bash
python3 <this-skill-dir>/scripts/text.py \
--request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.5-plus"}' \
--stream --print-response| 参数 | 说明 |
|---|---|
| JSON请求体 |
| 从文件加载请求( |
| 启用流式输出 |
| 将响应JSON保存到指定目录 |
| 将响应打印到标准输出 |
| 覆盖指定模型(也可在请求JSON中设置) |
Verify Result
结果验证
- Exit code + output contains valid JSON with
0field → successchoices - Non-zero exit, HTTP error, empty response, or JSON with /
"code"error → fail"message" - If agent cannot read exit codes, scan output for error patterns (,
Error,Traceback,401)403 - Post-execution check: When is used, verify the response JSON file exists and contains
--outputchoices - MANDATORY — stderr signal check: After confirming the result, scan the command's stderr output for
or
[ACTION_REQUIRED]. If either signal is present, you MUST follow the instructions in Update Check below before responding to the user.[UPDATE_AVAILABLE]
- 退出码为+ 输出包含带
0字段的有效JSON → 执行成功choices - 非零退出码、HTTP错误、空响应、或JSON包含/
"code"错误 → 执行失败"message" - 如果Agent无法读取退出码,请扫描输出查找错误模式(、
Error、Traceback、401)403 - 执行后检查:如果使用了参数,请验证响应JSON文件是否存在且包含
--output字段choices - 必填 — 标准错误信号检查:确认结果后,请扫描命令的标准错误输出是否有或
[ACTION_REQUIRED]。如果存在任一信号,你必须先遵循下方更新检查的说明操作,再响应用户。[UPDATE_AVAILABLE]
On Failure
失败处理
If the script fails, match the error output against the diagnostic table below to determine the resolution. If no match,
read execution-guide.md for alternative paths: curl commands (Path 2), Python SDK code
generation (Path 3), and autonomous resolution (Path 5).
If Python is not available at all → skip directly to Path 2 (curl)
in execution-guide.md.
| Error Pattern | Diagnosis | Resolution |
|---|---|---|
| Python not on PATH | Try |
| Script version check failed | Upgrade Python to 3.9+ |
| Python < 3.9 | Upgrade Python to 3.9+ |
| Missing API key | Obtain key from QwenCloud Console; add to |
| Invalid or mismatched key | Run qwencloud-ops-auth (non-plaintext check only); verify key is valid |
| SSL cert issue (proxy/corporate) | macOS: run |
| Network unreachable | Check internet; set |
| Rate limited | Wait and retry with backoff |
| Server error | Retry with backoff |
| Can't write output | Use |
如果脚本执行失败,请将错误输出与下方诊断表匹配来确定解决方案。如果没有匹配项,请查阅execution-guide.md了解替代路径:curl命令(路径2)、Python SDK代码生成(路径3)和自主解决(路径5)。
如果完全没有可用的Python → 直接跳转至execution-guide.md中的路径2(curl)。
| 错误模式 | 诊断原因 | 解决方案 |
|---|---|---|
| Python不在PATH环境变量中 | 尝试 |
| 脚本版本检查失败 | 将Python升级到3.9及以上版本 |
类型提示附近出现 | Python版本低于3.9 | 将Python升级到3.9及以上版本 |
| 缺少API密钥 | 从QwenCloud控制台获取密钥;添加到 |
| 密钥无效或不匹配 | 运行qwencloud-ops-auth(仅执行非明文检查);验证密钥是否有效 |
| SSL证书问题(代理/企业网络) | macOS:运行 |
| 网络不可达 | 检查网络连接;如果使用代理请设置 |
| 触发限流 | 等待后指数退避重试 |
| 服务器错误 | 等待后指数退避重试 |
| 无法写入输出目录 | 使用 |
Quick Reference
快速参考
Request Fields
请求字段
| Field | Type | Description |
|---|---|---|
| string | array | User input or message list |
| string | Model ID (e.g. |
| string | System prompt (optional) |
| float | 0–2, controls randomness |
| int | Max output tokens |
| array | Function definitions for tool calling |
| bool | Enable streaming (recommended for interactive use) |
| bool | Enable thinking mode. Model defaults apply: |
| 字段 | 类型 | 说明 |
|---|---|---|
| string | array | 用户输入或消息列表 |
| string | 模型ID(例如 |
| string | 系统提示词(可选) |
| float | 取值0–2,控制输出随机性 |
| int | 最大输出token数 |
| array | 工具调用的函数定义 |
| bool | 启用流式输出(推荐交互式场景使用) |
| bool | 启用思考模式。遵循模型默认设置: |
Response Fields
响应字段
| Field | Description |
|---|---|
| Generated text content |
| Model used |
| Token usage (prompt_tokens, completion_tokens) |
| Function call requests (if tools used) |
| 字段 | 说明 |
|---|---|
| 生成的文本内容 |
| 使用的模型 |
| Token使用情况(prompt_tokens、completion_tokens) |
| 函数调用请求(如果使用了工具) |
Advanced Features
高级功能
These are API-level features supported through request parameters. All use the same endpoint.
chat/completions| Feature | How to Enable | Notes |
|---|---|---|
| Structured output | | Force JSON output conforming to schema |
| Web search | | Real-time web search augmented responses |
| Deep thinking | | Extended reasoning; only when user requests it |
| Function calling | | Define functions for tool use |
| Context cache | Automatic for repeated prefixes; or explicit session-based | Reduces cost for repeated context |
| Partial mode | | Continue/complete a prefix |
| Batch inference | Async batch API with JSONL input | 50% cost discount |
For detailed usage of each feature, see api-guide.md and sources.md.
这些是通过请求参数支持的API级功能,全部使用同一个端点。
chat/completions| 功能 | 启用方式 | 说明 |
|---|---|---|
| 结构化输出 | | 强制输出符合schema的JSON格式 |
| 联网搜索 | | 基于实时网页搜索的增强回答 |
| 深度思考 | | 扩展推理能力;仅在用户请求时启用 |
| 函数调用 | | 定义可供调用的工具函数 |
| 上下文缓存 | 重复前缀自动缓存;或显式基于会话缓存 | 降低重复上下文的调用成本 |
| 续写模式 | | 续写/补全给定前缀 |
| 批量推理 | 支持JSONL输入的异步批量API | 成本降低50% |
如需了解每个功能的详细用法,请查阅api-guide.md和sources.md。
Error Handling
错误处理
| Error | Cause | Action |
|---|---|---|
| Invalid or missing API key | Run qwencloud-ops-auth if available; else prompt user to set key (non-plaintext check only) |
| Rate limit exceeded | Retry with backoff |
| Server error | Retry; check status page |
| Model ID not found | Verify model name against Model Selection table |
| Bad request body | Validate JSON and field types |
| openai SDK vs httpx incompatibility | |
| 错误类型 | 引发原因 | 处理措施 |
|---|---|---|
| API密钥无效或缺失 | 如果有可用的qwencloud-ops-auth技能则运行该技能;否则提示用户设置密钥(仅执行非明文检查) |
| 超出频率限制 | 指数退避重试 |
| 服务器错误 | 重试;查看状态页 |
| 模型ID不存在 | 对照模型选择表验证模型名称是否正确 |
| 请求体格式错误 | 验证JSON和字段类型是否正确 |
| openai SDK与httpx版本不兼容 | |
Output Location
输出位置
Prefer the current working directory for all outputs. Default subdirectory when is used:
.
--output./output/qwencloud-text/Write prohibition: NEVER write output files into this skill's installation directory or any hierarchy. All generated content must go to under the current working directory or a user-specified path.
skills/output/所有输出优先保存到当前工作目录。使用参数时默认子目录为:。
--output./output/qwencloud-text/写入禁止规则:绝对不要将输出文件写入本技能的安装目录或任何层级目录下。所有生成的内容必须保存到当前工作目录下的目录或用户指定的路径。
skills/output/Update Check (MANDATORY Post-Execution)
更新检查(执行后必须完成)
After script execution, check stderr for action signals. The script automatically detects update status and emits
structured signals. You MUST act on them. This section also applies when the user explicitly asks to check for updates.
脚本执行后,请检查标准错误输出中的操作信号。脚本会自动检测更新状态并输出结构化信号,你必须根据信号采取行动。当用户显式要求检查更新时,本节内容也适用。
Signal: [ACTION_REQUIRED] qwencloud-update-check skill is not installed
[ACTION_REQUIRED] qwencloud-update-check skill is not installed信号:[ACTION_REQUIRED] qwencloud-update-check skill is not installed
[ACTION_REQUIRED] qwencloud-update-check skill is not installedWhen stderr contains this signal, you MUST present the following options to the user and wait for their response
before proceeding. Do NOT silently skip this.
The update-check skill is not installed. It keeps you informed about new qwencloud/qwencloud-ai features and bug fixes.
- Install now — I'll run the install command for you
- Skip for now — do nothing this time
- Never remind me — permanently suppress this prompt
After the user responds:
- User chooses 1 → run:
, then run:
npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -ypython3 <this-skill-scripts-dir>/gossamer.py --dismiss - User chooses 2 → run: , then continue normally
python3 <this-skill-scripts-dir>/gossamer.py --dismiss - User chooses 3 → run: , then continue normally
python3 <this-skill-scripts-dir>/gossamer.py --never-install
当标准错误输出包含该信号时,你必须向用户展示以下选项,并等待用户回复后再继续操作,不要静默跳过。
更新检查技能未安装,它可以让你及时了解qwencloud/qwencloud-ai的新功能和bug修复。
- 立即安装 — 我将为你运行安装命令
- 本次跳过 — 这次不做任何操作
- 永不提醒 — 永久关闭该提示
用户回复后:
- 用户选择1 → 运行:,然后运行:
npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -ypython3 <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
Signal: [UPDATE_AVAILABLE]
[UPDATE_AVAILABLE]信号:[UPDATE_AVAILABLE]
[UPDATE_AVAILABLE]When stderr contains this signal, you MUST append a brief update notice to your response, including the version info and
the update command shown in the stderr output.
当标准错误输出包含该信号时,你必须在回复末尾附加简短的更新通知,包括标准错误输出中显示的版本信息和更新命令。
No signal in stderr
标准错误输出无信号
If stderr contains neither nor , no action is needed — the skill is installed
and up to date (or cached within 24h).
[ACTION_REQUIRED][UPDATE_AVAILABLE]如果标准错误输出既没有也没有,则无需采取任何操作——技能已安装且为最新版本(或24小时内已缓存更新状态)。
[ACTION_REQUIRED][UPDATE_AVAILABLE]Explicit user request
用户显式请求
When the user explicitly asks to check for updates (e.g. "check for updates", "check version"):
- Look for in sibling skill directories.
qwencloud-update-check/SKILL.md - If found — run: and report the result.
python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response - If not found — present the install options above.
当用户显式要求检查更新时(例如“检查更新”、“查看版本”):
- 在同级技能目录中查找。
qwencloud-update-check/SKILL.md - 如果找到 — 运行:并返回结果。
python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response - 如果未找到 — 向用户展示上述安装选项。
References
参考文档
- execution-guide.md — Fallback paths (curl, SDK, autonomous), function calling, thinking mode
- api-guide.md — API supplementary guide with full code examples
- sources.md — Official documentation URLs
- execution-guide.md — 备用执行路径(curl、SDK、自主解决)、函数调用、思考模式
- api-guide.md — API补充指南与完整代码示例
- sources.md — 官方文档URL