eduevidence 5.2.0

package/README.zh-CN.md

@@ -0,0 +1,434 @@
+# EduEvidence
+
+> **🌐 [English](README.md) | 中文**
+
+## EduEvidence Research Engine — Evidence-Based Education Decision Skill
+
+> **From Education Questions to Evidence-Based Decisions.**
+> **从教育问题，到有证据支撑的教育决策。**
+
+EduEvidence 面向教师、教学研究者与教学管理者，把"是否采用某教学法、课程设计、评估方式或 AI 教学工具"从经验判断转化为**可追溯、可质疑、可验证的证据决策流程**——教学法、课程、评估、学习干预与 AI 工具均是应用域，引擎方法学教育通用。
+
+- ⚖️ 不是替教师生成答案，而是帮助教师知道：证据支持什么、不能支持什么、适用于谁、应该怎样试点并验证。
+- 🧪 基于真实研究（示例包含 CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 的实证证据），不做无来源断言。
+- 🚦 最终输出不是"允许/禁止"的二元结论，而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的教学干预与评价方案。
+
+![EduEvidence 顶层宣传图](assets/top-banner.jpg)
+
+---
+
+## 快速安装
+
+**方式一：npm（推荐 — 安装为 Agent Skill）**
+
+```bash
+npm install -g eduevidence
+eduevidence skill                  # 交互式选择宿主（默认）
+eduevidence skill --list-hosts     # 或先查看全部宿主与落点
+# 非交互：eduevidence skill --host cursor
+```
+
+**方式二：curl 一键安装**
+
+> ⚠️ 供应链提示（E7）：curl 直跑等于执行远端脚本。更稳妥的方式是**方式二 clone 后
+> 先审阅再安装**；若坚持直跑，建议把 URL 固定到具体 commit 并先下载审阅。
+
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/37chengshan/eduevidence/main/install.sh)"
+```
+
+脚本自动 clone 仓库到 `./eduevidence` 并完成安装（venv + 依赖 + 自检 + 测试）。
+副作用披露：会在 `~/.eduevidence/env` 写入 `AGENT_MCP_INSTALLED=1` 声明；
+`--skill` 模式覆盖已有 skill 前自动备份。
+
+**方式三：git clone**
+
+```bash
+git clone https://github.com/37chengshan/eduevidence.git
+cd eduevidence
+bash install.sh              # 一键：venv + 依赖 + 自检 + 测试
+```
+
+安装后直接打开示例报告：
+
+```bash
+open examples/ai-coding-assistant/EduEvidence_Report.html
+```
+
+> 需要 Python 3.10+；核心零第三方依赖。学术图 PNG/PDF 导出可选装 matplotlib。
+> 安装完成后脚本会提示为项目点 star（仅提示，不会自动执行任何 GitHub 操作）。
+> ⚠️ 管道执行远程脚本以当前用户权限运行，建议先审阅 [install.sh](install.sh) 或用 git clone。
+
+---
+
+## 安装为 Skill（AI Agent 用户）
+
+> EduEvidence 本体是一个 **AI Agent Skill**（SKILL.md + skill/agents/ + references/ + schemas/ + scripts/ + retrieval/ + integrations/ + visualization/）。
+> 安装后，你的宿主 Agent（Claude Code / OMP / Codex / OpenCode / Kimi / ZCode / OpenClaw / Harness / Grok / Copilot / Cline …）就能在收到教学决策类问题时自动装载本 Skill。
+
+```bash
+npm install -g eduevidence
+eduevidence skill                  # 交互式选择宿主（默认）
+eduevidence skill --list-hosts
+eduevidence skill --dry-run
+eduevidence skill --host cursor    # 可选：跳过菜单，直接指定宿主
+```
+
+或从 git clone 目录：
+
+```bash
+bash install.sh --skill              # 交互式选择安装到哪个 Agent
+bash install.sh --list-hosts         # 查看支持的 Agent 与 Skill 落点
+bash install.sh --skill --host claude
+bash install.sh --skill --dry-run    # 只预览不写入
+```
+
+也可以不经 clone 直接远程执行（⚠️ 供应链提示见上：优先 clone + 审阅；直跑请固定 commit）：
+
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/37chengshan/eduevidence/main/install.sh)"
+```
+
+安装前脚本会自动备份目标目录中已有的 skill（`cp -r` 到 `.bak-<时间戳>`）；`--dry-run` 只预览不写入。
+
+### 支持的 Agent 与配置落点
+
+| Agent | 探测路径 | Skill 安装落点 |
+|---|---|---|
+| Cursor | `~/.cursor` | `~/.cursor/skills/eduevidence/` |
+| Claude Code | `~/.claude` | `~/.claude/skills/eduevidence/`（无用户级配置则装到项目 `.claude/skills/`）|
+| Codex | `~/.codex` 或 `codex` 命令 | `~/.agents/skills/`（兼容 `~/.codex/skills/`、`~/.codex/prompts/`）|
+| OMP | `~/.omp` | `~/.omp/agent/skills/eduevidence/` |
+| OpenCode | `~/.config/opencode` | `~/.config/opencode/skills/eduevidence/` |
+| Kimi Code | `$KIMI_CODE_HOME` 或 `~/.kimi-code` | `~/.kimi-code/skills/eduevidence/` |
+| ZCode | `~/.zcode` | `~/.zcode/skills/eduevidence/` |
+| OpenClaw | `~/.openclaw` | `~/.openclaw/skills/eduevidence/` |
+| Harness | `~/.harness` | `~/.harness/skills/eduevidence/` |
+| Grok | `~/.grok` | `~/.grok/skills/eduevidence/` |
+| GitHub Copilot CLI | `~/.copilot` | `~/.copilot/skills/eduevidence/` |
+| Cline | `~/.cline` 或 `~/.config/cline` | `~/.cline/skills/eduevidence/` |
+
+交互菜单中：选择 `all` 安装到全部 Agent；`custom` 手动指定 skill 目录；`local` 只装本地（venv + pytest + 自检）。
+
+### 方式三：通用提示词（未列出的 Agent）
+
+你的 Agent 不在列表里？把下面这段提示词**原样**交给任意支持 skill / 自定义指令的 AI，它会读取 [安装指南](docs/install-guide.md) 自行完成安装：
+
+```text
+请按照 https://github.com/37chengshan/eduevidence/blob/main/docs/install-guide.md
+的安装指南，为我把 EduEvidence 安装为 skill：先读取该文档，按第 2 节的落点表
+把 SKILL.md、skill/、references/、schemas/、scripts/、retrieval/、integrations/、
+visualization/ 复制到我的 skill 目录（或按我的装载机制导入），然后按第 3 节
+完成验证（SKILL.md 可读 + 脚本可运行 + 示例报告可渲染）。
+```
+
+## What Problem We Solve
+
+普通 AI 面对教育问题通常执行：
+
+```text
+问题 → 搜索若干材料 → 总结观点 → 给出建议
+```
+
+EduEvidence 执行：
+
+```text
+教学问题
+  → Education Research Framing（学习者/干预/对照/Outcome/场景）
+  → 文献与证据检索（支持证据 + 独立反方证据）
+  → Claim-Level Evidence Extraction
+  → Skeptic 反证协议 + Method Reviewer 方法学审查
+  → Evidence Tribunal（证据裁决）
+  → Applicability Analysis（适用性）
+  → Decision: ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE
+  → Teaching Intervention（最小可验证试点）
+  → Evaluation Plan（效果评价）
+```
+
+最终回答六个问题：
+
+1. 当前证据到底支持什么？
+2. 当前证据不能支持什么？
+3. 为什么不同研究会得到不同结果？
+4. 对哪类学生、什么课程、什么条件适用？
+5. 如果学校真的要用，怎样低风险落地？
+6. 实施后如何验证它到底有没有效果？
+
+## 30-second Demo
+
+> 主 Demo：**大一 C 语言课程是否应该允许学生使用生成式 AI 编程助手？**
+
+| 时间 | 阶段 |
+|---|---|
+| 0–20s | 输入教学问题 |
+| 20–45s | Education Research Frame |
+| 45–75s | Evidence Retrieval |
+| 75–110s | Evidence Matrix |
+| 110–135s | Methodology + Skeptic |
+| 135–155s | Evidence Tribunal |
+| 155–170s | Teaching Intervention + Evaluation |
+| 170–180s | Benchmark |
+
+完整示例包见 [`examples/ai-coding-assistant/`](examples/ai-coding-assistant/)。
+
+## Why Education Evidence Is Hard
+
+教育研究证据有几个天然陷阱，EduEvidence 的核心创新就是把应对这些陷阱的环节标准化：
+
+- **Outcome Separation**：`代码完成更快 ≠ 真正学会编程`；`短期成绩提高 ≠ 长期保持提高`；`AI 协助完成任务 ≠ 无 AI 环境下能够迁移`。
+- **Counter-Evidence Search**：不能只验证用户的最初假设，必须独立寻找 null / negative / contradictory 证据、AI dependency、novelty effect、self-selection bias 等。
+- **Evidence Tribunal**：不是简单把正反论文列在一起，而是判断哪些研究更可信、冲突来自样本/测量/课程/工具还是实验设计、目前最多能得出什么结论。
+- **Evidence-to-Action Bridge**：不能停在"研究显示……"，必须连到适用性判断、教学决策、试点干预与评价设计。
+
+## How EduEvidence Works
+
+```text
+┌─────────────────────────────────────┐
+│            EduEvidence              │
+│  教育领域知识 + 决策 + 干预 + 评价   │
+└────────────────┬────────────────────┘
+                 │
+┌────────────────▼────────────────────┐
+│        EvidenceFlow Protocol        │
+│ Frame / Retrieve / Extract /        │
+│ Challenge / Audit / Adjudicate      │
+└────────────────┬────────────────────┘
+                 │
+        ┌────────┴────────┐
+        ▼                 ▼
+ Platform Native      Agent MCP
+ Execution Mode      Enhanced Mode
+```
+
+完整工作流（9 步）：
+
+```text
+1. Frame          构建 EducationResearchFrame
+2. Retrieve       文献与证据检索（支持证据 + 独立反方证据）
+3. Extract        抽取 Claim-Level Evidence（绑定 Outcome）
+4. Challenge      Skeptic 反证协议（固定 9 项检查）
+5. Audit          Method Reviewer 方法学审查（15 项清单）
+6. Adjudicate     Evidence Tribunal 证据裁决（Evidence Matrix + Verdict）
+7. Applicability  适用性分析
+8. Intervene      Teaching Intervention 设计（最小可验证试点）
+9. Evaluate       Evaluation Plan 设计
+```
+
+每一步产出经过 JSON Schema 校验（`schemas/`），确定性逻辑由 `scripts/` 提供，教育方法论在 `references/` 中独立成文。
+
+## Outcome Separation
+
+EduEvidence 强制区分 20 类 Outcome（`references/outcome-taxonomy.md`）：
+
+```text
+学习效果:   Knowledge Gain / Concept Understanding / Retention / Transfer / Independent Problem Solving
+任务表现:   Completion Time / Accuracy / Code Quality / Assignment Score
+学习过程:   Engagement / Motivation / Cognitive Load / Help-Seeking / Metacognition
+风险指标:   AI Dependency / Over-reliance / Reduced Effort / Reduced Transfer / Academic Integrity Risk / False Confidence
+```
+
+主 Demo 的高光点正是这种区分：Kazemitabaar et al. (CHI 2023) 中 AI 代码助手使任务完成率提升 1.15×、得分提升 1.8×，但一周后的保持测试差异不显著——**任务表现 ≠ 学习效果**。
+
+## Evidence Tribunal
+
+`references/tribunal-policy.md` 定义了裁决规则：输入 Frame + Evidence Matrix + Skeptic Findings + Method Reviews，输出 EducationVerdict（`schemas/verdict.schema.json`），包括：
+
+- supported / uncertain / contradicted claims
+- 冲突来源分析（样本 / 测量 / 课程 / 工具 / 实验设计）
+- Can Claim / Cannot Claim 边界
+- 四态决策 + Confidence（规则化计算，不由模型自由生成）
+
+![Evidence Tribunal Workflow](assets/tribunal-workflow.jpg)
+
+## From Evidence to Action
+
+证据必须连接到真实教学现场（`references/applicability-policy.md`、`intervention-design.md`、`evaluation-design.md`）：
+
+- **Applicability**：For whom? For which course? For which outcome? Under what conditions? With what AI usage policy?
+- **Intervention**：永远是"最小可验证试点"，禁止直接全面部署；含 AI 使用规则、教师/学生角色、反思要求、停止条件。
+- **Evaluation**：任何 PILOT/ADOPT 建议必须附评价方案；区分基线/后测/保持测试/迁移测试；区分任务表现指标与学习指标。
+
+## Benchmark
+
+第一版 30 个教育研究问题（`benchmarks/questions.jsonl`），S×10 / M×10 / L×10；其中 15 题为主域"高校 AI 辅助教学"，30 题全部含人工金标注（`benchmarks/annotations/gold-Q01..Q30`）。
+
+基线设计：
+
+```text
+B0 Direct LLM
+B1 Search + LLM
+B2 Standard Research Agent
+B3 EduEvidence Single-Agent     ← 证明教育方法论价值（B2 vs B3）
+B4 EduEvidence + Agent MCP      ← 证明多 Agent 增强价值（B3 vs B4）
+```
+
+核心指标：Citation Support Precision / Unsupported Claim Rate / Contradiction Discovery Rate / Outcome Separation Accuracy / Scope Calibration / Intervention Evidence Alignment。详见 `docs/benchmark.md`。
+
+> ⚠️ `benchmarks/results/` 仍为 **harness validation（deterministic simulation，标注 SIMULATED）**，仅证明评测框架可运行，不是真实模型性能。**首轮 Layer B 实证运行已启动**（B2 vs B3，10 题 × 3 次，`omp` 驱动 `deepseek-v4-flash`——见 `benchmarks/empirical/run-empirical-01`，报告见 `benchmarks/empirical/v3-report.md`）。指标为 gold-based 启发式（`method: heuristic`），结果仍受模型与题目集限制，运行结果复核前不作定论性效果宣称。
+
+## Example: AI Coding Assistant
+
+> **大学一年级 C 语言课程是否应该允许学生使用生成式 AI 编程助手？**
+
+`examples/ai-coding-assistant/` 完整展示了从问题到决策的全过程：
+
+- **证据**（7 条，均绑定真实来源）：任务表现提升（Kazemitabaar 2023）、无护栏访问损害独立考试表现 -17%（Bastani 2025, PNAS）、护栏设计消除负效应（Bastani 2025）、形成性反馈写作证据（Marzuki 2024）。
+- **决策**：**PILOT** —— 任务表现证据强，但大学编程课程的直接学习效应证据缺失，无护栏风险已被证实。
+- **干预**：4 阶段试点（Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check）。
+- **评价**：无 AI 基线/后测/期末考试保持/无 AI 迁移任务 + AI 依赖风险指标。
+
+另外两个示例：AI 写作助手（`examples/ai-writing-assistant/`）、高数 AI Tutor（`examples/ai-tutor/`）——证明 Skill 不是为一个问题写死。
+
+## Visualization: Bilingual HTML Report + Infographics + Academic Figures
+
+After research completes, `result.json` is rendered by three deterministic Python adapters. The adapters use the standard library; the optional Web Studio chart enhancement has a separate browser dependency.
+
+```text
+result.json + result.zh.json
+  ├─ build_charts.py        → chart_specs.json (ECharts option data; no ECharts runtime bundled)
+  ├─ build_infographics.py  → infographics.json (hand-authored SVGs)
+  ├─ build_figures.py       → figures/ (publication figures: figure_data.json + SVG/PNG/PDF)
+  └─ build_report.py        → EduEvidence_Report.html (single-file bilingual report + report_spec.json)
+```
+
+**EduEvidence_Report.html (main deliverable)**:
+
+- **Bilingual switch**: Chinese by default, one click to EN; data remains isomorphic.
+- **Executive summary narrative**: question → evidence → action, with traceable source sections.
+- **Two-page layout**: Visual Brief + Full Report (AI-planned 5–7 dynamic chapters, not a fixed template).
+- **Five styles (chosen at generation time, no in-HTML switcher)**: claude / academic / datalab / datalab-dark / presentation.
+- **Static-first**: decision, matrix, tribunal, intervention and sources remain readable without JavaScript; ECharts is an optional enhancement.
+- **Integrity gate**: chart numbers are checked against result.json item by item; publishing is blocked with `REPORT_INVALID` on mismatch.
+
+**Local Web Studio** (`python3 scripts/dashboard_server.py --port 8765`) has exactly three read-only views: Dashboard, Report Browser and Data Visualization. It loads ECharts 5.4.3 from jsDelivr for interactive charts; the submission package does not bundle that runtime, so Web interactivity requires network access. The baked report's static HTML/SVG remains the offline artifact.
+
+> Open the example directly: `examples/ai-coding-assistant/EduEvidence_Report.html`
+
+## Architecture
+
+仓库是一个完整的 **Skill 包**：`SKILL.md` 是入口，其余目录按"Skill 运行必需 → 质量保障 → 演示"分层。详见 [`docs/architecture.md`](docs/architecture.md)：
+
+```text
+EduEvidence/  （= 一个 Skill 包）
+│
+├─ SKILL.md                  ← Skill 入口：When to Use / Inputs / 9 步 Workflow / 输出契约
+│
+├─ Skill 本体（运行必需）
+│  ├─ skill/agents/          8 个角色协议（Planner / Retriever / Analyst / Skeptic /
+│  │                         Method Reviewer / Judge / Intervention Designer / Evaluation Designer）
+│  ├─ references/            11 个教育方法论文档（证据质量 / 反证协议 / 裁决规则 / 干预设计…）
+│  ├─ schemas/               33 个 JSON Schema 数据契约（13 顶层 + 17 v2 + 3 v3，每步输出的校验门）
+│  ├─ scripts/               17 个确定性逻辑脚本（评分 / 矩阵 / 审计 / 置信度 / Orchestrator / 启动探测）
+│  ├─ retrieval/             检索与抓取层（fetch / validate / dedupe / failures）
+│  ├─ integrations/          Agent MCP 增强层 + Smart Web Fetch 集成
+│  └─ visualization/         结果呈现层（ECharts / 信息图 / 学术图 / 双语 HTML Composer）
+│
+├─ 质量保障
+│  ├─ tests/                 pytest 测试矩阵（752 个测试函数，73 个文件，见 docs/metrics.json）
+│  └─ benchmarks/            30 题 + 30 份金标注 + B0–B4 评测框架
+│
+└─ 演示与分发
+   ├─ examples/              3 个完整 Research & Decision Pack（含双语 HTML 报告）
+   ├─ docs/                  架构 / 方法论 / Benchmark / Demo / 复现指南
+   ├─ install.sh             一键安装（本地 / 多 Agent Skill）+ 自检
+   ├─ pyproject.toml         打包元数据（核心零第三方依赖）
+   └─ README(.en).md         双语说明
+```
+
+> Skill 包设计原则：**运行所需的最小集是 `SKILL.md + skill/ + references/ + schemas/ + scripts/`**；`retrieval/`、`integrations/`、`visualization/` 是让 Skill 真正"可运行、可呈现"的执行层；`tests/`、`benchmarks/`、`examples/`、`docs/` 是可信度与上手保障，不影响 Skill 本体。
+
+### SCP / Platform Native Mode
+
+EduEvidence 可完全脱离 Agent MCP 独立运行（无需任何外部服务）：
+
+- 不依赖本地 daemon
+- 不依赖某一个 CLI
+- 不依赖 Agent MCP
+- SKILL.md 可单独理解，核心工作流可完整执行
+- 所有 Schema / 方法 / 输出契约独立存在
+
+### Agent MCP Enhanced Mode
+
+Agent MCP 是**性能与可靠性增强层，不是 EduEvidence 成立的前提**（`docs/methodology.md` 的 Complexity Gate）：
+
+- S 级任务：单 Agent 直接执行，0 spawn
+- M 级任务：Primary Analysis + Independent Check
+- L 级任务：8 角色工作流（Planner / Retriever / Analyst / Skeptic / Method Reviewer / Judge / Intervention Designer / Evaluation Designer）
+
+> 角色数量 ≠ 必须启动的 Agent 数量。Platform Native Mode 由单 Agent 串行执行角色协议。
+
+> 🔒 Agent MCP 原则：**Scan first. Recommend second. Ask the user. Execute only after explicit confirmation.** 未经用户确认不得 spawn；用户拒绝则回退 Native。
+
+![Controlled Multi-Agent Research](assets/multi-agent-research.jpg)
+
+## Usage
+
+```bash
+# 1. 验证数据符合 Schema 契约
+python3 scripts/validate_schema.py --schema schemas/evidence.schema.json \
+    --data examples/ai-coding-assistant/evidence.jsonl
+
+# 2. 计算证据质量分与 Confidence
+python3 scripts/evidence_score.py examples/ai-coding-assistant/evidence.jsonl
+
+# 3. 生成 Evidence Matrix（主产品界面之一）
+python3 scripts/evidence_matrix.py examples/ai-coding-assistant/evidence.jsonl
+
+# 4. 运行 Citation Audit（Claim-证据追溯）
+python3 scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
+
+# 5. 渲染 Research & Decision Pack（Markdown）
+python3 scripts/render_report.py \
+    --frame examples/ai-coding-assistant/frame.json \
+    --evidence examples/ai-coding-assistant/evidence.jsonl \
+    --methodology examples/ai-coding-assistant/methodology.json \
+    --verdict examples/ai-coding-assistant/verdict.json \
+    --intervention examples/ai-coding-assistant/intervention.json \
+    --evaluation examples/ai-coding-assistant/evaluation.json \
+    --out REPORT.md
+
+# 6. 渲染单文件双语 HTML 报告（主产物）
+python3 visualization/eduevidence-report/scripts/build_report.py \
+    --result examples/ai-coding-assistant/result.json \
+    --out examples/ai-coding-assistant/EduEvidence_Report.html
+
+# 7. 校验 Benchmark 题目集
+python3 scripts/benchmark.py --questions benchmarks/questions.jsonl
+
+# 8. 运行测试
+pytest
+```
+
+> 真实使用中，Skill 由 Agent 读取 SKILL.md 执行 9 步工作流；`scripts/` 保证结构化数据的确定性校验，`visualization/` 保证展示层的确定性渲染，`examples/` 是完整运行示例。
+
+## Methodology
+
+- 教育证据质量框架：五维 0–2 分（D1 研究设计 / D2 样本质量 / D3 测量效度 / D4 时间强度 / D5 直接性），总分 0–10（`references/evidence-quality.md`）。
+- 方法学审查 15 项清单，最高优先级规则：**任务完成表现不能自动等价为学习效果**（`references/methodology-audit.md`）。
+- Confidence 规则化计算：`Evidence Quality + Consistency + Directness + Evidence Count - Conflict Penalty - Unsupported Penalty` → High / Moderate / Low / Insufficient（`scripts/evidence_score.py`）。
+- 失败处理：INSUFFICIENT_SOURCES / UNSUPPORTED_CLAIM / CONFLICT_UNRESOLVED / SCOPE_MISMATCH / METHODOLOGY_TOO_WEAK / NEEDS_USER_CONTEXT / TOOL_FAILURE —— 失败时禁止强行生成高确定性建议。
+
+## Limitations
+
+- Benchmark 基于真实文献的可检索证据；模型实际运行结果需按 `docs/benchmark.md` 的 B0–B4 基线采集。
+- 搜索与抽取依赖可用检索资源；`TOOL_FAILURE` 时不编造来源。
+- EduEvidence 是教学决策辅助，**不代替教师或学校最终决策**；涉及高风险评价、学生处分、个体心理判断、学生重大教育机会时不自动决策。
+
+## Roadmap
+
+**已完成（仅 harness / 仿真，标注 SIMULATED，非实证）：**
+
+- [x] Benchmark v2 harness / simulation —— `benchmarks/results/` 是确定性仿真，证明评测框架可运行，**不是**真实模型性能（见上方 [Benchmark](#benchmark) 的 ⚠️ 说明）。
+- [x] Skill 核心与管线：9 步协议（Research Core 6 + Decision Extension 3）、13 个顶层 JSON Schema、确定性脚本、8 角色协议（原计划 Phase 0–6）。
+- [x] Evidence-to-Action：适用性 / 四态决策 / 干预 / 评价设计。
+- [x] 产品 UI：单文件双语 HTML 报告 + 信息图 + 学术图（原计划 Phase 8）。
+
+**待做（尚未完成，不做已完成宣称）：**
+
+- [ ] **Empirical Benchmark** —— 首轮已启动（B2 vs B3，10 题 × 3 次，`omp` / `deepseek-v4-flash`，→ `benchmarks/empirical/v3-report.md`）；30 题全覆盖、**B3 vs B4**、重复运行、方差报告与 gold annotation / 独立评审计分仍在计划中（见 `docs/benchmark.md`）。
+- [ ] **HTML 可访问性** —— 语言切换同步 `<html lang>`、theme/lang 按钮 `aria-pressed`、表格筛选控件 label、SVG 图双语 title/desc、source link 安全 scheme 白名单。
+- [ ] **纵向决策闭环** —— 打通 **PILOT → 真实数据 → 再裁决**：试点结果回填项目证据图，产出更新后的决策（Full Research Cycle 端到端真实数据跑通）。
+
+## License
+
+MIT — 见 [LICENSE](LICENSE)。

package/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: eduevidence
+description: "Evidence-based decisions for ANY educational & social science question — whether, when, and how to adopt a teaching method, curriculum change, AI tool, or policy intervention. Orchestrates modular sub-skills for literature review, methodology bias audit (WWC 5.0 / GRADE), SSOT causal evidence graph construction, gap lens discovery, pre-registered trial design, and empirical DID data re-injection."
+---
+
+# EduEvidence 5.2 — Universal Evidence-Based Decision Skill
+
+> **AI4SS Track | 科艺融合 · 通用智能**
+> **From Empirical Questions to Evidence-Based Decisions & Causal Trial Loops.**
+
+EduEvidence delivers the **EduEvidence Research Engine** — a persistent system transforming research questions into verifiable decisions. State lives in a unified **Project Workspace** (Project / Run / Revision / DecisionSnapshot) and a **Single Source of Truth (SSOT) Evidence Graph** (engine/evidence_graph.py), linking Papers, Quantitative Effect Sizes (g), Claims, Social Science Risks, and Shared Research Library knowledge.
+
+The canonical protocol below is the single authoritative definition (docs/architecture.md); every stage output is schema-gated (schemas/, 37 contracts across V1–V4 generations — counts are machine-audited in docs/metrics.json).
+
+**Schema 版本口径**：schemas/ 顶层 13 个 = V1 契约（evidence.schema.json 当前修订 1.1、education-frame / verdict 等）；schemas/v2/ 17 个 = V2 契约（evidence-link / research-intent / study / graph-revision / project 等）。文档与代理配置一律以此口径命名。
+
+## 🧭 双研究模式（Research Mode）与执行层
+
+- **Evidence Review**（二手证据综述）与 **Full Research Cycle**（综述 → 知识缺口 → 研究设计 → 本地数据 → 分析 → 图更新 → 再裁决）两种 Research Mode。
+- **Project Workspace + Evidence Graph** 为不可变 revision 模型；result.json / HTML / Markdown 都是投影，不是事实库。
+- **Shared Research Library**：已验证外部事实（Source/Study/Finding/Audit）跨项目快照复用；研究事实可复用，解释（Claim/EvidenceLink/Applicability/Decision）必须项目本地。
+- 冻结科学规则：**No new study design without evidence grounding** — 任何新研究设计必须引用显式、有证据奠基的 KnowledgeGap ID。
+- 唯一事实来源与防重规则：**Single Canonical Project per Research Question** — 同一研究问题严格保持单实例，禁止重复建立同名主题目录；更新时采用不可变 Revision 升级机制。
+- **执行层双模式**：Mode A **Platform Native**（纯 SKILL 零依赖交付）/ Mode B **Agent MCP** Enhanced（可选增强：启动检测 → 推荐 → 用户授权 → safe_spawn；未启用自动降级 Native）。
+
+---
+
+## 📜 Canonical Protocol — 9 Steps = Research Core 6 + Decision Extension 3
+
+```text
+Research Core（6 阶段，证据纪律核心）:
+Frame → Retrieve → Extract → Challenge → Audit → Adjudicate
+
+Decision Extension（3 阶段，证据到行动）:
+Applicability → Intervene → Evaluate
+
+端到端 9 步:
+Frame → Retrieve → Extract → Challenge → Audit → Adjudicate
+→ Applicability → Intervene → Evaluate
+
+Fetch / Validate = Retrieve 内部强制 gate（RULE 2：snippet ≠ 证据内容）
+Present = 最终呈现层（不计入 9 步协议）
+```
+
+| # | 阶段 | 输出契约（schemas/） |
+|---|------|----------------------|
+| 1 | Frame | education-frame.schema.json |
+| 2 | Retrieve（内含 Fetch/Validate gate） | source.schema.json / fetch-result.schema.json |
+| 3 | Extract | evidence.schema.json |
+| 4 | Challenge | evidence.schema.json（反方/未发现/confounder） |
+| 5 | Audit | methodology.schema.json（task_vs_learning_guard） |
+| 6 | Adjudicate | verdict.schema.json（规则化置信度 + Pre-Verdict Gate） |
+| 7 | Applicability | applicability-policy.md（For whom / which course / which outcome / conditions） |
+| 8 | Intervene | intervention.schema.json（最小可验证 PILOT + Stop Conditions） |
+| 9 | Evaluate | evaluation.schema.json（基/后/保持/迁移 + 成功阈值） |
+| Present | 呈现层 | result.json / result.zh.json → 烘焙主题报告 |
+
+**Present 主题显示名（生成时五选一，烘焙定主题，最终 HTML 仅中英文切换）**：
+
+```text
+    ├─ Claude Research      [Light]
+    ├─ Academic Paper       [Light]
+    ├─ DataLab              [Light]
+    ├─ DataLab              [Dark]
+    └─ Presentation / Judge [Dark]
+```
+
+---
+
+## 🗺️ Sub-Skill Map（12 个子 skill 归位）
+
+| 阶段 | 实现组件 |
+|------|----------|
+| 1 Frame | skill/sub-skills/research-planning + Complexity Gate（S/M/L，scripts/complexity_gate.py） |
+| 2 Retrieve | skill/sub-skills/literature-review + skill/sub-skills/aihot-trend-analysis（retrieval/fetch.py + validate.py 为内部 gate） |
+| 3 Extract | skill/sub-skills/evidence-extraction |
+| 4 Challenge | skill/sub-skills/contradiction-analysis |
+| 5 Audit | skill/sub-skills/methodology-audit（WWC 5.0 / GRADE） |
+| 6 Adjudicate | skill/sub-skills/evidence-review + scripts/pre_verdict_gate.py + scripts/compute_confidence.py（meta-analysis：DerSimonian-Laird、Q、I²、Egger） |
+| 7 Applicability | references/applicability-policy.md |
+| 8 Intervene | references/intervention-design.md + skill/agents/intervention-designer.md |
+| 9 Evaluate | references/evaluation-design.md + skill/agents/evaluation-designer.md |
+| Present | skill/sub-skills/report-generation + visualization/eduevidence-report（静态报告与三适配器；Lieflat 仅作开发期图表参考，不是提交包运行时） |
+| Full Research Cycle 扩展 | skill/sub-skills/gap-analysis → skill/sub-skills/study-design → skill/sub-skills/data-analysis（DID 回注） |
+| 横切 | skill/sub-skills/ethics-review（IRB 合规） |
+
+**Full Research Cycle = Decision-to-Outcome Loop**：证据综述 → 知识缺口（Gap）→ 预注册研究设计 → 本地课堂/田野数据 → DID/OLS 分析 → Evidence Graph 更新 → 再裁决。Grounding Rule：不基于证据奠基的 KnowledgeGap ID，禁止产生新研究设计。
+
+**Complexity Gate（S/M/L）**：S（Quick Fact）快速路径；M（Standard Review）八角色全走；L（Deep Causal Cycle）标准路径 + 系统化搜索 + 独立双审 + 干预/评价强制产出。默认门控 M，向上从严。
+
+---
+
+## 🎯 Flagship Scenario: AI Coding Assistants in CS1
+
+**Question**: *Should first-year university C/Python students be allowed to use generative AI coding assistants?*
+
+`examples/ai-coding-assistant-evidence/` — every source is a real study with a
+registry-verified DOI (Crossref/DataCite audit trail: `benchmarks/doi-audit/report.md`):
+
+- **Real evidence base (8 sources)**: Bastani et al. PNAS 2025 field RCT,
+  Kazemitabaar et al. CHI 2023 novice RCT, Peng et al. 2023 professional-developer RCT
+  (preprint), plus benchmark/usability studies (JSS 2023, ICER 2022, UIST 2022, Koli 2023).
+- **Honest synthesis**: task performance improves reliably during AI access; unguarded
+  access harmed independent exam performance by −17% (PNAS 2025); guardrail design
+  (hints-not-answers) mitigates the harm.
+- **Tribunal Verdict**: **PILOT** (restricted 4-phase fading pilot) with engine-computed
+  confidence Moderate (0.586, policy 2026-08-12.v2) over 8 independent studies.
+- **Provenance badge**: data_origin=`manual_curated`. Other demo packs are badged
+  `synthetic` and must not be cited as evidence.
+- **Causal Closed Loop**: 12-week quasi-experimental DID trial design + Classroom CSV data injection.
+
+---
+
+## 🖥️ Local Web Studio（3 页，无 Agent 派遣）
+
+```bash
+python3 scripts/dashboard_server.py --port 8765
+# http://127.0.0.1:8765/
+```
+
+静态前端（web/）+ 轻量 API 服务，直接读取 examples/<project_id>/ 下的 skill 工件：
+
+1. **仪表盘 (Dashboard)** — 跨课题 KPI、效应量对比、课题资产矩阵。
+2. **报告浏览 (Report Browser)** — 列出有 EduEvidence_Report.html 的课题；若存在 reports-5themes/EduEvidence_Report_<theme>.html 则提供 5 主题烘焙变体选择。报告仅在生成时定主题，最终 HTML 只保留中英文切换，不做运行时换肤。
+3. **数据可视化 (Data Visualization)** — 按课题选择，查看森林图、效应量分布、结果维度与 SSOT 证据图谱。
+
+页面是 **契约驱动**：新课题只要产出 result.json / evidence_graph.json 即自动出现，无硬编码 demo 数据。
+
+---
+
+## 📦 Visualization Data Contract（Skill ↔ Web 同步）
+
+| 工件 | 产出阶段 | 消费页面 |
+| --- | --- | --- |
+| result.json → forest_plot_data | Extract + Adjudicate | 森林图 |
+| result.json → evidence（数值 effect_size） | Extract | 效应量分布 |
+| result.json → outcome_mapping | Extract + Audit | 结果维度 |
+| evidence_graph.json → export_echarts_graph() | Adjudicate（evidence-review） | SSOT 证据图谱 |
+| EduEvidence_Report.html + reports-5themes/*.html | Present（visualization/eduevidence-report/scripts/build_report.py） | 报告浏览（烘焙变体） |
+| result.json → meta.question + decision | Present | 仪表盘 / 可视化标题与裁决 |
+
+关键 forest_plot_data 字段：study_label、outcome_dimension、effect_size（Hedges g）、ci_lower/ci_upper、sample_size、direction、wwc_rating。
+
+---
+
+## 🛡️ 科学可信度强制（失败关闭）
+
+- **DID 失败关闭**：`scripts/did_regression.py` 对奇异/共线设计、空 2×2 格、零方差、
+  饱和模型等不可估计输入返回 `status="error"` + 稳定 `error_code`，且
+  `did_coefficient` / `standard_error` / `p_value` / `ci_95` / `hedges_g` 全部为
+  `null`，绝不伪造 `SE=1.0` 或虚假 p 值。
+- **非 cluster 显式标注**：普通 DID 结果带 `inference_status="non_cluster_warning"`；
+  DID/准实验（QED）永远不得标注 `Meets Standards Without Reservations`。
+- **无直接学习证据不得 ADOPT**：裁决要求 learning/独立迁移结果（直接性 directness=2）
+  才允许 High+支持 → ADOPT；任务表现、程序效率、主观体验只能 PILOT/INSUFFICIENT。
+- **无伪精度**：缺 CI 的森林图点只画点、不画误差线并标记 "CI not reported"；
+  meta 合并不使用默认 `se=0.20`，无精度证据的条目记录排除原因。
+
+## 📦 三适配器统一契约（Python 标准库）
+
+三个可视化适配器共享同一 envelope 契约，适配器本身只使用 Python 标准库；ECharts 是 Web Studio 的可选浏览器运行时，不属于适配器或提交包：
+统一 CLI：`--result <result.json> --out <out.json> [--lang zh|en]`：
+
+```bash
+python3 visualization/eduevidence-report/scripts/build_charts.py \
+    --result examples/ai-coding-assistant/result.json --out /tmp/charts.json
+python3 visualization/eduevidence-report/scripts/build_infographics.py \
+    --result examples/ai-coding-assistant/result.json --out /tmp/infographics.json
+python3 visualization/eduevidence-report/scripts/build_figures.py \
+    --result examples/ai-coding-assistant/result.json --out /tmp/figures.json --theme okabe_ito
+```
+
+输出 envelope：`adapter` / `contract_version` / `source_ref` / `source_sha256`（provenance）
+/ `locale` / `data`。报告渲染器 `build_report.py` 与 CLI 共享同一核心函数。
+（`build_figures.py --out-dir` 为兼容参数，迁移后移除。）
+
+## 🛠️ CLI Quick Commands
+
+```bash
+# 1. 3 页 Local Web Studio
+python3 scripts/dashboard_server.py --port 8765
+
+# 2. 学术与实时趋势检索
+python3 -m retrieval.search "AI coding assistants learning transfer"
+
+# 3. 田野数据 DID 回归（数据契约回写见 skill/sub-skills/data-analysis；
+#    示例用全研究周期夹具的 40 行匿名 DID 数据，无 PII）
+python3 scripts/did_regression.py examples/full-research-cycle-fixture/data.csv
+
+# 4. 效应量计算器
+python3 scripts/effect_calculator.py --mean1 78.5 --sd1 10.2 --n1 90 --mean2 72.1 --sd2 11.0 --n2 90
+
+# 5. Skill 一致性检查
+python3 scripts/skill_lint.py
+```