eduevidence 5.2.0

package/engine/update.py

@@ -0,0 +1,113 @@
+"""Close the Full Research Cycle: validated project analysis → graph evidence.
+
+One atomic mutation: a project-local Source (portable project:// locator,
+derived from DatasetAsset + AnalysisRun provenance), one Study, its
+Findings, MethodologyAudit, and contextual Claims/Links commit in ONE graph
+revision — never one revision per Finding.
+
+AnalysisRun.status must be `validated`; otherwise ANALYSIS_INVALID is
+returned and the graph stays unchanged. The engine derives the Source; the
+caller supplies schema-valid Study/Findings/Audit/Claims/Links.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from engine.contracts import validate_record
+from engine.graph_store import GraphStore, GraphMutation, GraphRevision
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def project_study_mutation(*, project: ProjectWorkspace,
+                           design: dict,
+                           dataset_asset: dict,
+                           analysis_run: dict,
+                           study: dict,
+                           findings: list[dict],
+                           methodology_audit: dict,
+                           claims: list[dict],
+                           links: list[dict]) -> GraphMutation:
+    """Build the bundle mutation; raises ValueError on invalid inputs.
+
+    The derived project-local Source carries a portable `project://` locator
+    referencing the dataset; raw filesystem paths stay provenance metadata.
+    """
+    if analysis_run.get("status") != "validated":
+        raise ValueError(
+            f"ANALYSIS_INVALID: AnalysisRun {analysis_run.get('analysis_run_id')} "
+            f"status {analysis_run.get('status')!r} is not 'validated'; graph "
+            f"unchanged")
+
+    source_id = f"SRC-{dataset_asset['dataset_id']}"
+    source = {
+        "source_id": source_id,
+        "origin": "project",
+        "source_type": "project_study",
+        "canonical_locator": (
+            f"project://{project.project_id}/datasets/{dataset_asset['dataset_id']}"),
+        "validation_status": "valid",
+        "content_hash": dataset_asset["content_hash"],
+        "extensions": {
+            "dataset_id": dataset_asset["dataset_id"],
+            "design_id": design["design_id"],
+            "analysis_run_id": analysis_run["analysis_run_id"],
+            "provenance": {
+                "provider": (analysis_run.get("extensions") or {}).get("provider"),
+                "software": (analysis_run.get("extensions") or {}).get("software"),
+            },
+        },
+    }
+    errors = validate_record("source", source)
+    if errors:
+        raise ValueError(f"derived project source invalid: {errors}")
+
+    # validate the whole bundle before touching the store
+    for label, schema, rec in (
+        ("study", "study", study),
+        ("audit", "methodology-audit", methodology_audit),
+    ):
+        errs = validate_record(schema, rec)
+        if errs:
+            raise ValueError(f"{label} invalid: {errs}")
+    for f in findings:
+        errs = validate_record("finding", f)
+        if errs:
+            raise ValueError(f"finding {f.get('finding_id')} invalid: {errs}")
+    for c in claims:
+        errs = validate_record("claim", c)
+        if errs:
+            raise ValueError(f"claim {c.get('claim_id')} invalid: {errs}")
+    for l in links:
+        errs = validate_record("evidence-link", l)
+        if errs:
+            raise ValueError(f"evidence_link {l.get('evidence_link_id')} invalid: {errs}")
+
+    return GraphMutation(
+        upserts={
+            "sources": [source],
+            "studies": [study],
+            "findings": findings,
+            "audits": [methodology_audit],
+            "claims": claims,
+            "evidence_links": links,
+        },
+        retire_ids={},
+    )
+
+
+def commit_project_study(*, store: GraphStore, run_id: str,
+                         design: dict, dataset_asset: dict,
+                         analysis_run: dict, study: dict,
+                         findings: list[dict], methodology_audit: dict,
+                         claims: list[dict], links: list[dict]) -> GraphRevision:
+    """Validate the bundle and commit it as exactly ONE graph revision."""
+    mutation = project_study_mutation(
+        project=store.project, design=design, dataset_asset=dataset_asset,
+        analysis_run=analysis_run, study=study, findings=findings,
+        methodology_audit=methodology_audit, claims=claims, links=links)
+    return store.commit(run_id=run_id, reason="project study evidence",
+                        mutation=mutation)

package/engine/versions.py

@@ -0,0 +1,12 @@
+"""Version pins for the V2 Research Engine.
+
+Policy versions are frozen identifiers, not free-form strings: changing a
+policy requires a new version, never silent mutation of an existing one.
+"""
+
+ENGINE_VERSION = "5.2.0"
+GRAPH_SCHEMA_VERSION = "2.0"
+SOURCE_VALIDATION_POLICY_VERSION = "2026-08-12.v2"
+METHODOLOGY_POLICY_VERSION = "2026-08-12.v2"
+CONFIDENCE_POLICY_VERSION = "2026-08-12.v3"
+REPORT_CONTRACT_VERSION = "3.0"

package/install.sh

@@ -0,0 +1,510 @@
+#!/usr/bin/env bash
+# EduEvidence 一键安装脚本（macOS / Linux）
+#
+# 供应链提示（E7）：远程执行请优先走「clone + 本地审阅」路径——
+#   git clone --depth 1 https://github.com/37chengshan/eduevidence
+#   cd eduevidence && bash install.sh
+# 若必须 curl 直跑，建议固定到具体 commit 并先人工审阅：
+#   curl -fsSL https://raw.githubusercontent.com/37chengshan/eduevidence/<commit>/install.sh -o install.sh
+#
+# 副作用披露：本脚本会 (a) 创建 Python venv 并安装依赖；
+# (b) 写入 $HOME/.eduevidence/env（AGENT_MCP_INSTALLED=1 声明）；
+# (c) --skill 模式在所选宿主目录写入 skill 文件（覆盖前自动备份）。
+#
+# 用法:
+#   bash install.sh                    # 本地安装：venv + 依赖 + 自检 + 测试（等价 --dev）
+#   bash install.sh --dev              # 同上（向后兼容，默认行为）
+#   bash install.sh --skill            # 交互式安装为 AI Agent Skill（选择宿主 Agent）
+#   bash install.sh --list-hosts       # 显示支持的宿主 Agent 与 Skill 落点
+#   bash install.sh --dry-run          # 只预览将执行的变更，不写入任何文件
+#   bash install.sh --skill --dry-run  # 预览 Skill 安装（仍会交互选择宿主）
+#   bash install.sh --skill --host claude          # 非交互：安装到指定宿主
+#   bash install.sh --skill --host all             # 非交互：安装到全部宿主
+#   bash install.sh --skill --dest ~/.cursor/skills  # 非交互：自定义 skill 根目录
+#   bash install.sh --skill --skill-only --host claude  # 仅复制 Skill，跳过 venv/pytest
+set -euo pipefail
+
+REPO_URL="https://github.com/37chengshan/eduevidence"
+SKILL_NAME="eduevidence"
+# Skill 本体（运行协议 + 确定性脚本 + 检索/集成层 + 展示层）。
+# retrieval/ 与 integrations/ 会被 scripts/ 直接 import；visualization/ 负责最终 HTML 渲染。
+SKILL_PAYLOAD=(SKILL.md engine domains skill references schemas scripts retrieval integrations visualization)
+# Agent MCP 声明文件：安装完成后写入 AGENT_MCP_INSTALLED=1，供
+# integrations/agent_mcp.py 作为 env 后备来源读取（真实环境变量优先于该文件）。
+AGENT_MCP_ENV_FILE="${AGENT_MCP_ENV_FILE:-$HOME/.eduevidence/env}"
+
+# ---------- curl 远程执行支持 ----------
+# 用法: bash -c "$(curl -fsSL https://raw.githubusercontent.com/37chengshan/eduevidence/main/install.sh)"
+# 脚本不在仓库内运行时（无 SKILL.md），自动 clone 仓库到 ./eduevidence 并进入。
+if [ ! -f "SKILL.md" ]; then
+    echo "==> 未在 EduEvidence 仓库内，自动克隆仓库…"
+    if command -v git >/dev/null 2>&1; then
+        git clone --depth 1 "$REPO_URL" eduevidence
+        cd eduevidence
+    else
+        echo "ERROR: 未找到 git，请先安装 git 或手动 clone 仓库" >&2
+        exit 1
+    fi
+fi
+
+# ---------- 参数解析 ----------
+INSTALL_DEV=""
+HAS_DEV_FLAG=0
+MODE="local"      # local | skill | list
+DRY_RUN=0
+HOST_CHOICE=""
+DEST_ROOT=""
+SKILL_ONLY=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dev)        INSTALL_DEV="--dev"; HAS_DEV_FLAG=1; shift ;;
+        --skill)      MODE="skill"; shift ;;
+        --skill-only) SKILL_ONLY=1; MODE="skill"; shift ;;
+        --list-hosts) MODE="list"; shift ;;
+        --dry-run)    DRY_RUN=1; shift ;;
+        --host)
+            HOST_CHOICE="${2:-}"
+            if [ -z "$HOST_CHOICE" ]; then
+                echo "ERROR: --host 需要参数（如 claude / codex / all）" >&2
+                exit 1
+            fi
+            MODE="skill"
+            shift 2
+            ;;
+        --dest)
+            DEST_ROOT="${2:-}"
+            if [ -z "$DEST_ROOT" ]; then
+                echo "ERROR: --dest 需要 skill 根目录参数" >&2
+                exit 1
+            fi
+            DEST_ROOT="${DEST_ROOT%/}"
+            DEST_ROOT="${DEST_ROOT/#\~/$HOME}"
+            MODE="skill"
+            shift 2
+            ;;
+        *) echo "ERROR: 未知参数: $1" >&2; exit 1 ;;
+    esac
+done
+# 向后兼容：裸 `bash install.sh` 等价于 `bash install.sh --dev`
+if [ "$MODE" = "local" ] && [ "$HAS_DEV_FLAG" -eq 0 ]; then
+    INSTALL_DEV="--dev"
+fi
+
+# ---------- 宿主 Agent 表 ----------
+HOSTS=(claude codex cursor omp opencode kimi zcode openclaw harness grok copilot cline)
+
+# 探测宿主是否已安装（尽力而为；未探测到不阻塞安装，只做提示）
+host_detect() {
+    case "$1" in
+        claude)   [ -d "$HOME/.claude" ] || [ -f "$HOME/.claude.json" ] ;;
+        codex)    [ -d "$HOME/.codex" ] || command -v codex >/dev/null 2>&1 ;;
+        cursor)   [ -d "$HOME/.cursor" ] ;;
+        omp)      [ -d "$HOME/.omp" ] ;;
+        opencode) [ -d "$HOME/.config/opencode" ] || command -v opencode >/dev/null 2>&1 ;;
+        kimi)     [ -d "${KIMI_CODE_HOME:-$HOME/.kimi-code}" ] || command -v kimi >/dev/null 2>&1 ;;
+        zcode)    [ -d "$HOME/.zcode" ] ;;
+        openclaw) [ -d "$HOME/.openclaw" ] ;;
+        harness)  [ -d "$HOME/.harness" ] ;;
+        grok)     [ -d "$HOME/.grok" ] ;;
+        copilot)  [ -d "$HOME/.copilot" ] || command -v copilot >/dev/null 2>&1 ;;
+        cline)    [ -d "$HOME/.cline" ] || [ -d "$HOME/.config/cline" ] ;;
+        *) return 1 ;;
+    esac
+}
+
+# 返回某宿主的 skill 根目录（eduevidence/ 会创建为其子目录）
+host_skill_root() {
+    case "$1" in
+        claude)
+            if [ -d "$HOME/.claude/skills" ] || [ -d "$HOME/.claude" ]; then
+                echo "$HOME/.claude/skills"          # 用户级配置存在 → 用户级落点
+            else
+                echo "$PWD/.claude/skills"           # 否则装到项目级 .claude/skills/
+            fi
+            ;;
+        codex)
+            # 官方标准 ~/.agents/skills，兼容 ~/.codex/skills 与 ~/.codex/prompts，按探测顺序取
+            if [ -d "$HOME/.agents/skills" ]; then
+                echo "$HOME/.agents/skills"
+            elif [ -d "$HOME/.codex/skills" ]; then
+                echo "$HOME/.codex/skills"
+            elif [ -d "$HOME/.codex/prompts" ]; then
+                echo "$HOME/.codex/prompts"
+            else
+                echo "$HOME/.agents/skills"
+            fi
+            ;;
+        cursor)   echo "$HOME/.cursor/skills" ;;
+        omp)      echo "$HOME/.omp/agent/skills" ;;
+        opencode) echo "$HOME/.config/opencode/skills" ;;
+        kimi)     echo "${KIMI_CODE_HOME:-$HOME/.kimi-code}/skills" ;;
+        zcode)    echo "$HOME/.zcode/skills" ;;
+        openclaw) echo "$HOME/.openclaw/skills" ;;
+        harness)  echo "$HOME/.harness/skills" ;;
+        grok)     echo "$HOME/.grok/skills" ;;
+        copilot)  echo "$HOME/.copilot/skills" ;;
+        cline)    echo "$HOME/.cline/skills" ;;
+    esac
+}
+
+# ---------- 通用提示词（方式三：宿主不在支持列表时交给任意 AI） ----------
+UNIVERSAL_PROMPT="请把 https://github.com/37chengshan/eduevidence 仓库中的 EduEvidence 安装为 skill：
+1. 将仓库根目录的 SKILL.md、skill/、references/、schemas/、scripts/、retrieval/、integrations/、visualization/ 复制到你的 skill 目录
+   （如 ~/.claude/skills/eduevidence/、~/.omp/agent/skills/eduevidence/、~/.agents/skills/eduevidence/ 等），
+   或按你的 skill 装载机制导入；
+2. 安装完成后确认能读取 SKILL.md，并能运行 scripts/ 下的确定性脚本；
+3. 告诉我安装结果。"
+
+print_universal_prompt() {
+    echo ""
+    echo "============================================================"
+    echo "方式三：通用提示词（宿主 Agent 不在支持列表时使用）"
+    echo "============================================================"
+    echo "把下面这段提示词原样交给任意支持 skill / 自定义指令的 AI："
+    echo ""
+    echo "$UNIVERSAL_PROMPT"
+    echo ""
+    echo "============================================================"
+}
+
+# ---------- 安装完成后的提示（仅提示，不自动执行任何 star 操作） ----------
+star_prompt() {
+    echo ""
+    echo "==> If EduEvidence helps, consider starring ⭐ ${REPO_URL}（仅提示，不会自动点 star）"
+}
+
+# ---------- Agent MCP 声明（~/.eduevidence/env） ----------
+# 安装完成后写入 AGENT_MCP_INSTALLED=1，供 integrations/agent_mcp.py 读取。
+# 只写「已安装」声明，不安装 agent-mcp daemon：detect 仍要求 daemon 可达
+# （声明但 daemon 未起 -> state: unavailable；daemon 起但未声明 ->
+# state: daemon_reachable_undeclared）。
+write_agent_mcp_env() {
+    if [ "$DRY_RUN" -eq 1 ]; then
+        echo "    [dry-run] 将写入 $AGENT_MCP_ENV_FILE: AGENT_MCP_INSTALLED=1"
+        return 0
+    fi
+    mkdir -p "$(dirname "$AGENT_MCP_ENV_FILE")"
+    touch "$AGENT_MCP_ENV_FILE"
+    if grep -q '^AGENT_MCP_INSTALLED=' "$AGENT_MCP_ENV_FILE" 2>/dev/null; then
+        # 幂等更新（兼容 macOS/BSD 与 GNU sed：不用 -i）
+        local tmp
+        tmp="$(mktemp)"
+        sed 's/^AGENT_MCP_INSTALLED=.*/AGENT_MCP_INSTALLED=1/' \
+            "$AGENT_MCP_ENV_FILE" > "$tmp"
+        mv "$tmp" "$AGENT_MCP_ENV_FILE"
+    else
+        printf 'AGENT_MCP_INSTALLED=1\n' >> "$AGENT_MCP_ENV_FILE"
+    fi
+    echo "    ✅ 已写入 ${AGENT_MCP_ENV_FILE}（AGENT_MCP_INSTALLED=1）"
+}
+
+# ---------- 本地安装：Python 检查 + venv + 依赖 + 自检（--dev 时含 pytest） ----------
+local_setup() {
+    local PYTHON_BIN="${PYTHON:-python3}"
+
+    echo "==> EduEvidence 安装开始"
+
+    # 1. 检查 Python >= 3.10
+    if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
+        if [ "$DRY_RUN" -eq 1 ]; then
+            echo "    [dry-run] Python 版本检查将失败：未找到 ${PYTHON_BIN}（需要 3.10+）"
+            echo "    [dry-run] 预览结束（本环境不会真正安装）"
+            exit 0
+        fi
+        echo "ERROR: 未找到 ${PYTHON_BIN}，请先安装 Python 3.10+ (https://www.python.org/downloads/)" >&2
+        exit 1
+    fi
+    PY_VERSION="$("$PYTHON_BIN" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+    PY_MAJOR="${PY_VERSION%%.*}"
+    PY_MINOR="${PY_VERSION#*.}"
+    if [ "$PY_MAJOR" -lt 3 ] || { [ "$PY_MAJOR" -eq 3 ] && [ "$PY_MINOR" -lt 10 ]; }; then
+        if [ "$DRY_RUN" -eq 1 ]; then
+            echo "    [dry-run] Python 版本检查将失败：需要 3.10+，当前 $PY_VERSION"
+            echo "    [dry-run] 预览结束（本环境不会真正安装）"
+            exit 0
+        fi
+        echo "ERROR: 需要 Python 3.10+，当前 $PY_VERSION" >&2
+        exit 1
+    fi
+    echo "    Python $PY_VERSION OK"
+
+    # 2. 创建 venv（如不存在）
+    if [ ! -d ".venv" ]; then
+        if [ "$DRY_RUN" -eq 1 ]; then
+            echo "    [dry-run] 将创建虚拟环境 .venv"
+        else
+            echo "==> 创建虚拟环境 .venv"
+            "$PYTHON_BIN" -m venv .venv
+        fi
+    fi
+    if [ "$DRY_RUN" -eq 1 ]; then
+        echo "    [dry-run] 将激活 .venv 并安装依赖（pip install -e .）"
+        echo "    [dry-run] 将运行自检：Schema 校验 + 渲染双语 HTML 报告"
+        write_agent_mcp_env
+        return 0
+    fi
+    # shellcheck disable=SC1091
+    source .venv/bin/activate
+    echo "    venv: $(command -v python)"
+
+    # 3. 安装依赖（EduEvidence 核心零依赖；--dev 额外安装 pytest）
+    if [ "$INSTALL_DEV" = "--dev" ]; then
+        echo "==> 安装开发依赖（pytest）"
+        pip install --quiet --upgrade pip
+        pip install --quiet -e '.[dev]'
+    else
+        echo "==> 安装核心（零第三方依赖）"
+        pip install --quiet --upgrade pip
+        pip install --quiet -e .
+    fi
+
+    # 4. 可选：matplotlib 用于学术图 PNG/PDF 导出（非必需）
+    if python -c "import matplotlib" 2>/dev/null; then
+        echo "    matplotlib: 已安装（学术图 PNG/PDF 可用）"
+    else
+        echo "    matplotlib: 未安装（学术图仍可输出 SVG；PNG/PDF 导出需要 pip install matplotlib）"
+    fi
+
+    # 5. 自检：Schema 校验 + 报告渲染
+    echo "==> 自检：Schema 校验"
+    python scripts/validate_schema.py --schema schemas/verdict.schema.json \
+        --data examples/ai-coding-assistant/verdict.json
+    python scripts/validate_schema.py --schema schemas/evidence.schema.json \
+        --data examples/ai-coding-assistant/evidence.jsonl
+
+    echo "==> 自检：渲染双语 HTML 报告"
+    python visualization/eduevidence-report/scripts/build_report.py \
+        --result examples/ai-coding-assistant/result.json \
+        --out /tmp/eduevidence-smoke.html
+    rm -f /tmp/eduevidence-smoke.html
+
+    # 6. 运行测试（仅 dev 模式）
+    if [ "$INSTALL_DEV" = "--dev" ]; then
+        echo "==> 运行测试"
+        pytest -q
+    fi
+
+    # 7. Agent MCP 声明：写入 AGENT_MCP_INSTALLED=1（~/.eduevidence/env）
+    write_agent_mcp_env
+}
+
+local_finish() {
+    echo ""
+    echo "安装完成。下一步："
+    echo "  1. 查看示例报告:  open examples/ai-coding-assistant/EduEvidence_Report.html"
+    echo "  2. 渲染自己的 result.json（需同时准备 result.zh.json 中文平行数据）:"
+    echo "     python visualization/eduevidence-report/scripts/build_report.py \\"
+    echo "         --result <你的 result.json> --out REPORT.html"
+    echo "  3. Agent MCP: 已写入 ${AGENT_MCP_ENV_FILE}（AGENT_MCP_INSTALLED=1），"
+    echo "     安装并启动 agent-mcp daemon 后 detect 即报 state: available"
+}
+
+# ---------- Skill 安装 ----------
+# 复制 Skill 本体到指定目录（写前自动备份：cp -r 到 .bak-时间戳）
+install_to_dir() {
+    local dest="$1"
+    if [ "$DRY_RUN" -eq 1 ]; then
+        echo "    [dry-run] 将备份已有目录: $dest → $dest.bak-<时间戳>（如存在）"
+        echo "    [dry-run] 将复制: ${SKILL_PAYLOAD[*]} → $dest/"
+        return 0
+    fi
+    if [ -e "$dest" ]; then
+        local bak="${dest}.bak-$(date +%Y%m%d%H%M%S)"
+        cp -r "$dest" "$bak"
+        echo "    已备份: $dest → $bak"
+        rm -rf "$dest"
+    fi
+    mkdir -p "$dest"
+    cp -R "${SKILL_PAYLOAD[@]}" "$dest"/
+    echo "    ✅ 已安装: $dest"
+}
+
+# 安装到单个宿主
+install_one_host() {
+    local host="$1"
+    local dest
+    dest="$(host_skill_root "$host")/$SKILL_NAME"
+    echo ""
+    echo "==> 安装 Skill 到 $host"
+    echo "    目标目录: $dest"
+    install_to_dir "$dest"
+    echo "    提示: 重启 $host 会话后 Skill 即可自动发现（或按宿主机制手动装载）"
+}
+
+# custom：手动指定 skill 根目录
+custom_install() {
+    local dir=""
+    read -r -p "请输入 skill 根目录（将创建 <目录>/$SKILL_NAME/）: " dir || true
+    dir="${dir%/}"
+    dir="${dir/#\~/$HOME}"        # 展开 ~
+    if [ -z "$dir" ]; then
+        echo "ERROR: 未输入目录，取消安装。" >&2
+        exit 1
+    fi
+    echo "==> 安装 Skill 到自定义目录"
+    echo "    目标目录: $dir/$SKILL_NAME"
+    install_to_dir "$dir/$SKILL_NAME"
+}
+
+# 非交互：--host / --dest 指定落点
+skill_install_noninteractive() {
+    local choice="$1"
+    case "$choice" in
+        all)
+            for h in "${HOSTS[@]}"; do install_one_host "$h"; done
+            print_universal_prompt
+            ;;
+        local)
+            echo "==> 仅本地安装：安装 pytest 并运行测试"
+            if [ "$DRY_RUN" -eq 1 ]; then
+                echo "    [dry-run] 将执行: pip install -e '.[dev]' && pytest -q"
+            else
+                pip install --quiet -e '.[dev]'
+                pytest -q
+            fi
+            write_agent_mcp_env
+            ;;
+        custom)
+            echo "ERROR: 非交互模式请使用 --dest <skill根目录>" >&2
+            exit 1
+            ;;
+        *)
+            local found=0 h
+            for h in "${HOSTS[@]}"; do
+                [ "$h" = "$choice" ] && found=1
+            done
+            if [ "$found" -eq 0 ]; then
+                echo "ERROR: 无效宿主: $choice（bash install.sh --list-hosts 查看列表）" >&2
+                exit 1
+            fi
+            install_one_host "$choice"
+            print_universal_prompt
+            ;;
+    esac
+}
+
+# 交互式选择宿主并安装 Skill
+skill_install() {
+    if [ -n "$DEST_ROOT" ]; then
+        echo "==> 安装 Skill 到自定义目录"
+        echo "    目标目录: $DEST_ROOT/$SKILL_NAME"
+        install_to_dir "$DEST_ROOT/$SKILL_NAME"
+        print_universal_prompt
+        return 0
+    fi
+    if [ -n "$HOST_CHOICE" ]; then
+        echo "    已选择: $HOST_CHOICE"
+        skill_install_noninteractive "$HOST_CHOICE"
+        return 0
+    fi
+
+    local i=1 choice="" mark=""
+    echo ""
+    echo "==> 选择安装到哪个宿主 Agent（Skill 落点见: bash install.sh --list-hosts）："
+    for h in "${HOSTS[@]}"; do
+        if host_detect "$h"; then mark="✓ 已探测到"; else mark="未探测到"; fi
+        printf '  %2d) %-9s %s\n' "$i" "$h" "$mark"
+        i=$((i + 1))
+    done
+    printf '  %2d) %-9s 安装到全部 Agent\n' "$i" "all"
+    i=$((i + 1))
+    printf '  %2d) %-9s 手动指定 skill 目录\n' "$i" "custom"
+    i=$((i + 1))
+    printf '  %2d) %-9s 只装本地（venv + pytest + 自检）\n' "$i" "local"
+
+    read -r -p "请输入编号或名称 [claude]: " choice || true
+    choice="${choice:-claude}"
+
+    # 数字编号 → 名称
+    if [[ "$choice" =~ ^[0-9]+$ ]]; then
+        local idx=$((choice - 1))
+        if [ "$idx" -lt "${#HOSTS[@]}" ]; then
+            choice="${HOSTS[$idx]}"
+        else
+            case "$idx" in
+                11) choice="all" ;;
+                12) choice="custom" ;;
+                13) choice="local" ;;
+                *) echo "ERROR: 无效编号" >&2; exit 1 ;;
+            esac
+        fi
+    fi
+    # 名称校验
+    case "$choice" in
+        all|local|custom) ;;
+        *)
+            local found=0 h
+            for h in "${HOSTS[@]}"; do
+                [ "$h" = "$choice" ] && found=1
+            done
+            if [ "$found" -eq 0 ]; then
+                echo "ERROR: 无效选择: $choice" >&2
+                exit 1
+            fi
+            ;;
+    esac
+    echo "    已选择: $choice"
+
+    case "$choice" in
+        local)
+            echo "==> 仅本地安装：安装 pytest 并运行测试"
+            if [ "$DRY_RUN" -eq 1 ]; then
+                echo "    [dry-run] 将执行: pip install -e '.[dev]' && pytest -q"
+            else
+                pip install --quiet -e '.[dev]'
+                pytest -q
+            fi
+            write_agent_mcp_env
+            ;;
+        all)
+            for h in "${HOSTS[@]}"; do install_one_host "$h"; done
+            print_universal_prompt
+            ;;
+        custom)
+            custom_install
+            print_universal_prompt
+            ;;
+        *)
+            install_one_host "$choice"
+            print_universal_prompt
+            ;;
+    esac
+}
+
+# ---------- --list-hosts：显示支持列表与落点 ----------
+list_hosts() {
+    echo "==> EduEvidence 支持的宿主 Agent 与 Skill 落点"
+    printf '  %-10s %-12s %s\n' "宿主" "探测" "Skill 安装落点"
+    printf '  %-10s %-12s %s\n' "----" "----" "----------------"
+    for h in "${HOSTS[@]}"; do
+        if host_detect "$h"; then mark="✓ 已探测到"; else mark="未探测到"; fi
+        printf '  %-10s %-12s %s/%s/\n' "$h" "$mark" "$(host_skill_root "$h")" "$SKILL_NAME"
+    done
+    echo ""
+    echo "  选择 all 安装到全部 Agent；custom 手动指定目录；local 只装本地。"
+    echo "  未列出的 Agent（方式三）：用通用提示词手动安装，详见 README「安装为 Skill」。"
+}
+
+# ---------- 主流程 ----------
+case "$MODE" in
+    list)
+        list_hosts
+        ;;
+    skill)
+        if [ "$SKILL_ONLY" -eq 1 ] || [ -n "$HOST_CHOICE" ] || [ -n "$DEST_ROOT" ]; then
+            echo "==> Skill-only 安装（跳过 venv / pytest）"
+            write_agent_mcp_env
+        else
+            local_setup
+        fi
+        skill_install
+        star_prompt
+        ;;
+    local)
+        local_setup
+        local_finish
+        star_prompt
+        ;;
+esac
+echo ""
+echo "完成。"

package/integrations/__init__.py

@@ -0,0 +1 @@
+"""EduEvidence integration modules."""