eduevidence 5.2.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (276) hide show
  1. package/README.md +54 -42
  2. package/README.zh-CN.md +51 -28
  3. package/SKILL.md +390 -133
  4. package/agents/openai.yaml +4 -0
  5. package/assets/readme/controlled-execution.svg +34 -0
  6. package/assets/readme/logo.png +0 -0
  7. package/assets/readme/research-workflow.svg +56 -0
  8. package/assets/readme/studio-graph.png +0 -0
  9. package/assets/readme/studio-overview.png +0 -0
  10. package/assets/readme/studio-reports.png +0 -0
  11. package/autoevolve/config.yaml +17 -0
  12. package/autoevolve/program.md +25 -0
  13. package/autoevolve/protected.manifest.yaml +34 -0
  14. package/benchmarks/adversarial/cases.jsonl +7 -0
  15. package/benchmarks/evidence-library.json +5268 -0
  16. package/benchmarks/partitions.json +8 -0
  17. package/docs/architecture.md +220 -0
  18. package/docs/autoresearch-evolution-plan.md +2903 -0
  19. package/docs/autoresearch-implementation-status.md +101 -0
  20. package/docs/demo-storyboard.md +20 -0
  21. package/docs/demo-workplace-ai.md +92 -0
  22. package/docs/demo.md +32 -0
  23. package/docs/install-guide.md +150 -0
  24. package/docs/orchestration-role-model.md +1254 -0
  25. package/docs/release-closeout/README.md +17 -0
  26. package/docs/release-closeout/frontend-acceptance.md +23 -0
  27. package/docs/release-closeout/issues.md +19 -0
  28. package/docs/release-closeout/verification.md +28 -0
  29. package/docs/release-contract.md +108 -0
  30. package/docs/research-studio-guide.zh-CN.md +166 -0
  31. package/eduevidence_cli.py +17 -11
  32. package/engine/_resources.py +13 -0
  33. package/engine/autoevolve/__init__.py +3 -0
  34. package/engine/autoevolve/agent_view.py +167 -0
  35. package/engine/autoevolve/core.py +357 -0
  36. package/engine/autoevolve/events.py +11 -0
  37. package/engine/autoevolve/git_workspace.py +77 -0
  38. package/engine/autoevolve/projection.py +23 -0
  39. package/engine/autoevolve/runner.py +413 -0
  40. package/engine/autoevolve/trust.py +146 -0
  41. package/engine/autoresearch/__init__.py +6 -0
  42. package/engine/autoresearch/commit.py +132 -0
  43. package/engine/autoresearch/contracts.py +126 -0
  44. package/engine/autoresearch/controller.py +207 -0
  45. package/engine/autoresearch/events.py +12 -0
  46. package/engine/autoresearch/gap_priority.py +168 -0
  47. package/engine/autoresearch/projection.py +30 -0
  48. package/engine/autoresearch/research_memory.py +59 -0
  49. package/engine/autoresearch/saturation.py +91 -0
  50. package/engine/briefs.py +2 -1
  51. package/engine/capabilities.py +1 -0
  52. package/engine/contracts.py +3 -1
  53. package/engine/evidencecore.py +7 -5
  54. package/engine/gaps.py +90 -51
  55. package/engine/judge_pack.py +65 -0
  56. package/engine/library_builtin.py +3 -1
  57. package/engine/living.py +2 -1
  58. package/engine/meta_synthesis.py +3 -1
  59. package/engine/orchestration.py +460 -0
  60. package/engine/pilot.py +2 -1
  61. package/engine/project.py +2 -2
  62. package/engine/research_service.py +113 -0
  63. package/engine/studio_read_model.py +400 -0
  64. package/engine/tribunal.py +1 -2
  65. package/engine/update.py +1 -0
  66. package/engine/versions.py +1 -1
  67. package/engine/worker_result.py +109 -0
  68. package/engine/workflows.py +70 -0
  69. package/examples/ai-coding-assistant-evidence/EduEvidence_Report.html +1720 -0
  70. package/examples/ai-coding-assistant-evidence/artifact_manifest.json +15 -0
  71. package/examples/ai-coding-assistant-evidence/citation_check.json +79 -0
  72. package/examples/ai-coding-assistant-evidence/claims.jsonl +12 -0
  73. package/examples/ai-coding-assistant-evidence/evaluation.json +35 -0
  74. package/examples/ai-coding-assistant-evidence/evidence.jsonl +12 -0
  75. package/examples/ai-coding-assistant-evidence/frame.json +48 -0
  76. package/examples/ai-coding-assistant-evidence/intervention.json +51 -0
  77. package/examples/ai-coding-assistant-evidence/methodology.json +36 -0
  78. package/examples/ai-coding-assistant-evidence/raw_verdict.json +86 -0
  79. package/examples/ai-coding-assistant-evidence/report_spec.json +219 -0
  80. package/examples/ai-coding-assistant-evidence/reports-5themes/EduEvidence_Report_academic.html +2614 -0
  81. package/examples/ai-coding-assistant-evidence/reports-5themes/EduEvidence_Report_claude.html +2614 -0
  82. package/examples/ai-coding-assistant-evidence/reports-5themes/EduEvidence_Report_datalab-dark.html +2614 -0
  83. package/examples/ai-coding-assistant-evidence/reports-5themes/EduEvidence_Report_datalab.html +2614 -0
  84. package/examples/ai-coding-assistant-evidence/reports-5themes/EduEvidence_Report_presentation.html +2614 -0
  85. package/examples/ai-coding-assistant-evidence/reports-5themes/report_academic.html +1720 -0
  86. package/examples/ai-coding-assistant-evidence/reports-5themes/report_claude.html +1720 -0
  87. package/examples/ai-coding-assistant-evidence/reports-5themes/report_datalab-dark.html +1720 -0
  88. package/examples/ai-coding-assistant-evidence/reports-5themes/report_datalab.html +1720 -0
  89. package/examples/ai-coding-assistant-evidence/reports-5themes/report_presentation.html +1720 -0
  90. package/examples/ai-coding-assistant-evidence/result.json +1453 -0
  91. package/examples/ai-coding-assistant-evidence/result.zh.json +1453 -0
  92. package/examples/ai-coding-assistant-evidence/sources.jsonl +8 -0
  93. package/examples/ai-coding-assistant-evidence/verdict.json +103 -0
  94. package/examples/workplace-ai-assistant/claims.jsonl +4 -0
  95. package/examples/workplace-ai-assistant/evaluation.json +19 -0
  96. package/examples/workplace-ai-assistant/evidence.jsonl +4 -0
  97. package/examples/workplace-ai-assistant/evidence_graph.json +444 -0
  98. package/examples/workplace-ai-assistant/frame.json +41 -0
  99. package/examples/workplace-ai-assistant/intervention.json +27 -0
  100. package/examples/workplace-ai-assistant/legacy-link-check.json +16 -0
  101. package/examples/workplace-ai-assistant/methodology.json +60 -0
  102. package/examples/workplace-ai-assistant/report_spec.json +55 -0
  103. package/examples/workplace-ai-assistant/reports-5themes/EduEvidence_Report_academic.html +2484 -0
  104. package/examples/workplace-ai-assistant/reports-5themes/EduEvidence_Report_claude.html +2484 -0
  105. package/examples/workplace-ai-assistant/reports-5themes/EduEvidence_Report_datalab-dark.html +2484 -0
  106. package/examples/workplace-ai-assistant/reports-5themes/EduEvidence_Report_datalab.html +2484 -0
  107. package/examples/workplace-ai-assistant/reports-5themes/EduEvidence_Report_presentation.html +2484 -0
  108. package/examples/workplace-ai-assistant/result.json +553 -0
  109. package/examples/workplace-ai-assistant/result.zh.json +553 -0
  110. package/examples/workplace-ai-assistant/search_log.json +19 -0
  111. package/examples/workplace-ai-assistant/sources.jsonl +3 -0
  112. package/examples/workplace-ai-assistant/validation_result.json +9 -0
  113. package/examples/workplace-ai-assistant/verdict.json +52 -0
  114. package/install.sh +7 -7
  115. package/integrations/orchestration_dispatch.py +146 -0
  116. package/package.json +37 -3
  117. package/pyproject.toml +11 -20
  118. package/references/autoresearch.md +30 -0
  119. package/references/evaluation-policy.md +24 -0
  120. package/references/orchestration.md +22 -0
  121. package/references/scientific-invariants.md +19 -0
  122. package/retrieval/audit.py +154 -0
  123. package/schemas/intervention.schema.json +106 -21
  124. package/schemas/report-result.schema.json +9 -1
  125. package/schemas/v2/project.schema.json +2 -2
  126. package/schemas/v2/run.schema.json +1 -1
  127. package/schemas/vNext/autoevolve-session.schema.json +1 -0
  128. package/schemas/vNext/eval-snapshot.schema.json +1 -0
  129. package/schemas/vNext/execution-plan.schema.json +1 -0
  130. package/schemas/vNext/gap-priority.schema.json +1 -0
  131. package/schemas/vNext/negative-search-record.schema.json +1 -0
  132. package/schemas/vNext/research-iteration.schema.json +1 -0
  133. package/schemas/vNext/research-strategy.schema.json +1 -0
  134. package/schemas/vNext/skill-experiment.schema.json +1 -0
  135. package/schemas/vNext/task-spec.schema.json +1 -0
  136. package/schemas/vNext/worker-result.schema.json +1 -0
  137. package/scripts/benchmark_judge.py +2 -2
  138. package/scripts/benchmark_v3.py +26 -43
  139. package/scripts/build_esl_artifacts.py +2 -2
  140. package/scripts/build_evidence_library.py +2 -2
  141. package/scripts/build_gh_pages.py +98 -0
  142. package/scripts/build_readme_diagrams.py +72 -0
  143. package/scripts/build_report_variants.py +85 -0
  144. package/scripts/check_autoresearch_invariants.py +95 -0
  145. package/scripts/daily_evolve.py +30 -0
  146. package/scripts/dashboard_server.py +130 -101
  147. package/scripts/did_regression.py +5 -30
  148. package/scripts/enrich_projects_human_and_lieflat.py +1 -1
  149. package/scripts/generate_metrics.py +4 -3
  150. package/scripts/generate_new_projects.py +1 -1
  151. package/scripts/orchestrator.py +172 -18
  152. package/scripts/rebake_all_5themes.py +1 -2
  153. package/scripts/research_auto_cli.py +475 -0
  154. package/scripts/run_workspace.py +17 -7
  155. package/scripts/search_provenance.py +64 -0
  156. package/scripts/serve_web.py +9 -10
  157. package/scripts/skill_lint.py +1 -1
  158. package/scripts/skill_payload.py +78 -0
  159. package/scripts/validate_schema.py +15 -1
  160. package/scripts/vnext_cli.py +133 -0
  161. package/setup.py +12 -0
  162. package/skill/roles/registry.yaml +45 -0
  163. package/skill/sub-skills/report-generation/SKILL.md +12 -6
  164. package/skill/task-briefs/applicability.md +3 -0
  165. package/skill/task-briefs/projection.md +3 -0
  166. package/skill/workflows/decision-and-pilot.md +10 -0
  167. package/skill/workflows/evaluate-and-update.md +10 -0
  168. package/skill/workflows/evidence-review.md +13 -0
  169. package/visualization/eduevidence-report/assets/base.css +2 -2
  170. package/visualization/eduevidence-report/assets/reader.css +752 -0
  171. package/visualization/eduevidence-report/assets/reader.js +132 -0
  172. package/visualization/eduevidence-report/references/chart-selection-catalog.md +109 -0
  173. package/visualization/eduevidence-report/references/lieflat-composition.md +3 -1
  174. package/visualization/eduevidence-report/scripts/build_report.py +58 -65
  175. package/visualization/eduevidence-report/scripts/lieflat_engine.py +24 -100
  176. package/visualization/eduevidence-report/themes/academic.css +1 -1
  177. package/visualization/eduevidence-report/themes/claude.css +1 -1
  178. package/visualization/eduevidence-report/themes/datalab-dark.css +2 -2
  179. package/visualization/eduevidence-report/themes/datalab.css +2 -2
  180. package/visualization/eduevidence-report/themes/presentation.css +2 -2
  181. package/web/README.md +18 -0
  182. package/web/index.html +53 -0
  183. package/web/studio/THIRD_PARTY_LICENSES.txt +146 -0
  184. package/web/studio/assets/index-CzXocaGv.css +1 -0
  185. package/web/studio/assets/index-pa7jD7n4.js +230 -0
  186. package/web/studio/config.json +1 -0
  187. package/web/studio/index.html +14 -0
  188. package/engine/__pycache__/__init__.cpython-312.pyc +0 -0
  189. package/engine/__pycache__/analysis.cpython-312.pyc +0 -0
  190. package/engine/__pycache__/bias.cpython-312.pyc +0 -0
  191. package/engine/__pycache__/briefs.cpython-312.pyc +0 -0
  192. package/engine/__pycache__/capabilities.cpython-312.pyc +0 -0
  193. package/engine/__pycache__/citation_check.cpython-312.pyc +0 -0
  194. package/engine/__pycache__/contracts.cpython-312.pyc +0 -0
  195. package/engine/__pycache__/datasets.cpython-312.pyc +0 -0
  196. package/engine/__pycache__/events.cpython-312.pyc +0 -0
  197. package/engine/__pycache__/evidence_graph.cpython-312.pyc +0 -0
  198. package/engine/__pycache__/evidence_review.cpython-312.pyc +0 -0
  199. package/engine/__pycache__/evidencecore.cpython-312.pyc +0 -0
  200. package/engine/__pycache__/gap_lens.cpython-312.pyc +0 -0
  201. package/engine/__pycache__/gaps.cpython-312.pyc +0 -0
  202. package/engine/__pycache__/graph_store.cpython-312.pyc +0 -0
  203. package/engine/__pycache__/graph_validate.cpython-312.pyc +0 -0
  204. package/engine/__pycache__/ids.cpython-312.pyc +0 -0
  205. package/engine/__pycache__/library.cpython-312.pyc +0 -0
  206. package/engine/__pycache__/library_builtin.cpython-312.pyc +0 -0
  207. package/engine/__pycache__/living.cpython-312.pyc +0 -0
  208. package/engine/__pycache__/log.cpython-312.pyc +0 -0
  209. package/engine/__pycache__/meta_analysis.cpython-312.pyc +0 -0
  210. package/engine/__pycache__/meta_synthesis.cpython-312.pyc +0 -0
  211. package/engine/__pycache__/migration.cpython-312.pyc +0 -0
  212. package/engine/__pycache__/mode_router.cpython-312.pyc +0 -0
  213. package/engine/__pycache__/paths.cpython-312.pyc +0 -0
  214. package/engine/__pycache__/pilot.cpython-312.pyc +0 -0
  215. package/engine/__pycache__/planner.cpython-312.pyc +0 -0
  216. package/engine/__pycache__/project.cpython-312.pyc +0 -0
  217. package/engine/__pycache__/projections.cpython-312.pyc +0 -0
  218. package/engine/__pycache__/robustness.cpython-312.pyc +0 -0
  219. package/engine/__pycache__/run.cpython-312.pyc +0 -0
  220. package/engine/__pycache__/semantics.cpython-312.pyc +0 -0
  221. package/engine/__pycache__/study_design.cpython-312.pyc +0 -0
  222. package/engine/__pycache__/synthesis.cpython-312.pyc +0 -0
  223. package/engine/__pycache__/tribunal.cpython-312.pyc +0 -0
  224. package/engine/__pycache__/update.cpython-312.pyc +0 -0
  225. package/engine/__pycache__/versions.cpython-312.pyc +0 -0
  226. package/integrations/__pycache__/__init__.cpython-312.pyc +0 -0
  227. package/integrations/__pycache__/agent_mcp.cpython-312.pyc +0 -0
  228. package/integrations/__pycache__/smart_web_fetch.cpython-312.pyc +0 -0
  229. package/retrieval/__pycache__/__init__.cpython-312.pyc +0 -0
  230. package/retrieval/__pycache__/corpus_store.cpython-312.pyc +0 -0
  231. package/retrieval/__pycache__/dedupe.cpython-312.pyc +0 -0
  232. package/retrieval/__pycache__/failures.cpython-312.pyc +0 -0
  233. package/retrieval/__pycache__/fetch.cpython-312.pyc +0 -0
  234. package/retrieval/__pycache__/search.cpython-312.pyc +0 -0
  235. package/retrieval/__pycache__/source.cpython-312.pyc +0 -0
  236. package/retrieval/__pycache__/validate.cpython-312.pyc +0 -0
  237. package/scripts/__pycache__/__init__.cpython-312.pyc +0 -0
  238. package/scripts/__pycache__/benchmark.cpython-312.pyc +0 -0
  239. package/scripts/__pycache__/benchmark_evaluator.cpython-312.pyc +0 -0
  240. package/scripts/__pycache__/benchmark_judge.cpython-312.pyc +0 -0
  241. package/scripts/__pycache__/benchmark_routing.cpython-312.pyc +0 -0
  242. package/scripts/__pycache__/benchmark_v2.cpython-312.pyc +0 -0
  243. package/scripts/__pycache__/benchmark_v3.cpython-312.pyc +0 -0
  244. package/scripts/__pycache__/build_result.cpython-312.pyc +0 -0
  245. package/scripts/__pycache__/claim_audit.cpython-312.pyc +0 -0
  246. package/scripts/__pycache__/complexity_gate.cpython-312.pyc +0 -0
  247. package/scripts/__pycache__/compute_confidence.cpython-312.pyc +0 -0
  248. package/scripts/__pycache__/dashboard_server.cpython-312.pyc +0 -0
  249. package/scripts/__pycache__/did_regression.cpython-312.pyc +0 -0
  250. package/scripts/__pycache__/effect_calculator.cpython-312.pyc +0 -0
  251. package/scripts/__pycache__/evidence_matrix.cpython-312.pyc +0 -0
  252. package/scripts/__pycache__/evidence_score.cpython-312.pyc +0 -0
  253. package/scripts/__pycache__/evidence_semantics.cpython-312.pyc +0 -0
  254. package/scripts/__pycache__/fetch_benchmark.cpython-312.pyc +0 -0
  255. package/scripts/__pycache__/lint_report_layout.cpython-312.pyc +0 -0
  256. package/scripts/__pycache__/orchestrator.cpython-312.pyc +0 -0
  257. package/scripts/__pycache__/pre_verdict_gate.cpython-312.pyc +0 -0
  258. package/scripts/__pycache__/recompute_demo_quality.cpython-312.pyc +0 -0
  259. package/scripts/__pycache__/render_report.cpython-312.pyc +0 -0
  260. package/scripts/__pycache__/render_report_html.cpython-312.pyc +0 -0
  261. package/scripts/__pycache__/run_workspace.cpython-312.pyc +0 -0
  262. package/scripts/__pycache__/skill_lint.cpython-312.pyc +0 -0
  263. package/scripts/__pycache__/startup_probe.cpython-312.pyc +0 -0
  264. package/scripts/__pycache__/sync_killer_demo_report.cpython-312.pyc +0 -0
  265. package/scripts/__pycache__/test_adversarial_empirical.cpython-312-pytest-9.0.2.pyc +0 -0
  266. package/scripts/__pycache__/test_adversarial_empirical.cpython-312-pytest-9.1.1.pyc +0 -0
  267. package/scripts/__pycache__/validate_schema.cpython-312.pyc +0 -0
  268. package/visualization/eduevidence-report/scripts/__pycache__/adapter_contract.cpython-312.pyc +0 -0
  269. package/visualization/eduevidence-report/scripts/__pycache__/build_artifact_manifest.cpython-312.pyc +0 -0
  270. package/visualization/eduevidence-report/scripts/__pycache__/build_charts.cpython-312.pyc +0 -0
  271. package/visualization/eduevidence-report/scripts/__pycache__/build_figures.cpython-312.pyc +0 -0
  272. package/visualization/eduevidence-report/scripts/__pycache__/build_infographics.cpython-312.pyc +0 -0
  273. package/visualization/eduevidence-report/scripts/__pycache__/build_report.cpython-312.pyc +0 -0
  274. package/visualization/eduevidence-report/scripts/__pycache__/charts_data.cpython-312.pyc +0 -0
  275. package/visualization/eduevidence-report/scripts/__pycache__/lieflat_engine.cpython-312.pyc +0 -0
  276. package/visualization/eduevidence-report/scripts/__pycache__/zh_labels.cpython-312.pyc +0 -0
