Skill: terryso/polyv-live-cli (version 1.0.5)

--- name: polyv-live-cli description: 管理保利威直播服务，包括频道管理、推流操作、商品管理、优惠券、回放、文档和统计数据。当用户需要管理直播频道、配置推流设置、管理商品、处理优惠券、查看直播数据或管理回放录像时使用。 allowed-tools: Bash(npx polyv-live-cli@latest:*) --- # 保利威直播 CLI ## 执行前验证 在执行任何 CLI 命令之前，必须先验证账号认证状态。 ### 1. 检测认证状态 ```bash npx polyv-live-cli@latest account list ``` ### 2. 配置认证（如需要） 如果用户未配置认证，引导用户提供 AppID 和 AppSecret： ``` 请提供你的保利威 AppID 和 AppSecret： - 访问 https://www.polyv.net/ 后台获取 - 路径：云直播 -> 设置 -> 开发者信息 ``` 然后用用户提供的凭据配置： ```bash npx polyv-live-cli@latest account add <名称> --app-id <appId> --app-secret <appSecret> npx polyv-live-cli@latest account set-default <名称> ``` ### 3. 验证配置成功 ```bash npx polyv-live-cli@latest channel list ``` ## 快速开始 ```bash # 添加账号凭证 npx polyv-live-cli@latest account add myaccount --app-id <id> --app-secret <secret> # 切换账号 npx polyv-live-cli@latest use myaccount # 创建频道 npx polyv-live-cli@latest channel create -n "我的直播" # 获取推流密钥（用于OBS） npx polyv-live-cli@latest stream get-key -c <channelId> # 开始直播 npx polyv-live-cli@latest stream start -c <channelId> # 监控直播状态 npx polyv-live-cli@latest stream status -c <channelId> -w ``` ## 身份认证 ```bash # 账号管理 npx polyv-live-cli@latest account add <名称> --app-id <id> --app-secret <secret> npx polyv-live-cli@latest account list npx polyv-live-cli@latest account set-default <名称> npx polyv-live-cli@latest account remove <名称> # 切换当前会话账号 npx polyv-live-cli@latest use <名称> # 或使用内联凭证 npx polyv-live-cli@latest channel list --appId <id> --appSecret <secret> npx polyv-live-cli@latest channel list -a <账号名称> ``` ## 频道命令 ```bash # 增删改查操作 npx polyv-live-cli@latest channel create -n <名称> [-d <描述>] [--scene <场景类型>] npx polyv-live-cli@latest channel list [-P <页码>] [-l <数量>] [--keyword <关键词>] npx polyv-live-cli@latest channel get -c <频道ID> npx polyv-live-cli@latest channel update -c <频道ID> [-n <名称>] [-d <描述>] npx polyv-live-cli@latest channel delete -c <频道ID> [-f] npx polyv-live-cli@latest channel batch-delete --channelIds <id1> <id2> ... # 场景类型: topclass(大班课,默认) | alone(活动营销) | seminar(研讨会) | train(企业培训) | double(双师课,需开通) | guide(导播,需开通) # 模板: ppt(三分屏-横屏,默认) | portrait_ppt(三分屏-竖屏) | alone(纯视频-横屏) | portrait_alone(纯视频-竖屏) | topclass(纯视频极速-横屏) | portrait_topclass(纯视频极速-竖屏) | seminar(研讨会) ``` ## 推流命令 ```bash # 推流操作 npx polyv-live-cli@latest stream get-key -c <频道ID> # 获取RTMP地址和推流密钥 npx polyv-live-cli@latest stream start -c <频道ID> # 开始直播 npx polyv-live-cli@latest stream stop -c <频道ID> # 结束直播 npx polyv-live-cli@latest stream status -c <频道ID> [-w] # 查看状态（-w持续监控） npx polyv-live-cli@latest stream push -c <频道ID> -f <文件> # 推送视频文件 npx polyv-live-cli@latest stream verify -c <频道ID> [-d 60] # 直播质量验证 npx polyv-live-cli@latest stream monitor -c <频道ID> [-r 5] # 实时监控面板 ``` ## 商品命令 ```bash # 商品管理 npx polyv-live-cli@latest product list -c <频道ID> npx polyv-live-cli@latest product add -c <频道ID> --name <名称> --price <价格> npx polyv-live-cli@latest product get -c <频道ID> -p <商品ID> npx polyv-live-cli@latest product update -c <频道ID> -p <商品ID> [--name <名称>] npx polyv-live-cli@latest product delete -c <频道ID> -p <商品ID> ``` ## 优惠券命令 ```bash # 优惠券操作 npx polyv-live-cli@latest coupon add -c <频道ID> --name <名称> --type <类型> --discount <金额> npx polyv-live-cli@latest coupon list -c <频道ID> [--status enabled|disabled] npx polyv-live-cli@latest coupon delete -c <频道ID> --coupon-ids <id1> <id2> # 优惠券类型: discount(折扣券), reduction(满减券) ``` ## 回放命令 ```bash # 回放管理 npx polyv-live-cli@latest playback list -c <频道ID> npx polyv-live-cli@latest playback get -c <频道ID> --video-id <回放ID> npx polyv-live-cli@latest playback delete -c <频道ID> --video-id <回放ID> npx polyv-live-cli@latest playback merge -c <频道ID> --file-ids <id1,id2,id3> ``` ## 录制设置命令 ```bash # 回放设置管理 npx polyv-live-cli@latest record setting get -c <频道ID> npx polyv-live-cli@latest record setting set -c <频道ID> [--playback-enabled Y|N] [--type single|list] [--origin playback|vod|record] # 录制转存 npx polyv-live-cli@latest record convert -c <频道ID> --file-name <文件名> [--session-id <场次ID>] [--async] npx polyv-live-cli@latest record set-default -c <频道ID> --video-id <视频ID> [--list-type playback|vod] # origin 类型: playback(回放列表), vod(点播列表), record(录制文件) # type 类型: single(单个回放), list(列表回放) ``` ## 场次命令 ```bash # 场次管理 npx polyv-live-cli@latest session list [-c <频道ID>] [--page <页码>] [--page-size <数量>] npx polyv-live-cli@latest session get -c <频道ID> --session-id <场次ID> # 状态值: unStart(未开始), live(直播中), end(已结束), playback(回放中), expired(已过期) ``` ## 文档命令 ```bash # 文档管理 npx polyv-live-cli@latest document list -c <频道ID> [--status <状态>] [--page <页码>] [--page-size <数量>] npx polyv-live-cli@latest document upload -c <频道ID> --url <文件URL> [--type common|animate] [--doc-name <名称>] npx polyv-live-cli@latest document delete -c <频道ID> --file-id <文档ID> [--type old|new] [--force] npx polyv-live-cli@latest document status -c <频道ID> --file-id <文档ID> # 状态值: normal, waitUpload, failUpload, waitConvert, failConvert # 类型: common(普通转换), animate(动效转换) ``` ## 统计命令 ```bash # 查看每日观看统计 npx polyv-live-cli@latest statistics view -c <频道ID> --start-day 2024-01-01 --end-day 2024-01-31 # 查看历史并发数据 npx polyv-live-cli@latest statistics concurrency -c <频道ID> --start-date 2024-01-01 --end-date 2024-01-31 # 查看历史最高并发人数 npx polyv-live-cli@latest statistics max-concurrent -c <频道ID> --start-time 1704067200000 --end-time 1735689600000 # 查看观众统计 npx polyv-live-cli@latest statistics audience device -c <频道ID> # 设备分布 npx polyv-live-cli@latest statistics audience region -c <频道ID> # 地区分布 # 导出统计数据 npx polyv-live-cli@latest statistics export -c <频道ID> -f csv -o report.csv ``` ## 播放器命令 ```bash # 播放器配置 npx polyv-live-cli@latest player config get -c <频道ID> npx polyv-live-cli@latest player config update -c <频道ID> [--autoplay] [--logo <url>] ``` ## 场景初始化 ```bash # 预设场景 npx polyv-live-cli@latest setup --list # 列出可用场景 npx polyv-live-cli@latest setup e-commerce # 电商直播场景 npx polyv-live-cli@latest setup education # 在线教育场景 ``` ## 监控命令 ```bash # 直播监控面板 npx polyv-live-cli@latest monitor start -c <频道ID> npx polyv-live-cli@latest monitor stop ``` ## 聊天消息命令 ```bash # 发送管理员消息 npx polyv-live-cli@latest chat send -c <频道ID> -m <文本消息> npx polyv-live-cli@latest chat send -c <频道ID> -i <图片URL> npx polyv-live-cli@latest chat send -c <频道ID> -m <消息> -n <昵称> -a <角色> # 查看聊天历史 npx polyv-live-cli@latest chat list -c <频道ID> npx polyv-live-cli@latest chat list -c <频道ID> --page <页码> --size <数量> npx polyv-live-cli@latest chat list -c <频道ID> --start-day <开始日期> --end-day <结束日期> # 删除消息 npx polyv-live-cli@latest chat delete -c <频道ID> -m <消息ID> npx polyv-live-cli@latest chat delete -c <频道ID> --clear # 清空所有消息 ``` ## 禁言踢人命令 (Story 11-2) ```bash # 禁言用户（频道级别） npx polyv-live-cli@latest chat ban -c <频道ID> -u <用户ID1,用户ID2> npx polyv-live-cli@latest chat ban -c <频道ID> -u <用户ID> -o json # 全局禁言（账号级别） npx polyv-live-cli@latest chat ban -u <用户ID1,用户ID2> --global # 解除禁言 npx polyv-live-cli@latest chat unban -c <频道ID> -u <用户ID1,用户ID2> npx polyv-live-cli@latest chat unban -u <用户ID1,用户ID2> --global # 踢人（频道级别） npx polyv-live-cli@latest chat kick -c <频道ID> -v <观众ID1,观众ID2> -n <昵称1,昵称2> npx polyv-live-cli@latest chat kick -c <频道ID> -v <观众ID> -o json # 全局踢人（账号级别） npx polyv-live-cli@latest chat kick -v <观众ID1> -n <昵称1> --global # 解除踢人 npx polyv-live-cli@latest chat unkick -c <频道ID> -v <观众ID1> -n <昵称1> npx polyv-live-cli@latest chat unkick -v <观众ID1> --global # 查看禁言列表 npx polyv-live-cli@latest chat banned list -c <频道ID> --type userId # 禁言用户列表 npx polyv-live-cli@latest chat banned list -c <频道ID> --type ip # 禁言IP列表 npx polyv-live-cli@latest chat banned list -c <频道ID> --type badword # 禁言词列表 # 查看踢人列表 npx polyv-live-cli@latest chat kicked list -c <频道ID> npx polyv-live-cli@latest chat kicked list -c <频道ID> -o json ``` ## 签到管理命令 (Story 11-3) ```bash # 发起签到 npx polyv-live-cli@latest checkin start -c <频道ID> npx polyv-live-cli@latest checkin start -c <频道ID> --limit-time 30 # 设置签到时长30秒 npx polyv-live-cli@latest checkin start -c <频道ID> --delay-time 1700734800000 # 定时签到 npx polyv-live-cli@latest checkin start -c <频道ID> --message "请签到" # 自定义签到提示语 npx polyv-live-cli@latest checkin start -c <频道ID> --force # 强制签到模式 # 查询签到成功记录 npx polyv-live-cli@latest checkin list -c <频道ID> npx polyv-live-cli@latest checkin list -c <频道ID> --page 1 --size 20 # 分页查询 npx polyv-live-cli@latest checkin list -c <频道ID> --date 2024-01-15 # 按日期筛选 npx polyv-live-cli@latest checkin list -c <频道ID> --session-id <场次ID> # 按场次筛选 # 查询签到详情（包括已签到和未签到） npx polyv-live-cli@latest checkin result -c <频道ID> --checkin-id <签到ID> npx polyv-live-cli@latest checkin result -c <频道ID> --checkin-id <签到ID> -o json # 查询签到发起记录（按时间范围） npx polyv-live-cli@latest checkin sessions -c <频道ID> npx polyv-live-cli@latest checkin sessions -c <频道ID> --start-date 2024-01-01 --end-date 2024-01-31 npx polyv-live-cli@latest checkin sessions -c <频道ID> -o json ``` ## 问答管理命令 (Story 11-4) ```bash # 发送问答卡（答题卡） npx polyv-live-cli@latest qa send -c <频道ID> --question-id <问题ID> npx polyv-live-cli@latest qa send -c <频道ID> --question-id <问题ID> --duration 30 # 设置答题时长30秒 npx polyv-live-cli@latest qa send -c <频道ID> --question-id <问题ID> -o json # JSON格式输出 # 查询问答卡列表 npx polyv-live-cli@latest qa list -c <频道ID> npx polyv-live-cli@latest qa list -c <频道ID> -o json # JSON格式输出 # 停止问答卡 npx polyv-live-cli@latest qa stop -c <频道ID> --question-id <问题ID> npx polyv-live-cli@latest qa stop -c <频道ID> --question-id <问题ID> -o json # JSON格式输出（含统计数据） ``` ## 问卷管理命令 (Story 11-4) ```bash # 创建问卷 npx polyv-live-cli@latest questionnaire create -c <频道ID> --title <问卷标题> --questions '<JSON数组>' npx polyv-live-cli@latest questionnaire create -c 3151318 --title "满意度调查" --questions '[{"name":"性别","type":"R","options":["男","女"],"required":"Y"}]' # 问卷题型类型: R=单选, C=多选, Q=填空, J=判断, X=评分 # 创建带自定义ID的问卷 npx polyv-live-cli@latest questionnaire create -c <频道ID> --title <标题> --questions '<JSON>' --custom-questionnaire-id <自定义ID> # 查询问卷列表 npx polyv-live-cli@latest questionnaire list -c <频道ID> npx polyv-live-cli@latest questionnaire list -c <频道ID> --page 1 --size 20 # 分页查询 npx polyv-live-cli@latest questionnaire list -c <频道ID> --session-id <场次ID> # 按场次筛选 npx polyv-live-cli@latest questionnaire list -c <频道ID> --start-date 2024-01-01 --end-date 2024-01-31 # 日期范围 # 获取问卷详情 npx polyv-live-cli@latest questionnaire detail -c <频道ID> --questionnaire-id <问卷ID> npx polyv-live-cli@latest questionnaire detail -c <频道ID> --questionnaire-id <问卷ID> -o json # JSON格式输出 ``` ## 抽奖管理命令 (Story 11-5) ```bash # 创建抽奖活动 npx polyv-live-cli@latest lottery create -c <频道ID> --name <抽奖名称> --type <类型> --amount <中奖人数> --prize <奖品名称> npx polyv-live-cli@latest lottery create -c 3151318 --name "幸运抽奖" --type none --amount 3 --prize "神秘礼品" # 无条件抽奖 npx polyv-live-cli@latest lottery create -c 3151318 --name "邀请抽奖" --type invite --amount 5 --prize "优惠券" --invite-num 3 # 邀请抽奖 npx polyv-live-cli@latest lottery create -c 3151318 --name "时长抽奖" --type duration --amount 2 --prize "红包" --duration 10 # 观看时长抽奖 # 抽奖类型: none=无条件, invite=邀请好友, duration=观看时长, comment=发表评论, question=回答问题 # 查询抽奖活动列表 npx polyv-live-cli@latest lottery list -c <频道ID> npx polyv-live-cli@latest lottery list -c <频道ID> --page 1 --size 20 # 分页查询 npx polyv-live-cli@latest lottery list -c <频道ID> -o json # JSON格式输出 # 获取抽奖活动详情 npx polyv-live-cli@latest lottery get -c <频道ID> --id <抽奖活动ID> # 更新抽奖活动 npx polyv-live-cli@latest lottery update -c <频道ID> --id <抽奖活动ID> --name <新名称> --amount <新人数> # 删除抽奖活动 npx polyv-live-cli@latest lottery delete -c <频道ID> --id <抽奖活动ID> # 查询中奖用户 npx polyv-live-cli@latest lottery winners -c <频道ID> --lottery-id <抽奖ID> npx polyv-live-cli@latest lottery winners -c <频道ID> --lottery-id <抽奖ID> --page 1 --limit 20 # 分页查询 # 查询抽奖记录 npx polyv-live-cli@latest lottery records -c <频道ID> npx polyv-live-cli@latest lottery records -c <频道ID> --session-id <场次ID> # 按场次筛选 npx polyv-live-cli@latest lottery records -c <频道ID> --start-time <时间戳> --end-time <时间戳> # 按时间范围 ``` ## 打赏管理命令 (Story 11-6) ```bash # 获取打赏配置 npx polyv-live-cli@latest donate config get -c <频道ID> npx polyv-live-cli@latest donate config get -c 3151318 -o json # JSON格式输出 # 更新打赏配置 npx polyv-live-cli@latest donate config update -c <频道ID> --cash-enabled Y # 启用现金打赏 npx polyv-live-cli@latest donate config update -c <频道ID> --gift-enabled Y # 启用礼物打赏 npx polyv-live-cli@latest donate config update -c <频道ID> --tips "感谢支持!" # 设置打赏提示语 npx polyv-live-cli@latest donate config update -c <频道ID> --amounts "0.88,6.66,8.88,18.88" # 设置打赏金额 # 查询打赏记录 npx polyv-live-cli@latest donate list -c <频道ID> --start <开始时间戳> --end <结束时间戳> npx polyv-live-cli@latest donate list -c 3151318 --start 1615772426000 --end 1615858826000 npx polyv-live-cli@latest donate list -c 3151318 --start 1615772426000 --end 1615858826000 --page 2 --size 20 # 分页 npx polyv-live-cli@latest donate list -c 3151318 --start 1615772426000 --end 1615858826000 -o json # JSON格式 ``` ## 观众信息查询命令 (Story 12-1) ```bash # 获取单个观众详情 npx polyv-live-cli@latest viewer get -v <观众ID> npx polyv-live-cli@latest viewer get -v [REDACTED_SECRET] -o json # JSON格式输出 # 列出观众列表 npx polyv-live-cli@latest viewer list npx polyv-live-cli@latest viewer list --page 1 --size 20 # 分页查询 npx polyv-live-cli@latest viewer list --source IMPORT # 按来源过滤（IMPORT/WX/MOBILE） npx polyv-live-cli@latest viewer list --mobile "13800138000" # 按手机号过滤 npx polyv-live-cli@latest viewer list --email "[REDACTED_SECRET]" # 按邮箱过滤 npx polyv-live-cli@latest viewer list --area "北京" # 按地址过滤 npx polyv-live-cli@latest viewer list --source WX -o json # JSON格式输出 ``` ## 观众标签管理命令 (Story 12-2) ```bash # 列出所有标签 npx polyv-live-cli@latest viewer tag list # 搜索标签 npx polyv-live-cli@latest viewer tag list --keyword "VIP" # 分页查询 npx polyv-live-cli@latest viewer tag list --page 1 --size 20 # JSON格式输出 npx polyv-live-cli@latest viewer tag list -o json # 为观众添加标签（单个观众+单个标签） npx polyv-live-cli@latest viewer tag add -v "viewer1" -l 1 # 为观众添加多个标签 npx polyv-live-cli@latest viewer tag add -v "viewer1" -l 1,2,3 # 批量为多个观众添加标签 npx polyv-live-cli@latest viewer tag add -v "viewer1,viewer2,viewer3" -l 1,2 # JSON格式输出 npx polyv-live-cli@latest viewer tag add -v "viewer1" -l 1 -o json # 移除观众的标签（单个观众+单个标签） npx polyv-live-cli@latest viewer tag remove -v "viewer1" -l 1 # 移除观众的多个标签 npx polyv-live-cli@latest viewer tag remove -v "viewer1" -l 1,2,3 # 批量移除多个观众的标签 npx polyv-live-cli@latest viewer tag remove -v "viewer1,viewer2" -l 1,2 # JSON格式输出 npx polyv-live-cli@latest viewer tag remove -v "viewer1" -l 1 -o json ``` ## 观看条件配置命令 (Story 12-3) ```bash # 获取观看条件配置 npx polyv-live-cli@latest watch-condition get # 获取全局设置 npx polyv-live-cli@latest watch-condition get --channel-id <频道ID> # 获取频道设置 npx polyv-live-cli@latest watch-condition get --channel-id 3151318 -o json # JSON格式输出 # 简单设置：关闭观看条件（公开观看） npx polyv-live-cli@latest watch-condition set --channel-id <频道ID> --rank 1 --auth-type none --enabled Y # 简单设置：密码观看 npx polyv-live-cli@latest watch-condition set --channel-id <频道ID> --rank 1 --auth-type code --enabled Y --auth-code "abc123" # 简单设置：付费观看（价格单位：元） npx polyv-live-cli@latest watch-condition set --channel-id <频道ID> --rank 1 --auth-type pay --enabled Y --price 99.9 # 复杂设置：使用 JSON 配置文件（支持多个条件和完整参数） npx polyv-live-cli@latest watch-condition set --channel-id <频道ID> --config ./watch-condition.json # 设置全局观看条件（不传频道ID） npx polyv-live-cli@latest watch-condition set --rank 1 --auth-type none --enabled N # 认证类型: none=无限制, code=密码观看, pay=付费观看, phone=白名单观看, info=登记观看, custom=自定义授权, external=外部授权, direct=独立授权 # 条件级别: rank 1=主要条件, rank 2=次要条件 # 启用状态: enabled Y=启用, N=禁用 ``` JSON 配置文件格式示例 (`watch-condition.json`): ```json { "authSettings": [ { "rank": 1, "enabled": "Y", "authType": "code", "authCode": "abc123" }, { "rank": 2, "enabled": "N" } ] } ``` ## 白名单管理命令 (Story 12-4) ```bash # 列出白名单 npx polyv-live-cli@latest whitelist list --rank 1 # 获取全局白名单 npx polyv-live-cli@latest whitelist list --channel-id <频道ID> --rank 1 # 获取频道白名单 npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 --page 1 --page-size 20 # 分页 npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 --keyword "张三" # 搜索 npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 -o json # JSON格式输出 # 添加白名单 npx polyv-live-cli@latest whitelist add --rank 1 --code "13800138000" --name "张三" # 全局白名单 npx polyv-live-cli@latest whitelist add --channel-id <频道ID> --rank 1 --code "13800138000" --name "张三" # 频道白名单 npx polyv-live-cli@latest whitelist add --rank 1 --code "13800138000" -o json # JSON格式输出 # 更新白名单 npx polyv-live-cli@latest whitelist update --rank 1 --old-code "13800138000" --code "13900139000" --name "李四" # 全局 npx polyv-live-cli@latest whitelist update --channel-id <频道ID> --rank 1 --old-code "13800138000" --code "13900139000" --name "李四" # 频道 npx polyv-live-cli@latest whitelist update --rank 1 --old-code "13800138000" --code "13900139000" -o json # JSON格式输出 # 删除白名单 npx polyv-live-cli@latest whitelist remove --rank 1 --codes "13800138000" # 删除单个（全局） npx polyv-live-cli@latest whitelist remove --channel-id <频道ID> --rank 1 --codes "13800138000,13900139000" # 批量删除 npx polyv-live-cli@latest whitelist remove --channel-id <频道ID> --rank 1 --clear # 清空所有白名单 npx polyv-live-cli@latest whitelist remove --rank 1 --codes "13800138000" -o json # JSON格式输出 # 条件级别: rank 1=主要条件, rank 2=次要条件 # 不传 --channel-id 为全局设置，传 --channel-id 为频道级别设置 ``` ## 平台账号信息管理命令 (Story 13-1) ```bash # 获取账号基本信息（用户ID、邮箱、频道数等） npx polyv-live-cli@latest platform get npx polyv-live-cli@latest platform get -o json # JSON格式输出 # 获取账号开关配置（全局设置、认证、录制等开关状态） npx polyv-live-cli@latest platform switch get npx polyv-live-cli@latest platform switch get -o json # JSON格式输出 # 更新账号开关配置 npx polyv-live-cli@latest platform switch update --param authEnabled --enabled Y # 启用认证 npx polyv-live-cli@latest platform switch update --param recordEnabled --enabled N # 禁用录制 npx polyv-live-cli@latest platform switch update --param authEnabled --enabled Y -o json # JSON格式输出 # 可用开关参数: # - globalSettingEnabled: 全局设置开关 # - authEnabled: 认证开关 # - recordEnabled: 录制开关 # - playbackEnabled: 回放开关 # - danmuEnabled: 弹幕开关 ``` ## 回调设置管理命令 (Story 13-2) ```bash # 获取回调设置（回调URL和启用状态） npx polyv-live-cli@latest platform callback get npx polyv-live-cli@latest platform callback get -o json # JSON格式输出 # 更新回调设置 npx polyv-live-cli@latest platform callback update --url https://example.com/callback # 更新回调URL npx polyv-live-cli@latest platform callback update --enabled Y # 启用回调 npx polyv-live-cli@latest platform callback update --url https://example.com/callback --enabled Y # 同时更新 npx polyv-live-cli@latest platform callback update --url https://example.com/callback -o json # JSON格式输出 ``` ### 全局频道设置管理 管理账号级别的全局频道设置，包括并发人数、转码、打赏等功能开关。 ```bash # 获取全局频道设置 npx polyv-live-cli@latest platform setting get npx polyv-live-cli@latest platform setting get -o json # JSON格式输出 # 更新全局频道设置 npx polyv-live-cli@latest platform setting update --channel-concurrences-enabled Y # 启用最大并发人数 npx polyv-live-cli@latest platform setting update --timely-convert-enabled N # 禁用自动转码 npx polyv-live-cli@latest platform setting update --donate-enabled Y # 启用打赏功能 npx polyv-live-cli@latest platform setting update --cover-img-type contain # 设置封面类型 # 同时更新多个设置 npx polyv-live-cli@latest platform setting update \ --channel-concurrences-enabled Y \ --timely-convert-enabled Y \ --donate-enabled N \ -o json # JSON格式输出 ``` #### 可用参数 | 参数 | 说明 | 值 | |------|------|------| | --channel-concurrences-enabled | 最大并发观看人数开关 | Y/N | | --timely-convert-enabled | 自动转码开关 | Y/N | | --donate-enabled | 打赏功能开关 | Y/N | | --rebirth-auto-upload-enabled | 转存自动上传PPT | Y/N | | --rebirth-auto-convert-enabled | 转存自动转码 | Y/N | | --ppt-covered-enabled | PPT全屏开关 | Y/N | | --cover-img-type | 封面图片类型 | contain/cover | | --test-mode-button-enabled | 测试模式按钮 | Y/N | ## 转播管理命令 (Story 14-3) ```bash # 批量创建转播频道 npx polyv-live-cli@latest transmit create -c <频道ID> --names "频道1,频道2,频道3" npx polyv-live-cli@latest transmit create -c 3151318 --names "转播1,转播2,转播3" -o json # 获取转播关联列表 npx polyv-live-cli@latest transmit list -c <频道ID> npx polyv-live-cli@latest transmit list -c 3151318 -o json # 最多支持一次创建100个转播频道 # -o table 为默认表格格式, -o json 为JSON格式输出 ``` ## 卡片推送命令 (Story 14-2) ```bash # 列出卡片配置 npx polyv-live-cli@latest card-push list -c <频道ID> npx polyv-live-cli@latest card-push list -c 3151318 -o json # 创建卡片配置 npx polyv-live-cli@latest card-push create -c <频道ID> --image-type <类型> --title <标题> --link <链接> --duration <秒数> --show-condition PUSH|WATCH npx polyv-live-cli@latest card-push create -c 3151318 --image-type giftbox --title "限时优惠" --link "https://example.com" --duration 10 --show-condition PUSH # 定时弹出卡片（观看时长触发） npx polyv-live-cli@latest card-push create -c 3151318 --image-type redpack --title "新手红包" --link "https://example.com" --duration 15 --show-condition WATCH --condition-value 30 --condition-unit SECONDS # 更新卡片配置 npx polyv-live-cli@latest card-push update -c <频道ID> --card-push-id <卡片ID> --title <新标题> npx polyv-live-cli@latest card-push update -c 3151318 --card-push-id 123 --duration 20 # 推送卡片 npx polyv-live-cli@latest card-push push -c <频道ID> --card-push-id <卡片ID> # 取消推送 npx polyv-live-cli@latest card-push cancel -c <频道ID> --card-push-id <卡片ID> # 删除卡片配置 npx polyv-live-cli@latest card-push delete -c <频道ID> --card-push-id <卡片ID> # image-type: giftbox(礼盒), redpack(红包), custom(自定义) # show-condition: PUSH(手动推送), WATCH(观看时长触发) # card-type: common(普通), qrCode(二维码) ``` ## 输出格式 大多数命令支持 `-o table`（默认表格格式）或 `-o json`（JSON格式，便于程序化处理）。 ```bash npx polyv-live-cli@latest channel list -o json npx polyv-live-cli@latest stream status -c <频道ID> -o json ``` ## 全局选项 ```bash --appId <id> # 保利威应用ID --appSecret <secret> # 保利威应用密钥 --userId <id> # 保利威用户ID（可选） -a, --account <名称> # 使用指定账号 --verbose # 显示详细信息 --debug # 启用调试模式 --timeout <毫秒> # API超时时间（默认30000毫秒） ``` ## 常用工作流程 ### 创建并开始直播 ```bash npx polyv-live-cli@latest use myaccount npx polyv-live-cli@latest channel create -n "新品发布会" -d "新品展示直播" # 记住输出的频道ID npx polyv-live-cli@latest stream get-key -c 3151318 # 在OBS中使用RTMP地址和推流密钥 npx polyv-live-cli@latest stream start -c 3151318 npx polyv-live-cli@latest stream status -c 3151318 -w ``` ### 初始化电商直播场景 ```bash npx polyv-live-cli@latest setup e-commerce # 自动创建带商品预配置的频道 ``` ### 监控直播质量 ```bash npx polyv-live-cli@latest stream verify -c 3151318 -d 120 -i 5 npx polyv-live-cli@latest stream monitor -c 3151318 -r 3 --alerts ``` ## 详细文档 * **身份认证配置** [references/authentication.md](references/authentication.md) * **频道管理** [references/channel-management.md](references/channel-management.md) * **推流操作** [references/streaming.md](references/streaming.md) * **商品管理** [references/products.md](references/products.md) * **优惠券管理** [references/coupons.md](references/coupons.md) * **回放管理** [references/playback.md](references/playback.md) * **录制设置** [references/record-settings.md](references/record-settings.md) * **场次管理** [references/session-management.md](references/session-management.md) * **文档管理** [references/documents.md](references/documents.md) * **聊天消息管理** [references/chat-management.md](references/chat-management.md) * **签到管理** [references/checkin.md](references/checkin.md) * **问答问卷管理** [references/qa-questionnaire.md](references/qa-questionnaire.md) * **抽奖管理** [references/lottery.md](references/lottery.md) * **打赏管理** [references/donate.md](references/donate.md) * **观众信息查询** [references/viewer.md](references/viewer.md) * **观众标签管理** [references/viewer-management.md](references/viewer-management.md) * **观看条件配置** [references/watch-condition.md](references/watch-condition.md) * **白名单管理** [references/whitelist.md](references/whitelist.md) * **平台账号信息管理** [references/platform.md](references/platform.md) * **卡片推送管理** [references/card-push.md](references/card-push.md) * **转播管理** [references/transmit.md](references/transmit.md) * **播放器配置** [references/player.md](references/player.md) * **直播监控** [references/monitor.md](references/monitor.md) * **统计分析** [references/statistics.md](references/statistics.md) * **场景初始化** [references/scene-setup.md](references/scene-setup.md) ## 联系方式 - 邮箱: [REDACTED_SECRET] - 官网: https://www.polyv.net/ - 保利威直播 API 文档: https://help.polyv.net/#/live/api/ - 技术支持: 400-993-9533

