eduevidence 5.2.0

package/domains/policy/manifest.json

@@ -0,0 +1,10 @@
+{
+  "domain": "policy",
+  "name": "policy（政策分析）",
+  "description": "政策分析领域（v4 首个自带契约的独立领域）。政策分析框架关注 decision_object/intervention/population/stakeholders/outcomes/context/scope，刻意不使用 education-frame 的 learner/course 概念。结果分类 5 类、方法学清单 12 项，配套 5 篇政策证据方法学短文（domains/policy/references/）。",
+  "frame_schema": "domains/policy/frame.schema.json",
+  "outcome_taxonomy": "domains/policy/outcome_taxonomy.json",
+  "methodology_checklist": "domains/policy/methodology_checklist.json",
+  "golds_dir": null,
+  "references_dir": "domains/policy/references"
+}

package/domains/policy/methodology_checklist.json

@@ -0,0 +1,109 @@
+{
+  "domain": "policy",
+  "name_zh": "政策证据质量 12 项清单",
+  "description": "评估一项政策证据（研究/综述）在政策决策意义上的质量。每项 status 枚举：met / partial / missing / not_applicable。配套方法学短文见 domains/policy/references/。",
+  "items": [
+    {
+      "id": "evidence_level",
+      "label_zh": "证据等级",
+      "question_zh": "证据是否来自系统综述、RCT 或高质量准实验？证据等级是否明确标注？",
+      "references": [
+        "evidence-hierarchy.md"
+      ]
+    },
+    {
+      "id": "causal_identification",
+      "label_zh": "因果识别",
+      "question_zh": "是否明确识别因果效应而非仅相关？识别策略（RCT/自然实验/DID/断点/IV）是否可信？",
+      "references": [
+        "causal-identification.md"
+      ]
+    },
+    {
+      "id": "external_validity",
+      "label_zh": "外部效度",
+      "question_zh": "结果能否推广到目标辖区与人群？情境差异（制度/文化/时间）是否被讨论？",
+      "references": [
+        "evidence-hierarchy.md"
+      ]
+    },
+    {
+      "id": "cost_evidence",
+      "label_zh": "成本证据",
+      "question_zh": "是否报告政策成本（财政/实施/机会成本）？是否有成本-效果或成本-收益分析？",
+      "references": [
+        "cost-evidence.md"
+      ]
+    },
+    {
+      "id": "stakeholder_representation",
+      "label_zh": "利益相关者代表",
+      "question_zh": "受益者、受损者与实施者的观点是否被代表，而非仅决策者视角？",
+      "references": [
+        "equity.md"
+      ]
+    },
+    {
+      "id": "implementation_evidence",
+      "label_zh": "实施证据",
+      "question_zh": "是否包含实施过程证据（保真度/覆盖率/实施能力/抵制）？",
+      "references": [
+        "implementation-evidence.md"
+      ]
+    },
+    {
+      "id": "equity_analysis",
+      "label_zh": "公平性分析",
+      "question_zh": "政策对不同群体的分布效应是否被分析（含弱势群体）？",
+      "references": [
+        "equity.md"
+      ]
+    },
+    {
+      "id": "effect_size_reported",
+      "label_zh": "效应量报告",
+      "question_zh": "是否报告效应量与置信区间，而非仅报告统计显著性？",
+      "references": [
+        "causal-identification.md"
+      ]
+    },
+    {
+      "id": "uncertainty_quantified",
+      "label_zh": "不确定性量化",
+      "question_zh": "不确定性是否被量化（敏感性分析/置信区间/情景）？",
+      "references": [
+        "cost-evidence.md"
+      ]
+    },
+    {
+      "id": "comparator_clarity",
+      "label_zh": "对照与反事实清晰",
+      "question_zh": "对照组/反事实是否明确（政策前后、无政策地区）？",
+      "references": [
+        "causal-identification.md"
+      ]
+    },
+    {
+      "id": "publication_bias_risk",
+      "label_zh": "发表偏倚风险",
+      "question_zh": "是否考虑发表偏倚与选择性报告？",
+      "references": [
+        "evidence-hierarchy.md"
+      ]
+    },
+    {
+      "id": "generalizability_claims",
+      "label_zh": "可推广性声明",
+      "question_zh": "结论外推的边界是否如实声明（不夸大适用范围）？",
+      "references": [
+        "implementation-evidence.md"
+      ]
+    }
+  ],
+  "statuses": [
+    "met",
+    "partial",
+    "missing",
+    "not_applicable"
+  ]
+}

package/domains/policy/outcome_taxonomy.json

