qwencloud-payment

QwenCloud 付款

管理 QwenCloud 账户的付款方式状态、银行卡绑定和消费限额。

前提条件

• 必须安装 QwenCloud CLI >= 1.3.0。使用以下命令验证：

qwencloud version

如果尚未安装，请运行：

npm install -g @qwencloud/qwencloud-cli

需要 Node.js >= 18。

• 所有账单命令都需要身份验证。请参阅下方的身份验证流程。

身份验证流程（适用于 Agent）

CLI 会自动检测非 TTY 环境，并安全降级。

简要说明 — 3 步身份验证流程

1. qwencloud auth status --format json → authenticated: true → 跳转到命令
2. qwencloud auth login --init-only --format json → 提取 verification_url → 在浏览器中打开
3. qwencloud auth login --complete --format json → 轮询，直到出现 success 事件

如果第 1 步返回 authenticated: true，请直接执行付款命令。

有关两阶段登录流程（init-only → complete）的完整详情，请参阅 qwencloud-usage 技能或 qwencloud-ops-auth 技能文档。

付款状态命令

付款方式状态

qwencloud billing payment-method list --format json

响应字段：

• items[] — 付款方式列表
• items[].status — 只有状态为 VALID 的项目才视为有效

显示有效付款方式的数量及其类型。

消费限额

查询或显示当前消费限额配置。

qwencloud billing limit --format json

返回已配置的消费限额及当前使用量。如果状态为 INACTIVE，请告知用户当前未配置消费限额。

数字格式： 显示较大数值时使用 K = 1000、M = 1000000（例如，$5K、$1.2M）。

绑定银行卡

此命令会打开官方网页控制台页面。它不会在对话中执行交易。

确认流程

执行绑定银行卡命令前，Agent 必须：

1. 说明影响 — 解释此操作的作用（打开银行卡绑定网页）
2. 等待用户明确确认 — 未获确认时返回 confirmation_required 状态
3. 仅在获得确认后执行

状态

状态	含义
confirmation_required	操作等待用户确认 — 不要执行
confirmed	用户已明确同意 — 执行命令

步骤

1. 用户请求绑定银行卡
2. Agent 提示：“这将会在您的浏览器中打开官方银行卡绑定页面。是否继续？”
3. 如果用户确认 → 执行命令
4. 如果用户拒绝或未响应 → 返回 confirmation_required，不采取任何操作

执行

qwencloud billing payment-method bind --format json

在用户的浏览器中打开官方银行卡绑定页面。不会通过 CLI 提交银行卡数据。

输出和 Agent 展示规则

CLI 命令在 Agent／管道环境中默认返回 JSON。 始终传入 --format json，解析结构化响应，然后提供易于理解的摘要。

如何展示输出

1. 解析 JSON，提取与用户问题相关的数据
2. 提供易于理解的摘要 — 不要直接输出原始 JSON
3. 在摘要之后添加分析 — 使用 --- 清晰分隔

错误处理

• 身份验证失败：返回 CLI 原始错误消息。不要循环重试登录。
• 登录成功后：仅重试失败的命令一次。
• 网络错误：报告错误，并建议用户检查网络连接。
• 未知错误：返回原始 CLI 标准错误输出以供调试。

结果状态

状态	条件
success	命令已执行并返回完整数据
partial	命令已执行（退出码为 0），但部分预期字段缺失或为 null —— 例如，payment-method list 返回了条目，但某个字段为 null；或者 billing limit 返回 INACTIVE，但部分字段缺失。展示可用数据，并提醒用户在 Web 控制台中核实详细信息
empty	命令已执行，但没有数据（例如，未绑定付款方式）
confirmation_required	绑定银行卡操作正在等待用户确认
error	命令执行失败 —— 包含错误详情

严禁

• ❌ 未经用户明确确认，不得执行 bind
• ❌ 不得在对话中实际提交银行卡信息或进行交易
• ❌ 未有明确标准时，不得判定付款方式“额度不足”
• ❌ 不得处理支持工单（不在处理范围内）
• ❌ 不得查询账单历史或用量（请改用 qwencloud-usage）
• ❌ 不得查询订阅状态（请改用 qwencloud-usage）
• ❌ 认证失败后不得循环重试登录