技能介绍

要解决什么问题

心理重建小组通常会在课程前后各发放一次量表问卷，用来衡量干预效果。数据最终落在 Excel 文件里，但每期的文件结构并不统一：列索引会漂移，前后测的维度列名可能只差一个"的"字，总分列在 74 期是第 6 列，到 75 期就变成了第 1 列。人工处理这些文件时，最耗时的不是算均值，而是反复核对哪列对应哪个维度、谁的昵称在前后测里改了字。

本技能解决的就是这个环节的工程化问题：给定一期小组的前测、后测 Excel 文件，自动完成列定位、学员匹配、统计分析，并输出一份 H5 交互页面和一份 Word 评估报告。

技能如何工作

核心处理流程分为几个阶段：

前置校验：确认数据目录、4 个 Excel 文件、维度定义.xlsx、Python3 及依赖包是否就绪。任何一项不满足都会先报错，不进入分析流程。
动态列定位：所有列索引通过关键词搜索获取，包括 find_col(df, '总分') 这类模糊匹配，不假设固定位置。维度列名如 愤怒的情绪 与 愤怒情绪 的差异由模糊匹配处理。
学员匹配：通过 name_map 字典处理前后测昵称变更，通过 anonymous_names 将真实昵称映射为报告中的化名。匹配人数与预期不符时会暂停并列出未匹配昵称。
脚本执行：scripts/generate_reports.py 处理数据并生成 6 张图表及 analysis_data.json；scripts/generate_h5.py 生成 Chart.js 渲染的 H5 页面。
报告组装：Word 报告基于 analysis_data.json 生成，包含封面、项目介绍、执行概况、评估方法、效果分析、小结与附录，并对学员信息匿名化。

适用边界

这个技能的边界划得很清楚：它只做前后测量表数据的描述性统计，不输出诊断结论或个体心理解读。以下场景不在能力范围内：

临床心理诊断或治疗建议
单个学员分数的心理学专业解读
非"100 题 × 6 维度"格式的其他量表
在线问卷发放与数据采集
跨机构或跨量表版本的数据合并

另外有几处工程细节值得注意：后测文件名中的"小组"二字有的期数有、有的没有，需用 glob 搜索；出勤列的值可能是 10次、8次 或纯数字 8，需要用正则提取；matplotlib 缓存目录在 macOS/Linux 下建议指向 /tmp/matplotlib_cache，Windows 下指向 %TEMP%\matplotlib_cache，避免权限问题。

所有数据在本地处理，不上传网络。当文件读取失败时，技能会直接报告"分析失败"并给出原因，不会推测或编造统计数据。