@@ -0,0 +1,53 @@
+{
+  "domain": "policy",
+  "source": "v4 policy domain 自建契约（domains/policy/outcome_taxonomy.json）",
+  "categories": {
+    "effectiveness": {
+      "name_zh": "效果",
+      "description_zh": "政策效果类结果。"
+    },
+    "cost": {
+      "name_zh": "成本",
+      "description_zh": "成本与资源配置类结果。"
+    },
+    "equity": {
+      "name_zh": "公平",
+      "description_zh": "公平与分配类结果。"
+    },
+    "feasibility": {
+      "name_zh": "可行性",
+      "description_zh": "实施可行性类结果。"
+    },
+    "risk": {
+      "name_zh": "风险",
+      "description_zh": "实施与执行风险类结果。"
+    }
+  },
+  "tokens": [
+    {
+      "id": "policy_effectiveness",
+      "category": "effectiveness",
+      "description_zh": "政策有效性：政策在真实情境中实现既定目标的因果效果（直接效果与净效果）。"
+    },
+    {
+      "id": "cost_effectiveness",
+      "category": "cost",
+      "description_zh": "成本效益：单位财政/资源投入所实现的效果（成本-效果分析、成本-收益分析）。"
+    },
+    {
+      "id": "equity",
+      "category": "equity",
+      "description_zh": "公平性：政策收益与成本在不同群体间的分配，尤其弱势群体是否受益或受损。"
+    },
+    {
+      "id": "feasibility",
+      "category": "feasibility",
+      "description_zh": "可行性：在给定制度、资源与政治约束下政策可实施的程度。"
+    },
+    {
+      "id": "implementation_risk",
+      "category": "risk",
+      "description_zh": "实施风险：政策落地过程中的执行风险（抵制、腐败、能力缺口、意外后果）。"
+    }
+  ]
+}

package/domains/policy/references/causal-identification.md

@@ -0,0 +1,45 @@
+# 政策证据的因果识别（Causal Identification）
+
+> 政策分析领域方法学短文 2/5 · 对应 checklist 项：causal_identification、comparator_clarity、effect_size_reported
+
+## 为什么政策证据必须问因果
+
+政策决策的核心问题是「如果采纳这项政策，结果会改变吗」。
+相关不等于因果：高绩效地区更可能推行某项政策，
+不代表该政策带来了高绩效——这是反向因果与选择效应。
+
+## 可信的识别策略
+
+1. **随机对照试验（RCT）**：随机分配消除可观测与不可观测混杂；
+   政策场景常受伦理（剥夺福利）、政治（公平诉求）与
+   溢出效应（控制组受政策波及）限制，未必总能实施。
+2. **双重差分（DID）**：比较「政策前后 × 处理/对照」的差异变化；
+   核心假设是平行趋势——政策前两组走势一致。
+3. **断点回归（RDD）**：利用分配规则（如分数线、贫困线）附近的
+   局部随机性；识别的是断点处局部平均处理效应（LATE），
+   外推到远离断点的人群需谨慎。
+4. **工具变量（IV）**：用只通过政策影响结果的外生变量
+   剥离内生性；工具变量相关性、排他性难以完全验证。
+5. **合成控制 / 匹配**：构造与处理组相似的反事实；
+   依赖可观测变量充分性假设（无隐藏混杂）。
+
+## 常见威胁清单
+
+- **选择偏差**：接受政策的人群与未接受者系统性不同。
+- **时间趋势**：政策前后自然变化被误归因于政策。
+- **同期干预**：评估窗口内发生其他政策变化。
+- **溢出/干扰**：处理组影响控制组，低估或高估效应。
+- **测量变化**：政策伴随统计口径改变，效应是测量假象。
+
+## 报告要求
+
+- 必须报告：识别策略、反事实构造、平行趋势/排他性检验、
+  效应量与置信区间（不能只给 p 值）。
+- 敏感性分析：更换样本、控制变量与估计方法后结论是否稳健。
+
+## 与清单的关系
+
+- `causal_identification`：识别策略是否可信。
+- `comparator_clarity`：对照/反事实是否明确。
+- `effect_size_reported`：是否报告效应量与不确定性。
+

package/domains/policy/references/cost-evidence.md