package/README.md CHANGED
@@ -1,18 +1,22 @@
1
+ <p align="center">
2
+ <img src="assets/readme/logo.png" width="88" height="88" alt="EduEvidence logo" />
3
+ </p>
4
+
1
5
  # EduEvidence
2
6
 
3
7
  > **🌐 English | [中文](README.zh-CN.md)**
4
8
 
5
- ## EduEvidence Research Engine — Evidence-Based Education Decision Skill
9
+ ## EduEvidence Research Engine — Evidence Research & Decision Skill
6
10
 
7
- > **From Education Questions to Evidence-Based Decisions.**
11
+ > **From Research Questions to Evidence-Based Decisions.**
8
12
 
9
13
  EduEvidence is delivered as an **AI Agent Skill**; inside the Skill operates
10
14
  the **EduEvidence Research Engine** — a persistent, auditable engine that
11
- turns education questions into evidence-grounded decisions.
15
+ turns research questions into evidence-grounded decisions across education and organizational policy.
12
16
 
13
- - **Two Research Modes** — **Evidence Review** (secondary-evidence research)
14
- and **Full Research Cycle** (Evidence Review Knowledge Gap study design
15
- your data analysis updated decision).
17
+ - **Three public workflows** — **Evidence Review**, **Decision & Pilot**, and
18
+ **Evaluate & Update**. A full research cycle connects existing evidence,
19
+ grounded knowledge gaps, a study design, new data and a revised decision.
16
20
  - **Project Workspace + Evidence Graph** — long-lived Projects with versioned,
