eduevidence 5.2.0 → 6.2.0

package/docs/release-closeout/README.md

@@ -0,0 +1,17 @@
+# EduEvidence 6.1 发布收尾
+
+本目录记录本地确定性验证与实际前端验收，不代表真实模型研究已通过。完整提交目录为 `dist/eduevidence-submission/`，根目录即 `SKILL.md`；交付目录而非压缩包。
+
+- [修复与范围](issues.md)
+- [前端验收](frontend-acceptance.md)
+- [验证记录与分发检查](verification.md)
+- [当前演示说明](../demo.md)
+- [企业客服来源核验](../demo-workplace-ai.md)
+
+中英文 README 使用同一组实际截图与可再生成的 SVG。Logo 使用用户提供的原图，以小尺寸显示。`scripts/build_readme_diagrams.py` 从 `engine/workflows.py` 读取九阶段顺序，更新流程 SVG；截图来自本地 Studio 的公开案例。
+
+仅重建源码对应的运行资源和演示投影。保留原有 `benchmarks/evidence-library.json` 修改、安装路径修改和本地研究目录。未推送、合并、远端部署或发起付费模型研究。
+
+## 最终状态
+
+Skill 与前端在记录的本机确定性及实际浏览器覆盖范围内合格；真实模型研究与企业试点仍未验证。Python 3.10/3.12 各 928 通过、1 个可选依赖检查跳过；浏览器 29 通过。详细边界见验证记录。

package/docs/release-closeout/frontend-acceptance.md

@@ -0,0 +1,23 @@
+# 前端验收
+
+环境：本机 macOS、Playwright Chromium 1193。Studio 预构建资源在本地 Python 服务和静态子目录部署下测试。
+
+自动浏览器覆盖 320 / 390 / 768 / 1440px、明暗外观、项目六个标签、总览/阅读室/系统迭代/流程导览；包含错误/空数据、无历史、过期决定、API 失败、静态私有状态排除、五主题双语/全文、下载和离线阅读。serious/critical 可访问性扫描包含测试中列出的页面与报告；这不等同完整人工 WCAG 认证。
+
+动效验证包括 Canvas 图像变化、停止后 400ms rAF 数量不增长、主标题几何不变、触屏静态与 reduced-motion、完整图谱链和播放暂停。导航底板实际采样确认白色背景、由短到长过渡、链接/文本位置不变、减少动态时 transition=0s。移动端完整图谱允许其容器横向滚动，页面本身不横向溢出。
+
+## 图像证据
+
+- 改造前截图：仓库本地 `dist/release-closeout/before/`。
+- 最终测试截图及动效 metrics：`studio/test-results/closeout/`。
+- README 实拍：`assets/readme/studio-overview.png`、`studio-graph.png`、`studio-reports.png`。
+- 最终侧栏尺寸预览：`dist/release-closeout/sidebar-compact.png`。
+- 固定视觉基线：`studio/tests/closeout.spec.ts-snapshots/`，四宽度 × 两外观的总览页。
+
+本次没有历史视觉基线。先审阅截图、再创建首组 macOS 基线，并另行执行匹配检查；首次生成截图不作为历史回归通过证据。基线仅覆盖总览矩阵，其余页面依靠本次功能、布局、扫描与截图审阅。更换操作系统、字体或浏览器版本时须审阅后重新建立基线。
+
+人工检查重点为长标题、卡片可读性、移动端折行、图谱节点及连线、报告主题身份和新导航。这里记录本机验收范围，不宣称 Safari/Firefox 或真实触屏硬件已验证。屏幕截图无法单独证明动画连续性，相关结论来自浏览器中的运动/暂停采样。
+
+## 结论
+
+**本机覆盖范围内合格**：29 项浏览器测试通过，包括首组 8 张固定视觉基线的独立匹配复验；最终 TypeScript/生产构建通过，重复构建资源逐字一致。未解决的 serious/critical 扫描缺陷为 0。首次建立基线不代表过去版本的视觉回归已经验证。

package/docs/release-closeout/issues.md

