小鹅通直播管理 v2.0
通过小鹅通开放 API 创建/查询/删除店铺直播并查询店铺经营数据。
快速上手（90% 场景）
安装一次全局命令后，创建直播只需一行：
xiaoe-live "直播标题" # 立即开播，默认：阿白/免费/15分钟/推流
xiaoe-live "标题" --duration 1800 # 覆盖时长（秒）
xiaoe-live "标题" --sell-mode paid --price 99 # 付费直播
xiaoe-live --title "标题" --start "2026-09-15 20:00:00" --teacher 阿白 # 完整参数
> 未安装全局命令时，用 python3 scripts/xiaoe_fast.py 替代 xiaoe-live，参数完全一致。安装方式见文末「安装全局命令」。
三层工具，按需选用
| 层级 | 工具 | 适用场景 |
|---|---|---|
| 快捷层 | xiaoe-live "标题" |
日常创建直播，一条命令含凭证自检+创建+验证+观看链接 |
| 脚本层 | python3 scripts/xiaoe_fast.py |
需要完整自定义参数（讲师/主播/售卖方式/时长/开播时间） |
| 底层 | python3 scripts/xiaoe_api.py |
排障、通用接口调用、直播列表/详情/删除、订单账单查询 |
工作流：创建直播
1. 计算开播时间
涉及"明天/后天/X点"等表述，先用日期工具拿到具体日期再传入；传 now 或不传则取当前时间。
时长换算：分钟 × 60 = 秒（15 分钟 → 900）。
2. 创建直播（快捷层，推荐）
只需标题，其余走默认值：
xiaoe-live "直播名称"
核心参数（均可覆盖）：
| 参数 | 默认值 | 说明 |
|---|---|---|
--title |
必填 | 直播名称 |
--start |
now |
开播时间，now=当前时间，或 YYYY-MM-DD HH:MM:SS |
--duration |
900 | 时长（秒），15分钟=900 |
--sell-mode |
free | 免费/付费/加密/指定学员/关联课程（支持中文别名） |
--teacher |
阿白 | 讲师昵称或 user_id |
--anchor |
同讲师 | 主播昵称或 user_id（与讲师不同时才传） |
--alive-type |
2 | 0语音 1录播 2推流 |
--dry-run |
- | 只打印参数不创建 |
售卖方式附加参数：
| 模式 | 值 | 附加参数 |
|---|---|---|
| 免费 | free/免费 |
无 |
| 付费 | paid/付费 |
--price 99（单位元，必填） |
| 加密 | encrypted/加密 |
--password 密码（必填） |
| 指定学员 | designated/指定学员 |
--users u_1,u_2（可选；名单字段未文档化，若被拒需后台添加） |
| 关联课程 | related/关联课程 |
--package p_xxx,p_yyy（课程资源id，必填）；可选 --price |
3. 验证（xiaoe_fast.py 自动完成，无需手动）
快捷脚本创建后自动执行：列表核对 + 详情核对 + 获取官方观看链接。输出包含：
✅ 创建成功，已核对：
名称 : 直播名称
时间 : 2026-09-14 06:19:02（时长 900s）
售卖 : payment_type=1 piece_price=0分
讲师 : 阿白
直播ID : l_xxx
观看链接: https://appxxx.h5.xiaoeknow.com/v4/course/alive/l_xxx?...
4. 发送观看链接
把脚本输出的观看链接发给用户，附上开播时间与售卖方式说明。
底层命令（xiaoe_api.py）
python3 scripts/xiaoe_api.py check-env # 凭证自检（每次排障先做）
python3 scripts/xiaoe_api.py create-live --title 测试 --start now --sell-mode free --teacher u_xxx
python3 scripts/xiaoe_api.py list-live --page 1 --page-size 20 # 直播列表
python3 scripts/xiaoe_api.py live-detail l_xxx # 直播详情（参数是 id，不是 alive_id）
python3 scripts/xiaoe_api.py live-url l_xxx # 获取观看链接
python3 scripts/xiaoe_api.py delete-live l_xxx # 删除直播
python3 scripts/xiaoe_api.py call /xe.user.list/1.0.0 --json '{"page":1,"page_size":50}' # 通用调用
数据查询：最近一周店铺数据
python3 scripts/xiaoe_api.py call /xe.ecommerce.order.list/1.0.0 \
--json '{"created_time_start":"2026-09-07 00:00:00","created_time_end":"2026-09-14 00:00:00","page":1,"page_size":50}'
连接器 xiaoe_overview（近 7 天订单 + 当月账单 + 用户总数）、xiaoe_users --days 7（新增用户）、xiaoe_trades --days 7（交易明细）组合使用。
关键坑速查
- 价格单位分、时长单位秒（创建；CLI 的
--price已自动转分） - 详情参数
id而非alive_id - role_info 同一用户只能写一个角色：讲师和主播为同一人时只写讲师，否则报"role_info里存在无效用户"（v2.0 已在 xiaoe_fast.py 自动去重）
- 售卖方式五种：免费/付费/加密/指定学员/关联课程，参数对照见
references/api_reference.md - "指定学员"名单字段官方未文档化，创建后若未生效需后台「用户列表」添加
- 沙箱凭证路径是相对 cwd 的
Users/ankang/.xiaoe-mcp/profiles/showtime - token 缓存过期/白名单未配 → 报"ip not in white list"，需用户加白名单后重试
- 详情见
references/api_reference.md（接口与参数）、references/troubleshooting.md（排障）
安装全局命令（一次性）
bash scripts/install.sh
安装后 xiaoe-live 命令全局可用，无需 cd 到脚本目录。脚本会自动把 wrapper 写入 ~/bin/xiaoe-live 并确保 ~/bin 在 PATH 中。
版本历史
见 CHANGELOG.md。