17
21
  immutable graph revisions; `result.json`/HTML/Markdown are projections, not
18
22
  fact stores.
@@ -21,14 +25,16 @@ turns education questions into evidence-grounded decisions.
21
25
  - **Frozen scientific rule** — *No new study design without evidence
22
26
  grounding*: designs must reference explicit, evidence-grounded Knowledge
23
27
  Gap IDs.
24
- - ⚖️ It does not generate answers for teachers — it shows what the evidence supports, what it cannot support, who it applies to, and how to pilot and verify it.
28
+ - ⚖️ Inspect what the evidence supports, what it cannot support, who it applies to, and how to pilot and verify it.
25
29
  - 🧪 Built on real research (examples include CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 empirical evidence); no claims without sources.
26
- - 🚦 The output is not a binary "allow/forbid" answer but a four-state decision — **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** — plus an actionable teaching intervention and evaluation plan.
30
+ - 🚦 The output is not a binary "allow/forbid" answer but a four-state decision — **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** — plus an actionable intervention and evaluation plan.
27
31
  - 🧩 The engine is an internal capability architecture — not a standalone
28
32
  server/app; Native Core runs on Python stdlib only and never requires
29
33
  Agent MCP or a daemon.
30
34
 
31
- ![EduEvidence overview banner](assets/top-banner.jpg)
35
+ ![Actual Research Studio overview: workplace AI evidence](assets/readme/studio-overview.png)
36
+
37
+ *Actual local Studio screenshot. This case is manually curated literature, with no attached research execution history.*
32
38
 
