可见性插件

可见性插件用于判断一个资源对当前调用者是否可见。它和鉴权插件经常配合使用，但不是同一件事。

这个区别在 AI 管理中心中尤其重要。Skill、Prompt、AgentSpec 等资源可以是 PUBLIC 或 PRIVATE。一个资源即使已经上线，也可能因为调用者不是 Owner、不是管理员、也没有显式授权而不可见。

适用场景

可见性插件适合处理这些问题：

可见性插件可以独立判断，也可以把显式授权交给当前鉴权插件判断。默认实现采用后一种方式。

默认实现中，可见性插件会把显式可见性权限映射成一个特殊资源：

@@visibility/{namespaceId}/{resourceType}/{resourceName}

然后它把这个资源交给当前鉴权插件做权限判断。这样可以保持职责清晰：

能力	负责内容
鉴权插件	认证身份，并判断身份是否有某个资源的读写权限。
可见性插件	判断资源是否应出现在详情、列表和搜索结果里。

Nacos 默认提供名为 nacos 的可见性实现。它由默认 Nacos 鉴权实现提供，当前主要服务于 AI 管理中心资源。

默认行为如下：

列表和搜索接口不能先分页再在内存中过滤可见性。这样会导致 totalCount 不准、页面为空或延迟不可控。正确做法是在查询条件中提前加入可见性条件。

默认配置中已经包含可见性插件配置：

nacos.plugin.visibility.enabled=true
nacos.plugin.visibility.type=nacos

如果使用默认 nacos 可见性实现，请同时开启 Nacos 鉴权能力。默认实现会复用鉴权上下文中的用户信息。

nacos.core.auth.system.type=nacos
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true

插件专属配置可以使用以下前缀：

nacos.plugin.visibility.{serviceName}.*

例如自定义插件名是 example，可以读取：

nacos.plugin.visibility.example.timeout=3000

自定义可见性插件需要实现 com.alibaba.nacos.plugin.visibility.spi.VisibilityService。

方法	说明
`getVisibilityServiceName()`	返回插件名，需要和 `nacos.plugin.visibility.type` 对应。
`init(properties)`	初始化插件专属配置。
`resolveDefaultScopeForCreate(identity, apiType, resourceType)`	资源创建时，如果请求没有指定 `scope`，返回默认可见性。默认是 `PRIVATE`。
`validateVisibility(identity, action, apiType, resource)`	判断单个资源是否对当前身份可见或可写。
`adviseQuery(identity, action, apiType, queryContext)`	为列表和搜索生成可见性查询建议。

列表和搜索接口会使用 QueryAdvisor 把可见性转换为查询条件。

如果存储层支持条件查询，应优先在存储查询中合并这些条件，而不是把所有资源加载到内存后再过滤。

AI 管理中心资源会同时受到生命周期、可见性和鉴权影响：

更多 AI 资源状态说明，请参考 AI 资源生命周期。