eduevidence 6.0.0 → 6.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to EduEvidence
+
+EduEvidence 是一个**证据驱动的决策引擎**：它的产出要能被第三方复核。因此本仓库的贡献规则有一条主线——**契约先行**。每个科学概念都在多处声明（协议、能力、角色、简报、子技能、分包），任何一处漂移都会让结论失去可追溯性。
+
+## 1. 环境准备
+
+```bash
+git clone https://github.com/37chengshan/eduevidence.git
+cd eduevidence
+bash install.sh            # venv + 依赖 + 自检 + 测试
+# 或最小安装
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+```
+
+要求 Python ≥ 3.10；内核（`engine/`、`retrieval/`）零第三方依赖，测试需要 `pytest`。Node 只在构建 Research Studio 前端时需要。
+
+## 2. 提交前必须跑的门
+
+```bash
+python scripts/check_version_consistency.py   # 版本口径单一权威
+python scripts/generate_metrics.py --check    # 文档数字与仓库一致
+python scripts/skill_lint.py                  # Skill 结构完整
+python scripts/check_protocol_alignment.py    # 协议五方对齐
+ruff check --select E9,F63,F7,F82 .
+python -m pytest -q
+```
+
+CI（`.github/workflows/ci.yml`）会重复执行上述门，外加 wheel 隔离安装冒烟、schema-smoke 与提交包构建。本地全绿是提交的最低门槛。
+
+## 3. 科学不变量（不可协商）
+
+- **任务表现 ≠ 学习效果**：任何把任务完成度当作学习收益的写法都会被门拒绝。
+- **snippet ≠ 证据**：检索片段与摘要只是发现线索，只有抓取并通过校验门的正文可以抽取。
+- **缺证据 ≠ 零效应**：证据不足时输出 `INSUFFICIENT EVIDENCE`，不得换算成"无效"。
+- **无证据奠基不得设计新研究**：研究设计必须引用显式的 KnowledgeGap ID。
+- **证据 append-only**：修订产生新 revision 与新 decision snapshot，绝不覆盖历史。
+- **写入者唯一**：图修订只能由规范写入者提交，worker 不得直接写图。
+
+详见 `references/scientific-invariants.md`，由 `scripts/check_autoresearch_invariants.py` 强制。
+
+## 4. 如何新增一项能力（capability）
+
+能力是"协议能做什么"的最小单元，它与模型、CLI、Agent 数量无关。新增一项能力需要同时落地四处，缺一不可：
+
+1. `engine/capabilities.py`：用 `_register(...)` 注册 `capability_id`、输入/输出契约、是否可确定性本地执行，以及（如有）科学门。
+2. `skill/roles/registry.yaml`：把能力分配给承担它的角色（`capabilities:` 列表）。
+3. `skill/agents/<role>.md`：在 frontmatter 的 `capabilities` 中同步，并在正文写清产出契约。
+4. `skill/sub-skills/<name>/SKILL.md`：frontmatter 写 `capability:`，正文按 recipe 模板给出 Inputs / Process / Output Contract / Quality Gates / Anti-Patterns。
+
+跑 `python scripts/check_protocol_alignment.py` 验证五方一致。
+
+## 5. 如何新增一个子技能（sub-skill）
+
+子技能是内部能力配方，不是新的用户入口。模板：
+
+```markdown
+---
+name: <dir-name>            # 必须与目录名一致
+description: "..."
+capability: <capability_id>  # 映射到 engine/capabilities.py
+---
+
+# <Title>
+## When to Use
+## Inputs
+## Process
+## Output Contract
+## Quality Gates
+## Anti-Patterns
+## Worked Example
+## References
+```
+
+## 6. 如何新增一个角色（role）
+
+角色是责任单元，不是运行时 Agent。新增角色需要：`skill/roles/registry.yaml`（stage / capability / critical_path）、`skill/agents/<role>.md`（frontmatter 用 `role_id` / `capabilities` / `output_contracts` / `recommended_reasoning`，**不得写死模型或 CLI 名**）、`integrations/agent_mcp.py` 的 `ROLE_REQUIREMENTS`（只写能力等级）。
+
+需要独立性的角色显式声明：`independence_required: different-model-family`（如 skeptic）或 `role-separation`（如 method-reviewer）。
+
+## 7. 如何新增一个检索通道
+
+1. 在 `retrieval/` 下实现 provider（stdlib-only、超时、定型错误，不抛异常到管道）。
+2. 零配置通道进 `zero_config_academic` / `zero_config_web`；需 key 的学术通道进 `academic_key_providers`，并实现 `is_available()`。
+3. 命中结果统一为 `SearchHit`；沿用 `doc_id` / `chunk_id` / `offset` 表达定位（如适用）。
+4. 在 `docs/` 记录端点契约，在 `references/retrieval-compliance.md` 补齐配额与限制，在 `tests/` 用 mock HTTP 覆盖成功与各类失败。
+
+## 8. 证据纪律与文档
+
+- 示例与演示必须如实标注 `data_origin`（manual_curated / synthetic / hybrid）；不得把手工整理文献说成模型运行结果。
+- 数字口径以 `docs/metrics.json` 为准，文档中不硬编码会漂移的计数。
+- 内部文档用中文，`SKILL.md` 保持英文；协议语义（九步、四态、Projection 边界）不因文档改写而改变。
+
+## 9. PR 检查表
+
+- [ ] 五个门本地全绿（版本 / 指标 / skill_lint / 协议对齐 / 测试）。
+- [ ] 新增或改动的契约在五方（协议 / 能力 / 角色 / 简报 / 子技能）一致。
+- [ ] 未引入硬编码的模型名、CLI 名或密钥。
+- [ ] 科学不变量未被弱化；如有例外，在 PR 说明中显式论证。
+- [ ] 文档、CHANGELOG、`docs/plans/STATUS.md` 同步更新。
+- [ ] 未提交本地运行状态、私有数据或凭据。
+
+## 10. 行为准则
+
+讨论以证据为准：提出结论时给出可核验来源；被反驳时更新结论而不是更新措辞。对他人贡献的评审聚焦"证据是否支撑结论"，不针对作者。
+

