千问-工单支持 (QianWen Support)

Manage support tickets via QianWen CLI v1.2.0+ qianwen support commands. Supports the full ticket lifecycle: create, list, view, reply, close, and rate.

This skill can be loaded by any Agent that supports Agent Skills and can execute local commands. Other QianWen Skills (auth, usage, model selection, etc.) are optional collaborators — when present they provide deeper domain diagnostics; when absent, this skill continues with QianWen CLI read-only checks and never blocks ticket management.

Skill Directory

Prerequisites

• QianWen CLI v1.2.0+ (verify: qianwen version). Install: npm install -g @qianwenai/qianwen-cli. Node.js >= 18.
• Authentication: CLI session via qianwen auth login (browser device flow). For full auth procedure, load references/auth-flow.md.

Security

NEVER output any credential value in plaintext. Report only status (e.g. "authenticated" / "expired").

Sensitive Info Masking (Descriptions & Replies)

When composing ticket descriptions or drafting replies, always mask sensitive info:

• ❌ Never include: full email, user ID, phone number, API key, AccessKey, password
• ✅ Use masked formats:
  • Email: zephy*****@gmail.com
  • Phone: 138****1234
  • API Key / AccessKey: sk-****xxxx（仅保留前 3 位和后 4 位）
  • 用户 ID / 工号: 08****94

Two Credential Systems — Never Confuse

Red line: Never offer $DASHSCOPE_API_KEY to fix CLI AUTH_REQUIRED errors.

Authentication Flow (TL;DR)

1. qianwen auth status --format json → authenticated: true → skip to commands
2. qianwen auth login --init-only --format json → extract verification_url → open in browser
3. qianwen auth login --complete --format json → poll until success event

Full procedure (two-phase login, JSON events, TTY handling): load references/auth-flow.md.

General Rule: Web Portal Guidance

Whenever guiding users to the QianWen cloud ticket page (for any reason: viewing screenshots, performing authorization, uploading attachments, etc.), always provide the specific ticket link so users can click directly:

https://platform.qianwenai.com/home/support/detail?id=<ticket-id>

Never just say "please log in to the web portal" without providing the actual link.

General Rule: Ticket ID Hyperlinks

每次输出中出现工单号时，必须将其格式化为超链接，指向对应的工单详情页：

https://platform.qianwenai.com/home/support/detail?id={工单号}

示例：

• 正确：工单 0005PYGCW
• 错误：工单 0005PYGCW（无链接）

此规则适用于所有场景：工单创建成功、查看工单状态、展示工程师回复、引导用户操作等。只要工单号出现在给用户的消息中，就必须附带超链接。

General Rule: Reply Workflow

When a ticket has engineer replies and the user needs to respond, must follow this three-step workflow in order:

1. 完整展示工程师回复：将工程师的回复内容原封不动地呈现给用户（遵循 Phase 4 的完整转述规则），不得删减、概括或改写。
2. 等待用户指示：展示完毕后，明确询问用户希望如何回复，等待用户给出具体指示。不得自行推测用户意图或代替用户决定回复内容。
3. 草拟回复并提交：根据用户指示草拟回复内容，展示给用户确认后再提交。未经用户确认，不得直接发送回复。

核心原则：展示 → 等指示 → 草拟确认 → 提交。 每一步都不可跳过，不可合并。

General Rule: Authorization Requests — Immediate Stop

当工程师要求客户提供授权时，立即停止所有其他操作，优先处理授权引导。 这是一条核心规则，只要触发就必须执行，不可跳过或延迟。

触发条件：工程师回复中包含任何授权相关请求（如 API Key 重新生成、账户验证、权限授予、身份确认等）。

触发后必须执行的动作：

1. 立即停止当前工作流：不再执行任何其他操作（如草拟回复、继续诊断等），优先处理授权引导。
2. 明确告知禁止 Agent 操作：直接告知用户"授权操作禁止在 Agent 中执行，必须由您本人登录千问AI平台工单页面完成"。
3. 提供工单链接：必须提供对应工单的链接，便于用户直接点击打开操作：https://platform.qianwenai.com/home/support/detail?id=<ticket-id>
4. 完整转述授权要求：将工程师要求的具体授权事项原封不动地转述给用户，帮助用户了解需要做什么。

