eduevidence 5.2.0

package/visualization/eduevidence-report/references/lieflat-composition.md

@@ -0,0 +1,79 @@
+# Lieflat Composition — 注册表、契约与推荐组合
+
+EduEvidence 的 Lieflat 画廊是**数据驱动的手作图表组合**：上游 AI 按数据形状自由选型（只能选注册表内图型），渲染器从 `result.json` 提取真实数据渲染成主题化内联 SVG。AI 不直接写数值——所有数字经 `scripts/charts_data.py` 提取器出数，完整性门 `lieflat_data_bound` 逐值核对溯源。
+
+> 上游规范 = `visualization/lieflat-charts/`（Lupi 正本 + mono-tokens）。本文件只记录 EduEvidence 特有规则。
+
+## 1. 注册表（type ↔ 目录编号 ↔ 数据形状 ↔ 提取器）
+
+| `type` | 目录编号 | 数据形状 | 提取器（scripts/charts_data.py） |
+|---|---|---|---|
+| `forest_plot` | FOREST-PLOT (publication figure) | 逐研究 Hedges' g + 95% CI（meta.forest 或 evidence.effect_size） | `meta.forest` |
+| `dot_cascade` | L2 Dot Cascade | 逐研究效应量排序（g + N） | `evidence.ranked_effects` |
+| `bubble_almanac` | L9 Bubble Almanac | 年份 × 结果维度，气泡面积 ∝ 研究数 | `evidence.year_x_dimension` |
+| `jitter_strip` | G15 Jitter Strip | 分组逐条 g 分布（每点一篇研究） | `evidence.grouped_distribution` |
+| `parallel_coordinates` | L20 Parallel Coordinates | 同一批研究跨 g / N / 质量 / 年份 | `evidence.multidim_top` |
+| `hundred_field` | L14 Hundred Field | 100% 构成（单位 = 1 篇研究，总数 ≤100） | `evidence.study_type_composition` |
+| `tick_donut` | F4 Tick Donut | 100% 构成（100 ticks ∝ 份额） | `evidence.wwc_composition` |
+| `tick_rows` | F5 Tick Rows | 各结果正向/负向/零效应计数（每点 1 条证据） | `outcomes.direction_counts` |
+| `rung_bars` | F1 Rung Bars | 各结果方向计数（每格 1 条证据，竖排） | `outcomes.direction_counts` |
+| `paired_rungs` | F6 Paired Rungs | 每结果正负两列对比 | `outcomes.paired_counts` |
+| `brand_spectrum` | L7 Brand Spectrum | 双极维度：位置 = （正向 − 负向）÷ 方向计数 | `outcomes.bipolar_axes` |
+| `barcode_lollipop` | L3 Barcode Lollipop | 16 周 × 阶段归属（柱高 = 阶段序号，无逐日数据不伪造） | `intervention.phase_weeks` |
+| `launch_fan` | L1 Launch Fan | 干预阶段与活动权重（权重 = 活动条数） | `intervention.activity_weights` |
+| `dotty_matrix` | L8 Dotty Matrix | 阶段 × 网格 × 活动（每点 = 1 项活动，强度均匀） | `intervention.phase_groups` |
+| `tick_gauge` | F11 Tick Gauge | 单值 0–100%（决策置信度） | `decision.confidence_score` |
+| `ballot_tally` | L15 Ballot Tally | 各方法学检查项独立计票（每 tick = 1 条审计结论） | `methodology.flag_rates` |
+| `matrix_heat` | L16 Matrix Heat | 年份 × 结果维度 × 计数 | `evidence.year_x_outcome_counts` |
+
+未注册 `type` → 该条被丢弃并写入 `report_spec.json` 的 `visualization_decisions.lieflat_gallery.rejected`，**不静默回退**。M1/M2 地图与 B1–B3 交互大图不进入 EduEvidence 默认画廊。
+
+## 2. `visual_layout` 条目契约
+
+写入 `result.json` 与 `result.zh.json` 的 `visual_layout`（两份文件条目完全相同，双语文本内嵌于每条）：
+
+```json
+{
+  "chart_id": "lieflat-dot-cascade.svg",
+  "type": "dot_cascade",
+  "catalog_ref": "L2 Dot Cascade",
+  "title_zh": "16 篇写作实证的效应量梯队级联",
+  "title_en": "Ranked effect-size cascade of 16 writing studies",
+  "subtitle_zh": "按 g 降序 · 圆点高度 ∝ |g| · 顶部数字 = g · 悬停读样本量",
+  "subtitle_en": "Sorted by g · dot height ∝ |g| · top number = g · hover for sample size",
+  "caption_zh": "梯队数值来自 evidence.effect_size.value 与 sample_size。",
+  "caption_en": "Cascade values from evidence.effect_size.value and sample_size.",
+  "source": "evidence.ranked_effects",
+  "params": {"limit": 12}
+}
+```
+
+规则：
+
+- `chart_id` 唯一；缺省 = `lieflat-<type>.svg`；与学术图键（`outcome-comparison.svg` 等）冲突时自动加 `lieflat-` 前缀。
+- `type` 必须在注册表内；`catalog_ref` 写错只告警并采用注册表值。
+- `title/subtitle/caption` 双语齐备（旧式 `title/subtitle` 双语共用被兼容但告警）。
+- `params` 白名单：`forest_plot{max_studies}`、`dot_cascade/jitter_strip/parallel_coordinates{limit}`、`launch_fan{max_items}`、`tick_rows/rung_bars/paired_rungs/brand_spectrum{outcomes:[…]}`。未知键或类型错误 → 条目被丢弃并记录原因。
+- 标题写结论不写图型名；副标题把图例/单位说清（`·` 分隔）；来源行由渲染器按 `SOURCE · CATALOG_REF` 全大写输出。
+- 每图一个独立结论，总数 ≤6，形状不重复；schema 见 `schemas/visual-layout.schema.json`。
+
+## 3. 数据不足抑制（Meaningful Visualization Gate 镜像）
+
+- 类目 <3、无 CI、无 phase 周区间、无年份、无 audit_items 等 → 该图抑制，原因写入 `report_spec.json` 的 `lieflat_gallery.suppressed`，报告 Brief 中以 `lieflat-suppressed` 块解释「为什么不画」。
+- `visual_layout` 缺失或全无效 → 确定性安全组合 `forest_plot + dot_cascade + bubble_almanac + tick_rows`（同样经提取器出数，数据不足仍逐图抑制），画廊不空。
+- 大样本 → top-N 截断 + `<title>` 悬停读数；不加欺骗性交互。
+- 暗色主题 → SVG 底色 = 主题 `card_bg`，对比度 ≥4.5:1；浅/暗同图同结构仅换色。
+- 无 JS / reduced-motion / 打印 → 图表静态完整可见（motion 模板的 `data-lieflat` 规则覆盖）。
+
+## 4. 三个示例项目的推荐组合样例
+
+- **ai-coding-assistant-50（50 篇，数据最全）**：`parallel_coordinates`（L20 跨维度）+ `jitter_strip`（G15 分布）+ `hundred_field`（L14 设计构成）+ `tick_gauge`（F11 置信度）+ `ballot_tally`（L15 审计计票）+ `matrix_heat`（L16 年份×维度）——六种轮廓全不重复。
+- **highschool-math-ai-tutor（16 篇）**：`forest_plot` + `brand_spectrum`（L7 提速 vs 留存）+ `barcode_lollipop`（L3 四阶段）+ `launch_fan`（L1 活动权重）+ `paired_rungs`（F6 正负对比）。
+- **esl-academic-writing-ai（16 篇）**：`forest_plot` + `dot_cascade`（L2 梯队）+ `bubble_almanac`（L9 年历）+ `tick_rows`（F5 方向分布）+ `dotty_matrix`（L8 阶段点阵）。
+
+## 5. 渲染层不变式
+
+- 渲染器只吃提取器 bundle；`lieflat_engine.render_figure(type, bundle, theme, meta)` 未知 type 抛错。
+- SVG 内无 `<style>`；动画 = `lf-pop/lf-fade/lf-draw` 类 + `--motion-delay` 内联变量（点阵 12ms、条形 100ms stagger），由 `motion/motion.css` 定义曲线（quarticOut 族）。
+- 卡片四件套：结论式标题（700）+ 副标题（图例，`·` 分隔）+ 图 + 全大写加字距来源行；图注可选。
+- SVG 最小字号 6.5px；数值字重 800；面积编码用 sqrt；计数轴整数刻度。

