返回技能市场
企业经营 安全

千问AI-工单支持

@qianwen-ai/qianwenai-support

通过千问 CLI 管理支持工单——创建、列出、查看、回复、关闭和评价。提交前运行基础 CLI 诊断。其他千问 Skills 是可选协作者，而非运行时依赖；缺少这些 Skills 时，继续执行千问 CLI 只读检查，绝不阻塞工单管理。适用场景：用户明确要求提交/创建/查看/回复/关闭/评价工单，或提到 'ticket'、'工单'、'提交工单'、'转人工'。不适用场景：一般产品问题、模糊反馈、'provide feedback'、'支持' 或非千问产品问题——先确认用户意图。

千问AI平台 热度 643v0.0.1

千问-工单支持

通过 千问 CLI v1.2.0+ 的 qianwen support 命令管理支持工单。支持完整的工单生命周期：创建、列出、查看、回复、关闭和评价。

任何支持 Agent Skills 且能执行本地命令的 Agent 都可以加载此 skill。其他千问 Skills（认证、用量、模型选择等）是可选协作者——存在时，它们可提供更深入的领域诊断；缺少时，此 skill 会继续执行千问 CLI 只读检查，绝不阻塞工单管理。

Skill 目录

| 位置 | 用途 | |----------|---------| | references/auth-flow.md | 完整认证流程（需要登录时加载） | | references/ticket-categories.md | 分类关键词映射参考 |

前置条件

  • 千问 CLI v1.2.0+（验证：qianwen version）。安装：npm install -g @qianwenai/qianwen-cli。Node.js >= 18。
  • 认证：通过 qianwen auth login 建立 CLI 会话（浏览器设备流程）。如需完整认证流程，请加载 references/auth-flow.md。

安全

禁止以明文输出任何凭证值。仅报告状态（例如 "authenticated" / "expired"）。

敏感信息脱敏（描述与回复）

编写工单描述或起草回复时，始终对敏感信息进行脱敏：

  • ❌ 禁止包含：完整邮箱、用户 ID、电话号码、API 密钥、AccessKey、密码
  • ✅ 使用脱敏格式：
  • Email: zephy*****@gmail.com
  • Phone: 138****1234
  • API Key / AccessKey: sk-****xxxx（仅保留前 3 位和后 4 位）
  • 用户 ID / 工号: 08****94

两套凭证体系——切勿混淆

| 凭证 | 用途 | 提供方式 | |------------|---------|----------------| | API 密钥（sk-...） | 在代码中调用模型 APIs | $DASHSCOPE_API_KEY / $QIANWEN_API_KEY 环境变量 | | CLI 会话 | 授权 CLI 子命令 | qianwen auth login（浏览器设备流程） |

红线：禁止提供 $DASHSCOPE_API_KEY 来修复 CLI AUTH_REQUIRED 错误。

认证流程（TL;DR）

  1. qianwen auth status --format json → authenticated: true → 跳至命令执行
  2. qianwen auth login --init-only --format json → 提取 verification_url → 在浏览器中打开
  3. qianwen auth login --complete --format json → 轮询直至出现 success 事件
完整流程（两阶段登录、JSON 事件、TTY 处理）：加载 references/auth-flow.md。

通用规则：Web 门户指引

每当引导用户前往千问AI平台工单页面时（无论出于何种原因：查看截图、执行授权、上传附件等），始终提供具体的工单链接，以便用户直接点击：

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

禁止只说"请登录 Web 门户"而不提供实际链接。

通用规则：工单 ID 超链接

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

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

示例：

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

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

通用规则：回复工作流

工单已有工程师回复且用户需要回应时，必须按顺序遵循以下三步工作流：

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

通用规则：授权请求——立即停止

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

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

触发后必须执行的动作：

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

核心工作流

阶段 0：预检查（静默执行）

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

仅当某项检查阻塞操作时，才向用户说明问题。

可选协作与回退

千问 CLI 可准确执行查询和操作；此 Skill 直接调用 CLI 进行基础诊断和工单管理。其他千问 Skills 并非能力更强，也不是必需依赖——它们在特定领域（认证、用量、计费、模型选择等）积累了更精细的判断能力。

规则：

  1. 当检测到并已安装对应的领域 Skill 时：优先采用其专门的诊断流程进行深入排查。
  2. 当对应的领域 Skill 未安装时：使用千问 CLI 执行此 Skill 自身的只读基础检查。
  3. 绝不能因缺少领域 Skills 而阻塞工单管理（创建、列出、查看、回复、关闭、评价）。
  4. 禁止声称具备此 Skill 并不具备的专业诊断能力——应如实说明已执行的检查。
  5. 当基础诊断无法解决问题时，展示工单草稿，并在提交前取得用户确认。

