---
title: "认证插件与无状态组件"
description: "认证插件为什么共享 Worker，以及 stateless-v1 组件规范。"
---

**认证插件**不是普通安全徽章，而是平台对某个精确、不可变插件版本授予的跨租户共享执行资格。相同 artifact digest 的安装可以共享一个 Worker、一个 `BasePlugin` 实例和一组组件实例；每个安装只保留轻量的配置、权限与生命周期上下文。这里的“一组组件”指每个已声明组件 manifest 各一个实例，包括 EventListener、Tool、Command、KnowledgeEngine、Parser、Page 和 Runner。

## 声明

```yaml
execution:
  python:
    path: main.py
    attr: Plugin
  sharedRuntime: shared-runtime-v1
  componentModel: stateless-v1
```

两个字段必须同时出现。声明只是申请，不能代替辅助审查、人工批准和精确 artifact 签名。

## 无状态组件规范

- `BasePlugin.initialize()` 和组件 `initialize()` 是进程级初始化，每个 Worker 只运行一次。
- 所有组件实例都可能同时处理不同工作区的调用，必须可重入。
- 在 `BasePlugin` 中使用 `self.get_config()`；在组件中使用 `self.get_plugin_config()` 或 `self.plugin.get_config()` 读取当前安装配置。
- 不得在实例字段或模块全局变量中保存配置、凭据、Workspace/installation ID 或请求数据。
- 不得在 `initialize()` 中读取并保存租户配置。
- 存储、文件、凭据、日志、模型及其他平台能力必须通过 SDK Host API 访问；SDK 从当前 task-local invocation context 取得权限。
- 持久租户状态必须保存在 Host 服务中。进程内 cache 只能保存 artifact 级公共数据，或以完整 installation binding 为 key 并支持撤销清理。
- `stateless-v1` 当前禁止携带租户数据的 detached 后台任务或线程；SDK 尚未提供插件侧所有权/撤销 API。

这些约束为未来 serverless 组件执行保留接口语义；当前版本仍运行长生命周期 Worker，并未提供 serverless 部署模式。

## 配置访问示例

```python
class LookupTool(Tool):
    async def initialize(self):
        self.transport = StatelessHTTPTransport()

    async def call(self, params, **kwargs):
        config = self.get_plugin_config()
        return await self.transport.lookup(config["endpoint"], params)
```

不要这样写：

```python
async def initialize(self):
    self.endpoint = self.plugin.config["endpoint"]
    self.api_key = self.plugin.config["api_key"]
```

共享初始化没有租户配置，因此这段代码会读取空值/旧值或失败；任何把调用配置保存到共享对象的做法都是认证 blocker。

## 兼容旧插件

旧源码和未签名插件包仍兼容 dedicated Worker。在 OSS 中，没有受信任 `stateless-v1` v2 证书的插件按准入策略保持 dedicated；Cloud 可能在安装前拒绝不满足证书策略的插件。已有安装不代表获得新共享资格。仅修改 manifest 而不迁移代码不会通过认证审查。

认证流程仍包括辅助代码审查和人工批准，并将插件身份、版本、digest、`shared-runtime-v1` 与 `stateless-v1` 一起签入证书。提交方式参阅[发布到插件市场](/zh/plugin/dev/publish/market)。