元镜（yotta-mirror）
本地、确定性的学情分析技能。元镜把成绩 / 答题表与题目-知识点映射变成一份可复算、可追溯的
诊断报告：既给结论，也给结论背后的题号、样本量、比例与阈值。
可信契约：
- 每条薄弱点结论都带证据（涉及题号、样本量、掌握率、所用阈值）；
- 同一份数据、同一份配置得到同一份结论（仅生成时间不同）；
- 样本量低于阈值、分界线附近的判断一律降级为人工复核项；
- 核心路径不联网、不调用模型、不写外部路径；学生数据只在本机流转。
何时使用
- 分析班级测验 / 作业结果，找薄弱知识点与临界生；
- 把「统计 + 写分析报告」这段耗时的杂活交给自动化流程；
- 需要一份下发给备课组 / 年级组的学情报告，且要求结论可核查；
- 把学情分析接入 CI 或批处理（
--gate weak=<n>提供退出码）。
Do NOT trigger：
- 不生成学生评语、排名榜、奖惩建议，不给学生贴能力或性格标签；
- 不预测升学结果，不做学业结论性判断；
- 不解析图片 / 扫描件试卷（不做 OCR），输入必须是结构化表格；
- 不上传、不联网、不同步学生数据；跨设备同步属另一条需显式开启的分支，本版不实现；
- 不替代教师判断：报告输出的是数据事实与待复核清单。
快速使用
Windows 使用 python，Linux / macOS 使用 python3。
# 生成录入模板（成绩表 + 题目映射 + 阈值配置）
python3 scripts/yotta_mirror.py template --output-dir ./mirror-template
# 分析一次测验，输出 Markdown 报告
python3 scripts/yotta_mirror.py analyze --input scores.csv --items item-map.json
# 输出 JSON（自动化 / 存档），并按薄弱点数量设闸门
python3 scripts/yotta_mirror.py analyze --input scores.csv --items item-map.json \
--config thresholds.json --format json --out report.json --gate weak=3
# 从标准输入读取，学生标识匿名化后再分享
cat scores.csv | python3 scripts/yotta_mirror.py analyze --stdin --items item-map.json --anonymize
# 校验阈值配置
python3 scripts/yotta_mirror.py config validate --pack thresholds.json
退出码：0 正常 ｜ 1 触发 --gate ｜ 2 输入错误 ｜ 3 配置或映射错误 ｜ 4 运行时错误。
输入与输出
- 成绩 / 答题表：CSV / TSV，首行表头，第一列 = 学生标识，其余列 = 题目；单元格 = 该题得分，留空 = 缺失；
- 题目映射：JSON，声明每题
id/max_score/knowledge（一题可挂多个知识点）与可选difficulty； - 阈值配置（可选）：
mastery.weak_below/mastery.solid_at_or_above/layers.*/min_respondents/critical_margin； - 报告：Markdown（人读）+ JSON（稳定契约，
schema_version），字段定义见references/report-format.md。
字段规范与常见报错对照见 references/data-format.md。
分析模型
- 数据闸门：列与映射不一致、学生重复、非数值、得分越界 → 立即报错并指出行 / 列；
- 逐题统计：作答数、缺失数、平均分、得分率、满分人数、零分人数；
- 知识点聚合：按题目分值加权计算掌握率，输出题号清单与样本量；
- 学生分层：A / B / C 三档 + 分界线附近的临界生标记；
- 薄弱点诊断：掌握率低于阈值 → 生成诊断项（高 / 中严重度）；样本不足 → 人工复核项；
- 报告：结论 + 证据 + 复核清单 + 免责声明。
数据与隐私
- 学生数据默认只在本机读取、分析与落盘：核心路径零网络、零模型调用；
--anonymize用可复算代号（SHA-256 前 8 位）替换学生标识，便于对外分享；- 对外分享前建议只带结论与证据，不带原始姓名；
- 报告固定免责声明：仅用于教学改进，不用于学生评价、排名或升学判断。
详见 references/privacy.md。
家族协同
- 元呈 yotta-present：把学情报告渲染成统一格式（表格 / 结论卡）再交付；
- 元忆 yotta-memory：按需保存报告摘要与阈值配置版本（学生明细自决是否入库）；
- 元规 yotta-compliance：对涉及学生个人信息的材料做条款级合规审查；
- 元真 yotta-humanize：需要发给家长 / 教师的叙述性文字去 AI 味；
- 元阁 yotta-skills：作为编排层把「分析 → 呈现 → 记录」串成一条工作流。
渐进披露
- 字段与报错对照：
references/data-format.md - 报告与 JSON 契约、退出码、闸门：
references/report-format.md - 数据边界与匿名化：
references/privacy.md
按需读取，不必每次全读。
