EduEvidence

🌐 English | 中文

EduEvidence Research Engine — Evidence Research & Decision Skill

From Research Questions to Evidence-Based Decisions. 从研究问题，到有证据支撑的决策。

▶ 在线演示： 介绍页 · Research Studio · 深度调研对比页

EduEvidence 面向研究者与实践决策者，将教育、组织政策和 AI 工具采用等问题转化为可追溯、可质疑、可验证的证据决策流程。当前公开案例涵盖编程学习和企业客服，分别使用教育与组织政策领域契约。

• 三条公开工作流：Evidence Review（证据综述）、Decision & Pilot（决策与试点）、Evaluate & Update（评估与更新）。完整研究周期将文献证据、有依据的知识缺口、研究设计、新数据和决策修订连接起来。
• ⚖️ 帮助研究者与实践决策者判断：证据支持什么、不能支持什么、适用于谁、应该怎样试点并验证。
• 🧪 基于真实研究（示例包含 CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 的实证证据），不做无来源断言。
• 🚦 最终输出不是"允许/禁止"的二元结论，而是 ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE 四态决策 + 可落地的干预与评价方案。

本地 Studio 真实录屏（非示意）：总览 → 报告阅读室 → 五种报告形态。下方为介绍页滚动实录：

快速安装

方式一：npm（推荐 — 安装为 Agent Skill）

npm install -g eduevidence
eduevidence skill                  # 交互式选择宿主（默认）
eduevidence skill --list-hosts     # 或先查看全部宿主与落点
# 非交互：eduevidence skill --host cursor

方式二：curl 一键安装

⚠️ 供应链提示（E7）：curl 直跑等于执行远端脚本。更稳妥的方式是方式二 clone 后 先审阅再安装；若坚持直跑，建议把 URL 固定到具体 commit 并先下载审阅。

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

git clone https://github.com/37chengshan/eduevidence.git
cd eduevidence
bash install.sh              # 一键：venv + 依赖 + 自检 + 测试

安装后直接打开示例报告：

open examples/ai-coding-assistant-evidence/EduEvidence_Report.html

需要 Python 3.10+；核心零第三方依赖。学术图 PNG/PDF 导出可选装 matplotlib。 安装完成后脚本会提示为项目点 star（仅提示，不会自动执行任何 GitHub 操作）。 ⚠️ 管道执行远程脚本以当前用户权限运行，建议先审阅 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。

npm install -g eduevidence
eduevidence skill                  # 交互式选择宿主（默认）
eduevidence skill --list-hosts
eduevidence skill --dry-run
eduevidence skill --host cursor    # 可选：跳过菜单，直接指定宿主

或从 git clone 目录：

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 -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，它会读取 安装指南 自行完成安装：

请按照 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 面对教育问题通常执行：

问题 → 搜索若干材料 → 总结观点 → 给出建议

EduEvidence 执行：

教学问题
  → 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-evidence/。

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

┌─────────────────────────────────────┐
│            EduEvidence              │
│  教育领域知识 + 决策 + 干预 + 评价   │
└────────────────┬────────────────────┘
                 │
┌────────────────▼────────────────────┐
│        EvidenceFlow Protocol        │
│ Frame / Retrieve / Extract /        │
│ Challenge / Audit / Adjudicate      │
└────────────────┬────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
 Platform Native      Agent MCP
 Execution Mode      Enhanced Mode

完整工作流（9 步）：

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）：

学习效果:   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（规则化计算，不由模型自由生成）

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）。

基线设计：

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-evidence/ 完整展示了从问题到决策的全过程：

• 证据（12 条发现、8 个来源）：任务表现提升（Kazemitabaar 2023）、无护栏访问损害独立考试表现 -17%（Bastani 2025, PNAS）、护栏设计消除负效应（Bastani 2025）、形成性反馈写作证据（Marzuki 2024）。
• 决策：落档动作 PILOT（Moderate，0.586）；矩阵落点（engine.decision_policy.decision_outcome）为 INSUFFICIENT_EVIDENCE（unresolved_conflict）—— decisive relations 中同时存在 support_adoption 与 oppose_adoption，冲突检查在 ADOPT/PILOT 判定前即短路；任务表现证据强，但大学编程课程的直接学习效应证据缺失，且无护栏风险已被证实。
• 干预：4 阶段试点（Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check）。
• 评价：无 AI 基线/后测/期末考试保持/无 AI 迁移任务 + AI 依赖风险指标。

