eduevidence 6.0.0 → 6.3.0

package/integrations/semantic_decide.py

@@ -0,0 +1,286 @@
+"""SemDecide CLI integration (experimental mode 2 / hybrid 3).
+
+Exit 2/3/4 never resolve silently — escalate to the host large model.
+Secrets stay in env files; never passed on argv.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+SEMDECIDE_ENV_FILE = os.environ.get("JEV_ENV_FILE", "~/.eduevidence/env")
+SEMDECIDE_BIN_ENV = "SEMDECIDE_BIN"
+SEMDECIDE_UNAVAILABLE = "SEMDECIDE_UNAVAILABLE"
+SEMDECIDE_APPROVAL_REQUIRED = "SEMDECIDE_APPROVAL_REQUIRED"
+ESCALATE_TO_LLM = "ESCALATE_TO_LLM"
+DEFAULT_THRESHOLD = 0.7
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MIN_CONFIDENCE = 0.0
+SEMDECIDE_TIMEOUT = DEFAULT_TIMEOUT
+EXIT_OK = 0
+EXIT_FALSE = 1
+ESCALATE_EXIT_CODES = frozenset({2, 3, 4})
+EXIT_MEANINGS = {
+    0: "true/selected/match",
+    1: "false/no match",
+    2: "invalid input",
+    3: "uncertain",
+    4: "provider failure",
+}
+WRAPPED_COMMANDS = ("is", "filter", "choose", "score", "guard")
+
+def _env_file_values(path: str | Path | None = None) -> dict[str, str]:
+    try:
+        text = Path(os.path.expanduser(path or SEMDECIDE_ENV_FILE)).read_text(
+            encoding="utf-8")
+    except OSError:
+        return {}
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):]
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip().strip("\"'")
+    return values
+
+
+def binary_path() -> str | None:
+    override = os.environ.get(SEMDECIDE_BIN_ENV)
+    if override and os.path.exists(os.path.expanduser(override)):
+        return os.path.expanduser(override)
+    return shutil.which("semdecide")
+
+
+def detect_semdecide() -> dict[str, Any]:
+    """Probe the local semdecide CLI (never the network)."""
+    path = binary_path()
+    env_values = _env_file_values()
+    has_key = bool(
+        os.environ.get("TYPESAFE_API_KEY")
+        or env_values.get("TYPESAFE_API_KEY")
+        or os.environ.get("AI_GATEWAY_API_KEY")
+        or env_values.get("AI_GATEWAY_API_KEY")
+    )
+    available = path is not None
+    reasons: list[str] = []
+    if not available:
+        reasons.append("semdecide binary not on PATH (pipx/uv tool install "
+                       "from sharziki/semdecide release wheel)")
+    if not has_key:
+        reasons.append("TYPESAFE_API_KEY / AI_GATEWAY_API_KEY not set — "
+                       "semdecide will exit 4 (provider_failure)")
+    return {
+        "available": available,
+        "state": "available" if available else "unavailable",
+        "mode": "semdecide" if available else "none",
+        "binary": path,
+        "credentials_declared": has_key,
+        "reason": "; ".join(reasons) or "semdecide on PATH",
+        "reasons": reasons,
+        "hint": ("install: pipx install "
+                 "https://github.com/sharziki/semdecide/releases/download/"
+                 "v0.2.1/semdecide-0.2.1-py3-none-any.whl"
+                 if not available else ""),
+        "commands": list(WRAPPED_COMMANDS),
+        "escalate_exit_codes": sorted(ESCALATE_EXIT_CODES),
+    }
+
+
+
+def requires_llm_escalation(result: dict[str, Any]) -> bool:
+    """True for exit 2 / 3 / 4 (and missing binary)."""
+    if result.get("status") == SEMDECIDE_UNAVAILABLE:
+        return True
+    return result.get("exit_code") in ESCALATE_EXIT_CODES
+
+
+def _run(argv: list[str], *, stdin_text: str | None = None,
+         timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    path = binary_path()
+    if not path:
+        return {
+            "status": SEMDECIDE_UNAVAILABLE,
+            "exit_code": None,
+            "escalate": ESCALATE_TO_LLM,
+            "reason": "semdecide binary not found",
+        }
+    # Credentials come from the process env / credentials.env — never argv.
+    env = os.environ.copy()
+    for key, value in _env_file_values().items():
+        env.setdefault(key, value)
+    try:
+        proc = subprocess.run(
+            [path, *argv],
+            input=stdin_text if stdin_text is not None else "",
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.TimeoutExpired:
+        return {
+            "status": "SEMDECIDE_TIMEOUT",
+            "exit_code": None,
+            "escalate": ESCALATE_TO_LLM,
+            "reason": f"semdecide timed out after {timeout}s",
+        }
+    except OSError as exc:
+        return {
+            "status": SEMDECIDE_UNAVAILABLE,
+            "exit_code": None,
+            "escalate": ESCALATE_TO_LLM,
+            "reason": f"semdecide spawn failed: {type(exc).__name__}",
+        }
+
+    code = proc.returncode
+    stdout = proc.stdout or ""
+    stderr = proc.stderr or ""
+    payload: Any = None
+    if stdout.strip().startswith("{") or stdout.strip().startswith("["):
+        try:
+            payload = json.loads(stdout)
+        except json.JSONDecodeError:
+            payload = None
+
+    escalate = code in ESCALATE_EXIT_CODES
+    return {
+        "status": "ok" if code in (EXIT_OK, EXIT_FALSE) else EXIT_MEANINGS.get(
+            code, "unknown_exit"),
+        "exit_code": code,
+        "exit_meaning": EXIT_MEANINGS.get(code, "unknown_exit"),
+        "stdout": stdout,
+        "stderr": stderr[-2000:],
+        "json": payload,
+        "escalate": ESCALATE_TO_LLM if escalate else None,
+        "requires_llm": escalate,
+    }
+
+
+
+def is_predicate(text: str, predicate: str, *, threshold: float = DEFAULT_THRESHOLD,
+                 uncertainty_margin: float = 0.0, use_json: bool = True,
+                 timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """`semdecide is` — semantic predicate. Exit 2/3/4 escalate to the LLM."""
+    argv = ["is", predicate, f"--threshold={threshold}",
+            f"--uncertainty-margin={uncertainty_margin}"]
+    if use_json:
+        argv.append("--json")
+    result = _run(argv, stdin_text=text, timeout=timeout)
+    result["command"] = "is"
+    result["predicate"] = predicate
+    if isinstance(result.get("json"), dict):
+        result["verdict"] = result["json"].get("verdict")
+        result["probability"] = result["json"].get("probability")
+        result["confidence"] = result["json"].get("confidence")
+    return result
+
+
+def filter_records(records: list[dict[str, Any]] | str, predicate: str, *,
+                   field: str | None = "text", raw: bool = False,
+                   max_records: int | None = None,
+                   timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """`semdecide filter` — semantic JSONL filtering (order preserved)."""
+    if isinstance(records, str):
+        jsonl = records
+    else:
+        jsonl = "\n".join(json.dumps(r, ensure_ascii=False) for r in records)
+    argv = ["filter", predicate]
+    if field:
+        argv.extend(["--field", field])
+    if raw:
+        argv.append("--raw")
+    if max_records is not None:
+        argv.extend(["--max-records", str(int(max_records))])
+    result = _run(argv, stdin_text=jsonl + ("\n" if jsonl else ""), timeout=timeout)
+    result["command"] = "filter"
+    result["predicate"] = predicate
+    matched: list[Any] = []
+    for line in (result.get("stdout") or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            matched.append(json.loads(line))
+        except json.JSONDecodeError:
+            matched.append(line)
+    result["matched"] = matched
+    result["match_count"] = len(matched)
+    # filter: exit 1 means no definite match — not an escalation by itself.
+    if result.get("exit_code") == EXIT_FALSE:
+        result["escalate"] = None
+        result["requires_llm"] = False
+    return result
+
+
+def choose_route(text: str, question: str,
+                 options: dict[str, str], *,
+                 min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+                 use_json: bool = True,
+                 timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """`semdecide choose` — route among named options. Exit 2/3/4 escalate."""
+    argv = ["choose", question, f"--min-confidence={min_confidence}"]
+    for key, description in options.items():
+        argv.append(f"--option={key}={description}")
+    if use_json:
+        argv.append("--json")
+    result = _run(argv, stdin_text=text, timeout=timeout)
+    result["command"] = "choose"
+    result["question"] = question
+    if isinstance(result.get("json"), dict):
+        result["selected"] = result["json"].get("selected") or result["json"].get("choice")
+        result["probabilities"] = result["json"].get("probabilities")
+        result["confidence"] = result["json"].get("confidence")
+    return result
+
+
+def escalate_plan(result: dict[str, Any], *, stage: str = "") -> dict[str, Any]:
+    """Build the fail-closed hand-off when exit is 2/3/4 (or binary missing)."""
+    code = result.get("exit_code")
+    meaning = result.get("exit_meaning") or EXIT_MEANINGS.get(code, "unknown")
+    return {
+        "action": ESCALATE_TO_LLM,
+        "reason": meaning,
+        "exit_code": code,
+        "stage": stage,
+        "policy": {
+            2: "invalid input — repair inputs and re-run, or hand the whole "
+               "decision to the large model (never invent a verdict)",
+            3: "uncertain under margin — route to large model / human; do not "
+               "force true/false",
+            4: "provider failure — degrade to large model for this call only; "
+               "record the attempt",
+        }.get(code if isinstance(code, int) else -1,
+              "unavailable — use Platform Native / large model path"),
+        "raw_status": result.get("status"),
+    }
+
+
+
+__all__ = [
+    "DEFAULT_THRESHOLD", "DEFAULT_TIMEOUT", "ESCALATE_TO_LLM",
+    "SEMDECIDE_APPROVAL_REQUIRED", "SEMDECIDE_BIN_ENV", "SEMDECIDE_ENV_FILE",
+    "SEMDECIDE_UNAVAILABLE", "binary_path", "choose_route", "detect_semdecide",
+    "escalate_plan", "filter_records", "is_predicate", "requires_llm_escalation",
+]
+
+
+if __name__ == "__main__":
+    # `python3 integrations/semantic_decide.py ...` runs this file as a script,
+    # so the repository root must be importable before `integrations.*` is used.
+    # The CLI itself lives in integrations/semdecide_cli.py (file-size budget).
+    import sys as _sys
+
+    _ROOT = Path(__file__).resolve().parent.parent
+    if str(_ROOT) not in _sys.path:
+        _sys.path.insert(0, str(_ROOT))
+
+    from integrations.semdecide_cli import main as _cli_main
+
+    raise SystemExit(_cli_main())

package/integrations/semdecide_cli.py

@@ -0,0 +1,55 @@
+"""SemDecide detect CLI: the documented `--experimental <mode>` entry point.
+
+Kept separate from `integrations/semantic_decide.py` so the wrapper module stays
+inside the repository's 300-line file budget, the same way the Jev layer keeps
+its CLI in `integrations/jev/cli.py`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from integrations.semantic_decide import (
+    ESCALATE_EXIT_CODES,
+    WRAPPED_COMMANDS,
+    detect_semdecide,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Detect probe: local binary/credential state plus the resolved mode plan."""
+    parser = argparse.ArgumentParser(
+        description="SemDecide experimental detect probe (never calls the network)")
+    parser.add_argument("--experimental", nargs="?", const="1", default=None,
+                        metavar="MODE",
+                        help="enable experimental mode 0|1|2|3 (default 1) and "
+                             "print the resolved plan")
+    args = parser.parse_args(argv)
+
+    out: dict[str, Any] = {"detect": detect_semdecide()}
+    if args.experimental is not None:
+        from integrations.jev.config import MODE_HYBRID, MODE_SEMDECIDE, MODE_STANDARD
+        from integrations.jev.modes import resolve_experimental_mode
+
+        mode = resolve_experimental_mode(args.experimental)
+        out["experimental"] = {
+            "mode": mode,
+            "mode_name": {0: "standard", 1: "jev-mcp", 2: "semdecide",
+                          3: "hybrid"}.get(mode, str(mode)),
+            "enabled": mode in (MODE_SEMDECIDE, MODE_HYBRID),
+            "active": mode != MODE_STANDARD,
+            "commands": list(WRAPPED_COMMANDS),
+            "escalate_exit_codes": sorted(ESCALATE_EXIT_CODES),
+            "fail_closed": ("exit 2/3/4 and a missing binary escalate to the "
+                            "large model; filter exit 1 alone does not"),
+        }
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+__all__ = ["main"]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eduevidence",
-  "version": "6.0.0",
+  "version": "6.3.0",
   "description": "Evidence research and decision skill with education and organizational policy domains.",
   "license": "MIT",
   "author": "EduEvidence Contributors",
@@ -40,6 +40,9 @@
     "references/",
     "schemas/",
     "scripts/",
+    "!scripts/build_esl_artifacts.py",
+    "!scripts/generate_new_projects.py",
+    "!scripts/enrich_projects_human_and_lieflat.py",
     "retrieval/",
     "integrations/",
     "visualization/eduevidence-report/",
@@ -51,6 +54,12 @@
     "autoevolve/protected.manifest.yaml",
     "setup.py",
     "docs/architecture.md",
+    "docs/sciverse-api.md",
+    "docs/reproducibility.md",
+    "docs/j-ev-experimental.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "web/architecture.html",
     "docs/install-guide.md",
     "docs/release-contract.md",
     "docs/research-studio-guide.zh-CN.md",
@@ -68,11 +77,19 @@
     "examples/workplace-ai-assistant/*.jsonl",
     "examples/workplace-ai-assistant/*.html",
     "examples/workplace-ai-assistant/reports-5themes/*.html",
+    "examples/spaced-retrieval-practice/*.json",
+    "examples/spaced-retrieval-practice/*.jsonl",
+    "examples/spaced-retrieval-practice/*.html",
+    "examples/spaced-retrieval-practice/reports-5themes/*.html",
     "docs/demo-workplace-ai.md",
     "docs/demo.md",
     "docs/demo-storyboard.md",
     "docs/release-closeout/*.md",
-    "assets/readme/"
+    "assets/readme/",
+    "!**/__pycache__/",
+    "!**/*.pyc",
+    "!**/*.pyo",
+    "!**/.DS_Store"
   ],
   "engines": {
     "node": ">=18"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "eduevidence"
-version = "6.0.0"
+version = "6.3.0"
 description = "Evidence research and decision skill with education and organizational policy domains."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -18,7 +18,7 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=7.0"]
+dev = ["pytest>=7.0", "jsonschema>=4.0"]
 
 [project.scripts]
 eduevidence = "eduevidence_cli:main"
@@ -27,7 +27,8 @@ eduevidence = "eduevidence_cli:main"
 testpaths = ["tests", "scripts"]
 python_files = ["test_*.py"]
 addopts = "-q"
-filterwarnings = ["ignore::pytest.PytestReturnNotNoneWarning:scripts.*"]
+# scripts/* tests must assert; returning a dict is reported, not filtered.
+filterwarnings = []
 
 [tool.setuptools]
 py-modules = ["eduevidence_cli"]

package/references/report-copy-style.md

@@ -0,0 +1,107 @@
+# Report Copy Style — 读者向文案规范
+
+本规范约束**报告里面向读者的文字**（第一屏决策叙事、裁决列表、章节引导语、图表标题与说明）。它服务于一个判断标准：**读者能否一次读懂，且能核对**。规则由 `skill/agents/evidence-judge.md`（写作前）与 `visualization/eduevidence-report/scripts/build_report.py` 的语言门禁（交付后）双向执行。
+
+## 1. 谁写什么
+
+| 内容 | 作者 | 说明 |
+|---|---|---|
+| 决策叙事四件套（`strongest_support` / `key_uncertainty` / `main_risk` / `next_action`） | **裁决角色（模型）撰写** | 渲染器只呈现，缺字段就报缺，禁止用列表片段拼装句子 |
+| `decision_rationale` | 裁决角色 | ≤4 句，可独立阅读 |
+| 章节引导语、图例、按钮、兜底句 | 渲染器（固定文案表） | 不随研究内容变化 |
+| 证据与主张原文 | 抽取/裁决角色 | 渲染器不改写 |
+
+**为什么写死这条**：报告第一屏曾由渲染器从 `what_can_be_claimed[0]` 之类的片段拼出，读起来像拼装而非撰写，且掩盖了「该字段没人产出」这一事实。撰写责任在模型，呈现责任在渲染器。
+
+## 2. 语言
+
+- 面向**非本领域的决策者**：不假设读者熟悉术语。
+- 一句话一个意思；先结论、后依据。
+- 中文用中文，英文用英文；两种语言各自成篇，不做逐字直译。
+- 允许保留原文的例外：AI、RCT、DOI、WWC、GRADE、论文原标题（须标注「原文标题」）。
+
+## 3. 字数上限
+
+| 字段 | 上限 | 约合 |
+|---|---|---|
+| `strongest_support` | 60 字 | 2 句 |
+| `key_uncertainty` | 70 字 | 2–3 句 |
+| `main_risk` | 60 字 | 2 句 |
+| `next_action` | 80 字 | 2–3 句 |
+| `decision_rationale` | 160 字 | ≤4 句 |
+
+英文字数上限按等义折算（约为中文字数 ÷ 3 个单词）。
+
+## 4. 按域选文案（Domain copy packs）
+
+报告层**不得**再写死教育域用语。面向读者的研究文案、章节标题、模块标签与框架枚举一律从领域文案包读取：
+
+```
+domains/<domain_id>/copy/
+  framing_lexicon.json   # frame 枚举 + 字段/子字段标签
+  section_titles.json    # 01–12 章节标题与引导语、默认章节大纲、摘要块标题
+  module_labels.json     # 域敏感 UI 模块标签（干预/评价/护栏/分组）
+  terminology.json       # 方法学项标签 + 字段展示名
+  risk_constructs.json   # 结果分组、结果分离标题/注、构念护栏
+  few_shots.json         # 四态（adopt / pilot / reject / insufficient_evidence）各 1 例文案
+```
+
+中性 UI 词典在 `domains/_neutral/copy/`（`module_labels*.json` 按主题拆分；渲染器 chrome，无研究口吻）。大词典允许主题拆伴文件：`framing_enums.json`、`module_labels_*.json`，加载时并入上述六件套视图。加载与合并：`visualization/eduevidence-report/scripts/report_copy_pack.py`。
+
+**域名解析**：`result.meta.domain` → `result.research_frame.extensions.domain`。缺省按 `education`（引擎惯例）并告警；未知域中性回退 + 告警（`strict=True` 则 fail-clear）。
+
+**域差异（写作时对照）**：
+
+| 概念 | education | policy |
+|---|---|---|
+| 干预 | AI 干预 / 教学干预 | **干预方案**（禁止「AI 干预」） |
+| target_learners | 目标学习者 | **目标人群** |
+| 结果分离 | 任务表现 ≠ 学习效果 | 过程产出 ≠ 政策效果 |
+| 评价指标 | 过程 / **学习** / 风险 | 过程 / **效果** / 风险 |
+| 构念护栏 | 任务 vs 学习护栏 | 产出 vs 效果护栏 |
+| 章节 09 | 教学干预 | 干预方案 |
+
+**policy 词典硬约束**：`python3 domains/check_copy_packs.py` 断言 policy 文案包不含教学词（教学/学习者/学习指标/AI 干预/…）；`report_copy_pack.assert_policy_copy_clean` 在加载时同样 fail-clear。`build_infographics` 遗留的教育 SVG 标题由 `retitle_infographics()` 按域改写，不改适配器本体。
+
+**新增第三域（例如 workplace / health）**：
+
+1. 在 `domains/manifest.json` 注册 `id` / frame_schema / outcome_taxonomy / methodology_checklist（沿用 v4 领域契约）。
+2. 新建 `domains/<id>/copy/`，写入上述 6 个 JSON（`domain` 字段必须等于 `<id>`）。
+3. 口吻：从 policy 包复制结构，换成该域构念词；禁止混入其他域硬词（用 `check_copy_packs.py` 的词表扩展后自检）。
+4. `few_shots.json` 四态各写 1 例该域决策口吻（≤ 规范字数上限）。
+5. 结果分组：在 `risk_constructs.json` 的 `outcome_groups` 把该域 outcome token 映射到 `task` / `learning` / `risk`（内部桶名不变，展示名由 `module_labels` 决定）。
+6. 跑 `python3 domains/check_copy_packs.py` + 用该域 `result.json` 跑一次 `build_report.py`，确认 HTML 无外域硬词。
+
+## 5. 术语对照
+
+同一概念全文只用一个说法：
+
+| 内部字段 | 中文 | 英文 |
+|---|---|---|
+| `outcome` / `outcome_type` | 结果 | outcome |
+| `claim` | 主张 | claim |
+| `evidence` | 证据 | evidence |
+| `relation_to_claim` | 与主张的关系 | relation to claim |
+| `effect_direction` | 效应方向 | effect direction |
+| `directness` | 直接性 | directness |
+| `task_performance` | 任务表现 | task performance |
+| `retention` | 保持 | retention |
+| `transfer` | 迁移 | transfer |
+| `applicability` | 适用性 | applicability |
+
+## 6. 禁止
+
+- 内部字段名与存储标识（`effect_direction`、`first_programming_course_...`）出现在叙述句里；它们只能出现在「原始标识」提示或溯源展开区。
+- 证据 ID 堆砌（`E-001、E-006`）出现在决策叙事里；引用研究用「作者-年份 + 人话描述」。
+- 图表标题写公式（如 `position = (positive − negative) ÷ count`）；用自然语言说明图形含义。
+- 半句截断、`null` 残留、中英夹生。
+- 用兜底句掩盖缺失：字段没产出就如实说没产出。
+
+## 7. 门禁如何执行
+
+- `check_language_parallel()`：叙述字段必须为对应语言、双语不得完全相同、不得含内部键名。
+- 原始标识检查：`research_frame` 与决策字段中的多词串若含未注册的 `snake_case`，记为缺陷。
+- 字数检查：四件套超过上限即失败。
+- 一致性检查：`result.json` 与 `result.zh.json` 的证据在 id/来源/研究/样本/方向/关系六个结构字段上必须逐条相等（自由文本可不同）。
+
+相关：`visualization/eduevidence-report/references/bilingual-style.md`（双语渲染约定）、`references/scientific-invariants.md`（科学不变量）。

package/references/retrieval-compliance.md

@@ -0,0 +1,75 @@
+# Retrieval Compliance Policy（检索合规政策）
+
+本条政策约束 EduEvidence 的一切外部检索与抓取行为。它服务于两件事：**研究的可复现性**（每条来源都能被第三方重新定位）与**对他方服务与作者的尊重**（不越权、不滥用、不掩盖出处）。违反本条政策的检索结果不得进入证据链。
+
+## 1. 定位与适用范围
+
+适用于 `retrieval/` 下的全部通道：
+
+| 通道 | 类型 | 是否需 key |
+|---|---|---|
+| OpenAlex / Semantic Scholar / CrossRef | 学术元数据 API | 否 |
+| AIHot | 行业动态源 | 否 |
+| AgentSearch / ArXiv | 预印本检索 | 否 |
+| DuckDuckGo | 通用网页回退 | 否 |
+| Sciverse | 学术检索（含全文） | 是（`SCIVERSE_API_TOKEN`） |
+| Tavily / Brave | 商业搜索 API | 是 |
+| 抓取链（builtin / jina_reader / defuddle / markdown_new / raw_html） | 正文读取 | 否 |
+
+## 2. 抓取前：robots 与访问边界
+
+- **尊重 robots.txt**：目标站点在 robots.txt 中禁止抓取的路径不得作为抓取目标；需要该内容时改用其官方 API 或元数据记录，并在筛选中注明"仅元数据"。
+- **不绕过访问控制**：登录墙、付费墙、验证码页面一律视为不可读内容。抓取链会在校验门中把这些页面判为无效（`is_login_page` / `is_captcha_page`），此时正确做法是回到检索阶段寻找开放版本（预印本、机构库、作者主页），**而不是尝试绕过**。
+- **不伪造可读性**：`FETCH_FAILED` / `FETCH_PARTIAL` 的内容不得作为证据；不得由模型根据标题或摘要"补写"正文。
+- **私有地址不外发**：指向本机/私网的目标只允许本地读取，绝不提交给第三方清洗服务（`retrieval/fetch.py` 的 `LOCAL_PROVIDERS` 约束）。
+
+## 3. 限速与重试
+
+- 检索按查询批次串行执行，每次 provider 尝试最多重试 1 次（`AuditedSearchExecutor(max_retries=1)`）；失败即记录并切换通道，不做无限重试。
+- 单次运行的检索预算由 `SearchPlan.provider_budget` 限定；S/M/L 分级只影响预算，不影响协议。
+- 超时：检索 12 秒、抓取 20 秒；超时按失败处理并进入降级链。
+- 商用 API 通道按其配额与速率限制使用；配额耗尽是运营问题，不构成放宽其他通道约束的理由。
+
+### Sciverse 通道附加约定
+
+- 单次 `agentic-search` 的 `top_k` 上限 100，且同一篇论文最多返回约 3 个 chunk；`balanced` 模式服务端约截断至 50 条。
+- `filters` 为**软过滤**语义：chunk 侧元数据缺失的文档不会被排除。按年份等条件过滤时，结论表述必须写"近似范围"；需要严格范围时改用 `meta-search` 的结构化字段并核对返回记录。
+- `offset` / `limit` 以 **Unicode 码点**计（与 Python `len` 一致），不是字节；翻页使用返回的 `next_offset`。
+- 引用必须回指论文本身（DOI 或 `unique_id`），**不得把 Sciverse 记为引用目标**——它是读取路径，不是来源。
+
+## 4. 署名与引用
+
+- 引用目标永远是被引文献本身（DOI / 正式 URL / 数据库标识），绝不是检索或清洗通道（`r.jina.ai`、`markdown.new`、Sciverse 等）。
+- 作者、年份、标题、期刊按原文记录，不改写、不翻译、不合并同名作者。
+- 使用的每个来源都要能给出可核验的 `source_location`；没有位置的记录标 `needs_manual_location` 进入人工筛选。
+- 撤稿与更正：已引 DOI 通过 `scripts/retraction_watch.py` 定期核查，命中即移除其支撑作用并重新裁决。
+
+## 5. 缓存与留存
+
+- 抓取正文在 run workspace 的 `fetch/` 下保存（raw + clean + provenance + fallback_chain），用于复现与审计；该目录随 run 生命周期管理。
+- 检索审计（`search-provenance.json` / `search-attempts.jsonl` / `source-screening.csv` / `exclusion-log.csv`）与 run 同寿命，用于证明"检索确实发生过、范围如何"。
+- 不长期镜像第三方全文；需要长期复用时保存定位信息与哈希，而非内容副本。
+- 私有项目、用户上传数据与本地运行历史一律不进入公共产物（提交包由 `scripts/skill_payload.py` 的显式白名单构建）。
+
+## 6. 凭据处理
+
+- API key 只从环境变量读取（`SCIVERSE_API_TOKEN` / `TAVILY_API_KEY` / `BRAVE_API_KEY`）；不写入仓库、不写入产物、不进日志。
+- 错误信息只保留状态与简短描述，不携带 Authorization 头或 token 片段。
+- 缺少 key 时通道静默失活并如实上报状态，不影响零配置通道与科学门。
+
+## 7. 失败与例外
+
+| 情形 | 处理 |
+|---|---|
+| 站点禁止抓取 | 退回元数据记录并标注；不得绕过。 |
+| 付费墙 | 寻找开放版本；找不到则记 `needs_manual_location`。 |
+| 配额耗尽 | 记录该次尝试；切换零配置通道继续。 |
+| 合规与时效冲突 | 以合规为准；宁可结论标注"证据不足"。 |
+
+## 8. 交叉引用
+
+- 检索协议：`references/retrieval-protocol.md`（查询构造、来源分级、饱和规则）
+- 来源有效性：`references/source-validity.md`
+- 抓取与校验实现：`retrieval/fetch.py`、`retrieval/validate.py`
+- Sciverse 通道：`docs/sciverse-api.md`
+

package/references/retrieval-protocol.md

@@ -68,6 +68,24 @@ source-validity.md）后才能进入 Evidence Extraction。
 | RP-03 | 厂商/行业声明（如 Copilot 官方博客、AI 产品宣传页）**一律不得**作为独立证据，即使域名是 `.edu` / `.gov`（需核查内容是否厂商资助）。 |
 | RP-04 | 无法回溯到原始来源的二手转述，不得进入 Evidence Matrix。 |
 
+### 3.1 Sciverse 通道使用规则（key-based 学术通道）
+
+Sciverse（`retrieval/sciverse.py`，需 `SCIVERSE_API_TOKEN`）提供引用级学术检索与全文定位。使用时必须遵守以下语义，否则结论口径会被静默夸大：
+
+| 编号 | 规则 |
+| --- | --- |
+| RP-SV-01 | `/agentic-search` 返回的 chunk 是**定位子**（`doc_id` + Unicode 码点 `offset`），必须经 `/content` 读出正文并通过 `retrieval/validate.py` 校验门，才可进入 Extract（RULE 2 的机器化）。定位写入 `chunks.jsonl`，标注 `discovery_only_requires_content_fetch`。 |
+| RP-SV-02 | `filters` 是**软过滤**：chunk 元数据缺失的文档不会被排除。按年份等条件过滤时，结论与筛选表必须写"近似范围"；需要严格范围时改用 `/meta-search` 的结构化过滤并逐条核对返回记录。 |
+| RP-SV-03 | `offset` / `limit` 以 **Unicode 码点**计（与 Python `len` 一致）；翻页使用返回的 `next_offset`，不得用 `bytes_returned` 推算。 |
+| RP-SV-04 | 调用 `/content` 必须显式传 `offset`（省略会返回整篇全文并忽略 `limit`）。 |
+| RP-SV-05 | 同一篇论文最多返回约 3 个 chunk，`balanced` 模式服务端约截断至 50 条；高 `top_k` 需要足够多的不同论文，不得用同一篇的多个 chunk 充当多项独立证据。 |
+| RP-SV-06 | 引用目标永远是论文本身（DOI / `unique_id`），**不得把 Sciverse 记为来源或抓取渠道**。 |
+| RP-SV-07 | 无 DOI、无 URL 的记录标 `needs_manual_location` 进入人工筛选，**禁止伪造定位**。 |
+| RP-SV-08 | 引文链（`/meta-paper-relations`）用于饱和判断与滚雪球检索，对应 `SearchQuery.purpose = citation_chain`，其方向语义（CITATIONS 被引 / REFERENCES 参考文献）必须在记录中保留。 |
+| RP-SV-09 | 通道不可用（无 token / 401 / 429 / 5xx / 网络失败）时按定型状态记录并切换其他通道；不得因配额耗尽放宽证据标准。 |
+
+端点契约与限制见 `docs/sciverse-api.md`；配额、缓存与署名见 `references/retrieval-compliance.md`。
+
 ## 4. 检索轮次与饱和规则
 
 ### 4.1 最小轮次
@@ -140,3 +158,5 @@ Skeptic 的 9 项固定任务（skeptic-protocol.md）需要对应的独立查
 | RP-09 | snippet 与摘要不得直接作为证据内容（RULE 2）；检索阶段产物只能是线索。 |
 | RP-10 | 厂商声明与二手转述不得作为独立证据（RP-03 / RP-04）。 |
 | RP-11 | 达到饱和规则或数量下限后仍不足的，如实输出 `INSUFFICIENT_SOURCES`，禁止降低纳入标准凑数。 |
+
+来源合规（robots、限速、paywall、署名与凭据）统一见 `references/retrieval-compliance.md`；Sciverse 通道附加约定见本文 §3.1。