33
39
  ---
34
40
 
@@ -54,7 +60,7 @@ bash install.sh # one-click: venv + deps + self-check + tests
54
60
  Open the example report right away:
55
61
 
56
62
  ```bash
57
- open examples/ai-coding-assistant/EduEvidence_Report.html
63
+ open examples/ai-coding-assistant-evidence/EduEvidence_Report.html
58
64
  ```
59
65
 
60
66
  > Requires Python 3.10+; the core has zero third-party dependencies. `pip install matplotlib` is optional for academic-figure PNG/PDF export.
@@ -174,7 +180,7 @@ It answers six questions:
174
180
  | 155–170s | Teaching Intervention + Evaluation |
175
181
  | 170–180s | Benchmark |
176
182
 
177
- Full example pack: [`examples/ai-coding-assistant/`](examples/ai-coding-assistant/).
183
+ Full example pack: [`examples/ai-coding-assistant-evidence/`](examples/ai-coding-assistant-evidence/).
178
184
 
179
185
  ## Why Education Evidence Is Hard
180
186
 
@@ -244,7 +250,7 @@ The demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant r
244
250
  - Can Claim / Cannot Claim boundaries
245
251
  - four-state decision + Confidence (rule-based, not model-generated freely)
246
252
 
247
- ![Evidence Tribunal Workflow](assets/tribunal-workflow.jpg)
253
+ ![Evidence Tribunal Workflow](assets/readme/research-workflow.svg)
248
254
 