@@ -0,0 +1,44 @@
+# 政策证据中的成本证据（Cost Evidence）
+
+> 政策分析领域方法学短文 3/5 · 对应 checklist 项：cost_evidence、uncertainty_quantified
+
+## 为什么成本是政策证据的一部分
+
+「有效」不等于「值得」。一项有效但昂贵的政策可能挤占
+更优的资源配置。政策决策必须同时回答：
+效果有多大、成本有多高、谁承担成本、单位成本值不值。
+
+## 核心分析框架
+
+1. **成本-效果分析（CEA）**：比较不同方案在单一效果单位上的
+   单位成本（如每提升 1 分成绩的成本）；不把效果货币化。
+2. **成本-收益分析（CBA）**：把效果货币化后与成本比较，
+   回答「净收益是否为正」；货币化假设常受争议。
+3. **成本-效用分析（CUA）**：以质量调整生命年等效用单位
+   衡量效果，适合跨领域比较。
+4. **预算影响分析（BIA）**：财政约束下采纳该政策的预算影响，
+   回答「付得起吗」。
+
+## 成本要素清单
+
+- **财政成本**：直接政府支出（人员、物资、设施）。
+- **实施成本**：培训、监督、信息系统、合规管理。
+- **机会成本**：资源用于本政策而放弃的次优用途。
+- **社会成本**：家庭/企业承担的合规与时间成本。
+- **成本转移**：成本从政府转移到家庭（如家长陪护、自购设备）。
+
+## 不确定性处理
+
+- 参数不确定：关键参数（效果、单价、贴现率）应做
+  **敏感性分析**（单变量与多变量）与情景分析。
+- 时间维度：跨期成本与收益应贴现，报告贴现率假设。
+- 报告规范：说明分析视角（政府视角/社会视角）、
+  时间范围与数据来源，保证可复现。
+
+## 与清单的关系
+
+- `cost_evidence`：是否报告成本与成本-效果/收益分析。
+- `uncertainty_quantified`：成本与效果参数的不确定性是否量化。
+- 缺失成本证据不等于政策无效，而是**决策信息不完整**，
+  应标记为证据缺口而不是反对意见。
+

package/domains/policy/references/equity.md

@@ -0,0 +1,42 @@
+# 政策证据中的公平性（Equity）
+
+> 政策分析领域方法学短文 4/5 · 对应 checklist 项：equity_analysis、stakeholder_representation
+
+## 为什么公平性是政策证据的维度
+
+政策不是对「平均人」生效：同一政策对不同群体的效果与负担
+可能差异巨大。只看平均效应会掩盖「惠及强者、伤害弱者」
+的分配结果。教育/健康/就业等公共政策尤其如此。
+
+## 需要考察的分配维度
+
+1. **人群维度**：收入、性别、年龄、民族、地域、
+   残障状况、城乡、是否弱势家庭。
+2. **效果分配**：政策收益（成绩提升、服务可及）在不同群体
+   间是否公平分布；弱势群体是否获益较少甚至受损。
+3. **负担分配**：成本（时间、金钱、合规）由谁承担；
+   政策是否把负担转移给最无承受力的群体。
+4. **可及性**：弱势群体是否因信息、语言、数字鸿沟
+   无法享受政策红利（如线上服务反而排除无网家庭）。
+
+## 公平性评估方法
+
+- **亚组分析**：按关键维度报告亚组效应，而非只报总体。
+- **分布效应分析**：政策前后不同群体的受益/受损分布。
+- **公平影响评估（EIA）**：政策提案前系统评估公平影响。
+- **利益相关者参与**：把受益者、受影响方、实施者纳入评估，
+  避免「替弱者发言」的单方视角。
+
+## 常见错误
+
+- 只报告平均效应，掩盖群体差异（Simpson 悖论）。
+- 把「总福利最大」当作唯一标准，忽视分配公平。
+- 用「所有学生都适用」之类声明回避亚组证据缺失。
+
+## 与清单的关系
+
+- `equity_analysis`：分布效应与亚组分析是否充分。
+- `stakeholder_representation`：利益相关者是否被代表。
+- 公平性缺失时应明确标注为证据缺口，
+  尤其当政策涉及公共服务与弱势群体时。
+

package/domains/policy/references/evidence-hierarchy.md

