小鹅通直播学员批量导入
把格式各异的学员名单，整理成小鹅通直播后台能直接吃的 .csv。
典型输入：商家甩来一串手机号、聊天里粘的一大段号码、一个 名单.xlsx、一张名单截图。
典型输出：一份 .csv，商家拿去「直播 → 对应直播的学员/观看权限 → 批量导入」上传即可。
一、和「课程学员导入」的三处关键区别
| 课程学员 | 直播学员 | |
|---|---|---|
| 列数 | 5 列（含有效期、姓名、备注、公司名） | 只有 1 列：手机号/用户ID |
| 有效期 | 必填，要问 | 没有这一栏，别问 |
| 姓名等资料 | 可以带进去 | 带不进去，直播导入只管"谁能看" |
最容易犯的错：把课程那套流程搬过来，追着商家问"有效期给多久"。
直播的观看权限跟随直播本身（那场直播的时间），文件里没有、也不需要有效期。
表格里就算有"课程有效期""姓名""公司"列，也只能忽略——脚本会明确提示。
> 如果商家其实是要给课程开权限，那不该用本技能，用「小鹅通课程学员批量导入」。
二、格式速查（脚本已保证，你不需要手写）
| 项 | 硬要求 |
|---|---|
| 文件 | CSV，UTF-8 带 BOM，LF 换行 |
| 第 1 行 | 官方「导入说明（必读）」整段（5 条），被引号包裹 |
| 第 2 行 | 表头，只有 1 列：手机号/用户ID（必填） |
| 第 3 行起 | 一行一个号码，全文不出现任何逗号 |
成品长这样：
"导入说明（必读）：
1. 要导入的内容必须要存放在第1个工作表中。
……
5. 手机号输入请注意：字段前后不能有空格和超链接，国内手机号必须为11位手机号格式（示例：13511112222）。"
手机号/用户ID（必填）
13511112222
13511112223
u_60d1599c35cyh_xxxxxxxxxx
为什么"不能有逗号"是硬要求：模板是单列的，一旦某个号码里混进逗号，这一行就凭空变成两列，
后台只觉得"格式不对"，不会告诉你是哪一行。所以校验器直接断言整个文件 0 个逗号。
官方原文与每条规则出处见 @references/format-spec.md。
三、工作流
Step 0 · 不要问有效期
这是直播，没有有效期这一栏。问有效期会显得你不懂这个场景。
真正值得确认的只有一件：这批人要加到哪一场直播？
如果商家没说，可以在交付时提一句"上传时记得进对应那场直播的学员页"，不必非要追问。
Step 1 · 收输入
| 输入形态 | 怎么处理 |
|---|---|
| 一串号码（对话里粘贴） | 直接 --text，不用先整理 |
.csv / .tsv / .txt |
直接 --input |
.xlsx / .xlsm |
直接 --input（取第 1 个工作表，符合官方要求） |
.xls 老格式 |
让用户另存为 xlsx 或 csv |
| 名单截图 | 先读图把号码抄出来，抄完必须回读核对，错一位就是给陌生人开了直播 |
Step 2 · 生成
# 对话里粘的一串号码
python3 scripts/build_import.py \
--text "13511112222 135 1111 2223 +8613611112224" \
--out ~/Desktop/直播学员导入.csv
# 表格文件（自动找手机号列，其余列忽略）
python3 scripts/build_import.py \
--input ~/Desktop/名单.xlsx \
--out ~/Desktop/直播学员导入.csv
多列表格会自动定位手机号列（先看表头关键词，再看哪一列的合法号码最多），
并把"姓名/公司/有效期这些列不会带入"明确告诉你。
Step 3 · 读报告
看到"已排除"就逐条告诉用户是哪个号码、什么原因。
看到"以下列不会带入"要转达——商家常常以为姓名会跟着进去。
Step 4 · 校验（硬门槛）
python3 scripts/verify_import.py ~/Desktop/直播学员导入.csv --expect <数据行数>
必须看到 ✓ 校验通过 才能交付。
Step 5 · 交付
用 present_files 打开 CSV，并说明：
- 共几条学员、去重去掉了几个
- 排除了几条、分别什么原因
- 姓名/备注/公司名没有带进去（直播模板没这栏）
- 上传路径：小鹅通店铺后台 → 直播 → 对应直播的学员/观看权限 → 批量导入
- 提醒：不要用 Excel 打开后另存（会产生逗号、丢 BOM）
四、铁律
- 不要手写 CSV。 单列格式里多一个逗号就多一列，后台只回"导入异常"。
- 不要用 Excel 另存。 预览可以，保存一律回到脚本生成的那份。
- 不要编造手机号。 错一位就是给陌生人放进了直播。
- 不要问有效期。 直播没有这一栏。
- 不要承诺带姓名。 直播导入只解决"谁能看"，姓名跟着账号走，不跟着这个文件走。
- 新用户必须用手机号（从未访问过店铺的），用户ID 只对已有用户有效。
五、已知踩坑（脚本已处理）
| 坑 | 现象 | 本技能怎么绕开 |
|---|---|---|
| 手机号带空格 | 135 1111 2222 被按空格拆成 3 条垃圾数据 |
按 3-4-4 分组模式整体识别，不按空格切 |
| 全角数字 | １３５１１１１２２２２ 导入失败 |
先做 NFKC 归一化 |
+86 / 0086 前缀 |
13 位被判为非法 | 自动剥离国家码 |
| 用户ID 里的下划线 | u_60d1..._abc 被当分隔符删掉 |
先认 u_ 前缀，再清洗手机号分隔符 |
| 号码里混进逗号 | 凭空多一列，整份文件作废 | 生成时清掉逗号；校验时断言全文 0 逗号 |
| 多列表格挑错列 | 把"序号"或"备注"当手机号导进去 | 先认表头关键词，再按哪列合法号码最多兜底 |
| 单列文件带表头 | 「手机号」被当成无效号码报错 | 识别出表头行自动跳过 |
| Excel 另存 | 手机号变科学计数法、BOM 丢失 | 交付时明确提醒别另存 |
六、文件清单（缺一个都会跑不起来）
xiaoe-live-student-import/
├── SKILL.md # 本文件
├── references/
│ ├── format-spec.md # 官方格式原文 + 字段口径 + 校验规则
│ └── usage-examples.md # 真实场景：输入 → 命令 → 输出
└── scripts/
├── build_import.py # 名单 → 合规单列 CSV（清洗、定位列、去重、报告）
├── verify_import.py # 成品逐项校验（独立实现，并断言全文无逗号）
└── selftest.py # 回归自检 41 项，含 6 项负向对照 + 官方字节指纹
依赖：Python 3 标准库即可；读 .xlsx 需要 openpyxl（没装会提示另存 CSV）。
装完想确认没坏，跑一句：python3 scripts/selftest.py，应输出 全部通过 ✓（41 项）。
