微赞直播skill

快速开始

1. 接入账号：提供微赞 API 账号和密钥（获取方式见「认证预检 → 缺密钥时的用户引导话术」）
2. 自检鉴权：运行 --check 确认链路正常
3. 首次调用：执行一次查询确认接口权限已开通

> 若自检通过但业务接口返回 code:-2，是 SaaS 后台接口权限未开通，非鉴权失败。详见「失败处理」。

⚙️ 路径与自检 — MANDATORY

脚本位于 Skill 安装目录，非当前工作目录。所有命令须用绝对路径，执行前先定位：

SKILL_DIR="${CLAUDE_SKILL_DIR:-}"
[ -f "$SKILL_DIR/scripts/vzan-token.js" ] || for d in \
  "$HOME/.myagents/skills/微赞直播skill" "$HOME/.claude/skills/微赞直播skill" \
  "$HOME/.config/claude/skills/微赞直播skill"; do
  [ -f "$d/scripts/vzan-token.js" ] && SKILL_DIR="$d" && break; done
[ -z "$SKILL_DIR" ] && { echo "未找到微赞直播 Skill 目录"; exit 1; }
node "$SKILL_DIR/scripts/vzan-token.js" --check

> 下文示例写为 node scripts/vzan-token.js，实际须替换为 node "$SKILL_DIR/scripts/vzan-token.js"。

认证预检

密钥配置 — MANDATORY（运行任何命令前先完成）

本 Skill 通过两个环境变量鉴权：VZAN_ACCOUNT（账号）、VZAN_SECRET（密钥）。

先检测密钥是否已配置（这是 AI 的内部检测手段，不要把这条命令展示给用户）：

node "$SKILL_DIR/scripts/vzan-token.js" --check

• 输出 ✅ Token 获取成功 → 密钥已配置，可继续业务操作
• 输出 ❌ 未配置 VZAN_ACCOUNT / VZAN_SECRET → 缺密钥，按下方话术引导用户

缺密钥时的用户引导话术 — MANDATORY

用户大多数是非技术人员，不知道什么是"终端""环境变量""export"。 缺密钥时用大白话引导，不要甩 shell 命令给用户。

正确话术（按需改写，保留三要素）：

> 需要先接入你的微赞账号才能操作直播。请提供你的微赞账号和API 密钥。
>
> 密钥在微赞后台获取：登录微赞 → 微赞云 → 开通并查看 API 密钥（Account 和 Secret）。
>
> 拿到后发给我，我帮你配置好就可以用了。

收到密钥后：
1. 不要在对话中回显完整密钥（脱敏：只保留前 4 位 + 后 4 位）
2. 不要让用户自己去终端敲 export——密钥应填入所在平台的密钥配置入口（如 MyAgents 的设置 / Skill 的环境变量配置）。若所在平台无密钥配置 UI，再按平台给具体位置，仍避免让用户敲命令行。

> 安全底线：密钥只通过环境变量进入鉴权脚本，永不在对话中明文回显、不写入日志。

⚠️ 接口权限必须在 SaaS 后台单独开通 — MANDATORY

所有 API 接口（不是个别，是全部）都需要先在微赞 SaaS 后台开通权限，鉴权通过 ≠ 接口可用。

• 任何接口报 code:-2 api未开放，不是参数错、不是鉴权失败，是该接口权限没开
• 解法：去微赞 SaaS 后台开通对应接口（可批量开通）
• 开通后立即生效，无需刷新 Token

> 例如 express_company 在未开通时返回 code:-2，SaaS 后台开通后同一请求即可正常返回。鉴权链路（Token 获取）始终正常，区别仅在接口授权。

Token 获取

TOKEN=$(node scripts/vzan-token.js)          # 正常（6h 缓存）
TOKEN=$(node scripts/vzan-token.js --refresh) # 强制刷新

零外部依赖，跨平台一致。报错时按 stderr 检查账号/密钥。

⏰ 时间格式速查表 — MANDATORY

不同模块的时间字段使用不同格式，传错将报错或返回空。调用前按下表确认。

时间戳统一用 Node（跨平台一致）：node -e "console.log(Date.now())" 毫秒 / ÷1000 秒 / new Date(Date.now()-864e5).toISOString().slice(0,10) 昨天。

> ⚠️ 大盘 endDate 最晚只能选昨天，选当天返回 code:4011（见「失败处理」）。
> ⚠️ order_list（毫秒）与 get_refound_list（秒）差一个数量级，复制时注意区分。

通用请求格式

所有接口 POST JSON，code=0 成功。统一通过 vzan-api.js 脚本调用（Node.js 内部发请求，中文参数不经过 shell，Windows/macOS/Linux 行为一致）。

