学页｜学员学习报告生成器
概述
学页｜学员学习报告生成器是一款面向 K12 教培机构班主任与学管师的学员成果沟通技能。团队只需提供学员学习数据（平台导出或人工台账），即可批量生成"家长看得懂、学员不反感、机构能促续"的个性化学习报告，解决学情沟通中的四大痛点：
- 报告不会写——班主任一人带百人，逐人手写报告不现实，期末集中补报告流于形式
- 数据不会说——平台数据一堆数字，家长看不懂进度 74.6% 意味着什么
- 沟通没抓手——家长会/续费前缺少一份拿得出手的成果证据，续费全靠嘴说
- 问题看不见——单个学员的预警信号淹没在全班表格里，发现时已掉队
本技能内置 20+ 学习指标体系、五维健康雷达（H1-H4 分级）、七节报告结构与学段化话术规范，把"进度 74.6%、通过率 58%"变成"小雨本期掌握扎实，但几何证明是明显短板，建议每周 2 次专练、三周补齐"的家长语言。
触发场景
以下情况触发本技能：
- 直接关键词：学习报告、学情报告、学员报告、家长报告、阶段报告、期末报告、成绩单、学情反馈、报告生成、批量报告
- 语境触发：用户描述学情沟通需求（如"期末了要给每个家长发学习总结""给家长看的学习反馈怎么写""续费前要出一份学习成果"）
- 材料触发：用户上传学员学习数据（.csv/.xlsx：出勤、作业、测验、进度等），要求生成报告
- 组合触发：用户已用 xueye-completion-attributor 做完完课归因，现在要向家长与学管侧输出正式学情报告；或已用 xueye-recorded-course-manager 归档课程，周期末要出学员成果
不触发的场景：完课归因诊断（用 xueye-completion-attributor）、课程内容生产（用 xueye-lesson-prep）、课程体系规划（用 xueye-curriculum-builder）、纯数据可视化不做报告（常规表格任务）。
与其他学页技能的关系：
- xueye-completion-attributor（完课状态归因器）→ 内部视角"为什么掉队"，本技能外部视角"学得怎么样"；其 H4 风险学员联动本技能预警清单
- xueye-recorded-course-manager（录播课章节化管理器）→ 其课程清单是本技能报告的课程信息来源
- xueye-lesson-prep（AI备课）→ 报告建议中的补弱微课可由它快速产出
- xueye-replay-clipper（回放精华切片器）→ 报告建议可引用切片作为复习素材
- 本技能是学页系列"成果沟通层"工具：内容生产（备课/归档/切片）+ 效果运营（归因）之后，报告把成果讲给家长听，闭环收口
交付物一览
| 交付物 | 格式 | 内容 |
|---|---|---|
| 个人学习报告 | .docx（由 .md 排版） | 七节结构：总体表现→学习行为→知识掌握→进步轨迹→问题诊断→下阶段建议→家长行动清单；首页五维雷达与 H 等级结论 |
| 班级学习总览 | .xlsx | 三 Sheet：班级总览（H 等级着色+五维+预警项）、预警清单（仅 H3/H4，供学管师）、指标口径（数据说明） |
| 报告源文件 | report_data.json | 机器可读的完整报告数据，供校验、二次分析与跨期对比 |
工作流程
报告生成遵循五步标准化工作流。按顺序执行，每一步的输出作为下一步的输入。
Step 1: 需求采集
从用户输入中提取报告生成要素。如信息不完整，提问补充。
需采集的要素：
| 要素 | 必填 | 默认值 | 示例 |
|---|---|---|---|
| 课程名/编号 | 是 | — | "初中数学秋季提高班 C2026-08" |
| 学员学习数据 | 是 | — | .csv/.xlsx（学员粒度：出勤/作业/测验/进度） |
| 学段学科 | 是 | — | 初中·数学 |
| 报告期 | 是 | — | "2026暑期""2026秋季第1-8周" |
| 数据快照日期 | 否 | 今天 | 数据导出日 |
| 班级范围 | 否 | 全部学员 | "只给八年级3班出报告" |
| 报告称呼 | 否 | "该学员" | "小雨同学"（PII 由机构内部对照） |
| 上期基准 | 否 | 无（首轮） | 上期成绩，用于进步对比 |
| 落款信息 | 否 | 无 | 机构名 + 班主任称呼 |
| 报告模式 | 否 | 全员批量 | 单人深度版 / 全班批量版 |
采集规则：
1. 最多提问 3 个问题，一轮问完，禁止多轮追问
2. 只问缺失的必填项；用户已表达的信息不重复问
3. 用户上传数据文件后，先读取数据结构（运行解析器探查列名），再决定是否提问
4. 非必填项未提供时使用默认值，不提问
5. 信息齐全时直接进入 Step 2，无需确认
数据最低要求（学员粒度）：student_id 必须有；出勤/作业/测验/进度/互动/进步六类数据至少有一类非空，否则该学员报告无从谈起，提示用户补导。
Step 2: 数据解析与指标计算
对学员数据做结构化解析，计算指标、分档、五维雷达与健康等级。
实现方式： 运行 scripts/report_parser.py 解析数据
python scripts/report_parser.py students.csv --json
python scripts/report_parser.py students.csv --snapshot 2026-08-18 --meta meta.json
加载参考文档： references/report-metrics.md — 指标体系与数据口径
解析产出：
1. 20+ 指标：学习坚持类（出勤/提交/频率）、深度类（进度/回看/互动）、掌握类（测验/薄弱点）、进步类（进步值/排名变化），缺数据记 null 不编造
2. 五维雷达：坚持度/完成度/掌握度/互动度/进步度，0-100 归一化
3. 健康等级：H1 优质（0 预警维）/ H2 稳定（1）/ H3 波动（2）/ H4 风险（≥3）
4. 班级基准：出勤率/提交率/均分/进度均值与互动 P50，供分位对比
解析规则：
1. 列名宽容匹配（中英文列名、大小写、下划线均识别）
2. 数据残缺记录跳过并报错提示，不静默丢弃
3. 快照原则：全部指标基于同一快照日期计算
4. 班级基准两遍计算：先算全班，再带基准重算个人互动分位与预警
Step 3: 报告内容生成
将解析产出组装为 report_data.json，撰写话术填充 suggestions 与 parent_actions。
加载参考文档：
- references/report-structure.md — 七节报告结构与写作规范
- references/tone-guide.md — 话术规范与分段评语库
- references/report-schema.md — report_data.json 字段字典
内容生成要点：
- 评语撰写：以解析器产出的分档与指标为骨架，按 tone-guide 句式库撰写；学段差异（小学活泼/初中平等/高中务实）必须落实
- 建议生成：每个 H3/H4 学员 2-4 条建议，与问题一一对应（目标+动作+频次+负责人）；负责人从 {授课老师/班主任/学管师/教研} 中选
- 家长动作：1-3 条、每条 ≤20 字，只做督促/沟通/支持，不给家长布置学科任务
- 进步对比：有上期数据写进步轨迹，首轮报告明确标注"首次报告，下期开始呈现对比"
- unclear 纪律：数据不足的维度写"本期未采集"，禁止编造；H4 学员提示联动完课归因
Step 4: 方案质量审查
对照 schema 逐项审查 report_data.json 草稿，错误清零后方可导出。
实现方式： 运行 scripts/report_validator.py
python scripts/report_validator.py report_data.json
python scripts/report_validator.py report_data.json --json
审查清单：
1. 结构完整性：meta 必填齐全、学员五区齐全、雷达五维齐全
2. 口径一致：student_count 与明细条数一致；health 与雷达预警维数一致
3. 枚举合法：health 四种、owner 四种、分档四种
4. 话术红线：禁用词表扫描（不及格/差生/拖后腿/笨/保证提分等 21 词），命中即 error
5. PII 检查：键名与文本双重扫描（含 11 位手机号正则），PII 不入报告
6. 健康度提示：H4>30% 提示先归因再发报告；H3+H4>50% 提示分批沟通
warning 逐条人工评估后放行或修正；error 必须清零。
Step 5: 成果生成与交付
将 report_data.json 转化为报告文件交付。
实现方式： 运行本技能脚本产出 .md 与 .xlsx，再调用 tencent-docx 将 .md 排版为 .docx
文件生成顺序：
1. 先写 report_data.json（机器可读源）
2. 运行 scripts/report_validator.py report_data.json 校验通过
3. 运行 scripts/report_export.py report_data.json --outdir ./output --prefix "课程名" 产出个人报告 .md（reports/ 目录）与班级总览 .xlsx
4. 调用 tencent-docx 将 reports/*.md 逐份排版为 .docx
5. 调用 present_files 统一交付（人数多时可先交 1-2 份样稿，确认后批量出）
文件命名： {学员称呼}·{课程名}学习报告（{报告期}）.docx / {课程名}_班级学习总览.xlsx
交付后提示：
- 告知班主任/学管师文件位置，可预览/下载
- 提示"报告为 AI 初稿，发出前需班主任人工复核签字"（双闸门纪律）
- 提示"班级总览按 H 等级着色，建议学管师优先处理预警清单中的 H3/H4 学员"
- 提示"H4 学员建议联动完课归因器做深度诊断，先定位原因再干预"
- 提示"下期报告沿用本期 curr_score 作为进步对比基准，形成跨期成长档案"
- 涉及学员个人信息的动作提醒通过内部系统执行，交付物中已脱敏
参考文档索引
以下参考文档按需加载，不必一次性全部读取：
| 文档 | 路径 | 加载时机 |
|---|---|---|
| 报告指标体系与数据口径 | references/report-metrics.md |
Step 2 数据解析 |
| 七节报告结构与写作规范 | references/report-structure.md |
Step 3 内容生成 |
| 话术规范与分段评语库 | references/tone-guide.md |
Step 3 内容生成 |
| report_data.json 字段字典 | references/report-schema.md |
Step 3/4 方案与审查 |
工具脚本
以下脚本可直接执行，提供确定性能力：
| 脚本 | 路径 | 用途 | 调用时机 |
|---|---|---|---|
| 学习数据解析器 | scripts/report_parser.py |
解析学员数据，输出指标、分档、五维雷达、健康等级与班级基准 | Step 2 数据解析 |
| 报告方案校验器 | scripts/report_validator.py |
校验 report_data.json 的结构、口径、枚举、话术红线与 PII | Step 4 交付前 |
| 报告导出器 | scripts/report_export.py |
将 report_data.json 导出为个人报告 .md + 班级总览 .xlsx | Step 5 成果生成 |
学习数据解析用法：
python scripts/report_parser.py students.csv
python scripts/report_parser.py students.csv --json
python scripts/report_parser.py students.csv --snapshot 2026-08-18 --meta meta.json
报告校验用法：
python scripts/report_validator.py report_data.json
python scripts/report_validator.py report_data.json --json
报告导出用法：
python scripts/report_export.py report_data.json --outdir ./output
python scripts/report_export.py report_data.json --outdir ./output --prefix "初中数学秋季班"
python scripts/report_export.py report_data.json --outdir ./output --students S001,S003
依赖的 WorkBuddy 内置技能
| 技能 | 用途 | 调用步骤 |
|---|---|---|
tencent-docx |
将报告 .md 排版为 .docx | Step 5 |
| 表格能力（openpyxl 链路） | 生成班级总览 .xlsx | Step 5 |
present_files |
统一交付成果 | Step 5 |
重要约束
- 数据真实性红线：所有指标与评语必须基于用户提供的真实数据，数据不足写"本期未采集"，禁止编造"假设该学员互动积极"类推断。
- 话术红线：禁用词表硬校验（validator 强制），负面信息必须配出口（问题必有建议），对事不对人。
- 脱敏纪律：学员姓名、手机号等 PII 不进入任何交付物；报告称呼由机构内部对照 display_name 提供，无法对照时用"该学员"。
- AI 初稿双闸门：AI 产出的是报告初稿，发出前必须班主任人工复核签字；交付时必须提示复核要求。
- 口径统一纪律：一份报告一套口径，全部指标基于同一快照日期；进步对比基准在报告期注明。
- 克制沟通：H3+H4 占比超 50% 时提示分批触达，避免同日集中向家长发预警引发焦虑与投诉。
- 机构主导：最终是否发送、如何发送报告由机构决定；技能不自动外发任何文件。