package/visualization/eduevidence-report/references/motion-system.md

@@ -0,0 +1,31 @@
+# Motion System
+
+EduEvidence motion is a fixed presentation template, not per-report decoration.
+
+Allowed roles:
+
+- `section-enter` — one-shot section/chapter reveal.
+- `stagger-enter` — evidence/tribunal/source groups reveal in reading order.
+- `bar-grow` — meaningful comparison bars grow from zero once.
+- `quality-grow` — inline quality meters grow once.
+- `trace-reveal` — Claim → Evidence → Source chains reveal in order.
+- `flow-reveal` — Evidence-to-Action nodes and arrows reveal in order.
+- `detail-expand` — native `<details>` content receives a short opacity/translate reveal.
+- `page-transition` — Visual Brief / Full Report switch uses a short page reveal.
+- `toc-active` — active chapter changes color/border only.
+- `chart-reveal` — `[data-lieflat]` gallery cards follow the Lieflat mono-tokens `obsReveal` contract. **This is a fixed template role; the five themes must not invent alternative chart animation logic.**
+
+`chart-reveal` contract (implemented in `motion/motion.css` + `motion/motion.js`):
+
+- Elements carry `lf-pop` / `lf-fade` / `lf-draw` classes plus an inline `--motion-delay` variable (dot matrices stagger 12 ms, bars 100 ms — the 8–15 ms / 80–130 ms token ranges).
+- Curves are the mono-tokens family: `lf-pop` scale 0→1 with `cubic-bezier(.2,.7,.3,1.3)` 500 ms; `lf-fade` 900 ms ease; `lf-draw` dasharray 1 with `cubic-bezier(.4,0,.2,1)` 1 s.
+- Reveal runs once when the card scrolls into view (IntersectionObserver, threshold .3), gated by the `.js-lf` root class; clicking the card replays the reveal after clearing that card's registered timers (no animation stacking).
+- Without JS, or under `prefers-reduced-motion: reduce`, or in print, every element stays static and fully visible — motion never hides evidence.
+
+Constraints:
+
+- Motion never changes numbers, evidence direction, ordering, adjudication, or chart scale.
+- Every reveal runs at most once per element (except explicit user-requested replay via click on `[data-lieflat]`).
+- `prefers-reduced-motion: reduce` disables nonessential animation.
+- Print disables all animation and exposes detail content.
+- Five visual themes may alter layout and surfaces, but must not invent new motion behaviors.

