eduevidence 5.2.0

package/bin/eduevidence.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * EduEvidence npm CLI — wraps install.sh from the published package root.
+ *
+ *   npm install -g eduevidence
+ *   eduevidence skill              # interactive host picker (default)
+ *   eduevidence skill --host claude
+ *   npx eduevidence skill --list-hosts
+ */
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const INSTALL_SH = path.join(PKG_ROOT, 'install.sh');
+
+function usage() {
+  console.log(`eduevidence ${readPkgVersion()} — Evidence-Based Education Decision Skill
+
+Install (Python runtime + self-check):
+  eduevidence install [--dev] [--dry-run]
+
+Install as AI Agent Skill:
+  eduevidence skill                         Interactive host picker
+  eduevidence skill --host <name>           claude | codex | cursor | all | …
+  eduevidence skill --dest <dir>            Custom skill root (creates <dir>/eduevidence/)
+  eduevidence skill --list-hosts            Supported agents and install paths
+  eduevidence skill --dry-run               Preview without writing
+
+Legacy install.sh flags (also accepted):
+  eduevidence --skill [--host claude] [--dry-run]
+  eduevidence --list-hosts
+
+Requires: bash, Python 3.10+ (for install / scripts)
+Docs: https://github.com/37chengshan/eduevidence/blob/main/docs/install-guide.md
+`);
+}
+
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'),
+    );
+    return pkg.version || '';
+  } catch {
+    return '';
+  }
+}
+
+function runInstallSh(args) {
+  if (!fs.existsSync(INSTALL_SH)) {
+    console.error('ERROR: install.sh not found in package:', PKG_ROOT);
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(PKG_ROOT, 'SKILL.md'))) {
+    console.error('ERROR: SKILL.md not found in package:', PKG_ROOT);
+    process.exit(1);
+  }
+
+  const result = spawnSync('bash', [INSTALL_SH, ...args], {
+    cwd: PKG_ROOT,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (result.error) {
+    console.error('ERROR: failed to run install.sh:', result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+function mapArgs(argv) {
+  if (argv.length === 0) {
+    usage();
+    return null;
+  }
+
+  const first = argv[0];
+  if (first === '-h' || first === '--help' || first === 'help') {
+    usage();
+    return null;
+  }
+
+  if (first === 'install') {
+    return argv.slice(1);
+  }
+
+  if (first === 'skill') {
+    const rest = argv.slice(1);
+    if (rest.includes('--list-hosts')) {
+      return ['--list-hosts'];
+    }
+    const out = ['--skill', '--skill-only'];
+    for (let i = 0; i < rest.length; i += 1) {
+      const arg = rest[i];
+      if (arg === '--host' || arg === '--dest') {
+        out.push(arg, rest[i + 1] ?? '');
+        i += 1;
+        continue;
+      }
+      if (arg === '--dry-run') {
+        out.push('--dry-run');
+        continue;
+      }
+      console.error(`ERROR: unknown skill flag: ${arg}`);
+      usage();
+      process.exit(1);
+    }
+    return out;
+  }
+
+  // Pass through legacy install.sh flags (--skill, --dev, --list-hosts, …).
+  return argv;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const mapped = mapArgs(argv);
+  if (mapped === null) {
+    process.exit(0);
+  }
+  runInstallSh(mapped);
+}
+
+main();

package/domains/education/manifest.json

@@ -0,0 +1,183 @@
+{
+  "domain": "education",
+  "name": "education（教育研究）",
+  "description": "education 域只是“指向现有契约”的注册：不新增任何逻辑路径，不引入新 schema / 新校验器 / 新方法学。引擎层 load_domain('education') 只做契约存在性校验；领域选择由主 agent 接 CLI 完成。",
+  "contracts_source": {
+    "frame_schema": "schemas/education-frame.schema.json（EducationResearchFrame，顶层 additionalProperties:false，required: question/decision_target）",
+    "outcome_taxonomy": "20 token 取自 schemas/evidence.schema.json 的 outcome_type enum；四类映射参考 engine/pilot.py _OUTCOME_CATEGORY",
+    "methodology_checklist": "15 项取自 skill/agents/method-reviewer.md；每项 status 枚举 met/partial/missing/not_applicable",
+    "golds_dir": "benchmarks/annotations（30 条人工金标 gold-Q*.json）",
+    "references_dir": "references（11 篇教育证据方法学文档）"
+  },
+  "frame_schema": "schemas/education-frame.schema.json",
+  "outcome_taxonomy": "domains/education/outcome_taxonomy.json",
+  "methodology_checklist": [
+    {
+      "id": "control_group",
+      "label_zh": "有无对照",
+      "description_zh": "是否设置对照/控制条件",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "randomization",
+      "label_zh": "是否随机",
+      "description_zh": "被试/班级是否随机分配",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "pre_test",
+      "label_zh": "有无前测",
+      "description_zh": "是否测量干预前基线",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "post_test",
+      "label_zh": "有无后测",
+      "description_zh": "是否测量干预后即时结果",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "retention_test",
+      "label_zh": "有无延迟/保持测试",
+      "description_zh": "是否有延迟保持测量",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "transfer_test",
+      "label_zh": "有无迁移测试",
+      "description_zh": "是否有迁移/新情境测量",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "sample_bias",
+      "label_zh": "样本偏差",
+      "description_zh": "样本是否具有代表性/存在偏差",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "self_selection",
+      "label_zh": "自选择",
+      "description_zh": "被试是否自选进入条件组",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "measurement_validity",
+      "label_zh": "测量效度",
+      "description_zh": "测量工具是否有效测量目标构念",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "confounders",
+      "label_zh": "混杂变量",
+      "description_zh": "是否识别并控制混杂变量",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "instructor_effect",
+      "label_zh": "教师效应",
+      "description_zh": "教师/授课者差异是否被控制",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "novelty_effect",
+      "label_zh": "新奇效应",
+      "description_zh": "干预新奇性是否影响结果",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "tool_version_effect",
+      "label_zh": "工具版本效应",
+      "description_zh": "AI 工具版本/配置是否明确固定",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "ai_usage_policy",
+      "label_zh": "AI 使用规则是否明确",
+      "description_zh": "AI 使用边界是否在研究中明确定义",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    },
+    {
+      "id": "dropout",
+      "label_zh": "流失率",
+      "description_zh": "流失率是否报告并处理",
+      "statuses": [
+        "met",
+        "partial",
+        "missing",
+        "not_applicable"
+      ]
+    }
+  ],
+  "golds_dir": "benchmarks/annotations",
+  "references_dir": "references"
+}

package/domains/education/outcome_taxonomy.json

@@ -0,0 +1,127 @@
+{
+  "domain": "education",
+  "source": {
+    "tokens": "schemas/evidence.schema.json -> outcome_type enum（20 token）",
+    "categories": "engine/pilot.py -> _OUTCOME_CATEGORY（learning/task_performance/process/risk 四类）"
+  },
+  "categories": {
+    "learning": {
+      "name_zh": "学习效果",
+      "description_zh": "指向学习本身的持久改变：知识、理解、保持与迁移。任务完成表现不能自动等价为学习效果。"
+    },
+    "task_performance": {
+      "name_zh": "任务表现",
+      "description_zh": "任务完成的质量与效率（完成时间/准确率/代码质量/作业成绩），不等于学习效果。"
+    },
+    "process": {
+      "name_zh": "学习过程",
+      "description_zh": "过程性变量：参与、动机、认知负荷、求助行为与元认知。"
+    },
+    "risk": {
+      "name_zh": "风险",
+      "description_zh": "干预（如 AI 工具）可能带来的风险与负面结果：依赖、过度依赖、努力减少、迁移受损、诚信风险、虚假信心。"
+    }
+  },
+  "tokens": [
+    {
+      "id": "knowledge_gain",
+      "category": "learning",
+      "description_zh": "知识获得：知识量的增加（测验得分提升）"
+    },
+    {
+      "id": "concept_understanding",
+      "category": "learning",
+      "description_zh": "概念理解：对核心概念的深层理解"
+    },
+    {
+      "id": "retention",
+      "category": "learning",
+      "description_zh": "保持：延迟测试后仍能保持所学"
+    },
+    {
+      "id": "transfer",
+      "category": "learning",
+      "description_zh": "迁移：迁移到新情境/新问题"
+    },
+    {
+      "id": "independent_problem_solving",
+      "category": "learning",
+      "description_zh": "独立解题：无支持下独立解决问题"
+    },
+    {
+      "id": "completion_time",
+      "category": "task_performance",
+      "description_zh": "完成时间：任务完成速度"
+    },
+    {
+      "id": "accuracy",
+      "category": "task_performance",
+      "description_zh": "准确率：任务完成正确率"
+    },
+    {
+      "id": "code_quality",
+      "category": "task_performance",
+      "description_zh": "代码质量：代码可读性/结构/缺陷密度"
+    },
+    {
+      "id": "assignment_score",
+      "category": "task_performance",
+      "description_zh": "作业成绩：作业/测验得分"
+    },
+    {
+      "id": "engagement",
+      "category": "process",
+      "description_zh": "参与度：课堂/任务参与程度"
+    },
+    {
+      "id": "motivation",
+      "category": "process",
+      "description_zh": "动机：学习动机与自我效能"
+    },
+    {
+      "id": "cognitive_load",
+      "category": "process",
+      "description_zh": "认知负荷：任务过程中的认知负荷体验"
+    },
+    {
+      "id": "help_seeking",
+      "category": "process",
+      "description_zh": "求助行为：求助模式（对 AI/教师/同伴）"
+    },
+    {
+      "id": "metacognition",
+      "category": "process",
+      "description_zh": "元认知：元认知监控与学习策略"
+    },
+    {
+      "id": "ai_dependency",
+      "category": "risk",
+      "description_zh": "AI 依赖：对 AI 工具的依赖程度"
+    },
+    {
+      "id": "over_reliance",
+      "category": "risk",
+      "description_zh": "过度依赖：过度依赖 AI 完成任务"
+    },
+    {
+      "id": "reduced_effort",
+      "category": "risk",
+      "description_zh": "努力减少：学习投入/努力下降"
+    },
+    {
+      "id": "reduced_transfer",
+      "category": "risk",
+      "description_zh": "迁移受损：迁移能力受损"
+    },
+    {
+      "id": "academic_integrity_risk",
+      "category": "risk",
+      "description_zh": "学术诚信风险：抄袭/作弊等诚信风险"
+    },
+    {
+      "id": "false_confidence",
+      "category": "risk",
+      "description_zh": "虚假信心：未掌握却过度自信"
+    }
+  ]
+}

package/domains/manifest.json

@@ -0,0 +1,26 @@
+{
+  "version": "4.0.0",
+  "description": "EduEvidence v4 领域注册表（EvidenceCore 抽象第一步）。每个条目声明一个领域的契约：frame_schema（框架 schema）、outcome_taxonomy（结果分类）、methodology_checklist（方法学清单）、golds_dir（金标目录）与 references_dir（参考文献目录）。education 为“指向现有契约”的注册域，不新增任何逻辑路径；policy 为 v4 首个自带契约的独立领域。domain select（领域选择）由主 agent 接 CLI 完成，引擎层不自行选择领域。",
+  "domains": [
+    {
+      "id": "education",
+      "name": "education",
+      "description": "教育研究领域（注册域，零逻辑路径）：框架复用 schemas/education-frame.schema.json（EducationResearchFrame），结果分类复用 evidence.schema.json 的 20 个 outcome_type token 并按 engine/pilot.py _OUTCOME_CATEGORY 归为四类，方法学清单复用 skill/agents/method-reviewer.md 的 15 项审查清单。",
+      "frame_schema": "schemas/education-frame.schema.json",
+      "outcome_taxonomy": "domains/education/outcome_taxonomy.json",
+      "methodology_checklist": "domains/education/manifest.json#/methodology_checklist",
+      "golds_dir": "benchmarks/annotations",
+      "references_dir": "references"
+    },
+    {
+      "id": "policy",
+      "name": "policy",
+      "description": "政策分析领域（v4 首个自带契约的独立领域）：政策分析框架（decision_object/intervention/population/stakeholders/outcomes/context/scope，不含 education-frame 的 learner/course 概念）、5 类政策结果分类（policy_effectiveness/cost_effectiveness/equity/feasibility/implementation_risk）与 12 项政策证据质量清单。",
+      "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/frame.schema.json

@@ -0,0 +1,234 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/domains/policy/frame.schema.json",
+  "title": "PolicyAnalysisFrame",
+  "description": "Structured framing of a policy analysis question (v4 policy domain). 政策分析框架：decision_object / intervention / population / stakeholders / outcomes / context / scope。刻意不使用 education-frame 的 learner/course 概念。扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "question",
+    "decision_object",
+    "intervention",
+    "population",
+    "outcomes"
+  ],
+  "properties": {
+    "question": {
+      "type": "string",
+      "minLength": 5,
+      "description": "政策分析问题，如 '是否应在公立高中全面推行无手机课堂政策？'"
+    },
+    "decision_object": {
+      "type": "string",
+      "enum": [
+        "adopt",
+        "modify",
+        "terminate",
+        "maintain",
+        "evaluate_impact"
+      ],
+      "description": "待决策的政策对象与动作：采纳 / 修改 / 终止 / 维持 / 评估影响。"
+    },
+    "intervention": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "待评估的政策干预本身（不是教学干预）。",
+      "properties": {
+        "policy_name": {
+          "type": "string",
+          "examples": [
+            "classroom_phone_ban"
+          ]
+        },
+        "policy_type": {
+          "type": "string",
+          "enum": [
+            "regulation",
+            "subsidy",
+            "tax_incentive",
+            "mandate",
+            "information_campaign",
+            "nudge",
+            "institutional_reform",
+            "other"
+          ]
+        },
+        "jurisdiction": {
+          "type": "string",
+          "examples": [
+            "public_high_schools",
+            "province_scope"
+          ]
+        },
+        "mechanism": {
+          "type": "string",
+          "description": "政策的作用机制/传导路径。"
+        },
+        "duration": {
+          "type": "string",
+          "examples": [
+            "3_years"
+          ]
+        },
+        "intensity": {
+          "type": "string",
+          "examples": [
+            "full_prohibition",
+            "partial"
+          ]
+        }
+      }
+    },
+    "population": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "政策针对的人群（不是 'learner' 学习者概念）。",
+      "properties": {
+        "target_group": {
+          "type": "string",
+          "examples": [
+            "public_high_school_students"
+          ]
+        },
+        "excluded_groups": {
+          "type": "string"
+        },
+        "scale": {
+          "type": "string",
+          "examples": [
+            "district_wide",
+            "national"
+          ]
+        }
+      }
+    },
+    "stakeholders": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "利益相关者：决策者、受益者、受影响方、实施者。",
+      "properties": {
+        "decision_maker": {
+          "type": "string",
+          "examples": [
+            "school_board",
+            "education_bureau"
+          ]
+        },
+        "beneficiaries": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "affected_parties": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "implementers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "outcomes": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "政策结果（policy outcome taxonomy 五类）。",
+      "properties": {
+        "primary": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "policy_effectiveness",
+              "cost_effectiveness",
+              "equity",
+              "feasibility",
+              "implementation_risk"
+            ]
+          }
+        },
+        "secondary": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "政策情境：制度环境、历史沿革、政治条件。",
+      "properties": {
+        "policy_environment": {
+          "type": "string",
+          "examples": [
+            "provincial_education_budget_constraint"
+          ]
+        },
+        "prior_policy_history": {
+          "type": "string"
+        },
+        "political_conditions": {
+          "type": "string"
+        }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "证据检索范围：时间窗、地理、证据类型。",
+      "properties": {
+        "time_range": {
+          "type": "string",
+          "examples": [
+            "2015-2025"
+          ]
+        },
+        "geography": {
+          "type": "string",
+          "examples": [
+            "CN",
+            "worldwide"
+          ]
+        },
+        "evidence_types": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "comparison": {
+      "type": "string",
+      "description": "对照/反事实条件，如 '无政策地区'、'政策实施前'。"
+    },
+    "inclusion_criteria": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "exclusion_criteria": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "success_condition": {
+      "type": "string",
+      "description": "什么算这项决策的成功结果。"
+    },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}