核心原则：触发授权 → 停止一切 → 引导登录 → 提供链接 → 转述要求。 此规则优先级高于其他所有工作流规则。

Core Workflow

Phase 0: Pre-flight Checks (silent)

qianwen auth status --format json   # 1. Check auth
qianwen version                      # 2. Check CLI version (need >= 1.2.0)
qianwen doctor --format json         # 3. Collect diagnostics

Only surface issues to the user if a check blocks the operation.

Optional Collaboration and Fallback

QianWen CLI accurately executes queries and operations; this Skill calls CLI directly for basic diagnostics and ticket management. Other QianWen Skills are not more capable and not required dependencies — they accumulate finer judgment in specific domains (auth, usage, billing, model selection, etc.).

Rules:

1. When the corresponding domain Skill is detected and installed: prefer its specialized diagnostic flow for deeper investigation.
2. When the corresponding domain Skill is not installed: execute this Skill's own read-only basic checks using QianWen CLI.
3. Never block ticket management (create, list, view, reply, close, rate) due to missing domain Skills.
4. Never claim professional diagnostics this Skill does not possess — be honest about what was checked.
5. When basic diagnostics cannot resolve the issue, display the ticket draft and obtain user confirmation before submitting.

Phase 1: Auto-Diagnosis (avoid unnecessary tickets)

CRITICAL: Two types of 401 — never confuse them.

Diagnosis decision tree:

1. Identify the error source: which command or API returned the error?
2. If the error is from qianwen support commands → handle as CLI session issue → qianwen auth login
3. If the error is from model API calls → handle as API Key issue → do NOT run qianwen auth login
4. If unsure, run qianwen doctor --format json for environment diagnostics first

Full diagnostic capabilities:

Only create a ticket if CLI auto-resolve fails or the issue is clearly a platform bug.

Phase 2: Ticket Creation

2.1 Fetch categories (always dynamic, never hardcode)

qianwen support create --list-categories --format json

Select the category that best matches the user's issue. Use references/ticket-categories.md for keyword mapping guidance.

2.2 Compose description

Must start with [QianWen-CLI] prefix. First sentence becomes the ticket title. Max 2000 chars.

[QianWen-CLI] Concise issue summary (≤20 chars, becomes title)

[Symptom]
- What happened / When it started / Frequency

[Impact]
- Affected models/features / Business impact

[Steps tried]
- Attempted fix 1 → result
- Attempted fix 2 → result

[Error details]
- Error code / HTTP status / Relevant log snippet

[Diagnostics]
- qianwen doctor output (summarized)

2.3 Display draft and confirm

Show the ticket draft to the user. Only after user confirms, submit:

qianwen support create \
  --category-id <id> \
  --description "[QianWen-CLI] <summary>. <detailed description>..." \
  --format json

Phase 3: Post-Creation

After successful creation, report:

• Ticket ID and link: https://platform.qianwenai.com/home/support/detail?id=<ticket-id>
• Current status and expected response time (typically 24 hours)

Phase 4: Viewing Customer Service Replies

When using qianwen support view <id> to read customer service replies:

⚠️ 首先检查工单是否处于终态：

status = ticket.status  // 从 qianwen support view 返回的 JSON 中获取

if status in ["closed", "resolved", "confirmed"]:
    // 终态 — 无法回复或修改
    展示工单摘要（标题、日期、最后消息）
    告知用户："该工单已处于终态（{status}），无法回复。"
    询问："是否创建新工单？"
    return

// 非终态 — 继续展示客服回复
if ticket has replies:
    完整转述客服回复（禁止修改）
    如有截图，引导用户到 Web 门户查看

终态状态速查：

关键规则： 只要 status 是 closed、resolved 或 confirmed 中的任何一个，就绝对不能尝试回复或关闭工单。

1. 完整转述，禁止修改：客服的回复内容必须原封不动地呈现给用户，不得删减、概括、改写或重新组织。即使回复中存在错别字、格式问题或表述不清，也必须保持原文。
2. 截图处理：如果客服在回复中提供了截图（图片链接或附件），CLI 无法直接展示图片。此时应：
   • 告知用户："客服在回复中提供了截图，请登录千问AI平台工单页面查看。"
   • 提供工单链接：https://platform.qianwenai.com/home/support/detail?id=<ticket-id>
   • 说明截图的大致位置或上下文（如"截图位于客服回复的第 2 条消息中"）