package/visualization/eduevidence-report/schemas/adapter-envelope.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v5/adapter-envelope.schema.json",
+  "title": "AdapterEnvelope",
+  "description": "Uniform envelope produced by the three zero-dependency visualization adapters (build_charts / build_infographics / build_figures). source_ref is a display alias only; source_sha256 is the provenance that pins the envelope to its exact result.json bytes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "adapter", "contract_version", "source_ref", "source_sha256", "locale", "data"
+  ],
+  "properties": {
+    "adapter": {
+      "type": "string",
+      "enum": ["charts", "infographics", "figures"]
+    },
+    "contract_version": { "type": "string", "const": "1.0" },
+    "source_ref": { "type": "string", "minLength": 1 },
+    "source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "locale": { "type": "string", "enum": ["zh", "en"] },
+    "data": { "type": "object" }
+  }
+}

package/visualization/eduevidence-report/schemas/visual-layout.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/visualization/eduevidence-report/schemas/visual-layout.schema.json",
+  "title": "VisualLayout",
+  "description": "AI-composed Lieflat gallery plan written by the upstream AI into result.json.visual_layout. Entries name a registered chart type, its catalog reference, bilingual copy, data source and renderer params — the AI never writes numbers; the renderer extracts every value from result.json via scripts/charts_data.py. Unregistered types are rejected (no silent fallback).",
+  "type": "array",
+  "minItems": 1,
+  "maxItems": 6,
+  "uniqueItems": true,
+  "items": {
+    "type": "object",
+    "required": ["type"],
+    "oneOf": [
+      {
+        "description": "New bilingual contract (preferred).",
+        "required": ["title_zh", "title_en", "subtitle_zh", "subtitle_en"]
+      },
+      {
+        "description": "Legacy contract (title/subtitle shared across languages; accepted with a warning).",
+        "required": ["title", "subtitle"]
+      }
+    ],
+    "properties": {
+      "type": {
+        "type": "string",
+        "enum": [
+          "forest_plot",
+          "dot_cascade",
+          "bubble_almanac",
+          "jitter_strip",
+          "parallel_coordinates",
+          "hundred_field",
+          "tick_donut",
+          "tick_rows",
+          "rung_bars",
+          "paired_rungs",
+          "brand_spectrum",
+          "barcode_lollipop",
+          "launch_fan",
+          "dotty_matrix",
+          "tick_gauge",
+          "ballot_tally",
+          "matrix_heat"
+        ],
+        "description": "Registered Lieflat chart type (the registry lives in scripts/lieflat_engine.py). Unknown types are dropped with a recorded reason."
+      },
+      "chart_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Stable id for the rendered figure; defaults to lieflat-<type>.svg. Academic figure keys are namespaced automatically."
+      },
+      "catalog_ref": {
+        "type": "string",
+        "description": "Catalog number + name (e.g. 'L2 Dot Cascade', 'G15 Jitter Strip'). Must match the registry value."
+      },
+      "source": {
+        "type": "string",
+        "description": "Extractor source key in scripts/charts_data.py (e.g. 'evidence.ranked_effects'). Defaults to the registry source."
+      },
+      "title_zh": {"type": "string", "minLength": 1},
+      "title_en": {"type": "string", "minLength": 1},
+      "subtitle_zh": {"type": "string", "minLength": 1},
+      "subtitle_en": {"type": "string", "minLength": 1},
+      "caption_zh": {"type": "string"},
+      "caption_en": {"type": "string"},
+      "title": {"type": "string", "minLength": 1},
+      "subtitle": {"type": "string", "minLength": 1},
+      "params": {
+        "type": "object",
+        "description": "Renderer/extractor parameters. Allowed keys per type: forest_plot{max_studies}, dot_cascade{limit}, jitter_strip{limit}, parallel_coordinates{limit}, launch_fan{max_items}, tick_rows/rung_bars/paired_rungs/brand_spectrum{outcomes}. Unknown keys or wrong types reject the entry.",
+        "properties": {
+          "max_studies": {"type": "integer", "minimum": 1, "maximum": 30},
+          "limit": {"type": "integer", "minimum": 3, "maximum": 60},
+          "max_items": {"type": "integer", "minimum": 3, "maximum": 12},
+          "outcomes": {
+            "type": "array",
+            "items": {"type": "string"},
+            "minItems": 1,
+            "description": "Optional filter of outcome_type keys to include."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/visualization/eduevidence-report/scripts/adapter_contract.py

@@ -0,0 +1,72 @@
+"""adapter_contract.py — shared zero-dependency envelope helpers (P1 contract gate).
+
+Every visualization adapter CLI (build_charts / build_infographics /
+build_figures) writes the same envelope through write_adapter_output():
+adapter, contract_version, source_ref, source_sha256, locale, data.
+build_report.py imports the same core functions, so the CLI path and the
+report path can never diverge.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+CONTRACT_VERSION = "1.0"
+ADAPTERS = ("charts", "infographics", "figures")
+
+
+def load_result(path: str) -> dict:
+    """Load a result.json as a JSON object; fail closed with a clear message."""
+    p = Path(path)
+    if not p.exists():
+        print(f"ERROR: result file not found: {path}", file=sys.stderr)
+        sys.exit(2)
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"ERROR: result file is not valid JSON: {path} ({exc})", file=sys.stderr)
+        sys.exit(2)
+    if not isinstance(data, dict):
+        print(f"ERROR: result file must contain a JSON object: {path}", file=sys.stderr)
+        sys.exit(2)
+    return data
+
+
+def result_sha256(path: str) -> str:
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def write_adapter_output(out: str, adapter: str, result_path: str, payload: dict,
+                         locale: str = "zh") -> None:
+    """Validate inputs and write the adapter envelope; never fabricate data."""
+    if adapter not in ADAPTERS:
+        print(f"ERROR: unknown adapter {adapter!r} (expected one of {ADAPTERS})",
+              file=sys.stderr)
+        sys.exit(2)
+    if locale not in ("zh", "en"):
+        print(f"ERROR: locale must be zh or en (got {locale!r})", file=sys.stderr)
+        sys.exit(2)
+    envelope = {
+        "adapter": adapter,
+        "contract_version": CONTRACT_VERSION,
+        "source_ref": Path(result_path).name,
+        "source_sha256": result_sha256(result_path),
+        "locale": locale,
+        "data": payload,
+    }
+    out_path = Path(out)
+    try:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        print(f"ERROR: cannot create output directory {out_path.parent}: {exc}",
+              file=sys.stderr)
+        sys.exit(2)
+    try:
+        out_path.write_text(json.dumps(envelope, ensure_ascii=False, indent=2),
+                            encoding="utf-8")
+    except OSError as exc:
+        print(f"ERROR: cannot write output file {out_path}: {exc}", file=sys.stderr)
+        sys.exit(2)

package/visualization/eduevidence-report/scripts/build_artifact_manifest.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""build_artifact_manifest.py — HTML-03 Artifact Manifest generator.
+
+Validates that every HTML under --html-dir embeds the same result.json SHA-256
+(matching the actual result files) and writes artifact_manifest.json:
+
+    examples/ai-coding-assistant/artifact_manifest.json
+    {
+      "result_sha256": "...", "result_zh_sha256": "...",
+      "renderer_version": "1.0.0", "git_commit": "...",
+      "evidence_count": 13, "source_count": 7,
+      "themes": ["claude", "academic", "datalab", "datalab-dark", "presentation"]
+    }
+
+Usage:
+    python3 visualization/eduevidence-report/scripts/build_artifact_manifest.py \
+        --result examples/ai-coding-assistant/result.json \
+        --result-zh examples/ai-coding-assistant/result.zh.json \
+        --html-dir examples/ai-coding-assistant/reports-5themes \
+        --out examples/ai-coding-assistant/artifact_manifest.json
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from build_report import RENDERER_VERSION, THEME_NAMES, write_artifact_manifest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+
+def git_commit() -> str:
+    try:
+        out = subprocess.run(["git", "rev-parse", "HEAD"], cwd=str(REPO_ROOT),
+                             capture_output=True, text=True, timeout=10)
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate HTML-03 artifact manifest")
+    parser.add_argument("--result", required=True)
+    parser.add_argument("--result-zh", required=True)
+    parser.add_argument("--html-dir", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--renderer-version", default=RENDERER_VERSION)
+    parser.add_argument("--git-commit", default="")
+    args = parser.parse_args()
+
+    html_dir = Path(args.html_dir)
+    html_paths = sorted(
+        p for p in html_dir.glob("EduEvidence_Report_*.html")
+        if any(p.name.endswith(f"_{t}.html") for t in THEME_NAMES))
+    if len(html_paths) != len(THEME_NAMES):
+        print(f"ERROR: expected {len(THEME_NAMES)} theme HTMLs in {html_dir}, found {len(html_paths)}")
+        return 2
+    commit = args.git_commit or git_commit()
+    manifest = write_artifact_manifest(Path(args.result), Path(args.result_zh), html_paths,
+                                       args.renderer_version, commit, Path(args.out))
+    print(f"wrote {args.out}: result={manifest['result_sha256'][:12]}… "
+          f"evidence={manifest['evidence_count']} sources={manifest['source_count']} "
+          f"themes={len(manifest['themes'])} commit={commit or '(none)'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())