另一公开案例 examples/workplace-ai-assistant/ 使用组织政策领域，讨论企业客服是否引入 AI 助手：3 项研究、4 条发现，区分直接客服证据与间接写作/咨询证据，落档动作 PILOT（Moderate，0.578），矩阵落点为 INSUFFICIENT_EVIDENCE 且 downgrade_reason=None：4 条 decisive relation 全为 conditional，而 conditional 不属于冲突关系（engine.decision_policy.CONFLICT_RELATIONS = {conflict, mixed}），因此引擎不记录降级理由；又因没有任何 decisive 的 support_adoption，Moderate 置信度无法升到 PILOT。详见 来源核验与边界。

第三个公开案例 examples/spaced-retrieval-practice/（来源经 Sciverse 通道逐条读回原文）讨论间隔重复与检索练习能否替代集中式复习：6 条证据、7 篇 tier-1 DOI 来源，判定 ADOPT（High，引擎复算 0.893）—— 唯一一个落档动作与矩阵落点一致的公开案例。它是“ADOPT 出口真实可达”的实证：延迟保持与迁移两个主要结果上都有 directness=2 的直接且一致证据；另两例低于 ADOPT：编程案中 decisive relations 同时含 support_adoption 与 oppose_adoption（unresolved_conflict），企业客服案中没有任何 decisive 的 support_adoption（4 条全为 conditional），因此矩阵落点均为 INSUFFICIENT_EVIDENCE，不得表述为已落在 PILOT。

三个公开案例的数据来源各自如实标注：编程与企业客服两例为人工整理文献（manual_curated），间隔重复一例为真实 Sciverse 检索运行记录（real_run_sciverse），报告生成不等于九阶段模型研究已运行，也不代表试点已经执行。四个旧教学示例迁入 tests/fixtures/legacy-examples/，仅供软件兼容测试，排除于公共目录和分发包；未核验或合成数据不能引用为研究证据。旧 ai-coding-assistant 路径保留兼容别名。

Studio 实际界面

点击图谱节点可以追溯“来源 → 发现 → 主张”。连线流动用于辅助阅读，不表示后台研究正在执行。

同一份证据可以用五个独立主题阅读，支持中英文及简报/全文切换。

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; legacy ECharts enhancement is optional and is not required by the new Research Studio.

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.

Research Studio 研究观察台保持只读。运行 python3 scripts/dashboard_server.py --port 8765，打开 /studio/，即可查看研究项目、证据与来源、实际运行记录、已提交版本及五种风格报告。Skill 自进化实验单独展示；控制台不会启动研究、修改证据或派发代理。

控制台采用 React + TypeScript，分发包已包含静态资源，使用者无需安装 Node。新图表不依赖远程 ECharts CDN，也不在浏览器中计算合并效应量。本地研究不会进入 GitHub Pages 公共导出。五主题从完整双语输入生成，缺失内容明确标记，不补造结论。

详见研究观察台流程与交付指南。

Open the example directly: examples/ai-coding-assistant-evidence/EduEvidence_Report.html

可选检索通道（key-based）

零配置检索（OpenAlex / Semantic Scholar / CrossRef / AIHot / AgentSearch）开箱可用。配置以下 key 后通道自动启用，未配置时静默失活、不影响科学门：

export SCIVERSE_API_TOKEN=sv-...   # 引用级学术检索 + 全文定位（meta-search / agentic-search / content / paper-relations）
export TAVILY_API_KEY=...          # 通用网页检索
export BRAVE_API_KEY=...           # 通用网页检索

Sciverse 通道把 /agentic-search 的 chunk 当作定位子：必须经 /content 读原文并通过校验门后，才允许进入证据抽取（RULE 2 的机器化执行）。契约见 docs/sciverse-api.md，合规见 references/retrieval-compliance.md。

Architecture

仓库是一个完整的 Skill 包：SKILL.md 是入口，其余目录按"Skill 运行必需 → 质量保障 → 演示"分层。详见 docs/architecture.md：

同一套架构的图解单页（九步协议 / 角色与独立性 / 产物状态地图 / 执行与审批闭环）见 web/architecture.html。

