gate-exchange-coupon

解析 gate-cli（二进制路径）

按以下顺序解析 gate-cli：(1) command -v gate-cli 和 gate-cli --version 均成功；(2) 如果 ${HOME}/.local/bin/gate-cli 可执行，则使用该路径；(3) 如果 ${HOME}/.openclaw/skills/bin/gate-cli 可执行，则使用该路径。规范规则：exchange-runtime-rules.md §4（或 gate-runtime-rules.md §4）。

Gate 优惠券助手

查询并查看 Gate Exchange 上的优惠券／代金券账户。支持六种场景：列出可用优惠券、按优惠券类型搜索、查看已过期／已使用记录、查看完整优惠券详情、读取使用规则，以及追溯优惠券获取来源。

通用规则

⚠️ 停止——继续之前，必须阅读并严格遵守共享运行时规则。 在阅读完所有规则之前，切勿选择或调用任何工具。这些规则具有最高优先级。 → 阅读 ./references/gate-runtime-rules.md

• 仅使用本技能中明确列出的 gate-cli 命令。 对于这些工作流，不得运行此处未记录的命令，即使其他接口提供了这些命令也不例外。

技能依赖项

使用的 gate-cli 命令

查询操作（只读）

• gate-cli cex coupon detail
• gate-cli cex coupon list

身份验证

• **交互式文件配置：**当主机上未同时设置 GATE_API_KEY 和 GATE_API_SECRET 时，运行 gate-cli config init，通过向导完成 API 密钥、密钥、配置文件和默认值的设置（参见 gate-cli）。
• 环境变量／标志：如果已提供凭据，则无需运行 gate-cli config init——例如，主机上已设置 GATE_API_KEY 和 GATE_API_SECRET，或在支持的情况下使用 --api-key／--api-secret——绝不要要求用户在聊天中粘贴密钥。
• 需要 API Key：是
• **权限：**Coupon:Read
• **管理入口：**在聊天之外创建或轮换密钥：https://www.gate.com/myaccount/profile/api-key/manage

安装检查

• 必需：gate-cli（如果缺少，请在此技能目录中运行 sh ./setup.sh；可选设置 GATE_CLI_SETUP_MODE=release）。
• 如果按名称调用 gate-cli，请将 $HOME/.openclaw/skills/bin 添加到 PATH（或者添加 setup.sh 的安装目录）。
• 凭据：如果主机上同时设置了非空的 GATE_API_KEY 和 GATE_API_SECRET，不要要求运行 gate-cli config init——这对 gate-cli 来说是等效的有效配置。如果两者均未设置或为空，请提醒操作者运行 gate-cli config init，或在技能库中对应的技能内配置 GATE_API_KEY／GATE_API_SECRET（绝不要要求用户在聊天中粘贴密钥）。
• **健全性检查：**在 CLI 按预期运行之前，不要继续进行经过身份验证的调用（例如 gate-cli --version，或本技能中的只读 gate-cli cex ... 命令）；在执行变更操作前，确认凭据能够正确解析。

执行模式

阅读并严格遵守 references/gate-cli.md，然后执行本技能的优惠券查询工作流。

• SKILL.md 保留优惠券语义、映射规则和呈现策略。
• references/gate-cli.md 是有关列表／详情查询行为和安全降级输出的权威 gate-cli 执行规范。

领域知识

命令映射

工具	描述
gate-cli cex coupon list	获取用户优惠券列表（支持分页，并可按类型／状态筛选）
gate-cli cex coupon detail	获取单张优惠券的完整详情

优惠券类型参考

重要——类型翻译规则：显示优惠券类型时，必须严格将 coupon_type 映射为显示名称。可以根据响应语言翻译显示名称，但映射必须准确，不得互换或混淆不同类型。关键区别：position_voucher（仓位体验券）是基于仓位的体验券，中文应译为“仓位体验券”，绝不能译为“合约体验金”；contract_bonus（合约体验金）是合约体验资金，应译为“合约体验金”。它们是完全不同的产品。