@@ -0,0 +1,19 @@
+# 修复与范围
+
+| 问题 | 修复与验证方式 |
+|---|---|
+| 侧栏纹理不可见、文字后有方块 | 空白区铺开小轴测方块，品牌和文字区域遮罩；68px 局部范围的平滑衰减、弹簧起伏、暖色调，保留鼠标/键盘入口 |
+| 导航底板不一致 | 全部使用主题表面色，未选中底板缩短 42px、上下各缩进 3px；选中平滑展开，减少动态时禁用过渡 |
+| 主区光晕跟随感不足 | 三层按帧时间修正的阻尼跟随；离开淡出，页面隐藏、静止和卸载停止 rAF |
+| 图谱蓝色鼠标焦点框、流动截断 | 暖色键盘焦点环；沿真实边追溯完整上下游；总览与详情统一流动、暂停与减少动态降级 |
+| 五主题中宽布局裁切 | 修改共享 reader.css，行动卡换行、长文本断行；重新生成报告后布局门通过 |
+| 新例被误标为教育、强制 learner 字段 | meta.domain 与 frame 扩展回退；intervention 支持 target_population，报告显示目标人群；保留旧教育字段兼容 |
+| 旧例混入公开目录 | 四例移入明确标注的测试 fixtures；删除孤立生成报告；只公开编程与客服案例，重建静态 API |
+| 别名成为公共项目 ID | 目录扫描排除符号链接；兼容 API 仍可读取旧别名；测试明确核验两个 canonical ID |
+| 外部 schema 的内部引用失效 | 外部文件引用使用其自身文档根解析 definitions；增加回归用例 |
+| wheel 仅导入成功但无法定位资源 | 统一 source/share/sys.prefix 资源根；安装后实际读取 schema/domain、建项目、启动 Studio |
+| 包含旧 UI 或私有状态的风险 | flat Skill/wheel 共用显式运行文件清单；排除本地状态、旧 UI、测试、缓存与 holdout 答案 |
+| 测试改写本地证据库 | 内置证据库测试改为临时输出和隔离路径；原始工作树文件逐字比对恢复并保留 |
+| 旧 README 和演示脚本夸大能力 | 更新中英文、工作流图、实际截图和录屏说明；区分人工文献案例、执行记录与未开展的真实模型验证 |
+
+Archify 的阅读交互用于概念参考，图谱实现位于本项目 React/SVG 组件；未引入 Archify、Three.js 或远程动画依赖。方块采用用户最终确认的分离小方块视觉，不保留尝试过的连续网格面。

package/docs/release-closeout/verification.md

@@ -0,0 +1,28 @@
+# 验证记录
+
+完整日志保存在仓库本地 `dist/release-closeout/`，不是模型执行历史，也不会作为研究事实输入。最终分发目录附带本报告和逐文件 SHA-256 清单。
+
+| 检查 | 证据 |
+|---|---|
+| Python 3.12 / 3.10 | `python312-final.log` / `python310-final.log` |
+| 浏览器、无障碍、静态子目录 | `browser-final.log` |
+| 首组视觉基线建立 | `visual-baseline-create.log`，后续 browser-final 另行验证 |
+| 版本 / metrics / Ruff | `version.log` / `metrics-check.log` / `ruff.log` |
+| Skill 协议 / 科学不变量 | `skill-lint.log` / `scientific-gates.log` |
+| 五主题中宽布局 | `report-layout.log` |
+| 锁定依赖 / 安全检查 | `npm-ci.log` / `npm-audit.json` / `python-audit.json` |
+| 构建 / 静态导出 | `studio-build.log` / `pages-build.log` |
+| wheel / flat Skill | `wheel-build.log` / `final-package-smoke.log` |
+| 完整目录清单 | `dist/eduevidence-submission/submission-manifest.json` |
+
+Python 3.12 和 3.10 全量结果均为 **928 passed, 1 skipped**。跳过项是依赖可选第三方 jsonschema 的 `test_approval_matches_schema`；主路径的标准库 schema 验证已执行。六条 warning 来自已有对抗测试返回 dict，并非执行失败。metrics 的 878 表示源码测试函数数，不能与参数化执行用例数混用。版本 6.0.0、47 schemas、Skill lint、科学不变量与 Ruff 通过。
+
+隔离 wheel 和完整 Skill 均通过仓库外 CLI、schema、双领域读取、临时项目创建、HTTP Studio 与两例各五主题报告检查；启动 PATH 不含 Node。npm 锁定安装、官方 registry audit（0 vulnerabilities）和 pip-audit（未发现漏洞）有日志。真实模型九阶段研究、跨后端并行实证效果、企业试点执行均未开展；新客服例是人工文献整理。未知效应、置信区间和运行成本不会补成零。
+
+## 交付结论
+
+- **Skill：本地确定性门禁及独立运行范围内合格。**
+- **前端：本机已覆盖功能、视觉、动效和浏览器门禁范围内合格。** 最终 29 项浏览器测试通过，8 张初始基线经独立复验；生产资源二次构建逐字一致。
+- **真实模型研究 / 真实企业试点 / 跨后端实证比较：未验证。**
+
+最终提交为 `dist/eduevidence-submission/` 整体目录，未创建本次交付压缩包。根目录 `START-HERE.md` 提供中英启动说明，`submission-manifest.json` 校验文件完整性。

package/docs/release-contract.md