EduEvidence/  （= 一个 Skill 包）
│
├─ SKILL.md                  ← Skill 入口：使命 → 工作流路由 → 科学门禁 → 9 步协议 → 输出要求
│
├─ Skill 本体（运行必需）
│  ├─ skill/agents/          8 个角色协议（Planner / Retriever / Analyst / Skeptic /
│  │                         Method Reviewer / Judge / Intervention Designer / Evaluation Designer）
│  ├─ references/            方法论文档（证据质量 / 反证协议 / 裁决规则 / 干预设计 / 检索合规 / 文案规范…；数量见 docs/metrics.json）
│  ├─ schemas/               50 个 JSON Schema 数据契约（15 顶层 + 18 v2 + 3 v3 + 4 v4 + 10 vNext，每步输出的校验门；递归计数见 `scripts/generate_metrics.py`）
│  ├─ scripts/               确定性逻辑脚本（评分 / 矩阵 / 审计 / 置信度 / Orchestrator / 启动探测）
│  ├─ retrieval/             检索与抓取层（fetch / validate / dedupe / failures）
│  ├─ integrations/          Agent MCP 增强层 + Smart Web Fetch 集成
│  └─ visualization/         结果呈现层（ECharts / 信息图 / 学术图 / 双语 HTML Composer）
│
├─ 质量保障
│  ├─ tests/                 pytest 测试矩阵（测试函数与文件数见源码仓库的 docs/metrics.json）
│  └─ benchmarks/            30 题 + 30 份金标注 + B0–B4 评测框架
│
└─ 演示与分发
   ├─ examples/              3 个完整 Research & Decision Pack（含双语 HTML 报告）
   ├─ docs/                  架构 / 方法论 / Benchmark / Demo / 复现指南
   ├─ install.sh             一键安装（本地 / 多 Agent Skill）+ 自检
   ├─ pyproject.toml         打包元数据（核心零第三方依赖）
   └─ README.md / README.zh-CN.md  双语说明

Skill 包设计原则：运行所需的最小集是 SKILL.md + skill/ + references/ + schemas/ + scripts/；retrieval/、integrations/、visualization/ 是让 Skill 真正"可运行、可呈现"的执行层；tests/、benchmarks/、examples/、docs/ 是可信度与上手保障，不影响 Skill 本体。

分发

两条发布通道共用同一份运行时 allowlist（scripts/skill_payload.py，宿主安装脚本也用这一份）：

• 提交包 —— bash packaging/make_upload.sh 重建 dist/eduevidence-submission/（扁平 Skill 包 + submission-manifest.json + UPLOAD-README.md）；它会先重建五种风格的报告变体，缺少已构建的 web/studio/index.html 时直接中止。旧 upload/ 目录是冻结的废弃快照，不得随包分发 —— 见 upload/DEPRECATED.md。
• npm 包 —— npm install -g eduevidence，然后用 eduevidence skill --list-hosts（列出全部宿主与落点）或 eduevidence skill --dry-run（只预览，不写入）。在仓库目录中等价写法是 node bin/eduevidence.js skill --list-hosts / --dry-run。

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。

Usage

# 1. 验证数据符合 Schema 契约
python3 scripts/validate_schema.py --schema schemas/evidence.schema.json \
    --data examples/ai-coding-assistant-evidence/evidence.jsonl

# 2. 计算证据质量分与 Confidence
python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence.jsonl

# 3. 生成 Evidence Matrix（主产品界面之一）
python3 scripts/evidence_matrix.py examples/ai-coding-assistant-evidence/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-evidence/frame.json \
    --evidence examples/ai-coding-assistant-evidence/evidence.jsonl \
    --methodology examples/ai-coding-assistant-evidence/methodology.json \
    --verdict examples/ai-coding-assistant-evidence/verdict.json \
    --intervention examples/ai-coding-assistant-evidence/intervention.json \
    --evaluation examples/ai-coding-assistant-evidence/evaluation.json \
    --out REPORT.md

# 6. 渲染单文件双语 HTML 报告（主产物）
python3 visualization/eduevidence-report/scripts/build_report.py \
    --result examples/ai-coding-assistant-evidence/result.json \
    --out examples/ai-coding-assistant-evidence/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 的 ⚠️ 说明）。
• [x] Skill 核心与管线：9 步协议（Research Core 6 + Decision Extension 3）、50 个版本化 JSON Schema（schemas/**，计数见 scripts/generate_metrics.py）、确定性脚本、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。