249
255
  ## From Evidence to Action
250
256
 
@@ -276,26 +282,18 @@ Key metrics: Citation Support Precision / Unsupported Claim Rate / Contradiction
276
282
 
277
283
  > **Should first-year C programming students be allowed to use generative AI coding assistants?**
278
284
 
279
- `examples/ai-coding-assistant/` shows the full path from question to decision:
285
+ `examples/ai-coding-assistant-evidence/` shows the full path from question to decision:
280
286
 
281
- - **Evidence** (7 items, all bound to real sources): task-performance gains (Kazemitabaar 2023), unguarded access harming independent exam performance by −17% (Bastani 2025, PNAS), guardrails eliminating the negative effect (Bastani 2025), formative-feedback writing evidence (Marzuki 2024).
287
+ - **Evidence** (12 findings from 8 sources): task-performance gains (Kazemitabaar 2023), unguarded access harming independent exam performance by −17% (Bastani 2025, PNAS), guardrails eliminating the negative effect (Bastani 2025), formative-feedback writing evidence (Marzuki 2024).
282
288
  - **Decision**: **PILOT** — task-performance evidence is strong, but direct learning-effect evidence for university programming courses is missing, and the unguarded-access risk is documented.
283
289
  - **Intervention**: 4-phase pilot (Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check).
284
290
  - **Evaluation**: no-AI baseline / post-test / final-exam retention / no-AI transfer task + AI-dependency risk metrics.
285
291
 
286
- Two more examples AI writing assistant (`examples/ai-writing-assistant/`) and a calculus AI tutor (`examples/ai-tutor/`) show the skill is not hard-coded to one question.
292
+ 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.
287
293
 
288
- **Example provenance (read before citing)**: every example pack carries a `data_origin`
289
- badge in its report header and in `result.json.meta`:
294
+ 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.
290
295
 
291
- - `examples/ai-coding-assistant-evidence/` **flagship, real literature**: 8 sources with
292
- registry-verified DOIs (Crossref/DataCite audit: `benchmarks/doi-audit/report.md`),
293
- engine-computed confidence; data_origin=`manual_curated`.
294
- - `examples/ai-coding-assistant/`, `ai-tutor/`, `ai-writing-assistant/` — real-source
295
- walkthrough packs.
296
- - `examples/esl-academic-writing-ai/`, `highschool-math-ai-tutor/` — **synthetic
297
- demonstrations** (data_origin=`synthetic`). Their numbers and citations are illustrative,
298
- not real studies; reports carry a loud SYNTHETIC badge. Do not cite them as evidence.
296
+ 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.
299
297
 
300
298
  ### Start your own research in ~30 minutes
301
299
 
@@ -307,9 +305,19 @@ bash scripts/bake_pack.sh <pack_dir> # 5-theme bilingual rep
307
305
  python3 scripts/citation_check.py --pack <pack_dir> --write-back # DOI ✓ badges
308
306
  ```
309
307
 
308
+ ## Studio in use
309
+
310
+ Select a graph node to trace source → finding → claim. The flow is a visual aid; it does not signal an active research run.
311
+
312
+ ![Actual provenance graph](assets/readme/studio-graph.png)
313
+
314
+ Read the same evidence through five independent report themes, with bilingual and brief/full views.
315
+
316
+ ![Actual report reading room](assets/readme/studio-reports.png)
317
+
310
318
  ## Visualization: Bilingual HTML Report + Infographics + Academic Figures
311
319
 
312
- After research completes, `result.json` is rendered into three visualization outputs by deterministic Python adapters. The adapters themselves use the standard library; the optional Web Studio chart enhancement has a separate browser dependency.
320
+ After research completes, `result.json` is rendered into three visualization outputs by deterministic Python adapters. The adapters themselves use the standard library; legacy ECharts enhancement is optional and is not required by the new Research Studio.
313
321
 
314
322
  ```text
315
323
  result.json + result.zh.json (Chinese parallel data)
