学页｜完课状态归因器
概述
学页｜完课状态归因器是一款面向 K12 教培机构教务与运营团队的学习效果诊断技能。团队只需提供学员学习数据（平台导出或人工台账），即可获得一套"状态分得清、原因归得准、干预排得开"的完课诊断方案，解决课程运营中的四大痛点：
- 完课率黑箱——只知道完课率 30%，不知道卡在哪、为什么卡
- 干预千人一面——对所有未完课学员群发同样的催学短信，无差别骚扰
- 归因靠拍脑袋——"这批学员就是懒"，把节奏问题、难度问题都当成动力问题
- 资源撒胡椒面——班主任时间有限，不知道该先救谁、怎么救
本技能内置 5 类完课状态分型标准、6 层完课漏斗、6 类归因模型与 P0-P3 干预优先级体系，让"完课率 30%"变成"临门一脚 5 人 24 小时内可挽回、中途停滞 13 人主因是难度爬坡"的可执行诊断。
触发场景
以下情况触发本技能：
- 直接关键词：完课率、完课归因、学员流失、流失分析、学习停滞、课程完课、学员唤醒、干预清单、续费预警、学习数据诊断
- 语境触发：用户描述完课/流失诊断需求（如"这期班完课率掉得厉害，帮我分析下""哪些学员快流失了""学员学到一半不动了怎么办"）
- 材料触发：用户上传学员学习数据（.csv/.xlsx：进度、观看时长、最近活跃等），要求诊断完课问题
- 组合触发：用户已用 xueye-recorded-course-manager 归档课程、或用 xueye-replay-clipper 切了复习素材，现在要诊断学员完课情况并制定干预方案
不触发的场景：课程内容生产（用 xueye-lesson-prep）、回放切片（用 xueye-replay-clipper）、章节归档（用 xueye-recorded-course-manager）、纯数据可视化不做归因（常规表格任务）。
与其他学页技能的关系：
- xueye-recorded-course-manager（录播课章节化管理器）→ 定义"课程有什么"，本技能诊断"学员学得怎么样"
- xueye-replay-clipper（回放精华切片器）→ 其切片产物是本技能 M3 兴趣衰减干预的推荐素材（轻复习/高能预告）
- xueye-lesson-prep（AI备课）→ M1 难度失配干预中的补弱微课可用它快速产出
- 本技能是学页系列"运营效果层"工具：前三款管内容生产，本款管学习效果运营，闭环补全
交付物一览
| 交付物 | 格式 | 内容 |
|---|---|---|
| 归因分析报告 | .docx | 核心结论、完课漏斗、状态分布、归因分布与解读、P0 名单、干预排期建议、数据口径说明 |
| 学员干预清单 | .xlsx | 逐人工单：学员ID、状态、进度、主/次归因、置信度、优先级（着色）、建议动作（含执行人）、执行状态跟踪 |
| 归因源文件 | attribution.json | 机器可读的完整归因方案，供校验、二次分析与下轮对比 |
工作流程
归因遵循五步标准化工作流。按顺序执行，每一步的输出作为下一步的输入。
Step 1: 需求采集
从用户输入中提取归因分析要素。如信息不完整，提问补充。
需采集的要素：
| 要素 | 必填 | 默认值 | 示例 |
|---|---|---|---|
| 课程名/编号 | 是 | — | "初中数学秋季提高班 C2026-08" |
| 学员学习数据 | 是 | — | .csv/.xlsx（学员粒度：进度/时长/最近活跃） |
| 学段学科 | 是 | — | 初中·数学 |
| 数据快照日期 | 否 | 今天 | 数据导出日 |
| 班级范围 | 否 | 全部班级 | "只看八年级3班" |
| 学员价值分层 | 否 | 统一常规 | "客单价≥5000算高价值" |
| 历史基线 | 否 | 无（首轮） | 上轮完课率/归因分布 |
| 已知背景 | 否 | — | "期中考试刚结束""最近换过播放系统" |
采集规则：
1. 最多提问 3 个问题，一轮问完，禁止多轮追问
2. 只问缺失的必填项；用户已表达的信息不重复问
3. 用户上传数据文件后，先读取数据结构（运行解析器探查列名），再决定是否提问
4. 非必填项未提供时使用默认值，不提问
5. 信息齐全时直接进入 Step 2，无需确认
数据最低要求（学员粒度，缺一不可）：学员ID、进度（或已完成/总课时）、累计观看时长、最近学习日期、报名日期。缺字段时提示用户补导，不得凭空编造。
Step 2: 数据解析与状态分型
对学员数据做结构化解析，完成状态分型与漏斗分层。
实现方式： 运行 scripts/completion_parser.py 解析数据
python scripts/completion_parser.py students.csv --json
python scripts/completion_parser.py students.csv --snapshot 2026-08-18
加载参考文档： references/completion-metrics.md — 完课指标与漏斗定义
解析产出：
1. 5 类状态分型：已完课 / 临门一脚 / 中途停滞 / 浅尝辄止 / 未启动（+在学观测态）
2. 6 层完课漏斗：报名→激活→首课→25%→50%→80%→完课，逐层转化率与流失人数，标出最大流失层
3. 核心指标：激活率、首课完课率、整体完课率、7日活跃率（对照健康参考线）
4. 待归因学员清单：非完课且非在学的学员，进入 Step 3
解析规则：
1. 列名宽容匹配（中英文列名、大小写、下划线均识别）
2. 状态判定优先级：completed > not_started > active > 按进度×闲置天数分桶
3. 数据残缺记录跳过并报错提示，不静默丢弃
4. 快照原则：全部指标基于同一快照日期计算
Step 3: 归因分析与方案生成
对待归因学员逐人归因，生成 attribution.json。
加载参考文档：
- references/attribution-models.md — 归因模型库（6 类模型的识别信号与决策流）
- references/intervention-strategies.md — 干预策略手册（P0-P3 与标准动作）
- references/attribution-schema.md — attribution.json 字段字典
归因执行要点：
- 信号识别：结合解析产出（进度曲线、闲置天数、停滞课时）与用户提供的补充信息（班主任备注、作业记录、客服工单、考试日历），按 6 类模型的信号表逐条匹配
- 归属决策：按 M6→M4→M1→M3→M2→M5 顺序判归属（外部性、确定性强的先判）
- 置信度分级：高（3条信号）/ 中（2条）/ 低（2条但有矛盾）/ unclear（无信号），宁可 unclear 不强行归类
- 优先级判定：状态×置信度基准矩阵起步，学员价值高上调一级（封顶 P0）；临门一脚必须 P0/P1
- 动作匹配：按主归因从干预策略手册匹配标准动作（1-4 个），标注执行人与时限
归因纪律：
- 每人最多 1 主归因 + 2 次归因，主归因决定干预主干
- 信号不足学员归 unclear 并附已观察信号清单——unclear 群体本身提示数据采集缺口
- 补充信息（台账/工单）与行为数据冲突时，行为数据优先，冲突记入 signals
Step 4: 方案质量审查
对照 schema 逐项审查 attribution.json 草稿，错误清零后方可交付。
实现方式： 运行 scripts/attribution_validator.py
python scripts/attribution_validator.py attribution.json
审查清单：
1. 结构完整性：meta 必填齐全、funnel 七层、状态六键、归因逐条字段齐全
2. 口径一致：状态六键之和=学员总数=归因条数+完课+在学；漏斗单调不增；漏斗×状态交叉一致
3. 枚举合法：归因 7 种、置信度 4 种、优先级 4 种、执行人 4 种
4. 红线规则：临门一脚必须 P0/P1；unclear 归因 confidence 必须 unclear 且无次归因；完课/在学学员不得入归因
5. 汇总一致：summary 分布与明细逐条计数一致
6. 健康度提示：unclear 占比>30% 提示补采数据；P0>15 人提示分批排期
warning 逐条人工评估后放行或修正；error 必须清零。
Step 5: 成果生成与交付
将归因方案转化为三份文件交付。
实现方式： 运行本技能脚本产出 .xlsx、报告 .md，再调用 tencent-docx 将 .md 排版为 .docx
文件生成顺序：
1. 先写 attribution.json（机器可读源）
2. 运行 scripts/attribution_validator.py attribution.json 校验通过
3. 运行 scripts/attribution_export.py attribution.json --outdir ./output 产出干预清单 .xlsx 与报告 .md
4. 调用 tencent-docx 将报告 .md 转为 .docx
5. 调用 present_files 统一交付
文件命名： {课程名}_归因分析报告.docx / _学员干预清单.xlsx
交付后提示：
- 告知教务/运营团队文件位置，可预览/下载
- 提示"干预清单按优先级着色排序，建议班主任从 P0 开始逐一消化"
- 提示"干预后 14 天回看状态迁移，回看结果计入下轮归因基线"（形成运营闭环）
- 提示"unclear 学员建议人工回访补采信息，数据越全归因越准"
- 涉及学员个人信息的动作提醒通过内部系统执行，交付物中已脱敏
参考文档索引
以下参考文档按需加载，不必一次性全部读取：
| 文档 | 路径 | 加载时机 |
|---|---|---|
| 完课指标与漏斗定义 | references/completion-metrics.md |
Step 2 数据解析 |
| 归因模型库 | references/attribution-models.md |
Step 3 归因分析 |
| 干预策略手册 | references/intervention-strategies.md |
Step 3 归因分析、Step 5 交付 |
| attribution.json 字段字典 | references/attribution-schema.md |
Step 3/4 方案与审查 |
工具脚本
以下脚本可直接执行，提供确定性能力：
| 脚本 | 路径 | 用途 | 调用时机 |
|---|---|---|---|
| 完课数据解析器 | scripts/completion_parser.py |
解析学员数据，输出状态分型、漏斗、核心指标与待归因清单 | Step 2 数据解析 |
| 归因方案校验器 | scripts/attribution_validator.py |
校验 attribution.json 的结构、口径、枚举、红线规则 | Step 4 交付前 |
| 归因导出器 | scripts/attribution_export.py |
将 attribution.json 导出为干预清单 .xlsx + 报告 .md | Step 5 成果生成 |
完课数据解析用法：
python scripts/completion_parser.py students.csv
python scripts/completion_parser.py students.csv --json
python scripts/completion_parser.py students.csv --snapshot 2026-08-18
归因校验用法：
python scripts/attribution_validator.py attribution.json
python scripts/attribution_validator.py attribution.json --json
归因导出用法：
python scripts/attribution_export.py attribution.json --outdir ./output
python scripts/attribution_export.py attribution.json --outdir ./output --prefix "初中数学秋季班"
依赖的 WorkBuddy 内置技能
| 技能 | 用途 | 调用步骤 |
|---|---|---|
tencent-docx |
将报告 .md 排版为 .docx | Step 5 |
| 表格能力（openpyxl 链路） | 生成干预清单 .xlsx | Step 5 |
present_files |
统一交付成果 | Step 5 |
重要约束
- 数据真实性红线：所有归因必须基于用户提供的真实数据信号，禁止编造"假设该学员回看3次"类推断；数据不足宁可 unclear，不强行归类。
- 口径统一纪律：一份报告一套口径（分母、活跃、进度），中途不得切换；进度折算口径须在报告注明。
- 脱敏纪律：学员姓名、手机号等 PII 不进入任何交付物，统一用 student_id；联系方式由机构内部系统对照获取。
- 干预克制原则：频次红线（重干预周≤1次、轻触达周≤3次）写入排期建议；不诱导机构对明确拒绝的学员持续骚扰。
- unclear 是特性：保留 unclear 群体并提示数据采集缺口，不用默认模型填充掩盖问题。
- 机构主导：AI 产出的是归因假设与干预建议，最终干预决策权归机构负责人；交付时须提示人工复核 P0 名单。
