eduevidence 5.2.0 → 6.2.0

package/visualization/eduevidence-report/assets/reader.js

@@ -0,0 +1,132 @@
+/* Offline reader: navigation and display only; no research state mutations. */
+(function () {
+  "use strict";
+  var root = document.documentElement;
+  var copy = {
+    zh: {
+      brief: "\u6458\u8981",
+      full: "\u5b8c\u6574\u62a5\u544a",
+      print: "\u6253\u5370",
+      matched: "\u6761\u8bc1\u636e",
+    },
+    en: {
+      brief: "Brief",
+      full: "Full report",
+      print: "Print",
+      matched: "findings",
+    },
+  };
+  function labels() {
+    var lang = root.lang.indexOf("en") === 0 ? "en" : "zh";
+    document.querySelectorAll("[data-copy]").forEach(function (el) {
+      el.textContent = copy[lang][el.dataset.copy];
+    });
+  }
+  labels();
+  new MutationObserver(labels).observe(root, {
+    attributes: true,
+    attributeFilter: ["lang"],
+  });
+  document.querySelectorAll(".reader-print").forEach(function (b) {
+    b.addEventListener("click", function () {
+      window.print();
+    });
+  });
+  document.querySelectorAll(".reader-home").forEach(function (a) {
+    a.addEventListener("click", function (e) {
+      e.preventDefault();
+      window.scrollTo({ top: 0, behavior: "instant" });
+    });
+  });
+  var scheduled = false;
+  function progress() {
+    scheduled = false;
+    var max = document.documentElement.scrollHeight - window.innerHeight;
+    var fraction = max > 0 ? Math.min(1, Math.max(0, window.scrollY / max)) : 0;
+    var bar = document.querySelector(".reader-progress>span");
+    if (bar) bar.style.transform = "scaleX(" + fraction + ")";
+    var shell = Array.from(document.querySelectorAll(".report-shell")).find(
+      function (s) {
+        return getComputedStyle(s).display !== "none";
+      },
+    );
+    if (!shell) return;
+    var blocks = Array.from(shell.querySelectorAll(".brief-block[id]"));
+    var current = blocks
+      .filter(function (b) {
+        return b.getBoundingClientRect().top < 150;
+      })
+      .pop();
+    shell.querySelectorAll(".brief-navigation a").forEach(function (a) {
+      var active = current && a.hash === "#" + current.id;
+      a.classList.toggle("active", !!active);
+      if (active) a.setAttribute("aria-current", "location");
+      else a.removeAttribute("aria-current");
+    });
+  }
+  function queue() {
+    if (!scheduled) {
+      scheduled = true;
+      requestAnimationFrame(progress);
+    }
+  }
+  window.addEventListener("scroll", queue, { passive: true });
+  window.addEventListener("resize", queue);
+  document.addEventListener("click", queue);
+  progress();
+  document.querySelectorAll(".report-view-btn").forEach(function (btn) {
+    btn.addEventListener("click", function () {
+      window.scrollTo({ top: 0, behavior: "instant" });
+    });
+  });
+  document
+    .querySelectorAll(".table-wrap,.evidence-to-action")
+    .forEach(function (el) {
+      el.tabIndex = 0;
+      el.setAttribute("role", "region");
+      el.setAttribute(
+        "aria-label",
+        root.lang.indexOf("en") === 0
+          ? "Scrollable data table"
+          : "\u53ef\u6eda\u52a8\u6570\u636e\u8868",
+      );
+    });
+  document
+    .querySelectorAll('table[id^="evidence-matrix-"]')
+    .forEach(function (table) {
+      var suffix = table.id.replace(/^evidence-matrix-/, "");
+      var counter = document.createElement("p");
+      counter.className = "reader-filter-count";
+      counter.setAttribute("role", "status");
+      counter.setAttribute("aria-live", "polite");
+      table.parentElement.insertAdjacentElement("beforebegin", counter);
+      function count() {
+        var rows = Array.from(table.querySelectorAll("tbody tr"));
+        var visible = rows.filter(function (r) {
+          return r.style.display !== "none";
+        }).length;
+        counter.textContent =
+          visible +
+          " / " +
+          rows.length +
+          " " +
+          copy[suffix.endsWith("en") ? "en" : "zh"].matched;
+      }
+      ["matrix-search-", "matrix-direction-", "matrix-outcome-"].forEach(
+        function (prefix) {
+          var input = document.getElementById(prefix + suffix);
+          if (input) {
+            input.addEventListener("input", count);
+            input.addEventListener("change", count);
+          }
+        },
+      );
+      count();
+    });
+  document
+    .querySelectorAll('a[href^="http:"] , a[href^="https:"]')
+    .forEach(function (a) {
+      a.target = "_blank";
+      a.rel = "noopener noreferrer";
+    });
+})();