path: references/authentication.md
content: # 身份认证配置

## 认证优先级

保利威直播 CLI 支持多种认证来源，按以下优先级顺序使用：

1. **命令行参数**：`--appId`、`--appSecret`、`--userId`
2. **会话账号**：`npx polyv-live-cli@latest use <账号名称>`
3. **账号标志**：`-a <名称>` 或 `--account <名称>`
4. **环境变量**：`POLYV_APP_ID`、`POLYV_APP_SECRET`、`POLYV_USER_ID`
5. **默认账号**：通过 `account set-default` 设置
6. **全局配置**：存储在 `~/.npx polyv-live-cli@latest/` 目录

## 账号管理

### 添加新账号

```bash
# 基本账号
npx polyv-live-cli@latest account add production \
  --app-id your-app-id \
  --app-secret your-app-secret

# 包含用户ID
npx polyv-live-cli@latest account add production \
  --app-id your-app-id \
  --app-secret your-app-secret \
  --user-id your-user-id
```

### 查看所有账号

```bash
npx polyv-live-cli@latest account list

# 输出示例：
# NAME         APP ID       DEFAULT
# production   abc123...    Yes
# staging      def456...    No
```

### 设置默认账号

```bash
npx polyv-live-cli@latest account set-default production
```

### 切换会话账号

```bash
# 切换当前会话使用的账号
npx polyv-live-cli@latest use staging

# 后续所有命令都会使用 staging 账号
npx polyv-live-cli@latest channel list
```

### 删除账号

```bash
npx polyv-live-cli@latest account delete old-account
```

## 使用内联凭证

### 单次命令指定凭证

```bash
# 直接使用凭证参数
npx polyv-live-cli@latest channel list --appId <id> --appSecret <secret>

# 使用账号标志简写
npx polyv-live-cli@latest channel list -a production

# 使用 --verbose 查看认证来源
npx polyv-live-cli@latest channel list --verbose
```

## 环境变量

### 在 Shell 配置文件中设置

```bash
# 添加到 ~/.bashrc、~/.zshrc 或 ~/.profile
export POLYV_APP_ID="your-app-id"
export POLYV_APP_SECRET="your-app-secret"
export POLYV_USER_ID="your-user-id"
```

### 在脚本中使用

```bash
#!/bin/bash
export POLYV_APP_ID="${APP_ID}"
export POLYV_APP_SECRET="${APP_SECRET}"

npx polyv-live-cli@latest channel list
```

## 验证认证状态

### 检查认证信息

```bash
# 使用 --verbose 输出显示认证来源
npx polyv-live-cli@latest channel list --verbose

# 输出包含：
# 🔐 认证来源: session-account
# 👤 账号: production
```

### 诊断认证问题

```bash
# 列出账号以验证配置
npx polyv-live-cli@latest account list

# 检查是否设置了默认账号
npx polyv-live-cli@latest account list | grep -i default
```

## 安全最佳实践

### 建议

- 日常使用账号管理功能
- CI/CD 流水线中使用环境变量
- 不同环境使用不同账号
- 定期轮换凭证

### 不建议

- 不要将凭证提交到版本控制
- 不要在团队成员之间共享账号
- 不要在开发环境使用生产凭证

## CI/CD 集成

### GitHub Actions

```yaml
env:
  POLYV_APP_ID: ${{ secrets.POLYV_APP_ID }}
  POLYV_APP_SECRET: ${{ secrets.POLYV_APP_SECRET }}

steps:
  - name: 列出频道
    run: npx polyv-live-cli@latest channel list
```

### GitLab CI

```yaml
variables:
  POLYV_APP_ID: ${POLYV_APP_ID}
  POLYV_APP_SECRET: ${POLYV_APP_SECRET}

script:
  - npx polyv-live-cli@latest channel list
```

## 故障排除

### "Auth configuration is incomplete"（认证配置不完整）

此错误表示未找到有效凭证：

1. 检查账号是否存在：`npx polyv-live-cli@latest account list`
2. 设置默认账号：`npx polyv-live-cli@latest account set-default <名称>`
3. 或使用内联凭证：`npx polyv-live-cli@latest channel list -a <名称>`

### "Invalid credentials"（无效凭证）

1. 验证 appId 和 appSecret 是否正确
2. 检查凭证是否已过期
3. 确保账号具有必要权限

### 如何获取保利威凭证

