安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install yotta-mirror
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 yotta-mirror。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Yotta Mirror 是一项本地、确定性的分析技能，可将评估结果转化为可执行的教学见解。它会检查输入数据、汇总题目表现、计算按分数加权的知识点掌握率、将学生分为 A/B/C 层级、标记临界情况，并识别潜在薄弱环节。
每项诊断都包含可追溯的证据，例如题号、样本量、掌握率和阈值。核心工作流可离线运行，不会调用模型，并将学生数据保留在本地。Openclaw Skills 用户可以用它自动生成报告，同时确保结论可供审查，并聚焦于改进教学，而非学生排名或评估。

应用场景

分析班级测验、考试或作业，找出可能需要重新讲授的知识点。
找出接近已配置层级边界的学生，以便教师审查其结果。
为教学团队或年级组生成可分享、有证据支持的报告。
使用本地命令行工作流，替代重复的成绩汇总和报告撰写。
在批处理任务或 CI 中运行分析，并将薄弱环节阈值用作门槛。
分享报告输出前，对学生标识符进行匿名化。
在需要可复现的教育数据分析、又不希望将学生数据发送到网络服务时，使用 Openclaw Skills 工作流。

工作原理

验证结构化成绩表和题目映射；针对无效值、重复的学生标识符、超出范围的分数或列不匹配问题，报告相关行或列的详细信息。
计算每道题的作答人数、缺失人数、平均分、得分率，以及满分和零分人数。
按映射的知识点汇总题目得分，并计算按分数加权的掌握率，同时列出相关题目和样本量。
应用已配置的阈值分配 A/B/C 学生层级，并标记接近层级边界、需要审查的学生。
识别低于薄弱环节阈值的知识点。对于样本量较低或处于临界状态的发现，将其降级为人工审查事项，而不将其作为确定结论呈现。
生成人类可读的 Markdown 报告或供自动化使用的 JSON 输出，其中包含发现、支持性证据、待审查事项和免责声明。

配置指南

在 Linux 或 macOS 上使用 Python 3，在 Windows 上使用 python。技能文档提供了直接运行脚本的命令，并未规定单独的包安装步骤。获取代码仓库后，在项目目录中运行脚本。

生成成绩、题目映射和阈值模板

python3 scripts/yotta_mirror.py template --output-dir ./mirror-template

使用题目到知识点的映射分析成绩表

python3 scripts/yotta_mirror.py analyze --input scores.csv --items item-map.json

为自动化写入 JSON；薄弱环节达到 3 个或以上时返回门槛退出码

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
提供带标题行的 CSV 或 TSV 成绩表：第一列为学生标识符，其余列为题目得分；空单元格表示缺失分数。JSON 题目映射为每道题定义 id、max_score 和 knowledge 值，并可选包含 difficulty。阈值配置为可选项。退出码：0 表示成功，1 表示触发门槛，2 表示输入错误，3 表示配置或映射错误，4 表示运行时错误。
Yotta Mirror 学习分析 数据架构与分类体系
文件或来源 格式 用途
成绩或答题纸 CSV/TSV 标题行；第一列为学生标识符，其余列为题目得分。空单元格表示缺失分数。
题目映射 JSON 将每道题映射到 id、max_score 和一个或多个 knowledge 知识点；可包含 difficulty。
阈值包 JSON，可选 配置 mastery.weak_below、mastery.solid_at_or_above、layers.*、min_respondents 和 critical_margin。
输出与组织
模板生成会在选定的输出目录中创建初始文件，可用于录入成绩、设置题目映射和配置阈值。
分析会生成供阅读的 Markdown 报告，也可生成用于归档或自动化的 JSON。JSON 报告包含 schema_version，以确保输出约定稳定。
报告包含题目级统计、知识点掌握情况及其证据、学生层级和临界标记、薄弱环节发现、人工审查事项以及免责声明。
使用 --anonymize 时，学生标识符会替换为可复现的别名，别名由 SHA-256 哈希的前八个字符生成。
字段定义和输入问题排查记录在 references/data-format.md 中；报告字段和退出码说明见 references/report-format.md；隐私指南见 references/privacy.md。
Openclaw Skills 用户可以将 JSON 报告传递给下游自动化流程，同时让分析本身保持在本地。

高级特性

确定性结果：相同的数据和配置会产生相同的结论，生成时间除外。
与证据关联的诊断：薄弱环节发现包含题号、样本量、掌握率和所用阈值。
可配置掌握率、学生层级、最低作答人数和边界审查余量的阈值。
保守的审查处理：样本量较低的发现和接近边界的判断会标记为需人工审查。
CI 和批处理门槛：当达到配置的薄弱环节数量时， --gate weak= 返回退出码 1；其他退出码用于区分输入、配置和运行时错误。
灵活的输入和输出：分析文件或标准输入，输出 Markdown 或 JSON，并对标识符进行匿名化以便分享。
注重隐私的执行方式：核心流程不使用网络、不调用模型，也不会写入外部路径。
仅用于辅助教学：不会生成学生评价、排名、能力标签、录取预测、奖励或惩罚。Openclaw Skills 工作流应保留教师审查，并保留报告中关于预期用途的免责声明。

name: yotta-mirror slug: yotta-mirror version: 0.1.0 displayName: 学情分析·元镜 summary: 本地、确定性的学情分析：成绩 / 答题表 → 知识点掌握率、学生分层与临界生、薄弱点诊断；每条结论带题号 / 样本量 / 掌握率 / 阈值，学生数据不出本机，零依赖。 description: 学情分析（元镜）—— 把成绩 / 答题表与题目-知识点映射，变成可复算、可追溯的诊断报告：数据质量闸门、逐题统计、按分值加权的知识点掌握率、A/B/C 分层与临界生识别、薄弱点诊断（低样本自动降级为人工复核），支持阈值配置、学生标识匿名化与 CI 闸门；零依赖本地运行，不联网、不调用模型，不用于学生评价或排名。 tags: [学情分析, 成绩分析, 作业诊断, 知识点掌握, 班级报告, 分层教学, 临界生, 数据本地化, 证据链, education, learning analytics] license: MIT homepage: https://github.com/YottaMeta/yotta-mirror 元镜（yotta-mirror）

本地、确定性的学情分析技能。元镜把成绩 / 答题表与题目-知识点映射变成一份可复算、可追溯的 诊断报告：既给结论，也给结论背后的题号、样本量、比例与阈值。

可信契约：

每条薄弱点结论都带证据（涉及题号、样本量、掌握率、所用阈值）；
同一份数据、同一份配置得到同一份结论（仅生成时间不同）；
样本量低于阈值、分界线附近的判断一律降级为人工复核项；
核心路径不联网、不调用模型、不写外部路径；学生数据只在本机流转。
何时使用
分析班级测验 / 作业结果，找薄弱知识点与临界生；
把「统计 + 写分析报告」这段耗时的杂活交给自动化流程；
需要一份下发给备课组 / 年级组的学情报告，且要求结论可核查；
把学情分析接入 CI 或批处理（--gate weak= 提供退出码）。

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

按需读取，不必每次全读。

Yotta Lesson (元案)
Voice TTS Studio — 三剪客 Speech TTS