eduevidence 5.2.0

package/retrieval/validate.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""validate.py — Fetch Validation Gate (Smart Web Fetch 方案 v3 §7-8).
+
+A successful fetch is NOT automatically evidence. Checks:
+
+    HTTP success / body length / title match / URL match
+    login page? / error page? / captcha? / navigation only? / too short?
+    scheme whitelist (http/https) / private-network target (incl. redirects)
+
+Output: passed(bool) + per-check results. FETCH_FAILED content must never be
+used for Evidence Extraction (v3 §8).
+"""
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from typing import Any
+from urllib.parse import urlparse
+
+ERROR_PATTERNS = [
+    r"(?i)404 not found",
+    r"(?i)page not found",
+    r"(?i)access denied",
+    r"(?i)forbidden",
+    r"(?i)service unavailable",
+]
+LOGIN_PATTERNS = [
+    r"(?i)sign in to continue",
+    r"(?i)please log in",
+    r"(?i)login required",
+]
+CAPTCHA_PATTERNS = [
+    r"(?i)captcha",
+    r"(?i)verify you are human",
+    r"(?i)cloudflare",
+    r"(?i)robot check",
+]
+NAV_ONLY_MARKERS = ["menu", "home", "about us", "contact us", "privacy policy"]
+
+ALLOWED_SCHEMES = ("http", "https")
+
+# Third-party cleaning providers fetch a wrapped URL (r.jina.ai/<url>), not the
+# original — a resolved-vs-original URL equality check is meaningless for them.
+WRAPPER_PROVIDERS = ("jina_reader", "markdown_new")
+
+
+def _count(text: str, patterns: list[str]) -> int:
+    return sum(1 for p in patterns if re.search(p, text))
+
+
+# ---------------------------------------------------------------- private URL
+
+
+_CGNAT_NET = ipaddress.ip_network("100.64.0.0/10")
+
+
+def _ip_is_private(addr: ipaddress._BaseAddress) -> bool:
+    """Loopback / private / link-local / CGNAT / reserved / multicast / unspecified."""
+    return (
+        addr.is_loopback
+        or addr.is_private
+        or addr.is_link_local
+        or addr.is_reserved
+        or addr.is_multicast
+        or addr.is_unspecified
+        or addr in _CGNAT_NET
+    )
+
+
+def is_private_url(url: str) -> bool:
+    """True if the URL targets a private/local/unsafe location.
+
+    Host-based judgement only (urllib.parse.urlparse + ipaddress): loopback,
+    private, link-local, CGNAT, reserved, multicast and unspecified address
+    ranges, plus local hostnames (localhost / *.localhost / *.local). URL path
+    content — e.g. a DOI's "10." prefix — never influences the verdict.
+
+    Non-http(s) schemes (file://, ftp://, data:, ...) also count as private:
+    such URLs must never reach third-party cleaning providers.
+    """
+    if not url:
+        return True
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return True
+    scheme = (parsed.scheme or "").lower()
+    if scheme not in ALLOWED_SCHEMES:
+        return True
+    host = (parsed.hostname or "").lower()
+    if not host:
+        return True
+    if host == "localhost" or host.endswith(".localhost") or host.endswith(".local"):
+        return True
+    try:
+        addr = ipaddress.ip_address(host)  # IPv4 literals and bracketed IPv6
+    except ValueError:
+        return False  # a normal DNS name is not private by itself
+    return _ip_is_private(addr)
+
+
+def resolves_to_private(url: str) -> bool | None:
+    """Best-effort DNS re-check: does the URL's host resolve to a private IP?
+
+    Guards against redirect targets whose hostname resolves to a loopback /
+    private address (e.g. DNS-rebinding style redirects). Returns None when
+    the host cannot be resolved — that is treated as "not private" by callers.
+    """
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return True
+    host = parsed.hostname
+    if not host:
+        return True
+    try:
+        ipaddress.ip_address(host)
+    except ValueError:
+        pass
+    else:
+        return is_private_url(url)  # literal IP: judge directly
+    try:
+        infos = socket.getaddrinfo(host, parsed.port or 80, proto=socket.IPPROTO_TCP)
+    except OSError:
+        return None
+    for info in infos:
+        try:
+            addr = ipaddress.ip_address(info[4][0])
+        except ValueError:
+            continue
+        if _ip_is_private(addr):
+            return True
+    return False
+
+
+# ------------------------------------------------------------- URL comparison
+
+
+def _normalize_url(url: str) -> str:
+    """Normalize for comparison: lowercase scheme/host, drop default port,
+    strip fragment and trailing slash."""
+    try:
+        p = urlparse(url)
+    except ValueError:
+        return url
+    scheme = (p.scheme or "").lower()
+    host = (p.hostname or "").lower()
+    if p.port is None or p.port == {"http": 80, "https": 443}.get(scheme):
+        port_str = ""
+    else:
+        port_str = f":{p.port}"
+    path = p.path.rstrip("/") or "/"
+    query = f"?{p.query}" if p.query else ""
+    return f"{scheme}://{host}{port_str}{path}{query}"
+
+
+def _same_path_and_query(resolved: str, original: str) -> bool:
+    """True when both URLs denote the same resource path/query even if the host
+    changed — the canonical doi.org -> publisher redirect pattern."""
+    try:
+        rp = urlparse(resolved)
+        op = urlparse(original)
+    except ValueError:
+        return False
+    return (rp.path.rstrip("/") or "/") == (op.path.rstrip("/") or "/") and rp.query == op.query
+
+
+def _same_doi(resolved: str, original: str) -> bool:
+    """True when both URLs reference the same DOI (doi.org -> publisher hops)."""
+    from retrieval.source import parse_doi_from_url
+
+    r_doi = parse_doi_from_url(resolved)
+    o_doi = parse_doi_from_url(original)
+    return bool(r_doi and o_doi and r_doi.lower() == o_doi.lower())
+
+
+# ---------------------------------------------------------------- validation
+
+
+def validate_fetch_result(result: dict[str, Any], *, expect_title: str | None = None) -> dict[str, Any]:
+    """Run the Fetch Validation Gate over a fetch result dict.
+
+    Returns {"passed": bool, "checks": {...}, "issues": [...]}.
+    """
+    content = result.get("content", "") or ""
+    status = result.get("fetch_status", "FETCH_FAILED")
+    checks: dict[str, Any] = {}
+    issues: list[str] = []
+
+    if status == "FETCH_FAILED":
+        checks["http_success"] = False
+        checks["body_length_ok"] = False
+        return {"passed": False, "checks": checks, "issues": ["FETCH_FAILED: no content"]}
+
+    checks["http_success"] = True
+    checks["body_length_ok"] = len(content) >= 200
+    if not checks["body_length_ok"]:
+        issues.append("body too short")
+
+    checks["is_error_page"] = _count(content, ERROR_PATTERNS) >= 2
+    checks["is_login_page"] = _count(content, LOGIN_PATTERNS) >= 1
+    checks["is_captcha_page"] = _count(content, CAPTCHA_PATTERNS) >= 1
+    checks["navigation_only"] = all(m in content.lower() for m in NAV_ONLY_MARKERS) and len(content) < 1000
+
+    if expect_title:
+        title = content.splitlines()[0].strip() if content.splitlines() else ""
+        checks["title_matches"] = expect_title.lower() in (title.lower() or content[:200].lower())
+        if not checks["title_matches"]:
+            issues.append("expected title not found in content head")
+    else:
+        checks["title_matches"] = None
+
+    # URL match: real comparison between the resolved URL (resp.geturl(), after
+    # redirects) and the original URL. Wrapper providers fetch a different URL
+    # by design, so the check is not applicable (None) for them.
+    provider = result.get("fetch_provider", "")
+    resolved_url = result.get("resolved_url") or ""
+    original_url = result.get("original_url") or ""
+    if provider in WRAPPER_PROVIDERS or not resolved_url or not original_url:
+        checks["url_matches"] = None
+    else:
+        checks["url_matches"] = (
+            _normalize_url(resolved_url) == _normalize_url(original_url)
+            or _same_path_and_query(resolved_url, original_url)
+            or _same_doi(resolved_url, original_url)
+        )
+        if not checks["url_matches"]:
+            issues.append("resolved URL does not match original URL")
+
+    # Scheme whitelist: only http/https may enter Evidence Extraction.
+    if original_url:
+        checks["scheme_allowed"] = (urlparse(original_url).scheme or "").lower() in ALLOWED_SCHEMES
+        if not checks["scheme_allowed"]:
+            issues.append("unsupported URL scheme (only http/https)")
+    else:
+        checks["scheme_allowed"] = None
+
+    # Private-target re-check after redirects/DNS. A public request that landed
+    # on a private network is a security event and must fail; a local request
+    # (original already private, fetched natively) stays usable.
+    if resolved_url and original_url:
+        original_private = is_private_url(original_url)
+        checks["private_target"] = is_private_url(resolved_url)
+        if checks["private_target"] and not original_private:
+            issues.append("fetch resolved to a private/local network")
+    elif resolved_url:
+        checks["private_target"] = is_private_url(resolved_url)
+    else:
+        checks["private_target"] = None
+
+    failed_hard = any(checks[k] for k in ("is_error_page", "is_login_page", "is_captcha_page", "navigation_only"))
+    if failed_hard:
+        issues.append("blocked/error-like page detected")
+
+    passed = not failed_hard and checks["body_length_ok"] and not issues
+    return {"passed": passed, "checks": checks, "issues": issues}

package/schemas/agent-mcp-approval.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/agent-mcp-approval.schema.json",
+  "title": "AgentMcpApproval",
+  "description": "User approval record for the Agent MCP role -> CLI -> model mapping (Phase 8 Approval Gate). Only an explicit, hash-verified record permits spawning via safe_spawn(). Any change to the mapping (new CLI / replaced model / new role / modified mapping / raised budget / new provider) invalidates the record and requires re-confirmation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["approved", "approved_at", "allowed_clis", "role_mapping_hash", "roles"],
+  "properties": {
+    "approved": {
+      "type": "boolean",
+      "const": true,
+      "description": "Explicit user confirmation. A mere agent-mcp installation is NOT approval."
+    },
+    "approved_at": { "type": "string", "format": "date-time" },
+    "allowed_clis": {
+      "type": "array",
+      "description": "CLI set the user allowed for dispatch (scan scope + gate check).",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "role_mapping_hash": {
+      "type": "string",
+      "description": "SHA-256 of the canonical 'roles' object; integrity check against tampering.",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "roles": {
+      "type": "object",
+      "description": "role -> {cli, model} mapping the user explicitly approved; enforced verbatim by safe_spawn().",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["cli", "model"],
+        "properties": {
+          "cli": { "type": "string" },
+          "model": { "type": "string" }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "description": "Approved cost/budget envelope (per-run or per-task); raising it requires re-confirmation.",
+      "additionalProperties": true
+    },
+    "provider": {
+      "type": ["string", "null"],
+      "description": "Approved provider endpoint; a new provider requires re-confirmation."
+    },
+    "schema_version": { "type": "integer", "const": 1 },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/chart-spec.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/chart-spec.schema.json",
+  "title": "ChartSpec",
+  "description": "Chart spec produced by visualization build_charts.py. integrity is a per-check map with PASS/FAIL/NOT_CHECKED strings (P0-2 rewrite to match the real producer).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "chart_id",
+    "purpose",
+    "engine",
+    "chart_type"
+  ],
+  "properties": {
+    "chart_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "purpose": {
+      "type": "string"
+    },
+    "engine": {
+      "type": "string",
+      "enum": [
+        "echarts",
+        "svg"
+      ]
+    },
+    "chart_type": {
+      "type": "string",
+      "minLength": 1
+    },
+    "semantic_basis": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "option": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "summary_text": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "numbers_match_result": {
+          "type": "string",
+          "enum": [
+            "PASS",
+            "FAIL",
+            "NOT_CHECKED"
+          ]
+        },
+        "no_axis_distortion": {
+          "type": "string",
+          "enum": [
+            "PASS",
+            "FAIL",
+            "NOT_CHECKED"
+          ]
+        },
+        "no_false_precision": {
+          "type": "string",
+          "enum": [
+            "PASS",
+            "FAIL",
+            "NOT_CHECKED"
+          ]
+        },
+        "colorblind_safe": {
+          "type": "string",
+          "enum": [
+            "PASS",
+            "FAIL",
+            "NOT_CHECKED"
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/cross-model-review.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/cross-model-review.schema.json",
+  "title": "CrossModelReview",
+  "description": "Output contract of the independent-model cross review (总体实施计划 §25). An independent model (different model/CLI than the primary analysis) verifies a Draft Verdict before the Final Judge rules. 扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["agreement", "final_recommendation"],
+  "properties": {
+    "agreement": {
+      "type": "string",
+      "description": "To what degree the reviewer agrees with the draft verdict (e.g. 'high/partial/low agreement on the four-state decision')."
+    },
+    "disagreements": { "type": "array", "items": { "type": "string" } },
+    "unsupported_claims": { "type": "array", "items": { "type": "string" } },
+    "missed_counterevidence": { "type": "array", "items": { "type": "string" } },
+    "scope_violations": { "type": "array", "items": { "type": "string" } },
+    "methodology_issues": { "type": "array", "items": { "type": "string" } },
+    "confidence_adjustment": { "type": "string", "enum": ["upgrade", "downgrade", "no_change"] },
+    "required_revision": { "type": "boolean", "default": false },
+    "final_recommendation": { "type": "string" },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/education-frame.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/education-frame.schema.json",
+  "title": "EducationResearchFrame",
+  "description": "Structured framing of an education research question. Framing MUST be completed before any final teaching recommendation is generated (EduEvidence EvidenceFlow Protocol, step 1). 扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["question", "decision_target"],
+  "properties": {
+    "question": {
+      "type": "string",
+      "minLength": 5,
+      "description": "The teaching/education question, e.g. 'Should first-year C programming students be allowed to use generative AI coding assistants?'"
+    },
+    "decision_target": {
+      "type": "string",
+      "enum": ["evidence_review", "teaching_decision", "pilot_design", "evaluation_design"],
+      "description": "What the user wants to produce. Default for the skill: evidence_review."
+    },
+    "learner": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "education_level": { "type": "string", "examples": ["undergraduate_year_1"] },
+        "major": { "type": "string", "examples": ["computer_science"] },
+        "prior_knowledge": { "type": "string", "examples": ["first_programming_course"] },
+        "special_characteristics": { "type": "string", "examples": ["mixed_ability", "large_class"] }
+      }
+    },
+    "course": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "subject": { "type": "string", "examples": ["C_programming"] },
+        "course_type": { "type": "string", "examples": ["lecture_lab", "lab_only", "flipped"] },
+        "duration": { "type": "string", "examples": ["16_weeks", "one_semester"] }
+      }
+    },
+    "intervention": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "teaching_method": { "type": "string", "examples": ["paired_programming", "problem_based_learning"] },
+        "ai_tool": { "type": "string", "examples": ["github_copilot", "chatgpt", "generic_generative_ai"] },
+        "allowed_usage": { "type": "string", "examples": ["explain_errors_only", "full_code_generation"] },
+        "frequency": { "type": "string", "examples": ["every_class", "weekly"] },
+        "duration": { "type": "string", "examples": ["8_weeks"] }
+      }
+    },
+    "comparison": {
+      "type": "string",
+      "description": "Comparison condition, e.g. 'no AI usage', 'textbook-only', 'TA support only'."
+    },
+    "outcomes": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "primary": {
+          "type": "array",
+          "items": { "type": "string", "enum": [
+            "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"
+          ] }
+        },
+        "secondary": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "risk": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "teacher_support": { "type": "string", "examples": ["TA_supported", "trained_instructors"] },
+        "class_size": { "type": "string", "examples": ["60_students"] },
+        "online_or_offline": { "type": "string", "enum": ["online", "offline", "hybrid"] }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "time_range": { "type": "string", "examples": ["2019-2025"] },
+        "geography": { "type": "string", "examples": ["worldwide"] },
+        "study_types": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "inclusion_criteria": { "type": "array", "items": { "type": "string" } },
+    "exclusion_criteria": { "type": "array", "items": { "type": "string" } },
+    "success_condition": { "type": "string", "description": "What would count as a successful outcome for this decision." },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/evaluation.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/evaluation.schema.json",
+  "title": "EvaluationPlan",
+  "description": "Evaluation design attached to any PILOT / ADOPT recommendation. Must separate Task Performance from Learning, and Immediate from Retention/Transfer. 扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["research_question", "groups", "analysis_plan"],
+  "properties": {
+    "research_question": { "type": "string" },
+    "groups": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "treatment": { "type": "string" },
+        "comparison": { "type": "string" }
+      }
+    },
+    "baseline": { "type": "string", "description": "Pre-test / baseline measurement." },
+    "post_test": { "type": "string" },
+    "retention_test": { "type": ["string", "null"], "description": "Delayed test (e.g. 4-8 weeks after intervention)." },
+    "transfer_test": { "type": ["string", "null"], "description": "New task in a no-AI environment to verify real transfer." },
+    "process_metrics": { "type": "array", "items": { "type": "string" } },
+    "learning_metrics": { "type": "array", "items": { "type": "string" } },
+    "risk_metrics": { "type": "array", "items": { "type": "string" } },
+    "analysis_plan": { "type": "string" },
+    "success_threshold": { "type": "string" },
+    "stop_conditions": { "type": "array", "items": { "type": "string" } },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/evidence.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/evidence.schema.json",
+  "title": "EvidenceObject",
+  "description": "Claim-level evidence object. MANDATORY fields (schema v1.1): evidence_id, source_id, study_id, sample_id, claim_id, claim, outcome_type, relation_to_claim, effect_direction, source_location. Missing any mandatory field marks the object as UNSUPPORTED. 三种方向语义严格分开：relation_to_claim（支持/反驳某条 claim）、effect_direction（研究观察到的效应方向）、decision_relation（对最终教学决策的意义）。direction 为旧契约字段，仅向后兼容，已废弃（deprecated）。扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["evidence_id", "source_id", "study_id", "sample_id", "claim_id", "claim", "outcome_type", "relation_to_claim", "effect_direction", "source_location"],
+  "properties": {
+    "evidence_id": { "type": "string", "examples": ["E-001"] },
+    "source_id": { "type": "string", "examples": ["S-2023-kazemitabaar"] },
+    "study_id": { "type": "string", "description": "所属研究的稳定标识，用于独立研究计数（独立于 evidence_id，防止同一研究的多条 Evidence Object 重复放大信心）。" },
+    "sample_id": { "type": "string", "description": "所属样本的稳定标识，用于独立样本计数。无法区分样本时可显式使用 UNKNOWN-SAMPLE-<study_id>，但不能静默缺失。" },
+    "claim_id": { "type": "string", "description": "该证据所绑定 Claim 的稳定标识（Claim Registry 一等字段，Claim -> Evidence -> Source 不再依赖渲染阶段临时编号）。", "examples": ["C-003"] },
+    "title": { "type": "string" },
+    "year": { "type": ["integer", "null"] },
+    "study_type": {
+      "type": "string",
+      "enum": ["rct", "quasi_experimental", "observational", "survey", "qualitative", "meta_analysis", "literature_review", "case_study", "mixed_methods"]
+    },
+    "education_level": { "type": "string", "examples": ["undergraduate", "k12", "graduate"] },
+    "subject": { "type": "string", "examples": ["programming", "mathematics", "writing"] },
+    "population": { "type": "string", "examples": ["first_year_CS_students"] },
+    "sample_size": { "type": ["integer", "null"], "minimum": 0 },
+    "intervention": { "type": "string", "examples": ["copilot_allowed_in_lab"] },
+    "comparison": { "type": "string", "examples": ["no_ai_control_group"] },
+    "outcome_type": {
+      "type": "string",
+      "enum": [
+        "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"
+      ]
+    },
+    "outcome_measure": { "type": "string", "examples": ["final_exam_score", "post_test_transfer_task"] },
+    "claim": { "type": "string", "description": "The specific claim this evidence supports or contradicts." },
+    "direction": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "DEPRECATED: legacy direction field, kept for backward compatibility only. Use relation_to_claim instead." },
+    "relation_to_claim": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "该证据与 claim 的关系（支持/反驳/中性）。Claim Audit 只依据此字段判断支持/反驳，不得用 effect_direction 或 legacy direction 替代。" },
+    "effect_direction": { "type": "string", "enum": ["positive", "negative", "null"], "description": "研究观察到的效应方向。Outcome 可视化 / 聚合只依据此字段。" },
+    "decision_relation": { "type": "string", "enum": ["support_adoption", "oppose_adoption", "conditional", "neutral"], "description": "该证据对最终教学决策的意义（支持采纳/反对采纳/有条件采纳/中性）。跨研究一致性（Consistency）与 Tribunal 依据此字段计算。" },
+    "effect": { "type": "string", "examples": ["positive_medium", "null", "negative_small"] },
+    "duration": { "type": "string", "examples": ["8_weeks"] },
+    "method": { "type": "string", "examples": ["quasi_experimental_pre_post"] },
+    "strengths": { "type": "array", "items": { "type": "string" } },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "confounders": { "type": "array", "items": { "type": "string" } },
+    "source_location": { "type": "string", "description": "Verifiable pointer to the source (DOI / URL / database identifier / page)." },
+    "quality_dimensions": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "D1 Study Design, D2 Sample Quality, D3 Measurement Validity, D4 Temporal Strength, D5 Directness. Each scored 0/1/2.",
+      "properties": {
+        "D1_study_design": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "D2_sample_quality": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "D3_measurement_validity": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "D4_temporal_strength": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "D5_directness": { "type": "integer", "minimum": 0, "maximum": 2 }
+      }
+    },
+    "quality_score": { "type": ["number", "null"], "minimum": 0, "maximum": 10 },
+    "evidence_level": {
+      "type": "string",
+      "enum": ["strong", "moderate", "weak", "very_weak"]
+    },
+    "applicability": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Match against the target context: learner match, subject match, tool match, usage match, teacher support match."
+    },
+    "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
+    "status": { "type": "string", "enum": ["SUPPORTED", "UNSUPPORTED", "DOWNGRADE_CONFIDENCE", "CONTRADICT"], "default": "SUPPORTED" },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}