跳到主要内容
版本：0.4.x(Latest)

基本介绍​

AI能力是LinaPro插件系统中的类型化智能能力命名空间。源码插件通过services.AI()访问，动态插件通过plugin.yaml声明service: ai后使用pluginbridge.Default().AI()客户端访问。

根命名空间只负责聚合子能力，不直接追加所有AI方法。每个子能力拥有自己的请求、响应、提供方契约、状态和降级行为。官方提供默认的AI能力实现插件linapro-ai-core，宿主通过插件治理状态判断该提供方是否可服务。

能力阶段：运行期

类型支持：源码插件、动态插件

能力设计​

子能力体系​

AI能力采用聚合子能力模式，每个子能力拥有独立的请求、响应、提供方契约和降级行为：

子能力源码入口动态方法说明
文本AI().Text()text.generate文本生成，支持purpose、档位、消息、输出上限和推理力度
图片AI().Image()image.generate、image.edit图片生成和图片编辑，输入输出以受保护资产引用表达
向量AI().Embedding()embedding.create创建向量嵌入
音频AI().Audio()audio.transcribe、audio.synthesize音频转写和语音合成
视觉AI().Vision()vision.analyze图片、截图、图示和帧内容分析
文档AI().Document()document.analyze、document.cite文档分析和带引用文档问答
安全AI().Safety()safety.moderate文本和资产输入安全审核
视频AI().Video()video.generate、video.edit、video.extend、video.operation.get、video.operation.cancel视频生成、编辑、延展和提供方操作查询或取消

来源身份和治理​

宿主通过aicap.ForPlugin为插件绑定来源身份。该身份进入提供方请求，用于审计、用量归因、问题定位，以及后续插件级配额、限流、档位访问和purpose策略决策。

插件不应在请求中伪造来源插件ID。源码插件只需使用绑定后的services.AI()，动态插件的来源身份由宿主桥接层从当前插件产物和授权缓存状态中生成。

可用性和降级​

每个子能力都支持降级。当未配置提供方或提供方插件不可用时，调用方会收到结构化的不可用状态或错误，而非返回nil服务。插件可先调用Available()或Status()判断能力状态，再决定是否展示入口、降级到规则逻辑或提示管理员配置智能中心。

接口定义​

源码插件接口​

源码插件通过services.AI()访问各子能力。每个子能力提供独立的类型化方法，例如AI().Text().GenerateText(ctx, req)、AI().Image().Generate(ctx, req)等。所有子能力均遵循Available()、Status()、类型化方法的统一模式。

动态插件接口​

动态插件通过hostServices.ai声明授权的子能力方法：

动态方法说明
text.generate文本生成
image.generate图片生成
image.edit图片编辑
embedding.create创建向量嵌入
audio.transcribe音频转写
audio.synthesize语音合成
vision.analyze图片内容分析
document.analyze文档分析
document.cite带引用文档问答
safety.moderate输入安全审核
video.generate视频生成
video.edit视频编辑
video.extend视频延展
video.operation.get提供方操作查询
video.operation.cancel提供方操作取消

能力使用​

源码插件使用​

源码插件通过services.AI()直接访问各子能力。宿主通过aicap.ForPlugin自动注入插件来源身份，插件无需手动管理：

// 在路由注册回调中获取已绑定来源身份的AI服务
aiSvc := registrar.Services().AI()

// 使用文本生成子能力
result, err := aiSvc.Text().GenerateText(ctx, aitext.GenerateRequest{
    Purpose:  "report.summary", 
    Messages: messages,
    Tier:     aitext.TierStandard,
})

需要替换角色权限集合的可信源码插件，应使用services.Admin().Auth().Authz().ReplaceRolePermissions。

动态插件使用​

动态插件在plugin.yaml中声明所需的AI子能力方法：

hostServices:
  - service: ai
    methods:
      - text.generate
      - document.cite

purpose和tier在调用时通过请求DTO传递，不在清单中声明。动态插件通过pluginbridge.Default().AI().Text().GenerateText(ctx, req)等类型化方法调用：

aiSvc := pluginbridge.Default().AI()

result, err := aiSvc.Text().GenerateText(ctx, aitext.GenerateRequest{
    Purpose:  "report.summary",
    Tier:     aitext.TierStandard,
    Messages: messages,
})

设计约束​

  • 方法授权与业务参数分离。 plugin.yaml只声明方法白名单，purpose和tier等业务参数在每次调用时通过请求DTO传递，授权检查和业务校验各司其职。
  • 使用purpose表达业务场景。 purpose不是模型名，也不是供应商名，而是宿主治理、审计和配额使用的业务意图，调用时必须提供。
  • 资产以引用传递。 AssetRef不携带内联文件字节或提供方认证下载地址，插件应使用受保护资产引用。
  • 档位是平台抽象。 basic、standard和advanced由宿主映射到具体模型或提供方，插件不直接绑定供应商内部模型。
  • 元数据不得包含正文。 请求metadata只适合放短审计键，不应包含提示词、响应正文或敏感数据。

相关服务​