@@ -0,0 +1,108 @@
+# EduEvidence Release Contract（当前实现事实表）
+
+> 本文件记录当前可发布实现与边界。权威运行定义仍以 `SKILL.md`、`schemas/`、结果 JSON、CI 与 `packaging/make_upload.sh` 为准。
+
+## 1. 产品入口
+
+- **介绍页**：`web/landing.html`，用于项目说明与进入 Research Studio。
+- **正式控制台开发源**：`studio/`（React + TypeScript + Vite）。
+- **正式控制台运行时**：`web/studio/`，由构建生成，不手工编辑。
+- **本地入口**：`python3 scripts/dashboard_server.py --host 127.0.0.1 --port 8765` 后访问 `/studio/`。
+- **公开静态入口**：GitHub Pages 根页保留介绍页，`/studio/` 提供只读公开示例。
+- `web/index.html` 是新版构建缺失时的明确提示页，不会回退到旧版 v5 控制台。旧 `web/js/` 与 `web/styles.css` 仅保留在仓库中供兼容维护，不进入正式 Skill 包。
+
+## 2. Research Studio 边界
+
+Research Studio 是**只读研究驾驶舱**，可查看：
+
+- Project / Decision / Applicability
+- Sources / Studies / Findings / Claims
+- Source → Finding → Claim 图谱
+- Runs / stage state / execution plan / gates
+- Artifacts / Events
+- GraphRevision / DecisionSnapshot
+- KnowledgeGap / ResearchIteration
+- 五主题报告库
+- Skill Autoevolve 观测记录
+
+Studio 不拥有研究执行权，不提供绕过 Agent、CLI、Agent MCP、科学门或 canonical single-writer 的写入口。
+
+## 3. 科学展示契约
+
+1. 缺失值保持缺失，不把 `None`、未报告 CI 或无检索命中转换为 0。
+2. 合法 `0.0` 端点必须保留。
+3. Studio 不自行计算 pooled effect、跨 outcome 平均值或根据数值正负推断 Claim relation。
+4. Finding 的 observed effect 与 Finding→Claim 的 relation 是不同概念。
+5. DecisionSnapshot 若未绑定当前 GraphRevision，前端必须暴露 stale 状态。
+6. Graph 只读取 committed HEAD ancestry；孤立 revision 不进入历史。
+7. 报告缺数据时应抑制不适用图表，而不是生成假效应量、假 p 值、假风险或假课堂处方。
+
+## 4. 五主题报告契约
+
+保留五个视觉身份：
+
+- Claude Research
+- Academic Paper
+- DataLab
+- DataLab Dark
+- Presentation / Judge
+
+主题可以改变视觉语言、信息密度和阅读节奏，但同一研究版本的证据、来源、数值、适用边界与 Decision 必须一致。
+
+报告包含 Visual Brief 与 Full Report 两种阅读层级。Full Report 由语义模块组成，允许上游 AI 组织通常 5–7 个章节；未提供有效 outline 时使用内置 fallback。图表选择可以由 AI 根据数据形态规划，但数值由确定性提取器从 `result.json` 读取。
+
+报告仍保持 single-file、双语、离线可读；JavaScript 是增强层，不得成为关键科学内容唯一载体。
+
+## 5. Evidence Autoresearch / Skill Autoevolve 边界
+
+- Evidence Autoresearch 可以优化检索策略和研究过程，但不能让 worker 直接解决 KnowledgeGap、修改 canonical scientific state 或自动决定最终结论。
+- Skill Autoevolve 不修改真实用户研究状态。
+- 自动流程不得自主发起人体研究、merge `main`、release 或 deploy。
+- Evidence revision 与 Skill revision 是两条独立历史。
+
+## 6. 静态发布与隐私
+
+GitHub Pages 构建只导出仓库中的公开 examples。以下内容不得进入静态站：
+
+- `EDUEVIDENCE_HOME`
+- 本地用户 projects
+- research-control SQLite 数据
+- 本地 run/event/artifact 历史
+- Autoevolve 私有 session / candidate 内容
+
+本地 Studio 的 SQLite 访问是只读；投影不得向浏览器暴露宿主机文件路径。
+
+## 7. 构建与门禁
+
+当前发布门包含：
+
+- Python 3.10 / 3.12 full pytest
+- Ruff E9/F63/F7/F82
+- metrics gate
+- schema smoke
+- isolated wheel smoke
+- upload build
+- SKILL parity
+- zero-leak
+- Autoresearch scientific / orchestration / protected gates
+- benchmark partition contract
+- npm locked install + high-severity audit
+- TypeScript build
+- `web/studio/` reproducible build check
+- Playwright browser / responsive / static deployment tests
+- serious / critical accessibility scan
+- five-theme standalone report validation
+- final Skill closure build
+- GitHub Pages local build (remote deployment requires separate authorization)
+
+自动测试不是完整人工 WCAG 认证，也不能替代视觉审查；关键前端变更应同时检查 CI 截图。
+
+## 8. 分发边界
+
+`packaging/make_upload.sh` 以 allowlist 从干净 staging 重建最终 Skill。发布包应包含运行所需的 `SKILL.md`、agents 配置、engine、schemas、references、retrieval、integrations、visualization、构建后的 `web/studio/` 与必要文档；不得携带 `.git`、`.venv`、缓存、本地研究状态、私有 benchmark 历史或 Autoevolve 私有运行目录。
+
+Node 是 Research Studio **开发/构建依赖**，不是最终本地 Studio 的运行依赖；最终用户运行控制台只需要已构建的静态资源与 Python 服务。
+
+## 9. 仓库治理
+
+`main` 的代码合并应以 exact-head CI 为门。仓库当前应优先配置 GitHub branch protection / ruleset，至少要求 PR、CI、Autoresearch Gates 与 Research Studio 检查通过后才能合并；自动研究与 Autoevolve 永远不是 `main` 的 merge authority。

