# @yottameta/yotta-mirror > YuanJing (yotta-mirror) — a local, deterministic learning-diagnostics skill for AI agents: reads a CSV / TSV score or answer sheet plus an item-to-knowledge map, runs a data gate, per-item statistics, score-weighted knowledge mastery, student layers with Latest version **0.1.0** (published 2026-09-24) · MIT license · 0 weekly downloads ## Install ```sh npm install @yottameta/yotta-mirror pnpm add @yottameta/yotta-mirror yarn add @yottameta/yotta-mirror bun add @yottameta/yotta-mirror ``` Provides the command `yotta-mirror`. ## Health **Score 60/100 (C)** — status: active. Positive: no vulnerabilities; has provenance; recently updated; high maintenance score. Warnings: low downloads; no types; no esm support; pre 1.0. ## Facts | | | |---|---| | Version | 0.1.0 | | Published | 2026-09-24 | | First published | 2026-09-24 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Unpacked size | 244.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 0 | | Maintainers | yottameta | | Keywords | agent-skills, yotta-mirror, yottaskills, learning-analytics, education | ## Links - npm: https://www.npmjs.com/package/@yottameta/yotta-mirror - Repository: https://github.com/YottaMeta/yotta-mirror - Homepage: https://github.com/YottaMeta/yotta-mirror#readme - Issues: https://github.com/YottaMeta/yotta-mirror/issues - npm.io page: https://npm.io/package/@yottameta/yotta-mirror ## Recent versions - 0.1.0 (latest) — 2026-09-24 - 0.0.0 — 2026-09-24 ## README

Language: English · 中文

yotta-mirror banner

yotta-mirror · 元镜 (YuanJing)

YottaMeta's deterministic learning-diagnostics skill: turn a score / answer sheet plus an item-to-knowledge map into a reproducible diagnosis report where every weak-point conclusion carries its item ids, sample size, rate and threshold.

Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; student data stays on your machine — no network, no model calls, no upload.

License: MIT Standard: agentskills.io npm package GitHub stars

## What it is yotta-mirror reads a structured score sheet (CSV / TSV / stdin) and an item-to-knowledge map, then runs a deterministic pipeline: data gate → per-item statistics → score-weighted knowledge mastery → student layers and borderline students → weak-point diagnosis with evidence → Markdown / JSON report. It is a teaching-improvement aid, not a student evaluation tool. It never produces rankings, comments, or predictions, and every conclusion can be re-computed from the archived inputs. ## Core value - **Evidence for every conclusion** — each weak point lists its items, respondents, rate and the threshold used. - **Deterministic** — the same data and thresholds produce the same report; only `generated_at` changes. - **Explicit thresholds** — mastery, layer and sample-size thresholds come from a JSON config and are echoed into the report. - **Human review by default** — low-sample statistics and borderline students are downgraded to review items instead of conclusions. - **Privacy first** — local-only, zero network imports, `--anonymize` for shareable reports. - **Stable JSON contract** — fixed top-level schema for automation, archiving and CI gates. ## Quick start Windows uses `python`, Linux / macOS use `python3`. ```bash # 1. Create input templates (score sheet + item map + thresholds) python3 scripts/yotta_mirror.py template --output-dir ./mirror-template # 2. Analyse one quiz and print a Markdown report python3 scripts/yotta_mirror.py analyze --input scores.csv --items item-map.json # 3. Emit JSON and fail CI when 3 or more weak knowledge points appear python3 scripts/yotta_mirror.py analyze --input scores.csv --items item-map.json \ --format json --out report.json --gate weak=3 # 4. Share a report without student identifiers python3 scripts/yotta_mirror.py analyze --input scores.csv --items item-map.json --anonymize ``` ## Commands | Command | Description | |---|---| | `analyze --input ` | Analyse a CSV / TSV score sheet | | `analyze --stdin` | Read the score sheet from standard input | | `analyze --items ` | Item-to-knowledge map (required) | | `analyze --config ` | Override mastery / layer / sample-size thresholds | | `analyze --format md\|json` | Markdown (default) or JSON report | | `analyze --out ` | Write the report to a file instead of stdout | | `analyze --anonymize` | Replace student identifiers with reproducible codes | | `analyze --gate weak=` | Exit code 1 when the weak-point count reaches `n` | | `template --output-dir ` | Write starter score sheet, item map and thresholds | | `config validate --pack ` | Validate a thresholds file | | `--version` | Print the engine version | Exit codes: `0` ok ｜ `1` gate triggered ｜ `2` input error ｜ `3` config / map error ｜ `4` runtime error. ## Input format ```csv student,T1,T2,T3 S01,5,3,2 S02,5,3, ``` - First column = student identifier; the remaining columns are item ids that must match the item map. - A cell is the score for that item; blank cells count as missing and are reported separately. - Judgement items use `0` / `1` with `max_score = 1`. ```json { "schema_version": "1.0", "items": [ {"id": "T1", "max_score": 5, "knowledge": ["有理数运算"], "difficulty": "easy"}, {"id": "T2", "max_score": 3, "knowledge": ["有理数运算", "计算"]} ] } ``` See [references/data-format.md](references/data-format.md) for the full schema and the error message table. ## Report contract Markdown sections: input summary → per-item statistics → knowledge mastery → student layers → weak-point diagnosis → human review → disclaimer. JSON top-level keys: `schema_version`, `tool`, `tool_version`, `generated_at`, `input`, `quality`, `items_stats`, `knowledge`, `layers`, `diagnoses`, `review_items`, `summary`, `thresholds`, `disclaimer`. Full field list, decision rules and exit codes: [references/report-format.md](references/report-format.md). ## Privacy - Student data never leaves the machine: the engine imports no network library and calls no model. - `--anonymize` replaces identifiers with `S-` + the first 8 hex digits of their SHA-256, so codes are reproducible within a dataset but not reversible across datasets. - Reports carry a fixed disclaimer: for teaching improvement only — not for student evaluation, ranking or admission decisions. Details and a safety checklist: [references/privacy.md](references/privacy.md). ## Installation ### Option 1 — npx (recommended) ```bash npx -y @yottameta/yotta-mirror --agent codex # or: --agent claude | cursor | gemini | opencode ... npx -y @yottameta/yotta-mirror --dir ``` ### Option 2 — git clone ```bash git clone https://github.com/YottaMeta/yotta-mirror.git /yotta-mirror ``` ### Option 3 — Download ZIP Download ZIP from https://github.com/YottaMeta/yotta-mirror and extract it into your agent's skills directory. ### Option 4 — install.sh ```bash bash install.sh --list # show agent → default directory bash install.sh --agent codex # install for one agent bash install.sh --dir # install into an explicit directory ``` ## Works with - **yotta-present** — render the diagnostics report into a consistent, copyable layout; - **yotta-memory** — store report summaries and threshold versions on request; - **yotta-compliance** — clause-level review for materials that contain student personal information; - **yotta-humanize** — natural-language polish for teacher-facing narratives; - **yotta-skills** — orchestrate analyse → present → record as one workflow. ## Requirements - Python 3.8+ (standard library only) - UTF-8 encoded CSV / TSV input; no extra packages, no database, no service ## License MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). --- _Source: https://npm.io/package/@yottameta/yotta-mirror · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._