package/README.md

@@ -8,15 +8,28 @@
 
 ## EduEvidence Research Engine — Evidence Research & Decision Skill
 
-> **From Research Questions to Evidence-Based Decisions.**
+> **From Research Questions to Evidence-Based Decisions.** · Current release **6.2.0**
+
+> **▶ Live demo:** [Landing](https://37chengshan.github.io/eduevidence/) · [Research Studio](https://37chengshan.github.io/eduevidence/studio/) · [Deep Research comparison](https://37chengshan.github.io/eduevidence/comparison.html)
 
 EduEvidence is delivered as an **AI Agent Skill**; inside the Skill operates
 the **EduEvidence Research Engine** — a persistent, auditable engine that
-turns research questions into evidence-grounded decisions across education and organizational policy.
+turns a decision question into an evidence-grounded answer. It is **multi-domain**:
+the domain registry (`domains/manifest.json`) ships **education** and **policy**
+today, each declaring its own frame schema, outcome taxonomy and methodology
+checklist, so one nine-stage protocol serves education and applied social science
+work without forking the engine.
 
 - **Three public workflows** — **Evidence Review**, **Decision & Pilot**, and
   **Evaluate & Update**. A full research cycle connects existing evidence,
   grounded knowledge gaps, a study design, new data and a revised decision.
+- **Multi-domain by contract** — `education` and `policy` are registered domains;
+  a run validates against its own domain's frame schema and outcome taxonomy
+  (`engine/taxonomy.py` is the single authority; unknown tokens fail closed).
+- **Retrieval that stays traceable** — zero-config channels (OpenAlex / Semantic
+  Scholar / CrossRef / AIHot / AgentSearch / DuckDuckGo) plus key-based channels:
+  **Sciverse** (citation-grade academic retrieval with full-text locators),
+  Tavily and Brave. A lookup snippet is a locator, never evidence.
 - **Project Workspace + Evidence Graph** — long-lived Projects with versioned,
   immutable graph revisions; `result.json`/HTML/Markdown are projections, not
   fact stores.
@@ -32,13 +45,31 @@ turns research questions into evidence-grounded decisions across education and o
   server/app; Native Core runs on Python stdlib only and never requires
   Agent MCP or a daemon.
 
-![Actual Research Studio overview: workplace AI evidence](assets/readme/studio-overview.png)
+![Research Studio walkthrough: overview, report library, and the five report identities](assets/readme/studio-tour.gif)
+
+*Recorded from the actual local Studio — no mockups: overview → report library → five report identities. Below, the introduction page walkthrough:*
 
-*Actual local Studio screenshot. This case is manually curated literature, with no attached research execution history.*
+![Introduction page walkthrough: hero, nine-step protocol, five report systems](assets/readme/landing-tour.gif)
 
 ---
 
-## Quick Install
+## Quick Start
+
+**Fastest path — read a finished report (no install):**
+
+```bash
+open examples/ai-coding-assistant-evidence/EduEvidence_Report.html
+open examples/spaced-retrieval-practice/EduEvidence_Report.html   # real Sciverse run
+```
+
+**Look at the console (Python 3.10+, Node not required):**
+
+```bash
+python3 scripts/dashboard_server.py --host 127.0.0.1 --port 8765
+# browser: http://127.0.0.1:8765/studio/   (read-only research console)
+```
+
+**Install it:**
 
 **npm (recommended for Skill install)**
 
@@ -135,7 +166,7 @@ runnable + sample report renderable).
 
 ## What Problem We Solve
 