package/docs/research-studio-guide.zh-CN.md

@@ -0,0 +1,166 @@
+# Research Studio：研究观察与报告阅读
+
+## 1. 产品边界
+
+Research Studio 是研究过程的只读观察窗口，不是另一个 Agent，也不代替研究引擎。研究仍由 Skill、CLI 和经过授权的执行器驱动。控制台不创建课题、不启动或停止研究、不修改证据、不批准试点，也不派发子代理。
+
+控制台允许搜索、筛选、切换阅读方式、查看详细记录、刷新读取结果和下载已有报告。这些操作只改变当前浏览状态，不改变研究状态。
+
+介绍页和 Agent MCP 的实现不属于本次重构范围。
+
+## 2. 信息架构
+
+| 入口 | 内容 | 数据权威 |
+|---|---|---|
+| 研究总览 | 本地研究与公开案例，问题、数据来源、决定、更新时间 | Project 和案例结果的只读投影 |
+| 研究详情／总览 | 当前决定、依据、适用边界、试点与评价资料 | DecisionSnapshot 及明确关联的输入 |
+| 研究详情／证据 | 可筛选 Finding、原文来源、方法学记录、数值与区间 | 当前 GraphRevision 或案例 result.json |
+| 研究详情／图谱 | 来源、发现、主张之间已经存在的关系 | 已记录的关系，不由浏览器补造连接 |
+| 研究详情／运行 | Run、阶段状态、产物、事件、实际保存的执行计划与门控记录 | 运行文件及只读事件索引 |
+| 研究详情／版本 | 已提交版本链、决定快照、KnowledgeGap、研究迭代 | Graph HEAD 的父版本链 |
+| 报告阅览室 | 五主题、摘要／全文、中英文、独立 HTML | 实际生成并通过数据门控的报告 |
+| 系统迭代 | Skill Autoevolve 实验与保留／拒绝原因 | 独立的系统实验记录 |
+| 流程导览 | 三种工作流、九阶段、角色与状态权威 | 项目现有科学协议 |
+
+本地研究和案例库有独立标记。合成案例必须保留其数据来源标识，不能与真实人工整理文献混为一谈。统计数字表示已记录条目，不暗示独立研究数量、科学质量或真实业务收益。
+
+## 3. 三条用户工作流
+
+### Evidence Review：先理解已有证据
+
+研究问题 → Frame → Retrieve → Extract → Challenge → Audit → Adjudicate。
+
+控制台依次帮助回答：研究边界是什么，找到哪些来源，提取了什么结果，哪些反证存在，质量和直接性有什么限制，当前决定依据什么成立。
+
+### Decision & Pilot：把不确定性变成可验证问题
+
+DecisionSnapshot → Applicability → 有证据依据的 KnowledgeGap → Intervene。
+
+PILOT 不是“先试试”的泛泛建议。其对象、对照、结局、时间和停止条件应来自引擎已有产物。没有产物就显示未提供，不由前端自动补全。
+
+### Evaluate & Update：新数据回来以后重新判断
+
+实际分析结果 → 经校验的 Finding → 新 GraphRevision → 新 DecisionSnapshot。
+
+新证据不必改变决定标签；它可能只改变适用边界、确定性或下一步研究方向。旧版本必须保留。控制台显示真实变化，不为了形成漂亮的进度曲线而制造进展。
+
+### 两种迭代不能混淆
+
+研究迭代针对一个现实问题，更新项目证据；Skill Autoevolve 针对研究系统本身，修改并评估候选实现。因此二者分开显示，不共享一个“成功率”或一条版本时间线。
+
+Protocol Stage、Scientific Role、Capability、Worker 和 Model 是不同概念。九阶段不等于九个子代理。实际派发结果只在对应 Run 保存了执行记录时显示。
+
+## 4. 科学数据的展示规则
+
+1. 图谱优先读取 Graph HEAD 指向的已提交版本，并沿 parent_revision 还原历史；游离版本目录不算已提交历史。
+2. 决定绑定的 graph_revision 与当前 HEAD 不同时，明确标记过期，不能表现为当前有效裁决。
+3. `0.0` 是合法数值，不等同于缺失。布尔值、NaN、Infinity 和不可解析内容不能转换成效应量。
+4. 缺失、仅一侧存在或倒置的置信区间有不同标记；不填默认标准误，不把未知画成零。
+5. 浏览器不计算合并效应量，不平均不同研究、不同结局或不同量纲。森林图按指标、结局和时间点分组；未知指标分开展示。
+6. Finding 的效应方向不等于其对 Claim 的支持／反驳关系；同一 Finding 对不同 Claim 的关系可以不同。
+7. 报告字段缺失时显示缺失，不填入固定案例的百分比、显著性、风险或教学方案。
+8. 研究正在更新时，如果读取前后的 Graph HEAD 不一致，本次投影失败并允许重试，不返回混合版本。
+9. 事件和产物索引以只读 SQLite 连接访问；页面读取不能初始化工作区、修复数据库或创建研究文件。
+10. 相同内容可复用内容哈希，但项目／运行／产物类型的关联身份必须独立，避免跨项目提交后产物消失。
+
+## 5. 五主题：同一事实，五种阅读气质
+
+| 主题 | 保留的视觉身份 | 阅读重点 |
+|---|---|---|
+| Claude Research | 暖纸色、赤陶强调、舒展阅读 | 默认研究阅读和决定依据 |
+| Academic Paper | 论文式排版、克制边框、正式层级 | 方法、来源、全文与打印 |
+| DataLab | 浅色分析工作台、紧凑数据密度 | 证据比较、筛选、图表 |
+| DataLab Dark | 深色分析工作台 | 长时间查看数据与证据 |
+| Presentation / Judge | 深色、强层级、重点突出 | 快速抓住问题、边界与下一步 |
+
+共同阅读层包括：固定工具条、阅读进度、摘要目录、完整报告目录、证据筛选、展开细节、来源链接、键盘焦点、手机布局、减少动画偏好与打印样式。
+
+主题在生成时确定，独立报告内只切换语言与摘要／全文。控制台选择另一主题时加载另一份已生成报告；不存在的主题不伪装成可用。
+
+报告是独立 HTML，不依赖外部 CDN 才能阅读。嵌入阅览室采用隔离 iframe；原始 HTML 下载后保留阅读工具。主题变化不能改变来源、数值、结论和适用范围。
+
+完整双语输入可在构建阶段批量生成五主题。缺少输入的历史案例仍可查看原始证据，主题显示“尚未生成”；不得为了凑齐展示而伪造翻译或科学字段。
+
+## 6. 前端与后端分工
+
+```text
+studio/src                    React + TypeScript 源码
+        ↓ npm run build
+web/studio                    可直接分发的静态资源
+        ↓
+Python 本地服务 / GitHub Pages
+```
+
+前端负责阅读状态、导航和交互。`engine/studio_read_model.py` 负责受限只读投影。研究引擎继续独立管理科学状态。
+
+本地 API：
+
+```text
+GET /api/studio/catalog
+GET /api/studio/projects/<key>
+GET /api/studio/projects/<key>/report?theme=<theme>
+GET /api/studio/evolution
+```
+
+其中 `example--...` 和 `project--PRJ-...` 是两个不同命名空间。文件路径、主题名、报告名均受约束；不能把任意本地路径传给服务读取。
+
+生产控制台只发送读取请求。服务不提供研究变更接口。请求失败、内容格式错误和报告不存在都有明确界面状态；不会把 iframe 的 load 事件当作报告成功的证明。
+
+## 7. 本地使用、开发与静态部署
+
+### 完整分发包使用
+
+```bash
+python3 scripts/dashboard_server.py --host 127.0.0.1 --port 8765
+```
+
+打开本地 `/studio/`。分发包包含构建后的资源，不要求用户安装 Node。
+
+本地项目根目录由 `EDUEVIDENCE_HOME` 指定。未创建本地研究时案例库仍可阅读，页面不会代替引擎创建工作区。
+
+### 前端开发
+
+```bash
+cd studio
+npm ci
+npm run typecheck
+npm run build
+```
+
+### 报告和静态站
+
+```bash
+python3 scripts/build_report_variants.py
+python3 scripts/build_gh_pages.py
+```
+
+静态导出只包含仓库内公开案例，不读取或打包个人研究目录、运行历史、外部实验目录或拒绝的候选代码。静态模式没有本地操作能力，也不假装正在连接实时研究。子路径部署通过相对资源地址及 hash 导航支持。
+
+### 分发包
+
+```bash
+bash packaging/make_upload.sh
+```
+
+构建阶段生成经过门控的报告和完整资源清单。最终上传包不包含 node_modules、前端开发工具、测试材料或私人研究历史。
+
+## 8. 验证要求
+
+Python 验证覆盖：只读副作用、零值与区间状态、跨项目产物关联、路径约束、陈旧决定、版本链、公开导出的隐私边界和 HTTP 拒绝行为。
+
+TypeScript 编译与 Vite 构建覆盖组件和资源依赖。Playwright 在真实 HTTP 服务上验证项目导航、筛选、详情关闭与焦点恢复、图谱选择、真实运行夹具、报告切换、独立下载、API 失败、静态子路径部署和 320／390／768／1440 像素布局。报告还验证五主题的摘要／全文、中英文和键盘可达性。
+
+自动可访问性检测和截图检查相互补充。自动规则通过不等于完整的人工可访问性认证，必须同时查看实际构图、文字密度和图表解释。
+
+验证状态以当前 PR 对应提交的 CI 结果为准，不沿用旧提交的绿灯。
+
+## 9. 设计参考与复用边界
+
+- Linear：低噪声侧栏、清晰的项目层级与重点阅读。参考 https://linear.app/now/how-we-redesigned-the-linear-ui 。
+- Langfuse：运行追踪与产物的层级组织。参考 https://github.com/langfuse/langfuse 。
+- Evidence：数据驱动报告与静态交付。参考 https://github.com/evidence-dev/evidence 。
+- OpenStatus：状态观察与故障表达，仅参考交互思想，不复制 AGPL 项目的实现。参考 https://github.com/openstatusHQ/openstatus 。
+- Vite：传统后端接入和静态部署。参考 https://vite.dev/guide/backend-integration 与 https://vite.dev/guide/static-deploy 。
+- WCAG Reflow：正文重排与数据表格的局部二维滚动。参考 https://www.w3.org/WAI/WCAG22/Understanding/reflow.html 。
+
+本实现使用自主编写的布局与组件，不移植参考产品代码或品牌资源。第三方依赖许可证由分发清单单独记录。