| 问题类型 | 领域 Skill 可用 | 仅安装千问-工单支持 | |---|---|---| | 模型 API 返回 401 | 使用 qianwen-ops-auth 排查 API Key | 区分该 401 来自模型 API 还是 qianwen support 命令；仅报告 Key 是否已设置，禁止显示 Key 值；禁止使用 qianwen auth login 修复模型 API 401 | | 用量或配额异常 | 使用 qianwen-usage 进行详细查询和解释 | 运行 qianwen usage summary 和其他只读命令；数据不可用时明确说明 | | 计费或充值问题 | 使用 qianwen-payment 执行资金安全流程 | 仅查询余额；不得主动判断余额不足，不得发起充值，不得打开充值页面 | | 未找到模型 | 使用 qianwen-model-selector 查询能力并寻找替代方案 | 仅使用 qianwen models search 验证模型是否存在；不得编造替代模型 | | 文本/图片/视频/音频任务失败 | 使用对应的执行 Skill 排查参数和任务状态 | 收集模型、时间、错误码、request-id；运行 doctor 或 usage logs；不得假装具备领域参数诊断能力 | | request-id 或 4xx/5xx 调用记录 | 使用 qianwen-usage 或直接调用 CLI | 直接使用 qianwen usage logs——无需安装用量 Skill |

阶段 1：自动诊断（避免不必要的工单）

关键：401 分为两类——切勿混淆。

| 401 来源 | 原因 | 正确修复方式 | 错误修复方式 | |---|---|---|---| | qianwen support 命令返回 401 | CLI 会话令牌已过期 | qianwen auth login → 使用 qianwen auth status 验证 | — | | 模型 API（例如 qwen-text、qwen-vision）返回 401 | API Key 无效、缺失或不匹配 | 若已安装 qianwen-ops-auth：使用该 Skill。否则：报告 Key 状态（已设置/未设置），禁止显示 Key 值，并引导用户在 Web 门户重新生成 | qianwen auth login（CLI 登录无法修复模型 API 401） |

诊断决策树：

  1. 识别错误来源：哪个命令或 API 返回了错误？
  2. 如果错误来自 qianwen support 命令 → 按 CLI 会话问题处理 → qianwen auth login
  3. 如果错误来自模型 API 调用 → 按 API Key 问题处理 → 禁止运行 qianwen auth login
  4. 如果不确定，先运行 qianwen doctor --format json 进行环境诊断

完整诊断能力：

| 问题分类 | CLI 自动解决能力 | |---|---| | CLI 会话过期 / qianwen support 返回 401 | qianwen auth login → 使用 qianwen auth status 验证 | | 模型 API 返回 401（API Key 问题） | 区分错误来源；仅报告 Key 状态；若 qianwen-ops-auth 不可用，则引导用户前往 Web 门户 | | 配额耗尽 | qianwen usage summary --format json → 建议切换模型或升级套餐 | | CLI 版本不匹配 | qianwen update → 使用 qianwen version 验证 | | 配置错误 | qianwen config list --format json → 识别并修复 | | 网络/连接问题 | qianwen doctor --format json → 报告诊断结果 | | 未找到模型 | qianwen models search "<keyword>" --format json → 建议替代方案 | | 4xx/5xx 错误或 request-id 查询 | qianwen usage logs --format json → 按状态码或 request-id 查询（CLI v1.4.0+） |

仅当 CLI 自动解决失败或问题明显为平台缺陷时，才创建工单。

阶段 2：创建工单

2.1 获取分类（始终动态获取，禁止硬编码）

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

选择最符合用户问题的分类。参考 references/ticket-categories.md 中的关键词映射指引。

2.2 编写描述

必须以 [QianWen-CLI] 前缀开头。第一句话将成为工单标题。最多 2000 个字符。