1. 登录 [保利威后台](https://www.polyv.net/)
2. 进入「开发设置」→「API设置」
3. 获取 AppID 和 AppSecret


path: references/channel-management.md
content: # 频道管理

## 概述

频道是保利威直播的核心资源。每个频道代表一个直播间，拥有独立的配置、商品和回放设置。

## 频道增删改查

### 创建频道

```bash
# 基本创建
npx polyv-live-cli@latest channel create -n "我的直播"

# 带描述
npx polyv-live-cli@latest channel create -n "产品演示" -d "新产品功能演示"

# 完整选项
npx polyv-live-cli@latest channel create \
  -n "高级网络研讨会" \
  -d "月度付费用户专属研讨会" \
  --scene topclass \
  --template ppt \
  --password web123 \
  --max-viewers 1000 \
  --auto-record

# JSON输出（便于程序化处理）
npx polyv-live-cli@latest channel create -n "API频道" -o json
```

### 场景类型 (newScene)

| 场景 | 说明 | 备注 |
|------|------|------|
| `topclass` | 大班课（默认） | ✅ 推荐 |
| `alone` | 活动营销 | ✅ |
| `seminar` | 研讨会 | ✅ |
| `train` | 企业培训 | ✅ |
| `double` | 双师课 | ⚠️ 需开通权限 |
| `guide` | 导播 | ⚠️ 需开通权限 |

### 模板类型 (template)

| 模板 | 说明 |
|------|------|
| `ppt` | 三分屏-横屏（默认） |
| `portrait_ppt` | 三分屏-竖屏 |
| `alone` | 纯视频-横屏 |
| `portrait_alone` | 纯视频-竖屏 |
| `topclass` | 纯视频极速-横屏 |
| `portrait_topclass` | 纯视频极速-竖屏 |
| `seminar` | 研讨会 |

### 查看频道列表

```bash
# 基本列表（第一页，20条）
npx polyv-live-cli@latest channel list

# 分页查询
npx polyv-live-cli@latest channel list -P 2 -l 10

# 按关键词筛选
npx polyv-live-cli@latest channel list --keyword "研讨会"

# 按分类筛选
npx polyv-live-cli@latest channel list --category-id "cat123"

# JSON输出
npx polyv-live-cli@latest channel list -o json
```

### 查看频道详情

```bash
# 表格格式
npx polyv-live-cli@latest channel get -c 3151318

# JSON格式
npx polyv-live-cli@latest channel get -c 3151318 -o json
```

### 更新频道

```bash
# 更新名称
npx polyv-live-cli@latest channel update -c 3151318 -n "新名称"

# 更新描述
npx polyv-live-cli@latest channel update -c 3151318 -d "更新后的描述"

# 更新密码
npx polyv-live-cli@latest channel update -c 3151318 -p "newpass123"

# 更新多个字段
npx polyv-live-cli@latest channel update \
  -c 3151318 \
  -n "重命名频道" \
  --max-viewers 5000 \
  --publisher "主持人姓名"
```

### 删除频道

```bash
# 带确认提示
npx polyv-live-cli@latest channel delete -c 3151318

# 强制删除（无确认）
npx polyv-live-cli@latest channel delete -c 3151318 -f

# JSON输出
npx polyv-live-cli@latest channel delete -c 3151318 -o json
```

### 批量删除

```bash
# 删除多个频道
npx polyv-live-cli@latest channel batch-delete --channelIds 3151318 3151319 3151320

# 强制批量删除
npx polyv-live-cli@latest channel batch-delete --channelIds 3151318 3151319 -f
```

## 频道配置

### 密码保护

```bash
# 创建时设置密码
npx polyv-live-cli@latest channel create -n "私密直播" -p "secure123"

# 更新密码
npx polyv-live-cli@latest channel update -c 3151318 -p "newpass456"

# 移除密码（设置为空）
npx polyv-live-cli@latest channel update -c 3151318 -p ""
```

### 观众人数限制

```bash
# 设置最大观看人数
npx polyv-live-cli@latest channel create -n "限定直播" --max-viewers 500

# 更新人数限制
npx polyv-live-cli@latest channel update -c 3151318 --max-viewers 1000
```

### 自动录制

```bash
# 启用自动录制
npx polyv-live-cli@latest channel create -n "录制直播" --auto-record
```

### 封面和引导图

```bash
# 更新封面图
npx polyv-live-cli@latest channel update -c 3151318 --cover-img "https://example.com/cover.jpg"

# 更新引导图
npx polyv-live-cli@latest channel update -c 3151318 --splash-img "https://example.com/splash.jpg"
```

## 输出格式

### 表格格式（默认）

```bash
npx polyv-live-cli@latest channel list
# 显示表格，包含以下列：
# 频道ID | 名称 | 状态 | 场景 | 创建时间
```

### JSON格式

```bash
npx polyv-live-cli@latest channel list -o json

# 返回：
# {
#   "code": 200,
#   "status": "success",
#   "data": {
#     "contents": [...],
#     "pageSize": 20,
#     "pageNumber": 1,
#     "totalItems": 50
#   }
# }
```

## 常用工作流程

### 创建网络研讨会频道

```bash
npx polyv-live-cli@latest channel create \
  -n "Q4战略研讨会" \
  -d "全员季度战略回顾" \
  --scene seminar \
  --template seminar \
  --max-viewers 500 \
  --auto-record \
  -o json
```

### 创建电商直播频道

```bash
npx polyv-live-cli@latest channel create \
  -n "限时特卖活动" \
  -d "24小时限时特卖直播" \
  --scene alone \
  --template portrait_alone \
  --max-viewers 10000 \
  -o json
```

### 批量清理测试频道

```bash
# 列出测试频道
npx polyv-live-cli@latest channel list --keyword "test" -o json | jq '.data.contents[].channelId'

# 批量删除
npx polyv-live-cli@latest channel batch-delete --channelIds 123 456 789 -f
```

## 故障排除

### "Channel not found"（频道不存在）

- 确认频道ID是否正确
- 检查频道是否属于当前账号
- 确认频道是否已被删除

### "Invalid scene type"（无效场景类型）

- 使用以下之一：`topclass`、`alone`、`seminar`、`train`、`double`、`guide`
- 场景名称区分大小写
- `double` 和 `guide` 需要开通权限

### "密码必须是6-16位字母数字"

- 只使用字母和数字
- 长度必须在6-16个字符之间


path: references/coupons.md
content: # 优惠券管理

## 概述

优惠券是直播购物时可以使用的折扣码，用于促进销售和提高观众参与度。

## 创建优惠券

### 基本优惠券

```bash
npx polyv-live-cli@latest coupon create \
  -c 3151318 \
  -n "夏季特惠" \
  --discount 10.00
```

### 完整选项

```bash
npx polyv-live-cli@latest coupon create \
  -c 3151318 \
  -n "VIP折扣" \
  --discount 50.00 \
  --type percentage \
  --min-purchase 100.00 \
  --max-usage 1000 \
  --start-time "2024-06-01T00:00:00Z" \
  --end-time "2024-06-30T23:59:59Z"
```

### 优惠券选项

| 选项 | 说明 | 必填 |
|------|------|------|
| `-c, --channelId` | 频道ID | 是 |
| `-n, --name` | 优惠券名称 | 是 |
| `--discount` | 折扣金额/比例 | 是 |
| `--type` | `percentage`（百分比）或 `fixed`（固定金额） | 否（默认：fixed） |
| `--min-purchase` | 最低消费金额 | 否 |
| `--max-usage` | 最大使用次数 | 否 |
| `--start-time` | 生效时间（ISO 8601格式） | 否 |
| `--end-time` | 失效时间（ISO 8601格式） | 否 |

### 折扣类型

| 类型 | 说明 | 示例 |
|------|------|------|
| `fixed` | 固定金额减免 | 减¥10.00 |
| `percentage` | 百分比折扣 | 打9折 |

## 优惠券列表

```bash
# 基本列表
npx polyv-live-cli@latest coupon list -c 3151318

# 输出：
# 优惠券ID | 名称 | 折扣 | 类型 | 使用情况 | 状态
# cpn001   | 夏季特惠 | ¥10.00 | fixed | 50/100 | 有效
# cpn002   | VIP9折 | 10% | percentage | 25/- | 有效
```

### JSON输出

```bash
npx polyv-live-cli@latest coupon list -c 3151318 -o json
```

## 获取优惠券详情

```bash
# 表格格式
npx polyv-live-cli@latest coupon get -c 3151318 --couponId cpn001

# JSON格式
npx polyv-live-cli@latest coupon get -c 3151318 --couponId cpn001 -o json
```

## 删除优惠券

```bash
# 带确认提示
npx polyv-live-cli@latest coupon delete -c 3151318 --couponId cpn001

# 强制删除
npx polyv-live-cli@latest coupon delete -c 3151318 --couponId cpn001 -f
```

## 常用工作流程

### 创建限时特卖优惠券

```bash
# 创建限时优惠券
npx polyv-live-cli@latest coupon create \
  -c 3151318 \
  -n "限时8折" \
  --discount 20 \
  --type percentage \
  --max-usage 500 \
  --start-time "2024-06-15T10:00:00Z" \
  --end-time "2024-06-15T12:00:00Z"
```

### 创建VIP专属优惠券

```bash
# 高价值VIP优惠券
npx polyv-live-cli@latest coupon create \
  -c 3151318 \
  -n "VIP专属立减50" \
  --discount 50.00 \
  --type fixed \
  --min-purchase 200.00 \
  --max-usage 100
```

### 查看有效优惠券

```bash
# 获取所有优惠券并筛选有效
npx polyv-live-cli@latest coupon list -c 3151318 -o json | jq '.data[] | select(.status == "active")'
```

### 批量创建优惠券

```bash
# 为营销活动创建多张优惠券
for i in {1..10}; do
  npx polyv-live-cli@latest coupon create \
    -c 3151318 \
    -n "活动优惠券$i" \
    --discount 10.00 \
    --max-usage 100
done
```

## 优惠券状态

| 状态 | 说明 |
|------|------|
| `active` | 优惠券可使用 |
| `expired` | 优惠券已过期 |
| `exhausted` | 已达最大使用次数 |
| `disabled` | 已手动禁用 |

## 故障排除

### "Coupon not found"（优惠券不存在）

- 确认优惠券ID是否正确
- 检查优惠券是否属于该频道

### "Coupon expired"（优惠券已过期）

- 检查结束时间：`npx polyv-live-cli@latest coupon get -c <频道ID> --couponId <优惠券ID>`
- 创建新的优惠券并设置有效日期

### "Maximum usage reached"（已达最大使用次数）

- 检查使用次数：`npx polyv-live-cli@latest coupon get -c <频道ID> --couponId <优惠券ID>`
- 创建新优惠券或增加使用上限

### "Minimum purchase not met"（未达到最低消费）

- 告知用户最低消费要求
- 最低消费在创建优惠券时设置


path: references/scene-setup.md
content: # 场景初始化

## 概述

场景初始化命令用于快速创建预配置的频道，适用于电商、教育、活动等常见场景。

## 查看可用场景

```bash
npx polyv-live-cli@latest setup --list

# 输出：
# 场景        | 描述
# e-commerce  | 电商直播（预置商品功能）
# education   | 在线教育/云课堂
# event       | 活动/会议直播
# webinar     | 专业网络研讨会
```

## 电商场景

适用于直播带货和电商直播。

```bash
npx polyv-live-cli@latest setup e-commerce

# 创建内容：
# - 电商模板频道
# - 开启频道商品库
# - 示例商品
# - 新人优惠券
# - 开启观看页优惠券展示
# - 购物车集成
# - 商品展示布局
```

### 电商场景选项

```bash
npx polyv-live-cli@latest setup e-commerce \
  --channel-name "限时特卖" \
  --products 10 \
  --coupons 5
```

## 教育场景

适用于在线课程和培训。

```bash
npx polyv-live-cli@latest setup education

# 创建内容：
# - 云课堂模板频道
# - PPT/文档支持
# - 学员互动功能
# - 自动录制
```

### 教育场景选项

```bash
npx polyv-live-cli@latest setup education \
  --channel-name "在线课程" \
  --max-students 500 \
  --auto-record
```

## 活动场景

适用于活动和会议直播。

```bash
npx polyv-live-cli@latest setup event

# 创建内容：
# - 高容量频道
# - 多机位支持
# - 互动问答功能
# - 社交分享
```

### 活动场景选项

```bash
npx polyv-live-cli@latest setup event \
  --channel-name "年度大会" \
  --max-viewers 10000 \
  --live-qa \
  --social-sharing
```

## 研讨会场景

适用于专业网络研讨会。

```bash
npx polyv-live-cli@latest setup webinar

# 创建内容：
# - 专业研讨会频道
# - 报名系统
# - 投票问卷
# - 录制和回放
```

### 研讨会场景选项

```bash
npx polyv-live-cli@latest setup webinar \
  --channel-name "产品演示" \
  --registration \
  --polls \
  --auto-record
```

## 自定义配置

```bash
# 自定义配置
npx polyv-live-cli@latest setup custom \
  --channel-name "自定义直播" \
  --scene topclass \
  --template ppt \
  --products \
  --coupons \
  --auto-record
```

## 常用工作流程

### 快速电商配置

```bash
# 一键完成电商配置
npx polyv-live-cli@latest setup e-commerce \
  --channel-name "今日特惠" \
  --products 20 \
  --coupons 3 \
  -o json
```

### 教育课程配置

```bash
# 创建课程频道
npx polyv-live-cli@latest setup education \
  --channel-name "JavaScript基础" \
  --max-students 200 \
  --auto-record

# 添加课程资料（如支持）
npx polyv-live-cli@latest document upload -c 3151318 -f slides.pdf
```

### 多日活动

```bash
# 创建活动频道
npx polyv-live-cli@latest setup event \
  --channel-name "技术峰会2024" \
  --max-viewers 5000 \
  --live-qa

# 活动会有多场直播
# 每场直播创建一个新回放
```

## 场景选项汇总

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--channel-name` | 新频道名称 | 基于场景 |
| `--products` | 示例商品数量 | 0 |
| `--coupons` | 示例优惠券数量 | 0 |
| `--max-viewers` | 最大并发观众数 | 基于场景 |
| `--auto-record` | 启用自动录制 | false |
| `--registration` | 启用报名 | false |
| `--live-qa` | 启用互动问答 | false |
| `--polls` | 启用投票 | false |
| `-o, --output` | 输出格式 | table |

## 初始化后操作

运行场景初始化后：

1. **获取推流凭证**
   ```bash
   npx polyv-live-cli@latest stream get-key -c <频道ID>
   ```

2. **配置商品**（如适用）
   ```bash
   npx polyv-live-cli@latest product list -c <频道ID>
   npx polyv-live-cli@latest product update -c <频道ID> -p <商品ID> --price <价格>
   ```

3. **配置优惠券**（如适用）
   ```bash
   npx polyv-live-cli@latest coupon list -c <频道ID>
   ```

4. **开始直播**
   ```bash
   npx polyv-live-cli@latest stream start -c <频道ID>
   ```

## 故障排除

### "Scene template not found"（场景模板不存在）

- 使用 `--list` 查看可用场景
- 场景名称区分大小写

### "Setup failed"（初始化失败）

- 检查认证是否有效
- 确认账号有权限
- 尝试使用 --verbose 查看详细信息

### "Products not created"（商品未创建）

- 某些场景默认不包含商品
- 使用 `--products <数量>` 指定商品数量


path: references/chat-management.md
content: # 聊天消息管理

本文档详细介绍保利威直播 CLI 的聊天消息管理命令。

## 命令概览

```bash
npx polyv-live-cli@latest chat <子命令> [选项]
```

## 子命令

### chat send - 发送管理员消息

向指定频道发送管理员消息（文本或图片）。

```bash
npx polyv-live-cli@latest chat send -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-m, --msg <文本>` | 文本消息内容 |
| `-i, --img-url <url>` | 图片 URL |
| `-p, --pic <url>` | 发送者头像 URL |
| `-n, --nickname <名称>` | 发送者昵称 |
| `-a, --actor <角色>` | 发送者角色 |
| `--admin-index <数字>` | 管理员索引 |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

> 注意：`-m` 和 `-i` 至少需要提供一个。

#### 示例

```bash
# 发送文本消息
npx polyv-live-cli@latest chat send -c 3151318 -m "欢迎观看直播！"

# 发送图片消息
npx polyv-live-cli@latest chat send -c 3151318 -i "https://example.com/image.png"

# 发送带自定义昵称的消息
npx polyv-live-cli@latest chat send -c 3151318 -m "大家好" -n "主播" -a "主持人"

# JSON 格式输出
npx polyv-live-cli@latest chat send -c 3151318 -m "测试消息" -o json
```

---

### chat list - 查看聊天历史

获取指定频道的聊天消息历史记录。

```bash
npx polyv-live-cli@latest chat list -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `--start-day <日期>` | 开始日期筛选（格式：yyyy-MM-dd） |
| `--end-day <日期>` | 结束日期筛选（格式：yyyy-MM-dd） |
| `--page <数字>` | 页码（默认 1） |
| `--size <数字>` | 每页数量，1-100（默认 20） |
| `--user-type <类型>` | 用户类型筛选 |
| `--status <状态>` | 消息状态筛选 |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 查看最近聊天消息
npx polyv-live-cli@latest chat list -c 3151318

# 分页查看
npx polyv-live-cli@latest chat list -c 3151318 --page 2 --size 50

# 按日期范围筛选
npx polyv-live-cli@latest chat list -c 3151318 --start-day 2024-01-01 --end-day 2024-01-31

# JSON 格式输出
npx polyv-live-cli@latest chat list -c 3151318 -o json
```

#### 表格输出字段

| 字段 | 说明 |
|------|------|
| Message ID | 消息唯一标识 |
| Content | 消息内容（过长会截断） |
| Time | 消息发送时间 |
| Sender | 发送者昵称 |
| User Type | 发送者类型 |

---

### chat delete - 删除消息

删除单条消息或清空频道所有聊天消息。

```bash
npx polyv-live-cli@latest chat delete -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-m, --message-id <id>` | 要删除的消息 ID |
| `--clear` | 清空该频道所有聊天消息 |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

> 注意：如果使用 `--clear`，则不需要指定 `--message-id`。

#### 示例

```bash
# 删除单条消息
npx polyv-live-cli@latest chat delete -c 3151318 -m abc123

# 清空所有消息
npx polyv-live-cli@latest chat delete -c 3151318 --clear
```

> 警告：删除操作不可恢复，执行前会有确认提示。

---

## 禁言踢人管理 (Story 11-2)

### chat ban - 禁言用户

禁言指定用户，支持频道级别和账号级别（全局）。

```bash
npx polyv-live-cli@latest chat ban [选项]
```

#### 选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID（频道级别禁言时必需） |
| `-u, --user-ids <ids>` | 用户 ID，多个用逗号分隔（必需） |
| `--global` | 全局禁言（账号级别） |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 频道级别禁言
npx polyv-live-cli@latest chat ban -c 3151318 -u user1,user2

# 全局禁言
npx polyv-live-cli@latest chat ban -u user1,user2 --global

# JSON 格式输出
npx polyv-live-cli@latest chat ban -c 3151318 -u user1 -o json
```

---

### chat unban - 解除禁言

解除用户的禁言状态。

```bash
npx polyv-live-cli@latest chat unban [选项]
```

#### 选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID（频道级别解禁时必需） |
| `-u, --user-ids <ids>` | 用户 ID，多个用逗号分隔（必需） |
| `--global` | 全局解禁（账号级别） |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 频道级别解禁
npx polyv-live-cli@latest chat unban -c 3151318 -u user1,user2

# 全局解禁
npx polyv-live-cli@latest chat unban -u user1,user2 --global
```

---

### chat kick - 踢人

将用户踢出直播间，支持频道级别和账号级别（全局）。

```bash
npx polyv-live-cli@latest chat kick [选项]
```

#### 选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID（频道级别踢人时必需） |
| `--viewer-ids <ids>` | 观众 ID，多个用逗号分隔 |
| `-n, --nick-names <names>` | 观众昵称，多个用逗号分隔 |
| `--global` | 全局踢人（账号级别） |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

> 注意：`--viewer-ids` 和 `-n` 至少需要提供一个。

#### 示例

```bash
# 频道级别踢人
npx polyv-live-cli@latest chat kick -c 3151318 --viewer-ids viewer1,viewer2 -n Nick1,Nick2

# 全局踢人
npx polyv-live-cli@latest chat kick --viewer-ids viewer1 --global

# JSON 格式输出
npx polyv-live-cli@latest chat kick -c 3151318 --viewer-ids viewer1 -o json
```

---

### chat unkick - 解除踢人

解除用户的踢人状态，允许重新进入直播间。

```bash
npx polyv-live-cli@latest chat unkick [选项]
```

#### 选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID（频道级别解踢时必需） |
| `--viewer-ids <ids>` | 观众 ID，多个用逗号分隔 |
| `-n, --nick-names <names>` | 观众昵称，多个用逗号分隔 |
| `--global` | 全局解踢（账号级别） |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 频道级别解踢
npx polyv-live-cli@latest chat unkick -c 3151318 --viewer-ids viewer1 -n Nick1

# 全局解踢
npx polyv-live-cli@latest chat unkick --viewer-ids viewer1 --global
```

---

### chat banned list - 查看禁言列表

查看频道的禁言用户、禁言 IP 或禁言词列表。

```bash
npx polyv-live-cli@latest chat banned list -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |
| `--type <类型>` | 列表类型：userId（用户）、ip（IP地址）、badword（禁言词） |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 查看禁言用户列表
npx polyv-live-cli@latest chat banned list -c 3151318 --type userId

# 查看禁言 IP 列表
npx polyv-live-cli@latest chat banned list -c 3151318 --type ip

# 查看禁言词列表
npx polyv-live-cli@latest chat banned list -c 3151318 --type badword

# JSON 格式输出
npx polyv-live-cli@latest chat banned list -c 3151318 --type userId -o json
```

---

### chat kicked list - 查看踢人列表

查看频道被踢出的用户列表。

```bash
npx polyv-live-cli@latest chat kicked list -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 查看踢人列表
npx polyv-live-cli@latest chat kicked list -c 3151318

# JSON 格式输出
npx polyv-live-cli@latest chat kicked list -c 3151318 -o json
```

---

## 常见工作流程

### 1. 发送直播公告

```bash
# 发送开播公告
npx polyv-live-cli@latest chat send -c 3151318 -m "直播即将开始，请稍候..." -n "系统公告" -a "管理员"
```

### 2. 查看并管理聊天记录

```bash
# 查看今天的聊天记录
npx polyv-live-cli@latest chat list -c 3151318 --start-day 2024-01-15 --end-day 2024-01-15

# 如果发现不当内容，删除该消息
npx polyv-live-cli@latest chat delete -c 3151318 -m <消息ID>
```

### 3. 直播结束后清理聊天

```bash
# 清空所有聊天消息
npx polyv-live-cli@latest chat delete -c 3151318 --clear
```

## 错误处理

| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| `channelId is required` | 未指定频道 ID | 使用 `-c` 参数指定频道 |
| `msg or imgUrl is required` | 发送消息时未提供内容 | 使用 `-m` 或 `-i` 参数 |
| `messageId is required when --clear is not specified` | 删除时未指定消息 ID | 使用 `-m` 参数或 `--clear` 选项 |

## API 参考

相关 API 文档：
- [发送管理员消息](https://help.polyv.net/#/live/api/chat/send_admin_msg)
- [获取聊天历史](https://help.polyv.net/#/live/api/chat/get_history)
- [删除聊天消息](https://help.polyv.net/#/live/api/chat/del_chat)
- [清空聊天记录](https://help.polyv.net/#/live/api/chat/clean_chat)


path: references/platform.md
content: # 平台账号信息管理命令

## 概述

平台账号信息管理命令用于查看和配置保利威账号的基本信息和开关配置。

## 命令列表

| 命令 | 描述 |
|------|------|
| `platform get` | 获取账号基本信息 |
| `platform switch get` | 获取账号开关配置 |
| `platform switch update` | 更新账号开关配置 |
| `platform callback get` | 获取回调设置 |
| `platform callback update` | 更新回调设置 |
| `platform setting get` | 获取全局频道设置 |
| `platform setting update` | 更新全局频道设置 |

## platform get

获取账号基本信息，包括用户ID、邮箱、频道数、连麦限制等。

### 用法

```bash
npx polyv-live-cli@latest platform get [选项]
```

### 选项

| 选项 | 简写 | 描述 | 默认值 |
|------|------|------|--------|
| `--output` | `-o` | 输出格式 (table\|json) | table |

### 示例

```bash
# 获取账号基本信息（表格格式）
npx polyv-live-cli@latest platform get

# 获取账号基本信息（JSON格式）
npx polyv-live-cli@latest platform get -o json
```

### 输出字段说明

| 字段 | 描述 |
|------|------|
| 用户 ID | 保利威账号的用户ID |
| 邮箱 | 账号绑定的邮箱地址 |
| 最大频道数 | 账号可创建的最大频道数量 |
| 总频道数 | 当前已创建的频道总数 |
| 可用频道数 | 剩余可创建的频道数量 |
| 连麦限制 | 连麦功能的限制数 |
| 观看域名 | 自定义观看域名（如已配置） |

### JSON 输出示例

```json
{
  "userId": "user123",
  "email": "[REDACTED_SECRET]",
  "maxChannels": 100,
  "totalChannels": 10,
  "availableChannels": 90,
  "linkMicLimit": 10,
  "watchDomain": "https://live.example.com"
}
```

---

## platform switch get

获取账号的开关配置状态，包括全局设置、认证、录制、回放、弹幕等开关状态。

### 用法

```bash
npx polyv-live-cli@latest platform switch get [选项]
```

### 选项

| 选项 | 简写 | 描述 | 默认值 |
|------|------|------|--------|
| `--output` | `-o` | 输出格式 (table\|json) | table |

### 示例

```bash
# 获取开关配置（表格格式）
npx polyv-live-cli@latest platform switch get

# 获取开关配置（JSON格式）
npx polyv-live-cli@latest platform switch get -o json
```

### 输出字段说明

| 开关名称 | 描述 |
|----------|------|
| 全局设置 | 全局设置开关状态 |
| 认证 | 认证功能开关状态 |
| 录制 | 自动录制开关状态 |
| 回放 | 回放功能开关状态 |
| 弹幕 | 弹幕功能开关状态 |

### JSON 输出示例

```json
{
  "config": {
    "globalSettingEnabled": true,
    "authEnabled": false,
    "recordEnabled": true,
    "playbackEnabled": true,
    "danmuEnabled": false
  }
}
```

---

## platform switch update

更新账号的开关配置。

### 用法

```bash
npx polyv-live-cli@latest platform switch update --param <参数名> --enabled <Y|N> [选项]
```

### 选项

| 选项 | 简写 | 描述 | 必需 | 默认值 |
|------|------|------|------|--------|
| `--param` | - | 开关参数名称 | 是 | - |
| `--enabled` | - | 启用状态 (Y\|N) | 是 | - |
| `--output` | `-o` | 输出格式 (table\|json) | 否 | table |

### 可用参数

| 参数名 | 描述 |
|--------|------|
| `globalSettingEnabled` | 全局设置开关 |
| `authEnabled` | 认证开关 |
| `recordEnabled` | 录制开关 |
| `playbackEnabled` | 回放开关 |
| `danmuEnabled` | 弹幕开关 |

### 示例

```bash
# 启用认证功能
npx polyv-live-cli@latest platform switch update --param authEnabled --enabled Y

# 禁用录制功能
npx polyv-live-cli@latest platform switch update --param recordEnabled --enabled N

# 启用弹幕功能（JSON输出）
npx polyv-live-cli@latest platform switch update --param danmuEnabled --enabled Y -o json
```

### 错误处理

| 错误情况 | 错误信息 |
|----------|----------|
| 参数为空 | `param (配置项名称) 是必需的` |
| enabled 值无效 | `enabled 必须是 Y 或 N` |
| 不支持的参数 | `不支持的配置项: xxx。可用配置项: globalSettingEnabled, authEnabled, recordEnabled, playbackEnabled, danmuEnabled` |

---

## API 映射

| CLI 命令 | SDK 方法 | API 端点 |
|----------|----------|----------|
| `platform get` | `account.getUserInfo()` | `/live/v3/user/get-info` |
| `platform switch get` | `account.switchGet()` | `/live/v3/user/switch/get` |
| `platform switch update` | `account.switchUpdate()` | `/live/v3/user/switch/update` |
| `platform callback get` | `v4User.getCallback()` | `/live/v4/user/callback/get` |
| `platform callback update` | `v4User.updateCallback()` | `/live/v4/user/callback/update` |
| `platform setting get` | `v4User.getGlobalChannelSettings()` | `/live/v4/user/global-setting/switch/get` |
| `platform setting update` | `v4User.updateGlobalChannelSettings()` | `/live/v4/user/global-setting/switch/update` |

---

## platform callback get

获取回调设置，包括回调URL和启用状态。

### 用法

```bash
npx polyv-live-cli@latest platform callback get [选项]
```

### 选项

| 选项 | 简写 | 描述 | 默认值 |
|------|------|------|--------|
| `--output` | `-o` | 输出格式 (table\|json) | table |

### 示例

```bash
# 获取回调设置（表格格式）
npx polyv-live-cli@latest platform callback get

# 获取回调设置（JSON格式）
npx polyv-live-cli@latest platform callback get -o json
```

### 输出字段说明

| 字段 | 描述 |
|------|------|
| 回调 URL | 接收回调通知的URL地址 |
| 是否启用 | 回调功能是否启用（是/否） |

### JSON 输出示例

```json
{
  "url": "https://example.com/callback",
  "enabled": true
}
```

---

## platform callback update

更新回调设置，可以更新回调URL和启用状态。

### 用法

```bash
npx polyv-live-cli@latest platform callback update [选项]
```

### 选项

| 选项 | 简写 | 描述 | 必需 | 默认值 |
|------|------|------|------|--------|
| `--url` | - | 回调URL（必须以 http:// 或 https:// 开头） | 否 | - |
| `--enabled` | - | 启用状态 (Y\|N) | 否 | - |
| `--output` | `-o` | 输出格式 (table\|json) | 否 | table |

**注意：** 至少需要提供一个选项（`--url` 或 `--enabled`）。

### 示例

```bash
# 更新回调URL
npx polyv-live-cli@latest platform callback update --url https://example.com/callback

# 启用回调
npx polyv-live-cli@latest platform callback update --enabled Y

# 禁用回调
npx polyv-live-cli@latest platform callback update --enabled N

# 同时更新URL和启用状态
npx polyv-live-cli@latest platform callback update --url https://example.com/callback --enabled Y

# JSON格式输出
npx polyv-live-cli@latest platform callback update --url https://example.com/callback -o json
```

### 错误处理

| 错误情况 | 错误信息 |
|----------|----------|
| 无参数提供 | `至少需要提供 url 或 enabled 参数` |
| URL格式错误 | `url 必须以 http:// 或 https:// 开头` |
| enabled值无效 | `enabled 必须是 Y 或 N` |

---

## platform setting get

获取全局频道设置，包括并发观看人数、自动转码、打赏等功能的状态。

### 用法

```bash
npx polyv-live-cli@latest platform setting get [选项]
```

### 选项

| 选项 | 简写 | 描述 | 默认值 |
|------|------|------|--------|
| `--output` | `-o` | 输出格式 (table\|json) | table |

### 示例

```bash
# 获取全局频道设置（表格格式）
npx polyv-live-cli@latest platform setting get

# 获取全局频道设置（JSON格式）
npx polyv-live-cli@latest platform setting get -o json
```

### 输出字段说明

| 设置项 | 描述 |
|--------|------|
| 最大并发观看人数 | 最大并发观看人数开关（开启/禁用） |
| 自动转码 | 自动转码功能开关 |
| 打赏功能 | 打赏功能开关 |
| 转存自动上传 | 转存自动上传PPT开关 |
| 转存自动转码 | 转存自动转码开关 |
| PPT全屏 | PPT全屏显示开关 |
| 封面图片类型 | 播放器封面图片类型（contain/cover） |
| 测试模式按钮 | 测试模式按钮开关 |

### JSON 输出示例

```json
{
  "channelConcurrencesEnabled": "Y",
  "timelyConvertEnabled": "Y",
  "donateEnabled": "N",
  "rebirthAutoUploadEnabled": "N",
  "rebirthAutoConvertEnabled": "N",
  "pptCoveredEnabled": "N",
  "coverImgType": "contain",
  "testModeButtonEnabled": "N"
}
```

---

## platform setting update

更新全局频道设置，可以同时更新多个设置项。

### 用法

```bash
npx polyv-live-cli@latest platform setting update [选项]
```

### 选项

| 选项 | 描述 | 值 |
|------|------|------|
| `--channel-concurrences-enabled` | 最大并发观看人数开关 | Y/N |
| `--timely-convert-enabled` | 自动转码开关 | Y/N |
| `--donate-enabled` | 打赏功能开关 | Y/N |
| `--rebirth-auto-upload-enabled` | 转存自动上传PPT | Y/N |
| `--rebirth-auto-convert-enabled` | 转存自动转码 | Y/N |
| `--ppt-covered-enabled` | PPT全屏开关 | Y/N |
| `--cover-img-type` | 封面图片类型 | contain/cover |
| `--test-mode-button-enabled` | 测试模式按钮 | Y/N |
| `--output` | 输出格式 (table\|json) | table |

**注意：** 至少需要提供一个设置选项。

### 示例

```bash
# 更新单个设置
npx polyv-live-cli@latest platform setting update --channel-concurrences-enabled Y

# 更新多个设置
npx polyv-live-cli@latest platform setting update \
  --channel-concurrences-enabled Y \
  --timely-convert-enabled Y \
  --donate-enabled N

# 更新封面图片类型
npx polyv-live-cli@latest platform setting update --cover-img-type contain

# JSON格式输出
npx polyv-live-cli@latest platform setting update --donate-enabled Y -o json
```

### 错误处理

| 错误情况 | 错误信息 |
|----------|----------|
| 无参数提供 | `至少需要提供一个参数 (At least one parameter is required)` |
| Y/N值无效 | `xxx 必须是 Y 或 N` |
| 封面类型无效 | `coverImgType 必须是 contain 或 cover` |

---

## API 映射

- [身份认证配置](authentication.md)
- [频道管理](channel-management.md)
- [录制设置](record-settings.md)


path: references/player.md
content: # 播放器管理

## 概述

播放器命令用于管理频道播放器配置，包括水印设置、暖场图片和基础访问量等。

## 获取播放器配置

```bash
# 获取频道播放器配置
npx polyv-live-cli@latest player config get -c 3151318

# JSON输出
npx polyv-live-cli@latest player config get -c 3151318 -o json
```

### 输出示例

```
┌─────────────────────┬──────────────────────────────┐
│ Setting             │ Value                        │
├─────────────────────┼──────────────────────────────┤
│ Watermark Enabled   │ Y                            │
│ Watermark URL       │ http://example.com/logo.png  │
│ Watermark Position  │ br (Bottom-right)            │
│ Watermark Opacity   │ 0.8                          │
│ Warmup Enabled      │ Y                            │
│ Warmup Image URL    │ http://example.com/warmup.jpg│
│ Base Page Views     │ 1000                         │
└─────────────────────┴──────────────────────────────┘
```

## 更新播放器配置

### 水印设置

```bash
# 启用水印
npx polyv-live-cli@latest player config update -c 3151318 --watermark-enabled Y

# 设置水印图片
npx polyv-live-cli@latest player config update -c 3151318 --watermark-url "http://example.com/logo.png"

# 设置水印位置
npx polyv-live-cli@latest player config update -c 3151318 --watermark-position br

# 设置水印透明度
npx polyv-live-cli@latest player config update -c 3151318 --watermark-opacity 0.8

# 完整水印配置
npx polyv-live-cli@latest player config update -c 3151318 \
  --watermark-enabled Y \
  --watermark-url "http://example.com/logo.png" \
  --watermark-position br \
  --watermark-opacity 0.8
```

### 水印位置说明

| 值 | 位置 |
|----|------|
| `tl` | 左上角 (Top-left) |
| `tr` | 右上角 (Top-right) |
| `bl` | 左下角 (Bottom-left) |
| `br` | 右下角 (Bottom-right) |

### 水印透明度

- 范围：0 - 1
- 0 = 完全透明
- 1 = 完全不透明
- 推荐值：0.7 - 0.9

### 暖场设置

```bash
# 启用暖场图片
npx polyv-live-cli@latest player config update -c 3151318 --warmup-enabled Y

# 设置暖场图片
npx polyv-live-cli@latest player config update -c 3151318 --warmup-image-url "http://example.com/warmup.jpg"

# 完整暖场配置
npx polyv-live-cli@latest player config update -c 3151318 \
  --warmup-enabled Y \
  --warmup-image-url "http://example.com/warmup.jpg"
```

### 基础访问量

```bash
# 设置基础访问量
npx polyv-live-cli@latest player config update -c 3151318 --base-pv 1000
```

> **说明**: 基础访问量会在实际访问量基础上叠加显示，用于初始化显示数据。

## 更新选项汇总

| 选项 | 说明 | 格式 |
|------|------|------|
| `--watermark-enabled` | 启用/禁用水印 | Y / N |
| `--watermark-url` | 水印图片URL | 完整URL |
| `--watermark-position` | 水印位置 | tl / tr / bl / br |
| `--watermark-opacity` | 水印透明度 | 0 - 1 |
| `--warmup-enabled` | 启用/禁用暖场 | Y / N |
| `--warmup-image-url` | 暖场图片URL | 完整URL |
| `--base-pv` | 基础访问量 | 数字 |
| `-o, --output` | 输出格式 | table / json |

## 常用工作流程

### 配置品牌水印

```bash
# 1. 获取当前配置
npx polyv-live-cli@latest player config get -c 3151318

# 2. 配置品牌水印
npx polyv-live-cli@latest player config update -c 3151318 \
  --watermark-enabled Y \
  --watermark-url "https://cdn.example.com/brand-logo.png" \
  --watermark-position br \
  --watermark-opacity 0.7

# 3. 验证配置
npx polyv-live-cli@latest player config get -c 3151318 -o json
```

### 配置直播暖场

```bash
# 1. 准备暖场图片（建议16:9比例）
# 2. 上传到CDN获取URL

# 3. 配置暖场图片
npx polyv-live-cli@latest player config update -c 3151318 \
  --warmup-enabled Y \
  --warmup-image-url "https://cdn.example.com/warmup.jpg"

# 4. 直播开始后禁用暖场（可选）
npx polyv-live-cli@latest player config update -c 3151318 --warmup-enabled N
```

### 批量配置多个频道

```bash
# 为多个频道应用相同配置
for channel in 3151318 3151319 3151320; do
  npx polyv-live-cli@latest player config update -c $channel \
    --watermark-enabled Y \
    --watermark-url "https://cdn.example.com/logo.png" \
    --watermark-position br \
    --watermark-opacity 0.8
done
```

### 导出和导入配置

```bash
# 导出配置
npx polyv-live-cli@latest player config get -c 3151318 -o json > player-config.json

# 查看配置
cat player-config.json

# 可以用于文档记录或其他频道的参考
```

## Y/N 值说明

以下选项使用 Y/N 格式：

| 值 | 说明 |
|----|------|
| `Y` | 是/启用 |
| `N` | 否/禁用 |

## 输出格式

### 表格格式（默认）

```
┌─────────────────────┬──────────────────────────────┐
│ Setting             │ Value                        │
├─────────────────────┼──────────────────────────────┤
│ Watermark Enabled   │ Y                            │
│ Watermark URL       │ http://example.com/logo.png  │
│ ...                 │ ...                          │
└─────────────────────┴──────────────────────────────┘
```

### JSON格式

```json
{
  "channelId": "3151318",
  "watermark": {
    "enabled": "Y",
    "url": "http://example.com/logo.png",
    "position": "br",
    "opacity": 0.8
  },
  "warmup": {
    "enabled": "Y",
    "imageUrl": "http://example.com/warmup.jpg"
  },
  "basePv": 1000
}
```

## 故障排除

### "水印不显示"

- 确认 `--watermark-enabled` 设置为 Y
- 检查图片URL是否可访问
- 确保图片格式为 PNG、JPG 或 GIF
- 检查透明度设置（0.5以上更明显）

### "暖场图片不显示"

- 确认 `--warmup-enabled` 设置为 Y
- 检查图片URL是否有效
- 建议使用 CDN 托管图片
- 图片建议尺寸：1920x1080（16:9）

### "配置更新失败"

- 确认频道ID正确
- 检查URL格式是否正确（需包含 http:// 或 https://）
- 确保有频道管理权限

### "参数值无效"

- `--watermark-position` 只接受 tl/tr/bl/br
- `--watermark-opacity` 范围为 0-1
- `--watermark-enabled` 和 `--warmup-enabled` 只接受 Y 或 N


path: references/statistics.md
content: # 统计分析

## 概述

统计命令提供频道表现、观众行为和直播质量的洞察数据。

## 查看每日观看统计

```bash
npx polyv-live-cli@latest statistics view -c <频道ID> --start-day 2024-01-01 --end-day 2024-01-31

# JSON格式输出
npx polyv-live-cli@latest statistics view -c 3151318 --start-day "2024-01-01" --end-day "2024-01-31" -o json
```

### 选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID | 必填 |
| `--start-day` | 开始日期 | YYYY-MM-DD |
| `--end-day` | 结束日期 | YYYY-MM-DD |
| `-o, --output` | 输出格式 | table（默认）/ json |

## 历史并发数据

查看指定日期范围内的并发数据。

```bash
npx polyv-live-cli@latest statistics concurrency -c <频道ID> --start-date 2024-01-01 --end-date 2024-01-31

# JSON格式输出
npx polyv-live-cli@latest statistics concurrency -c 3151318 --start-date 2024-01-01 --end-date 2024-01-31 -o json
```

### 选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID | 必填 |
| `--start-date` | 开始日期 | YYYY-MM-DD |
| `--end-date` | 结束日期 | YYYY-MM-DD |
| `-o, --output` | 输出格式 | table（默认）/ json |

## 历史最高并发人数

查看指定时间范围内的最高并发观看人数。

```bash
npx polyv-live-cli@latest statistics max-concurrent -c <频道ID> --start-time 1704067200000 --end-time 1735689600000

# JSON格式输出
npx polyv-live-cli@latest statistics max-concurrent -c 3151318 --start-time 1704067200000 --end-time 1735689600000 -o json
```

### 选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID | 必填 |
| `--start-time` | 开始时间戳 | 13位毫秒时间戳 |
| `--end-time` | 结束时间戳 | 13位毫秒时间戳 |
| `-o, --output` | 输出格式 | table（默认）/ json |

**注意：** 时间范围不能超过3个月

## 观众统计

查看观众的设备和地区分布。

### 设备分布

```bash
npx polyv-live-cli@latest statistics audience device -c <频道ID>
```

### 地区分布

```bash
npx polyv-live-cli@latest statistics audience region -c <频道ID>
```

## 导出统计数据

导出频道统计数据到文件。

```bash
npx polyv-live-cli@latest statistics export -c <频道ID> -f csv -o report.csv

# 导出为JSON
npx polyv-live-cli@latest statistics export -c 3151318 -f json -o channel-stats.json
```

### 导出选项

| 选项 | 说明 | 可选值 |
|------|------|--------|
| `-c, --channel-id` | 频道ID | 必填 |
| `-f, --format` | 导出格式 | csv, json |
| `-o, --output` | 输出文件路径 | - |

## 常用工作流程

### 生成周报

```bash
# 查看一周的观看数据
npx polyv-live-cli@latest statistics view \
  -c 3151318 \
  --start-day 2024-06-10 \
  --end-day 2024-06-16

# 导出为CSV
npx polyv-live-cli@latest statistics export \
  -c 3151318 \
  -f csv \
  -o weekly-report.csv
```

### 查看并发峰值

```bash
# 查看一个月内的最高并发
npx polyv-live-cli@latest statistics max-concurrent \
  -c 3151318 \
  --start-time 1704067200000 \
  --end-time 1706745600000
```

### 对比多个频道

```bash
# 导出多个频道的统计
for channel in 3151318 3151319 3151320; do
  npx polyv-live-cli@latest statistics view -c $channel -o json > "channel-$channel.json"
done
```

## 故障排除

### "No data available"（无可用数据）

- 检查日期范围是否有效
- 确认频道已有直播场次
- 确保数据已处理完成（最多需要24小时）

### "Date range too large"（日期范围过大）

- max-concurrent: 时间范围不能超过3个月
- view: 日期范围不能超过60天

### 时间戳转换

```bash
# 将日期转换为13位毫秒时间戳
date -j -f "%Y-%m-%d" "2024-01-01" "+%s"000
# 输出: 1704067200000
```


path: references/transmit.md
content: # 转播管理命令

批量创建和管理转播频道，## 如述

转播功能允许将主直播内容同时分发到多个频道，## 命令

### 创建转播频道

```bash
# 批量创建转播频道
npx polyv-live-cli@latest transmit create -c <主频道ID> --names "频道1,频道2,频道3"

# 礼例
npx polyv-live-cli@latest transmit create -c 3151318 --names "转播频道1,转播频道2,转播频道3"

# JSON格式输出
npx polyv-live-cli@latest transmit create -c 3151318 --names "频道1,频道2" -o json
```

**参数说明**:

| 参数 | 必填 | 说明 |
|------|------|------|
| -c, --channelId | 是 | 主频道ID（发起转播的频道） |
| --names | 是 | 转播频道名称，多个名称用逗号分隔，最多支持100个 |

### 列出转播关联

```bash
# 列出转播关联
npx polyv-live-cli@latest transmit list -c <频道ID>

# JSON格式输出
npx polyv-live-cli@latest transmit list -c 3151318 -o json
```

**参数说明**:

| 参数 | 必填 | 说明 |
|------|------|------|
| -c, --channelId | 是 | 频道ID |

### 输出格式

所有命令支持 `-o table`（默认）表格格式）或 `-o json`（JSON格式，## 选项

| 选项 | 缩写 | 说明 |
|------|------|------|
| -o | --output | 格式 | table 或 json |

## 限制

- 诏次最多创建 **100** 个转播频道
- 转播频道名称不能包含逗号（会被自动分割）
- 输出格式仅支持 table 和 json

## 使用示例

### 场景：批量创建多个转播频道

```bash
# 为频道 3151318 创建3个转播频道
npx polyv-live-cli@latest transmit create -c 3151318 --names "北京分会场上海分会场,广州分会场

# JSON格式输出（便于程序化处理）
npx polyv-live-cli@latest transmit create -c 3151318 --names "北京分会场,上海分会场" -o json
```

### 场景：查看转播关联

```bash
# 查看频道 3151318 的转播关联
npx polyv-live-cli@latest transmit list -c 3151318

# JSON格式输出
npx polyv-live-cli@latest transmit list -c 3151318 -o json
```

## 相关API

- [批量创建转播频道](https://help.polyv.net/#/live/api/channel/transmit/batch_create)
- [获取转播关联](https://help.polyv.net/#/live/api/channel/transmit/get_associations)


path: references/donate.md
content: # Donate Management Commands

Manage live streaming donation (打赏) interactions through the PolyV CLI.

## Overview

The donate commands allow you to:
- Get channel donate configuration settings
- Update donate settings (cash enabled, gift enabled, tips, amounts)
- List donation records with time range filtering

## Commands

### donate config get

Get the donate configuration for a channel.

```bash
polyv-live-cli donate config get -c <channelId> [options]
```

**Required Options:**
- `-c, --channel-id <id>` - Channel ID

**Optional Options:**
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# Get donate configuration
polyv-live-cli donate config get -c "3151318"

# Get configuration in JSON format
polyv-live-cli donate config get -c "3151318" -o json
```

**Output (table format):**
```
Donate Configuration for Channel: 3151318

Global Setting Enabled: Y
Cash Donate Enabled: Y
Good Donate Enabled: Y
Point Donate Enabled: N
Donate Tips: Thanks for your support!
Cash Min: 0.01
Cash Amounts: 0.88, 6.66, 8.88, 18.88, 66.6, 88.8
Goods:
  - Flower (0) - Enabled
  - Heart (1.99) - Enabled
```

---

### donate config update

Update the donate configuration for a channel.

```bash
polyv-live-cli donate config update -c <channelId> [options]
```

**Required Options:**
- `-c, --channel-id <id>` - Channel ID

**Optional Options:**
- `--cash-enabled <Y|N>` - Enable/disable cash donations
- `--gift-enabled <Y|N>` - Enable/disable gift donations
- `--tips <text>` - Donate tips text to display
- `--amounts <values>` - Comma-separated donation amounts (e.g., "0.88,6.66,8.88")
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# Enable cash donations
polyv-live-cli donate config update -c "3151318" --cash-enabled Y

# Update with tips and custom amounts
polyv-live-cli donate config update -c "3151318" \
  --tips "Thank you for your support!" \
  --amounts "0.88,6.66,8.88,18.88"

# Update all settings at once
polyv-live-cli donate config update -c "3151318" \
  --cash-enabled Y \
  --gift-enabled Y \
  --tips "Thanks!" \
  --amounts "1,5,10"
```

---

### donate list

List donation records for a channel within a time range.

```bash
polyv-live-cli donate list -c <channelId> --start <timestamp> --end <timestamp> [options]
```

**Required Options:**
- `-c, --channel-id <id>` - Channel ID
- `--start <timestamp>` - Start time (13-digit millisecond timestamp)
- `--end <timestamp>` - End time (13-digit millisecond timestamp)

**Optional Options:**
- `--page <number>` - Page number (default: 1)
- `--size <number>` - Page size (default: 10)
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# List donations within a time range
polyv-live-cli donate list -c "3151318" \
  --start 1615772426000 \
  --end 1615858826000

# List with pagination
polyv-live-cli donate list -c "3151318" \
  --start 1615772426000 \
  --end 1615858826000 \
  --page 2 \
  --size 20

# JSON output
polyv-live-cli donate list -c "3151318" \
  --start 1615772426000 \
  --end 1615858826000 \
  -o json
```

**Output (table format):**
```
Found 50 donate records
Page: 1, Size: 10
Total pages: 5
┌─────────────────┬────────────────────┬──────────────┬────────┬────────────────────┬────────────┬─────────────────────────┐
│ User ID         │ Nickname           │ Type         │ Amount │ Name               │ Session ID │ Time                    │
├─────────────────┼────────────────────┼──────────────┼────────┼────────────────────┼────────────┼─────────────────────────┤
│ user123         │ Test User          │ Props/Points │ 6.66   │ Flower             │ session001 │ 3/15/2021, 10:00:26 AM  │
│ user456         │ Another User       │ Cash         │ 8.88   │ Cash               │ session001 │ 3/15/2021, 10:16:66 AM  │
└─────────────────┴────────────────────┴──────────────┴────────┴────────────────────┴────────────┴─────────────────────────┘
```

**Output Columns:**
| Column | Description |
|--------|-------------|
| User ID | Viewer user ID |
| Nickname | Viewer nickname |
| Type | Donation type: Props/Points (type 1) or Cash (type 2) |
| Amount | Donation amount |
| Name | Gift name or "Cash" |
| Session ID | Live session ID |
| Time | Donation timestamp |

---

## API Endpoints

| Command | API Endpoint | Method |
|---------|--------------|--------|
| `donate config get` | `/live/v4/channel/donate/get` | GET |
| `donate config update` | `/live/v4/channel/donate/update` | POST |
| `donate list` | [REDACTED_SECRET] | GET |

## Output Formats

All commands support two output formats:

- **table** (default): Human-readable formatted table
- **json**: Machine-readable JSON format for scripting

## Error Handling

The commands provide user-friendly error messages for common issues:

- Missing required parameters (channelId, start/end timestamps)
- Invalid parameter values (Y/N flags, numeric values)
- Invalid time ranges (start must be before end)
- API authentication errors
- API rate limiting

## Related Commands

- [`lottery`](lottery.md) - Manage lottery activities
- [`checkin`](checkin.md) - Manage check-in activities
- [`qa`](qa-questionnaire.md) - Manage Q&A and questionnaires


path: references/streaming.md
content: # 推流操作

## 概述

推流命令用于管理直播推流操作，包括获取推流凭证、开始/结束直播、监控直播质量等。

## 获取推流凭证

### 基本使用

```bash
# 获取RTMP地址和推流密钥
npx polyv-live-cli@latest stream get-key -c 3151318

# 输出：
# RTMP地址: rtmp://push.polyv.net/live/
# 推流密钥: 3151318-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

### JSON输出（用于脚本）

```bash
npx polyv-live-cli@latest stream get-key -c 3151318 -o json

# {
#   "rtmpUrl": "rtmp://push.polyv.net/live/",
#   "streamKey": "3151318-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
#   "fullRtmpUrl": "rtmp://push.polyv.net/live/3151318-xxxx-xxxx..."
# }
```

## 开始和结束直播

### 开始直播

```bash
# 开始直播推流
npx polyv-live-cli@latest stream start -c 3151318

# 输出：
# ✅ 直播已开始
# 频道ID: 3151318
# 状态: 直播中
```

### 结束直播

```bash
# 结束直播
npx polyv-live-cli@latest stream stop -c 3151318

# 输出：
# ✅ 直播已结束
# 频道ID: 3151318
# 状态: 已结束
```

## 直播状态

### 单次状态查询

```bash
npx polyv-live-cli@latest stream status -c 3151318

# 输出包含：
# 状态: 直播中
# 时长: 00:45:32
# 帧率: 30
# 码率: 2500 kbps
# 观看人数: 127
```

### 持续监控

```bash
# 监控模式（每5秒刷新）
npx polyv-live-cli@latest stream status -c 3151318 -w

# 按 Ctrl+C 停止
```

### JSON输出

```bash
npx polyv-live-cli@latest stream status -c 3151318 -o json

# {
#   "status": "live",
#   "duration": 2732,
#   "fps": 30,
#   "bandwidth": 2500,
#   "viewerCount": 127
# }
```

## 推送视频文件

### 基本推送

```bash
# 推送本地视频文件到频道
# 需要安装 FFmpeg
npx polyv-live-cli@latest stream push -c 3151318 -f /path/to/video.mp4
```

### 带质量验证

```bash
# 推送并实时验证质量
npx polyv-live-cli@latest stream push \
  -c 3151318 \
  -f video.mp4 \
  --verify \
  --verification-interval 5 \
  --quality-threshold 20
```

### 显示观众链接

```bash
# 推送时显示观众观看链接
npx polyv-live-cli@latest stream push -c 3151318 -f video.mp4 --show-viewer-links
```

## 直播质量验证

### 基本验证

```bash
# 验证直播质量（60秒）
npx polyv-live-cli@latest stream verify -c 3151318

# 输出包含：
# ✅ 直播质量报告
# 验证时长: 60秒
# 平均帧率: 29.5
# 平均码率: 2450 kbps
# 质量评分: 95%
```

### 扩展验证

```bash
# 2分钟验证，每5秒检测一次
npx polyv-live-cli@latest stream verify -c 3151318 -d 120 -i 5
```

### 保存报告

```bash
# 保存验证报告到文件
npx polyv-live-cli@latest stream verify -c 3151318 -s report.json -o json
```

### 验证选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-d, --duration` | 验证时长（秒） | 60 |
| `-i, --interval` | 检测间隔（秒） | 10 |
| `-t, --quality-threshold` | 帧率警告阈值 | 15 |
| `--show-viewer-links` | 显示观众链接 | false |
| `-s, --save-report` | 保存报告到文件 | - |
| `-o, --output` | 输出格式 | table |

## 实时监控面板

### 基本监控

```bash
# 实时监控面板
npx polyv-live-cli@latest stream monitor -c 3151318

# 面板显示：
# ┌─────────────────────────────────────┐
# │ 📺 直播监控面板                      │
# ├─────────────────────────────────────┤
# │ 状态: 🔴 直播中                      │
# │ 时长: 00:32:15                      │
# │ 帧率: 30 | 码率: 2500 kbps          │
# │ 观看人数: 127                        │
# └─────────────────────────────────────┘
```

### 启用告警

```bash
# 启用质量告警
npx polyv-live-cli@latest stream monitor -c 3151318 -r 3 --alerts

# 以下情况会告警：
# - 帧率低于阈值
# - 码率波动较大
# - 直播不稳定
```

### 监控选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-r, --refresh` | 刷新间隔（秒） | 5 |
| `--alerts` | 启用质量告警 | false |
| `-o, --output` | 输出格式 | table |

## 配合 OBS Studio 使用

### 步骤1：获取推流凭证

```bash
npx polyv-live-cli@latest stream get-key -c 3151318 -o json
```

### 步骤2：配置 OBS

1. 打开 OBS Studio
2. 进入 **设置** → **推流**
3. 将 **服务** 设置为 "自定义"
4. 将 **RTMP地址** 复制到 **服务器** 字段
5. 将 **推流密钥** 复制到 **串流密钥** 字段
6. 点击 **确定**

### 步骤3：开始直播

```bash
# 在保利威平台开始直播
npx polyv-live-cli@latest stream start -c 3151318

# 在 OBS 中点击"开始推流"

# 监控直播状态
npx polyv-live-cli@latest stream status -c 3151318 -w
```

### 步骤4：结束直播

```bash
# 先在 OBS 中停止推流

# 然后在保利威平台结束直播
npx polyv-live-cli@latest stream stop -c 3151318
```

## 配合 FFmpeg 使用

### 直接使用 FFmpeg 推流

```bash
# 先获取推流凭证
npx polyv-live-cli@latest stream get-key -c 3151318 -o json

# 使用 FFmpeg 推流
ffmpeg -re -i video.mp4 \
  -c:v libx264 -c:a aac \
  -f flv "rtmp://push.polyv.net/live/推流密钥"
```

### 或使用内置推送命令

```bash
# 更简单 - CLI自动处理
npx polyv-live-cli@latest stream push -c 3151318 -f video.mp4 --verify
```

## 直播状态说明

| 状态 | 说明 |
|------|------|
| `live` | 正在直播 |
| `waiting` | 频道已创建，未开始 |
| `stopped` | 直播已结束 |
| `error` | 直播出错 |

## 故障排除

### "FFmpeg not found"（未找到FFmpeg）

安装 FFmpeg：
```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
# 从 https://ffmpeg.org/download.html 下载
```

### "Channel must be in live state"（频道必须处于直播状态）

- 先开始直播：`npx polyv-live-cli@latest stream start -c <频道ID>`
- 确认频道已激活：`npx polyv-live-cli@latest channel get -c <频道ID>`

### 帧率过低警告

- 检查网络带宽
- 在编码器中降低视频质量
- 使用有线网络代替WiFi


path: references/qa-questionnaire.md
content: # 问答问卷管理

本文档详细介绍保利威直播 CLI 的问答卡和问卷管理命令。

## 命令概览

```bash
# 问答卡命令
npx polyv-live-cli@latest qa <子命令> [选项]

# 问卷命令
npx polyv-live-cli@latest questionnaire <子命令> [选项]
```

---

## 问答卡命令 (QA)

问答卡用于在直播过程中发起答题互动。

### qa send - 发送问答卡

向指定频道发送一个问答卡（答题卡）。

```bash
npx polyv-live-cli@latest qa send -c <频道ID> --question-id <问题ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |
| `--question-id <id>` | 问答卡 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `--duration <秒数>` | 答题限时（1-99秒） |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 发送问答卡
npx polyv-live-cli@latest qa send -c 3151318 --question-id gv0uf9s5v7

# 发送带30秒限时
npx polyv-live-cli@latest qa send -c 3151318 --question-id gv0uf9s5v7 --duration 30

# JSON 格式输出
npx polyv-live-cli@latest qa send -c 3151318 --question-id gv0uf9s5v7 -o json
```

---

### qa list - 查询问答卡列表

获取频道的所有问答卡列表。

```bash
npx polyv-live-cli@latest qa list -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 查询问答卡列表
npx polyv-live-cli@latest qa list -c 3151318

# JSON 格式输出
npx polyv-live-cli@latest qa list -c 3151318 -o json
```

#### 表格输出字段

| 字段 | 说明 |
|------|------|
| Question ID | 问答卡 ID |
| Name | 问题名称 |
| Type | 类型：R（单选）、C（多选）、S（评分）、V（投票） |
| Status | 状态：draft（草稿）、send（已发送）、delete（已删除） |
| Times | 发送次数 |

---

### qa stop - 停止问答卡

停止正在进行的问答卡，并获取答题统计结果。

```bash
npx polyv-live-cli@latest qa stop -c <频道ID> --question-id <问题ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |
| `--question-id <id>` | 问答卡 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 停止问答卡
npx polyv-live-cli@latest qa stop -c 3151318 --question-id gv0uf9s5v7

# JSON 格式输出
npx polyv-live-cli@latest qa stop -c 3151318 --question-id gv0uf9s5v7 -o json
```

#### 输出信息

停止后会显示答题统计：
- **Correct Answer**: 正确答案
- **Total Respondents**: 答题总人数
- **Correct**: 答对人数
- **Incorrect**: 答错人数
- **Option Distribution**: 各选项选择人数

---

## 问卷命令 (Questionnaire)

问卷用于在直播过程中收集观众反馈。

### questionnaire create - 创建问卷

为指定频道创建一个新问卷。

```bash
npx polyv-live-cli@latest questionnaire create -c <频道ID> --title <标题> --questions '<JSON数组>' [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |
| `--title <标题>` | 问卷标题 |
| `--questions <json>` | 题目数组（JSON 字符串） |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `--custom-questionnaire-id <id>` | 自定义问卷 ID |
| `--auto-publish-time <时间戳>` | 自动发布时间（时间戳） |
| `--auto-end-time <时间戳>` | 自动结束时间（时间戳） |
| `--privacy-enabled` | 启用隐私模式 |
| `--privacy-content <文本>` | 隐私协议内容 |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 题目 JSON 格式

```json
[
  {
    "name": "问题内容",
    "type": "R",
    "options": ["选项1", "选项2"],
    "required": "Y",
    "scoreEnabled": "Y",
    "score": 10,
    "answer": "A"
  }
]
```

#### 题目类型

| 类型 | 说明 | 必需字段 |
|------|------|---------|
| `R` | 单选题 | `options` |
| `C` | 多选题 | `options` |
| `Q` | 填空题 | - |
| `J` | 判断题 | - |
| `X` | 评分题 | - |

#### 示例

```bash
# 创建简单问卷（单选题）
npx polyv-live-cli@latest questionnaire create -c 3151318 --title "满意度调查" \
  --questions '[{"name":"您的性别?","type":"R","options":["男","女"],"required":"Y"}]'

# 创建带评分题的问卷
npx polyv-live-cli@latest questionnaire create -c 3151318 --title "服务评价" \
  --questions '[{"name":"您对我们的服务满意吗?","type":"X","required":"Y"}]'

# 创建带自定义 ID 的问卷
npx polyv-live-cli@latest questionnaire create -c 3151318 --title "调查问卷" \
  --questions '[...]' --custom-questionnaire-id "survey-001"

# JSON 格式输出
npx polyv-live-cli@latest questionnaire create -c 3151318 --title "调查" \
  --questions '[...]' -o json
```

---

### questionnaire list - 查询问卷列表

分页查询频道的问卷列表。

```bash
npx polyv-live-cli@latest questionnaire list -c <频道ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `--page <数字>` | 页码（默认 1） |
| `--size <数字>` | 每页数量（默认 20） |
| `--session-id <id>` | 按场次 ID 筛选 |
| `--start-date <日期>` | 开始日期（格式：yyyy-MM-dd） |
| `--end-date <日期>` | 结束日期（格式：yyyy-MM-dd） |
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

> 注意：日期范围默认为最近 7 天。

#### 示例

```bash
# 查询问卷列表
npx polyv-live-cli@latest questionnaire list -c 3151318

# 分页查询
npx polyv-live-cli@latest questionnaire list -c 3151318 --page 1 --size 20

# 按场次筛选
npx polyv-live-cli@latest questionnaire list -c 3151318 --session-id fwly13xczv

# 按日期范围筛选
npx polyv-live-cli@latest questionnaire list -c 3151318 --start-date 2024-01-01 --end-date 2024-01-31

# JSON 格式输出
npx polyv-live-cli@latest questionnaire list -c 3151318 -o json
```

#### 表格输出字段

| 字段 | 说明 |
|------|------|
| Questionnaire ID | 问卷 ID |
| Title | 问卷标题 |
| Last Modified | 最后修改时间 |
| Users | 答题人数 |

---

### questionnaire detail - 查询问卷详情

获取指定问卷的详细信息，包括题目列表。

```bash
npx polyv-live-cli@latest questionnaire detail -c <频道ID> --questionnaire-id <问卷ID> [选项]
```

#### 必需选项

| 选项 | 说明 |
|------|------|
| `-c, --channel-id <id>` | 频道 ID |
| `--questionnaire-id <id>` | 问卷 ID |

#### 可选选项

| 选项 | 说明 |
|------|------|
| `-o, --output <格式>` | 输出格式：table（默认）或 json |

#### 示例

```bash
# 查询问卷详情
npx polyv-live-cli@latest questionnaire detail -c 3151318 --questionnaire-id fs9v59nq4u

# JSON 格式输出
npx polyv-live-cli@latest questionnaire detail -c 3151318 --questionnaire-id fs9v59nq4u -o json
```

#### 输出信息

- **Channel ID**: 频道 ID
- **Questionnaire ID**: 问卷 ID
- **Name**: 问卷名称
- **Status**: 问卷状态
- **Questions**: 题目列表
  - Question ID: 题目 ID
  - Name: 题目内容
  - Type: 题目类型
  - Required: 是否必答
  - Score Enabled: 是否计分

---

## 常见工作流程

### 1. 发起快速答题

```bash
# 1. 查看可用的问答卡
npx polyv-live-cli@latest qa list -c 3151318

# 2. 发送问答卡
npx polyv-live-cli@latest qa send -c 3151318 --question-id gv0uf9s5v7 --duration 30

# 3. 停止答题并查看结果
npx polyv-live-cli@latest qa stop -c 3151318 --question-id gv0uf9s5v7
```

### 2. 创建并发布问卷

```bash
# 1. 创建问卷
npx polyv-live-cli@latest questionnaire create -c 3151318 --title "课后反馈" \
  --questions '[{"name":"课程难度如何?","type":"R","options":["简单","适中","困难"],"required":"Y"}]'

# 2. 查询问卷列表确认创建成功
npx polyv-live-cli@latest questionnaire list -c 3151318

# 3. 查看问卷详情
npx polyv-live-cli@latest questionnaire detail -c 3151318 --questionnaire-id <问卷ID>
```

### 3. 查看直播场次问卷统计

```bash
# 按场次查询问卷
npx polyv-live-cli@latest questionnaire list -c 3151318 --session-id <场次ID>

# 导出为 JSON 便于分析
npx polyv-live-cli@latest questionnaire list -c 3151318 --session-id <场次ID> -o json > survey_results.json
```

---

## 错误处理

| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| `channelId is required` | 未指定频道 ID | 使用 `-c` 参数指定频道 |
| `questionId is required` | 未指定问答卡 ID | 使用 `--question-id` 参数 |
| `questionnaireId is required` | 未指定问卷 ID | 使用 `--questionnaire-id` 参数 |
| `title is required` | 未指定问卷标题 | 使用 `--title` 参数 |
| `questions is required` | 未提供题目数组 | 使用 `--questions` 参数 |
| `Invalid JSON format for questions` | 题目 JSON 格式错误 | 检查 JSON 格式是否正确 |
| `duration must be between 1 and 99` | 答题时长超出范围 | 设置 1-99 之间的值 |
| `Invalid startDate format` | 日期格式错误 | 使用 yyyy-MM-dd 格式 |

---

## API 参考

相关 API 文档：
- [发送答题卡](https://help.polyv.net/#/live/v4/api/interact/question/send)
- [查询答题卡列表](https://help.polyv.net/#/live/v3/api/interact/question/list)
- [停止答题卡](https://help.polyv.net/#/live/v4/api/interact/question/stop)
- [创建问卷](https://help.polyv.net/#/live/v4/api/interact/questionnaire/save)
- [查询问卷列表](https://help.polyv.net/#/live/v3/api/interact/questionnaire/list)
- [查询问卷详情](https://help.polyv.net/#/live/v3/api/interact/questionnaire/detail)


path: references/monitor.md
content: # 直播监控

## 概述

监控命令提供直播实时监控面板，用于查看直播状态、观众数据和推流质量。

## 启动监控面板

```bash
# 启动默认监控面板
npx polyv-live-cli@latest monitor

# 设置刷新间隔（秒）
npx polyv-live-cli@latest monitor -r 3

# 使用紧凑布局
npx polyv-live-cli@latest monitor -l compact

# 使用暗色主题
npx polyv-live-cli@latest monitor -t dark

# 使用配置文件
npx polyv-live-cli@latest monitor -c ./monitor-config.json
```

### 监控选项

| 选项 | 说明 | 可选值 |
|------|------|--------|
| `-r, --refresh` | 刷新间隔（秒） | 默认5秒 |
| `-l, --layout` | 面板布局 | default, compact, single |
| `-t, --theme` | 颜色主题 | default, dark |
| `-c, --config` | 配置文件路径 | - |
| `-o, --output` | 输出格式 | table（默认）/ json |
| `-v, --verbose` | 详细日志 | 标志 |
| `-d, --debug` | 调试模式 | 标志 |

## 查看监控状态

```bash
# 查看当前监控状态
npx polyv-live-cli@latest monitor status

# JSON输出
npx polyv-live-cli@latest monitor status -o json
```

## 管理配置

### 查看当前配置

```bash
npx polyv-live-cli@latest monitor config

# JSON输出
npx polyv-live-cli@latest monitor config -o json
```

### 导出配置

```bash
# 导出配置到文件
npx polyv-live-cli@latest monitor export ./my-monitor-config.json
```

### 导入配置

```bash
# 从文件导入配置
npx polyv-live-cli@latest monitor import ./my-monitor-config.json
```

## 列出可用选项

### 可用布局

```bash
npx polyv-live-cli@latest monitor layouts

# 输出：
# ┌───────────┬────────────────────────────┐
# │ Layout    │ Description                │
# ├───────────┼────────────────────────────┤
# │ default   │ 标准布局，显示所有面板     │
# │ compact   │ 紧凑布局，适合小屏幕       │
# │ single    │ 单面板布局，专注单一指标   │
# └───────────┴────────────────────────────┘
```

### 可用主题

```bash
npx polyv-live-cli@latest monitor themes

# 输出：
# ┌───────────┬────────────────────────────┐
# │ Theme     │ Description                │
# ├───────────┼────────────────────────────┤
# │ default   │ 浅色主题                   │
# │ dark      │ 暗色主题                   │
# └───────────┴────────────────────────────┘
```

## 兼容性测试

```bash
# 测试终端兼容性
npx polyv-live-cli@latest monitor test

# 输出包含：
# ✅ 终端尺寸: 120x30
# ✅ 颜色支持: 256色
# ✅ Unicode支持: 是
```

## 配置文件格式

配置文件使用JSON格式：

```json
{
  "refreshInterval": 5,
  "layout": "default",
  "theme": "dark",
  "panels": [
    "stream",
    "viewers",
    "engagement"
  ],
  "alerts": {
    "enabled": true,
    "lowBitrate": 500,
    "highLatency": 3000,
    "viewerDrop": 10
  }
}
```

### 配置字段说明

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `refreshInterval` | 刷新间隔（秒） | 5 |
| `layout` | 面板布局 | default |
| `theme` | 颜色主题 | default |
| `panels` | 显示的面板 | 全部 |
| `alerts.enabled` | 启用告警 | true |
| `alerts.lowBitrate` | 低码率告警阈值（kbps） | 500 |
| `alerts.highLatency` | 高延迟告警阈值（ms） | 3000 |
| `alerts.viewerDrop` | 观众下降告警阈值（%） | 10 |

## 常用工作流程

### 启动直播监控

```bash
# 1. 启动频道直播
npx polyv-live-cli@latest stream start -c 3151318

# 2. 在另一个终端启动监控
npx polyv-live-cli@latest monitor -r 3 -t dark
```

### 配置监控告警

```bash
# 1. 创建配置文件
cat > monitor-alerts.json << 'EOF'
{
  "refreshInterval": 3,
  "layout": "compact",
  "alerts": {
    "enabled": true,
    "lowBitrate": 800,
    "highLatency": 2000,
    "viewerDrop": 5
  }
}
EOF

# 2. 使用配置启动监控
npx polyv-live-cli@latest monitor -c monitor-alerts.json
```

### 保存和恢复配置

```bash
# 导出当前配置
npx polyv-live-cli@latest monitor export ./saved-config.json

# 之后恢复配置
npx polyv-live-cli@latest monitor import ./saved-config.json
```

## 面板布局说明

### default（默认布局）

```
┌─────────────────────────────────────────────────────────┐
│ 直播状态面板                              │
├─────────────────────────────────────────────────────────┤
│ 观众数据面板                              │
├─────────────────────────────────────────────────────────┤
│ 互动统计面板                           │
└─────────────────────────────────────────────────────────┘
```

### compact（紧凑布局）

```
┌────────────────────┬────────────────────┐
│ Stream             │ Viewers            │
├────────────────────┴────────────────────┤
│ Engagement                               │
└─────────────────────────────────────────┘
```

### single（单面板布局）

```
┌─────────────────────────────────────────┐
│                                         │
│         Stream Status Panel             │
│                                         │
└─────────────────────────────────────────┘
```

## 故障排除

### "终端不支持"

- 确保终端支持ANSI颜色
- 尝试使用 `monitor test` 检测兼容性
- 使用不支持Unicode的终端时，部分图标可能显示异常

### "刷新间隔过快"

- 最小刷新间隔为1秒
- 建议使用3-5秒间隔以避免API限流
- 网络较慢时可增加刷新间隔

### "配置文件加载失败"

- 检查JSON格式是否正确
- 确保文件路径存在
- 使用 `monitor config` 查看当前配置验证格式


path: references/viewer.md
content: # 观众信息查询命令

## 概述

观众信息查询命令用于通过 CLI 查询直播间观众数据，支持获取单个观众详情和分页查询观众列表。

## 命令列表

| 命令 | 说明 |
|------|------|
| `viewer get` | 获取单个观众详情 |
| `viewer list` | 分页查询观众列表 |

## viewer get - 获取观众详情

获取指定观众的详细信息，包括昵称、手机号、来源、观看时长等。

### 语法

```bash
npx polyv-live-cli@latest viewer get -i <观众ID> [-o table|json]
```

### 参数

| 参数 | 简写 | 必填 | 说明 |
|------|------|------|------|
| `--viewer-id` | `-i` | 是 | 观众唯一 ID（viewerUnionId） |
| `--output` | `-o` | 否 | 输出格式：`table`（默认）或 `json` |

### 示例

```bash
# 获取观众详情（表格格式）
npx polyv-live-cli@latest viewer get -i "2_v378gn997yovtl3p8h77db9e224t6hg9"

# 获取观众详情（JSON格式）
npx polyv-live-cli@latest viewer get -i "2_v378gn997yovtl3p8h77db9e224t6hg9" -o json

# 使用完整参数名
npx polyv-live-cli@latest viewer get --viewer-id "2_v378gn997yovtl3p8h77db9e224t6hg9" --output json
```

### 输出字段

| 字段 | 说明 |
|------|------|
| Viewer ID | 观众唯一标识 |
| Nickname | 观众昵称 |
| Mobile | 手机号 |
| Source | 来源类型（IMPORT/WX/MOBILE） |
| Name | 采集姓名 |
| Email | 邮箱 |
| Area | 地址 |
| Watch Duration | 观看时长 |
| Watch Channels | 观看频道数 |
| Created Time | 创建时间 |

## viewer list - 查询观众列表

分页查询观众列表，支持按来源、手机号、邮箱、地址等条件过滤。

### 语法

```bash
npx polyv-live-cli@latest viewer list [选项]
```

### 参数

| 参数 | 简写 | 必填 | 说明 |
|------|------|------|------|
| `--source` | - | 否 | 来源过滤：`IMPORT`（导入）、`WX`（微信）、`MOBILE`（手机） |
| `--mobile` | - | 否 | 按手机号过滤 |
| `--email` | - | 否 | 按邮箱过滤 |
| `--area` | - | 否 | 按地址过滤 |
| `--page` | - | 否 | 页码，默认 1 |
| `--size` | - | 否 | 每页数量，默认 10，最大 1000 |
| `--output` | `-o` | 否 | 输出格式：`table`（默认）或 `json` |

### 示例

```bash
# 查询所有观众（默认分页）
npx polyv-live-cli@latest viewer list

# 分页查询
npx polyv-live-cli@latest viewer list --page 1 --size 20

# 按来源过滤
npx polyv-live-cli@latest viewer list --source IMPORT
npx polyv-live-cli@latest viewer list --source WX
npx polyv-live-cli@latest viewer list --source MOBILE

# 按手机号过滤
npx polyv-live-cli@latest viewer list --mobile "13800138000"

# 按邮箱过滤
npx polyv-live-cli@latest viewer list --email "[REDACTED_SECRET]"

# 按地址过滤
npx polyv-live-cli@latest viewer list --area "北京"

# 组合过滤条件
npx polyv-live-cli@latest viewer list --source IMPORT --page 1 --size 50 -o json

# JSON 格式输出
npx polyv-live-cli@latest viewer list --source WX -o json
```

### 输出字段

| 字段 | 说明 |
|------|------|
| Viewer ID | 观众唯一标识（截断显示） |
| Nickname | 观众昵称 |
| Mobile | 手机号 |
| Source | 来源类型 |
| Watch Duration | 观看时长 |
| Channels | 观看频道数 |
| Created Time | 创建时间 |

### JSON 输出格式

```json
{
  "pageNumber": 1,
  "pageSize": 10,
  "totalPages": 5,
  "totalItems": 47,
  "contents": [
    {
      "viewerUnionId": "2_v378gn997yovtl3p8h77db9e224t6hg9",
      "nickname": "张三",
      "mobile": "13800138000",
      "source": "IMPORT",
      "name": "张三",
      "email": "[REDACTED_SECRET]",
      "area": "北京",
      "watchDuration": 3600,
      "watchChannelCount": 5,
      "createTime": 1704067200000
    }
  ]
}
```

## 观众来源类型

| 值 | 说明 |
|----|------|
| `IMPORT` | 批量导入的观众 |
| `WX` | 微信授权登录的观众 |
| `MOBILE` | 手机号登录的观众 |

## 错误处理

| 错误 | 说明 |
|------|------|
| `viewerId is required` | 未提供观众 ID |
| `page must be a positive integer` | 页码必须为正整数 |
| `size must be a positive integer` | 每页数量必须为正整数 |
| `size must not exceed 1000` | 每页数量不能超过 1000 |
| `output must be either "table" or "json"` | 输出格式无效 |

## API 参考

- 获取观众详情：`GET /live/v4/user/viewer-record/get`
- 获取观众列表：`GET /live/v4/user/viewer-record/list`

## 相关命令

- [聊天消息管理](chat-management.md) - 管理直播间聊天消息
- [签到管理](checkin.md) - 管理直播签到
- [抽奖管理](lottery.md) - 管理抽奖活动


path: references/lottery.md
content: # 抽奖管理

## 概述

抽奖命令用于在直播过程中创建和管理抽奖活动，包括创建、查询、更新、删除抽奖活动，以及查询中奖用户和抽奖记录。

## 创建抽奖

```bash
# 创建无条件抽奖（默认）
npx polyv-live-cli@latest lottery create -c 3151318 --name "幸运抽奖" --type none --amount 3 --prize "神秘礼品"

# 创建邀请抽奖（观众邀请3人参与）
npx polyv-live-cli@latest lottery create -c 3151318 --name "邀请抽奖" --type invite --amount 5 --prize "优惠券" --duration 30 --invite-num 3

# 创建观看时长抽奖（观看10分钟后可参与）
npx polyv-live-cli@latest lottery create -c 3151318 --name "时长抽奖" --type duration --amount 2 --prize "红包" --duration 10

# 创建评论抽奖（发表评论后可参与）
npx polyv-live-cli@latest lottery create -c 3151318 --name "评论抽奖" --type comment --amount 3 --prize "积分" --duration 5

# 创建答题抽奖（回答问题后可参与）
npx polyv-live-cli@latest lottery create -c 3151318 --name "答题抽奖" --type question --amount 1 --prize "大奖" --duration 30

# JSON输出
npx polyv-live-cli@latest lottery create -c 3151318 --name "测试抽奖" --type none --amount 3 --prize "奖品" -o json
```

## 查询抽奖列表

```bash
# 查询频道所有抽奖活动
npx polyv-live-cli@latest lottery list -c 3151318

# 分页查询
npx polyv-live-cli@latest lottery list -c 3151318 --page 1 --size 20

# JSON输出
npx polyv-live-cli@latest lottery list -c 3151318 -o json
```

## 查询抽奖详情

```bash
# 获取指定抽奖活动详情
npx polyv-live-cli@latest lottery get -c 3151318 --id 20521

# JSON输出
npx polyv-live-cli@latest lottery get -c 3151318 --id 20521 -o json
```

## 更新抽奖

```bash
# 更新抽奖活动配置
npx polyv-live-cli@latest lottery update -c 3151318 --id 20521 --name "更新后的抽奖" --amount 5 --prize "新奖品"

# JSON输出
npx polyv-live-cli@latest lottery update -c 3151318 --id 20521 --amount 10 -o json
```

## 删除抽奖

```bash
# 删除指定抽奖活动
npx polyv-live-cli@latest lottery delete -c 3151318 --id 20521
```

## 查询中奖用户

```bash
# 查询中奖用户列表
npx polyv-live-cli@latest lottery winners -c 3151318 --lottery-id fv3mao43u6

# 分页查询
npx polyv-live-cli@latest lottery winners -c 3151318 --lottery-id fv3mao43u6 --page 1 --limit 20

# JSON输出
npx polyv-live-cli@latest lottery winners -c 3151318 --lottery-id fv3mao43u6 -o json
```

## 查询抽奖记录

```bash
# 查询频道抽奖记录
npx polyv-live-cli@latest lottery records -c 3151318

# 按场次筛选
npx polyv-live-cli@latest lottery records -c 3151318 --session-id fwly13xczv

# 按时间范围筛选
npx polyv-live-cli@latest lottery records -c 3151318 --start-time 1615772426000 --end-time 1615773566000

# 分页查询
npx polyv-live-cli@latest lottery records -c 3151318 --page 1 --limit 20

# JSON输出
npx polyv-live-cli@latest lottery records -c 3151318 -o json
```

## 命令选项

### lottery create

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--name` | 抽奖活动名称（必填） | - |
| `--type` | 抽奖条件类型（必填） | none/invite/duration/comment/question |
| `--amount` | 中奖人数（必填） | 数字 |
| `--prize` | 奖品名称（必填） | - |
| `--duration` | 抽奖时长（分钟） | 数字 |
| `--invite-num` | 邀请人数（仅invite类型） | 数字 |
| `--receive-info` | 中奖者信息收集配置 | JSON字符串 |
| `-o, --output` | 输出格式 | table（默认）/ json |

### lottery list

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--page` | 页码 | 数字，默认1 |
| `--size` | 每页数量 | 数字，默认10 |
| `-o, --output` | 输出格式 | table（默认）/ json |

### lottery get

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--id` | 抽奖活动ID（必填） | - |
| `-o, --output` | 输出格式 | table（默认）/ json |

### lottery update

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--id` | 抽奖活动ID（必填） | - |
| `--name` | 新的抽奖活动名称 | - |
| `--amount` | 新的中奖人数 | 数字 |
| `--prize` | 新的奖品名称 | - |
| `-o, --output` | 输出格式 | table（默认）/ json |

### lottery delete

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--id` | 抽奖活动ID（必填） | - |

### lottery winners

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--lottery-id` | 抽奖ID（必填） | - |
| `--page` | 页码 | 数字，默认1 |
| `--limit` | 每页数量 | 数字，默认20 |
| `-o, --output` | 输出格式 | table（默认）/ json |

### lottery records

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--session-id` | 场次ID | - |
| `--start-time` | 开始时间（毫秒时间戳） | 数字 |
| `--end-time` | 结束时间（毫秒时间戳） | 数字 |
| `--page` | 页码 | 数字，默认1 |
| `--limit` | 每页数量 | 数字，默认20 |
| `-o, --output` | 输出格式 | table（默认）/ json |

## 抽奖条件类型说明

| 类型 | 说明 | 必需参数 |
|------|------|----------|
| `none` | 无条件抽奖（默认） | - |
| `invite` | 邀请好友参与 | `--invite-num`（邀请人数） |
| `duration` | 观看时长抽奖 | `--duration`（观看分钟数） |
| `comment` | 发表评论抽奖 | `--duration`（评论后分钟内） |
| `question` | 回答问题抽奖 | `--duration`（答题时长） |

## 输出格式

### Table 格式（默认）

抽奖列表示例：
```
┌──────────┬─────────────────────┬──────────┬────────┬────────┬───────────────────┐
│ ID       │ Name                │ Type     │ Status │ Amount │ Prize             │
├──────────┼─────────────────────┼──────────┼────────┼────────┼───────────────────┤
│ 20521    │ 幸运抽奖            │ none     │ ended  │ 3      │ 神秘礼品          │
│ 20522    │ 邀请抽奖            │ invite   │ active │ 5      │ 优惠券            │
└──────────┴─────────────────────┴──────────┴────────┴────────┴───────────────────┘
```

中奖用户示例：
```
┌────────────┬────────────┬─────────────┬─────────────────────┐
│ Viewer ID  │ Nickname   │ Winner Code │ Win Time            │
├────────────┼────────────┼─────────────┼─────────────────────┤
│ viewer123  │ Winner1    │ ABC123      │ 2024-03-19 10:00:00 │
└────────────┴────────────┴─────────────┴─────────────────────┘
```

### JSON 格式

使用 `-o json` 选项输出结构化JSON数据，便于脚本处理。

## 相关文档

- [频道管理](./channel-management.md) - 频道基础操作
- [签到管理](./checkin.md) - 签到互动功能
- [聊天管理](./chat-management.md) - 聊天消息管理


path: references/checkin.md
content: # 签到管理

## 概述

签到命令用于在直播过程中发起签到互动，查询签到记录和统计结果。

## 发起签到

```bash
# 立即发起签到
npx polyv-live-cli@latest checkin start -c 3151318

# 设置签到时长30秒
npx polyv-live-cli@latest checkin start -c 3151318 --limit-time 30

# 定时签到（13位时间戳）
npx polyv-live-cli@latest checkin start -c 3151318 --limit-time 60 --delay-time 1700734800000

# 自定义签到提示语
npx polyv-live-cli@latest checkin start -c 3151318 --message "请各位学员签到"

# 强制签到模式
npx polyv-live-cli@latest checkin start -c 3151318 --force
```

### 签到选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--limit-time` | 签到时长（秒） | 0-86400，0表示立即 |
| `--delay-time` | 定时签到时间 | 13位时间戳 |
| `--message` | 签到提示语 | 文本 |
| `--force` | 强制签到模式 | 标志（无需值） |
| `-o, --output` | 输出格式 | table（默认）/ json |

### JSON输出

```bash
npx polyv-live-cli@latest checkin start -c 3151318 -o json
```

## 查询签到记录

查询已签到的用户列表。

```bash
# 查询所有签到记录
npx polyv-live-cli@latest checkin list -c 3151318

# 分页查询
npx polyv-live-cli@latest checkin list -c 3151318 --page 1 --size 20

# 按日期筛选
npx polyv-live-cli@latest checkin list -c 3151318 --date 2024-01-15

# 按场次筛选
npx polyv-live-cli@latest checkin list -c 3151318 --session-id fwly13xczv

# JSON输出
npx polyv-live-cli@latest checkin list -c 3151318 -o json
```

### 查询选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--page` | 页码 | 数字，默认1 |
| `--size` | 每页数量 | 数字，默认10 |
| `--date` | 筛选日期 | yyyy-MM-dd |
| `--session-id` | 场次ID | - |
| `-o, --output` | 输出格式 | table（默认）/ json |

## 查询签到详情

获取特定签到的详细结果，包括已签到和未签到的用户。

```bash
# 查询签到详情
npx polyv-live-cli@latest checkin result -c 3151318 --checkin-id db14ef80-81b8-11eb-b114-e7477b

# JSON输出
npx polyv-live-cli@latest checkin result -c 3151318 --checkin-id db14ef80-81b8-11eb-b114-e7477b -o json
```

### 详情选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--checkin-id` | 签到ID（必填） | - |
| `-o, --output` | 输出格式 | table（默认）/ json |

## 查询签到发起记录

按时间范围查询签到发起记录。

```bash
# 查询最近7天的签到记录（默认）
npx polyv-live-cli@latest checkin sessions -c 3151318

# 指定日期范围
npx polyv-live-cli@latest checkin sessions -c 3151318 --start-date 2024-01-01 --end-date 2024-01-31

# JSON输出
npx polyv-live-cli@latest checkin sessions -c 3151318 --start-date 2024-01-01 --end-date 2024-01-31 -o json
```

### 场次选项

| 选项 | 说明 | 格式 |
|------|------|------|
| `-c, --channel-id` | 频道ID（必填） | - |
| `--start-date` | 开始日期 | yyyy-MM-dd，默认7天前 |
| `--end-date` | 结束日期 | yyyy-MM-dd，默认今天 |
| `-o, --output` | 输出格式 | table（默认）/ json |

> **注意**: 日期范围不能超过30天。

## 常用工作流程

### 课堂签到流程

```bash
# 1. 开始直播后发起签到
npx polyv-live-cli@latest checkin start -c 3151318 --limit-time 60 --message "同学们请签到"

# 2. 签到结束后查看结果
npx polyv-live-cli@latest checkin result -c 3151318 --checkin-id <签到ID>

# 3. 导出签到数据
npx polyv-live-cli@latest checkin result -c 3151318 --checkin-id <签到ID> -o json > checkin-result.json
```

### 课后统计

```bash
# 查询某天的所有签到记录
npx polyv-live-cli@latest checkin list -c 3151318 --date 2024-01-15 -o json

# 查询某月的签到发起记录
npx polyv-live-cli@latest checkin sessions -c 3151318 --start-date 2024-01-01 --end-date 2024-01-31
```

### 定时签到

```bash
# 计算定时签到时间戳（例如：2024-01-15 10:00:00）
# macOS/Linux
date -j -f "%Y-%m-%d %H:%M:%S" "2024-01-15 10:00:00" +%s000

# 发起定时签到
npx polyv-live-cli@latest checkin start -c 3151318 --limit-time 120 --delay-time 1705287600000
```

## 输出格式

### 表格格式（默认）

```
┌──────────────────────────────┬──────────┬─────────────────┐
│ Checkin ID                   │ Status   │ Checked Count   │
├──────────────────────────────┼──────────┼─────────────────┤
│ db14ef80-81b8-11eb-b114...   │ Active   │ 45              │
└──────────────────────────────┴──────────┴─────────────────┘
```

### JSON格式

```json
{
  "checkinId": "db14ef80-81b8-11eb-b114-e7477b",
  "channelId": "3151318",
  "status": "active",
  "checkedCount": 45,
  "uncheckedCount": 10,
  "limitTime": 60,
  "message": "请签到"
}
```

## 故障排除

### "签到发起失败"

- 确认频道正在直播中
- 检查是否有正在进行的签到（需先结束或等待超时）
- 使用 `--force` 参数强制发起新签到

### "无签到记录"

- 确认日期范围正确
- 检查频道ID是否正确
- 确认该时间段内有直播场次

### "日期范围超出限制"

- 日期范围不能超过30天
- 缩小查询日期范围后重试


path: references/playback.md
content: # 回放管理

## 概述

回放是直播录制的视频文件。可以查看、删除或合并回放视频。

## 回放列表

### 基本列表

```bash
npx polyv-live-cli@latest playback list -c 3151318

# 输出：
# 视频ID | 标题 | 时长 | 大小 | 创建时间
# vid001 | 第一场直播 | 01:30:45 | 1.2GB | 2024-06-15
# vid002 | 第二场直播 | 00:45:22 | 0.8GB | 2024-06-16
```

### JSON输出

```bash
npx polyv-live-cli@latest playback list -c 3151318 -o json
```

## 获取回放详情

```bash
# 表格格式
npx polyv-live-cli@latest playback get -c 3151318 --videoId vid001

# JSON格式
npx polyv-live-cli@latest playback get -c 3151318 --videoId vid001 -o json
```

### 回放信息包括

- 视频ID和标题
- 时长
- 文件大小
- 创建时间
- 播放地址
- 缩略图地址
- 状态

## 删除回放

```bash
# 带确认提示
npx polyv-live-cli@latest playback delete -c 3151318 --videoId vid001

# 强制删除
npx polyv-live-cli@latest playback delete -c 3151318 --videoId vid001 -f
```

## 合并回放

将多个回放视频合并为一个视频。

### 基本合并

```bash
npx polyv-live-cli@latest playback merge \
  -c 3151318 \
  --videoIds vid001 vid002 vid003

# 输出：
# ✅ 合并任务已开始
# 新视频ID: vid999
# 状态: 处理中
```

### 指定标题

```bash
npx polyv-live-cli@latest playback merge \
  -c 3151318 \
  --videoIds vid001 vid002 \
  --title "完整研讨会合集"
```

### JSON输出

```bash
npx polyv-live-cli@latest playback merge \
  -c 3151318 \
  --videoIds vid001 vid002 \
  -o json
```

## 常用工作流程

### 清理旧录像

```bash
# 列出旧录像
npx polyv-live-cli@latest playback list -c 3151318 -o json | \
  jq '.data[] | select(.createdAt < "2024-01-01")'

# 删除旧录像
for vid in $(npx polyv-live-cli@latest playback list -c 3151318 -o json | \
  jq -r '.data[] | select(.createdAt < "2024-01-01") | .videoId'); do
  npx polyv-live-cli@latest playback delete -c 3151318 --videoId "$vid" -f
done
```

### 合并多场直播录像

```bash
# 合并多天活动的所有录像
npx polyv-live-cli@latest playback merge \
  -c 3151318 \
  --videoIds vid001 vid002 vid003 vid004 \
  --title "完整会议录像"
```

### 导出播放地址

```bash
# 获取所有回放的播放地址
npx polyv-live-cli@latest playback list -c 3151318 -o json | \
  jq -r '.data[] | "\(.title): \(.playbackUrl)"'
```

## 回放状态

| 状态 | 说明 |
|------|------|
| `ready` | 可以播放 |
| `processing` | 正在处理 |
| `error` | 处理失败 |
| `merging` | 正在合并 |

## 故障排除

### "Playback not found"（回放不存在）

- 确认视频ID是否正确
- 检查回放是否属于该频道

### "Merge failed"（合并失败）

- 确保所有视频ID有效
- 检查视频是否都处于 `ready` 状态
- 尝试减少合并的视频数量

### "Playback still processing"（回放仍在处理中）

- 等待处理完成
- 检查状态：`npx polyv-live-cli@latest playback get -c <频道ID> --videoId <视频ID>`
- 处理通常每1小时内容需要1-5分钟


path: references/viewer-management.md
content: # Viewer Management Commands

Viewer information query and tag management commands for managing viewers.

## Commands

### View Viewer Commands

| Command | Description |
| ------- | ----------- |
| `viewer get` | Get single viewer details |
| `viewer list` | List viewers with pagination and filters |
| `viewer tag list` | List all viewer tags |
| `viewer tag add` | Add tags to viewers |
| `viewer tag remove` | Remove tags from viewers |

### viewer get

Get single viewer details by viewer unique ID.

```bash
polyv-live-cli viewer get -i <viewerID>
polyv-live-cli viewer get -i "2_v378gn997yovtl3p8h77db9e224t6hg9"
```

**Options:**
- `-i, --viewer-id <id>` - Viewer unique ID (required)
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# Get viewer details
polyv-live-cli viewer get -i "2_v378gn997yovtl3p8h77db9e224t6hg9"

# JSON output
polyv-live-cli viewer get -i "2_v378gn997yovtl3p8h77db9e224t6hg9" -o json
```

### viewer list

List viewers with pagination and filters.

```bash
polyv-live-cli viewer list
polyv-live-cli viewer list --page 1 --size 20
polyv-live-cli viewer list --source IMPORT
polyv-live-cli viewer list --mobile "13800138000"
polyv-live-cli viewer list --email "[REDACTED_SECRET]"
polyv-live-cli viewer list --area "Beijing"
```

**Options:**
- `--source <type>` - Filter by source: `IMPORT`, `WX`, `MOBILE`
- `--mobile <number>` - Filter by mobile number
- `--email <email>` - Filter by email
- `--area <area>` - Filter by area
- `--page <number>` - Page number (default: 1)
- `--size <number>` - Page size (default: 10, max: 1000)
- `-o, --output <format>` - Output format: `table` (default) or `json`

### viewer tag list

List all viewer tags with optional keyword filter and pagination.

```bash
polyv-live-cli viewer tag list
polyv-live-cli viewer tag list --keyword "VIP"
polyv-live-cli viewer tag list --page 1 --size 20
```

**Options:**
- `-k, --keyword <keyword>` - Keyword to search tag name
- `--page <number>` - Page number (default: 1)
- `--size <number>` - Page size (default: 10, max: 1000)
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# List all tags
polyv-live-cli viewer tag list

# Search tags by keyword
polyv-live-cli viewer tag list -k "VIP"

# Pagination
polyv-live-cli viewer tag list --page 1 --size 20

# JSON output
polyv-live-cli viewer tag list -o json
```

### viewer tag add

Add tags to viewers (supports batch operation)

```bash
polyv-live-cli viewer tag add -V <viewer-ids> -l <label-ids>
polyv-live-cli viewer tag add -V "viewer1" -l 1
polyv-live-cli viewer tag add -V "viewer1,viewer2,viewer3" -l 1,2,3
```

**Options:**
- `-V, --viewer-ids <ids>` - Comma-separated viewer IDs (required)
- `-l, --label-ids <ids>` - Comma-separated label IDs (required)
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# Add single tag to single viewer
polyv-live-cli viewer tag add -V "viewer1" -l 1

# Add multiple tags to single viewer
polyv-live-cli viewer tag add -V "viewer1" -l 1,2,3

# Batch: add tags to multiple viewers
polyv-live-cli viewer tag add -V "viewer1,viewer2,viewer3" -l 1,2

# JSON output
polyv-live-cli viewer tag add -V "viewer1" -l 1 -o json
```

### viewer tag remove

Remove tags from viewers (supports batch operation)

```bash
polyv-live-cli viewer tag remove -V <viewer-ids> -l <label-ids>
polyv-live-cli viewer tag remove -V "viewer1" -l 1
polyv-live-cli viewer tag remove -V "viewer1,viewer2" -l 1,2,3
```

**Options:**
- `-V, --viewer-ids <ids>` - Comma-separated viewer IDs (required)
- `-l, --label-ids <ids>` - Comma-separated label IDs (required)
- `-o, --output <format>` - Output format: `table` (default) or `json`

**Examples:**
```bash
# Remove single tag from single viewer
polyv-live-cli viewer tag remove -V "viewer1" -l 1

# Remove multiple tags from single viewer
polyv-live-cli viewer tag remove -V "viewer1" -l 1,2,3

# Batch: remove tags from multiple viewers
polyv-live-cli viewer tag remove -V "viewer1,viewer2" -l 1,2

# JSON output
polyv-live-cli viewer tag remove -V "viewer1" -l 1 -o json
```

## Output Formats

All viewer commands support the following output formats:

| Format | Description |
| ------ | ----------- |
| `table` | Default. Formatted table output for human reading |
| `json` | JSON format for programmatic use |

Specify with `-o table` or `-o json` option.

## Global Options

All viewer commands support these global options

| Option | Description |
| ------ | ----------- |
| `--appId <id>` | PolyV application ID |
| `--appSecret <secret>` | PolyV application secret |
| `--userId <id>` | PolyV user ID (optional) |
| `-a, --account <name>` | Use specified account |
| `--verbose` | Show verbose output |
| `--debug` | Enable debug mode |
| `--timeout <ms>` | API timeout (default: 30000) |

## Authentication

Before using viewer commands, ensure you authentication is configured:

1. **Session account**: `polyv-live-cli use <account-name>`
2. **Environment variables**: `POLYV_APP_ID`, `POLYV_APP_SECRET`
3. **Default account**: `polyv-live-cli account set-default <name>`
4. **Command-line options**: `--appId`, `--appSecret`, `--userId`

See [Authentication Guide](./authentication.md) for more details.

## Related Documentation

- [Authentication Guide](./authentication.md)
- [Channel Management](./channel-management.md)
- [API Documentation](https://help.polyv.net/#/live/api/)


path: references/products.md
content: # 商品管理

## 概述

商品是直播过程中可以展示和销售的项目。每个频道可以关联多个商品。

## 商品列表

### 基本列表

```bash
npx polyv-live-cli@latest product list -c 3151318

# 输出：
# 商品ID | 名称 | 价格 | 库存 | 状态
# prod001 | 商品A | ¥99.00 | 100 | 上架
# prod002 | 商品B | ¥199.00 | 50 | 上架
```

### JSON输出

```bash
npx polyv-live-cli@latest product list -c 3151318 -o json
```

## 添加商品

### 基本商品

```bash
npx polyv-live-cli@latest product add \
  -c 3151318 \
  --name "高级产品" \
  --price 99.00
```

### 完整选项

```bash
npx polyv-live-cli@latest product add \
  -c 3151318 \
  --name "豪华套餐" \
  --price 299.00 \
  --stock 100 \
  --description "高级豪华套餐，包含额外配件" \
  --image "https://example.com/product.jpg"
```

### 商品选项

| 选项 | 说明 | 必填 |
|------|------|------|
| `-c, --channelId` | 频道ID | 是 |
| `--name` | 商品名称 | 是 |
| `--price` | 商品价格 | 是 |
| `--stock` | 库存数量 | 否 |
| `--description` | 商品描述 | 否 |
| `--image` | 商品图片URL | 否 |

## 获取商品详情

```bash
# 表格格式
npx polyv-live-cli@latest product get -c 3151318 -p prod001

# JSON格式
npx polyv-live-cli@latest product get -c 3151318 -p prod001 -o json
```

## 更新商品

```bash
# 更新价格
npx polyv-live-cli@latest product update -c 3151318 -p prod001 --price 129.00

# 更新库存
npx polyv-live-cli@latest product update -c 3151318 -p prod001 --stock 200

# 更新名称和描述
npx polyv-live-cli@latest product update \
  -c 3151318 \
  -p prod001 \
  --name "更新后的商品名称" \
  --description "新描述"

# 更新图片
npx polyv-live-cli@latest product update -c 3151318 -p prod001 --image "https://example.com/new-image.jpg"
```

## 删除商品

```bash
# 带确认提示
npx polyv-live-cli@latest product delete -c 3151318 -p prod001

# 强制删除
npx polyv-live-cli@latest product delete -c 3151318 -p prod001 -f
```

## 常用工作流程

### 为直播特卖设置商品

```bash
# 创建频道
npx polyv-live-cli@latest channel create -n "限时特卖" -o json

# 添加商品
npx polyv-live-cli@latest product add -c 3151318 --name "特卖商品1" --price 49.00 --stock 50
npx polyv-live-cli@latest product add -c 3151318 --name "特卖商品2" --price 99.00 --stock 30
npx polyv-live-cli@latest product add -c 3151318 --name "特卖商品3" --price 149.00 --stock 20

# 验证商品
npx polyv-live-cli@latest product list -c 3151318
```

### 批量更新价格

```bash
# 以JSON格式导出商品列表
npx polyv-live-cli@latest product list -c 3151318 -o json > products.json

# 编程方式编辑价格
# ... 更新 products.json ...

# 应用更新
for id in $(cat products.json | jq -r '.data[].productId'); do
  new_price=$(cat products.json | jq -r ".data[] | select(.productId == \"$id\") | .price")
  npx polyv-live-cli@latest product update -c 3151318 -p "$id" --price "$new_price"
done
```

### 库存管理

```bash
# 检查库存水平
npx polyv-live-cli@latest product list -c 3151318 -o json | jq '.data[] | {name: .name, stock: .stock}'

# 销售后更新库存
npx polyv-live-cli@latest product update -c 3151318 -p prod001 --stock 45
```

## 商品状态

| 状态 | 说明 |
|------|------|
| `active` | 商品可见且可购买 |
| `inactive` | 商品已隐藏 |
| `out_of_stock` | 库存不足 |

## 故障排除

### "Product not found"（商品不存在）

- 确认商品ID是否正确
- 确保商品属于指定频道

### "Insufficient stock"（库存不足）

- 检查当前库存：`npx polyv-live-cli@latest product get -c <频道ID> -p <商品ID>`
- 更新库存：`npx polyv-live-cli@latest product update -c <频道ID> -p <商品ID> --stock <数量>`

### "Invalid price format"（价格格式无效）

- 使用小数格式：`99.00` 而非 `99`
- 价格必须为正数


path: references/watch-condition.md
content: # 观看条件配置命令

## 概述

观看条件配置命令用于管理直播间的观看权限设置，支持获取和设置观看条件。 可配置多种认证方式，如密码观看、付费观看、白名单观看、登记观看等。

## 命令列表

| 命令 | 说明 |
|------|------|
| `watch-condition get` | 获取观看条件配置 |
| `watch-condition set` | 设置观看条件配置 |

## watch-condition get - 获取观看条件

获取当前频道或全局的观看条件配置信息。

### 语法

```bash
npx polyv-live-cli@latest watch-condition get [--channel-id <ID>] [-o table|json]
```

### 参数

| 参数 | 简写 | 必填 | 说明 |
|------|------|------|------|
| `--channel-id` | | 否 | 频道ID， 不传则获取全局设置 |
| `--output` | `-o` | 否 | 输出格式： `table`（默认）或 `json` |

### 示例

```bash
# 获取频道观看条件（表格格式）
npx polyv-live-cli@latest watch-condition get --channel-id 123456

# 获取全局观看条件设置
npx polyv-live-cli@latest watch-condition get

# 获取观看条件（JSON格式）
npx polyv-live-cli@latest watch-condition get --channel-id 123456 -o json
```

### 输出字段

| 字段 | 说明 |
|------|------|
| 条件级别 | 主要 (1) 或 次要 (2) |
| 状态 | 启用 (Y) 或 禁用 (N) |
| 认证类型 | 认证方式（无限制、密码观看、付费观看等） |
| 详细配置 | 根据认证类型显示具体配置 |

## watch-condition set - 设置观看条件

设置频道或全局的观看条件配置。

### 语法

```bash
npx polyv-live-cli@latest watch-condition set [options]
```

### 参数

| 参数 | 简写 | 必填 | 说明 |
|------|------|------|------|
| `--channel-id` | | 否 | 频道ID， 不传则设置全局 |
| `--rank` | | 否 | 条件级别: `1` (主要) 或 `2` (次要)， 默认 `1` |
| `--auth-type` | | 否 | 认证类型（见下表） |
| `--enabled` | | 否 | 是否启用: `Y` 或 `N`， 默认 `Y` |
| `--auth-code` | | 否 | 密码（auth-type 为 code 时使用） |
| `--price` | | 否 | 价格/元（auth-type 为 pay 时使用） |
| `--config-file` | | 否 | JSON 配置文件路径（复杂配置时使用） |
| `--output` | `-o` | 否 | 输出格式: `table`（默认）或 `json` |

### 认证类型 (auth-type)

| 值 | 说明 | 所需额外参数 |
|------|------|------|
| `none` | 无限制（公开观看） | - |
| `code` | 密码观看 | `--auth-code` |
| `pay` | 付费观看 | `--price` |
| `phone` | 白名单观看 | - |
| `info` | 登记观看 | 需通过配置文件设置 |
| `custom` | 自定义授权 | 需通过配置文件设置 |
| `external` | 外部授权 | 需通过配置文件设置 |
| `direct` | 独立授权 | 需通过配置文件设置 |

### 示例

```bash
# 设置公开观看（无限制）
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --rank 1 --auth-type none --enabled Y

# 设置密码观看
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --rank 1 --auth-type code --enabled Y --auth-code "abc123"

# 设置付费观看（99.9元）
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --rank 1 --auth-type pay --enabled Y --price 99.9

# 禁用主要观看条件
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --rank 1 --enabled N

# 使用配置文件设置复杂条件
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --config-file ./watch-condition.json
```

### 配置文件格式

使用 `--config-file` 参数时，JSON 文件格式如下：

```json
{
  "authSettings": [
    {
      "rank": 1,
      "authType": "code",
      "enabled": "Y",
      "authCode": "password123"
    },
    {
      "rank": 2,
      "authType": "info",
      "enabled": "Y",
      "infoFields": [
        { "type": "name", "name": "姓名" },
        { "type": "mobile", "name": "手机号", "sms": "Y" }
      ]
    }
  ]
}
```

## 常见用例

### 1. 开启密码观看

```bash
# 设置主要条件为密码观看
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --rank 1 --auth-type code --auth-code "mypassword" --enabled Y
```

### 2. 设置付费直播

```bash
# 设置付费观看（19.9元）
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --rank 1 --auth-type pay --price 19.9 --enabled Y
```

### 3. 配置多级认证

使用配置文件设置主要和次要观看条件：

```json
{
  "authSettings": [
    {
      "rank": 1,
      "authType": "code",
      "enabled": "Y",
      "code": "vip123"
    },
    {
      "rank": 2,
      "authType": "info",
      "enabled": "Y",
      "infoFields": [
        { "type": "name", "name": "姓名", "placeholder": "请输入姓名" },
        { "type": "mobile", "name": "手机号", "sms": "Y" }
      ]
    }
  ]
}
```

```bash
npx polyv-live-cli@latest watch-condition set --channel-id 123456 --config ./auth-config.json
```

## 注意事项

1. **认证优先级**: 主要条件 (rank=1) 优先于次要条件 (rank=2)
2. **全局设置**: 不传 `--channel-id` 时操作的是全局默认设置
3. **禁用条件**: 设置 `--enabled N` 可以禁用某个级别的观看条件
4. **价格单位**: `--price` 参数单位为元，会自动转换为分
5. **配置文件**: 复杂配置建议使用 JSON 文件方式


path: references/card-push.md
content: # 卡片推送命令

管理直播间的卡片推送功能，在直播过程中向观众推送营销卡片。

## 概述

卡片推送功能允许运营人员在直播过程中向观众推送各种类型的营销卡片，如红包、礼品盒、二维码等，提升观众互动和转化率。

## 命令列表

### 列出卡片配置

```bash
npx polyv-live-cli@latest card-push list -c <频道ID>
npx polyv-live-cli@latest card-push list -c 3151318 -o json  # JSON格式输出
```

### 创建卡片配置

```bash
# 基本创建（手动推送）
npx polyv-live-cli@latest card-push create -c <频道ID> \
  --image-type <图片类型> \
  --title <卡片标题> \
  --link <跳转链接> \
  --duration <倒计时时长> \
  --show-condition PUSH

# 定时弹出（观看时长触发）
npx polyv-live-cli@latest card-push create -c 3151318 \
  --image-type giftbox \
  --title "限时优惠" \
  --link "https://example.com/promo" \
  --duration 10 \
  --show-condition WATCH \
  --condition-value 30 \
  --condition-unit SECONDS

# 完整参数示例
npx polyv-live-cli@latest card-push create -c 3151318 \
  --image-type redpack \
  --title "新年红包" \
  --link "https://example.com/redpack" \
  --duration 15 \
  --show-condition PUSH \
  --card-type qrCode \
  --enter-enabled Y \
  --link-enabled Y \
  --redirect-type tab \
  -o json
```

### 更新卡片配置

```bash
npx polyv-live-cli@latest card-push update -c <频道ID> --card-push-id <卡片ID> --title <新标题>
npx polyv-live-cli@latest card-push update -c 3151318 --card-push-id 123 --title "更新后的标题"
npx polyv-live-cli@latest card-push update -c 3151318 --card-push-id 123 --duration 20 --link "https://new-url.com"
```

### 推送卡片

```bash
npx polyv-live-cli@latest card-push push -c <频道ID> --card-push-id <卡片ID>
npx polyv-live-cli@latest card-push push -c 3151318 --card-push-id 123
```

### 取消推送

```bash
npx polyv-live-cli@latest card-push cancel -c <频道ID> --card-push-id <卡片ID>
npx polyv-live-cli@latest card-push cancel -c 3151318 --card-push-id 123
```

### 删除卡片配置

```bash
npx polyv-live-cli@latest card-push delete -c <频道ID> --card-push-id <卡片ID>
npx polyv-live-cli@latest card-push delete -c 3151318 --card-push-id 123
```

## 参数说明

### 通用参数

| 参数 | 说明 | 必填 |
|------|------|------|
| -c, --channel-id | 频道ID | 是 |
| -o, --output | 输出格式 (table/json) | 否 |

### 创建/更新参数

| 参数 | 说明 | 值 |
|------|------|------|
| --image-type | 卡片图片类型 | giftbox(礼盒), redpack(红包), custom(自定义) |
| --title | 卡片标题 | 字符串 |
| --link | 点击跳转链接 | URL |
| --duration | 卡片倒计时时长(秒) | 数字 |
| --show-condition | 弹出方式 | PUSH(手动推送), WATCH(观看时长触发) |
| --condition-value | 触发条件值 | 数字 |
| --condition-unit | 触发条件单位 | SECONDS(秒), MINUTES(分钟) |
| --card-type | 卡片类型 | common(普通), qrCode(二维码) |
| --enter-enabled | 是否允许进场推送 | Y/N |
| --link-enabled | 是否启用跳转 | Y/N |
| --redirect-type | 跳转方式 | tab(新标签页), window(新窗口), self(当前页) |
| --countdown-msg | 倒计时提示语 | 字符串 |
| --duration-position | 倒计时位置 | top/bottom |

## 卡片类型说明

### image-type 图片类型

- **giftbox**: 礼盒样式
- **redpack**: 红包样式
- **custom**: 自定义图片

### show-condition 弹出方式

- **PUSH**: 手动推送，需要调用 push 命令
- **WATCH**: 观看时长触发，需配合 condition-value 和 condition-unit

### card-type 卡片类型

- **common**: 普通卡片
- **qrCode**: 二维码卡片

## 典型工作流程

### 手动推送流程

```bash
# 1. 创建卡片配置
npx polyv-live-cli@latest card-push create -c 3151318 \
  --image-type giftbox \
  --title "限时优惠" \
  --link "https://shop.example.com/promo" \
  --duration 10 \
  --show-condition PUSH

# 2. 在适当时机推送卡片
npx polyv-live-cli@latest card-push push -c 3151318 --card-push-id 123

# 3. 如需取消推送
npx polyv-live-cli@latest card-push cancel -c 3151318 --card-push-id 123
```

### 自动弹出流程

```bash
# 创建观看30秒后自动弹出的卡片
npx polyv-live-cli@latest card-push create -c 3151318 \
  --image-type redpack \
  --title "新手红包" \
  --link "https://shop.example.com/redpack" \
  --duration 15 \
  --show-condition WATCH \
  --condition-value 30 \
  --condition-unit SECONDS
```

### 管理现有卡片

```bash
# 列出所有卡片
npx polyv-live-cli@latest card-push list -c 3151318

# 更新卡片标题
npx polyv-live-cli@latest card-push update -c 3151318 --card-push-id 123 --title "新标题"

# 删除不需要的卡片
npx polyv-live-cli@latest card-push delete -c 3151318 --card-push-id 123
```

## 输出示例

### list 命令输出

```
┌─────────┬────────────┬──────────┬──────────┬───────────────┐
│ 卡片ID  │ 标题       │ 图片类型 │ 倒计时   │ 弹出方式      │
├─────────┼────────────┼──────────┼──────────┼───────────────┤
│ 123     │ 限时优惠   │ giftbox  │ 10秒     │ 手动推送      │
│ 124     │ 新手红包   │ redpack  │ 15秒     │ 观看30秒触发  │
└─────────┴────────────┴──────────┴──────────┴───────────────┘
```

### create 命令输出

```
✓ 卡片配置创建成功

卡片ID: 125
标题: 新年特惠
图片类型: giftbox
弹出方式: 手动推送
```

## 注意事项

1. **推送时机**: 使用 PUSH 模式时，需确保直播正在进行中才能推送
2. **条件设置**: WATCH 模式下，condition-value 和 condition-unit 必须同时设置
3. **链接有效性**: 确保 link 参数指向有效的 URL
4. **倒计时**: duration 决定卡片在观众端显示的时长


path: references/record-settings.md
content: # 录制设置命令

## 概述

录制设置命令用于管理直播频道的回放设置和录制文件转存。支持查询和修改回放配置、将录制文件转存到点播、设置默认回放视频等操作。

## 命令列表

### record setting get

查询频道回放设置。

```bash
npx polyv-live-cli@latest record setting get -c <频道ID> [-o table|json]
```

**参数：**
- `-c, --channel-id <channelId>` - 频道ID（必填）
- `-o, --output <format>` - 输出格式：table（默认）或 json

**示例：**

```bash
# 查询频道回放设置
npx polyv-live-cli@latest record setting get -c 2588188

# JSON格式输出
npx polyv-live-cli@latest record setting get -c 2588188 -o json
```

**响应字段：**
| 字段 | 说明 |
|------|------|
| channelId | 频道号 |
| playbackEnabled | 回放开关：Y(开启)、N(关闭) |
| type | 回放类型：single(单个回放)、list(列表回放) |
| origin | 回放来源：record(录制)、playback(回放列表)、vod(点播列表) |
| videoId | 回放视频ID |
| videoName | 回放视频名称 |
| sectionEnabled | 章节开关 |
| globalSettingEnabled | 是否应用通用设置 |
| playbackMultiplierEnabled | 倍数播放开关 |
| playbackProgressBarEnabled | 进度条开关 |

---

### record setting set

修改频道回放设置。

```bash
npx polyv-live-cli@latest record setting set -c <频道ID> [选项]
```

**参数：**
- `-c, --channel-id <channelId>` - 频道ID（必填）
- `--playback-enabled <Y|N>` - 回放开关
- `--type <single|list>` - 回放类型
- `--origin <record|playback|vod|material>` - 回放来源
- `--video-id <videoId>` - 视频ID（当origin为playback或vod时需要）
- `--global-setting-enabled <Y|N>` - 是否使用通用设置
- `--section-enabled <Y|N>` - 章节开关
- `--playback-multiplier-enabled <Y|N>` - 倍数播放开关
- `--playback-progress-bar-enabled <Y|N>` - 进度条开关
- `--chat-playback-enabled <Y|N>` - 聊天互动重现开关
- `-o, --output <format>` - 输出格式

**示例：**

```bash
# 开启回放
npx polyv-live-cli@latest record setting set -c 2588188 --playback-enabled Y

# 设置为单个回放模式，来源为回放列表
npx polyv-live-cli@latest record setting set -c 2588188 --type single --origin playback --video-id 73801f70c8

# 关闭回放
npx polyv-live-cli@latest record setting set -c 2588188 --playback-enabled N
```

---

### record convert

将录制文件转存到点播（同步模式）。

```bash
npx polyv-live-cli@latest record convert -c <频道ID> --file-name <文件名> [选项]
```

**参数：**
- `-c, --channel-id <channelId>` - 频道ID（必填）
- `--file-name <fileName>` - 转存后的文件名（必填）
- `--session-id <sessionId>` - 源场次ID
- `--to-play-list <Y|N>` - 是否存入回放列表
- `--set-as-default <Y|N>` - 是否设为默认回放
- `--callback-url <url>` - 回调URL
- `--async` - 使用异步模式转存
- `-o, --output <format>` - 输出格式

**示例：**

```bash
# 同步转存录制文件
npx polyv-live-cli@latest record convert -c 2588188 --file-name "直播回放20240320" --session-id abc123

# 异步转存（适用于大文件）
npx polyv-live-cli@latest record convert -c 2588188 --file-name "直播回放" --session-id abc123 --async

# 转存并设为默认回放
npx polyv-live-cli@latest record convert -c 2588188 --file-name "直播回放" --session-id abc123 --set-as-default Y
```

**注意事项：**
- 同步模式会立即返回点播视频ID（vid）
- 异步模式适用于大文件转存，vid需要通过回调获取
- 同一账号5分钟内只能调用一次转存接口

---

### record set-default

设置默认回放视频。

```bash
npx polyv-live-cli@latest record set-default -c <频道ID> --video-id <视频ID> [选项]
```

**参数：**
- `-c, --channel-id <channelId>` - 频道ID（必填）
- `--video-id <videoId>` - 视频ID（必填）
- `--list-type <playback|vod>` - 列表类型
- `-o, --output <format>` - 输出格式

**示例：**

```bash
# 从回放列表设置默认视频
npx polyv-live-cli@latest record set-default -c 2588188 --video-id 73801f70c8 --list-type playback

# 从点播列表设置默认视频
npx polyv-live-cli@latest record set-default -c 2588188 --video-id 73801f70c8 --list-type vod
```

---

## 常见工作流程

### 直播后设置回放

```bash
# 1. 查询当前回放设置
npx polyv-live-cli@latest record setting get -c 2588188

# 2. 转存录制文件到点播
npx polyv-live-cli@latest record convert -c 2588188 --file-name "产品介绍直播" --session-id session123

# 3. 设置为默认回放视频
npx polyv-live-cli@latest record set-default -c 2588188 --video-id vid456 --list-type playback

# 4. 开启回放功能
npx polyv-live-cli@latest record setting set -c 2588188 --playback-enabled Y
```

### 批量转存历史直播

```bash
# 查询场次列表获取sessionId
npx polyv-live-cli@latest session list -c 2588188

# 依次转存各场次的录制文件
npx polyv-live-cli@latest record convert -c 2588188 --file-name "直播01" --session-id session1 --async
npx polyv-live-cli@latest record convert -c 2588188 --file-name "直播02" --session-id session2 --async
```

## 相关API文档

- [查询频道回放设置](https://help.polyv.net/#/live/api/channel/playback/get_playback_setting)
- [修改频道回放设置](https://help.polyv.net/#/live/api/channel/playback/set_record_setting)
- [录制文件转存点播](https://help.polyv.net/#/live/api/channel/playback/record_convert)
- [设置默认回放视频](https://help.polyv.net/#/live/api/channel/playback/set_record_default)


path: references/whitelist.md
content: # 白名单管理命令

## 概述

白名单管理命令用于管理直播间的观看权限（白名单观看模式）。支持全局设置和频道级别设置。

白名单观看是一种观看条件认证方式，只有添加到白名单中的用户才能观看直播。白名单项包含会员码（手机号）和昵称（备注）。

## 命令列表

| 命令 | 说明 |
|------|------|
| `whitelist list` | 获取白名单列表 |
| `whitelist add` | 添加白名单项 |
| `whitelist update` | 更新白名单项 |
| `whitelist remove` | 删除白名单项 |

## 通用参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `--rank <number>` | 条件级别：1=主要条件，2=次要条件 | 是 |
| `--channel-id <id>` | 频道ID（不传为全局设置） | 否 |
| `-o, --output <format>` | 输出格式：table（默认）或 json | 否 |

## whitelist list - 获取白名单列表

获取白名单列表，支持分页和关键词搜索。

### 语法

```bash
npx polyv-live-cli@latest whitelist list --rank <1|2> [options]
```

### 参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `--rank <number>` | 条件级别：1=主要条件，2=次要条件 | 是 |
| `--channel-id <id>` | 频道ID（不传为全局设置） | 否 |
| `--page <number>` | 页码，默认为1 | 否 |
| `--page-size <number>` | 每页数量，默认为10 | 否 |
| `--keyword <keyword>` | 关键词（可根据会员码和名称查询） | 否 |
| `-o, --output <format>` | 输出格式：table（默认）或 json | 否 |

### 示例

```bash
# 获取全局白名单
npx polyv-live-cli@latest whitelist list --rank 1

# 获取频道白名单
npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1

# 分页查询
npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 --page 1 --page-size 20

# 关键词搜索
npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 --keyword "张三"

# JSON格式输出
npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 -o json
```

### 输出示例

**表格格式：**
```
找到 2 条白名单记录 (channel 3151318)
页码: 1 / 1
┌──────────────┬──────────┐
│ 会员码        │ 昵称      │
├──────────────┼──────────┤
│ 13800138000  │ 张三      │
│ 13900139000  │ 李四      │
└──────────────┴──────────┘
```

**JSON格式：**
```json
{
  "pageNumber": 1,
  "totalPages": 1,
  "pageSize": 10,
  "contents": [
    { "name": "张三", "phone": "13800138000" },
    { "name": "李四", "phone": "13900139000" }
  ]
}
```

## whitelist add - 添加白名单项

添加单个白名单项。

### 语法

```bash
npx polyv-live-cli@latest whitelist add --rank <1|2> --code <会员码> [options]
```

### 参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `--rank <number>` | 条件级别：1=主要条件，2=次要条件 | 是 |
| `--code <code>` | 会员码（最多50个字符） | 是 |
| `--channel-id <id>` | 频道ID（不传为全局设置） | 否 |
| `--name <name>` | 昵称/备注（最多50个字符） | 否 |
| `-o, --output <format>` | 输出格式：table（默认）或 json | 否 |

### 示例

```bash
# 添加频道白名单
npx polyv-live-cli@latest whitelist add --channel-id 3151318 --rank 1 --code "13800138000" --name "张三"

# 添加全局白名单
npx polyv-live-cli@latest whitelist add --rank 1 --code "13800138000" --name "张三"

# JSON格式输出
npx polyv-live-cli@latest whitelist add --rank 1 --code "13800138000" --name "张三" -o json
```

### 输出示例

**表格格式：**
```
Successfully added whitelist item for channel 3151318
```

**JSON格式：**
```json
{
  "success": true,
  "message": "白名单添加成功",
  "code": "13800138000",
  "channelId": "3151318"
}
```

## whitelist update - 更新白名单项

更新单个白名单项。需要提供原会员码（old-code）来标识要更新的记录。

### 语法

```bash
npx polyv-live-cli@latest whitelist update --rank <1|2> --old-code <原会员码> --code <新会员码> [options]
```

### 参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `--rank <number>` | 条件级别：1=主要条件，2=次要条件 | 是 |
| `--old-code <code>` | 原会员码（用于定位要更新的记录） | 是 |
| `--code <code>` | 新会员码（最多50个字符） | 是 |
| `--channel-id <id>` | 频道ID（不传为全局设置） | 否 |
| `--name <name>` | 新昵称/备注（最多50个字符） | 否 |
| `-o, --output <format>` | 输出格式：table（默认）或 json | 否 |

### 示例

```bash
# 更新频道白名单
npx polyv-live-cli@latest whitelist update --channel-id 3151318 --rank 1 --old-code "13800138000" --code "13900139000" --name "李四"

# 更新全局白名单
npx polyv-live-cli@latest whitelist update --rank 1 --old-code "13800138000" --code "13900139000" --name "李四"

# JSON格式输出
npx polyv-live-cli@latest whitelist update --rank 1 --old-code "13800138000" --code "13900139000" -o json
```

### 输出示例

**表格格式：**
```
Successfully updated whitelist item for channel 3151318
```

**JSON格式：**
```json
{
  "success": true,
  "message": "白名单更新成功",
  "oldCode": "13800138000",
  "newCode": "13900139000",
  "channelId": "3151318"
}
```

## whitelist remove - 删除白名单项

删除白名单项，支持单个删除和清空所有。

### 语法

```bash
npx polyv-live-cli@latest whitelist remove --rank <1|2> [options]
```

### 参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `--rank <number>` | 条件级别：1=主要条件，2=次要条件 | 是 |
| `--channel-id <id>` | 频道ID（不传为全局设置） | 否 |
| `--codes <codes>` | 要删除的会员码（目前只支持单个值） | 否* |
| `--clear` | 清空所有白名单 | 否* |
| `-o, --output <format>` | 输出格式：table（默认）或 json | 否 |

*必须指定 `--codes` 或 `--clear` 其中之一

### 示例

```bash
# 删除单个白名单
npx polyv-live-cli@latest whitelist remove --channel-id 3151318 --rank 1 --codes "13800138000"

# 清空所有白名单
npx polyv-live-cli@latest whitelist remove --channel-id 3151318 --rank 1 --clear

# JSON格式输出
npx polyv-live-cli@latest whitelist remove --rank 1 --codes "13800138000" -o json
```

### 输出示例

**表格格式（删除）：**
```
Successfully removed 1 whitelist item for channel 3151318
```

**表格格式（批量删除）：**
```
Successfully removed 3 whitelist items for channel 3151318
```

**表格格式（清空）：**
```
Successfully cleared all whitelist items for channel 3151318
```

**JSON格式：**
```json
{
  "success": true,
  "message": "白名单删除成功",
  "codes": "13800138000,13900139000",
  "clear": false,
  "channelId": "3151318"
}
```

## 错误处理

| 错误消息 | 原因 | 解决方案 |
|---------|------|---------|
| `rank 必须是 1 (主要条件) 或 2 (次要条件)` | rank 参数不是 1 或 2 | 使用有效的 rank 值 |
| `code (会员码) 是必需的` | 添加时未提供 code | 添加 --code 参数 |
| `old-code (原会员码) 是必需的` | 更新时未提供 old-code | 添加 --old-code 参数 |
| `必须指定 --codes 或使用 --clear 清空所有` | 删除时未提供 codes 或 clear | 添加 --codes 或 --clear 参数 |
| `code 不能超过50个字符` | code 超过长度限制 | 缩短 code 内容 |
| `name 不能超过50个字符` | name 超过长度限制 | 缩短 name 内容 |

## 使用场景

### 场景1：设置白名单观看模式

```bash
# 1. 设置观看条件为白名单模式
npx polyv-live-cli@latest watch-condition set --channel-id 3151318 --rank 1 --auth-type phone --enabled Y

# 2. 添加白名单用户
npx polyv-live-cli@latest whitelist add --channel-id 3151318 --rank 1 --code "13800138000" --name "VIP用户1"
npx polyv-live-cli@latest whitelist add --channel-id 3151318 --rank 1 --code "13900139000" --name "VIP用户2"

# 3. 验证白名单列表
npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1
```

### 场景2：批量管理白名单

```bash
# 批量添加（需逐个添加）
for phone in 13800138001 13800138002 13800138003; do
  npx polyv-live-cli@latest whitelist add --channel-id 3151318 --rank 1 --code "$phone"
done

# 搜索特定用户
npx polyv-live-cli@latest whitelist list --channel-id 3151318 --rank 1 --keyword "138001380"

# 批量删除（需逐个删除）
for phone in 13800138001 13800138002 13800138003; do
  npx polyv-live-cli@latest whitelist remove --channel-id 3151318 --rank 1 --codes "$phone"
done
```

### 场景3：直播结束后清理

```bash
# 清空所有白名单
npx polyv-live-cli@latest whitelist remove --channel-id 3151318 --rank 1 --clear

# 关闭白名单观看模式
npx polyv-live-cli@latest watch-condition set --channel-id 3151318 --rank 1 --auth-type none --enabled Y
```

## 注意事项

1. **全局设置 vs 频道设置**：不传 `--channel-id` 时为全局设置，传 `--channel-id` 时为频道级别设置
2. **rank 参数**：必须指定 rank（1=主要条件，2=次要条件），与观看条件配置对应
3. **白名单观看前提**：需要先通过 `watch-condition set` 命令设置认证类型为 `phone`（白名单观看）
4. **字符限制**：code 和 name 最多50个字符
5. **更新操作**：需要提供 `--old-code` 来定位要更新的记录
6. **删除限制**：`--codes` 参数目前只支持单个会员码（API限制），如需删除多个请逐个调用或使用 `--clear` 清空所有


path: references/session-management.md
content: # 场次管理

场次（Session）是直播频道的一次直播活动记录。每个频道可以有多个场次，用于记录不同的直播活动。

## 命令概览

| 命令 | 说明 |
|------|------|
| `session list` | 获取场次列表 |
| `session get` | 获取场次详情 |

## 场次列表

获取频道或账号下的场次列表。

### 语法

```bash
npx polyv-live-cli@latest session list [-c <频道ID>] [--page <页码>] [--page-size <数量>] [-o <格式>]
```

### 参数

| 参数 | 简写 | 必填 | 说明 |
|------|------|------|------|
| `--channel-id` | `-c` | 否 | 频道ID，不传则获取整个账号下的所有场次 |
| `--page` | | 否 | 页码，默认 1 |
| `--page-size` | | 否 | 每页数量，默认 10 |
| `--output` | `-o` | 否 | 输出格式：`table`（默认）或 `json` |

### 示例

```bash
# 获取频道场次列表
npx polyv-live-cli@latest session list -c 2588188

# 获取整个账号下的场次
npx polyv-live-cli@latest session list

# 分页查询
npx polyv-live-cli@latest session list -c 2588188 --page 2 --page-size 20

# JSON 格式输出
npx polyv-live-cli@latest session list -c 2588188 -o json
```

### 表格输出示例

```
场次列表 - 频道: 2588188
共 2 个场次

场次ID          名称          状态      开始时间              结束时间
e9s2h3jd8f     测试场次1     已结束    2024-01-15 10:30     2024-01-15 11:00
k7d9f2h1l5     测试场次2     直播中    2024-01-15 14:00     -
```

## 场次详情

获取指定场次的详细信息。

### 语法

```bash
npx polyv-live-cli@latest session get -c <频道ID> --session-id <场次ID> [-o <格式>]
```

### 参数

| 参数 | 简写 | 必填 | 说明 |
|------|------|------|------|
| `--channel-id` | `-c` | 是 | 频道ID |
| `--session-id` | | 是 | 场次ID |
| `--output` | `-o` | 否 | 输出格式：`table`（默认）或 `json` |

### 示例

```bash
# 获取场次详情
npx polyv-live-cli@latest session get -c 2588188 --session-id e9s2h3jd8f

# JSON 格式输出
npx polyv-live-cli@latest session get -c 2588188 --session-id e9s2h3jd8f -o json
```

### 表格输出示例

```
场次详情 - 频道: 2588188

场次ID: e9s2h3jd8f
名称: 测试场次1
状态: 已结束
开始时间: 2024-01-15 10:30
结束时间: 2024-01-15 11:00
计划开始: 2024-01-15 10:00
计划结束: 2024-01-15 12:00
推流类型: client
推流客户端: web
观看地址: https://live.polyv.net/2588188/e9s2h3jd8f
```

## 场次状态

| 状态值 | 中文名称 | 说明 |
|--------|----------|------|
| `unStart` | 未开始 | 场次已创建但尚未开始 |
| `live` | 直播中 | 正在直播 |
| `end` | 已结束 | 直播已结束 |
| `playback` | 回放中 | 正在播放回放 |
| `expired` | 已过期 | 场次已过期 |

## JSON 输出字段

### 场次列表响应

```json
{
  "contents": [
    {
      "sessionId": "e9s2h3jd8f",
      "channelId": "2588188",
      "name": "测试场次1",
      "status": "end",
      "startTime": "2024-01-15 10:30",
      "endTime": 1705287600000,
      "createdTime": 1705285800000,
      "planStartTime": 1705284000000,
      "planEndTime": 1705291200000,
      "streamType": "client",
      "pushClient": "web",
      "watchUrl": "https://live.polyv.net/2588188/e9s2h3jd8f",
      "userId": "user123"
    }
  ],
  "pageNumber": 1,
  "pageSize": 10,
  "totalItems": 2,
  "totalPages": 1
}
```

### 场次详情字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `sessionId` | String | 场次ID |
| `channelId` | String | 频道ID |
| `name` | String | 场次名称 |
| `status` | String | 场次状态 |
| `startTime` | String | 开始时间 |
| `endTime` | Number | 结束时间（毫秒时间戳） |
| `createdTime` | Number | 创建时间（毫秒时间戳） |
| `planStartTime` | Number | 计划开始时间（毫秒时间戳） |
| `planEndTime` | Number | 计划结束时间（毫秒时间戳） |
| `streamType` | String | 流类型 |
| `pushClient` | String | 推流客户端类型 |
| `watchUrl` | String | 观看地址 |
| `userId` | String | 用户ID |
| `splashImg` | String | 封面图 |
| `splashLargeImg` | String | 竖屏大图封面 |

## 相关 API 文档

- [获取场次列表](../../docs/api/v4/channel/session/new/list.md)
- [获取场次详情](../../docs/api/v4/channel/session/new/get.md)

## 相关命令

- [频道管理](channel-management.md) - 管理直播频道
- [回放管理](playback.md) - 管理直播回放
- [推流操作](streaming.md) - 开始/结束直播


path: references/documents.md
content: # 文档管理

管理直播频道的课件文档，支持上传、查看和删除文档。

## 命令概览

| 命令 | 说明 |
|------|------|
| `document list` | 获取频道文档列表 |
| `document upload` | 上传文档（通过URL） |
| `document delete` | 删除文档 |
| `document status` | 查询文档转码状态 |

## document list

获取指定频道的课件文档列表。

### 语法

```bash
npx polyv-live-cli@latest document list -c <频道ID> [选项]
```

### 选项

| 选项 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--channel-id <ID>` | `-c` | 频道ID（必填） | - |
| `--status <状态>` | `-s` | 文档状态过滤 | - |
| `--page <页码>` | `-P` | 页码 | 1 |
| `--page-size <数量>` | `-l` | 每页数量 | 10 |
| `--output <格式>` | `-o` | 输出格式 (table/json) | table |

### 文档状态

| 状态值 | 说明 |
|--------|------|
| `normal` | 正常 |
| `waitUpload` | 等待上传 |
| `failUpload` | 上传失败 |
| `waitConvert` | 等待转码 |
| `failConvert` | 转码失败 |

### 示例

```bash
# 列出频道所有文档
npx polyv-live-cli@latest document list -c 3151318

# 过滤转码失败的文档
npx polyv-live-cli@latest document list -c 3151318 --status failConvert

# 分页查询
npx polyv-live-cli@latest document list -c 3151318 --page 2 --page-size 20

# JSON格式输出
npx polyv-live-cli@latest document list -c 3151318 -o json
```

## document upload

通过URL上传文档到频道。

### 语法

```bash
npx polyv-live-cli@latest document upload -c <频道ID> --url <文件URL> [选项]
```

### 选项

| 选项 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--channel-id <ID>` | `-c` | 频道ID（必填） | - |
| `--url <URL>` | `-u` | 文件URL（必填） | - |
| `--type <类型>` | `-t` | 转换类型 | common |
| `--doc-name <名称>` | `-n` | 文档名称 | - |
| `--callback-url <URL>` | | 回调地址 | - |
| `--output <格式>` | `-o` | 输出格式 (table/json) | table |

### 转换类型

| 类型 | 说明 |
|------|------|
| `common` | 普通转换（静态PPT） |
| `animate` | 动效转换（保留PPT动画） |

### 支持格式

PPT、PDF、PPTX、DOC、DOCX、WPS

### 示例

```bash
# 上传PPT文档
npx polyv-live-cli@latest document upload -c 3151318 --url https://example.com/slides.pptx

# 上传带动画的PPT
npx polyv-live-cli@latest document upload -c 3151318 --url https://example.com/slides.pptx --type animate

# 指定文档名称
npx polyv-live-cli@latest document upload -c 3151318 --url https://example.com/slides.pptx --doc-name "产品介绍"

# 设置转码完成回调
npx polyv-live-cli@latest document upload -c 3151318 --url https://example.com/slides.pptx --callback-url https://myserver.com/callback
```

## document delete

删除指定文档。

### 语法

```bash
npx polyv-live-cli@latest document delete -c <频道ID> --file-id <文档ID> [选项]
```

### 选项

| 选项 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--channel-id <ID>` | `-c` | 频道ID（必填） | - |
| `--file-id <ID>` | `-f` | 文档ID（必填） | - |
| `--type <类型>` | `-t` | 文档类型 | 自动检测 |
| `--force` | | 跳过确认提示 | false |
| `--output <格式>` | `-o` | 输出格式 (table/json) | table |

### 文档类型

| 类型 | 说明 |
|------|------|
| `old` | 旧版文档 |
| `new` | 新版文档 |

> 注意：如果不指定 `--type`，系统会自动检测文档类型。

### 示例

```bash
# 删除文档（会有确认提示）
npx polyv-live-cli@latest document delete -c 3151318 --file-id abc123

# 强制删除，跳过确认
npx polyv-live-cli@latest document delete -c 3151318 --file-id abc123 --force

# 指定文档类型
npx polyv-live-cli@latest document delete -c 3151318 --file-id abc123 --type new
```

## document status

查询文档转码状态。

### 语法

```bash
npx polyv-live-cli@latest document status -c <频道ID> --file-id <文档ID>
```

### 选项

| 选项 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--channel-id <ID>` | `-c` | 频道ID（必填） | - |
| `--file-id <ID>` | `-f` | 文档ID（必填） | - |
| `--output <格式>` | `-o` | 输出格式 (table/json) | table |

### 示例

```bash
# 查询单个文档状态
npx polyv-live-cli@latest document status -c 3151318 --file-id abc123

# 批量查询（用逗号分隔）
npx polyv-live-cli@latest document status -c 3151318 --file-id abc123,def456

# JSON格式输出
npx polyv-live-cli@latest document status -c 3151318 --file-id abc123 -o json
```

## 输出示例

### document list 表格输出

```
┌──────────┬────────────────┬──────────┬────────┬─────────────┐
│ 文档ID   │ 文档名称       │ 类型     │ 状态   │ 创建时间    │
├──────────┼────────────────┼──────────┼────────┼─────────────┤
│ abc123   │ 产品介绍.pptx  │ pptx     │ normal │ 2024-03-20  │
│ def456   │ 公司简介.pdf   │ pdf      │ normal │ 2024-03-19  │
└──────────┴────────────────┴──────────┴────────┴─────────────┘
```

### document upload 输出

```
✓ 文档上传成功

文档ID: abc123
状态: waitConvert
类型: common
```

### document status 输出

```
┌──────────┬─────────────┬──────┬──────────┐
│ 文档ID   │ 转码状态    │ 类型 │ 总页数   │
├──────────┼─────────────┼──────┼──────────┤
│ abc123   │ success     │ new  │ 15       │
└──────────┴─────────────┴──────┴──────────┘
```

## 常见工作流程

### 上传并在直播中使用文档

```bash
# 1. 上传文档
npx polyv-live-cli@latest document upload -c 3151318 --url https://example.com/slides.pptx --type animate

# 2. 查看转码状态
npx polyv-live-cli@latest document status -c 3151318 --file-id <返回的文档ID>

# 3. 确认文档已就绪（状态为 success）
# 文档已可在直播间使用
```

### 批量管理文档

```bash
# 1. 查看所有转码失败的文档
npx polyv-live-cli@latest document list -c 3151318 --status failConvert -o json > failed.json

# 2. 逐个删除失败的文档
# jq -r '.contents[].fileId' failed.json | xargs -I {} npx polyv-live-cli@latest document delete -c 3151318 --file-id {} --force
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)