qmai-cli-public 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 企迈开放平台命令行工具，面向商品、门店组织、会员、营销、订单、财务、聚合配送、进销存和排队等业务场景，提供统一的命令行调用入口，并支持通过 npm 全局安装。
 
-为什么选 qmai-cli？ · 工具能力项 · 安装与快速开始 · 常用命令 · 认证与配置 · 安全与声明
+为什么选 qmai-cli？ · 工具能力项 · 安装与快速开始 · Agent Skills · 常用命令 · 认证与配置 · 安全与声明
 
 ## 为什么选 qmai-cli？
 
@@ -80,6 +80,23 @@
 - 环境诊断
 - shell 自动补全
 
+### Agent Skills（AI 助手）
+
+本仓库在 `skills/` 下提供与业务域对应的 Agent Skills（如 `qmai-product`、`qmai-order` 等），便于在 Cursor、Codex 等支持 Agent Skills 的环境中复用 `qmai` 子命令与参数说明。安装 CLI 后，可用 [Skills CLI](https://github.com/vercel-labs/skills) 从本仓库拉取技能包：
+
+```bash
+# 安装本仓库中的全部技能（需 Node.js 18+）
+npx skills add feixiao629/qmai-cli-public
+
+# 仅安装某一技能
+npx skills add feixiao629/qmai-cli-public --skill qmai-product
+
+# 使用完整 Git URL 亦可
+npx skills add https://github.com/feixiao629/qmai-cli-public
+```
+
+全局安装到当前用户目录时可按需加 CLI 支持的参数（例如部分环境为 `-g`）。技能安装位置取决于所用工具（常见为项目或用户下的 `.cursor/skills/`、`.agents/skills/` 等），请以 Skills CLI 与编辑器文档为准。
+
 ## 安装与快速开始
 
 ### 环境要求

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qmai-cli-public",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "qmai-cli npm installer package",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,7 @@
     "README.md",
     "LICENSE",
     "npm",
+    "skills",
     ".goreleaser.yml"
   ],
   "scripts": {

package/skills/qmai-delivery/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: qmai-delivery
+version: 1.0.0
+description: "聚合配送：创建、取消、查询配送订单与同步配送状态"
+metadata:
+  bins: [qmai]
+  help: "qmai delivery --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **order**: 创建配送单、取消配送单、查详情、查骑手位置、取消全部配送单
+- **status**: 同步商家自配送状态
+- **create-and-update**: 聚合接口，一次提交配送单创建和状态更新
+
+## 命令概览
+
+### 配送订单
+```bash
+qmai delivery order create --from-json delivery-create.json --dry-run
+qmai delivery order cancel --multi-mark S001 --order-source 1 --origin-order-no O20260407001 --dry-run
+qmai delivery order detail --order-source 1 --origin-order-no O20260407001
+qmai delivery order rider-location --order-source 1 --origin-order-no O20260407001
+qmai delivery order cancel-all --order-source 1 --origin-order-no O20260407001 --dry-run
+qmai delivery order create-and-update --from-json delivery-update.json --dry-run
+```
+
+### 状态同步
+```bash
+qmai delivery status update --origin-order-no O20260407001 --order-status 5 --dry-run
+```
+
+## 开放平台 API 端点
+
+| 操作 | 端点 |
+| --- | --- |
+| 创建配送订单 | POST /v3/delivery/createDeliveryOrder |
+| 取消配送订单 | POST /v3/delivery/cancelDeliveryOrder |
+| 查询配送单详情 | POST /v3/delivery/getDeliveryOrderInfo |
+| 查询骑手当前位置 | POST /v3/delivery/getRiderLocation |
+| 更新订单配送状态 | POST /v3/delivery/updateSelfOrderStatus |
+| 取消全部配送单 | POST /v3/delivery/cancelAllDeliveryOrder |
+| 创建配送单并更新配送状态 | POST /v3/delivery/updateDeliveryStatus |
+
+## 注意事项（Agent 必读）
+
+- `create` 和 `create-and-update` 请求体很大，统一用 `--from-json`
+- `cancel`、`cancel-all`、`status update` 都支持 `--dry-run`
+- `create-and-update` 官方文档明确说明不能和 `create + updateSelfOrderStatus` 混用
+- `order-source` 和 `order-status` 都是平台枚举值，传值前要先按企迈文档核实

package/skills/qmai-delivery/references/qmai-delivery-order.md

@@ -0,0 +1,23 @@
+# qmai-delivery 配送订单参考
+
+## 适用场景
+
+- 新建聚合配送单
+- 查询配送详情和骑手位置
+- 取消单笔或全部配送单
+
+## 推荐命令
+
+```bash
+qmai delivery order create --from-json delivery-create.json --dry-run
+qmai delivery order detail --order-source 1 --origin-order-no O20260407001
+qmai delivery order rider-location --order-source 1 --origin-order-no O20260407001
+qmai delivery order cancel --multi-mark S001 --order-source 1 --origin-order-no O20260407001 --dry-run
+qmai delivery order cancel-all --order-source 1 --origin-order-no O20260407001 --dry-run
+```
+
+## 排查建议
+
+- 创建配送单前先保留原始 JSON，请求失败时便于比对字段缺失
+- `detail` 和 `rider-location` 都依赖 `order-source + origin-order-no`
+- 如果同一笔单存在主单/补发单/拆单，补 `--order-flag`

package/skills/qmai-delivery/references/qmai-delivery-status.md

@@ -0,0 +1,19 @@
+# qmai-delivery 状态同步参考
+
+## 适用场景
+
+- 商家自配送状态回传
+- 三方配送聚合接口简化对接
+
+## 推荐命令
+
+```bash
+qmai delivery status update --origin-order-no O20260407001 --order-status 5 --dry-run
+qmai delivery order create-and-update --from-json delivery-update.json --dry-run
+```
+
+## 排查建议
+
+- `status update` 适用于商家自配送状态同步
+- `create-and-update` 是独立聚合接口，不应与普通创建接口混合使用
+- 当状态为取消或异常重发时，先确认企迈要求的状态推进顺序

package/skills/qmai-finance/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: qmai-finance
+version: 1.0.0
+description: "财务服务：分账明细、支付账单、营业统计、商品销售汇总"
+metadata:
+  bins: [qmai]
+  help: "qmai finance --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **statement**: 分账明细、微信账单、支付宝账单、微信账单下载地址
+- **stats**: 营业统计、订单渠道、结账方式、商品销售汇总
+
+## 命令概览
+
+### 对账与账单
+```bash
+qmai finance statement split-flows --created-at-start "2026-04-01 00:00:00" --created-at-end "2026-04-07 23:59:59" --page 1 --page-size 20
+qmai finance statement wechat-bills --bill-date 2026-04-07 --page 1 --page-size 20
+qmai finance statement alipay-bills --bill-date 2026-04-07 --page 1 --page-size 20
+qmai finance statement wechat-bill-url --bill-date 2026-04-07 --shop-code S001
+```
+
+### 统计与字典
+```bash
+qmai finance stats business-summary --shop-code S001 --start-date 2026-04-01 --end-date 2026-04-07
+qmai finance stats order-types
+qmai finance stats settle-scenes
+qmai finance stats item-turnover --shop-code S001 --start-date 2026-04-01 --page 1 --page-size 20
+```
+
+## 开放平台 API 端点
+
+| 操作 | 端点 |
+| --- | --- |
+| 查询分账明细 | POST /v3/payCenter/split/orderFlow |
+| 查询微信支付账单 | POST /v3/payCenter/custom/wechatBill |
+| 查询支付宝支付账单 | POST /v3/payCenter/offlinePayments/pullAlipayBillData |
+| 查询营业统计数据 | POST /v3/dataone/finance/summary/businessRecord |
+| 查询订单渠道 | POST /v3/dataone/finance/detail/orderType |
+| 查询订单结账方式 | POST /v3/dataone/finance/detail/settleScene |
+| 查询微信支付账单URL | POST /v3/pay/getWechatMerchantBillUrl |
+| 查询门店商品销售汇总 | POST /v3/dataone/item/store/turnover |
+
+## 注意事项（Agent 必读）
+
+- `alipay-bills` 的官方文档没有给出明确业务字段明细，CLI 先保留原始记录列；需要完整结构时优先用 `--format json`
+- `split-flows`、`wechat-bills`、`business-summary`、`item-turnover` 当前都是显式分页，不会自动拉全量
+- `item-turnover` 的 `page-size` 官方最大支持 200
+- `7.2 交易支付` 和 `7.3 门店账户` 在官方文档仍标记待上线，当前只保留在覆盖矩阵，不进入正式命令面

package/skills/qmai-finance/references/qmai-finance-statement.md

@@ -0,0 +1,22 @@
+# qmai-finance 对账参考
+
+## 适用场景
+
+- 查询分账明细
+- 查询微信或支付宝支付账单
+- 获取微信账单下载地址
+
+## 推荐命令
+
+```bash
+qmai finance statement split-flows --created-at-start "2026-04-01 00:00:00" --created-at-end "2026-04-07 23:59:59" --page 1 --page-size 20
+qmai finance statement wechat-bills --bill-date 2026-04-07 --page 1 --page-size 20
+qmai finance statement alipay-bills --bill-date 2026-04-07 --page 1 --page-size 20
+qmai finance statement wechat-bill-url --bill-date 2026-04-07 --shop-code S001
+```
+
+## 排查建议
+
+- 对账时间格式要严格按接口要求填写，`split-flows` 用完整时间，账单接口用日期
+- 微信账单查询支持多门店编码列表；需要跨店汇总时优先用 `--shop-codes`
+- 支付宝账单字段文档不完整，默认表格只回显原始记录

package/skills/qmai-finance/references/qmai-finance-stats.md

@@ -0,0 +1,22 @@
+# qmai-finance 统计参考
+
+## 适用场景
+
+- 查询单店营业统计
+- 查询订单渠道和结账方式字典
+- 查询门店商品销售汇总
+
+## 推荐命令
+
+```bash
+qmai finance stats business-summary --shop-code S001 --start-date 2026-04-01 --end-date 2026-04-07
+qmai finance stats order-types
+qmai finance stats settle-scenes
+qmai finance stats item-turnover --shop-code S001 --start-date 2026-04-01 --page 1 --page-size 20
+```
+
+## 排查建议
+
+- `business-summary` 必须带 `shop-code` 和日期范围
+- `item-turnover` 需要 `shop-code` 或 `shop-id` 二选一
+- 若要保留完整财务字段，优先用 `--format json`

package/skills/qmai-inventory/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: qmai-inventory
+version: 1.0.0
+description: "进销存：订货、调拨、退货、入出库与库存查询"
+metadata:
+  bins: [qmai]
+  help: "qmai inventory --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **sales**: 报货单、订货单、调拨单、退货单
+- **stock**: 入库单、出库单、门店库存台账、实时库存
+- **master**: 盘点调整、物品、分类、单位、供应商、品项下发
+
+## 命令概览
+
+### 销售管理
+```bash
+qmai inventory sales declare-receive --from-json declare-receive.json --dry-run
+qmai inventory sales declare-detail --declare-no BH20260407001
+qmai inventory sales require-update --from-json require-update.json --dry-run
+qmai inventory sales require-deliver --from-json require-deliver.json --dry-run
+qmai inventory sales return-cancel --from-json return-cancel.json --dry-run
+qmai inventory sales return-examine --from-json return-examine.json --dry-run
+qmai inventory sales return-receipt --from-json return-receipt.json --dry-run
+qmai inventory sales delivery-arrive --from-json delivery-arrive.json --dry-run
+qmai inventory sales require-list --page 1 --page-size 10
+qmai inventory sales require-create --from-json require-create.json --dry-run
+qmai inventory sales require-detail-update --from-json require-detail-update.json --dry-run
+qmai inventory sales transfer-list --page 1 --page-size 10
+qmai inventory sales transfer-detail --transfer-no DB20260407001
+qmai inventory sales return-list --page 1 --page-size 10
+```
+
+### 库存管理
+```bash
+qmai inventory stock inbound-create --from-json inbound-create.json --dry-run
+qmai inventory stock inbound-list --created-start-at "2026-04-01 00:00:00" --created-end-at "2026-04-07 23:59:59"
+qmai inventory stock inbound-update --from-json inbound-update.json --dry-run
+qmai inventory stock inbound-finish --from-json inbound-finish.json --dry-run
+qmai inventory stock outbound-create --from-json outbound-create.json --dry-run
+qmai inventory stock outbound-list --created-start-at "2026-04-01 00:00:00" --created-end-at "2026-04-07 23:59:59"
+qmai inventory stock outbound-update --from-json outbound-update.json --dry-run
+qmai inventory stock occupy --from-json stock-occupy.json --dry-run
+qmai inventory stock release --from-json stock-release.json --dry-run
+qmai inventory stock store-ledger --start-date 2026-04-01 --end-date 2026-04-07 --page 1 --page-size 10
+qmai inventory stock realtime-list --warehouse-nos CK001 --page 1 --page-size 20
+```
+
+### 基础资料管理
+```bash
+qmai inventory master inventory-adjust --from-json inventory-adjust.json --dry-run
+qmai inventory master transfer-audit --from-json transfer-audit.json --dry-run
+qmai inventory master product-create --from-json product-create.json --dry-run
+qmai inventory master category-create --from-json category-create.json --dry-run
+qmai inventory master unit-create --from-json unit-create.json --dry-run
+qmai inventory master product-update --from-json product-update.json --dry-run
+qmai inventory master supplier-create --from-json supplier-create.json --dry-run
+qmai inventory master product-distribute --from-json product-distribute.json --dry-run
+qmai inventory master supplier-update --from-json supplier-update.json --dry-run
+qmai inventory master machining-card-batch-create --from-json machining-card-batch-create.json --dry-run
+```
+
+## 注意事项（Agent 必读）
+
+- `declare-receive`、`require-update`、`require-deliver`、`return-cancel`、`return-examine`、`return-receipt`、`delivery-arrive`、`require-create` 以及库存/基础资料写接口都统一使用 `--from-json`
+- 订货、调拨、退货、库存日志目前仍是显式分页，不会自动拉全量
+- 半成品成本卡批量创建已经进入正式命令面，更新/套件/转化卡等待上线接口仍未暴露
+- 文档中部分历史 ID 已失效或漂移，新增接口前应先重新核实文档地址和更新时间

package/skills/qmai-inventory/references/qmai-inventory-master.md

@@ -0,0 +1,29 @@
+# qmai-inventory 基础资料参考
+
+## 适用场景
+
+- 创建盘点调整单
+- 审核调拨申请单
+- 新增或修改物品、分类、单位
+- 新增或修改供应商
+- 批量下发品项
+
+## 推荐命令
+
+```bash
+qmai inventory master inventory-adjust --from-json inventory-adjust.json --dry-run
+qmai inventory master transfer-audit --from-json transfer-audit.json --dry-run
+qmai inventory master product-create --from-json product-create.json --dry-run
+qmai inventory master category-create --from-json category-create.json --dry-run
+qmai inventory master unit-create --from-json unit-create.json --dry-run
+qmai inventory master supplier-create --from-json supplier-create.json --dry-run
+qmai inventory master product-distribute --from-json product-distribute.json --dry-run
+qmai inventory master machining-card-batch-create --from-json machining-card-batch-create.json --dry-run
+```
+
+## 排查建议
+
+- 物品和供应商接口字段很多，优先维护可复用 JSON 模板
+- `unit-create` 返回的是 `unitCode`，不是业务 id
+- `changeProduct` 与 `update` 字段结构相近，但新增与修改的必填项不同
+- 半成品成本卡的 `list` 为批量结构，单次最多内容较多时优先先跑 `--dry-run`

package/skills/qmai-inventory/references/qmai-inventory-sales.md

@@ -0,0 +1,25 @@
+# qmai-inventory 销售管理参考
+
+## 适用场景
+
+- 报货单接单或拒单
+- 查询订货单、调拨单、退货单
+- 创建、完成、发货订货单
+
+## 推荐命令
+
+```bash
+qmai inventory sales declare-detail --declare-no BH20260407001
+qmai inventory sales require-list --page 1 --page-size 10
+qmai inventory sales transfer-list --page 1 --page-size 10
+qmai inventory sales return-list --page 1 --page-size 10
+qmai inventory sales return-examine --from-json return-examine.json --dry-run
+qmai inventory sales return-receipt --from-json return-receipt.json --dry-run
+qmai inventory sales require-create --from-json require-create.json --dry-run
+```
+
+## 排查建议
+
+- 高副作用动作优先保留 JSON 请求体，便于审计和重试
+- `require-list`、`return-list`、`transfer-list` 默认只查单页
+- 调拨详情需使用 `transfer-no`，不是内部 id

package/skills/qmai-inventory/references/qmai-inventory-stock.md

@@ -0,0 +1,29 @@
+# qmai-inventory 库存管理参考
+
+## 适用场景
+
+- 批量查询入库单和出库单
+- 查询门店库存台账
+- 查询仓库实时库存
+
+## 推荐命令
+
+```bash
+qmai inventory stock inbound-create --from-json inbound-create.json --dry-run
+qmai inventory stock inbound-list --created-start-at "2026-04-01 00:00:00" --created-end-at "2026-04-07 23:59:59"
+qmai inventory stock inbound-update --from-json inbound-update.json --dry-run
+qmai inventory stock inbound-finish --from-json inbound-finish.json --dry-run
+qmai inventory stock outbound-create --from-json outbound-create.json --dry-run
+qmai inventory stock outbound-list --created-start-at "2026-04-01 00:00:00" --created-end-at "2026-04-07 23:59:59"
+qmai inventory stock outbound-update --from-json outbound-update.json --dry-run
+qmai inventory stock occupy --from-json stock-occupy.json --dry-run
+qmai inventory stock release --from-json stock-release.json --dry-run
+qmai inventory stock store-ledger --start-date 2026-04-01 --end-date 2026-04-07 --page 1 --page-size 10
+qmai inventory stock realtime-list --warehouse-nos CK001 --page 1 --page-size 20
+```
+
+## 排查建议
+
+- 入库单和出库单查询都要求创建时间范围
+- `realtime-list` 的 `page-size` 受官方接口限制，最大 100
+- 如果库存类数据需要完整字段，优先加 `--format json`

package/skills/qmai-marketing/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: qmai-marketing
+version: 1.1.0
+description: "营销服务：券查询与发券、活动查询与撤销、礼品卡查询与写入、结算页算价"
+metadata:
+  bins: [qmai]
+  help: "qmai marketing --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **coupon**: 券状态、券详情、券模板、不记名券、筛券、发券和模板启用
+- **campaign**: 发券活动、撤销发券、兑换码下发/作废、兑换码状态、任务活动参与记录和任务领取
+- **gift-card**: 卡信息、消费明细、卡模板、会员卡列表，以及单卡/批量余额扣减、冲正和发放
+- **pricing**: 门店促销活动查询与结算页算价
+
+## 命令概览
+
+### 券管理
+```bash
+qmai marketing coupon status --id CPN001
+qmai marketing coupon detail --user-coupon-code CPN001
+qmai marketing coupon template --id 1001
+qmai marketing coupon template-enable --id 1001 --dry-run
+qmai marketing coupon template-batch --ids 1001,1002
+qmai marketing coupon anonymous --code ANON001
+qmai marketing coupon template-by-third-code --seller-type 2 --third-biz-code EXT001
+qmai marketing coupon choose --from-json choose-coupon.json
+qmai marketing coupon grant-activity --from-json grant-activity.json --dry-run
+qmai marketing coupon grant-activity-async --from-json grant-activity-async.json --dry-run
+qmai marketing coupon grant-template --from-json grant-template.json --dry-run
+```
+
+### 活动管理
+```bash
+qmai marketing campaign list --channel-id 1 --page 1 --page-size 20
+qmai marketing campaign revoke-grant --from-json revoke-grant.json --dry-run
+qmai marketing campaign exchange-dispatch --from-json exchange-dispatch.json --dry-run
+qmai marketing campaign exchange-disable --from-json exchange-disable.json --dry-run
+qmai marketing campaign exchange-status --code EXCHANGE001
+qmai marketing campaign task-records --activity-ids 1001,1002 --customer-id 2001
+qmai marketing campaign task-claim --from-json task-claim.json --dry-run
+qmai marketing campaign recycle-coupons --from-json recycle-coupons.json --dry-run
+```
+
+### 卡管理
+```bash
+qmai marketing gift-card info --card-no CARD001 --take-card-template 1
+qmai marketing gift-card flow --card-no CARD001 --page 1 --page-size 20
+qmai marketing gift-card template --id 3001
+qmai marketing gift-card template-batch --ids 3001,3002
+qmai marketing gift-card list --customer-id 2001 --shop-code S001
+qmai marketing gift-card consume --from-json gift-card-consume.json --dry-run
+qmai marketing gift-card consume-batch --from-json gift-card-consume-batch.json --dry-run
+qmai marketing gift-card reverse --from-json gift-card-reverse.json --dry-run
+qmai marketing gift-card reverse-batch --from-json gift-card-reverse-batch.json --dry-run
+qmai marketing gift-card part-reverse --from-json gift-card-part-reverse.json --dry-run
+qmai marketing gift-card issue --from-json gift-card-issue.json --dry-run
+qmai marketing gift-card report-loss --from-json gift-card-report-loss.json --dry-run
+qmai marketing gift-card relieve-loss --from-json gift-card-relieve-loss.json --dry-run
+qmai marketing gift-card recycle --from-json gift-card-recycle.json --dry-run
+qmai marketing gift-card exchange --from-json gift-card-exchange.json --dry-run
+qmai marketing gift-card grant-template --from-json gift-card-grant-template.json --dry-run
+```
+
+### 营销计算
+```bash
+qmai marketing pricing activities --from-json promotion-activities.json
+qmai marketing pricing confirm --from-json confirm.json
+```
+
+## 注意事项（Agent 必读）
+
+- `coupon choose`、发券命令和 `pricing activities/confirm` 入参复杂，统一用 `--from-json`
+- `pricing confirm` 目前默认表格只展示价格摘要，若要看完整算价结果请加 `--format json`
+- 活动实时发券、异步发券、模板发券、模板启用、撤销发券、兑换码下发/作废、任务领取、回收券，以及礼品卡扣减/冲正/挂失/回收/兑换/发放已经进入正式命令面
+- 礼品卡写接口同样统一用 `--from-json`，建议先 `--dry-run`；其中 `part-reverse` 只能冲正统一消费接口，不能和全额冲正混用
+- `campaign list`、`gift-card flow` 是显式分页，不会自动拉全量

package/skills/qmai-marketing/references/qmai-marketing-card-pricing.md

@@ -0,0 +1,29 @@
+# qmai-marketing card/pricing 参考
+
+```bash
+qmai marketing campaign list --channel-id 1
+qmai marketing campaign task-records --activity-ids 1001,1002 --customer-id 2001
+qmai marketing gift-card info --card-no CARD001
+qmai marketing gift-card flow --card-no CARD001 --page 1 --page-size 20
+qmai marketing gift-card list --customer-id 2001 --shop-code S001
+qmai marketing gift-card consume --from-json gift-card-consume.json --dry-run
+qmai marketing gift-card consume-batch --from-json gift-card-consume-batch.json --dry-run
+qmai marketing gift-card reverse --from-json gift-card-reverse.json --dry-run
+qmai marketing gift-card reverse-batch --from-json gift-card-reverse-batch.json --dry-run
+qmai marketing gift-card part-reverse --from-json gift-card-part-reverse.json --dry-run
+qmai marketing gift-card issue --from-json gift-card-issue.json --dry-run
+qmai marketing gift-card report-loss --from-json gift-card-report-loss.json --dry-run
+qmai marketing gift-card relieve-loss --from-json gift-card-relieve-loss.json --dry-run
+qmai marketing gift-card recycle --from-json gift-card-recycle.json --dry-run
+qmai marketing gift-card exchange --from-json gift-card-exchange.json --dry-run
+qmai marketing gift-card grant-template --from-json gift-card-grant-template.json --dry-run
+qmai marketing pricing activities --from-json promotion-activities.json
+qmai marketing pricing confirm --from-json confirm.json --format json
+```
+
+## 说明
+
+- `pricing` 相关接口字段很多，建议先保留一份请求 JSON 模板
+- `pricing confirm` 用表格模式看摘要，用 `json` 看完整算价细节
+- 礼品卡冲正分为全额冲正和部分冲正两种，部分冲正要额外提供 `subBizId`
+- 礼品卡挂失/取消挂失一次最多处理数量以开放平台文档为准，CLI 不放宽上限

package/skills/qmai-marketing/references/qmai-marketing-coupon.md

@@ -0,0 +1,27 @@
+# qmai-marketing coupon 参考
+
+```bash
+qmai marketing coupon status --id CPN001
+qmai marketing coupon detail --user-coupon-code CPN001
+qmai marketing coupon template --id 1001
+qmai marketing coupon template-enable --id 1001 --dry-run
+qmai marketing coupon template-batch --ids 1001,1002
+qmai marketing coupon anonymous --code ANON001
+qmai marketing coupon template-by-third-code --seller-type 2 --third-biz-code EXT001
+qmai marketing coupon choose --from-json choose-coupon.json
+qmai marketing coupon grant-activity --from-json grant-activity.json --dry-run
+qmai marketing coupon grant-activity-async --from-json grant-activity-async.json --dry-run
+qmai marketing coupon grant-template --from-json grant-template.json --dry-run
+qmai marketing campaign revoke-grant --from-json revoke-grant.json --dry-run
+qmai marketing campaign exchange-dispatch --from-json exchange-dispatch.json --dry-run
+qmai marketing campaign exchange-disable --from-json exchange-disable.json --dry-run
+qmai marketing campaign task-claim --from-json task-claim.json --dry-run
+qmai marketing campaign recycle-coupons --from-json recycle-coupons.json --dry-run
+```
+
+## 说明
+
+- `choose-coupon.json` 直接按企迈文档请求结构组织
+- 若只是查券模板，优先用 `template` / `template-batch`
+- 发券与撤销发券都建议先 `--dry-run`，确认 `activityId`、`channelId`、`orderNo` 和会员标识结构
+- 兑换码下发与作废一次最多处理的数量要按企迈文档约束，CLI 不额外放宽