示例：

Agent (to user):
📋 工单 [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW) — 客服回复如下：

---
[客服 · 2026-07-09 14:30]
您好，经排查您反馈的 401 错误是由于 API Key 过期导致的。请您重新生成 API Key 后重试，操作步骤如下：
1. 登录 https://platform.qianwenai.com/api-keys
2. 点击「创建新的 API Key」
3. 替换代码中的旧 Key

（客服提供了截图，请登录工单页面查看：https://platform.qianwenai.com/home/support/detail?id=0005PYGCW）
---

Attachments

本 Skill 禁止上传任何附件。 无论用户要求上传什么类型的附件（图片、文档、日志、截图、压缩包等），均必须拒绝并引导用户登录千问AI平台工单页面自行操作。

禁止范围包括但不限于：

• 图片文件（PNG、JPG、GIF 等）
• 文档文件（PDF、Word、Excel、TXT 等）
• 日志文件
• 截图
• 压缩包（ZIP、RAR 等）
• 任何其他类型的文件

标准回复：

⚠️ 本 Skill 不支持上传附件。请登录千问AI平台工单页面上传：
👉 https://platform.qianwenai.com/home/support/detail?id=<ticket-id>

注意： 即使在工单描述中需要引用截图或日志内容，也只能以文本形式描述，不得尝试上传文件。

Batch Operations

本 Skill 不支持批量操作。 无论用户要求批量创建、批量回复、批量关闭、批量评价还是批量查询工单，均必须拒绝并引导用户登录千问AI平台工单页面自行操作。

不支持的批量操作包括但不限于：

• 批量创建工单（一次提交多个工单）
• 批量回复工单（对多个工单同时发送回复）
• 批量关闭工单（一次性关闭多个工单）
• 批量评价工单（对多个工单同时评分）
• 批量导出工单数据

标准回复：

⚠️ 本 Skill 不支持批量操作，仅支持逐个处理工单。
如需批量操作，请登录千问AI平台工单页面：
👉 https://platform.qianwenai.com/home/support

替代方案： 如果用户需要处理多个工单，可以逐个进行操作。每次只处理一个工单，完成后再处理下一个。

CLI Command Reference

All commands should use --format json for machine-parseable output. Parse JSON and present human-readable summaries to the user.

Ticket Status Flow

Tickets can be in the following statuses. The table includes both legacy status names and coded statuses — CLI may return either form.

Note: assigned 在不同版本中可能显示为"已分配"或"待响应"；processing 和 dealing 均表示"处理中"；waiting_user 和 wait_feedback 均表示"待反馈"。

Key rule (Agent 层面业务规则): Tickets in terminal statuses should not be closed or replied to. The three terminal statuses are:

• closed (已关闭) — ticket has been closed/cancelled
• resolved (待你评价) — ticket has been resolved and is awaiting user rating
• confirmed (已完成) — ticket has been completed and confirmed by user

注意： CLI 未强制限制对终态工单执行 reply/close 操作（实际调用会返回成功），但这是 Agent 层面必须遵守的业务规则。Agent 必须在调用前检查状态并主动拒绝，不得依赖 CLI 拦截。

Once a ticket enters any terminal status, no further replies or status changes should be made — a new ticket must be created instead.

Always check ticket status with qianwen support view <id> --format json before attempting reply or close operations. If the status is closed, resolved, or confirmed, inform the user that the ticket is in a terminal state and cannot be modified.

Terminal Status Ticket Handling (closed / resolved / confirmed)

If qianwen support view <id> returns status: "closed", status: "resolved", or status: "confirmed":

• Display ticket summary (title, dates, last message)
• Inform user that tickets in this status (已关闭 / 待你评价 / 已完成) cannot be replied to or closed again
• Offer to create a new ticket instead

Close Ticket — Always Invite Rating

--yes is required in non-TTY environments.

After successful closure, always invite the user to rate (see Rating section below).

Rating with Fuzzy Input