@@ -0,0 +1,41 @@
+# 政策证据等级（Evidence Hierarchy）
+
+> 政策分析领域方法学短文 1/5 · 对应 checklist 项：evidence_level
+
+## 目的
+
+政策证据等级帮助决策者快速判断「这条证据在因果强度上有多可信」，
+避免把弱设计（前后对比、专家意见）当作强证据使用。
+
+## 常用等级阶梯（从强到弱）
+
+1. **系统综述 / 荟萃分析**：对多个高质量研究的结构化综合；
+   能汇总效应量并检验异质性，是政策证据的最高等级。
+2. **随机对照试验（RCT）**：随机分配政策干预与对照；
+   因果推断的金标准，但在政策场景常受伦理与实施限制。
+3. **准实验设计**：双重差分（DID）、断点回归（RDD）、
+   工具变量（IV）、合成控制；无随机化但构造可信反事实。
+4. **前后对比 / 时间序列**：只有时间维度上的比较；
+   无法排除同期政策、趋势与回归均值等威胁。
+5. **观察性相关研究**：横断面或纵向相关；只能提示关联，
+   不能支撑因果结论。
+6. **案例研究 / 定性证据**：提供机制理解与情境细节；
+   回答「为什么」与「如何」，不代表平均因果效应。
+7. **专家意见 / 共识声明**：无系统证据时的兜底，
+   应明确标注为意见而非证据。
+
+## 政策场景下的重要提醒
+
+- **等级不是唯一标准**：一项高质量、贴近本地情境的准实验，
+  可能比一项异地、人群不匹配的系统综述更有决策价值。
+- **匹配决策问题**：评估「是否该采纳」更依赖因果证据；
+  评估「如何落地」则更需要实施证据与过程评价。
+- **报告义务**：引用证据时应同时给出等级与适用边界，
+  不得用「研究表明」掩盖设计缺陷。
+
+## 与清单的关系
+
+- `evidence_level`：证据等级是否明确标注。
+- `publication_bias_risk`：高等级证据同样可能受发表偏倚影响。
+- `external_validity`：等级高不等于可直接推广到本地。
+

package/domains/policy/references/implementation-evidence.md

@@ -0,0 +1,47 @@
+# 政策证据中的实施证据（Implementation Evidence）
+
+> 政策分析领域方法学短文 5/5 · 对应 checklist 项：implementation_evidence、generalizability_claims
+
+## 为什么有效政策仍会失败
+
+一项在试点中有效的政策，落地时可能因为执行不力而失败。
+「有没有效」（effectiveness）与「能不能落地」（implementation）
+是两个不同的问题。实施证据回答后者：
+政策在真实制度环境中如何被采纳、执行与维持。
+
+## 实施证据的核心维度
+
+1. **保真度（fidelity）**：实际执行与政策设计的一致程度；
+   偏离是合理适配还是走样。
+2. **覆盖率（coverage/reach）**：目标人群中有多大比例
+   实际接触到政策；服务盲区在哪里。
+3. **实施能力（capacity）**：实施机构的资源、技能、
+   人员与信息系统是否足以支撑政策。
+4. **采纳与抵制（uptake/resistance）**：基层执行者与
+   受影响方的配合程度、抵制来源与原因。
+5. **维持与制度化（sustainability）**：政策是否在
+   财政与人事变动后仍能持续。
+6. **意外后果（unintended consequences）**：政策引发的
+   替代行为、寻租、负担转移等未预期效应。
+
+## 常用方法
+
+- **过程评价（process evaluation）**：跟踪实施过程，识别断点。
+- **实施研究框架**：RE-AIM（覆盖/效果/采纳/实施/维持）、
+  CFIR（实施研究整合框架）等结构化分析。
+- **混合方法**：量化指标 + 定性访谈解释「为什么执行走样」。
+- **保真度-适配平衡**：区分必须保持的核心要素与允许适配的外围要素。
+
+## 对决策的意义
+
+- 实施证据强、效果证据弱：政策可行但效果存疑，适合小规模试点。
+- 效果证据强、实施证据弱：政策有效但落地风险高，
+  应优先建设实施能力与保障条件。
+- 两者都弱：不足以支持全面推广。
+
+## 与清单的关系
+
+- `implementation_evidence`：是否包含实施过程证据。
+- `generalizability_claims`：从试点到推广的外推边界
+  必须如实声明，不得把试点效果直接当作推广效果。
+

package/eduevidence_cli.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""eduevidence_cli.py — console-script shim for `eduevidence`.
+
+Installed via pyproject.toml [project.scripts]: the real implementation lives
+in scripts/orchestrator.py; this module only puts scripts/ (and the repo root
+for retrieval/integrations packages) on sys.path and forwards to it.
+
+Usage:
+    eduevidence run --question "..." --depth deep
+    eduevidence resume --run-id <id>
+    eduevidence status --run-id <id>
+    eduevidence list
+    eduevidence gate --run-id <id>
+"""
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+for _p in (str(ROOT / "scripts"), str(ROOT)):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from orchestrator import main  # noqa: E402
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engine/__init__.py

@@ -0,0 +1,11 @@
+"""EduEvidence V2 Research Engine — internal capability core.
+
+The competition artifact remains the EduEvidence Skill; this package is the
+engine behind it. Native Core depends only on the Python standard library.
+"""
+
+# Single source of truth for the engine version lives in engine/versions.py;
+# re-exported here so `from engine import ENGINE_VERSION` stays valid.
+from .versions import ENGINE_VERSION
+
+__all__ = ["ENGINE_VERSION"]