-A typical AI answers an education question like this:
+A typical AI answers a decision question like this:
 
 ```text
 Question → Search a few sources → Summarize opinions → Give advice
@@ -144,15 +175,15 @@ Question → Search a few sources → Summarize opinions → Give advice
 EduEvidence does this instead:
 
 ```text
-Education question
-  → Education Research Framing (learner / intervention / comparison / outcomes / context)
+Decision question (education or applied social science)
+  → Domain Research Framing (learner or decision object / intervention / comparison / outcomes / context)
   → Literature & evidence retrieval (supporting evidence + independent counter-evidence)
   → Claim-Level Evidence Extraction
   → Skeptic challenge protocol + Method Reviewer audit
   → Evidence Tribunal
   → Applicability Analysis
   → Decision: ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE
-  → Teaching Intervention (minimum viable pilot)
+  → Intervention (minimum viable pilot)
   → Evaluation Plan
 ```
 
@@ -161,43 +192,44 @@ It answers six questions:
 1. What does the current evidence actually support?
 2. What can the current evidence not support?
 3. Why do different studies reach different results?
-4. Which students, which courses, under which conditions does it apply to?
-5. If an institution adopts it, how to roll it out with low risk?
+4. Which population, in which setting, under which conditions does it apply to?
+5. If an institution adopts it, how should it be rolled out with low risk?
 6. How to verify whether it actually works after implementation?
 
-## 30-second Demo
+## 30-second tour
 
-> Main demo: **Should first-year C programming students be allowed to use generative AI coding assistants?**
+> Flagship question: **Should first-year C programming students be allowed to use generative AI coding assistants?**
 
 | Time | Stage |
 |---|---|
-| 0–20s | Ask the education question |
-| 20–45s | Education Research Frame |
+| 0–20s | Ask the decision question |
+| 20–45s | Research Frame (domain-specific schema) |
 | 45–75s | Evidence Retrieval |
 | 75–110s | Evidence Matrix |
 | 110–135s | Methodology + Skeptic |
 | 135–155s | Evidence Tribunal |
-| 155–170s | Teaching Intervention + Evaluation |
+| 155–170s | Intervention + Evaluation |
 | 170–180s | Benchmark |
 
 Full example pack: [`examples/ai-coding-assistant-evidence/`](examples/ai-coding-assistant-evidence/).
 
-## Why Education Evidence Is Hard
+## Why Evidence Decisions Are Hard
 
-Education evidence has natural pitfalls. EduEvidence's core contribution is standardizing the countermeasures:
+Evidence across education and applied social science shares the same natural pitfalls. EduEvidence's core contribution is standardizing the countermeasures:
 
 - **Outcome Separation**: `faster task completion ≠ actually learning to program`; `short-term score gains ≠ long-term retention`; `completing tasks with AI ≠ transferring skills without AI`.
 - **Counter-Evidence Search**: it does not just verify the user's initial assumption — it independently searches for null / negative / contradictory evidence, AI dependency, novelty effects, self-selection bias, and more.
 - **Evidence Tribunal**: instead of listing pros and cons, it judges which studies are more credible, whether conflicts come from samples / measurement / course / tool / design, and what can be concluded so far.
-- **Evidence-to-Action Bridge**: it does not stop at "research shows…" — it connects to applicability, the teaching decision, pilot intervention, and evaluation design.
+- **Evidence-to-Action Bridge**: it does not stop at "research shows…" — it connects to applicability, the decision, pilot intervention, and evaluation design.
 
 ## How EduEvidence Works
 
 ```text
 ┌─────────────────────────────────────┐
 │            EduEvidence              │