[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 展示草稿并确认

向用户展示工单草稿。仅在用户确认后再提交：

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

阶段 3：创建后处理

创建成功后，报告：

  • 工单 ID 和链接：https://platform.qianwenai.com/home/support/detail?id=<ticket-id>
  • 当前状态和预计响应时间（通常为 24 小时）

阶段 4：查看客服回复

使用 qianwen support view <id> 读取客服回复时：

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

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

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

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

终态状态速查：

| 状态码 | 中文名称 | 是否终态 | 能否回复 | |--------|----------|----------|----------| | created | 已创建 | 否 | 否（等待分配） | | assigned / dealing / processing | 已分配 / 处理中 | 否 | 是 | | waiting_user / wait_feedback | 待反馈 | 否 | 是（需先补充信息） | | resolved | 待你评价 | 是 | 否 | | closed | 已关闭 | 是 | 否 | | confirmed | 已完成 | 是 | 否 |

关键规则： 只要 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）
---

附件

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

禁止范围包括但不限于：

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

标准回复：

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

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

批量操作

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

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

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

标准回复：

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

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

CLI 命令参考

所有命令均应使用 --format json 以生成机器可解析的输出。解析 JSON 并向用户展示便于阅读的摘要。

| 命令 | 用途 | 关键参数 | |---------|---------|-----------| | qianwen support create | 创建工单 | --category-id <id> --description "<text>" --format json | | qianwen support create | 列出分类 | --list-categories --format json | | qianwen support list | 列出所有工单 | --page <n> --page-size <n> --format json | | qianwen support view <id> | 查看工单及消息 | --format json | | qianwen support reply <id> | 回复工单 | --message "<text>" --format json | | qianwen support close <id> | 关闭/取消工单 | --yes --format json | | qianwen support rate <id> | 评价已解决的工单 | --rating <0-2> --comment "<text>" --format json | | qianwen doctor | 运行诊断 | --format json | | qianwen auth status | 检查认证状态 | --format json | | qianwen usage logs | 查询 API 调用记录（4xx/5xx、request-id） | --status <code> --request-id <id> --format json（CLI 版本 v1.4.0+） | | qianwen usage summary | 查询用量/配额摘要 | --format json |

工单状态流转

工单可能处于以下状态。表中同时包含旧版状态名称和编码状态——CLI 可能返回任一形式。

| 编码 | 状态 | 中文名称 | 说明 | |------|--------|----------|------| | — | created | 已创建 | 工单刚提交 | | — | assigned | 已分配 / 待响应 | 工单已分配给工程师 | | — | processing / dealing | 处理中 | 工程师正在处理 | | — | waiting_user / wait_feedback | 待反馈 | 等待用户补充信息 | | — | feedback | 已反馈 | 用户已补充信息 | | — | wait_confirm | 待确认 | 工程师已解决，等待用户确认 | | — | resolved | 待你评价 | 工单已解决，等待用户评价（终态） | | — | closed | 已关闭 | 工单已关闭/取消（终态） | | 6 | confirmed | 已完成 | 用户已确认完成（终态） |

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

关键规则 (Agent 层面业务规则): 处于终态的工单不得关闭或回复。三种终态为：

  • closed (已关闭) — 工单已关闭/取消
  • resolved (待你评价) — 工单已解决，正在等待用户评价
  • confirmed (已完成) — 工单已完成并经用户确认
注意： CLI 未强制限制对终态工单执行 reply/close 操作（实际调用会返回成功），但这是 Agent 层面必须遵守的业务规则。Agent 必须在调用前检查状态并主动拒绝，不得依赖 CLI 拦截。

工单一旦进入任何终态，就不应再回复或更改状态——必须改为创建新工单。

每次尝试回复或关闭操作前，都必须使用 qianwen support view <id> --format json 检查工单状态。如果状态为 closed、resolved 或 confirmed，请告知用户该工单已处于终态，无法修改。

终态工单处理（closed / resolved / confirmed）

如果 qianwen support view <id> 返回 status: "closed"、status: "resolved" 或 status: "confirmed"：

  • 显示工单摘要（标题、日期、最后一条消息）
  • 告知用户，处于此状态（已关闭 / 待你评价 / 已完成）的工单无法回复或再次关闭
  • 改为提议创建新工单

关闭工单——始终邀请评价

在非 TTY 环境中，--yes 是必需的。

成功关闭后，始终邀请用户评价（见下方“评价”部分）。

模糊输入评价

评分标准：0 = 不满意，1 = 一般，2 = 满意。--comment 为可选项（最多 500 个字符）。

模糊输入处理

当用户的回复不是明确数字时，使用语义理解确定评分，并将用户的原始输入作为评价内容：

| 用户输入 | 解析后的评分 | 评价内容 | |------------|-------------------|---------| | 2 | 2 | （无） | | 2 很好 | 2 | "很好" | | 还行 | 1 | "还行" | | 一般般 | 1 | "一般般" | | 不太好 / 差 | 0 | "不太好" / "差" | | 非常满意，谢谢 | 2 | "非常满意，谢谢" | | skip | （跳过评价） | — |

规则：

  1. 如果输入包含数字（0/1/2），将该数字作为评分；其余文本作为评价内容
  2. 如果没有数字，根据情感倾向推断：正面 → 2，中性/模棱两可 → 1，负面 → 0
  3. 始终将用户的原始文本用作 --comment 的值
  4. 如果用户说 "skip" 或同义表达，则完全跳过评价
qianwen support rate <ticket-id> --rating <n> --comment "<text>" --format json

输出展示规则

JSON 模式（推荐）

  1. 解析 JSON并提取相关数据
  2. 展示便于阅读的摘要——禁止转储原始 JSON
  3. 在摘要之后添加分析——以 --- 分隔

禁止

  • ❌ 未经解释就向用户转储原始 JSON
  • ❌ 重新格式化或总结文本/表格输出
  • ❌ 添加“以下是您的工单：”之类的前缀
  • ❌ 将文本/表格输出转换为项目符号列表

✅ 正确：

您的待处理工单：

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

---

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

多语言工单

本 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。

错误处理

当 CLI 失败时，先分类，再恢复，然后重试。禁止悄然跳到回退方案。

| 类别 | 恢复方式 | |----------|----------| | auth-failure | 执行 3 步登录流程 → 重试原命令 | | not-installed | 显示安装命令 → 请用户安装 → 重试 | | version-mismatch | 建议 qianwen update → 升级 → 重试 | | network-timeout | 等待 2s 后重试一次；只有第二次失败后才询问是否稍后重试 | | rate-limit | 告知用户，等待后重试 | | ticket-not-found | 使用 qianwen support list 验证工单 ID → 修正后重试 | | other | 显示原始 stderr；提供文档链接 |

重试参数

| 参数 | 值 | 说明 | |-----------|-------|-------| | 网络超时 | 30 秒 | 每次 CLI 命令调用 | | 重试间隔 | 2 秒 | 重试间隔 | | 最大重试次数 | 1 | 对于 network-timeout 仅重试一次；第二次失败 → 执行回退 | | 身份验证登录超时 | 30 秒 | 用于轮询 qianwen auth login --complete | | 最长总等待时间 | 60 秒 | 单次操作所有重试的总时长 |

规则：禁止重试超过一次。如果重试仍然失败，立即回退到 Web 门户引导。不得创建重试循环。

CLI 命令超时

如果 CLI 命令卡住（例如 qianwen auth login --complete 没有返回）：

  1. 最多等待 30 秒，让命令完成
  2. 如果仍然卡住，中断命令（Ctrl+C 或超时）
  3. 回退方案：引导用户改为通过 Web 门户提交工单：
  • 工单创建页面：https://platform.qianwenai.com/home/support
  • 告知用户："CLI 无响应。您可以直接在 Web 门户提交此工单。"

级联故障处理

当恢复策略本身失败时（例如，在身份验证失败恢复期间，身份验证登录失败；或者在工单未找到恢复期间，qianwen support list 失败）：

  1. 同一恢复操作不得重试超过一次
  2. 如果第二次尝试仍然失败，停止自动恢复
  3. 最终回退方案：引导用户前往 Web 门户：
  • 工单页面：https://platform.qianwenai.com/home/support
  • 告知用户："CLI 出现问题。请直接在 Web 门户提交您的请求。"
  1. 向用户提供已尝试操作的摘要，以便他们在需要时将其写入 Web 工单

退出码

| 代码 | 含义 | |------|---------| | 0 | 成功 | | 1 | 常规错误/用法错误 | | 2 | 身份验证错误 | | 3 | 网络错误 | | 4 | 配置错误 | | 130 | 已中断 |

反模式

  • 禁止原样输出 JSON——始终解析并概括
  • 禁止混淆 CLI 会话与 API Key——禁止提出使用 $DASHSCOPE_API_KEY 修复 CLI AUTH_REQUIRED
  • 禁止使用 qianwen auth login 修复模型 API 401——模型 API 401 是 API Key 问题，不是 CLI 会话问题；重新登录无法修复；始终检查 qianwen doctor，并改为报告 Key 状态
  • 禁止在未先运行 qianwen doctor 的情况下创建工单
  • 禁止硬编码分类 ID——始终使用 --list-categories --format json 获取
  • 禁止在工单描述或回复中包含明文凭据——始终使用脱敏格式
  • 禁止跳过自动诊断——许多问题无需创建工单即可通过 CLI 解决
  • 禁止省略 --format json——确保输出可由机器解析
  • 禁止编造工单 ID 或状态——始终通过 CLI 查询
  • 禁止在关闭工单后跳过评价邀请
  • 禁止回复已关闭、已解决或已确认的工单——处于 "已关闭"、"待你评价" 或 "已完成" 状态的工单均为终态；应改为询问是否创建新工单
  • 禁止上传任何附件——严禁此 skill 上传任何文件（图片、文档、日志、截图、压缩包等）；始终拒绝并引导用户前往 Web 门户
  • 禁止修改客服回复——始终向用户原封不动地转述，不得概括、改写或编辑
  • 禁止代表用户执行授权——禁止在 Agent 中执行授权操作；必须由用户本人在 Web 门户完成；始终提供工单链接，方便用户访问
  • 禁止忽略回复中的截图——始终通知用户，并引导用户前往 Web 门户查看截图
  • 禁止尝试批量操作——此 skill 一次仅支持处理一个工单；不支持批量创建/回复/关闭/评价/导出；始终拒绝并引导用户前往 Web 门户

更新检查

当用户要求检查更新时，首先确定更新目标：

| 用户意图 | 检查对象 | 命令 | |---|---|---| | "CLI 是不是最新版" / "qianwen 版本" | 千问 CLI 二进制文件 | qianwen version --check | | "Support Skill 是不是最新版" / "Skills 合集版本" | qianwen-ai Skills 包 | 见下文 | | 不明确 | 请用户澄清 | — |

检查 Skills 包版本：

  1. 查找 qianwen-update-check：在同级 skill 目录中查找 qianwen-update-check/SKILL.md。
  2. 如果找到——运行：python3 <dir>/scripts/check_update.py --print-response，并报告结果。
  3. 如果未找到——告知用户未安装更新检查 skill；建议安装 qianwen-ai skills 包。

重要：任何更新操作都必须先说明目标和影响，然后获得用户确认后才能执行。

示例

示例：创建工单

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 小时内回复。
如需上传截图，请在工单页面操作。

示例：模型 API 401——正确处理方式（不运行 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

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

示例：已确认的工单

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)

