---
title: 插件清单
description: 在根目录的 plugin.json 中定义可移植的插件标识和元数据。
---

# 插件清单



每个 Agent Plugin 的根目录都只包含一个可移植清单 `plugin.json`。该文档必须是 JSON 对象，并且必须声明规范的 Schema 标识符和插件名称。

## 最小清单 [#最小清单]

```json title="plugin.json"
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "deployment.tools"
}
```

清单 Schema 是封闭的。可移植的顶层字段仅限于：

| 字段            |  必填 | 用途                                                     |
| ------------- | :-: | ------------------------------------------------------ |
| `$schema`     |  是  | 选择完整的 Agent Plugins 验证和解释约定。                           |
| `name`        |  是  | 供人阅读的插件名称和包标识符。                                        |
| `version`     |  否  | 插件版本；建议采用语义化版本。                                        |
| `description` |  否  | 插件的简短说明。                                               |
| `author`      |  否  | 包含可选 `name`、`email` 和 `url` 字符串的对象。                    |
| `homepage`    |  否  | 文档或主页字符串。                                              |
| `repository`  |  否  | 源代码仓库字符串。                                              |
| `license`     |  否  | 许可证字符串；建议使用 [SPDX 许可证标识符](https://spdx.org/licenses/)。 |
| `keywords`    |  否  | 用于搜索和发现的字符串数组。                                         |
| `extensions`  |  否  | 以反向域名命名空间为键的客户端自有数据。                                   |

元数据字符串即使不符合 URL、电子邮件、语义化版本或 SPDX 语法，也不会仅因此被拒绝，但其 JSON 类型仍为强制要求。

## 名称限制 [#名称限制]

插件名称长度为 1 至 64 个字符，只能使用小写 ASCII 字母、数字、连字符和句点。名称必须以字母或数字开头和结尾，且不能包含 `--` 或 `..`。

**有效：** `my-plugin`、`acme.tools`、`lint3r`

**无效：** `My-Plugin`、`-start`、`has--double`、`too.many..dots`

## 未知字段和无效字段 [#未知字段和无效字段]

未知顶层字段违反 Schema，但不会使其他部分有效的插件失效：客户端会报告并忽略该字段。客户端专属数据应放在 `extensions` 下。

其他清单 Schema 违规均为致命错误。客户端必须拒绝插件，且不得发现或执行其中的组件。

## 规范 Schema [#规范-schema]

下载 [`plugin.schema.json`](/schemas/1.0.0/plugin.schema.json)。如果规范文本与机器可读 Schema 冲突，以规范文本为准。


---

Source: [content/docs/plugin-authors/manifest.mdx](https://github.com/agentplugins/agent-plugins-site/blob/237bbf575f5843214923419f9d0933852662f4f3/content/docs/plugin-authors/manifest.mdx)
Source commit: 237bbf575f5843214923419f9d0933852662f4f3

---

For a semantic overview of all documentation, see [/zh/sitemap.md](/zh/sitemap.md)

For an index of all available documentation, see [/zh/llms.txt](/zh/llms.txt)