-│  education knowledge + decision +   │
-│  intervention + evaluation          │
+│  domain contracts (education /       │
+│  policy) + decision + intervention   │
+│  + evaluation                        │
 └────────────────┬────────────────────┘
                  │
 ┌────────────────▼────────────────────┐
@@ -215,22 +247,24 @@ Education evidence has natural pitfalls. EduEvidence's core contribution is stan
 The 9-step workflow:
 
 ```text
-1. Frame          Build the EducationResearchFrame
+1. Frame          Build the domain frame (education frame / policy frame)
 2. Retrieve       Retrieve literature & evidence (support + independent counter-evidence)
 3. Extract        Extract claim-level evidence (bound to outcomes)
 4. Challenge      Skeptic protocol (fixed 9 checks)
 5. Audit          Method Reviewer audit (15-item checklist)
 6. Adjudicate     Evidence Tribunal (Evidence Matrix + Verdict)
 7. Applicability  Applicability analysis
-8. Intervene      Teaching Intervention design (minimum viable pilot)
+8. Intervene      Intervention design (minimum viable pilot)
 9. Evaluate       Evaluation Plan design
 ```
 
-Every step is validated against JSON Schemas (`schemas/`), deterministic logic lives in `scripts/`, and the education methodology is documented independently in `references/`.
+Every step is validated against JSON Schemas (`schemas/`), deterministic logic lives in `scripts/`, and the methodology is documented independently in `references/` (21 documents: evidence quality, skeptic protocol, tribunal policy, WWC/GRADE standards, social-science pitfalls, retrieval protocol, report copy style …; counts in `docs/metrics.json`).
 
 ## Outcome Separation
 
-EduEvidence enforces 20 outcome types (`references/outcome-taxonomy.md`):
+Outcome tokens are domain-owned. The education taxonomy declares **20 tokens** in four categories (`domains/education/outcome_taxonomy.json`); the policy domain declares its own categories and tokens (`domains/policy/outcome_taxonomy.json`). `engine/taxonomy.py` is the only reader: an unknown token or unregistered domain **fails closed** instead of being silently classified as a learning outcome.
+
+The education set (`references/outcome-taxonomy.md`):
 
 ```text
 Learning:    Knowledge Gain / Concept Understanding / Retention / Transfer / Independent Problem Solving
@@ -239,11 +273,11 @@ Process:     Engagement / Motivation / Cognitive Load / Help-Seeking / Metacogni
 Risk:        AI Dependency / Over-reliance / Reduced Effort / Reduced Transfer / Academic Integrity Risk / False Confidence
 ```
 
-The demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant raised task completion by 1.15× and correctness by 1.8×, but the one-week retention test showed no significant difference — **task performance ≠ learning**.
+The flagship demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant raised task completion by 1.15× and correctness by 1.8×, but the one-week retention test showed no significant difference — **task performance ≠ learning**.
 
 ## Evidence Tribunal
 
-`references/tribunal-policy.md` defines the adjudication rules: input = Frame + Evidence Matrix + Skeptic Findings + Method Reviews; output = EducationVerdict (`schemas/verdict.schema.json`), including:
+`references/tribunal-policy.md` defines the adjudication rules: input = Frame + Evidence Matrix + Skeptic Findings + Method Reviews; output = the domain Verdict (`schemas/verdict.schema.json`), including:
 
 - supported / uncertain / contradicted claims
 - conflict-source analysis (sample / measurement / course / tool / design)
@@ -254,10 +288,10 @@ The demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant r
 
 ## From Evidence to Action
 
-Evidence must connect to the real classroom (`references/applicability-policy.md`, `intervention-design.md`, `evaluation-design.md`):
+Evidence must connect to the real setting — a classroom, a support team, a policy roll-out (`references/applicability-policy.md`, `intervention-design.md`, `evaluation-design.md`):
 