Rating scale: 0 = unsatisfied, 1 = neutral, 2 = satisfied. --comment is optional (max 500 chars).

Fuzzy Input Handling

When the user's reply is not a clear number, use semantic understanding to determine the rating, and include the user's original input as the comment:

Rules:

1. If input contains a number (0/1/2), use that as the rating; any remaining text becomes the comment
2. If no number, infer sentiment: positive → 2, neutral/ambiguous → 1, negative → 0
3. Always use the user's original text as the --comment value
4. If the user says "skip" or equivalent, skip rating entirely

qianwen support rate <ticket-id> --rating <n> --comment "<text>" --format json

Output Display Rules

JSON mode (recommended)

1. Parse the JSON and extract relevant data
2. Present a human-readable summary — never dump raw JSON
3. Add analysis AFTER the summary — separated with ---

NEVER

• ❌ Dump raw JSON to the user without interpretation
• ❌ Reformat or summarize text/table output
• ❌ Add prefixes like "Here's your ticket:"
• ❌ Convert text/table output to bullet points

✅ CORRECT:

您的待处理工单：

**[0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW)** — [QianWen-CLI] qianwen support list 报 401
**Status**: Assigned · **Created**: 2026-06-27

---

**💡 Analysis**: 该工单已分配给工程师...

Multi-Language Tickets

本 Skill 仅限中文站使用。 无论客户用什么语言描述问题，工单描述必须使用中文。但客户的原始描述不做翻译，完全展示原文。

1. 工单语言固定为中文：无论用户用中文、英文还是其他语言描述问题，[QianWen-CLI] 前缀后的工单描述必须使用中文撰写。Agent 需要将用户的非中文描述理解为中文工单内容。
2. 客户原文不翻译：当展示客户的问题描述、错误日志、代码片段等内容时，必须完全保留原文，不做任何翻译或改写。即使原文是英文，也原样展示。
3. 客服回复不翻译：工程师回复必须原封不动地转述（遵循 Phase 4 规则），无论语言。
4. 状态显示：同时显示英文状态和中文名称，便于理解。示例：Status: Resolved (待你评价)。
5. 技术内容保留原文：工单描述中的错误日志、代码片段、request-id 等技术内容保留原文（通常是英文），不翻译。
6. CLI 参数说明：qianwen support create 支持 --accept-language zh_CN | en_US 参数，CLI 本身具备多语言能力。但本 Skill 基于中文站业务规则，主动限定工单描述语言为中文。这是 Skill 层面的业务决策，不是 CLI 技术限制。Agent 不得因为用户使用英文就调用 --accept-language en_US。

Error Handling

When CLI fails, classify first, recover, then retry. Never silently skip to fallback.

Retry Parameters

Rule: Never retry more than once. If the retry also fails, immediately fall back to the web portal guidance. Do not create retry loops.

CLI Command Timeout

If a CLI command hangs (e.g., qianwen auth login --complete does not return):

1. Wait up to 30 seconds for the command to complete
2. If still hanging, interrupt the command (Ctrl+C or timeout)
3. Fallback: Guide the user to submit the ticket via the web portal instead:
   • Ticket creation page: https://platform.qianwenai.com/home/support
   • Inform the user: "The CLI is not responding. You can submit this ticket directly on the web portal."

Cascading Failure Handling

When a recovery strategy itself fails (e.g., auth login fails during auth-failure recovery, or qianwen support list fails during ticket-not-found recovery):

1. Do not retry the same recovery more than once
2. If the second attempt also fails, stop automated recovery
3. Final fallback: Guide the user to the web portal:
   • Ticket page: https://platform.qianwenai.com/home/support
   • Inform the user: "The CLI is experiencing issues. Please submit your request directly on the web portal."
4. Provide the user with a summary of what was attempted, so they can include it in their web ticket if needed

Exit Codes

Anti-Patterns