示例：回复工单

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 小时内回复。

示例：模糊评价

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):
✅ 评价已提交（一般）。评价内容："还行吧"。感谢您的反馈！

示例：工程师发起授权请求

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

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

示例：用户要求上传附件

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

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

示例：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

示例：网络超时——重试一次，然后回退到 Web 门户

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 恢复后再试，请告诉我。

示例：多语言工单——英语用户

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.

示例：分页——浏览大型工单列表

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 条工单。这是最后一页。
如需查看某个工单的详情，请告诉我工单号。

分页最佳实践

使用 qianwen support list 列出工单时，应使用分页以避免超时和数据量过大：

| 场景 | 推荐命令 | |----------|---------------------| | 查看近期工单 | qianwen support list --page 1 --page-size 5 --format json | | 浏览所有活跃工单 | 先运行 qianwen support list --page 1 --page-size 10 --format json，然后进行分页 | | 查找特定工单 | 直接使用 qianwen support view <id>，而不是扫描完整列表 | | 大量积压（100+ 个工单） | 从 --page-size 10 开始，仅在需要时向后翻页；禁止一次获取全部数据 |

规则：

  1. 分页大小限制：--page-size 必须在 1-10 之间（CLI 硬性限制），默认 10。超过 10 会直接报错 INVALID_ARGUMENT。
  2. 增量分页：每次获取一页。不得自动遍历所有页面。
  3. 停止条件：如果某页返回的记录数少于 --page-size，则该页为最后一页。
  4. 用户引导：如果用户要求"显示我的所有工单"，应显示第一页并询问是否继续查看，而不是获取全部工单。