@@ -328,9 +336,13 @@ result.json + result.zh.json (Chinese parallel data)
328
336
  - **Static-first**: decision, matrix, tribunal, intervention and sources remain readable without JavaScript; ECharts is an optional enhancement.
329
337
  - **Integrity gate**: chart numbers are checked against result.json item by item; publishing is blocked with `REPORT_INVALID` on mismatch.
330
338
 
331
- **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.
339
+ **Research Studio** is a read-only research workspace. Start `python3 scripts/dashboard_server.py --port 8765` and open `/studio/` to inspect projects, evidence, sources, recorded runs, committed revisions and five report identities. Skill Autoevolve has a separate observation view; the console cannot start research, mutate evidence or dispatch agents.
340
+
341
+ The React + TypeScript frontend ships as static assets: Node is needed only for development, not for running the packaged Skill. Its charts do not depend on a remote ECharts CDN and never compute a pooled effect in the browser. Local research remains local; GitHub Pages exports public example packs only. Report themes are generated from complete bilingual inputs with explicit missing-data states, not fabricated fallback claims.
342
+
343
+ See [Research Studio workflow and delivery guide](docs/research-studio-guide.zh-CN.md).
332
344
 
333
- > Open the example directly: `examples/ai-coding-assistant/EduEvidence_Report.html`
345
+ > Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
334
346
 
335
347
  ## Architecture
336
348
 
@@ -360,14 +372,14 @@ EduEvidence/ (= one Skill package)
360
372
  │ bilingual HTML composer + V2 project surfaces)
361
373
 
362
374
  ├─ Quality assurance
363
- │ ├─ tests/ pytest test matrix (V1–V4, 752 test functions / 73 files — docs/metrics.json)
375
+ │ ├─ tests/ pytest test matrix (V1–V4, current counts in docs/metrics.json)
364
376
  │ └─ benchmarks/ V1 questions + benchmarks/v2/ (graph/contract metrics)
365
377
 
366
378
  └─ Demos & distribution
367
379
  ├─ examples/ Research & Decision Packs + full-research-cycle-fixture (synthetic)
368
380
  ├─ docs/ architecture / methodology / benchmark / demo / reproducibility
369
381
  ├─ install.sh one-click install (local / multi-agent Skill) + self-check
370
- ├─ pyproject.toml packaging metadata (wheel ships CLI + engine; stdlib-only core)
382
+ ├─ pyproject.toml packaging metadata (wheel ships CLI, engine and installed runtime resources; stdlib-only core)
371
383
  └─ README(.en).md bilingual docs
372
384
  ```
373
385
 
@@ -419,7 +431,7 @@ Agent MCP is a **performance & reliability enhancement layer, not a prerequisite
419
431
 
420
432
  > 🔒 Agent MCP principle: **Scan first. Recommend second. Ask the user. Execute only after explicit confirmation.** No spawn without user approval; reject → fall back to Native.
421
433
 
422
- ![Controlled Multi-Agent Research](assets/multi-agent-research.jpg)
434
+ ![Controlled Multi-Agent Research](assets/readme/controlled-execution.svg)
423
435
 
424
436
 
425
437
  ## Usage
@@ -427,31 +439,31 @@ Agent MCP is a **performance & reliability enhancement layer, not a prerequisite
427
439
  ```bash
428
440
  # 1. Validate data against the schema contracts
429
441
  python3 scripts/validate_schema.py --schema schemas/evidence.schema.json \
430
- --data examples/ai-coding-assistant/evidence.jsonl
442
+ --data examples/ai-coding-assistant-evidence/evidence.jsonl
431
443
 
432
444
  # 2. Compute evidence quality scores and Confidence
433
- python3 scripts/evidence_score.py examples/ai-coding-assistant/evidence.jsonl
445
+ python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence.jsonl
434
446
 
435
447
  # 3. Generate the Evidence Matrix (one of the core views)
436
- python3 scripts/evidence_matrix.py examples/ai-coding-assistant/evidence.jsonl
448
+ python3 scripts/evidence_matrix.py examples/ai-coding-assistant-evidence/evidence.jsonl
437
449
 
438
450
  # 4. Run the Citation Audit (claim-evidence traceability)
439
451
  python3 scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
440
452
 
441
453
  # 5. Render the Research & Decision Pack (Markdown)
442
454
  python3 scripts/render_report.py \
443
- --frame examples/ai-coding-assistant/frame.json \
444
- --evidence examples/ai-coding-assistant/evidence.jsonl \
445
- --methodology examples/ai-coding-assistant/methodology.json \
446
- --verdict examples/ai-coding-assistant/verdict.json \
447
- --intervention examples/ai-coding-assistant/intervention.json \
448
- --evaluation examples/ai-coding-assistant/evaluation.json \
455
+ --frame examples/ai-coding-assistant-evidence/frame.json \
456
+ --evidence examples/ai-coding-assistant-evidence/evidence.jsonl \
457
+ --methodology examples/ai-coding-assistant-evidence/methodology.json \
458
+ --verdict examples/ai-coding-assistant-evidence/verdict.json \
459
+ --intervention examples/ai-coding-assistant-evidence/intervention.json \
460
+ --evaluation examples/ai-coding-assistant-evidence/evaluation.json \
449
461
  --out REPORT.md
450
462
 
451
463
  # 6. Render the single-file bilingual HTML report (main deliverable)
452
464
  python3 visualization/eduevidence-report/scripts/build_report.py \
453
- --result examples/ai-coding-assistant/result.json \
454
- --out examples/ai-coding-assistant/EduEvidence_Report.html
465
+ --result examples/ai-coding-assistant-evidence/result.json \
466
+ --out examples/ai-coding-assistant-evidence/EduEvidence_Report.html
455
467
 
456
468
  # 7. Validate the benchmark question set
457
469
  python3 scripts/benchmark.py --questions benchmarks/questions.jsonl