• Never dump raw JSON — always parse and summarize
• Never confuse CLI session with API key — never offer $DASHSCOPE_API_KEY as a fix for CLI AUTH_REQUIRED
• Never use qianwen auth login to fix a model API 401 — model API 401 is an API Key issue, not a CLI session issue; re-logging in cannot fix it; always check qianwen doctor and report Key status instead
• Never create a ticket without running qianwen doctor first
• Never hardcode category IDs — always fetch with --list-categories --format json
• Never include plaintext credentials in ticket descriptions or replies — always use masked formats
• Never skip auto-diagnosis — many issues are resolvable via CLI without a ticket
• Never omit --format json — ensures machine-parseable output
• Never fabricate ticket IDs or statuses — always query from CLI
• Never skip rating invitation after closing a ticket
• Never reply to a closed, resolved, or confirmed ticket — tickets in "已关闭", "待你评价", or "已完成" status are terminal; offer to create a new ticket instead
• Never upload any attachments — this skill is strictly prohibited from uploading any files (images, documents, logs, screenshots, archives, etc.); always decline and direct users to the web portal
• Never modify customer service replies — always relay them verbatim to the user, no summarizing, paraphrasing, or editing
• Never perform authorization on behalf of the user — authorization operations are prohibited in Agent; must be done by the user on the web portal; always provide the ticket link for easy access
• Never ignore screenshots in replies — always notify the user and guide them to the web portal to view screenshots
• Never attempt batch operations — this skill only supports processing one ticket at a time; batch create/reply/close/rate/export is not supported; always decline and direct users to the web portal

Update Check

When the user asks to check for updates, first identify the update target:

Checking Skills package version:

1. Find qianwen-update-check: Look for qianwen-update-check/SKILL.md in sibling skill directories.
2. If found — run: python3 <dir>/scripts/check_update.py --print-response and report the result.
3. If not found — inform the user that the update check skill is not installed; suggest installing qianwen-ai skills package.

Important: Any update operation must first explain the target and impact, then obtain user confirmation before executing.

Examples

Example: Create ticket

User: qianwen support list 一直报 401，帮我提交工单

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated: false (CLI session expired)
2. [Pre-flight] qianwen version → 1.4.0 ✅
3. [Auto-diagnose] 401 from `qianwen support` command → CLI session issue → run qianwen auth login → user confirms still failing after re-login
4. [Fetch categories] qianwen support create --list-categories --format json → select "CLI & SDK Issues"
5. [Draft] Compose description with doctor output

Agent (to user):
📋 工单草稿：
**Title**: [QianWen-CLI] support list 命令持续返回 401
**Category**: CLI & SDK Issues
**Description**: [Symptom] ... [Diagnostics] ...
是否提交此工单？(yes/no)

User: yes

Agent (to user):
✅ 工单已提交！
**工单 [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW)**
**Status**: Created · 预计 24 小时内回复。
如需上传截图，请在工单页面操作。

Example: Model API 401 — correct handling (no qianwen auth login)

User: qwen-text 调用返回 401，帮我提工单

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated ✅
2. [Auto-diagnose] 401 from model API (NOT from qianwen support command) → API Key issue
3. [Check] qianwen doctor --format json → DASHSCOPE_API_KEY: set
4. [Decision] This is a model API 401, NOT a CLI session 401 → do NOT run qianwen auth login
5. [Check domain Skill] qianwen-ops-auth not installed → report Key status only, cannot do deeper API Key investigation
6. [Fetch categories] → select "API Issues"
7. [Draft] Compose description, note that API Key is set but returning 401

Agent (to user):
📋 诊断结果：模型 API 返回 401，API Key 已设置。这可能是 Key 权限不匹配或已失效。
（注意：这不是 CLI 登录问题，重新登录无法解决。）

工单草稿：
**Title**: [QianWen-CLI] qwen-text API 返回 401，Key 已设置
**Category**: API Issues
**Description**: [Symptom] ... [Diagnostics] ...
是否提交此工单？(yes/no)

分支：当 qianwen-ops-auth 已安装时

User: qwen-text 调用返回 401，帮我提工单

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated ✅
2. [Auto-diagnose] 401 from model API (NOT from qianwen support command) → API Key issue
3. [Check] qianwen doctor --format json → DASHSCOPE_API_KEY: set
4. [Decision] This is a model API 401, NOT a CLI session 401 → do NOT run qianwen auth login
5. [Check domain Skill] qianwen-ops-auth IS installed → delegate to it for deeper API Key investigation
6. [Delegate] Load qianwen-ops-auth skill → run its diagnostic flow:
   - qianwen-ops-auth checks Key validity, expiration, permission scope
   - qianwen-ops-auth reports: "API Key expired at 2026-08-10, needs regeneration"