FAQ / 故障排查

| 问题 | 解答 | |------|------| | 忘记工单 ID？ | 运行 qianwen support list --page-size 5 --format json 查看最近创建的工单 | | CLI 报 401 但 auth status 显示已认证？ | Token 可能已静默过期，运行 qianwen auth login 重新认证 | | qianwen support create 成功但未返回工单 ID？ | 检查网络；运行 qianwen support list --page-size 5 查找最近创建的工单 | | 需要上传截图/附件？ | CLI 不支持上传，请通过 Web 门户操作：https://platform.qianwenai.com/home/support/detail?id=<ticket-id> | | 误关闭了工单？ | 已完成的工单无法重新打开，请新建工单并在描述中引用旧工单 ID | | qianwen auth login --complete 一直不返回？ | 等待 30 秒后中断，改用 Web 门户提交：https://platform.qianwenai.com/home/support | | 如何检查 CLI 版本？ | qianwen version — 需 >= 1.2.0。升级：qianwen update | | 关闭工单后如何跳过评价？ | 在提示评价时回复 "skip" |

参考资料

| 来源 | 用途 | |--------|---------| | references/auth-flow.md | 完整身份验证流程 | | references/ticket-categories.md | 分类关键词映射 | | qianwen support --help | CLI 内置帮助 | | qianwen doctor --format json | 环境诊断 |

qianwen skills install @qianwen-ai/qianwenai-support