eduevidence 6.0.0 → 6.3.0

package/docs/j-ev-experimental.md

@@ -0,0 +1,250 @@
+# Jev 生态实验模式（Experimental Jev / SemDecide Tier-0）
+
+> **实验性加速层，不是科学门。** Tier-0（screen / rerank / extract / classify / verify）
+> 只做窄域类型化判断，**不替代** `scripts/pre_verdict_gate.py`、Skeptic 九项检查、
+> 方法学审计与 Tribunal。不确定 / 非法结果 **fail-closed** 升级大模型。
+>
+> 入口开关：`--experimental <0|1|2|3>` 或 `EDU_EXPERIMENTAL_JEV=<mode>`。
+> 密钥仅存 `~/.eduevidence/env`（`AI_GATEWAY_API_KEY` + `JEV_PROVIDER=vercel`，可选
+> `TYPESAFE_API_KEY`；或 FreeJev：`FREEJEV_API_KEY` + `JEV_PROVIDER=freejev`），
+> **禁止写入仓库**。
+
+## 1. 定位
+
+| 组件 | 实现 | 上游 |
+|---|---|---|
+| `integrations/jev_mcp.py` | detect → approval → urllib 调 Vercel AI Gateway `typesafe-ai/jev` | TypeSafe System One / `@jkudish/jev-mcp` |
+| `integrations/semantic_decide.py` | subprocess `semdecide is / filter / choose` | [sharziki/semdecide](https://github.com/sharziki/semdecide) |
+| `engine/capabilities.py` | 注册 5 个实验能力（`experimental_capability_registry()`；默认科学注册表不含它们，避免协议角色门误伤） | 本仓库能力注册表 |
+| `skill/workflows/experimental-jev.md` | 模式 / 九阶段映射 / fail-closed | Skill 工作流覆盖层 |
+
+原则（与 agent-mcp 一致）：**检测 → 推荐 → 用户确认 → 调用 → 降级**。不迁移、不复制
+上游实现；上游不可用时整体退回 Platform Native / mode 0，科学协议不变。
+
+## 2. 启用方式
+
+```bash
+# 0) 密钥（本地，勿提交）
+# ~/.eduevidence/env
+#   # Vercel AI Gateway 路径
+#   export AI_GATEWAY_API_KEY=...
+#   export JEV_PROVIDER=vercel
+#   # 或 FreeJev 路径
+#   export FREEJEV_API_KEY=...
+#   export JEV_PROVIDER=freejev
+
+# 1) 检测
+python3 integrations/jev_mcp.py --experimental 3
+python3 integrations/semantic_decide.py --experimental 3
+
+# 2) 用户确认门 → ~/.eduevidence/jev_mcp_approval.json
+python3 integrations/jev_mcp.py --experimental 3 --approve
+
+# 3) 运行时打开 overlay（宿主 CLI 用 --enhancement 选择；写入 run 的 intake.json）
+eduevidence run --question "..." --run-id <id> --enhancement jev --enhancement semdecide
+# 检测类 CLI 用模式号：--experimental <0|1|2|3>，或 export EDU_EXPERIMENTAL_JEV=3
+```
+
+| Mode | 名称 | 后端 |
+|---:|---|---|
+| 0 | standard | 仅大模型（默认，无 `--experimental`） |
+| 1 | jev-mcp | FreeJev / Vercel Gateway urllib **或** 文档化 MCP |
+| 2 | semdecide | `semdecide is / filter / choose` |
+| 3 | hybrid | 1 + 2 |
+
+### Provider（Mode 1 / 3）
+
+| `JEV_PROVIDER` | 密钥 | Decide 端点 | 备注 |
+|---|---|---|---|
+| `freejev` | `FREEJEV_API_KEY` | `https://freejev.org/api/v1/decide` | 仅 `FREEJEV_API_KEY` 时可自动选中 |
+| `vercel`（默认） | `AI_GATEWAY_API_KEY`（或 `TYPESAFE_API_KEY`） | `https://ai-gateway.vercel.sh/typesafe/v1/systemone` | `model=typesafe-ai/jev` |
+
+MCP 备选（不自动 spawn，仅文档化）：
+
+```bash
+# FreeJev MCP
+#   https://freejev.org/mcp   + FREEJEV_API_KEY
+# npx 包路径
+claude mcp add jev -- npx -y @jkudish/jev-mcp
+# 通用 JSON：npx -y @jkudish/jev-mcp + TYPESAFE_API_KEY / AI_GATEWAY_API_KEY
+python3 integrations/jev_mcp.py --mcp-guide
+```
+
+**FreeJev `request_id` 不重试。** Decide 调用的 `request_id` 是幂等键：同一
+`request_id` **禁止重试**（超时 / 5xx / 未知结果一律不重发）。本调用
+fail-closed 升级大模型；若业务上必须再问一次，使用**新的** `request_id` 发起
+新调用，并单独记录 provenance。
+
+## 3. Tier-0 API 列表
+
+传输：`POST` 到 provider decide 端点（Vercel System One 或 FreeJev），
+`Authorization: Bearer $AI_GATEWAY_API_KEY` / `$FREEJEV_API_KEY`，
+`model=typesafe-ai/jev`。
+请求体 TypeSafe System One：`{ model, state, questions }` → `{ model, answers, usage }`。
+FreeJev 另带 `request_id`（见上：**不重试**）。
+
+| # | Python API | capability_id | MCP 工具 | SemDecide 对应 | 问题形态 | 默认阈值 |
+|---|---|---|---|---|---|---|
+| 1 | `jev_mcp.screen(text, purpose)` | `content_screen` | `jev_screen` | — | 3× Noul：injection / substance / relevance | `block_at=0.75`, `review_at=0.25` |
+| 2 | `jev_mcp.rerank(query, candidates)` | `semantic_rerank` | `jev_rerank` | — | 1× Noul / candidate | `auto_accept=0.70` |
+| 3 | `jev_mcp.extract(document, fields)` | `field_extract` | `jev_extract` | — | 1× Choice / field（regex 候选 + `none_of_them`） | `auto_accept=0.80`, `margin=0.40` |
+| 4 | `jev_mcp.classify(items, classes)` | `classify_check` | `jev_classify` | `choose` 可路由 | 1× Choice / item | `auto_accept=0.85`, `margin=0.50` |
+| 5 | `jev_mcp.verify(claims, evidence)` | `claim_verify` | `jev_verify` | `is` 可预筛 | 1× Choice / claim：supports / contradicts / says_nothing | `auto_accept=0.80` |
+
+统一入口：`jev_mcp.safe_call(capability_id, ...)`（先过 approval 门）。
+
+SemDecide 封装（exit 2/3/4 → 升级大模型）：
+
+| API | CLI | 用途 |
+|---|---|---|
+| `semdecide.is_predicate(text, predicate)` | `semdecide is` | 语义谓词 |
+| `semdecide.filter_records(records, predicate)` | `semdecide filter` | JSONL 语义过滤（保序） |
+| `semdecide.choose_route(text, question, options)` | `semdecide choose` | 命名选项路由 |
+
+### 状态与 fail-closed（与 `integrations/semantic_decide.py` 对齐）
+
+Jev / Tier-0：
+
+| 状态 | 含义 | 管道行为 |
+|---|---|---|
+| `ok` + `action/auto` | 可自动采用（仍不是科学门） | 记录 provenance，继续阶段 |
+| `review` / `not_found` / `JEV_INVALID_RESPONSE` | 低置信或非法答案（envelope 缺 `answers` 等） | **升级大模型**；extract 的 `review` 值不得当作已抽取 |
+| `JEV_APPROVAL_REQUIRED` | 无/错 approval | 不发网络请求 |
+| `JEV_UNAVAILABLE` | 无密钥 / 无可用传输 | 本调用升级大模型；hybrid 可切 mode 2 切片 |
+| `JEV_PROVIDER_ERROR` | 上游失败（HTTP 401/403/429/529/5xx） | 本调用升级大模型；FreeJev **`request_id` 不重试** |
+
+SemDecide（`EXIT_MEANINGS` / `ESCALATE_EXIT_CODES={2,3,4}`）：
+
+| exit / status | `EXIT_MEANINGS` | 管道行为 |
+|---|---|---|
+| `0` | `true/selected/match` | 语义结果可用 |
+| `1` | `false/no match` | 语义结果可用；`filter` 的 exit 1 **不**单独升级 |
+| **`2`** | `invalid input` | 修输入重跑，或整段决策**升级大模型**（`escalate_plan`） |
+| **`3`** | `uncertain` | **升级大模型 / 人工**；禁止强行 true/false |
+| **`4`** | `provider failure` | **升级大模型**（仅本调用）；记录 attempt |
+| `SEMDECIDE_UNAVAILABLE` | binary 缺失 / spawn 失败 | **升级大模型**（`requires_llm_escalation`） |
+| `SEMDECIDE_TIMEOUT` | 超时 | **升级大模型**（`result.escalate=ESCALATE_TO_LLM`） |
+
+`screen` 的 recommendation（pass / review / block / skip）仅为咨询；拦截执行权在调用方。
+
+## 4. 阈值
+
+| 参数 | 默认 | 调节建议 |
+|---|---:|---|
+| `screen_block_at` | 0.75 | 注入概率 ≥ 则 block（咨询） |
+| `screen_review_at` | 0.25 | 注入概率 ≥ 则 review |
+| `verify_auto_accept` | 0.80 | 关系裁决 confidence ≥ 才 `auto` |
+| `classify_auto_accept` | 0.85 | top 概率门槛 |
+| `classify_minimum_margin` | 0.50 | 冠亚军差门槛（二者同时满足才 auto） |
+| `extract_auto_accept` | 0.80 | 字段挑选 confidence |
+| `extract_minimum_margin` | 0.40 | 候选差门槛；失败 → `review` |
+| `rerank_auto_accept` | 0.70 | 相关 Noul 门槛 |
+| SemDecide `--threshold` | 0.70 | `is` / `filter` |
+| SemDecide `--min-confidence` | 0.70 | `choose`；低于则 exit 3 |
+| SemDecide `--uncertainty-margin` | 0.0 | 边缘区不强行二值化 |
+
+阈值是起点（TypeSafe cookbook 基线），**先在自有数据上校准再强制**。
+
+## 5. 九阶段映射（加速点）
+
+`frame → retrieve → extract → challenge → audit → adjudicate → applicability → intervene → evaluate`
+
+| 阶段 | Jev Tier-0 | SemDecide | 不变的科学门 |
+|---|---|---|---|
+| Frame | — | `choose` 可选 | frame schema |
+| Retrieve | screen / rerank / classify | `filter`, `is` | 检索计划 + 反方检索 + Fetch/Validate |
+| Extract | extract / classify | `is` 预检 | Evidence Objects、task ≠ learning |
+| Challenge | **verify 仅辅助** | `is` 辅助 | **Skeptic 九项检查** |
+| Audit | verify 辅助 | `is` 预筛 | 方法学审计 + guard |
+| Adjudicate | —（禁止 Tier-0 定裁决） | — | **Pre-Verdict Gate** + 四态裁决 |
+| Applicability | classify 可选 | `choose` 可选 | 人群/条件/排除/不确定性 |
+| Intervene | — | — | intervention_design |
+| Evaluate | — | — | evaluation_design / data_validation |
+
+完整矩阵见 `skill/workflows/experimental-jev.md`。
+
+## 6. 加速比口径（speedup）
+
+只比较**同一问题、同一 Complexity Gate、同一九阶段协议**下 mode 0 基线 vs 实验模式。
+
+| 指标 | 定义 | 统计范围 |
+|---|---|---|
+| `T_stage` | 单阶段 wall-clock（s），从进入阶段到产物过 schema/gate | 仅计 **gate 通过** 的阶段 |
+| `T_run` | Frame→Applicability（或声明的阶段子集）累计 | 同上 |
+| `speedup_stage` | `T_stage(mode0) / T_stage(exp)` | per stage |
+| `speedup_run` | `T_run(mode0) / T_run(exp)` | per run |
+| `cost_tokens` | 主模型 + Tier-0 `usage.input_tokens/output_tokens` | 双方同口径合计 |
+| `escalation_rate` | fail-closed 升级次数 / Tier-0 调用次数 | 实验侧 |
+| `gate_pass_rate` | 过科学门的阶段数 / 执行阶段数 | 双方 |
+
+规则：
+
+1. **质量门优先**：`gate_pass_rate(exp) < gate_pass_rate(mode0)` 时 speedup **无效**（质量退化不算加速）。
+2. Tier-0 调用耗时与 token 计入实验侧成本，不得只计大模型。
+3. 升级到大模型的调用耗时计入实验侧（含往返），避免“看起来快”。
+4. 未过 gate / 中断 / 人工改写的 run **不进入** speedup 均值，单独列表。
+5. 报告格式：每 run 一行 `{run_id, mode, T_run, speedup_run, cost_tokens, escalation_rate, gate_pass_rate}`。
+
+示例（示意，非承诺值）：
+
+| run | mode | T_run | speedup_run | escalations | gate_pass |
+|---|---:|---:|---:|---:|---:|
+| ai-cs1-b | 0 | 3120s | 1.00× | — | 7/7 |
+| ai-cs1-j | 3 | 1810s | 1.72× | 4/38 | 7/7 |
+
+## 7. A/B 验收
+
+| 项 | 通过条件 |
+|---|---|
+| 科学完整性 | 挑战阶段九项 Skeptic 全跑；Adjudicate 前 `pre_verdict_gate` 必跑且结论不被 Tier-0 覆盖 |
+| 质量非劣 | `gate_pass_rate` 不低于基线；Pre-Verdict critical 失败数不增加 |
+| 校准 | `verify`/`classify` 的 auto 集抽样人工一致率 ≥ 约定阈值（建议 ≥ 0.9） |
+| Fail-closed | 抽检 100% 的 SemDecide exit 2/3/4、`SEMDECIDE_TIMEOUT`/`SEMDECIDE_UNAVAILABLE` 与 `JEV_INVALID_RESPONSE`/`JEV_PROVIDER_ERROR` 都有升级记录 |
+| 密钥卫生 | 仓库与 run 产物无 `AI_GATEWAY_API_KEY` / `TYPESAFE_API_KEY` / `FREEJEV_API_KEY` 明文 |
+| FreeJev 幂等 | 抽检无同一 `request_id` 重试；失败一律升级大模型 |
+| 可复现 | mode、approval `tools_hash`、阈值、上游 model id 写入 run 元数据 |
+| 加速有效 | `speedup_run ≥ 1.2`（目标，可调）且质量非劣；否则保持 mode 0 |
+
+## 8. 降级路径
+
+```
+--experimental 3 (hybrid)
+  ├─ provider key + jev_mcp_approval.json → Tier-0 screen/rerank/extract/classify/verify
+  │    (FreeJev: FREEJEV_API_KEY + JEV_PROVIDER=freejev；request_id 不重试)
+  ├─ semdecide on PATH                  → is/filter/choose
+  ├─ exit 2/3/4 / SEMDECIDE_TIMEOUT
+  │    / JEV_INVALID_RESPONSE / JEV_PROVIDER_ERROR
+  │                                    → 单次升级大模型（fail-closed）
+  ├─ Jev 不可用                         → 仅 SemDecide（mode 2 切片）
+  ├─ semdecide 不可用                   → 仅 Jev（mode 1 切片）
+  └─ 双不可用 / 未开 --experimental     → mode 0 standard
+
+科学门永不降级：Pre-Verdict Gate / Skeptic 九项 / 方法学审计 / Tribunal 始终在宿主路径执行。
+```
+
+## 9. API 速查（代码）
+
+```python
+from integrations.jev_mcp import (
+    detect_jev_mcp, write_approval, load_approval,
+    screen, rerank, extract, classify, verify, safe_call,
+    resolve_experimental_mode, npx_mcp_guide,
+)
+from integrations.semantic_decide import (
+    detect_semdecide, is_predicate, filter_records, choose_route,
+    requires_llm_escalation, escalate_plan,
+)
+
+mode = resolve_experimental_mode(3)          # 0..3
+approval = load_approval()                   # ~/.eduevidence/jev_mcp_approval.json
+verdict = safe_call("claim_verify", claims, evidence, approval=approval)
+if verdict.get("escalate"):
+    ...  # fail-closed → large model
+```
+
+## 10. 变更记录
+
+| 日期 | 内容 |
+|---|---|
+| 2026-09-22 | 首版：Tier-0 五能力、approval 门、mode 0–3、阈值、加速比口径、A/B 验收、降级路径 |
+| 2026-09-22 | 收口：FreeJev（`FREEJEV_API_KEY` / `JEV_PROVIDER=freejev` / MCP `https://freejev.org/mcp` / `request_id` 不重试）；fail-closed 表与 `semantic_decide.py` 对齐 |

package/docs/orchestration-role-model.md

@@ -146,7 +146,7 @@ Retriever 永远等于 OMP
 当前仓库有：
 
 ```text
-education-planner
+research-planner
 evidence-retriever
 evidence-analyst
 skeptic

package/docs/release-closeout/README.md

@@ -1,4 +1,4 @@
-# EduEvidence 6.0 发布收尾
+# EduEvidence 6.1 发布收尾
 
 本目录记录本地确定性验证与实际前端验收，不代表真实模型研究已通过。完整提交目录为 `dist/eduevidence-submission/`，根目录即 `SKILL.md`；交付目录而非压缩包。
 

package/docs/reproducibility.md

@@ -0,0 +1,138 @@
+# EduEvidence 复现指南
+
+> **复现范围声明（v5.2.0 起，R6 口径收敛）**：可复现承诺分两层，不得混谈。
+>
+> 1. **确定性层（完全可复现）**：schema 校验、置信度计算（规则化公式）、pre-verdict gate、
+>    meta-analysis/robustness 数学、报告烘焙与哈希链——同一输入在同一版本上逐字节可复现；
+>    本指南的三步走覆盖这一层。
+> 2. **LLM 层（有边界可复现）**：检索、抽取、挑战、裁决等依赖外部 LLM 的阶段不是逐字节
+>    确定的。其复现条件 = 模型版本 + temperature + prompt 版本 三者同时固定；当前仓库通过
+>    run manifest 记录这三项（如 `benchmarks/empirical/run-empirical-01/manifest.json` 的
+>    `temperature: 0.0`），但不承诺跨模型供应商的结果一致。
+>
+> 引擎对"证据是否真实"的立场：所有示例包在 `result.json.meta.data_origin` 与报告头徽章中
+> 如实标注数据来源（`real` / `manual_curated` / `synthetic` / `hybrid`）；引用的 DOI 经
+> `scripts/audit_dois.py` 对照 Crossref/DataCite 注册表核验（报告：
+> `benchmarks/doi-audit/report.md`）。标注 `synthetic` 的演示包不构成任何实证声明。
+
+本指南确保任何人在全新环境中都能复现 EduEvidence 确定性层的校验、测试与 Benchmark 结果。全部命令以仓库根目录 `<repo-root>`（即 pyproject.toml 所在目录）为工作目录执行。
+
+## 〇、V2 Research Engine 复现
+
+- 引擎模块 `engine/`（stdlib-only）可独立复现：`python3 -m pytest tests/test_v2_*.py`。
+- 图状态复现：`graph/HEAD` + `revisions/rev-N` 快照 + `manifest.json` 的 before/after 哈希链；同一输入 bundle 提交产生确定性哈希。
+- V1 历史产物（`examples/ai-coding-assistant/`、旧 `runs/`）不可变；`eduevidence migrate-v1 --pack <dir>` 生成新 V2 Project 且不改动源包。
+- Shared Research Library 与 Project 图同用不可变 revision 模型；快照导入记录 `library_revision/library_entity_id/content_hash/imported_at`。
+- 测试覆盖：V1 兼容基线、图原子性/孤儿 revision/HEAD 镜像分歧修复、迁移不变量、模式推荐、能力规划、synthesis 独立计数、Tribunal 政策、Gap 推导、数据集隐私门、全周期单 revision 提交、决策 diff、CLI 薄分发。
+
+## 一、环境要求
+
+- **Python**：≥ 3.10（pyproject.toml 中 `requires-python = ">=3.10"`）；
+- **pytest**：≥ 7.0（dev 依赖，安装时自动带入）；
+- 无其它强制运行时依赖：EduEvidence 本体是文档+Schema+脚本，Mode A 平台原生模式下不需要 daemon / CLI / Agent MCP；
+- 操作系统：macOS / Linux / Windows 均可；建议使用 venv 隔离环境。
+
+### 1.1 创建虚拟环境（推荐）
+
+```bash
+cd <repo-root>
+python3.11 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+```
+
+## 二、安装步骤
+
+在虚拟环境内安装本项目（含 dev 依赖）：
+
+```bash
+pip install -e '.[dev]'
+```
+
+- `-e`（editable）安装使脚本与 schema 变更即时生效，无需重装；
+- `.[dev]` 安装 `pytest>=7.0`；
+- 安装成功后可用 `python -c "import sys; print(sys.version)"` 确认版本 ≥ 3.10。
+
+## 三、运行测试
+
+```bash
+pytest
+```
+
+- 测试自动发现 `tests/` 下 `test_*.py` 文件（见 pyproject.toml `[tool.pytest.ini_options]`）；
+- 覆盖范围：schema 校验器、confidence 规则化计算、Complexity Gate 判级、benchmark 输出格式等；
+- 预期结果：全部测试通过（`addopts = "-q"` 输出简洁）。
+
+## 四、运行 Schema 验证
+
+校验某份数据是否符合对应 Schema（mandatory 字段缺失会标记为 UNSUPPORTED）：
+
+```bash
+python scripts/validate_schema.py \
+  --schema schemas/evidence.schema.json \
+  --data examples/ai-coding-assistant/evidence.jsonl
+```
+
+- `--schema`：指定任一顶层 Schema（schemas/ 下 37 个契约，跨 V1–V4 代际，如 education-frame / evidence / methodology / verdict / intervention / evaluation / report-result 等）；
+- `--data`：指定要校验的 JSON 或 JSONL 数据文件；
+- 主 Demo 示例数据位于 `examples/ai-coding-assistant/evidence.jsonl`，验证通过时应输出每条 evidence 的校验状态与 SUPPORTED/UNSUPPORTED 统计；
+- 合格线：**校验通过率 100%**，任一条未通过即非零退出码。
+
+## 五、运行 Benchmark
+
+逐题运行五条基线（B0–B4）并生成结果：
+
+```bash
+python scripts/benchmark.py --questions benchmarks/questions.jsonl
+```
+
+- `--questions`：第一版 30 题（S×10 / M×10 / L×10），每题字段为 `id`、`level`（S/M/L）、`domain`、`question`、`expected_outcomes`、`notes`（与 `validate_questions()` 校验一致）；人工金标注位于 `benchmarks/annotations/gold-<id>.json`；
+- 运行产物：每题一个 JSON，写入 `benchmarks/results/`；
+- 核心指标（Citation Support Precision、Unsupported Claim Rate、Contradiction Discovery Rate、Outcome Separation Accuracy、Scope Calibration、Intervention Evidence Alignment）由 `benchmarks/evaluator/` 对照 `benchmarks/annotations/` 计算；
+- 可选参数（如 `--ablation` 跑 A1–A7、`--repeat 5` 测稳定性）以 `python scripts/benchmark.py --help` 为准。
+
+## 六、输出产物：Research & Decision Pack
+
+每次端到端运行（Demo 或 L 级题目）产出一份双层 Research & Decision Pack：
+
+- **Visual Brief**：用于快速浏览 Decision、Outcome Separation、Evidence Tribunal、Evidence-to-Action 与关键来源。
+- **Full Report**：由当前研究内容规划为 **5–7 个动态章节**，而不是固定章节模板。
+
+完整报告必须覆盖以下语义模块；这些模块可以按研究叙事合并进同一章节，但不得遗漏：
+
+| 模块 | 内容 |
+|------|------|
+| decision | 最终决策、Confidence、可说/不可说与主要风险 |
+| scope | Education Research Frame、研究边界与决策标准 |
+| retrieval | 检索策略、来源覆盖与证据选择 |
+| outcomes | Outcome Separation：任务表现、学习、保持、迁移与风险 |
+| evidence | Claim-Level Evidence 与 Evidence Matrix |
+| quality | Methodology / Evidence Quality Audit |
+| conflicts | Skeptic / Counter-Evidence / Conflict Analysis |
+| trace | Evidence Tribunal + Claim → Evidence → Source 追溯 |
+| applicability | 适用性、外推边界与必要条件 |
+| intervention | 最小可验证干预、Guardrails 与 Stop Conditions |
+| evaluation | Baseline / Post-test / Retention / Transfer 评价方案 |
+| sources | Sources、Provenance 与附录 |
+
+Pack 的证据链始终可以从 Decision / Claim 反查到 Evidence，再追溯到 Source 与 source location；章节如何合并不改变这一追溯关系。
+
+## 七、常见问题（FAQ）
+
+| 现象 | 处理 |
+|------|------|
+| `pytest` 无测试收集 | 确认在仓库根目录运行且依赖已安装 |
+| validate_schema 报非零退出 | 逐条查看 UNSUPPORTED 记录，补齐 mandatory 字段 |
+| benchmark 输出缺失 | 检查 `benchmarks/results/` 目录可写；确认 `benchmarks/questions.jsonl` 字段完整 |
+| pip install 找不到 `[dev]` | 确认工作目录是根目录（pyproject.toml 存在） |
+| Python 版本低于 3.10 | 升级解释器或使用 pyenv 安装 ≥3.10 |
+
+## 八、端到端复现三步走
+
+```bash
+pip install -e '.[dev]'   # 1. 安装
+pytest                    # 2. 验证环境
+python scripts/validate_schema.py --schema schemas/evidence.schema.json --data examples/ai-coding-assistant/evidence.jsonl
+python scripts/benchmark.py --questions benchmarks/questions.jsonl   # 3. 复现示例与基准
+```
+
+三步全部成功即视为复现完成。

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/domains/_neutral/copy/few_shots.json

@@ -0,0 +1,21 @@
+{
+  "domain": "_neutral",
+  "states": {
+    "adopt": {
+      "zh": "",
+      "en": ""
+    },
+    "pilot": {
+      "zh": "",
+      "en": ""
+    },
+    "reject": {
+      "zh": "",
+      "en": ""
+    },
+    "insufficient_evidence": {
+      "zh": "",
+      "en": ""
+    }
+  }
+}

package/domains/_neutral/copy/framing_lexicon.json

@@ -0,0 +1,19 @@
+{
+  "domain": "_neutral",
+  "frame_enums": {
+    "zh": {},
+    "en": {}
+  },
+  "frame_fields": {
+    "zh": {},
+    "en": {}
+  },
+  "frame_subfields": {
+    "zh": {},
+    "en": {}
+  },
+  "evidence_detail_labels": {
+    "zh": {},
+    "en": {}
+  }
+}

package/domains/_neutral/copy/module_labels.json

@@ -0,0 +1,5 @@
+{
+  "domain": "_neutral",
+  "purpose": "Neutral UI labels index; companions module_labels_*.json hold the actual keys.",
+  "labels": {}
+}