eduevidence 5.2.0 → 6.2.0

package/README.zh-CN.md

@@ -1,19 +1,30 @@
+<p align="center">
+  <img src="assets/readme/logo.png" width="88" height="88" alt="EduEvidence logo" />
+</p>
+
 # EduEvidence
 
 > **🌐 [English](README.md) | 中文**
 
-## EduEvidence Research Engine — Evidence-Based Education Decision Skill
+## EduEvidence Research Engine — Evidence Research & Decision Skill
+
+> **From Research Questions to Evidence-Based Decisions.**
+> **从研究问题，到有证据支撑的决策。**
 
-> **From Education 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 教学工具"从经验判断转化为**可追溯、可质疑、可验证的证据决策流程**——教学法、课程、评估、学习干预与 AI 工具均是应用域，引擎方法学教育通用。
+EduEvidence 面向研究者与实践决策者，将教育、组织政策和 AI 工具采用等问题转化为**可追溯、可质疑、可验证的证据决策流程**。当前公开案例涵盖编程学习和企业客服，分别使用教育与组织政策领域契约。
 
-- ⚖️ 不是替教师生成答案，而是帮助教师知道：证据支持什么、不能支持什么、适用于谁、应该怎样试点并验证。
+- **三条公开工作流**：Evidence Review（证据综述）、Decision & Pilot（决策与试点）、Evaluate & Update（评估与更新）。完整研究周期将文献证据、有依据的知识缺口、研究设计、新数据和决策修订连接起来。
+- ⚖️ 帮助研究者与实践决策者判断：证据支持什么、不能支持什么、适用于谁、应该怎样试点并验证。
 - 🧪 基于真实研究（示例包含 CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 的实证证据），不做无来源断言。
-- 🚦 最终输出不是"允许/禁止"的二元结论，而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的教学干预与评价方案。
+- 🚦 最终输出不是"允许/禁止"的二元结论，而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的干预与评价方案。
+
+![Research Studio 操作实录：总览 → 报告阅读室 → 五种报告形态](assets/readme/studio-tour.gif)
 
-![EduEvidence 顶层宣传图](assets/top-banner.jpg)
+*本地 Studio 真实录屏（非示意）：总览 → 报告阅读室 → 五种报告形态。下方为介绍页滚动实录：*
+
+![介绍页实录：首屏 → 九步协议 → 五套报告体系](assets/readme/landing-tour.gif)
 
 ---
 
@@ -52,7 +63,7 @@ bash install.sh              # 一键：venv + 依赖 + 自检 + 测试
 安装后直接打开示例报告：
 
 ```bash
-open examples/ai-coding-assistant/EduEvidence_Report.html
+open examples/ai-coding-assistant-evidence/EduEvidence_Report.html
 ```
 
 > 需要 Python 3.10+；核心零第三方依赖。学术图 PNG/PDF 导出可选装 matplotlib。
@@ -169,7 +180,7 @@ EduEvidence 执行：
 | 155–170s | Teaching Intervention + Evaluation |
 | 170–180s | Benchmark |
 
-完整示例包见 [`examples/ai-coding-assistant/`](examples/ai-coding-assistant/)。
+完整示例包见 [`examples/ai-coding-assistant-evidence/`](examples/ai-coding-assistant-evidence/)。
 
 ## Why Education Evidence Is Hard
 
@@ -238,7 +249,7 @@ EduEvidence 强制区分 20 类 Outcome（`references/outcome-taxonomy.md`）：
 - Can Claim / Cannot Claim 边界
 - 四态决策 + Confidence（规则化计算，不由模型自由生成）
 
-![Evidence Tribunal Workflow](assets/tribunal-workflow.jpg)
+![Evidence Tribunal Workflow](assets/readme/research-workflow.svg)
 
 ## From Evidence to Action
 
@@ -270,18 +281,32 @@ B4 EduEvidence + Agent MCP      ← 证明多 Agent 增强价值（B3 vs B4）
 
 > **大学一年级 C 语言课程是否应该允许学生使用生成式 AI 编程助手？**
 
-`examples/ai-coding-assistant/` 完整展示了从问题到决策的全过程：
+`examples/ai-coding-assistant-evidence/` 完整展示了从问题到决策的全过程：
 
-- **证据**（7 条，均绑定真实来源）：任务表现提升（Kazemitabaar 2023）、无护栏访问损害独立考试表现 -17%（Bastani 2025, PNAS）、护栏设计消除负效应（Bastani 2025）、形成性反馈写作证据（Marzuki 2024）。
+- **证据**（12 条发现、8 个来源）：任务表现提升（Kazemitabaar 2023）、无护栏访问损害独立考试表现 -17%（Bastani 2025, PNAS）、护栏设计消除负效应（Bastani 2025）、形成性反馈写作证据（Marzuki 2024）。
 - **决策**：**PILOT** —— 任务表现证据强，但大学编程课程的直接学习效应证据缺失，无护栏风险已被证实。
 - **干预**：4 阶段试点（Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check）。
 - **评价**：无 AI 基线/后测/期末考试保持/无 AI 迁移任务 + AI 依赖风险指标。
 
