aeval-framework 0.3.0__tar.gz → 0.3.1__tar.gz

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aeval-framework
-Version: 0.3.0
+Version: 0.3.1
 Summary: Aeval — open-source agent evaluation framework driven by OTel traces (suites, graders, metrics, storage, API, CLI)
 Project-URL: Homepage, https://github.com/QiYuyyds/Aeval
 Project-URL: Repository, https://github.com/QiYuyyds/Aeval

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/pyproject.toml

@@ -2,7 +2,9 @@
 # Distribution name: aeval-framework (PyPI). Python module: agent_eval, CLI: eval-suite.
 # (`agent-eval` on PyPI belongs to an unrelated project — UK AISI agenteval.)
 name = "aeval-framework"
-version = "0.3.0"
+# 版本只有一个真相源: src/agent_eval/__init__.py 的 __version__ (design D1)。
+# 手工写第二份 (旧的 pyproject `version =`) 才是缺陷 —— dynamic 让它无法被写出来。
+dynamic = ["version"]
 description = "Aeval — open-source agent evaluation framework driven by OTel traces (suites, graders, metrics, storage, API, CLI)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -58,6 +60,9 @@ Changelog = "https://github.com/QiYuyyds/Aeval/blob/main/CHANGELOG.md"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+path = "src/agent_eval/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/agent_eval"]
 # src/agent_eval/packs/** (含 starter pack 的 suite.yaml/manifest.json) 作为

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/src/agent_eval/__init__.py

@@ -11,4 +11,4 @@ Usage:
     result = await runner.run_suite(suite)
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

aeval_framework-0.3.0/src/agent_eval/cli.py → aeval_framework-0.3.1/src/agent_eval/_cli_app.py

@@ -1,46 +1,9 @@
 """
-eval-suite — the Aeval command line.
-
-Commands:
-    run        Execute a suite (default runner: built-in MockAgentRunner).
-               Exit 0 all passed / 1 failed tasks or baseline regression /
-               3 evaluation untrustworthy. --baseline adds a relative
-               regression gate against a stored run
-    validate   Validate a suite without running it
-    list       List runs or suites from the storage DB
-    show       Show one run's details (--task drills into a single task);
-               reports valid/invalid/pending counts, pass@1 95% CI and
-               extrapolation markers
-    compare    A/B compare two runs; overlapping 95% intervals read as
-               "not significant" with no directional verdict, and differing
-               statistics versions or evidence boundaries read as not comparable
-    power      Sample-size planning: trials needed for a target resolution
-               (--delta with an assumed or measured baseline pass rate)
-    serve      Serve the standalone API (/v1) via uvicorn
-
-Source forms (run/validate, spec: suite-distribution): a single suite.yaml
-file (status quo); a pack directory or .tar.gz/.zip archive (integrity-checked
-against manifest.json); a git URL (shallow clone into a temp dir — needs the
-git executable); or the literal "demo" (the built-in starter pack shipped
-inside the wheel; a local file/dir named demo wins with a hint). Temp dirs are
-cleaned up when the command ends.
-
-Holdout (run/validate): tasks marked holdout: true are excluded by default
-and the skip count is reported; --include-holdout runs them. validate reports
-the holdout count without running anything.
-
-Runner selection (run): --runner option > AEVAL_RUNNER env var > "mock"
-(forced "mock" for the built-in demo pack unless --runner is explicit).
-Custom runners register via the "agent_eval.runners" entry-point group
-(name → zero-arg factory returning an AgentRunner).
-
-Trace vocabulary (run): --vocabulary option > AEVAL_TRACE_VOCABULARY env var >
-"otel-genai". The value selects a built-in public-convention preset
-(agent_eval.trace.known_vocabularies()); host-private attribute names still go
-in through default_mapping(extra_entries) in library code, never through the CLI.
-
-Storage (list/show/compare and run persistence): SQLite, ./aeval.db by
-default; override with --db or the AEVAL_DB environment variable.
+eval-suite 的实现体 —— 依赖 typer (发行包 `cli` 可选依赖组里的命令行依赖)。
+
+本模块**不是**入口点: 入口是 `agent_eval/cli.py:main()`, 它必须能在缺少命令行
+依赖时被正常导入并给出指引 (spec: cli)。所以本模块只在入口点确认依赖齐备之后
+才被导入。命令语义与退出码见 `agent_eval.cli` 的模块文档。
 """
 
 from __future__ import annotations

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/src/agent_eval/api/app.py