node scripts/vzan-api.js {endpoint} --body '{"param": "value"}'

• endpoint 不含 /api/v2/ 前缀，如 topic/create、shop/order_list
• stdout 输出完整 JSON 响应；错误走 stderr + exit code 1
• 无需手动传 Token，脚本自动获取/复用缓存

> ⚠️ 不要用 curl 调用含中文参数的接口——Windows CMD 默认 GBK 编码会导致中文乱码。vzan-api.js 已绕开此问题。
> 仅在调试网络问题时可回退到 curl（纯英文/数字参数时安全）：
> bash > TOKEN=$(node scripts/vzan-token.js) > curl -s -X POST "https://openapi.vzan.com/api/v2/{endpoint}" \ > -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ > -d '{"param": "value"}' >

输出规范与执行规则

• 不原样 dump JSON：单条→简洁文字；列表→表格（高亮关键值+总数）；统计→先结论摘要再详细数据；错误→报 code/msg + 解决建议
• page_size ≤ 500；统计类接口串行请求防频率限制
• 时间字段按「时间格式速查表」逐接口确认，不统一假设毫秒
• 高风险操作（见下节）须复述目标并等用户确认，真金白银类带订单号+金额二次确认
• 不回显 Token 和密钥；缺密钥时按「认证预检 → 引导话术」引导用户

高风险操作 — MANDATORY

以下操作执行前必须复述目标并等用户确认后才发请求。涉及真金白银/不可逆的，必须带订单号 + 金额二次确认。

确认话术模板（真金白银类）：
> 即将对订单 #12345 退款 ¥199.00（数量 1），确认执行？回 OK 继续。

收到明确肯定（"OK"/"执行"/"对"）才发请求。模糊回答（"嗯"/"可能"）不算确认，再问一次。

示例

> 话题 ID / 订单 ID 为占位值，替换为真实 ID 后执行。所有示例中的 node scripts/vzan-token.js 须替换为绝对路径。

查询话题数据

node scripts/vzan-api.js topic/get_topic_analysis_data --body '{"id": <话题ID>}'

创建直播话题

START_TIME=$(node -e "console.log(Date.now()+2*3600*1000)")
node scripts/vzan-api.js topic/create --body "{\"title\":\"<标题>\",\"type\":0,\"isscreen\":\"1\",\"topic_type\":1,\"start_time\":\"$START_TIME\",\"introduce\":\"<简介>\"}"
# → 返回 { id, push_url, play_url, watch_url }

其余接口（订单/退款/发货/优惠券等）按「API 参考」索引到 references/ 对应模块查看参数表后拼接请求，格式同上：vzan-api.js {endpoint} --body '{json}'。

开播盯盘

串行调三个接口汇总：「当前在线 X 人，本场峰值 Y 人，状态：直播中/已结束」。
- 在线人数：node scripts/vzan-api.js topic/get_online_number --body '{"id":<话题ID>}'
- 峰值：node scripts/vzan-api.js topic/get_top_online_number --body '{"id":<话题ID>}'
- 状态：node scripts/vzan-api.js topic/get_status --body '{"id":<话题ID>}' → ⚠️ 返回值反直觉：-1未开始 / 0直播中 / 1已结束。用文字汇报，不要甩数字码。

退款（高风险）

① 调 shop/order_list 取回订单实付金额 → ② 复述「订单号+金额+数量」等确认 → ③ 调 shop/order_refund。
refund_money 原值原样回传，禁止换算。 对用户同时报接口原值和元金额供双重核对。

API 参考

> 完整参数表（字段名 / 类型 / 必填 / 枚举）见 references/ 下对应文件。 本节只列接口清单，调用前按模块读取对应参考文档确认参数。

话题管理 (topic) — references/topic.md

直播间数据 (live) — references/live.md

商品与订单管理 (shop) — references/shop.md

商品：

订单履约（电商带货核心）：

优惠券 (coupon) — references/coupon.md

失败处理

兜底：未列出的非 0 错误码，直接把 code 和 msg 原样报给用户，并按 msg 字面意思给出下一步建议；不要猜测错误原因。参数类报错对照 references/ 下对应模块的参数表检查字段名和类型。

参考资料

references/ 下的文件是各接口完整参数表的权威来源（字段名 / 类型 / 必填 / 枚举 / 返回示例）。调用具体接口前按模块读取：

• topic.md — 话题管理（创建/详情/分析/趋势/互动/在线/状态/结束）
• live.md — 直播间数据（大盘/用户详情/积分/交易趋势与汇总）
• shop.md — 商品管理 + 订单履约（查单/发货/改物流/物流轨迹/退款/核销）
• coupon.md — 优惠券发放（含高风险预检与发错兜底）