添加 API 依赖

API 以 run.halo.contentsafety:api 发布。消费方只把它作为编译期依赖，不要通过 implementation 打入自己的插件；请将 <version> 替换为实际发布版本。

dependencies {
    compileOnly 'run.halo.contentsafety:api:<version>'
    testCompileOnly 'run.halo.contentsafety:api:<version>'
    testRuntimeOnly 'run.halo.contentsafety:api:<version>'
}

声明可选插件依赖

在 plugin.yaml 中把内容安全声明为可选依赖（键名末尾加 ?）：

spec:
    requires: ">=2.27.0"
    pluginDependencies:
        content-safety?: ">=1.0.0 & <2.0.0"

可选依赖只解决类可见性和启动顺序。所有直接引用 ContentSafetyService、ContentSafetySceneContributor 等 API 类型的 Bean 都必须通过条件注册的 @Configuration 创建，不能在普通 @Component 上只加条件：

@Configuration
@ConditionalOnClass(name = "run.halo.contentsafety.api.ContentSafetyService")
class ContentSafetyConfiguration {
    // 在这里通过 @Bean 创建引用内容安全类型的适配器。
}

贡献场景

实现 ContentSafetySceneContributor，返回不可变的场景定义：

public class MyScenes implements ContentSafetySceneContributor {
    @Override
    public List<SceneDefinition> scenes() {
        return List.of(new SceneDefinition(
            "my-plugin:submission",
            "my-plugin",
            "业务提交",
            "在保存业务数据前检查标题和正文。",
            Set.of(ContentType.TEXT, ContentType.IMAGE)));
    }
}

通过上面的条件配置注册，并声明 ExtensionDefinition：

apiVersion: plugin.halo.run/v1alpha1
kind: ExtensionDefinition
metadata:
    name: my-plugin-content-safety-scenes
spec:
    className: example.MyScenes
    extensionPointName: content-safety-scenes
    displayName: 业务内容检查场景

• 场景 ID 使用 插件 ID:名称 形式，前缀必须与 pluginId 一致。
• displayName 和 description 面向管理员，使用中文说明检测发生在哪里。
• contentTypes 至少声明一项，只声明实际会提交的内容类型。
• 重复 ID 会被忽略并记录警告，内置场景优先。停用插件会移除动态场景，但保留已保存配置。
• 新场景默认关闭，必须由管理员在「检测场景」中明确启用。

检测后再保存

把 API 调用放在条件注册的适配组件里，业务入口只注入消费方自己的接口。下面是一个完整的文本检测适配器：

public interface ContentCheck {
    Mono<Void> inspect(String scene, String actor, String resourceId, String correlationId, String text);
}

class ContentSafetyCheck implements ContentCheck {
    private final ExtensionGetter extensionGetter;

    ContentSafetyCheck(ExtensionGetter extensionGetter) {
        this.extensionGetter = extensionGetter;
    }

    @Override
    public Mono<Void> inspect(
            String scene, String actor, String resourceId, String correlationId, String text) {
        return extensionGetter.getEnabledExtension(ContentSafetyService.class)
            .flatMap(service -> service.inspect(new InspectionRequest(
                scene, actor, resourceId, correlationId,
                List.of(new InspectionInput("text", text, null, null)))))
            .doOnNext(InspectionReport::requireAllowed)
            .onErrorMap(
                InspectionRejectedException.class,
                error -> new ResponseStatusException(
                    error.report().outcome() == InspectionReport.Outcome.BLOCK
                        ? HttpStatus.UNPROCESSABLE_ENTITY
                        : HttpStatus.SERVICE_UNAVAILABLE,
                    "提交未通过内容安全检查",
                    error))
            .then();
    }
}

业务入口在保存前执行检测；组件不存在时直接保存：

Mono<Void> check = checkProvider.getIfAvailable() == null
    ? Mono.empty()
    : checkProvider.getObject().inspect(scene, actor, resourceId, correlationId, text);
return check.then(Mono.defer(this::saveBusinessData));

• 未安装或未启用内容安全时，适配组件不存在，业务照常保存。这不表示内容已通过检测。
• 适配组件存在但 getEnabledExtension 返回空时，应按“站点未配置检测”处理；业务不能接受这种降级时，应在适配组件内显式返回错误。
• 场景未启用时，inspect 返回 SKIPPED，业务照常保存；同样不能当作已检测。
• 场景启用后，PASS 放行，BLOCK / ERROR 阻止保存。
• actor 必须来自可信认证上下文；resourceId 和 correlationId 只用于记录，不是幂等键。
• 检测必须发生在保存最终内容之前，修改内容后需要重新检测。检测通过不代表业务保存成功。

结果与错误处理

report.requireAllowed() 在 PASS、SKIPPED 之外抛出携带报告的 InspectionRejectedException。调用方应把 BLOCK 映射为 422，把 ERROR 映射为 503；频率、每日额度或容量限制可映射为 429，并在 retryAfterSeconds 非空时附 Retry-After。不要把异常 message 或原因码直接作为 UI 文案。

内容安全已启用时，未知场景、无效请求和 SQLite 故障仍可能以 Mono error 返回。调用方应传播失败，不能 onErrorResume 为通过。API 不提供“跳过检测”参数，也不执行业务写入；业务插件仍须对自身入口做鉴权、请求体限额和必要的 IP 频率控制。

输入与调用限制

• 一个请求最多 32 项输入，id 在整个请求内唯一。
• 每项输入只能提供 text、image 字节、attachmentName 中的一项，不能传 URL 让检测服务下载。
• 文本硬上限为 10000 个 UTF-16 单元；启用阿里云时，单个字段超过 600 个 UTF-16 单元会被拒绝。
• 图片仅支持静态 PNG / JPEG，单图不超过 2 MiB、2500 万像素；每次最多 10 图，可按场景收紧。
• 超过启用的限制时整批拒绝，付费调用前校验，不截断、不拆分。
• 检测受场景频率、全站并发、服务商每日额度和 15 秒总体期限控制。

接入验证

安装内容安全插件和消费方插件后，至少验证：

1. 未安装或未启用内容安全时，消费方插件正常启动，业务数据正常写入，且不产生检测记录。
2. 安装并启用内容安全后，消费方的场景出现在「检测场景」中，且默认关闭。
3. 场景启用后，违规内容或检测故障被拒绝，且不写入业务数据。