@@ -184,7 +184,7 @@ def create_app(runner: EvalRunner | None = None) -> FastAPI:
     """
     app = FastAPI(
         title="Aeval API",
-        version="0.1.0",
+        version=package_version(),
         description="Agent Evaluation Framework API",
     )
 

aeval_framework-0.3.1/src/agent_eval/cli.py

@@ -0,0 +1,103 @@
+"""
+eval-suite — the Aeval command line.
+
+本模块是命令行入口点 (`pyproject [project.scripts]`)，**不得在模块期导入
+typer**：发行包无条件生成 `eval-suite` 可执行文件（PEP 621 的 `[project.scripts]`
+是项目级表，无法按可选依赖声明，见 change 的 design D2），所以只装了 core 的人
+手上也有这条命令。它必须在这里被说清楚缺什么，而不是抛一个指向内部依赖的
+traceback (spec: cli)。真正的实现体在 `agent_eval/_cli_app.py`。
+
+Commands:
+    run        Execute a suite (default runner: built-in MockAgentRunner).
+               Exit 0 all passed / 1 failed tasks or baseline regression /
+               3 evaluation untrustworthy. --baseline adds a relative
+               regression gate against a stored run
+    validate   Validate a suite without running it
+    list       List runs or suites from the storage DB
+    show       Show one run's details (--task drills into a single task);
+               reports valid/invalid/pending counts, pass@1 95% CI and
+               extrapolation markers
+    compare    A/B compare two runs; overlapping 95% intervals read as
+               "not significant" with no directional verdict, and differing
+               statistics versions or evidence boundaries read as not comparable
+    power      Sample-size planning: trials needed for a target resolution
+               (--delta with an assumed or measured baseline pass rate)
+    serve      Serve the standalone API (/v1) via uvicorn
+
+Exit codes: 0 放行 / 1 agent 表现未达标 / 2 用法错误 / 3 评测本身不可信 /
+            4 命令行依赖缺失（安装形态不对，见 `MISSING_CLI_DEPENDENCY_EXIT_CODE`）
+
+Source forms (run/validate, spec: suite-distribution): a single suite.yaml
+file (status quo); a pack directory or .tar.gz/.zip archive (integrity-checked
+against manifest.json); a git URL (shallow clone into a temp dir — needs the
+git executable); or the literal "demo" (the built-in starter pack shipped
+inside the wheel; a local file/dir named demo wins with a hint). Temp dirs are
+cleaned up when the command ends.
+
+Holdout (run/validate): tasks marked holdout: true are excluded by default
+and the skip count is reported; --include-holdout runs them. validate reports
+the holdout count without running anything.
+
+Runner selection (run): --runner option > AEVAL_RUNNER env var > "mock"
+(forced "mock" for the built-in demo pack unless --runner is explicit).
+Custom runners register via the "agent_eval.runners" entry-point group
+(name → zero-arg factory returning an AgentRunner).
+
+Trace vocabulary (run): --vocabulary option > AEVAL_TRACE_VOCABULARY env var >
+"otel-genai". The value selects a built-in public-convention preset
+(agent_eval.trace.known_vocabularies()); host-private attribute names still go
+in through default_mapping(extra_entries) in library code, never through the CLI.
+
+Storage (list/show/compare and run persistence): SQLite, ./aeval.db by
+default; override with --db or the AEVAL_DB environment variable.
+"""
+
+from __future__ import annotations
+
+import sys
+
+# 与评测结果 (1/3) 和用法错误 (2) 都区分开，脚本可以只凭退出码判定"安装形态不对"
+MISSING_CLI_DEPENDENCY_EXIT_CODE = 4
+# 缺依赖指引的稳定标记：文本可判别，不需要去匹配 traceback
+MISSING_CLI_DEPENDENCY_TOKEN = "error: missing-cli-dependency"
+
+# `cli` 可选依赖组实际提供的顶层模块 —— 只有缺这些才给安装指引
+_CLI_EXTRA_MODULES = frozenset({"typer", "rich"})
+
+_DISTRIBUTION_NAME = "aeval-framework"
+
+
+def missing_dependency_guidance() -> str:
+    """缺命令行依赖时的可行动指引 (spec: cli「未安装 CLI 依赖时命令行入口必须给出可行动指引」)。"""
+    return (
+        f"{MISSING_CLI_DEPENDENCY_TOKEN}\n"
+        "eval-suite needs the command-line dependencies, which are not installed\n"
+        f"in the {_DISTRIBUTION_NAME} environment. The library itself is fine — only\n"
+        "this command is missing its extras.\n"
+        "\n"
+        f"    pip install \"{_DISTRIBUTION_NAME}[cli]\"\n"
+        "\n"
+        f"(from a source checkout: pip install -e \".[cli]\")\n"
+    )
+
+
+def _is_missing_cli_dependency(exc: BaseException) -> bool:
+    """区分"命令行依赖没装"与"安装坏了/代码本身有 bug"——后者不能被指引用盖住。"""
+    missing = getattr(exc, "name", None) or ""
+    return missing.partition(".")[0] in _CLI_EXTRA_MODULES
+
+
+def main() -> int | None:
+    """Console-script entry point (pyproject [project.scripts])."""
+    try:
+        from agent_eval._cli_app import main as _cli_main
+    except ImportError as exc:
+        if not _is_missing_cli_dependency(exc):
+            raise
+        sys.stderr.write(missing_dependency_guidance())
+        return MISSING_CLI_DEPENDENCY_EXIT_CODE
+    return _cli_main()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/tests/test_cli.py

@@ -10,7 +10,7 @@ import re
 
 from typer.testing import CliRunner
 
-from agent_eval.cli import app
+from agent_eval._cli_app import app
 
 runner = CliRunner()
 
@@ -699,8 +699,8 @@ class TestServeSmoke:
     def test_serve_defaults_are_loopback(self):
         import inspect
 
-        from agent_eval import cli
+        from agent_eval import _cli_app
 
-        sig = inspect.signature(cli.serve)
+        sig = inspect.signature(_cli_app.serve)
         default = sig.parameters["host"].default
         assert getattr(default, "default", default) == "127.0.0.1"

aeval_framework-0.3.1/tests/test_cli_entry_guard.py

@@ -0,0 +1,193 @@
+"""core-only 安装形态下命令行入口的指引 (change fix-version-drift-and-cli-entry-guard,
+组 4 / spec: cli「未安装 CLI 依赖时命令行入口必须给出可行动指引」).
+
+全部用子进程跑真入口点 —— 引导路径的成立与否取决于"模块导入期碰不到 typer"，
+进程内 import 早就把模块缓存好了，测不到那一层。
+"""
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import agent_eval
+from agent_eval.cli import (
+    _CLI_EXTRA_MODULES,
+    MISSING_CLI_DEPENDENCY_EXIT_CODE,
+    MISSING_CLI_DEPENDENCY_TOKEN,
+)
+
+PACKAGE_ROOT = Path(agent_eval.__file__).parent
+CHILD_ENV = {**os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONPATH": str(PACKAGE_ROOT.parent)}
+
+# 屏蔽指定顶层模块后再走真入口点，模拟"该依赖没装"
+GUARD_PROBE = """
+import sys
+
+
+class _Blocker:
+    def __init__(self, names):
+        self.names = set(names)
+
+    def find_spec(self, name, path=None, target=None):
+        if name in self.names or name.partition(".")[0] in self.names:
+            raise ModuleNotFoundError(f"No module named {{name!r}}", name=name)
+        return None
+
+
+sys.meta_path.insert(0, _Blocker([{blocked!r}]))
+sys.argv = ["eval-suite", *{argv!r}]
+from agent_eval.cli import main
+
+sys.exit(main())
+"""
+
+CLI_ARGS = ["--help", "run --help", "validate --help", "list --help", "show --help",
+            "compare --help", "power --help", "serve --help", "extensions"]
+
+
+def _run_python(body: str, extra_env: dict | None = None, **fmt) -> subprocess.CompletedProcess:
+    env = {**CHILD_ENV, **(extra_env or {})}
+    return subprocess.run(
+        [sys.executable, "-c", body.format(**fmt)],
+        capture_output=True, text=True, encoding="utf-8", env=env,
+    )
+
+
+def _module_entry(module: str, args: str, extra_env: dict | None = None) -> subprocess.CompletedProcess:
+    env = {**CHILD_ENV, **(extra_env or {})}
+    return subprocess.run(
+        [sys.executable, "-m", module, *args.split()],
+        capture_output=True, text=True, encoding="utf-8", env=env,
+    )
+
+
+# 两条路径都在 -c 子进程里跑并把 argv[0] 钉成 eval-suite —— 与真 console script 同形，
+# click 由此算出同一个 prog_name，剩下的字节差只可能来自引导层。
+RUN_ENTRY = """
+import sys
+sys.argv = ["eval-suite", *{argv!r}]
+from agent_eval.cli import main
+
+sys.exit(main())
+"""
+RUN_IMPL = """
+import sys
+sys.argv = ["eval-suite", *{argv!r}]
+from agent_eval._cli_app import app
+
+app()
+"""
+
+
+class TestNormalPathIsUntouched:
+    """Scenario: 已装齐依赖时零影响 —— 引导路径完全不介入。"""
+
+    def test_entry_module_import_alone_never_touches_typer(self):
+        """改动前 `import agent_eval.cli` 就会 ModuleNotFoundError; 入口模块必须与依赖解耦。"""
+        body = """
+import sys
+import agent_eval.cli
+print("typer" in sys.modules, "agent_eval._cli_app" in sys.modules)
+"""
+        resp = _run_python(body)
+        assert resp.returncode == 0, resp.stderr
+        assert resp.stdout.strip() == "False False", resp.stdout
+
+    def test_bootstrap_adds_zero_bytes_and_zero_exit_code_shift(self):
+        """主闸: 走入口点的输出与退出码, 和直接跑实现体逐字节相同。"""
+        for args in CLI_ARGS:
+            argv = args.split()
+            through_entry = _run_python(RUN_ENTRY, argv=argv)
+            direct = _run_python(RUN_IMPL, argv=argv)
+            label = f"[{args}]"
+            assert through_entry.stdout == direct.stdout, f"{label} stdout 变了"
+            assert through_entry.stderr == direct.stderr, f"{label} stderr 变了"
+            assert through_entry.returncode == direct.returncode, f"{label} 退出码变了"
+
+    def test_guidance_text_is_absent_when_dependencies_are_installed(self):
+        from agent_eval.cli import missing_dependency_guidance
+
+        guidance_word = "pip install"
+        for args in CLI_ARGS:
+            resp = _module_entry("agent_eval.cli", args)
+            assert guidance_word not in resp.stdout + resp.stderr, args
+        assert guidance_word in missing_dependency_guidance()
+
+    def test_run_demo_still_exits_zero_through_the_entry(self, tmp_path):
+        """正常路径不止 help: 真跑一次内置套件仍按既有语义给码 (0=放行)。"""
+        resp = _module_entry(
+            "agent_eval.cli", "run demo", extra_env={"AEVAL_DB": str(tmp_path / "demo.db")}
+        )
+        assert resp.returncode == 0, resp.stdout + resp.stderr
+        assert "Status: completed" in resp.stdout
+
+
+class TestMissingCliDependencyGuidance:
+    """Scenario: 裸装后执行命令行 —— 得到的是指引，不是指向内部依赖的 traceback。"""
+
+    def test_missing_typer_yields_actionable_guidance(self, tmp_path):
+        resp = _run_python(GUARD_PROBE, blocked="typer", argv=["--help"])
+        out = resp.stdout + resp.stderr
+        assert resp.returncode != 0
+        assert "pip install" in out and "[cli]" in out, out
+        assert "eval-suite" in out
+
+    def test_output_is_not_a_typer_traceback(self):
+        resp = _run_python(GUARD_PROBE, blocked="typer", argv=["--help"])
+        out = resp.stdout + resp.stderr
+        assert "Traceback" not in out, out
+        assert "No module named 'typer'" not in out, out
+        assert "agent_eval/_cli_app.py" not in out.replace("\\", "/"), out
+
+    def test_handled_module_set_matches_the_declared_cli_extra(self):
+        """守护集合不许和发行声明漂移 —— `cli` 组改了这里就得改。"""
+        tomllib = pytest.importorskip("tomllib")
+        pyproject = PACKAGE_ROOT.parent.parent / "pyproject.toml"
+        if not pyproject.is_file():
+            pytest.skip("发行环境不随包带 pyproject.toml")
+        declared = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"][
+            "optional-dependencies"
+        ]["cli"]
+        tops = {re.match(r"\s*([A-Za-z0-9._-]+)", r).group(1) for r in declared}
+        assert tops == set(_CLI_EXTRA_MODULES), (tops, set(_CLI_EXTRA_MODULES))
+
+    def test_rich_is_not_an_import_time_dependency_of_the_entry(self):
+        """记录实测边界: 缺 typer 才是裸装形态的真实故障点 (rich 由 typer 在渲染期拉入)。"""
+        resp = _run_python(GUARD_PROBE, blocked="rich", argv=["--help"])
+        assert "No module named 'rich'" in resp.stderr or resp.returncode != 0
+        assert resp.returncode != MISSING_CLI_DEPENDENCY_EXIT_CODE
+
+    def test_unrelated_import_failure_is_not_masked_by_the_guidance(self):
+        """安装坏了/代码自身有 bug 时不许用"请装 [cli]"盖住 —— 那会把人引到错路上。"""
+        resp = _run_python(GUARD_PROBE, blocked="agent_eval.core.types", argv=["--help"])
+        out = resp.stdout + resp.stderr
+        assert resp.returncode != 0
+        assert "Traceback" in out, "非依赖缺失的导入失败必须照原样抛出来"
+        assert "pip install" not in out, out
+
+
+class TestExitCodeIsScriptDiscriminable:
+    def test_missing_dependency_code_is_distinct_from_every_outcome(self):
+        """4.4: 成功与两种失败不共用一个码 (0 放行 / 1 表现 / 2 用法 / 3 不可信 / 4 缺依赖)。"""
+        assert MISSING_CLI_DEPENDENCY_EXIT_CODE == 4
+        assert len({MISSING_CLI_DEPENDENCY_EXIT_CODE, 0, 1, 2, 3}) == 5
+
+    def test_missing_dependency_run_reports_the_documented_code(self):
+        resp = _run_python(GUARD_PROBE, blocked="typer", argv=["--help"])
+        assert resp.returncode == MISSING_CLI_DEPENDENCY_EXIT_CODE
+
+    def test_guidance_carries_a_stable_machine_readable_token(self):
+        resp = _run_python(GUARD_PROBE, blocked="typer", argv=["--help"])
+        out = resp.stdout + resp.stderr
+        assert MISSING_CLI_DEPENDENCY_TOKEN in out
+        # 脚本只需匹配这一行，不需要读安装表达式的具体写法
+        assert out.strip().splitlines()[0].startswith(MISSING_CLI_DEPENDENCY_TOKEN)
+
+    def test_normal_path_never_emits_the_token(self):
+        for args in CLI_ARGS:
+            resp = _module_entry("agent_eval.cli", args)
+            assert MISSING_CLI_DEPENDENCY_TOKEN not in resp.stdout + resp.stderr, args

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/tests/test_discovery.py

@@ -221,7 +221,7 @@ def test_same_name_conflict_raises_listing_both_sources(monkeypatch):
 
 def test_cli_extensions_listing_shows_builtin_and_discovered(monkeypatch):
     """eval-suite extensions: 内置 + 被发现的 (标注来源包)。"""
-    from agent_eval.cli import app
+    from agent_eval._cli_app import app
 
     patch_entry_points(
         monkeypatch,
@@ -240,8 +240,8 @@ def test_cli_extensions_listing_shows_builtin_and_discovered(monkeypatch):
 
 def test_cli_and_rest_meta_list_same_names(monkeypatch):
     """CLI 清单与 /meta 能力清单给出的自定义判据名字集合相同。"""
+    from agent_eval._cli_app import app
     from agent_eval.api.app import meta_payload
-    from agent_eval.cli import app
 
     patch_entry_points(
         monkeypatch,

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/tests/test_holdout_and_canary.py

@@ -12,7 +12,7 @@ from pathlib import Path
 import pytest
 from typer.testing import CliRunner
 
-from agent_eval.cli import app
+from agent_eval._cli_app import app
 from agent_eval.core.runner import EvalRunner, NoRunnableTasksError
 from agent_eval.core.suite import SuiteLoadError, load_suite
 from agent_eval.core.types import RunResult

{aeval_framework-0.3.0 → aeval_framework-0.3.1}/tests/test_packaging.py

@@ -401,7 +401,7 @@ class TestCliSourceForms:
     def test_run_tar_gz_source_completes(self, tmp_path):
         from typer.testing import CliRunner
 
-        from agent_eval.cli import app
+        from agent_eval._cli_app import app
 
         root = _make_pack(tmp_path)
         archive = _tar_pack(tmp_path, root, name="suite-pack.tar.gz")
@@ -417,7 +417,7 @@ class TestCliSourceForms:
 
         from typer.testing import CliRunner
 
-        from agent_eval.cli import app
+        from agent_eval._cli_app import app
 
         repo = tmp_path / "suite-repo"
         repo.mkdir()

aeval_framework-0.3.1/tests/test_version_single_source.py

@@ -0,0 +1,131 @@
+"""版本出口同源 (change fix-version-drift-and-cli-entry-guard, 组 2 / spec: rest-api).
+
+钉住三件事:
+1. 同一进程内接口文档版本 / 能力清单版本 / 版本响应头三处相等;
+2. 寄宿挂载形态与独立部署形态读到的接口文档版本相同;
+3. `api/` 下不存在第二处写死的版本号字面量 —— 静态扫描, 防的是"新增第二处"。
+"""
+
+import ast
+import re
+from pathlib import Path
+
+from starlette.testclient import TestClient
+
+import agent_eval.api
+from agent_eval.api.app import create_app, meta_payload, package_version
+from agent_eval.api.standalone import create_standalone_app
+
+VERSION_LITERAL = re.compile(r"\d+\.\d+\.\d+[\w.+-]*")
+API_ROOT = Path(next(iter(agent_eval.api.__path__)))
+
+
+def _doc_string_nodes(tree: ast.AST) -> set[int]:
+    """docstring 常量节点 id —— 叙述历史版本的文字不是版本声明。"""
+    out = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef):
+            first = node.body[0] if node.body else None
+            if (
+                isinstance(first, ast.Expr)
+                and isinstance(first.value, ast.Constant)
+                and isinstance(first.value.value, str)
+            ):
+                out.add(id(first.value))
+    return out
+
+
+def _version_literals_in(source: str, path: Path) -> list[str]:
+    tree = ast.parse(source)
+    docstrings = _doc_string_nodes(tree)
+    offenders = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Constant) or id(node) in docstrings:
+            continue
+        if isinstance(node.value, str) and VERSION_LITERAL.fullmatch(node.value):
+            loc = path.relative_to(API_ROOT.parent).as_posix()
+            offenders.append(f"{loc}:{node.lineno} = {node.value!r}")
+    return offenders
+
+
+class TestVersionOutletsSameSource:
+    def test_openapi_meta_and_header_agree_in_one_process(self):
+        """Scenario: 同一进程对外声明的版本只有一个来源 (独立部署形态三出口齐全)。"""
+        app = create_standalone_app()
+        doc_version = app.openapi()["info"]["version"]
+        with TestClient(app) as client:
+            meta_version = client.get("/v1/meta").json()["version"]
+            header = client.get("/v1/health").headers["X-Aeval-Version"]
+
+        resolved = package_version()
+        assert doc_version == resolved, doc_version
+        assert meta_version == resolved, meta_version
+        assert header == resolved, header
+
+    def test_hosted_openapi_and_meta_agree(self):
+        """寄宿形态自己那两处出口同样同源 (它没有版本头, 那是独立部署专属)。"""
+        app = create_app()
+        resolved = package_version()
+        assert app.openapi()["info"]["version"] == resolved
+        assert meta_payload()["version"] == resolved
+
+    def test_mounted_openapi_served_under_prefix_matches(self):
+        """独立部署里内层 app 被挂到 /v1, 它自己的接口文档也是同一版本。"""
+        with TestClient(create_standalone_app()) as client:
+            resp = client.get("/v1/openapi.json")
+        assert resp.status_code == 200
+        assert resp.json()["info"]["version"] == package_version()
+
+    def test_bumping_the_package_version_moves_every_outlet(self):
+        """Scenario: 升级包版本后所有出口同步 —— 不改任何接口层代码。"""
+        import agent_eval.api.app as app_module
+        import agent_eval.api.standalone as standalone_module
+
+        bumped = "9.9.9"
+        original = app_module.package_version
+        assert package_version() != bumped
+        app_module.package_version = lambda: bumped
+        standalone_module.package_version = lambda: bumped
+        try:
+            app = create_standalone_app()
+            with TestClient(app) as client:
+                assert app.openapi()["info"]["version"] == bumped
+                assert client.get("/v1/meta").json()["version"] == bumped
+                assert client.get("/v1/health").headers["X-Aeval-Version"] == bumped
+            assert create_app().openapi()["info"]["version"] == bumped
+            assert meta_payload()["version"] == bumped
+        finally:
+            app_module.package_version = original
+            standalone_module.package_version = original
+
+
+class TestDeploymentFormsAgree:
+    def test_mounted_and_standalone_read_the_same_doc_version(self):
+        """Scenario: 两种部署形态给出同一版本 —— 挂载形态不得成为例外。"""
+        hosted = create_app().openapi()["info"]["version"]
+        standalone = create_standalone_app().openapi()["info"]["version"]
+        assert hosted == standalone == package_version()
+
+
+class TestNoSecondVersionLiteral:
+    def test_api_source_is_found_by_the_scan(self):
+        """一条永远绿的守护测试比没有更糟 —— 先确认扫描真的覆盖了 api/ 源码。"""
+        scanned = sorted(p.name for p in API_ROOT.rglob("*.py"))
+        assert {"app.py", "standalone.py"} <= set(scanned), scanned
+
+    def test_guard_actually_catches_a_planted_literal(self):
+        """守护测试自己得是活的: 手工植入一处字面量必须被抓到并报出位置。"""
+        planted = 'app = FastAPI(title="Aeval API", version="0.1.0")\n'
+        offenders = _version_literals_in(planted, API_ROOT / "planted.py")
+        assert len(offenders) == 1, offenders
+        assert offenders[0].endswith("planted.py:1 = '0.1.0'"), offenders
+
+    def test_api_layer_has_no_hardcoded_version_string(self):
+        """Scenario: 出现第二处版本字面量时测试失败并报出该位置。"""
+        offenders = []
+        for path in sorted(API_ROOT.rglob("*.py")):
+            offenders += _version_literals_in(path.read_text(encoding="utf-8"), path)
+
+        assert not offenders, (
+            "api/ 下出现写死的版本号字面量, 必须改走 package_version(): " + "; ".join(offenders)
+        )