-- **Applicability**: For whom? For which course? For which outcome? Under what conditions? With what AI usage policy?
-- **Intervention**: always a "minimum viable pilot", never direct full deployment; includes AI usage rules, teacher/student roles, reflection requirements, and stop conditions.
+- **Applicability**: For whom? In which setting? For which outcome? Under what conditions? With what AI usage policy?
+- **Intervention**: always a "minimum viable pilot", never direct full deployment; includes AI usage rules, staff/user roles, reflection requirements, and stop conditions.
 - **Evaluation**: every PILOT/ADOPT recommendation must come with an evaluation plan; distinguishes baseline / post-test / retention / transfer, and task-performance vs learning metrics.
 
 ## Benchmark
@@ -291,14 +325,16 @@ Key metrics: Citation Support Precision / Unsupported Claim Rate / Contradiction
 
 A second public example, `examples/workplace-ai-assistant/`, evaluates AI assistance in enterprise customer support using the policy domain: 4 findings from 3 studies, with direct and indirect evidence distinguished. Its proposed supervised pilot has not been executed.
 
-Both public examples are **manually curated literature demonstrations** (`manual_curated`). A generated report does not establish that an agent completed the nine-stage research workflow. The coding case contains 12 findings from 8 sources; the workplace case contains 4 findings from 3 sources. See [the workplace evidence notes](docs/demo-workplace-ai.md) for source versions and limitations.
+The third public example, `examples/spaced-retrieval-practice/`, asks whether spaced repetition and retrieval practice should replace massed review in an introductory programming course. It is the first pack whose sources were located through the **Sciverse** channel (`discovery_provider=sciverse`, `fetch_provider=sciverse_content`) and whose `meta.data_origin` is `real_run_sciverse`: 6 findings from 7 tier-1 DOI sources, decision **ADOPT** (High confidence). It is the worked example that the ADOPT path is reachable: retention and transfer - the two primary outcomes - carry direct, consistent evidence at directness 2, while the coding and workplace cases stay bounded at PILOT because their primary learning evidence is missing.
+
+Each pack ships `result.json` + `result.zh.json` (bilingual parallel data), a packaged-`EduEvidence_Report.html` root report, and `reports-5themes/` with the five standalone theme HTML files.
 
-Four older teaching demos have moved to `tests/fixtures/legacy-examples/` for compatibility tests. They are excluded from public catalogs and distribution; their unverified or synthetic findings must not be cited as research evidence. The old `ai-coding-assistant` path remains a compatibility alias.
+All three public examples are literature demonstrations, and their `data_origin` says exactly what produced them. The coding and workplace cases are **manually curated** (`manual_curated`); the spaced-retrieval case is a recorded **Sciverse-backed run** (`real_run_sciverse`). A rendered report never establishes that an agent completed the whole nine-stage research workflow. See [the workplace evidence notes](docs/demo-workplace-ai.md) for source versions and limitations, and [`docs/reproducibility.md`](docs/reproducibility.md) for how `data_origin` is declared.
 
 ### Start your own research in ~30 minutes
 
 ```bash
-python3 scripts/quickstart.py "你的教育研究问题"          # creates runs/<id> + NEXT_STEPS.md
+python3 scripts/quickstart.py "你的研究问题"             # creates runs/<id> + NEXT_STEPS.md
 # hand the LLM stages to your AI agent per NEXT_STEPS.md, then finish with:
 python3 scripts/orchestrator.py adjudicate --project runs/<id>
 bash scripts/bake_pack.sh <pack_dir>                     # 5-theme bilingual report
@@ -321,10 +357,10 @@ After research completes, `result.json` is rendered into three visualization out
 
 ```text
 result.json + result.zh.json (Chinese parallel data)
