eduevidence 5.2.0

package/schemas/fetch-result.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/fetch-result.schema.json",
+  "title": "FetchResult",
+  "description": "Result of one fetch attempt through the Smart Web Fetch degradation chain (v3 方案 §6-8). Only FETCH_VALID (or rule-confirmed FETCH_PARTIAL) may enter Evidence Extraction; FETCH_FAILED must not let the model guess content from search snippets. 扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "original_url",
+    "fetch_status"
+  ],
+  "properties": {
+    "original_url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "resolved_url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "fetch_method": {
+      "type": "string",
+      "enum": [
+        "native",
+        "smart_web_fetch"
+      ]
+    },
+    "fetch_provider": {
+      "type": "string",
+      "enum": [
+        "builtin",
+        "jina_reader",
+        "markdown_new",
+        "defuddle",
+        "raw_html",
+        "pdf_parser"
+      ]
+    },
+    "fetch_status": {
+      "type": "string",
+      "enum": [
+        "FETCH_VALID",
+        "FETCH_PARTIAL",
+        "FETCH_FAILED"
+      ]
+    },
+    "fetched_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "content_hash": {
+      "type": "string"
+    },
+    "content_length": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "raw_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "clean_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "compression_ratio": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "fallback_used": {
+      "type": "boolean",
+      "default": false
+    },
+    "fallback_chain": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "content": {
+      "type": "string",
+      "description": "清洗后的正文（Markdown/文本），仅 FETCH_VALID/PARTIAL 时携带"
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "passed"
+      ],
+      "description": "Fetch Validation Gate result (validate_fetch_result output): passed + per-check booleans + issues.",
+      "properties": {
+        "passed": {
+          "type": "boolean"
+        },
+        "checks": {
+          "type": "object",
+          "additionalProperties": {
+            "type": [
+              "boolean",
+              "null"
+            ]
+          }
+        },
+        "issues": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/intervention.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/intervention.schema.json",
+  "title": "TeachingIntervention",
+  "description": "A minimal verifiable pilot intervention. EduEvidence NEVER recommends full deployment directly — it always produces a small-scale, evaluable pilot with stop conditions. 扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["decision", "target_learners", "pilot_duration", "stop_conditions"],
+  "properties": {
+    "decision": { "type": "string", "enum": ["adopt", "pilot", "reject", "insufficient_evidence"] },
+    "target_learners": { "type": "string" },
+    "learning_goals": { "type": "array", "items": { "type": "string" } },
+    "pilot_duration": { "type": "string", "examples": ["8_weeks"] },
+    "phase_1": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Phase structure: name, activities, ai_usage_rule, outcome_check.",
+      "properties": {
+        "name": { "type": "string" },
+        "activities": { "type": "array", "items": { "type": "string" } },
+        "ai_usage_rule": { "type": "string" },
+        "outcome_check": { "type": "string" }
+      }
+    },
+    "phase_2": { "type": "object", "additionalProperties": true },
+    "phase_3": { "type": "object", "additionalProperties": true },
+    "phase_4": { "type": "object", "additionalProperties": true },
+    "ai_usage_policy": { "type": "string", "description": "Explicit allowed/forbidden AI usage rules for students." },
+    "teacher_role": { "type": "string" },
+    "student_role": { "type": "string" },
+    "reflection_requirement": { "type": "string", "description": "e.g. students must explain key logic generated by AI." },
+    "assessment": { "type": "string" },
+    "risk_control": { "type": "array", "items": { "type": "string" } },
+    "stop_conditions": { "type": "array", "items": { "type": "string" } },
+    "evidence_alignment": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "evidence_id(s) that this intervention traces back to."
+    },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/methodology.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/methodology.schema.json",
+  "title": "MethodologyAudit",
+  "description": "Methodological audit of one study (or the overall evidence base). The highest-priority rule: task performance must NOT be automatically equated with learning effect. 扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "target",
+    "verdict",
+    "audit_items",
+    "task_vs_learning_guard",
+    "limitations",
+    "suggestions"
+  ],
+  "properties": {
+    "target": {
+      "type": "string",
+      "description": "evidence_id or source_id being audited, or 'overall'."
+    },
+    "audit_items": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "status"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "met",
+              "partial",
+              "missing",
+              "not_applicable"
+            ]
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Keys: control_group, randomization, pre_test, post_test, retention_test, transfer_test, sample_bias, self_selection, measurement_validity, confounders, instructor_effect, novelty_effect, tool_version_effect, ai_usage_policy, dropout."
+    },
+    "task_vs_learning_guard": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "measured_construct": {
+          "type": "string",
+          "examples": [
+            "task_completion",
+            "learning_outcome"
+          ]
+        },
+        "equates_task_with_learning": {
+          "type": "boolean"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "verdict": {
+      "type": "string",
+      "enum": [
+        "PASS",
+        "CONCERN",
+        "FAIL"
+      ]
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "suggestions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    },
+    "study_audits": {
+      "type": [
+        "array",
+        "null"
+      ],
+      "description": "Per-study methodology audits (method-reviewer output for multi-study reviews).",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/schemas/report-result.schema.json

@@ -0,0 +1,381 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/report-result.schema.json",
+  "title": "ReportResult",
+  "description": "Validated result.json contract (总体实施计划 §27). Produced by the EduEvidence research core, consumed by the visualization layer. The report layer may choose HOW to present but must never change this data. claims 每条必须携带 claim_id（C-001 格式，Claim-Evidence Contract）。扩展字段一律放在各对象 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "meta",
+    "research_frame",
+    "decision",
+    "evidence"
+  ],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "skill"
+      ],
+      "properties": {
+        "skill": {
+          "type": "string",
+          "const": "eduevidence"
+        },
+        "version": {
+          "type": "string"
+        },
+        "generated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "platform_native",
+            "agent_mcp_enhanced"
+          ]
+        },
+        "question": {
+          "type": "string"
+        },
+        "data_origin": {
+          "type": "string",
+          "enum": [
+            "real",
+            "synthetic",
+            "hybrid",
+            "manual_curated"
+          ],
+          "description": "Provenance of the pack data (plan R4). real=pipeline-generated from real studies; manual_curated=hand-curated from real verified studies; synthetic=demonstration content, not real studies; hybrid=mixed."
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How this result was produced: complexity grade, agent topology, token/cost usage.",
+      "properties": {
+        "complexity": {
+          "type": "string",
+          "enum": [
+            "S",
+            "M",
+            "L"
+          ]
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "platform_native",
+            "agent_mcp_enhanced"
+          ]
+        },
+        "agents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "usage": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "measurement_status"
+          ],
+          "description": "Token/cost usage. Unknown values are null with measurement_status=NOT_CAPTURED; never fabricate 0 as a real measurement (P1-3).",
+          "properties": {
+            "measurement_status": {
+              "type": "string",
+              "enum": [
+                "NOT_CAPTURED"
+              ],
+              "description": "NOT_CAPTURED: usage was not measured by the pipeline."
+            },
+            "input_tokens": {
+              "type": [
+                "integer",
+                "null"
+              ]
+            },
+            "output_tokens": {
+              "type": [
+                "integer",
+                "null"
+              ]
+            },
+            "cost_usd": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "latency_s": {
+              "type": [
+                "number",
+                "null"
+              ]
+            }
+          }
+        }
+      }
+    },
+    "research_frame": {
+      "type": "object",
+      "description": "EducationResearchFrame (see education-frame.schema.json)."
+    },
+    "decision": {
+      "type": "object",
+      "description": "EducationVerdict (see verdict.schema.json)."
+    },
+    "outcomes": {
+      "type": "array",
+      "description": "Outcome-level aggregation: per outcome type, effect_direction counts (positive/negative/null) and evidence ids.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "outcome_type": {
+            "type": "string"
+          },
+          "positive_count": {
+            "type": "integer"
+          },
+          "negative_count": {
+            "type": "integer"
+          },
+          "null_count": {
+            "type": "integer"
+          },
+          "evidence_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "claims": {
+      "type": "array",
+      "description": "Claim-level rows bound to evidence (Claim-Evidence Contract).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "claim_id"
+        ],
+        "properties": {
+          "claim_id": {
+            "type": "string",
+            "pattern": "^C-[0-9]{3}$",
+            "examples": [
+              "C-001"
+            ]
+          },
+          "claim": {
+            "type": "string"
+          },
+          "outcome_type": {
+            "type": "string"
+          },
+          "evidence_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "SUPPORTED",
+              "UNSUPPORTED",
+              "DOWNGRADE_CONFIDENCE",
+              "CONTRADICT"
+            ]
+          },
+          "bias_warning": {
+            "type": "string",
+            "description": "Optional methodological caveat attached to a claim row."
+          },
+          "pooled_effect_g": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Optional pooled Hedges g attached to a claim row."
+          }
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "description": "Source Objects (see source.schema.json).",
+      "items": {
+        "$ref": "source.schema.json"
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": [
+          "evidence_id",
+          "source_id",
+          "outcome_type",
+          "direction"
+        ]
+      },
+      "description": "Evidence rows (projection of evidence.schema.json; stage-level gate enforces the full contract)."
+    },
+    "methodology_reviews": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": [
+          "verdict"
+        ]
+      }
+    },
+    "conflicts": {
+      "type": "array",
+      "description": "Conflict analysis entries (why studies disagree).",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "applicability": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "intervention": {
+      "type": "object",
+      "description": "TeachingIntervention (see intervention.schema.json)."
+    },
+    "evaluation": {
+      "type": "object",
+      "description": "EvaluationPlan (see evaluation.schema.json)."
+    },
+    "benchmark": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Benchmark metrics for this result (optional)."
+    },
+    "outcome_mapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "entries",
+        "declared_without_evidence"
+      ],
+      "description": "Frame-declared vs evidence-covered outcome map (OPEN-2): every outcome type seen in frame or evidence, with directional counts and an explicit status. Entries never mix support/contradict/neutral.",
+      "properties": {
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "outcome_type",
+              "status",
+              "support_count",
+              "contradict_count",
+              "neutral_count",
+              "evidence_ids"
+            ],
+            "properties": {
+              "outcome_type": {
+                "type": "string"
+              },
+              "declared_in_frame": {
+                "type": "boolean"
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "supported",
+                  "contested",
+                  "contradicted",
+                  "null_evidence_only",
+                  "no_evidence"
+                ]
+              },
+              "support_count": {
+                "type": "integer"
+              },
+              "contradict_count": {
+                "type": "integer"
+              },
+              "neutral_count": {
+                "type": "integer"
+              },
+              "evidence_ids": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "declared_without_evidence": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Frame-declared outcomes that no evidence covers — the evidence gaps a decision must disclose."
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Fetch/search provenance (Smart Web Fetch v3 §6): sources must carry fetch provenance.",
+      "properties": {
+        "search_provider": {
+          "type": "string"
+        },
+        "fetched_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "fetch_summary": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "report_outline": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional chapter outline consumed by the report builder; the builder falls back to a safe six-chapter layout when absent."
+    },
+    "report_structure": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Legacy alias of report_outline accepted for compatibility."
+    },
+    "forest_plot_data": {
+      "type": "array",
+      "description": "Optional precomputed forest-plot rows consumed by the Web Studio visualization page (SKILL.md Visualization Data Contract).",
+      "items": {
+        "type": "object"
+      }
+    },
+    "visual_layout": {
+      "type": [
+        "object",
+        "array"
+      ],
+      "description": "Optional Lieflat gallery layout composition consumed by build_report.resolve_visual_layout."
+    },
+    "meta_analysis": {
+      "type": "object",
+      "description": "Optional pooled meta-analysis block (synthetic demo packs only unless engine-generated)."
+    }
+  }
+}