学管录音解析（三讲标准）
把一条学管电话 / 家长会录音，变成两份可交付物：Word 分析报告 + 网页报告。每处引用原文都标注「时间 + 说话人」，方便回听复核。
判定依据全部来自 references/standard.md（三讲与标准流程），话术写法来自 references/script-writing.md，数据结构见 references/output-schema.md。动手前先读 standard.md，写话术前读 script-writing.md。
一、输入与产出
| 内容 | |
|---|---|
| 必要输入 | 原文逐字稿（.docx / .xlsx / .xlsm / .csv / .txt，须含说话人与时间戳） |
| 可选输入 | 录音文件（仅用于校验时长是否 ≥20min、判断录音类型） |
| 产出 1 | <学员>-录音分析报告.docx（封面 + 6 章，可直接打印/发群） |
| 产出 2 | <学员>-录音分析报告.html（同源数据，带评分的可视化版本） |
| 中间件 | .analysis/analysis.json（两份产物唯一数据源，必须保留） |
> 不再生成「原文标注版 docx」。原文位置直接写进报告的引文框（原文｜01:45:47 家长 楷芝妈妈），需要核对时按时间戳回听即可。
二、环境准备（只做一次）
# 找一个可用的 Python：macOS/Linux 多为 python3，Windows 上 python3 常不存在，退到 python
PY=""
for c in python3 python; do command -v "$c" >/dev/null 2>&1 && PY="$c" && break; done
[ -n "$PY" ] || { echo "未找到 Python，请先安装 Python 3.9+"; exit 1; }
$PY -c "import docx, openpyxl" 2>/dev/null || {
$PY -m venv ~/.workbuddy/binaries/python/envs/default
~/.workbuddy/binaries/python/envs/default/bin/pip install python-docx lxml openpyxl
PY=~/.workbuddy/binaries/python/envs/default/bin/python
}
> Windows 差异：venv 的解释器在 Scripts\python.exe（不是 bin/python），pip 也在 Scripts\ 下，把命令里的 bin/ 换成 Scripts\ 即可。
后续所有命令中的 $PY 均指这个已装 python-docx + openpyxl 的解释器，$SKILL 指本技能目录。
三、工作流
Step 1｜收料与准入
$PY $SKILL/scripts/probe_audio.py <录音文件> --transcript-json .analysis/transcript.json # 有录音时
$PY $SKILL/scripts/extract_transcript.py <原文.docx|.xlsx|.csv> --outdir .analysis
extract_transcript.py 产出 transcript.json 与 transcript.md，并打印来源类型、时长、说话人分布、各环节关键词命中位置。
原文格式兼容（脚本自动识别，不需要用户改表）：
| 形态 | 处理方式 |
|---|---|
| Word | 说话人\t00:00:18 / 正文 逐段排列，或带 [SID:...] 标记 |
| Excel 带表头 | 表头含「说话人 / 时间 / 内容（或 文本、台词、对话）」任意组合，按列名取值 |
| Excel 无表头 | 自动猜列：时间列看 00:00:18 格式，内容列看平均长度，说话人列看短文本 |
| Excel 只有「时间 + 内容」 | 说话人记为「原文」，分析时按上下文推断角色 |
| Excel 单列逐段文本 | 按 Word 段落逻辑解析（说话人行 + 正文行交替） |
| CSV | 同 Excel |
Excel 情况下 pid = 数据行号（表头不计），报告复核时可按行号回到表格定位。
准入判断（写进报告 meta，不满足先告知用户）：
- 时长 ≥ 20min；识别到扩科/扩频/续费/转全/复课目标；属于"任务不达标"的抽检样本
- 时长不足或全程无业绩目标 → 提示用户该录音不适合按本标准解析，再询问是否继续
- Excel 里说话人全为「原文」→ 先问用户能否补一列说话人；补不了就在报告 meta 里说明角色按上下文推断
Step 2｜通读逐字稿
读 .analysis/transcript.md。必须读完全文，长录音分 2—3 段读，不要只读前半段就动笔——后半段的异议与收口往往才是失分重心。
阅读时同步记录四类信息（后面写 JSON 直接用）：
- 时间戳 + 说话人 + 原句（可作
quote） - 环节边界（开场在哪结束、老师讲到哪、学管主场从哪开始）
- 数据点（分数、均分、板块分值、课时、位次、目标院校）
- 情绪点（家长失望、孩子抵触、同伴比较、心理阴影）
hints 里给出的 pid 只是线索，不要直接当结论——关键词命中"目标"不代表讲了目标。
Step 3｜定环节（先做 flow，再写问题）
按 standard.md 四、标准流程逐环节判定 完整 / 部分 / 缺失，每格都要写清"现场发生了什么"，附时间戳。
原则：
- 环节缺失不需要原文引用，但要指出"本该出现的位置"（如"老师讲完 08:06 处直接进入家长提问"）
- 老师发言与学管主场要分开判，不要把两者混成"沟通充分"
- 闭环跟进只看有没有时间点、责任人、书面方案，不看有没有说"回头联系"
Step 4｜写 analysis.json
按 references/output-schema.md 写。硬性要求：
- 问题点 3—5 个，跨至少 2 个环节（三讲 + 异议/跟进），每个配
script - 亮点 2—3 个，写"机制"不写"态度"（例：用 4/24/6 的板块占分把"考差"讲成"哪块没讲到"）
quote从 transcript.md 原样复制，pid用行首编号；quote_source写成「时间 + 角色」，如01:45:47 家长 楷芝妈妈（Excel 来源且时间缺失时写行号，如第 128 行 家长）script180—350 字，含数字、时间、动作；不确定的分数/院校线用「」占位，禁止编造overall_score按五维加权取整，verdict一句话同时点出最强亮点与最致命问题
写完先自检：问题数、亮点数、每个问题的 script 是否都有数字与动作。
Step 5｜出报告
$PY $SKILL/scripts/build_report.py .analysis/analysis.json --outdir ./输出 --name "<学员>-录音分析报告"
一次生成 Word + HTML 两份，同源同数据。不再调用标注脚本、不再改动原文。
Step 6｜质检（不过不许交付）
- [ ] 整体点评含四件事：环节完整性、目标传达、优势点、问题点
- [ ] 问题点 3—5 个，每个都有「环节定位 + 原文 + 为什么 + 后果 + 改进话术」
- [ ] 亮点 2—3 个，且能写成"可复用动作"
- [ ] 改进话术能直接背：有数字、有课时/时间、有下一步动作
- [ ] 每处引文都带原文位置（时间戳 + 说话人），点击/回听能定位到原句；无时间戳的 Excel 用行号兜底
- [ ] 报告里没有空话（"整体不错""有待提升""加强沟通"一律替换成具体判断）
- [ ] 两份产物章节编号一致（01 整体点评 / 02 问题点 / 03 亮点 / 04 五维评分 / 05 跟进建议 / 06 口径说明）
Step 7｜交付
用文件展示工具给出两份产物 + analysis.json，回复中说明：综合得分、3 个最致命问题、下一步动作。不要把报告全文贴进对话。
四、经验规则
- 老师讲得好 ≠ 沟通成功。教师端数据再扎实，学管没做"总结—目标—方案"，家长依然不会决策，这类场次综合分通常在 45—55 分。
- 家长重复提问就是信号。同一个问题被问 2 次以上（"后面怎么安排""到底有没有用"），说明前一环节没答到位，直接作为问题点。
- 内部规则话术是高频硬伤。"档期站不住""经理过不去""一个月不能留"——出现即列为问题，并给替换话术。
- 口语与 ASR 错字保留原样。引用"那高那那两分"而不是改成"那高两分"，否则按时间戳回听时对不上原句。
- 不确定就留空。目标院校、具体分数未知时用「XX 大学」「」占位，让学管现场填，比编造安全。
- 长会先确认场景再动笔。2 小时以上的线下家长会常混着"老师学情 + 学管规划 + 事务通知 + 闲聊"四段，先按时间轴切出"老师离场点"，否则会把事务通知误判成学管主场。
- 说话人行可能带转写标记。常见形式
名字[SID:55109321]\t00:00:18，SPEAKER_RE已兼容；若仍提取到 0 条，先用docx.paragraphs打印前 20 段确认"说话人"与"正文"是不是分成了两段、分隔符是不是制表符。 - 版式约定：问题点的「问题描述」整段标红（红字 #B4232C + 浅红底 #FDECEC + 左侧红边），「改进话术」标签保持黄色高亮。两处不能同色，否则读者分不清"哪儿说错了"和"该怎么说"。
- Excel 只当"表格"读，不当"文档"读。带表头就按列名取值，没表头就按时间格式／平均长度猜列；猜不出来时脚本会退化成单列文本解析，这时先看
transcript.md前 20 行确认没把整个单元格当一句话。 - 原文位置是交付的一部分。报告引文框必须写「原文｜时间 角色」，没有时间戳就写行号——学管要能凭这一行回去找原话，否则报告只能当读后感看。
- 原文是纯文本（.txt）时流程相同，
extract_transcript.py自动识别；缺说话人标记时先提示用户补格式，或按段落粗分并在报告中说明。
五、文件地图
scripts/extract_transcript.py Word/Excel/CSV/txt → transcript.json/md（pid 与原文段落或行号对齐）
scripts/probe_audio.py 录音时长与准入校验（afinfo/ffprobe）
scripts/build_report.py analysis.json → Word + HTML
scripts/common.py 版式与文本对齐工具
references/standard.md 三讲、标准流程、五维评分、高频问题清单
references/script-writing.md 话术四要素、六类模板、禁语、检查清单
references/output-schema.md analysis.json 字段与 pid 取值方法