-另外两个示例：AI 写作助手（`examples/ai-writing-assistant/`）、高数 AI Tutor（`examples/ai-tutor/`）——证明 Skill 不是为一个问题写死。
+另一公开案例 `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`），间隔重复一例为真实 Sciverse 检索运行记录（`real_run_sciverse`），报告生成不等于九阶段模型研究已运行，也不代表试点已经执行。四个旧教学示例迁入 `tests/fixtures/legacy-examples/`，仅供软件兼容测试，排除于公共目录和分发包；未核验或合成数据不能引用为研究证据。旧 `ai-coding-assistant` 路径保留兼容别名。
+
+## Studio 实际界面
+
+点击图谱节点可以追溯“来源 → 发现 → 主张”。连线流动用于辅助阅读，不表示后台研究正在执行。
+
+![实际溯源图谱](assets/readme/studio-graph.png)
+
+同一份证据可以用五个独立主题阅读，支持中英文及简报/全文切换。
+
+![实际报告阅读室](assets/readme/studio-reports.png)
 
 ## Visualization: Bilingual HTML Report + Infographics + Academic Figures
 
-After research completes, `result.json` is rendered by three deterministic Python adapters. The adapters use the standard library; the optional Web Studio chart enhancement has a separate browser dependency.
+After research completes, `result.json` is rendered by three deterministic Python adapters. The adapters use the standard library; legacy ECharts enhancement is optional and is not required by the new Research Studio.
 
 ```text
 result.json + result.zh.json
@@ -300,14 +325,32 @@ result.json + result.zh.json
 - **Static-first**: decision, matrix, tribunal, intervention and sources remain readable without JavaScript; ECharts is an optional enhancement.
 - **Integrity gate**: chart numbers are checked against result.json item by item; publishing is blocked with `REPORT_INVALID` on mismatch.
 
-**Local Web Studio** (`python3 scripts/dashboard_server.py --port 8765`) has exactly three read-only views: Dashboard, Report Browser and Data Visualization. It loads ECharts 5.4.3 from jsDelivr for interactive charts; the submission package does not bundle that runtime, so Web interactivity requires network access. The baked report's static HTML/SVG remains the offline artifact.
+**Research Studio 研究观察台**保持只读。运行 `python3 scripts/dashboard_server.py --port 8765`，打开 `/studio/`，即可查看研究项目、证据与来源、实际运行记录、已提交版本及五种风格报告。Skill 自进化实验单独展示；控制台不会启动研究、修改证据或派发代理。
+
+控制台采用 React + TypeScript，分发包已包含静态资源，使用者无需安装 Node。新图表不依赖远程 ECharts CDN，也不在浏览器中计算合并效应量。本地研究不会进入 GitHub Pages 公共导出。五主题从完整双语输入生成，缺失内容明确标记，不补造结论。
+
+详见[研究观察台流程与交付指南](docs/research-studio-guide.zh-CN.md)。
+
+> Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
+
+### 可选检索通道（key-based）
 
-> Open the example directly: `examples/ai-coding-assistant/EduEvidence_Report.html`
+零配置检索（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 包）
 │
@@ -316,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）
@@ -324,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 评测框架
 │
 └─ 演示与分发
@@ -359,38 +402,38 @@ Agent MCP 是**性能与可靠性增强层，不是 EduEvidence 成立的前提*
 
 > 🔒 Agent MCP 原则：**Scan first. Recommend second. Ask the user. Execute only after explicit confirmation.** 未经用户确认不得 spawn；用户拒绝则回退 Native。
 
-![Controlled Multi-Agent Research](assets/multi-agent-research.jpg)
+![Controlled Multi-Agent Research](assets/readme/controlled-execution.svg)
 
 ## Usage
 
 ```bash
 # 1. 验证数据符合 Schema 契约
 python3 scripts/validate_schema.py --schema schemas/evidence.schema.json \
-    --data examples/ai-coding-assistant/evidence.jsonl
+    --data examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 2. 计算证据质量分与 Confidence
-python3 scripts/evidence_score.py examples/ai-coding-assistant/evidence.jsonl
+python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 3. 生成 Evidence Matrix（主产品界面之一）
-python3 scripts/evidence_matrix.py examples/ai-coding-assistant/evidence.jsonl
+python3 scripts/evidence_matrix.py examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 4. 运行 Citation Audit（Claim-证据追溯）
 python3 scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
 
 # 5. 渲染 Research & Decision Pack（Markdown）
 python3 scripts/render_report.py \
-    --frame examples/ai-coding-assistant/frame.json \
-    --evidence examples/ai-coding-assistant/evidence.jsonl \
-    --methodology examples/ai-coding-assistant/methodology.json \
-    --verdict examples/ai-coding-assistant/verdict.json \
-    --intervention examples/ai-coding-assistant/intervention.json \
-    --evaluation examples/ai-coding-assistant/evaluation.json \
+    --frame examples/ai-coding-assistant-evidence/frame.json \
+    --evidence examples/ai-coding-assistant-evidence/evidence.jsonl \
+    --methodology examples/ai-coding-assistant-evidence/methodology.json \
+    --verdict examples/ai-coding-assistant-evidence/verdict.json \
+    --intervention examples/ai-coding-assistant-evidence/intervention.json \
+    --evaluation examples/ai-coding-assistant-evidence/evaluation.json \
     --out REPORT.md
 
 # 6. 渲染单文件双语 HTML 报告（主产物）
 python3 visualization/eduevidence-report/scripts/build_report.py \
-    --result examples/ai-coding-assistant/result.json \
-    --out examples/ai-coding-assistant/EduEvidence_Report.html
+    --result examples/ai-coding-assistant-evidence/result.json \
+    --out examples/ai-coding-assistant-evidence/EduEvidence_Report.html
 
 # 7. 校验 Benchmark 题目集
 python3 scripts/benchmark.py --questions benchmarks/questions.jsonl