> ## Documentation Index > Fetch the complete documentation index at: https://docs.clousight.com/llms.txt > Use this file to discover all available pages before exploring further. # 扩展（插件） > 添加平台、维度、领域或负载引擎。 Clousight Bench 采用**核心引擎 + 入口点插件**的架构。引擎负责运行基准测试、归属溯源、持久化 schema-0.4 记录,但对任何具体的云平台、任务或数据集一无所知。所有领域相关的内容——benchmark 套件、evaluator、指标、判定、平台适配器、enricher、reaper——均作为**插件**,在运行时通过 Python 入口点发现。 核心原则：**通过编写插件来定制，而非 fork 核心代码。** 参考领域随包一同发布，使其开箱即用，同时也为你提供可直接复制的规范示例；你自己的逻辑放在你自己的包中。 ## 层次结构 | 层次 | 内容 | 分发方式 | | - | - | - | | **核心包**（`clousight-bench`） | 引擎（编排器、schema/记录格式、CLI、插件注册表）、插件**契约**（`BenchmarkSuite`、`Evaluator`、`Metric`、`AgentRuntimeAdapter`、`RuntimeProviderPlugin`、`ResourceReaper`、`ResultEnricher`、`DomainPack`）、报告/查询/追踪/汇总工具，以及**数据平面探针**运行时。 | pip 可安装，开源（Apache-2.0） | | **参考领域** | 五个领域——`agent-runtime`、`data-warehouse`、`key-value`、`transactional-db`、`llm`——每个都带一个可运行的参考适配器。领域**不带自研任务**：套件（`BenchmarkSuite` + `Evaluator`）是唯一的基准轨道。 | 捆绑在核心包中，但以*插件*方式注册（见下文） | | **你的插件** | 你的任务、适配器、领域、enricher、reaper。 | 你发布或本地安装的独立 pip 包 | | **商业版（pro）** | 精选数据集、托管服务、SLA、私有适配器。 | 通过相同入口点在顶层安装的私有插件 | 由于参考领域本身也是通过入口点系统注册的，它们并无任何特殊之处——你的插件与之完全平等，是一等公民。 ## 入口点分组 在你的包的 `pyproject.toml` 中声明入口点，即可注册插件。引擎通过 `importlib.metadata.entry_points`（`clousight_bench.core.registry`）发现它们： | 分组 | 提供内容 | 参考示例 | | - | - | - | | `clousight_bench.domains` | `DomainPack`——一组具名的任务 + 适配器 | `agent-runtime` | | `clousight_bench.benchmark_suites` | `BenchmarkSuite`——包装公认的上游基准 harness | `swe-bench` | | `clousight_bench.evaluators` | `Evaluator`——把套件产物转成命名空间化的 `Measurement`(+ 逐项 `items()`) | `official-mmlu-evaluator` | | `clousight_bench.metrics` | `Metric`——可组合的逐项打分器,作用于 `items` 后聚合;一次运行可多个,发出 `.` | `answered-rate` | | `clousight_bench.judges` | `JudgeProvider`——LLM-as-judge(`JudgeModel`)的配置接入工厂,由配置选择;支撑判定型指标 | `openai-compatible` | | `clousight_bench.runtime_providers` | `RuntimeProviderPlugin`——某个 provider 的真实云传输 + 活动探针钩子 | `aliyun` | | `clousight_bench.resource_reapers` | `ResourceReaper`——为 `csbench sweep` 查找并删除孤立云资源 | `aliyun` | | `clousight_bench.enrichers` | `ResultEnricher`——运行后对记录进行丰富处理（例如定价） | `pricing` | | `clousight_bench.span_exporters` | 用于追踪导出的 span 导出器（本地 JSONL 导出器内置在核心里——`core/tracing.py`——不以插件注册） | — | | `clousight_bench.asset_resolvers` | 解析负载资产（数据集、脚本） | — | **新增一个 benchmark = 实现 `BenchmarkSuite` + `Evaluator`**(可选 `Metric` / judge),注册这些入口点,用 `csbench run --benchmark ` 运行。这是唯一对外的 benchmark 契约——开源与商业套件一视同仁(商业套件从私有包发布同样的入口点)。自插件 API 2.0 起,suite/evaluator 就是唯一的基准轨道——旧的内部 `Task` 契约已删除。当前插件 API 为 `3.0`(OTel 原生追踪的破坏性变更;注册表拒绝钉在 2.x 范围的插件)。 **打分器三角**——三个打分器,三种职责: * **`Evaluator`**——套件的官方判定(artifacts → measurements),never-re-score 的载体。每套件一个,命名空间 `.*`。 * **`Metric`**——叠加的、可组合的逐条维度,作用在 evaluator 的 `items()` 上,产出 `.`。 * **`Judge`**——`Metric` 可选用的实现手段(经 `clousight_bench.judges` 接缝的 LLM 裁判),绝不是第三条打分路径。 适配器的 `status` 字面量（`skeleton` / `reference` / …）不会因安装插件而改变：一个 `skeleton` 适配器在真实模式下变为*可运行*，纯粹是因为 `get_runtime_provider()` 现在返回了非 None 的插件——也就是说，安装 provider 插件即可完成连接，无需修改适配器。 ## 编写你自己的插件 主要的扩展是一个 **benchmark**——一个 `BenchmarkSuite` + `Evaluator`,用 `csbench run --benchmark ` 运行。它有独立的、可直接复制的完整走查: 实现一个 Suite + Evaluator,注册两个入口点,运行它。 附加的 **[metrics](/docs/zh/metrics)** 与 **[判定](/docs/zh/judges)** 遵循同样的模式 (一个类 + 一个 `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`，无需拼装各部件。 * **它就是模板**：参考领域*本身*就是结构良好的插件的最佳范例；你可以照其形态构建自己的插件。 * **统一的完整链路**：[数据平面探针](/docs/zh/probe-carrier)也随核心包一同发布，因此区域内的探针 carrier 只需 `pip install clousight-bench[probe]`，即可获得与控制平面完全一致的探针逻辑。 * 源码已在 GitHub 上完全开放，可供阅读、fork 和提交 PR——但*首选*的定制路径是插件包，而非编辑已安装的源码。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.