---
title: Plugin 是什么？
description: 理解统一的 Plugin 模型、实现、Instance 以及 Capability 连接。
---

Plugin 是可以被团队构建、版本化、安装、配置、停用、更新和移除的 App 行为单元。
Agent Tool、Auth provider、Prompt source、Web endpoint 和 Session store 都可以是
Plugin。

Lenso **只有一种 Plugin 模型**。Wasm、原生 Process、Linked Rust 和 Bun 是
Plugin 的实现或执行方式，不是不同的产品类型。

## 你会操作的四个对象

| 名称 | 它回答什么问题 | 示例 |
| --- | --- | --- |
| Plugin Contract | 这个 Release 承诺什么行为和配置？ | `company.uppercase@1.0.0` 提供 Agent Tool Provider |
| Plugin Implementation | 兼容 Host 如何执行这个 Contract？ | Wasm Component 或可信 Process |
| Plugin Instance | App 中存在哪一个已配置副本？ | `company.uppercase/default` |
| Capability | 这个 Plugin 如何与其他 Plugin 协作？ | `lenso.agent.tool-provider@2` |

只有保持相同 Contract 和可观察行为时，一个 Release 才能包含多个实现。Host 会在
解析 App 之前选择一个兼容实现；运行时不会现场跑分，也不会在失败后自动回退到
另一个实现。

一个 App 可以从同一个 Plugin 创建多个 Instance。每个 Instance 都有自己的 key、
配置、资源、生命周期 Generation、endpoint 和 binding。

## 一个具体例子

[第一个 App 教程](/docs/zh/agent/first-app)会创建以下行为：

```text
Plugin Release: company.uppercase@0.1.0
Contract:       提供 lenso.agent.tool-provider@2
Implementations:
  - wasm
  - process
App Instance:   company.uppercase/default
Visible Tool:   company.uppercase
```

删除 Plugin 目录，就会从该 App 删除它的软件包和 Instance。其他 Plugin 不会
直接访问它的私有 Rust 类型、文件或数据表。

## Capability 负责连接 Plugin

Capability 是版本化的角色 Contract。它拥有 operation 和领域值，不拥有传输或
部署方式。consumer 只能收到 resolved App 显式绑定给它的强类型 client。

Capability 支持三种交互形态：

| 形态 | 用途 | 结果 |
| --- | --- | --- |
| Request | 命令或查询 | 一个终结成功结果或 Domain Error |
| Stream | 有界会话 | 强类型消息、half-close 和一个终结结果 |
| Event | 易失 fan-out | 每个订阅者各自的准入结果 |

它们是 Capability operation 的形态，不是 Plugin 类型。一个 Linked Rust Plugin
可以在同一个生命周期中同时提供 Request、Stream 与 Event operation。

依赖会声明基数：必须有一个 provider、可选一个，或允许多个。App resolution
会在启动前闭合所有必需 binding。Plugin 代码不会从运行时 registry 中查找
provider。

## Contract 的所有权

Plugin Contract 拥有：

- Plugin ID 与 Release 版本；
- 配置 Schema 与默认值；
- 提供和依赖的 Capability；
- restart policy 与 criticality；
- 生命周期与状态语义。

每个实现拥有自己的 runtime artifact、target、entrypoint 与 Execution Class。
App owner 拥有 Instance、配置 patch、资源文件和 provider 选择。Host 拥有实际
可用的实现与 Adapter。

下一步阅读[选择 Plugin 开发路径](/docs/zh/core/choose-plugin-path)，决定该如何编写
Plugin。