package/visualization/eduevidence-report/references/chart-selection-catalog.md

@@ -0,0 +1,109 @@
+# Chart Selection Catalog — AI 选图与表格边界
+
+本目录是 EduEvidence 报告生成阶段的**自包含选图控制面**。AI 可以根据 `result.json` 的数据形状自由组合图表，但只能从运行时注册表中选择；AI 负责“选什么、为什么”，确定性渲染器负责“从哪里取数、怎么画”。
+
+> 核心原则：**图负责模式识别，表负责精确核验。** 不为了“更像数据产品”把所有表格图表化，也不了“严谨”把所有模式藏在大表里。
+
+## 1. Table vs. chart policy
+
+### 必须保留表格 / 展开详情的内容
+
+- `EvidenceMatrix`：Evidence ID / Outcome / Effect / Quality / Claim / Source。
+- `SourceList`：来源标题、年份、authority、canonical location。
+- `MethodologyPanel` / methodology details：审计项的原始判断与备注。
+- `ClaimTrace`：Claim → Evidence → Outcome → Effect → Quality → Source 的精确链路。
+- 任何用户需要逐行复核、复制、引用或追溯的记录。
+
+这些是审计面，不属于“可视化失败”。图表可以总结它们，但不能替代它们。
+
+### 优先使用图表的内容
+
+- 效应量及 CI 的横向比较。
+- 研究/证据在年份、结果维度、设计簻型上的分布。
+- 正向 / 负向 / 零效应的构成或两极差异。
+- 干预阶段、活动数量与时间分布。
+- 单值置信度和方法学检查构成。
+- 多维研究特征的模式发现。
+
+### 不画图的情况
+
+- 数据不足以形成至少一个诚实的视觉关系。
+- 维度单位不可比较或把不同 outcome 合并会制造假结论。
+- 只有一条记录且图表没有比文本/表格增加信息。
+- 缺失值会迫使渲染器填 `0`、补 CI、补趋势或推断因果方向。
+
+此时输出 `VisualizationSuppressed` / `LieflatSuppressed` 和原因，比凑图更正确。
+
+## 2. AI selection protocol
+
+对每个准备表达的**独立结论**执行：
+
+1. **识别数据形状**：g+CI、排序 g+N、年份×维度、逐条分布、100% 构成、方向计数、双极轴、阶段周区间、单值置信度、审计票数等。
+2. **召回候选**：从下表中找语义匹配且提取器有数据的候选。通常比较至少 3 个；如果有效候选本来只有 1–2 个，不得为了满足数量硬凑不合适图型。
+3. **逐项比较**：语义契合、单位诚实、标签容纳、阅读速度、移动端适配、与本批次图型是否重复、数据是否达到 Meaningful Visualization Gate。
+4. **记录淘汰原因**：例如“需要 CI，但当前只有点估计”“类别名过长，不适合竖排”“与上一张同为方向计数，信息重复”。
+5. **选择 ≤6 张**：每张图必须承担不同结论，优先轮廓多样性而非数量；同一数据形状不要堆多个近似图。
+6. **只写计划，不写数值**：AI 只写 `type / catalog_ref / title_zh+en / subtitle_zh+en / caption_zh+en / source / params`。所有数值由 `charts_data.py` 提取。
+7. **让渲染器最终裁决可画性**：注册表未收录、参数非法或数据不足时显式拒绝/抑制，不允许 AI 绕过。
+
+## 3. Registered chart catalog
+
+| `type` | `catalog_ref` | 数据形状 / extractor source | 最适合表达 | 避免使用 |
+|---|---|---|---|---|
+| `forest_plot` | FOREST-PLOT (publication figure) | g + 95% CI · `meta.forest` | 多研究效应与不确定性、零线关系 | 无 CI 时不要伪造区间 |
+| `dot_cascade` | L2 Dot Cascade | 排序 g + N · `evidence.ranked_effects` | 效应量梯队、快速看排序与差距 | outcome/单位不可比时不要混排 |
+| `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% 构成 · `evidence.study_type_composition` | 离散单位组成、研究设计结构 | 总数过大且单位点失去意义时慎用 |
+| `tick_donut` | F4 Tick Donut | WWC 100% 构成 · `evidence.wwc_composition` | 少类别质量/等级份额 | 类别过多或精确比较更重要时不用 |
+| `tick_rows` | F5 Tick Rows | outcome 方向计数 · `outcomes.direction_counts` | 长类目下的正/负/零分布 | 样本点太少且文本更清楚时不用 |
+| `rung_bars` | F1 Rung Bars | outcome 方向计数 · `outcomes.direction_counts` | 紧凑方向计数比较 | 长中文类目或移动端拥挤时优先 tick_rows |
+| `paired_rungs` | F6 Paired Rungs | 正/负成对计数 · `outcomes.paired_counts` | 每 outcome 正负直接对照 | 需要展示大量 null 时不优先 |
+| `brand_spectrum` | L7 Brand Spectrum | 双极位置 · `outcomes.bipolar_axes` | “收益 ↔ 风险/退化”的方向张力 | 不得把 claim support 当正效应 |
+| `barcode_lollipop` | L3 Barcode Lollipop | 周次 × 阶段 · `intervention.phase_weeks` | 干预阶段时间安排 | 没有真实周区间时不补时间点 |
+| `launch_fan` | L1 Launch Fan | 阶段 × 活动权重 · `intervention.activity_weights` | 阶段工作量/活动构成 | “活动条数”不是强度时须在副标题说明 |
+| `dotty_matrix` | L8 Dotty Matrix | 阶段 × 活动点阵 · `intervention.phase_groups` | 阶段结构和活动密度 | 不得把点数解释成效果大小 |
+| `tick_gauge` | F11 Tick Gauge | 0–100% 单值 · `decision.confidence_score` | 已存在的决策置信度 | 不得从证据数量自行计算 confidence |
+| `ballot_tally` | L15 Ballot Tally | 方法学检查计票 · `methodology.flag_rates` | 审计通过/风险项概览 | 不替代方法学原始备注 |
+| `matrix_heat` | L16 Matrix Heat | 年份 × outcome × count · `evidence.year_x_outcome_counts` | 二维覆盖、证据空白和聚集区 | count 不代表效果强弱，标题需避免误导 |
+
+## 4. Recommended candidate families
+
+同一“问题”先在家族内比较，再跨家族避免重复：
+
+- **效应与不确定性**：`forest_plot` / `dot_cascade` / `jitter_strip` / `parallel_coordinates`。
+- **证据分布与覆盖**：`bubble_almanac` / `matrix_heat` / `hundred_field` / `tick_donut`。
+- **结果方向**：`tick_rows` / `rung_bars` / `paired_rungs` / `brand_spectrum`。
+- **干预结构**：`barcode_lollipop` / `launch_fan` / `dotty_matrix`。
+- **决策与方法学摘要**：`tick_gauge` / `ballot_tally`。
+
+示例：如果目标是“不同 outcome 的正负证据差异”，先比较 `tick_rows`、`rung_bars`、`paired_rungs`、`brand_spectrum`；如果类目长且要保留 null，通常 `tick_rows` 更合适；如果核心是两极张力，`brand_spectrum` 更快；如果只想看正负并排，`paired_rungs` 更直接。
+
+## 5. Composition constraints
+
+- 一份报告最多 6 张 AI-composed 图；少而准优先于填满 6 张。
+- 每图对应一个明确问题或结论，不允许仅因“有数据”就画。
+- 同一批次避免重复轮廓：例如已经用 `tick_rows` 讲方向分布，就不要再用 `rung_bars` 重复同一事实，除非第二张回答的是不同问题。
+- 五种主题共享同一个 `visual_layout` 科学结构；主题只能改变版式、色板、表格密度和阅读节奏，不能改变数据、结论、图型含义或 Meaningful Visualization Gate。
+- 报告中的 `EvidenceMatrix`、`SourceList`、方法学详情和 `ClaimTrace` 始终保留可审计入口。
+- 图表数据必须通过 `lieflat_data_bound`；任何 AI 写入的数值都不进入渲染数据面。
+
+## 6. Output contract example
+
+```json
+{
+  "type": "paired_rungs",
+  "catalog_ref": "F6 Paired Rungs",
+  "title_zh": "迁移与保持结果呈现更明显的正负分化",
+  "title_en": "Transfer and retention outcomes show the clearest directional split",
+  "subtitle_zh": "每格 = 1 条已提取证据 · 正向与负向并列",
+  "subtitle_en": "1 cell = 1 extracted finding · positive and negative shown side by side",
+  "caption_zh": "仅展示已记录的 effect_direction，不根据 claim relation 推断方向。",
+  "caption_en": "Uses recorded effect_direction only; claim relation never determines effect direction.",
+  "source": "outcomes.paired_counts",
+  "params": {}
+}
+```
+
+AI 选择图型后，仍由 `references/lieflat-composition.md`、`schemas/visual-layout.schema.json`、`charts_data.py` 与 `lieflat_engine.REGISTRY` 共同执行机械校验。

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

@@ -2,10 +2,12 @@
 
 EduEvidence 的 Lieflat 画廊是**数据驱动的手作图表组合**：上游 AI 按数据形状自由选型（只能选注册表内图型），渲染器从 `result.json` 提取真实数据渲染成主题化内联 SVG。AI 不直接写数值——所有数字经 `scripts/charts_data.py` 提取器出数，完整性门 `lieflat_data_bound` 逐值核对溯源。
 
-> 上游规范 = `visualization/lieflat-charts/`（Lupi 正本 + mono-tokens）。本文件只记录 EduEvidence 特有规则。
+> AI 选图规范已内置于 `chart-selection-catalog.md`；本文件记录可执行注册表、数据契约与渲染不变量。任何外部图库只可作为设计灵感，不能成为运行时依赖。
 
 ## 1. 注册表（type ↔ 目录编号 ↔ 数据形状 ↔ 提取器）
 
+选图前先读 `chart-selection-catalog.md`：表格负责逐行审计，图表负责模式表达；AI 通常比较至少 3 个**可行**候选并记录淘汰理由，但候选不足时不得为凑数量选择错误图型。
+
 | `type` | 目录编号 | 数据形状 | 提取器（scripts/charts_data.py） |
 |---|---|---|---|
 | `forest_plot` | FOREST-PLOT (publication figure) | 逐研究 Hedges' g + 95% CI（meta.forest 或 evidence.effect_size） | `meta.forest` |

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

@@ -32,7 +32,7 @@ from pathlib import Path
 from typing import Any
 
 from adapter_contract import load_result, write_adapter_output
-from zh_labels import zh_outcome
+from zh_labels import label
 from build_charts import effect_outcomes
 
 OKABE_ITO = ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7", "#000000"]
@@ -82,7 +82,26 @@ def _linear_ticks(maxv: int) -> list[int]:
     return ticks
 
 
+def _caption_width(caption: str, font_size: int = 11) -> int:
+    """Conservative width of an italic caption line at the SVG font stack.
+
+    The caption is a single unwrapped line, so a long title used to run past
+    the fixed 720px canvas and get clipped. CJK glyphs are a full em wide;
+    latin is bounded by the same cap-height factor used elsewhere in this
+    module.
+    """
+    cjk = sum(1 for ch in caption if "\u4e00" <= ch <= "\u9fff")
+    latin = len(caption) - cjk
+    # 0.75em is the measured upper bound for the latin part of the stack
+    # (Helvetica/Arial italic); ~2 full-width latin words at the start of the
+    # caption also shift the whole line right by the x=20 origin.
+    return int(cjk * font_size + latin * font_size * 0.78) + 60
+
+
 def _figure_svg(title: str, caption: str, body: str, w: int = 720, h: int = 300) -> str:
+    # Grow (never shrink) the canvas so the unwrapped caption fits instead of
+    # being cut off at the right edge; the body keeps its designed layout.
+    w = max(w, _caption_width(caption))
     return (f'<svg viewBox="0 0 {w} {h}" xmlns="http://www.w3.org/2000/svg" role="img" '
             f'aria-label="{_esc(caption)}">'
             f'<rect width="{w}" height="{h}" fill="#FFFFFF"/>'
@@ -337,8 +356,11 @@ def render_figures(figure_data: dict, theme: str = "okabe_ito", lang: str = "zh"
     # 绝不把 relation_to_claim 的 support/contradict 当作 outcome 好坏；计数轴整数刻度。)
     outcomes = figure_data.get("outcomes", [])
     if outcomes:
-        names = [zh_outcome(o["outcome_type"]) if lang == "zh"
-                 else o["outcome_type"] for o in outcomes]
+        # Both locales render a curated label. The English axis used to print
+        # the storage token ("knowledge_gain") because only zh went through
+        # OUTCOME_ZH; the English report then showed raw enum values as its
+        # headline comparison chart's axis.
+        names = [label(lang, "outcome", o["outcome_type"]) for o in outcomes]
         series = [{"name": s["name"],
                    "data": [o.get(s["data"], 0) for o in outcomes]}
                   for s in DIR_SERIES[lang]]

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

@@ -160,7 +160,11 @@ def tribunal_svg(verdict: dict, lang: str = "zh") -> str:
     none_text = labs["none"]
     can = verdict.get("supported_claims") or verdict.get("what_can_be_claimed") or [none_text]
     cannot = verdict.get("contradicted_claims") or verdict.get("what_cannot_be_claimed") or [none_text]
-    action = verdict.get("recommended_action", "insufficient_evidence").upper()
+    # The badge is a reader-facing label, so it goes through the same curated
+    # action table as the rest of the report instead of shouting the storage
+    # token. `.upper()` used to print "PILOT" on the Chinese infographic.
+    action_raw = verdict.get("recommended_action", "insufficient_evidence")
+    action = str(label(lang, "action", action_raw) or action_raw)
 
     def col(x: int, title: str, items: list[str], color: str) -> str:
         ids = _evidence_ids(items)