-  ├─ build_charts.py        → chart_specs.json (ECharts option data; no ECharts runtime bundled)
-  ├─ build_infographics.py  → infographics.json (hand-authored SVGs)
-  ├─ build_figures.py       → figures/ (publication figures: figure_data.json + SVG/PNG/PDF)
-  └─ build_report.py        → EduEvidence_Report.html (single-file bilingual report + report_spec.json)
+  ├─ visualization/eduevidence-report/scripts/build_charts.py        → chart_specs.json (ECharts option data; no ECharts runtime bundled)
+  ├─ visualization/eduevidence-report/scripts/build_infographics.py  → infographics.json (hand-authored SVGs)
+  ├─ visualization/eduevidence-report/scripts/build_figures.py       → figures/ (publication figures: figure_data.json + SVG/PNG/PDF)
+  └─ visualization/eduevidence-report/scripts/build_report.py        → EduEvidence_Report.html (single-file bilingual report + report_spec.json)
 ```
 
 **EduEvidence_Report.html (main deliverable)**:
@@ -344,10 +380,25 @@ See [Research Studio workflow and delivery guide](docs/research-studio-guide.zh-
 
 > Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
 
+
+### Optional key-based retrieval channels
+
+Zero-config retrieval (OpenAlex / Semantic Scholar / CrossRef / AIHot / AgentSearch) works out of the box. These channels activate once a key is present and stay silently inactive otherwise — the scientific gates never depend on them:
+
+```bash
+export SCIVERSE_API_TOKEN=sv-...   # citation-grade academic retrieval + full-text location
+export TAVILY_API_KEY=...          # general web search
+export BRAVE_API_KEY=...           # general web search
+```
+
+The Sciverse channel treats an `/agentic-search` chunk as a **locator**: it must be expanded through `/content` and pass the validation gate before it may enter evidence extraction (RULE 2, machine-enforced). Contract: `docs/sciverse-api.md`; compliance: `references/retrieval-compliance.md`.
+
 ## Architecture
 
 The repository is a complete **Skill package**: `SKILL.md` is the entry point; everything else is layered as *skill core → quality assurance → demos*. See [`docs/architecture.md`](docs/architecture.md):
 
+Read the illustrated single-file walkthrough of the same architecture (nine-step protocol, roles and independence, artifact/state map, execution and approval loop) at [`web/architecture.html`](web/architecture.html).
+
 ```text
 EduEvidence/  (= one Skill package)
 │
@@ -448,7 +499,9 @@ python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence
 python3 scripts/evidence_matrix.py examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 4. Run the Citation Audit (claim-evidence traceability)
-python3 scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
+python3 scripts/claim_audit.py \
+  --claims examples/ai-coding-assistant-evidence/claims.jsonl \
+  --evidence examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 5. Render the Research & Decision Pack (Markdown)
 python3 scripts/render_report.py \
@@ -466,6 +519,8 @@ python3 visualization/eduevidence-report/scripts/build_report.py \
     --out examples/ai-coding-assistant-evidence/EduEvidence_Report.html
 
 # 7. Validate the benchmark question set
+# Source checkout only: benchmarks/questions.jsonl is not part of the
+# shipped Skill package (see packaging/upload-layout.md).
 python3 scripts/benchmark.py --questions benchmarks/questions.jsonl
 
 # 8. Run the tests

package/README.zh-CN.md

@@ -11,6 +11,8 @@
 > **From Research Questions to Evidence-Based Decisions.**
 > **从研究问题，到有证据支撑的决策。**
 