7. [Result] Root cause identified: API Key expired → no need to create ticket
8. [Guide] Inform user to regenerate API Key on web portal

Agent (to user):
📋 诊断结果（由 qianwen-ops-auth 深入排查）：
你的 API Key 已于 2026-08-10 过期，这就是 401 的原因。
请前往千问AI平台重新生成 API Key：
👉 https://platform.qianwenai.com/api-keys

（无需提交工单，问题已定位。）

Example: Confirmed ticket

User: reply to ticket 00069R8Z4Y

Agent (internal): qianwen support view 00069R8Z4Y --format json → status: "confirmed"

Agent (to user):
📋 工单 [00069R8Z4Y](https://platform.qianwenai.com/home/support/detail?id=00069R8Z4Y) 状态为已完成 (confirmed)。
**Title**: [QianWen-CLI] qianwen support list 报 401
**Confirmed**: 2026-06-28
**Last message**: Issue resolved.
该工单已处于终态，无法回复。**是否创建新工单？** (yes/no)

Example: Reply to ticket

User: 回复工单 0005PYGCW，补充一下错误日志

Agent (internal):
1. qianwen support view 0005PYGCW --format json → status: "dealing"
2. Status is not "confirmed" → reply is allowed

Agent (to user):
📋 工单 [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW) — [QianWen-CLI] qianwen support list 报 401
**Status**: Dealing · **Last updated**: 2026-06-28
请问您希望如何回复？

User: 补充一下，错误日志如下：HTTP 401 Unauthorized, x-request-id: abc123, 从昨天下午开始出现的

Agent (internal):
- Run: qianwen support reply 0005PYGCW --message "补充一下，错误日志如下：HTTP 401 Unauthorized, x-request-id: abc123, 从昨天下午开始出现的" --format json

Agent (to user):
✅ 回复已发送至工单 [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW)。
工程师将收到通知，预计 24 小时内回复。

Example: Fuzzy rating

User: close ticket 0005PYGCW

Agent (internal): qianwen support close 0005PYGCW --yes --format json

Agent (to user):
✅ 工单 [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW) 已关闭。
是否对本次服务进行评价？
🟢 2 = 满意  🟡 1 = 一般  🔴 0 = 不满意
回复数字 (0-2)，也可附带评价内容。回复 "skip" 跳过。

User: 还行吧

Agent (internal):
- Semantic analysis: "还行吧" → neutral → rating = 1
- Comment: "还行吧"
- Run: qianwen support rate 0005PYGCW --rating 1 --comment "还行吧" --format json

Agent (to user):
✅ 评价已提交（一般）。评价内容："还行吧"。感谢您的反馈！

Example: Authorization request from engineer

User: 查看工单 0005PYGCW 的回复

Agent (internal):
1. qianwen support view 0005PYGCW --format json
2. 检测到工程师回复中包含授权请求："请重新生成您的 API Key 并在代码中替换"
3. 触发授权规则 → 立即停止其他操作

Agent (to user):
📋 工单 [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW) — 工程师回复如下：

---
[客服 · 2026-07-10 14:30]
您好，经排查您反馈的 401 错误是由于 API Key 过期导致的。请您重新生成 API Key 后重试，操作步骤如下：
1. 登录 https://platform.qianwenai.com/api-keys
2. 点击「创建新的 API Key」
3. 替换代码中的旧 Key
---

⚠️ 工程师要求您进行授权操作（重新生成 API Key）。
**授权操作禁止在 Agent 中执行，必须由您本人登录千问AI平台工单页面完成。**
👉 请前往工单页面操作：https://platform.qianwenai.com/home/support/detail?id=0005PYGCW

完成授权后，请告诉我结果，我可以帮您继续后续操作。

Example: User requests attachment upload

User: 帮我把这个截图上传到工单 0005PYGCW

Agent (to user):
⚠️ 本 Skill 不支持上传附件。请登录千问AI平台工单页面上传：
👉 https://platform.qianwenai.com/home/support/detail?id=0005PYGCW

Example: API 调用失败 — 使用 qianwen usage logs 诊断

User: 调用 qwen-plus 一直返回 500 错误，帮我提工单

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated ✅
2. [Pre-flight] qianwen version → 1.4.0 ✅ (supports usage logs)
3. [Auto-diagnose] 500 from model API → could be platform issue or transient
4. [Diagnose] qianwen usage logs --status 500 --format json → returns 3 records in last 24h:
   - record 1: model=qwen-plus, status=500, time=2026-08-13 14:22, request-id=req-abc123
   - record 2: model=qwen-plus, status=500, time=2026-08-13 15:01, request-id=req-abc456
   - record 3: model=qwen-plus, status=500, time=2026-08-13 16:45, request-id=req-abc789
5. [Analyze] 3 failures within 2.5 hours, same model, all 500 → likely platform-side issue, not transient
6. [Decision] Pattern suggests platform bug → ticket warranted
7. [Fetch categories] qianwen support create --list-categories --format json → select "API Issues"
8. [Draft] Compose description with usage logs evidence and request-ids

Agent (to user):
📋 诊断结果：过去 24 小时内 qwen-plus 共出现 3 次 500 错误（14:22、15:01、16:45），集中在今天下午，疑似平台侧问题。

工单草稿：
**Title**: [QianWen-CLI] qwen-plus 持续返回 500 错误
**Category**: API Issues
**Description**:
[QianWen-CLI] qwen-plus 连续返回 500，疑似平台故障

[Symptom]
- 调用 qwen-plus 模型返回 HTTP 500
- 首次出现：2026-08-13 14:22
- 频率：24 小时内 3 次

[Error details]
- request-id: req-abc123, req-abc456, req-abc789
- 所有请求均返回 500

[Diagnostics]
- qianwen usage logs --status 500 确认 3 条失败记录
- qianwen doctor 环境检查正常

是否提交此工单？(yes/no)

分支：usage logs 显示为偶发错误时

Agent (internal):
4. [Diagnose] qianwen usage logs --status 500 --format json → returns 1 record:
   - record 1: model=qwen-plus, status=500, time=2026-08-13 03:12, request-id=req-xyz999
5. [Analyze] Only 1 failure in 24h, at 03:12 (off-peak) → likely transient error
6. [Decision] Isolated incident, not a pattern → advise user to retry, no ticket needed yet

Agent (to user):
📋 诊断结果：过去 24 小时内 qwen-plus 仅有 1 次 500 错误（凌晨 03:12），属于偶发情况。
建议先重试调用，如果问题复现再提交工单。
如需查看完整调用记录，可运行：qianwen usage logs --status 500 --format json

Example: Network timeout — retry once, then fallback to web portal

User: 帮我提交工单，qianwen doctor 显示网络正常但 create 一直超时

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated ✅
2. [Pre-flight] qianwen version → 1.4.0 ✅
3. [Auto-diagnose] qianwen doctor --format json → network: ok, auth: ok
4. [Fetch categories] qianwen support create --list-categories --format json → success
5. [Draft] Compose description, user confirms → submit
6. [Submit] qianwen support create --category-id <id> --description "..." --format json
   → TIMEOUT after 30 seconds (exit code 3)
7. [Retry] Wait 2 seconds → retry the same command
   → TIMEOUT again after 30 seconds (exit code 3)
8. [Decision] Two consecutive timeouts → stop retrying, fall back to web portal
9. [Total wait] 30s + 2s + 30s = 62s (within acceptable range for one retry)

Agent (to user):
📋 CLI 连续两次提交超时（各等待 30 秒），可能是网络波动或平台侧暂时不可用。

建议您直接通过 Web 门户提交工单，无需等待 CLI 恢复：
👉 https://platform.qianwenai.com/home/support

工单草稿已准备好，您可以复制以下内容到 Web 门户：
**Title**: [QianWen-CLI] qianwen doctor 正常但 create 命令持续超时
**Category**: CLI & SDK Issues
**Description**: [Symptom] ... [Diagnostics] ...

如需等 CLI 恢复后再试，请告诉我。

Example: Multi-language ticket — English user

User: I keep getting a 401 error when calling qwen-vision. Can you create a ticket?

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated ✅
2. [Auto-diagnose] 401 from model API (NOT from qianwen support command) → API Key issue
3. [Check] qianwen doctor --format json → DASHSCOPE_API_KEY: set
4. [Decision] Model API 401 → do NOT run qianwen auth login
5. [Check domain Skill] qianwen-ops-auth not installed → report Key status only
6. [Fetch categories] qianwen support create --list-categories --format json → select "API Issues"
7. [Language detection] User writes in English → but 本 Skill 仅限中文站, ticket description must be in Chinese
8. [Draft] Compose description in Chinese with [QianWen-CLI] prefix; preserve user's original English text verbatim in [Error details]

Agent (to user):
📋 Diagnostic result: The model API returns 401. Your API Key is set but may be invalid or mismatched.
(Note: This is NOT a CLI session issue — re-logging in cannot fix it.)

Ticket draft:
**Title**: [QianWen-CLI] qwen-vision API 返回 401，Key 已设置
**Category**: API Issues
**Description**:
[QianWen-CLI] qwen-vision API 返回 401，Key 已设置但仍报错

[问题现象]
- 调用 qwen-vision 模型时返回 HTTP 401 Unauthorized
- 开始时间：2026-08-13
- 频率：每次请求都失败

[客户原文 / Error details]
- HTTP 401, x-request-id: req-def456
- API Key is set (verified via qianwen doctor)

[诊断结果]
- qianwen doctor：环境正常，API Key 已设置
- 非 CLI session 问题（auth status: authenticated）

Shall I submit this ticket? (yes/no)

User: yes

Agent (internal):
- Run: qianwen support create --category-id <id> --description "[QianWen-CLI] qwen-vision API 返回 401..." --format json

Agent (to user):
✅ Ticket submitted!
**Ticket [0007AB123](https://platform.qianwenai.com/home/support/detail?id=0007AB123)**
**Status**: Created · Expected response within 24 hours.

Example: Pagination — browsing a large ticket list

User: 帮我看看我所有的工单

Agent (internal):
1. [Pre-flight] qianwen auth status --format json → authenticated ✅
2. [Pagination] User asks for "all tickets" → fetch first page with default page-size 10
3. [Query] qianwen support list --page 1 --page-size 10 --format json → returns 10 records
4. [Check] 10 records returned = page-size → there may be more pages
5. [Present] Show first page summary, ask if user wants to see more

Agent (to user):
📋 您的工单列表（第 1 页，共 10 条）：

| # | 工单 | 标题 | 状态 |
|---|------|------|------|
| 1 | [0007AB123](https://platform.qianwenai.com/home/support/detail?id=0007AB123) | qwen-vision API 返回 401 | Created |
| 2 | [00069R8Z4Y](https://platform.qianwenai.com/home/support/detail?id=00069R8Z4Y) | support list 报 401 | Confirmed |
| ... | ... | ... | ... |

当前显示最近 10 条。是否查看下一页？(yes/no)

User: yes

Agent (internal):
6. [Paginate] qianwen support list --page 2 --page-size 10 --format json → returns 7 records
7. [Check] 7 records < page-size (10) → this is the last page
8. [Present] Show second page summary, indicate it's the last page

Agent (to user):
📋 您的工单列表（第 2 页，共 7 条）：

| # | 工单 | 标题 | 状态 |
|---|------|------|------|
| 11 | [0005PYGCW](https://platform.qianwenai.com/home/support/detail?id=0005PYGCW) | qwen-text API 返回 401 | Resolved |
| ... | ... | ... | ... |

当前显示第 11-17 条，共 17 条工单。这是最后一页。
如需查看某个工单的详情，请告诉我工单号。

Pagination Best Practices

When listing tickets with qianwen support list, use pagination to avoid timeouts and excessive data:

Rules:

1. Page size 限制：--page-size 必须在 1-10 之间（CLI 硬性限制），默认 10。超过 10 会直接报错 INVALID_ARGUMENT。
2. Incremental pagination: Fetch one page at a time. Do not loop through all pages automatically.
3. Stop condition: If a page returns fewer records than --page-size, it is the last page.
4. User guidance: If the user asks "show all my tickets", show the first page and ask if they want to see more, rather than fetching everything.

FAQ / Troubleshooting

References