coupon_type	显示名称	描述
position_voucher	仓位体验券	用于开立期货仓位的虚拟资金（与合约体验金不同）。盈利可提现；到期后收回本金。
tradfi_position_voucher	TradFi 仓位体验券	概念与仓位体验券相同，但适用于 TradFi 工具（股票、外汇等）。
contract_bonus	合约体验金	可用于合约交易的体验资金。未使用余额将在到期时收回。
contract_bonus_new	合约券	较新形式的合约体验资金，可配置杠杆和交易对限制；有效期为设定的小时数。
commission_rebate	手续费返佣券	按适用市场实际产生的交易手续费比例返佣；余额用完前可重复使用。
hold_bonus	Earn 奖励金	用于 Earn 产品（例如 Lend & Earn）的体验资金；到期后收回。
point	积分卡	可兑换奖励或用于参与活动的平台积分。
financial_rate	利率提升券	为符合条件的 Earn 产品在基础利率上增加额外年化利率，最高不超过指定金额。
robot_bonus	机器人体验金	用于交易机器人的体验资金（例如网格、合约网格）；运行固定时长后收回。
loss_protection_copier	跟单保护	补偿部分跟单亏损，但设有最高赔付金额和符合条件的交易者限制。
vip_card	VIP 体验卡	激活后，在固定天数内享受临时 VIP 等级手续费率和权益。
interest_voucher	杠杆利息折扣券	按设定比例降低逐仓借款利率，折扣金额不超过最高限额。
p2p	P2P 折扣券	抵扣一定比例的 P2P 交易手续费，但设有上限和最低交易额。
cash	现金券	可兑换为账户现金余额；满足条件后发放。
crypto_loan_interest	加密货币借贷利息折扣券	降低加密货币抵押贷款（灵活期限）的利息，但设有最高折扣金额和最低贷款金额。
copy_trading	跟单体验金	用于跟单交易的体验资金；支持指定交易者或所有交易者，并设有止损限额和固定体验期限。
alpha_voucher	Alpha 现金券	可用于在 Gate Alpha 市场购买代币的现金抵扣额度。
etf_voucher	ETF 体验金	用于杠杆 ETF 交易的体验资金，在指定 ETF 交易对上有效，期限为设定的小时数。

状态参考

Status	含义
NOT_ACTIVE	待激活
ACTIVATED	已激活
TO_BE_USED	可用，尚未使用
EXPIRED	已过期（未使用）
USED	已使用／已消耗
RECYCLED	已被平台回收
INVALID	已失效
TASK_WAIT	任务进行中
TASK_DONE	任务已完成，奖励处理中
TASK_RECEIVE_SUCCESS	已领取任务奖励
TASK_EXPIRED	任务未完成即已过期
TASK_START	任务尚未开始（优惠券已发放，任务待激活）
TASK_NOT_STARTED_EXPIRED	任务开始前已过期
TASK_RECEIVE_FAIL	任务奖励领取失败
UNKNOWN	未知状态

gate-cli cex coupon list 参数

参数	默认值	说明
expired	0	0 = 有效优惠券；1 = 已过期／已使用的优惠券
limit	20	页面大小（1–20）
last_id	0	游标分页：上一页的最后一个 id
expire_time	0	游标分页：上一页最后一项的 expire_time_order_by；需与 last_id 一起使用
order_by	latest	latest = 按获取时间排序；expired = 按过期时间升序排序
coupon_type	（全部）	按优惠券类型筛选
is_task_coupon	（全部）	0 = 仅普通优惠券；1 = 仅任务优惠券

gate-cli cex coupon detail 参数

参数	必填	说明
coupon_type	是	优惠券类型字符串
detail_id	是	普通优惠券：列表中的 details_id；任务优惠券：列表中的 id
is_task_coupon	否	0 = 普通优惠券（默认）；1 = 任务优惠券

路由规则

识别用户意图，并路由至对应的参考文档：

意图	示例表达	路由至
列出可用优惠券	“我有哪些优惠券？”、“显示我的可用优惠券”、“我有代金券吗？”、“查询我的优惠券余额”	阅读 references/list-coupons.md
按优惠券类型搜索	“我有佣金返还代金券吗？”、“查询我是否有期货奖金”、“显示我的 VIP 体验卡”	阅读 references/list-coupons.md
查看优惠券详情	“显示我的佣金返还优惠券详情”、“这张代金券的详情是什么？”、“我的优惠券还剩多少？”	阅读 references/coupon-detail.md
查看使用规则	“这张优惠券有哪些规则？”、“如何使用这张代金券？”、“我的期货奖金有哪些条款？”	阅读 references/coupon-detail.md
追溯优惠券来源	“我怎么获得这张优惠券的？”、“这张代金券从哪里来的？”、“我参加什么活动获得了这张优惠券？”	阅读 references/coupon-detail.md
查询已过期／已使用的优惠券	“显示我已使用的优惠券”、“列出我已过期的代金券”、“我用过哪些优惠券？”	阅读 references/list-coupons.md
意图不明确	“介绍一下我的优惠券”、“优惠券帮助”	澄清：询问用户是想列出所有优惠券，还是查询某一张优惠券

执行

1. 根据上方“路由规则”表识别用户意图。
2. 加载对应的参考文档。
3. 按照该文档中的步骤逐一执行工作流。
4. 所有操作均为只读操作，无需确认。

错误处理

情况	操作
未找到优惠券	优惠券记录不存在或不属于当前用户。请用户重新确认指的是哪张优惠券；重新获取列表以取得有效 ID。
优惠券类型无效	coupon_type 不是已识别的枚举值。将用户的自然语言映射到优惠券类型参考表，然后重试。
未返回优惠券	告知用户没有符合查询条件的优惠券。建议通过任务、活动或推荐赚取优惠券。
用户提及的优惠券类型无法识别	用户提及的名称含糊或不正式。请列出优惠券类型参考表中最接近的类型名称以进行澄清。

安全规则

• 此技能中的所有操作均为只读（仅查询，不写入）。
• 切勿在对话中索取或泄露用户的 API 密钥。
• 不要推断或猜测优惠券 ID——务必先从列表 API 获取。