package/README.zh-CN.md CHANGED
@@ -1,19 +1,26 @@
1
+ <p align="center">
2
+ <img src="assets/readme/logo.png" width="88" height="88" alt="EduEvidence logo" />
3
+ </p>
4
+
1
5
  # EduEvidence
2
6
 
3
7
  > **🌐 [English](README.md) | 中文**
4
8
 
5
- ## EduEvidence Research Engine — Evidence-Based Education Decision Skill
9
+ ## EduEvidence Research Engine — Evidence Research & Decision Skill
6
10
 
7
- > **From Education Questions to Evidence-Based Decisions.**
8
- > **从教育问题,到有证据支撑的教育决策。**
11
+ > **From Research Questions to Evidence-Based Decisions.**
12
+ > **从研究问题,到有证据支撑的决策。**
9
13
 
10
- EduEvidence 面向教师、教学研究者与教学管理者,把"是否采用某教学法、课程设计、评估方式或 AI 教学工具"从经验判断转化为**可追溯、可质疑、可验证的证据决策流程**——教学法、课程、评估、学习干预与 AI 工具均是应用域,引擎方法学教育通用。
14
+ EduEvidence 面向研究者与实践决策者,将教育、组织政策和 AI 工具采用等问题转化为**可追溯、可质疑、可验证的证据决策流程**。当前公开案例涵盖编程学习和企业客服,分别使用教育与组织政策领域契约。
11
15
 
12
- - ⚖️ 不是替教师生成答案,而是帮助教师知道:证据支持什么、不能支持什么、适用于谁、应该怎样试点并验证。
16
+ - **三条公开工作流**:Evidence Review(证据综述)、Decision & Pilot(决策与试点)、Evaluate & Update(评估与更新)。完整研究周期将文献证据、有依据的知识缺口、研究设计、新数据和决策修订连接起来。
17
+ - ⚖️ 帮助研究者与实践决策者判断:证据支持什么、不能支持什么、适用于谁、应该怎样试点并验证。
13
18
  - 🧪 基于真实研究(示例包含 CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 的实证证据),不做无来源断言。
14
- - 🚦 最终输出不是"允许/禁止"的二元结论,而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的教学干预与评价方案。
19
+ - 🚦 最终输出不是"允许/禁止"的二元结论,而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的干预与评价方案。
20
+
21
+ ![实际研究概览:企业客服 AI 证据案例](assets/readme/studio-overview.png)
15
22
 
16
- ![EduEvidence 顶层宣传图](assets/top-banner.jpg)
23
+ *本地 Studio 实际截图。案例为人工整理文献,未附研究执行历史。*
17
24
 
18
25
  ---
19
26
 
@@ -52,7 +59,7 @@ bash install.sh # 一键:venv + 依赖 + 自检 + 测试
52
59
  安装后直接打开示例报告:
53
60
 
54
61
  ```bash
55
- open examples/ai-coding-assistant/EduEvidence_Report.html
62
+ open examples/ai-coding-assistant-evidence/EduEvidence_Report.html
56
63
  ```
57
64
 
58
65
  > 需要 Python 3.10+;核心零第三方依赖。学术图 PNG/PDF 导出可选装 matplotlib。
@@ -169,7 +176,7 @@ EduEvidence 执行:
169
176
  | 155–170s | Teaching Intervention + Evaluation |
170
177
  | 170–180s | Benchmark |
171
178
 
172
- 完整示例包见 [`examples/ai-coding-assistant/`](examples/ai-coding-assistant/)。
179
+ 完整示例包见 [`examples/ai-coding-assistant-evidence/`](examples/ai-coding-assistant-evidence/)。
173
180
 
174
181
  ## Why Education Evidence Is Hard
175
182
 
@@ -238,7 +245,7 @@ EduEvidence 强制区分 20 类 Outcome(`references/outcome-taxonomy.md`):
238
245
  - Can Claim / Cannot Claim 边界
239
246
  - 四态决策 + Confidence(规则化计算,不由模型自由生成)
240
247
 
241
- ![Evidence Tribunal Workflow](assets/tribunal-workflow.jpg)
248
+ ![Evidence Tribunal Workflow](assets/readme/research-workflow.svg)
242
249
 
243
250
  ## From Evidence to Action
244
251
 
@@ -270,18 +277,30 @@ B4 EduEvidence + Agent MCP ← 证明多 Agent 增强价值(B3 vs B4)
270
277
 
271
278
  > **大学一年级 C 语言课程是否应该允许学生使用生成式 AI 编程助手?**
272
279
 
273
- `examples/ai-coding-assistant/` 完整展示了从问题到决策的全过程:
280
+ `examples/ai-coding-assistant-evidence/` 完整展示了从问题到决策的全过程:
274
281
 
275
- - **证据**(7 条,均绑定真实来源):任务表现提升(Kazemitabaar 2023)、无护栏访问损害独立考试表现 -17%(Bastani 2025, PNAS)、护栏设计消除负效应(Bastani 2025)、形成性反馈写作证据(Marzuki 2024)。
282
+ - **证据**(12 条发现、8 个来源):任务表现提升(Kazemitabaar 2023)、无护栏访问损害独立考试表现 -17%(Bastani 2025, PNAS)、护栏设计消除负效应(Bastani 2025)、形成性反馈写作证据(Marzuki 2024)。
276
283
  - **决策**:**PILOT** —— 任务表现证据强,但大学编程课程的直接学习效应证据缺失,无护栏风险已被证实。
277
284
  - **干预**:4 阶段试点(Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check)。
278
285
  - **评价**:无 AI 基线/后测/期末考试保持/无 AI 迁移任务 + AI 依赖风险指标。
279
286
 
