APEX

该仓库将 APEX 防御器、基准数据归一化、可信能力清单以及比较方法集成相互分离，以便每一层都能被独立检查。

安装

python -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
export PYTHONPATH="$PWD/src:$PWD"

由模型支持的组件从环境变量中读取 OPENAI_API_KEY 以及可选的 OPENAI_BASE_URL。仅将 .env.example 作为参考复制； 代码不会读取本地凭据文件。

仓库结构图

路径	职责
src/apex/defender/	APEX 任务契约、类型化绑定、回执、证明检查、PLANT、WRAP 以及续接处理
src/apex/core/	共享协议、结果类型、聚合以及提供商中立的模型边界
benchmark/adapter/	将基准发布版本只读转换为统一的 BenchmarkCase 接口
benchmark/registry/	可信能力注册以及各基准专属清单
baseline/<name>/	每种对比方法对应一个实现或运行时集成
tests/	仓库不变量与快速单元检查

有关组件流程和扩展点，请参见 STRUCTURE.md。

加载基准用例

全部六个基准的紧凑冻结用例描述符均包含在 benchmark/data/ 下。完整的上游仓库和运行时沙箱未随仓库提供。 传入 None 会选择打包数据；显式指定 data_root 仍可覆盖该选择。

from benchmark.adapter import adapter_for

adapter = adapter_for("scr", None)
attack_cases = list(adapter.cases("attack"))

适配器负责用例标识符、划分标签、套件标签、资格判定，以及呈现给基准运行时的载荷。它不会更改基准内容，也不会注册工具权限。

加载受信任的清单

from benchmark.registry import module_for

registry = module_for("mcptox")
environment_plan = registry.load("12306-mcp")

能力清单与数据集适配器分开保存，因为基准测试文本是不可信的 episode 输入，而清单描述的是 episode 之前可用的、由操作者拥有的执行边界。

每个 benchmark/registry/data/<benchmark>/manifest.json 都是使用 apex-benchmark-registry-v2 的最终注册表产物。一个 bundle 存储去重后的 capability_units、可复用环境以及显式用例绑定。因此，一个包含数百个用例的基准测试不会将相同的 Tool 清单重复数百次。每个单元保留精确的输入/输出 schema、effect、observation、effect_return、receipt 角色以及类型化注解。每个环境分别记录来源、Skills 和 agent_visible_surface。

来自实验实现的精确审计源输入保存在 benchmark/registry/source/ 下。构建步骤会对这些现有注册进行规范化与去重；它不会从基准测试提示中推断新的能力语义。使用以下命令重新生成所有最终产物：

pip install -e '.[registry]'
python scripts/build_registry_manifests.py
python scripts/audit_registry_coverage.py

要从本地上游检出刷新打包的用例描述符，请运行：

python scripts/import_benchmark_data.py \
  --research-root <research-checkout> \
  --scr-root <SCR_Bench-checkout>

SCR 导入器在推导其紧凑的 case/Skill 暴露索引之前，会先验证固定的提交。

APEX 执行流程

1. TaskContractor 将可信的用户请求编译为任务契约。
2. 基准注册表提供干净的能力面。
3. 引擎解析类型化值，并将观测结果记录为回执。
4. PLANT 检查任务级来源和承诺结构。
5. WRAP 根据契约和回执检查完整的拟议效果。
6. 引擎返回允许、拒绝、修复或重新规划的延续信息。

确定性检查保持独立于目标模型。由模型支持的角色提交类型化候选，这些候选必须通过相同的验证边界。

基线

baseline/registry.py 定义了 13 种比较方法。每种方法都有一个以该方法命名的专用文件夹，以及一个 implementation.py 入口点。具有自身运行时的依赖项采用惰性导入，因此无需安装所有基准环境即可测试 APEX 核心和数据适配器。

验证

python -m compileall -q src benchmark baseline tests
pytest

发布前，还请运行 ANONYMITY.md 中的匿名性检查。提交内容中不应添加任何凭据、结果文件、机器特定 路径、Git 远程仓库或作者元数据。