Skip to main content
Clousight Bench 采用核心引擎 + 入口点插件的架构。引擎负责运行基准测试、归属溯源、持久化 schema-0.4 记录,但对任何具体的云平台、任务或数据集一无所知。所有领域相关的内容——benchmark 套件、evaluator、指标、判定、平台适配器、enricher、reaper——均作为插件,在运行时通过 Python 入口点发现。 核心原则：通过编写插件来定制，而非 fork 核心代码。 参考领域随包一同发布，使其开箱即用，同时也为你提供可直接复制的规范示例；你自己的逻辑放在你自己的包中。

​
层次结构

由于参考领域本身也是通过入口点系统注册的，它们并无任何特殊之处——你的插件与之完全平等，是一等公民。

​
入口点分组

在你的包的 pyproject.toml 中声明入口点，即可注册插件。引擎通过 importlib.metadata.entry_points（clousight_bench.core.registry）发现它们： 新增一个 benchmark = 实现 BenchmarkSuite + Evaluator(可选 Metric / judge),注册这些入口点,用 csbench run --benchmark <id> 运行。这是唯一对外的 benchmark 契约——开源与商业套件一视同仁(商业套件从私有包发布同样的入口点)。自插件 API 2.0 起,suite/evaluator 就是唯一的基准轨道——旧的内部 Task 契约已删除。当前插件 API 为 3.0(OTel 原生追踪的破坏性变更;注册表拒绝钉在 2.x 范围的插件)。 打分器三角——三个打分器,三种职责:
  • Evaluator——套件的官方判定(artifacts → measurements),never-re-score 的载体。每套件一个,命名空间 <suite_id>.*。
  • Metric——叠加的、可组合的逐条维度,作用在 evaluator 的 items() 上,产出 <suite_id>.<metric_id>。
  • Judge——Metric 可选用的实现手段(经 clousight_bench.judges 接缝的 LLM 裁判),绝不是第三条打分路径。
适配器的 status 字面量（skeleton / reference / …）不会因安装插件而改变：一个 skeleton 适配器在真实模式下变为可运行，纯粹是因为 get_runtime_provider(<provider>) 现在返回了非 None 的插件——也就是说，安装 provider 插件即可完成连接，无需修改适配器。

​
编写你自己的插件

主要的扩展是一个 benchmark——一个 BenchmarkSuite + Evaluator,用 csbench run --benchmark <id> 运行。它有独立的、可直接复制的完整走查:

新增一个 benchmark

实现一个 Suite + Evaluator,注册两个入口点,运行它。
附加的 metrics 与 判定 遵循同样的模式 (一个类 + 一个 clousight_bench.metrics / .judges 下的入口点)。 一切都从你自己包的 pyproject.toml 入口点发布——你从不改动已安装的 clousight-bench。 一个商业套件/指标/判定/数据集,就是一个注册了同样入口点的私有包;装上它,csbench list 即可发现,由 requires_plugin_api 守护兼容性。 DomainPack + ProviderAdapter 仍是新增一整个产品类别及其 platform 适配器(如一个新云) 的方式;benchmark 本身始终以 BenchmarkSuite + Evaluator 入口点落地。

​
为什么参考逻辑打包在内而非仅供下载

  • 开箱即用：pip install clousight-bench 后即可立即运行 agent-runtime，无需拼装各部件。
  • 它就是模板：参考领域本身就是结构良好的插件的最佳范例；你可以照其形态构建自己的插件。
  • 统一的完整链路：数据平面探针也随核心包一同发布，因此区域内的探针 carrier 只需 pip install clousight-bench[probe]，即可获得与控制平面完全一致的探针逻辑。
  • 源码已在 GitHub 上完全开放，可供阅读、fork 和提交 PR——但首选的定制路径是插件包，而非编辑已安装的源码。