package/docs/sciverse-api.md

@@ -0,0 +1,125 @@
+# Sciverse 检索通道（API 契约存档）
+
+本条记录 EduEvidence 接入 Sciverse 开放平台所用的最小契约，依据官方 `openapi.yaml` **v0.14.2**（`opendatalab/Sciverse-Agent-Tools`）整理。目的是让检索链在**没有网络**时也能被复核：字段名、错误码、限制与语义都在这里，代码变更需同步更新本文件。
+
+## 1. 基本信息
+
+| 项 | 值 |
+|---|---|
+| Base URL | `https://api.sciverse.space` |
+| 鉴权 | `Authorization: Bearer <SCIVERSE_API_TOKEN>`（HTTP Bearer） |
+| Token 来源 | 控制台 Tokens 页；同账号可通用于 Sciverse / DianShi / SeqStudio 已开通能力 |
+| 实现 | `retrieval/sciverse.py`（stdlib-only） |
+| 通道类型 | key-based 学术通道，在 `MultiSearchRouter.academic_key_providers` 中优先于零配置学术通道 |
+| 无 token 行为 | 通道静默失活（`SCIVERSE_UNAVAILABLE`），零配置通道继续工作 |
+
+## 2. 使用的四个端点
+
+### 2.1 `POST /meta-search` — 结构化元数据检索
+
+用于 Source 级命中：标题、作者、摘要、期刊、年份、DOI。
+
+- 请求（所用子集）：`collection`（papers/authors/sources）、`query`（BM25）、`filters_advanced[]`（`{field, operator, value}`）、`page`、`page_size`（≤50）。
+- 响应：`results[]`（注意是 `results`，不是 `hits`）、`total_count`、`page`、`page_size`、`total_pages`、`next_cursor`。
+- 关键字段：`unique_id`（元数据全局唯一 ID，**始终存在**）、`doc_id`（全文内容哈希 sha256，**仅当存在全文**）、`is_content_accessible`、`doi`、`author[].name`、`publication_published_year`、`publication_venue_name_unified`。
+- 过滤操作符：`FILTER_OP_EQ/NE/GT/GTE/LT/LTE/IN/NIN/CONTAINS/MATCH/MATCH_PHRASE`；`doi` 用 `EQ`（服务端去 `doi.org` 前缀并转小写后精确匹配）。
+- 排序与加权：`sort_by_year`（`auto` 在带 query 时保留相关性排序）、`freshness_boost` / `impact_boost` / `language_affinity`（`NONE|MILD|STRONG`，仅在 query 非空时生效；加权生效时**不支持深翻页**）。
+
+### 2.2 `POST /agentic-search` — 自然语言语义检索（RAG）
+
+用于 chunk 级**定位子**：
+
+- 请求：`query`（1–200 字最佳）、`top_k`（1–100）、`mode`（`fast` ~200ms / `balanced` ~600ms / `quality` ~2–4s）、可选 `filters`、`source_types`（`web` / `pdf`）。
+- 响应：`hits[]`，每条含 `chunk_id`、`doc_id`、`score`、`title`、`offset`（**Unicode 码点**，可直接作为 `/content` 的 offset）、`page_no`、`source_type`、`chunk`、`abstract`。
+- **限制**：`balanced` 模式服务端约截断至 50 条；同一篇论文最多返回约 3 个 chunk，因此高 `top_k` 需要足够多的不同论文。
+- **软过滤语义**：`filters` 在召回阶段与语义检索同时下推，但 chunk 侧元数据缺失的文档不会被排除（按年份过滤时，缺年份的 chunk 仍可能返回）。结论表述必须写"近似范围"；需要严格范围时改用 `meta-search` 的结构化过滤并核对返回记录。
+- 唯一的硬过滤字段是 `doc_id`（命中绝不越出给定集合；去重后上限默认 1000）。
+
+### 2.3 `GET /content` — 按码点区间读原文
+
+把 chunk 定位子扩展为可抽取的正文：
+
+- 参数：`doc_id`（必填）、`offset`（默认 0）、`limit`（默认 4096，服务端上限 524288，超出静默钳制）。
+- **必须显式传 `offset`**：省略时服务端返回整篇全文并忽略 `limit`。
+- 响应：`text`、`bytes_returned`（UTF-8 字节数，仅供参考）、`next_offset`（下一段起始码点，翻页用它而非字节数）、`more`。
+- 单位：`offset` / `limit` 均以 **Unicode 码点**计，与 Python `len` 一致，不是字节。
+
+### 2.4 `POST /meta-paper-relations` — 引用 / 被引 / 相关工作
+
+用于引文链审计（`SearchQuery.purpose = citation_chain`）：
+
+- 请求：`unique_id`（**不是 doc_id**）、`relation`（`CITATIONS` 被引 / `REFERENCES` 参考文献 / `RELATED_WORKS`）、`page`、`page_size`（≤200）。
+- 响应：`items[]`（`id` / `id_type` / `title`）、`total_count`、`page`、`page_size`、`total_pages`。
+- 方向语义：`CITATIONS` 是"谁引用了我"，`REFERENCES` 是"我引用了谁"，两者相反。
+- **上限**：关系数超 10000 返回 `429`；`page × page_size` 超 10000 返回 `400`。两种情况改用 `meta-search` 的 `references_unique_id` 反查（支持深翻页与任意排序）。
+- `total_count` 只统计库内命中，与论文自身 `citation_count` 可能有约 ±1% 差异。
+
+## 3. 错误处理与状态映射
+
+`retrieval/sciverse.py` 把 HTTP 与网络异常统一映射为**定型状态**，绝不把异常抛进检索管道：
+
+| HTTP / 情形 | 状态 | 管道行为 |
+|---|---|---|
+| 200 | `ok` | 正常解析 |
+| 401 / 403 | `SCIVERSE_UNAUTHORIZED` | 记录尝试，切换其他通道 |
+| 400 / 404 / 429 | `SCIVERSE_BAD_REQUEST` | 同上（429 视为配额/上限耗尽） |
+| 502 / 503 / 5xx | `SCIVERSE_UPSTREAM_ERROR` | 同上 |
+| 超时 / DNS / TLS | `SCIVERSE_NETWORK_ERROR` | 同上 |
+| 未配置 token | `SCIVERSE_UNAVAILABLE` | 通道失活，不产生请求 |
+
+错误信息只保留服务端 `ApiError.message` 或状态描述，**不携带 Authorization 头或 token 片段**。
+
+## 4. 在证据链中的位置（RULE 2 的机器化）
+
+```text
+/meta-search      → Source 级命中（DOI → https://doi.org/<doi>；无 DOI 则标记 needs_manual_location）
+/agentic-search   → chunk 定位子（doc_id + offset）→ 写入 chunks.jsonl，标注 discovery_only_requires_content_fetch
+/content          → 按定位读原文 → 经 retrieval/validate.py 校验门 → 才可进入 Extract
+/meta-paper-relations → 引文链记录（写入审计导出，供筛选与饱和判断）
+```
+
+要点：**chunk 不是证据**。它是发现线索；只有 `/content` 读到的正文通过校验门（长度、错误页、登录页、验证码、标题匹配等）之后，才允许被抽取为 Evidence Object。这条纪律由 `retrieval/fetch.py::fetch_sciverse_content()` 实现，产出与 `FetchResult` 同形，下游零改动。
+
+引用目标永远是论文本身（DOI / `unique_id`），**不是 Sciverse** —— 它是读取路径，不是来源。
+
+## 5. 配置
+
+```bash
+export SCIVERSE_API_TOKEN=sv-...        # 必需；未设置时通道失活
+# 可选：指向测试环境
+export SCIVERSE_BASE_URL=https://api.sciverse.space
+```
+
+宿主侧如已安装官方 Skill / MCP，可作为**补充**而非替代（本仓库的实现不依赖它）：
+
+```bash
+npx skills add https://sciverse.space
+# 或 MCP server
+npm install -g sciverse-mcp-server
+export SCIVERSE_API_TOKEN=sv-...
+```
+
+## 6. 验证
+
+```bash
+# 契约与降级行为（离线，mock HTTP）
+python -m pytest tests/test_sciverse_channel.py -q
+
+# 真实连通冒烟（需 token）
+python - <<'PY'
+from retrieval import sciverse as s
+print('available:', s.available())
+print('meta:', s.meta_search('generative AI coding assistants learning outcomes', limit=3).status)
+r = s.agentic_search('unguarded GPT-4 access harms independent exam performance', top_k=3)
+recs = s.chunk_records(r)
+print('chunks:', len(recs))
+if recs:
+    c = s.read_content(recs[0]['doc_id'], offset=recs[0]['offset'], limit=600)
+    print('content:', c.status, len(c.data.get('text') or ''))
+PY
+```
+
+## 7. 合规
+
+配额、限速、缓存与署名规则统一见 `references/retrieval-compliance.md`（§3 Sciverse 附加约定）。规范漂移时以官方 `openapi.yaml` 为准，并同步更新本文件与 `references/retrieval-protocol.md`。
+