+> **▶ 在线演示：** [介绍页](https://37chengshan.github.io/eduevidence/) · [Research Studio](https://37chengshan.github.io/eduevidence/studio/) · [深度调研对比页](https://37chengshan.github.io/eduevidence/comparison.html)
+
 EduEvidence 面向研究者与实践决策者，将教育、组织政策和 AI 工具采用等问题转化为**可追溯、可质疑、可验证的证据决策流程**。当前公开案例涵盖编程学习和企业客服，分别使用教育与组织政策领域契约。
 
 - **三条公开工作流**：Evidence Review（证据综述）、Decision & Pilot（决策与试点）、Evaluate & Update（评估与更新）。完整研究周期将文献证据、有依据的知识缺口、研究设计、新数据和决策修订连接起来。
@@ -18,9 +20,11 @@ EduEvidence 面向研究者与实践决策者，将教育、组织政策和 AI
 - 🧪 基于真实研究（示例包含 CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 的实证证据），不做无来源断言。
 - 🚦 最终输出不是"允许/禁止"的二元结论，而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的干预与评价方案。
 
-![实际研究概览：企业客服 AI 证据案例](assets/readme/studio-overview.png)
+![Research Studio 操作实录：总览 → 报告阅读室 → 五种报告形态](assets/readme/studio-tour.gif)
+
+*本地 Studio 真实录屏（非示意）：总览 → 报告阅读室 → 五种报告形态。下方为介绍页滚动实录：*
 
-*本地 Studio 实际截图。案例为人工整理文献，未附研究执行历史。*
+![介绍页实录：首屏 → 九步协议 → 五套报告体系](assets/readme/landing-tour.gif)
 
 ---
 
@@ -284,9 +288,11 @@ B4 EduEvidence + Agent MCP      ← 证明多 Agent 增强价值（B3 vs B4）
 - **干预**：4 阶段试点（Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check）。
 - **评价**：无 AI 基线/后测/期末考试保持/无 AI 迁移任务 + AI 依赖风险指标。
 
-另一公开案例 `examples/workplace-ai-assistant/` 使用组织政策领域，讨论企业客服是否引入 AI 助手：3 项研究、4 条发现，区分直接客服证据与间接写作/咨询证据，建议有监督试点。详见 [来源核验与边界](docs/demo-workplace-ai.md)。
+另一公开案例 `examples/workplace-ai-assistant/` 使用组织政策领域，讨论企业客服是否引入 AI 助手：3 项研究、4 条发现，区分直接客服证据与间接写作/咨询证据，判定 **PILOT**（Moderate）。详见 [来源核验与边界](docs/demo-workplace-ai.md)。
+
+第三个公开案例 `examples/spaced-retrieval-practice/`（来源经 Sciverse 通道逐条读回原文）讨论间隔重复与检索练习能否替代集中式复习：6 条证据、7 篇 tier-1 DOI 来源，判定 **ADOPT**（High，引擎复算 0.893）。它是“ADOPT 出口真实可达”的实证：延迟保持与迁移两个主要结果上都有 directness=2 的直接且一致证据；另两例因为主要学习结果上缺直接证据而停在 PILOT。
 
-两个公开案例均为人工整理文献（`manual_curated`），报告生成不等于九阶段模型研究已运行，也不代表试点已经执行。四个旧教学示例迁入 `tests/fixtures/legacy-examples/`，仅供软件兼容测试，排除于公共目录和分发包；未核验或合成数据不能引用为研究证据。旧 `ai-coding-assistant` 路径保留兼容别名。
+三个公开案例的数据来源各自如实标注：编程与企业客服两例为人工整理文献（`manual_curated`），间隔重复一例为真实 Sciverse 检索运行记录（`real_run_sciverse`），报告生成不等于九阶段模型研究已运行，也不代表试点已经执行。四个旧教学示例迁入 `tests/fixtures/legacy-examples/`，仅供软件兼容测试，排除于公共目录和分发包；未核验或合成数据不能引用为研究证据。旧 `ai-coding-assistant` 路径保留兼容别名。
 
 ## Studio 实际界面
 
@@ -327,10 +333,24 @@ result.json + result.zh.json
 
 > Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
 
+### 可选检索通道（key-based）
+
+零配置检索（OpenAlex / Semantic Scholar / CrossRef / AIHot / AgentSearch）开箱可用。配置以下 key 后通道自动启用，未配置时静默失活、不影响科学门：
+
+```bash
+export SCIVERSE_API_TOKEN=sv-...   # 引用级学术检索 + 全文定位（meta-search / agentic-search / content / paper-relations）
+export TAVILY_API_KEY=...          # 通用网页检索
+export BRAVE_API_KEY=...           # 通用网页检索
+```
+
+Sciverse 通道把 `/agentic-search` 的 chunk 当作**定位子**：必须经 `/content` 读原文并通过校验门后，才允许进入证据抽取（RULE 2 的机器化执行）。契约见 `docs/sciverse-api.md`，合规见 `references/retrieval-compliance.md`。
+
 ## Architecture
 
 仓库是一个完整的 **Skill 包**：`SKILL.md` 是入口，其余目录按"Skill 运行必需 → 质量保障 → 演示"分层。详见 [`docs/architecture.md`](docs/architecture.md)：
 
+同一套架构的图解单页（九步协议 / 角色与独立性 / 产物状态地图 / 执行与审批闭环）见 [`web/architecture.html`](web/architecture.html)。
+
 ```text
 EduEvidence/  （= 一个 Skill 包）
 │
@@ -339,7 +359,7 @@ EduEvidence/  （= 一个 Skill 包）
 ├─ Skill 本体（运行必需）
 │  ├─ skill/agents/          8 个角色协议（Planner / Retriever / Analyst / Skeptic /
 │  │                         Method Reviewer / Judge / Intervention Designer / Evaluation Designer）
-│  ├─ references/            11 个教育方法论文档（证据质量 / 反证协议 / 裁决规则 / 干预设计…）
+│  ├─ references/            方法论文档（证据质量 / 反证协议 / 裁决规则 / 干预设计 / 检索合规 / 文案规范…；数量见 docs/metrics.json）
 │  ├─ schemas/               33 个 JSON Schema 数据契约（13 顶层 + 17 v2 + 3 v3，每步输出的校验门）
 │  ├─ scripts/               17 个确定性逻辑脚本（评分 / 矩阵 / 审计 / 置信度 / Orchestrator / 启动探测）
 │  ├─ retrieval/             检索与抓取层（fetch / validate / dedupe / failures）
@@ -347,7 +367,7 @@ EduEvidence/  （= 一个 Skill 包）
 │  └─ visualization/         结果呈现层（ECharts / 信息图 / 学术图 / 双语 HTML Composer）
 │
 ├─ 质量保障
-│  ├─ tests/                 pytest 测试矩阵（752 个测试函数，73 个文件，见 docs/metrics.json）
+│  ├─ tests/                 pytest 测试矩阵（测试函数与文件数见源码仓库的 docs/metrics.json）
 │  └─ benchmarks/            30 题 + 30 份金标注 + B0–B4 评测框架
 │
 └─ 演示与分发

package/SKILL.md

@@ -2,7 +2,7 @@
 name: eduevidence
 description: "Decision-grade evidence synthesis for education and applied social science intervention decisions. Use when a user needs to determine whether, when, for whom, or how to adopt, pilot, evaluate, or revise a teaching method, curriculum change, AI tool, program, or policy intervention. Run an auditable evidence-to-decision workflow spanning systematic retrieval, counter-evidence challenge, methodological quality and evidence-certainty appraisal, provenance-traceable evidence graphs, applicability boundaries, evidence-grounded gap detection, preregistration-ready study or pilot design, empirical evidence re-injection, and decision revision."
 ---
-# EduEvidence 6.0 — Decision-Grade Evidence Engine
+# EduEvidence 6.2 — Decision-Grade Evidence Engine
 > **AI4SS Track | Art–Science Integration · General Intelligence**  
 > **From empirical questions to decision-grade evidence and evidence-to-action loops.**
 
@@ -303,6 +303,14 @@ The example demonstrates:
 - Empirical evidence re-injection followed by decision revision.
 Do not generalize the flagship verdict to unrelated populations, courses, tools, or policy contexts.
 
+The four-state output is reachable on both ends, and each public case records which end it reached:
+
+- `examples/ai-coding-assistant-evidence/` - `PILOT` / Moderate / 0.586. Primary evidence stops at task performance, so the decision is bounded.
+- `examples/spaced-retrieval-practice/` - `ADOPT` / High / 0.893. Retention and transfer, the primary outcomes, carry direct evidence at directness 2.
+- `examples/workplace-ai-assistant/` - `PILOT` / Moderate / 0.578, using the policy domain contract.
+
+A verdict never awards itself an action: the Pre-Verdict Gate re-derives primary-outcome directness from the evidence corpus and caps an unsupported `ADOPT` to `PILOT`. Never present a case as ADOPT without that derivation passing.
+
 ---
 
 ## 16. Keep Presentation as a Projection Layer
@@ -391,7 +399,8 @@ python3 scripts/dashboard_server.py --port 8765
 # Search academic and current evidence
 python3 -m retrieval.search "AI coding assistants learning transfer"
 # Run the DID fixture / empirical analysis path
-python3 scripts/did_regression.py examples/full-research-cycle-fixture/data.csv
+python3 scripts/did_regression.py <your.csv>   # needs treat / post / outcome columns
+# column names are matched case-insensitively; see scripts/did_regression.py
 # Compute an effect size
 python3 scripts/effect_calculator.py \
   --mean1 78.5 --sd1 10.2 --n1 90 \

package/bin/eduevidence.js

@@ -17,7 +17,8 @@ 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
+  console.log(`eduevidence ${readPkgVersion()} — Evidence-Based Decision Skill
+   for education and organizational policy (multi-domain by contract)
 
 Install (Python runtime + self-check):
   eduevidence install [--dev] [--dry-run]