280
- 另外两个示例:AI 写作助手(`examples/ai-writing-assistant/`)、高数 AI Tutor(`examples/ai-tutor/`)——证明 Skill 不是为一个问题写死。
287
+ 另一公开案例 `examples/workplace-ai-assistant/` 使用组织政策领域,讨论企业客服是否引入 AI 助手:3 项研究、4 条发现,区分直接客服证据与间接写作/咨询证据,建议有监督试点。详见 [来源核验与边界](docs/demo-workplace-ai.md)。
288
+
289
+ 两个公开案例均为人工整理文献(`manual_curated`),报告生成不等于九阶段模型研究已运行,也不代表试点已经执行。四个旧教学示例迁入 `tests/fixtures/legacy-examples/`,仅供软件兼容测试,排除于公共目录和分发包;未核验或合成数据不能引用为研究证据。旧 `ai-coding-assistant` 路径保留兼容别名。
290
+
291
+ ## Studio 实际界面
292
+
293
+ 点击图谱节点可以追溯“来源 → 发现 → 主张”。连线流动用于辅助阅读,不表示后台研究正在执行。
294
+
295
+ ![实际溯源图谱](assets/readme/studio-graph.png)
296
+
297
+ 同一份证据可以用五个独立主题阅读,支持中英文及简报/全文切换。
298
+
299
+ ![实际报告阅读室](assets/readme/studio-reports.png)
281
300
 
282
301
  ## Visualization: Bilingual HTML Report + Infographics + Academic Figures
283
302
 
284
- 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.
303
+ 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.
285
304
 
286
305
  ```text
287
306
  result.json + result.zh.json
@@ -300,9 +319,13 @@ result.json + result.zh.json
300
319
  - **Static-first**: decision, matrix, tribunal, intervention and sources remain readable without JavaScript; ECharts is an optional enhancement.
301
320
  - **Integrity gate**: chart numbers are checked against result.json item by item; publishing is blocked with `REPORT_INVALID` on mismatch.
302
321
 
303
- **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.
322
+ **Research Studio 研究观察台**保持只读。运行 `python3 scripts/dashboard_server.py --port 8765`,打开 `/studio/`,即可查看研究项目、证据与来源、实际运行记录、已提交版本及五种风格报告。Skill 自进化实验单独展示;控制台不会启动研究、修改证据或派发代理。
323
+
324
+ 控制台采用 React + TypeScript,分发包已包含静态资源,使用者无需安装 Node。新图表不依赖远程 ECharts CDN,也不在浏览器中计算合并效应量。本地研究不会进入 GitHub Pages 公共导出。五主题从完整双语输入生成,缺失内容明确标记,不补造结论。
325
+
326
+ 详见[研究观察台流程与交付指南](docs/research-studio-guide.zh-CN.md)。
304
327
 
305
- > Open the example directly: `examples/ai-coding-assistant/EduEvidence_Report.html`
328
+ > Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
306
329
 
307
330
  ## Architecture
308
331
 
@@ -359,38 +382,38 @@ Agent MCP 是**性能与可靠性增强层,不是 EduEvidence 成立的前提*
359
382
 
360
383
  > 🔒 Agent MCP 原则:**Scan first. Recommend second. Ask the user. Execute only after explicit confirmation.** 未经用户确认不得 spawn;用户拒绝则回退 Native。
361
384
 
362
- ![Controlled Multi-Agent Research](assets/multi-agent-research.jpg)
385
+ ![Controlled Multi-Agent Research](assets/readme/controlled-execution.svg)
363
386
 
364
387
  ## Usage
365
388
 
366
389
  ```bash
367
390
  # 1. 验证数据符合 Schema 契约
368
391
  python3 scripts/validate_schema.py --schema schemas/evidence.schema.json \
369
- --data examples/ai-coding-assistant/evidence.jsonl
392
+ --data examples/ai-coding-assistant-evidence/evidence.jsonl
370
393
 
371
394
  # 2. 计算证据质量分与 Confidence
372
- python3 scripts/evidence_score.py examples/ai-coding-assistant/evidence.jsonl
395
+ python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence.jsonl
373
396
 
374
397
  # 3. 生成 Evidence Matrix(主产品界面之一)
375
- python3 scripts/evidence_matrix.py examples/ai-coding-assistant/evidence.jsonl
398
+ python3 scripts/evidence_matrix.py examples/ai-coding-assistant-evidence/evidence.jsonl
376
399
 
377
400
  # 4. 运行 Citation Audit(Claim-证据追溯)
378
401
  python3 scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
379
402
 
380
403
  # 5. 渲染 Research & Decision Pack(Markdown)
381
404
  python3 scripts/render_report.py \
382
- --frame examples/ai-coding-assistant/frame.json \
383
- --evidence examples/ai-coding-assistant/evidence.jsonl \
384
- --methodology examples/ai-coding-assistant/methodology.json \
385
- --verdict examples/ai-coding-assistant/verdict.json \
386
- --intervention examples/ai-coding-assistant/intervention.json \
387
- --evaluation examples/ai-coding-assistant/evaluation.json \
405
+ --frame examples/ai-coding-assistant-evidence/frame.json \
406
+ --evidence examples/ai-coding-assistant-evidence/evidence.jsonl \
407
+ --methodology examples/ai-coding-assistant-evidence/methodology.json \
408
+ --verdict examples/ai-coding-assistant-evidence/verdict.json \
409
+ --intervention examples/ai-coding-assistant-evidence/intervention.json \
410
+ --evaluation examples/ai-coding-assistant-evidence/evaluation.json \
388
411
  --out REPORT.md
389
412
 
390
413
  # 6. 渲染单文件双语 HTML 报告(主产物)
391
414
  python3 visualization/eduevidence-report/scripts/build_report.py \
392
- --result examples/ai-coding-assistant/result.json \
393
- --out examples/ai-coding-assistant/EduEvidence_Report.html
415
+ --result examples/ai-coding-assistant-evidence/result.json \
416
+ --out examples/ai-coding-assistant-evidence/EduEvidence_Report.html
394
417
 
395
418
  # 7. 校验 Benchmark 题目集
396
419
  python3 scripts/benchmark.py --questions benchmarks/questions.jsonl