package/eduevidence_cli.py

@@ -1,18 +1,23 @@
 #!/usr/bin/env python3
-"""eduevidence_cli.py — console-script shim for `eduevidence`.
-
-Installed via pyproject.toml [project.scripts]: the real implementation lives
-in scripts/orchestrator.py; this module only puts scripts/ (and the repo root
-for retrieval/integrations packages) on sys.path and forwards to it.
-
-Usage:
-    eduevidence run --question "..." --depth deep
-    eduevidence resume --run-id <id>
-    eduevidence status --run-id <id>
-    eduevidence list
-    eduevidence gate --run-id <id>
+"""Console-script shim for ``eduevidence``.
+
+The legacy orchestrator remains authoritative for existing commands. vNext adds
+only two intercepted command domains:
+
+    eduevidence research auto ...
+    eduevidence evolve ...
 """
 import sys
+
+MIN_PYTHON = (3, 10)
+
+if sys.version_info < MIN_PYTHON:
+    import platform
+    sys.stderr.write(
+        f"EduEvidence requires Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or newer; "
+        f"this interpreter is {platform.python_version()}.\n"
+        "Install a supported Python and re-run, or set PYTHON to one.\n")
+    raise SystemExit(2)
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent
@@ -20,7 +25,18 @@ for _p in (str(ROOT / "scripts"), str(ROOT)):
     if _p not in sys.path:
         sys.path.insert(0, _p)
 
-from orchestrator import main  # noqa: E402
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if len(args) >= 2 and args[:2] == ["research", "auto"]:
+        from vnext_cli import research_auto
+        return research_auto(args[2:])
+    if args and args[0] == "evolve":
+        from vnext_cli import evolve
+        return evolve(args[1:])
+    from orchestrator import main as legacy_main
+    return legacy_main(args)
+
 
 if __name__ == "__main__":
     sys.exit(main())

package/engine/_resources.py

@@ -0,0 +1,13 @@
+"""Locate immutable bundled resources in a checkout, Skill or installed wheel."""
+from pathlib import Path
+import sys
+
+
+def resource_root() -> Path:
+    package_root = Path(__file__).resolve().parent.parent
+    candidates = (package_root, package_root / "share" / "eduevidence",
+                  Path(sys.prefix) / "share" / "eduevidence")
+    for candidate in candidates:
+        if (candidate / "SKILL.md").is_file():
+            return candidate
+    return package_root

package/engine/autoevolve/__init__.py

@@ -0,0 +1,3 @@
+from .core import *
+from .git_workspace import GitWorkspace
+from .runner import DailyEvolutionRunner