eduevidence 5.2.0

package/integrations/smart_web_fetch.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""smart_web_fetch.py — Smart Web Fetch integration wrapper (v3 方案).
+
+Positioning: Fetch Reliability Layer, NOT a search layer. It reads a known URL
+reliably through the provider degradation chain and records provenance.
+
+Security principles (v3 §26):
+  - record provider, keep original_url
+  - NEVER send private/login/session pages to third-party cleaning services
+  - never send local files; never send private teaching data
+  - private materials are handled locally only
+
+Usage:
+    from integrations.smart_web_fetch import smart_fetch
+    result = smart_fetch("https://doi.org/10.xxxx", expect_title="...")
+    # result["fetch_status"] in {"FETCH_VALID", "FETCH_PARTIAL", "FETCH_FAILED"}
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from retrieval.fetch import fetch_url
+from retrieval.validate import is_private_url
+
+
+def is_private(url: str) -> bool:
+    """Private/local URLs must never go through third-party cleaning providers.
+
+    Host-based judgement (urllib.parse.urlparse + ipaddress): loopback, private,
+    link-local, CGNAT, reserved ranges and local hostnames. URL path content —
+    e.g. a DOI's "10." prefix — never influences the verdict, so
+    https://doi.org/10.1145/... is NOT private. See retrieval.validate.is_private_url.
+    """
+    return is_private_url(url)
+
+
+def smart_fetch(url: str, *, expect_title: str | None = None, timeout: int = 20) -> dict[str, Any]:
+    """Fetch a known URL through the Smart Web Fetch chain.
+
+    Private URLs are fetched natively only (no third-party cleaning).
+    """
+    if is_private(url):
+        result = fetch_url(url, use_smart_fetch=False, timeout=timeout, expect_title=expect_title)
+        result["validation"]["checks"]["private_url_local_only"] = True
+        return result
+    return fetch_url(url, use_smart_fetch=True, timeout=timeout, expect_title=expect_title)
+
+
+def fetch_summary(result: dict[str, Any]) -> dict[str, Any]:
+    """Compact fetch provenance summary for report Sources & Provenance panel."""
+    return {
+        "original_url": result.get("original_url"),
+        "resolved_url": result.get("resolved_url"),
+        "fetch_provider": result.get("fetch_provider"),
+        "fetch_status": result.get("fetch_status"),
+        "fetched_at": result.get("fetched_at"),
+        "fallback_used": result.get("fallback_used", False),
+        "content_verified": result.get("validation", {}).get("passed", False),
+    }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "eduevidence",
+  "version": "5.2.0",
+  "description": "Evidence-Based Education Decision Skill — from any education question to an auditable, evidence-grounded decision.",
+  "license": "MIT",
+  "author": "EduEvidence Contributors",
+  "homepage": "https://github.com/37chengshan/eduevidence#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/37chengshan/eduevidence.git"
+  },
+  "bugs": {
+    "url": "https://github.com/37chengshan/eduevidence/issues"
+  },
+  "keywords": [
+    "education",
+    "evidence",
+    "skill",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "codex",
+    "research"
+  ],
+  "bin": {
+    "eduevidence": "bin/eduevidence.js"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "install.sh",
+    "eduevidence_cli.py",
+    "pyproject.toml",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md",
+    "engine/",
+    "domains/",
+    "skill/",
+    "references/",
+    "schemas/",
+    "scripts/",
+    "retrieval/",
+    "integrations/",
+    "visualization/eduevidence-report/"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eduevidence"
+version = "5.2.0"
+description = "Evidence-Based Education Decision Skill — from any education question (teaching methods, curriculum, assessment, learning interventions, AI tools) to an evidence-based decision."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "EduEvidence Contributors" }]
+keywords = ["education", "evidence", "skill", "evidence-based", "teaching", "ai-education"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Education",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+eduevidence = "eduevidence_cli:main"
+
+[tool.pytest.ini_options]
+# scripts/ 只为收编历史遗留的红队压测 scripts/test_adversarial_empirical.py
+# （E5：该文件是全仓唯一 test_*.py 命名的脚本，纳入默认收集后不再"死测试"）。
+testpaths = ["tests", "scripts"]
+python_files = ["test_*.py"]
+addopts = "-q"
+filterwarnings = ["ignore::pytest.PytestReturnNotNoneWarning:scripts.*"]
+
+# wheel 自包含 CLI：eduevidence_cli + engine + scripts（V1/V2 命令实现与
+# validate_schema）+ schemas 数据文件（data-files 安装到 share/eduevidence/，
+# engine.contracts / orchestrator 按回退路径解析）。Skill 本体（SKILL.md +
+# skill/ + references/ + retrieval/ + integrations/ + visualization/ +
+# assets/）由 install.sh 或源码包完整分发。
+[tool.setuptools]
+py-modules = ["eduevidence_cli"]
+packages = ["engine", "scripts"]
+
+[tool.setuptools.data-files]
+"share/eduevidence/schemas" = ["schemas/*.json"]
+"share/eduevidence/schemas/v2" = ["schemas/v2/*.json"]
+"share/eduevidence/schemas/v3" = ["schemas/v3/*.json"]
+"share/eduevidence/schemas/v4" = ["schemas/v4/*.json"]
+"share/eduevidence/domains" = ["domains/manifest.json", "domains/education/manifest.json", "domains/education/outcome_taxonomy.json", "domains/policy/manifest.json", "domains/policy/frame.schema.json", "domains/policy/outcome_taxonomy.json", "domains/policy/methodology_checklist.json"]
+"share/eduevidence/domains/policy/references" = ["domains/policy/references/*.md"]
+"share/eduevidence/benchmarks" = ["benchmarks/evidence-library.json"]
+
+[tool.ruff.lint]
+# E5 最小守门集：语法层错误 + 未定义/重定义名。风格类规则不设（存量代码
+# 不做一次性大规模格式化，避免淹没 review）。
+select = ["E9", "F63", "F7", "F82"]

package/references/applicability-policy.md

@@ -0,0 +1,88 @@
+# Applicability Analysis（适用性分析）
+
+## 1. 目的
+
+裁判庭（tribunal-policy.md）得出"结论可以成立"之后，还需回答最后一个问题：
+**这个结论能用在我的场景吗？** 适用性分析把结论从其原研究情境映射到目标情境，
+明确边界，避免盲目照搬。
+
+## 2. 核心原则
+
+```
+证据只对其检验过的  learner × course × outcome × tool × context  组合严格成立；
+组合中任一维度变化，成立强度都要降级。
+```
+
+## 3. 七问检查（Applicability Check）
+
+对每条可成立结论逐一回答七个问题：
+
+| 问题 | 检查内容 | 判定输出 |
+| --- | --- | --- |
+| For whom? | 原研究学习者与目标学习者是否一致（层次/专业/先验/特征）？ | 一致 / 部分一致 / 不一致 |
+| Which course? | 学科、课程类型、时长、难度是否匹配？ | 一致 / 部分一致 / 不一致 |
+| Which outcome? | 结论的 Outcome 与你的目标结果是否同类（见 outcome-taxonomy.md）？ | 同类 / 相关但不同类 / 不同类 |
+| What conditions? | 班级规模、线上线下、教师支持是否可比？ | 可比 / 部分可比 / 不可比 |
+| How long? | 干预时长与研究时长是否可比（短期结论不宜外推到长期）？ | 可比 / 更长 / 更短 |
+| What teacher support? | 你能否提供与研究相当的教师/助教支持？ | 具备 / 需额外投入 / 不具备 |
+| What AI usage policy? | 你能执行的 AI 使用规范（allowed_usage）是否与研究一致？ | 可执行 / 需调整 / 不可执行 |
+
+## 4. 输出结构
+
+```yaml
+applicability:
+  conclusion: <被评估的可成立结论>
+  suitable_for:
+    - <明确匹配的组合，如: 大一 C 语言、代码补全型工具、线下小班、有助教、8 周试点>
+  not_suitable_for:
+    - <明确不匹配的组合及其原因>
+  required_conditions:
+    - <要落地该结论必须具备的条件，如: 需要 AI 使用日志、需要受限账号>
+  teacher_requirements:
+    - <教师所需能力与投入，如: 教师需掌握工具配置、需每周答疑 2 小时>
+  student_prerequisites:
+    - <学生的先决条件，如: 需先完成顺序/分支/循环三大语法单元>
+  usage_constraints:
+    - <可执行的使用边界，如: 禁止完整代码生成、实验课外使用需登记>
+  risk_factors:
+    - <落地后需监控的风险，如: 依赖指标上升、代写行为增加>
+```
+
+## 5. 执行规则
+
+| 编号 | 规则 |
+| --- | --- |
+| AP-01 | 七问中任一"不一致"，必须在输出中显式降级结论置信度或缩小 suitable_for 范围。 |
+| AP-02 | `not_suitable_for` 不允许留空偷懒；即使无明确证据，也需列出"未验证的组合"作为待验证项。 |
+| AP-03 | `usage_constraints` 必须与 Frame 的 `intervention.allowed_usage` 一致，不得凭空放宽。 |
+| AP-04 | `risk_factors` 必须与 Frame 的 `outcomes.risk` 对应；新增风险需说明依据。 |
+| AP-05 | 若目标场景与研究场景差异过大（如工具类型不同），即使原研究是 `strong`，也只能给 `moderate` 或 `low` 的外推置信度。 |
+
+## 6. 示例：把"Copilot 提高作业正确率"结论应用到另一所学校
+
+```
+conclusion: "Copilot 可提高 AI 环境下大一 C 语言作业正确率（C2/accuracy）"
+           ——原研究: 线下小班 60 人、有助教、8 周、受限账号 + 使用日志。
+
+applicability:
+  suitable_for:
+    - 线下实验课、班级 ≤ 80 人、有助教、有 AI 使用日志监控的同类课程
+    - 能提供与 8 周相当的试点期的课程
+  not_suitable_for:
+    - 2000 人 MOOC（无教师监控，日志缺失）
+    - 纯线上自学课程（无对照班与监督）
+    - 要求学生"先独立完成再求助"的作业模式（与研究的使用方式冲突）
+  required_conditions:
+    - 为每个学生配置可审计的受限 AI 账号
+    - 保留每周作业的无 AI 独立版本以跟踪 C1
+  teacher_requirements:
+    - 教师须完成工具使用培训
+    - 助教每周 2 学时答疑，负责核查使用日志
+  student_prerequisites:
+    - 学生已掌握指针之前的语法基础（实验内容不超过研究覆盖范围）
+  usage_constraints:
+    - 仅允许代码补全与报错解释；禁止完整代码生成
+    - 实验课内使用，课外使用需登记
+  risk_factors:
+    - 每周跟踪 C4/ai_dependency；若独立题正确率连续 2 周下降则触发暂停
+```

package/references/education-framing.md

@@ -0,0 +1,132 @@
+# Education Research Framing（教育研究框架）
+
+## 1. 为什么先 Frame 再回答
+
+教育问题的答案高度依赖上下文：同一个干预（例如"允许学生使用 AI 编程助手"）
+在一个班级是脚手架，在另一个班级可能变成依赖源。脱离 Frame 直接回答，
+等于把某篇论文的结论盲目套用到一个未必匹配的课堂。因此本框架规定：
+
+- **任何最终教学建议都必须由一个完整的 EducationResearchFrame 推导而来。**
+- Frame 不完整时，只能给出"需要补充哪些信息"的中间反馈，禁止生成最终建议。
+
+### 执行规则（必须遵守）
+
+| 规则编号 | 内容 |
+| --- | --- |
+| FR-01 | 回答教育问题前，先输出 EducationResearchFrame；缺失任一必填字段则框架不完整。 |
+| FR-02 | 框架完整前，禁止输出最终教学建议（含"建议允许/不允许""建议调整策略"等结论性语句）。 |
+| FR-03 | 框架内不得出现"待定""TBD""占位符"；未知信息应明确标注 `unknown + 如何获取`。 |
+| FR-04 | Frame 与证据（Evidence）必须一起呈现：先 Frame，再 Evidence，最后结论。 |
+
+## 2. EducationResearchFrame 字段清单
+
+### question（研究问题）
+
+- 用一句话表述，必须包含"干预 × 学习者 × 结果"三要素。
+- 示例：`"在 Python 入门课中，允许使用 AI 代码补全是否会影响学生的独立编程能力？"`
+
+### decision_target（决策目标）
+
+- 本次回答要支持的具体决策，例如"是否允许某工具""是否采用某教学法""是否调整某门课的评分规则"。
+- 一个 Frame 只服务一个 decision_target；多目标请拆分为多个 Frame。
+
+### learner（学习者）
+
+- `education_level`：小学 / 初中 / 高中 / 大学本科（大一…大四）/ 研究生 / 成人 / 职业培训。
+- `major`：专业或院系背景（如计算机、非计算机、人文社科），影响先前经验假设。
+- `prior_knowledge`：目标技能的前测水平描述（如"未系统学过编程，仅会打字与上网"）。
+- `special_characteristics`：特殊特征（如高年级占比、性别比例、民族/语言差异、学习障碍、班内基础两极分化）。
+
+### course（课程）
+
+- `subject`：学科（如 C 语言、数据结构、线性代数）。
+- `course_type`：课程类型（必修/选修、理论/实验/混合、项目制、MOOC）。
+- `duration`：课程总时长（如 16 周、一学期 48 学时、两周集训营）。
+
+### intervention（干预）
+
+- `teaching_method`：教学方法（讲授、翻转课堂、项目式、同伴教学等）。
+- `ai_tool`：具体 AI 工具及版本（如 GitHub Copilot v1.x、ChatGPT GPT-4o、Cursor；未指定版本视为不完整）。
+- `allowed_usage`：允许的使用方式（禁止使用 / 仅解释报错 / 局部生成须注释 / 完全放开）。
+- `frequency`：使用频率（每节课几次、每周上限）。
+- `duration`：干预持续时长（如 4 周、一整个学期）。
+
+### comparison（对照组）
+
+- 与什么比较：无 AI 传统教学 / 无 AI 但加强练习 / 不同 AI 策略。
+- 若缺失对照，只能得到描述性结果，不能得到因果结论。
+
+### outcomes（结果）
+
+- `primary`：主要结果，通常是"学习效果"类指标（见 outcome-taxonomy.md），一个为佳。
+- `secondary`：次要结果（任务表现、学习过程指标）。
+- `risk`：风险指标（AI 依赖、学术诚信风险等），必须至少列出并监控一项。
+
+### context（情境）
+
+- `teacher_support`：教师支持程度（有无助教、教师是否懂 AI、答疑频次）。
+- `class_size`：班级规模（20 人小班 / 100 人大班 / 2000 人 MOOC）。
+- `online_or_offline`：线上 / 线下 / 混合。
+
+### scope（证据检索范围）
+
+- `time_range`：文献时间范围（如 2015–2025，AI 教育研究时效性强，优先近 3 年）。
+- `geography`：地域范围（国内 / 欧美 / 全球；注意文化差异）。
+- `study_types`：纳入的研究类型（RCT、准实验、观察性、质性）。
+
+### inclusion_criteria / exclusion_criteria（纳入/排除标准）
+
+- 纳入标准示例：`样本为本科编程入门课；干预与 AI 工具相关；报告至少一个学习结果指标。`
+- 排除标准示例：`仅报告满意度或工具使用时长；样本为研究生及以上；干预时长不足 2 周。`
+
+### success_condition（成功条件）
+
+- 判断"该干预值得继续/推广"的可操作标准，例如：
+  `"迁移测试成绩无显著下降（效应量 -0.1 以内）且 AI 依赖风险指标不升高，即可继续试点。"`
+
+## 3. 示例 Frame：大一C语言课是否允许使用AI编程助手
+
+```
+question: 在大一 C 语言程序设计必修课中，允许学生使用 AI 编程助手
+          （自动补全 + 完整代码生成）是否会影响其独立编程能力与课堂作业诚信？
+decision_target: 决定该课程本学期的 AI 使用政策（禁止 / 受限允许 / 放开）
+learner:
+  education_level: 大学本科一年级
+  major: 非计算机专业（电子信息类）
+  prior_knowledge: 无编程基础；高中信息课仅接触 Office；前测 0-1 道题可独立完成
+  special_characteristics: 班内基础差异大，约 30% 学生畏难、倾向直接抄答案
+course:
+  subject: C 语言程序设计
+  course_type: 必修、含 2 学时/周实验课
+  duration: 16 周（一学期）
+intervention:
+  teaching_method: 讲授 + 上机实验 + 每周编程作业
+  ai_tool: GitHub Copilot（指定版本）+ 课堂专用受限账号（无登录历史）
+  allowed_usage: 待评估——本次回答的决策对象
+  frequency: 每周作业 1 次，实验课 2 学时
+  duration: 8 周（试点阶段）
+comparison: 同期不启用 AI 的平行班（同教材同教师）
+outcomes:
+  primary: 期末独立编程题得分（无 AI 环境考试）
+  secondary: 作业正确率、完成时间、课堂参与度
+  risk: 脱离 AI 后能否独立改错；作业代写检测；学生对 AI 的依赖自评
+context:
+  teacher_support: 1 名教师 + 1 名研究生助教；教师已通过 AI 工具培训
+  class_size: 约 60 人 / 班
+  online_or_offline: 线下实验课 + 线上提交作业
+scope:
+  time_range: 2019–2025
+  geography: 国内高校 + 欧美本科入门编程课研究
+  study_types: RCT、准实验、有对照的前后测研究
+inclusion_criteria: 本科入门编程课；干预涉及代码补全/生成类 AI；报告学习或迁移指标
+exclusion_criteria: 仅报告"学生满意度"或"使用时长"；干预不足 2 周；样本为研究生
+success_condition: 8 周试点后，独立编程题得分与对照班无显著差异（下降不超 5%），
+                  且 AI 依赖风险指标不高于对照组，则允许受限使用；否则维持禁止。
+```
+
+## 4. 框架使用顺序
+
+1. 用户提出教育问题 → 先把问题翻译成 `question + decision_target`。
+2. 逐一核对全部字段；缺信息时向用户提问或标注 `unknown + 获取途径`。
+3. 字段齐全后，才允许检索证据、构建 Evidence Matrix。
+4. 最后基于 Frame 输出建议，并明示该建议仅对该 Frame 有效（见 applicability-policy.md）。

package/references/effect_size_formulas.md

@@ -0,0 +1,35 @@
+# Effect Size Formulas & Statistical Reference
+
+> **Standardized Mean Differences (Cohen's d, Hedges' g) & Difference-in-Differences (DID)**
+
+---
+
+## 1. Standardized Mean Difference: Cohen's d and Hedges' g
+
+Given Treatment Group (n1, mean1, sd1) and Control Group (n2, mean2, sd2):
+
+### Pooled Standard Deviation (s_pooled):
+s_pooled = sqrt(((n1 - 1)*sd1^2 + (n2 - 1)*sd2^2) / (n1 + n2 - 2))
+
+### Cohen's d:
+d = (mean1 - mean2) / s_pooled
+
+### Hedges' g (Small-Sample Bias Correction J):
+J(df) = 1 - (3 / (4 * (n1 + n2 - 2) - 1))
+g = J(df) * d
+
+### Variance and Standard Error of g:
+Var(g) = (n1 + n2)/(n1 * n2) + (g^2) / (2 * (n1 + n2))
+SE(g) = sqrt(Var(g))
+95% CI(g) = [g - 1.96 * SE(g), g + 1.96 * SE(g)]
+
+---
+
+## 2. Difference-in-Differences (DID) Regression Model
+
+For panel/classroom trial data across pre- and post-periods:
+Y_ist = beta0 + beta1 * Treat_i + beta2 * Post_t + delta * (Treat_i * Post_t) + epsilon_ist
+
+- beta1: Baseline difference between treatment and control cohorts.
+- beta2: Shared secular trend over time.
+- delta: The causal DID treatment effect parameter ((Y_T_post - Y_T_pre) - (Y_C_post - Y_C_pre)).

package/references/evaluation-design.md

@@ -0,0 +1,111 @@
+# Evaluation Design（评价设计）
+
+## 1. 目的与核心区分
+
+评价设计回答：**试点是否成功？** 评价必须同时区分两组维度，禁止混为一谈：
+
+```
+即时效果（immediate）  ≠  保持（retention）  ≠  迁移（transfer）
+任务表现（task performance, C2）  ≠  学习（learning, C1）
+```
+
+任何"成功"判定必须说明它来自哪个维度。只用任务表现定成功 → 无效评价。
+
+## 2. EvaluationPlan 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `research_question` | 与 Frame.question 一致的一句话问题 |
+| `groups` | `treatment`（试点组）与 `comparison`（对照/基线组）的定义与人数 |
+| `baseline` | 前测内容与时间点（无 AI 环境，测 C1 基线） |
+| `post_test` | 干预结束时的即时后测（仍按阶段 AI 政策执行） |
+| `retention_test` | 结课后 2–4 周的延迟测验（无 AI） |
+| `transfer_test` | 新题型/新环境/无 AI 的迁移任务 |
+| `process_metrics` | 学习过程数据（C3：engagement、help_seeking、cognitive_load 等） |
+| `learning_metrics` | 学习效果数据（C1：knowledge_gain、independent_problem_solving 等） |
+| `risk_metrics` | 风险数据（C4：ai_dependency、over_reliance、academic_integrity_risk） |
+| `analysis_plan` | 统计方法、效应量与置信区间、多重比较控制 |
+| `success_threshold` | 判定成功的预注册阈值（必须同时看学习与风险） |
+| `stop_conditions` | 立即终止/回退的阈值（与 intervention-design.md 一致） |
+
+## 3. 测量时间轴（推荐模板）
+
+| 时间点 | 测量 | 维度 |
+| --- | --- | --- |
+| T0（试点前） | 前测（无 AI）：语法知识 + 独立编程题 + 学习动机问卷 | C1 基线、C3 |
+| T1（每阶段末） | 阶段小测、AI 使用日志、求助行为记录 | C2、C3、C4 |
+| T2（第 8 周末） | 后测：即时独立编程测验 + 满意度/依赖自评 | C1（即时）、C2、C4 |
+| T3（+2~4 周） | 保持测验（无 AI，新题但同难度） | C1/retention |
+| T4（+2~4 周内） | 迁移任务（新题型或换语言，无 AI） | C1/transfer、C4 |
+
+## 4. 指标绑定规则
+
+- `learning_metrics` 只收 C1 指标；`process_metrics` 只收 C3；`risk_metrics` 只收 C4；
+  C2（任务表现）单列，不得混入 learning_metrics。
+- 每条数据记录格式：`指标名（类别）— 时间点 — 组别 — 值/变化`。
+- 缺失 retention/transfer 测量的评价报告不得包含"长期有效""能迁移"字样。
+
+## 5. 分析与成功判定
+
+### 5.1 analysis_plan（示例）
+
+- 主要比较：treatment vs comparison 在 T2 的 C1 后测差；效应量 Cohen's d 与 95% CI。
+- 保持与迁移：T3、T4 两组差异（若 T2 有差异但 T3/T4 消失 → 即时红利假象）。
+- 风险联动：C1 提升的同时检查 C4 是否上升；上升则成功判定需打折。
+- 多重比较：涉及多个学习指标时做 Bonferroni 或 FDR 校正。
+- 缺失值：报告 dropout 率；> 20% 需做敏感性分析。
+
+### 5.2 success_threshold（示例）
+
+成功 = 以下**全部**满足：
+
+1. T2 无 AI 独立测验：treatment 不显著低于 comparison（d ≥ -0.1）；
+2. T3 保持测验：无显著差异（d ≥ -0.15）；
+3. T4 迁移测验：treatment 不显著低于 comparison（d ≥ -0.2）；
+4. C4 风险指标不高于 comparison（ai_dependency 无上升）；
+5. 代写命中率 ≤ 5%。
+
+> 注意：允许阈值用"不显著低于对照"而不是"显著高于"，因为目标常是"在不损害学习的
+> 前提下获得效率红利"，高估是更危险的错误。
+
+## 6. 常见陷阱与检查
+
+| 陷阱 | 检查 |
+| --- | --- |
+| 只用 AI 环境成绩定成功 | 必须有无 AI 的 post/retention/transfer 测量 |
+| 后测即用训练题 | 后测、保持、迁移必须与训练题不同 |
+| 无基线对照 | T0 必须测量，否则不能归因 |
+| 只报平均分不报方差 | 报告分布与效应量，警惕少数人拉高均值 |
+| 实验组额外获得辅导 | 记录辅导时间，作为 confounder 控制 |
+
+## 7. 评价示例（C 语言 4 阶段试点）
+
+```
+research_question: 8 周分阶段 AI 使用政策是否影响大一 C 语言学生
+                   的独立编程能力、保持、迁移与 AI 依赖？
+groups:
+  treatment: 试点班 60 人（4 阶段政策）
+  comparison: 平行班 60 人（全程禁止 AI，同教材同教师）
+baseline: T0 无 AI 前测（语法知识 20 题 + 独立编程 3 题），两组基线可比性卡方检验
+post_test: T2 无 AI 独立编程测验（新题 4 道，覆盖指针/数组/函数）
+retention_test: T3（+3 周）同难度新题 4 道（无 AI）
+transfer_test: T4 用 C++ 实现链表反转（无 AI，教师未教过该语法）
+process_metrics: 上机活跃时长、求助 AI 次数、Phase2/3 越界使用次数、NASA-TLX
+learning_metrics: T2/T3/T4 得分（C1）；T2 与 T0 差 = knowledge_gain
+risk_metrics: 撤除 AI 后独立完成率、代写检测率、依赖自评（4 题量表）
+analysis_plan: 独立样本 t 检验 + Cohen's d；risk 指标做秩和检验；
+               T3/T4 为关键检验（防即时红利假象）；FDR 校正
+success_threshold:
+  - T2 d ≥ -0.1 且 T3 d ≥ -0.15 且 T4 d ≥ -0.2（treatment 不低于 comparison）
+  - C4 无上升（依赖自评与撤除后完成率不劣于 comparison）
+  - 代写命中率 ≤ 5%
+stop_conditions:
+  - 任意阶段无 AI 独立题正确率低于基线 15% 连续 2 周
+  - 越界使用完整代码生成比例 > 40%
+  - 代写命中率 > 10%
+```
+
+## 8. 报告最小清单
+
+评价报告必须包含：测量时间轴、各组人数与 dropout、每条指标的组间差（含效应量与
+置信区间）、retention 与 transfer 结果、C4 风险结果、对照 success_threshold 的逐条判定。

package/references/evidence-quality.md

@@ -0,0 +1,79 @@
+# Evidence Quality（证据质量评估）
+
+## 1. 五维质量框架（每维 0/1/2 分）
+
+每条证据按以下五个维度独立打分，各维得分相加，总分 0–10。
+
+### D1 Study Design（研究设计）
+
+- 2 分：随机对照试验（RCT）或有清晰匹配的准实验，含对照且干预与测量分离。
+- 1 分：有对照但非随机（如自然班对照）；或前后测无对照；或仅有单组重复测量。
+- 0 分：纯观察 / 调查 / 主观报告 / 无对照的描述性研究。
+
+> 对照缺失时该维至多 0 分，整条证据通常无法支撑因果结论。
+
+### D2 Sample Quality（样本质量）
+
+- 2 分：样本与目标 learner 匹配（如同为本科大一编程入门）、样本量足够（每组 ≥ 30）、报告了基线差异并处理。
+- 1 分：样本基本匹配但有偏差（如报名制、自选实验组）、样本量偏小（每组 10–30）。
+- 0 分：样本严重不匹配（如用研究生推本科结论）、样本量 < 10、无任何样本描述。
+
+### D3 Measurement Validity（测量有效性）
+
+- 2 分：测量工具已验证（标准量表、标准题型）、前后测等价、评分有规范（如盲评、双人评卷）。
+- 1 分：测量合理但未验证（自编题目、自评量表）、评分主观且未盲评。
+- 0 分：测量与声称结果不对应（如用满意度代替学习效果）、或测量就是任务表现却被当作学习效果。
+
+> 参考 outcome-taxonomy.md：把 C2 当 C1 测量属于测量无效，D3 记 0 分。
+
+### D4 Temporal Strength（时间强度）
+
+- 2 分：干预 ≥ 8 周，且包含保持测试（retention test）或迁移测试（transfer test）。
+- 1 分：干预 2–8 周，有后测但无保持/迁移测量。
+- 0 分：单次实验/单课时干预，或只有即时效果无任何后续测量。
+
+### D5 Directness（直接性）
+
+- 2 分：证据的 干预×学习者×课程×工具×结果 与目标 Frame 完全对应（如同是"大一 C 语言 + 代码生成工具 + 独立编程"）。
+- 1 分：大致对应但有偏差（不同课程但同难度、不同工具同类型、仅指标相近）。
+- 0 分：仅在变量名称上相关（如用"编程课满意度"支撑"编程能力"结论）。
+
+> 直接性越低，外推风险越高，需在结论中明确限定范围（见 applicability-policy.md）。
+
+## 2. 总分与等级
+
+| 总分 | 等级 | 含义 | 使用方式 |
+| --- | --- | --- | --- |
+| 8–10 | `strong` | 设计、样本、测量、时间、直接性均强 | 可支撑较高置信度的建议 |
+| 5–7 | `moderate` | 基本可信但有一两处明显不足 | 可作支持性证据，需限范围 |
+| 2–4 | `weak` | 设计或测量存在硬伤 | 仅作参考线索，不单独支撑结论 |
+| 0–1 | `very_weak` | 几乎不可用 | 不进入 Evidence Matrix 或仅作"反例提示" |
+
+## 3. 评分示例
+
+### 示例 A：某 RCT，大一 C 语言，Copilot vs 无 AI，8 周，含 4 周保持测试与无 AI 迁移测试
+
+- D1=2（RCT 有对照）；D2=2（每组 45 人、基线匹配）；D3=2（标准题本 + 盲评）；
+- D4=2（8 周 + 保持 + 迁移）；D5=2（与目标 Frame 完全对应）。
+- **总分 10 = strong**。
+
+### 示例 B：某班用 AI 后"作业提交率上升"，教师自评"教学效果变好"
+
+- D1=0（无对照）；D2=1（一个班 28 人）；D3=0（满意度/提交率当学习效果）；
+- D4=0（无保持/迁移测量）；D5=1（班级相似但测量不对应）。
+- **总分 1 = very_weak**，不得进入结论。
+
+### 示例 C：某研究用"高中 Python 课 + 代码补全"替代"本科 C 语言"，其余条件一致
+
+- D1=2；D2=2；D3=2；D4=1（只有后测无保持测试）；D5=1（课程与学习者层面有偏差）。
+- **总分 8 = strong**，但直接性扣分意味着结论必须限定"对高中 Python 场景强、对本科 C 场景中等"。
+
+## 4. 使用规则（必须遵守）
+
+| 编号 | 内容 |
+| --- | --- |
+| EQ-01 | 每条证据必须给出五维逐项得分与总分，禁止只给一个模糊的"质量高/低"。 |
+| EQ-02 | 任何维度证据不足时记 0 分，禁止用"大概""据经验"补分。 |
+| EQ-03 | 总分 < 5 的证据不能单独支撑教学建议；`very_weak` 证据不进 Evidence Matrix。 |
+| EQ-04 | 结论的置信度与证据等级联动：`strong` 可给高置信度建议，`moderate` 必须附条件，`weak` 只能给"待验证"。 |
+| EQ-05 | 质量评估针对"证据"，不针对"研究作者"；同一研究的不同结论需分别评分。 |

package/references/grade_framework.md

@@ -0,0 +1,29 @@
+# GRADE (Grading of Recommendations Assessment, Development and Evaluation)
+
+> **GRADE Certainty of Evidence Rating Framework for Social & Educational Science**
+
+---
+
+## 1. Four Levels of Evidence Certainty
+
+1. **High (++++)**: We are very confident that the true effect lies close to that of the estimate of the effect.
+2. **Moderate (+++o)**: We are moderately confident in the effect estimate; the true effect is likely to be close, but there is a possibility that it is substantially different.
+3. **Low (++oo)**: Our confidence in the effect estimate is limited; the true effect may be substantially different from the estimate.
+4. **Very Low (+ooo)**: We have very little confidence in the effect estimate; the true effect is likely to be substantially different from the estimate.
+
+---
+
+## 2. Five Downgrading Criteria (1 to 2 Levels Down per domain)
+
+1. **Risk of Bias (Study Limitations)**: Flawed randomization, allocation concealment failure, lack of blinding in subjective assessments, selective outcome reporting.
+2. **Inconsistency (Heterogeneity)**: High unexplained heterogeneity across studies (I^2 > 50%, Cochran Q p < 0.10, conflicting effect directions).
+3. **Indirectness**: Population mismatch (e.g. university CS majors vs K-12 primary students), intervention mismatch, surrogate outcomes (task completion instead of delayed transfer).
+4. **Imprecision**: Wide 95% confidence intervals crossing clinical/educational decision thresholds, small pooled sample size (N < 200).
+5. **Publication Bias**: Funnel plot asymmetry (Egger regression p < 0.10), missing negative trial results, Rosenthal Fail-Safe N < 5k + 10.
+
+---
+
+## 3. Three Upgrading Criteria (Only for Observational/QED without initial downgrades)
+1. **Large Effect Size**: g > 0.80 (upgrade 1 level); g > 1.20 (upgrade 2 levels).
+2. **Dose-Response Gradient**: Clear monotonic relationship between exposure dose and outcome gain.
+3. **Plausible Residual Confounding**: All plausible unmeasured confounders would diminish the observed effect rather than explain it.