> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

插件可以把一套完成任务的方法、需要调用的工具，以及可操作的界面组合起来，交给 Agent 持续使用。你不需要理解协议、撰写代码，只需要用自然语言说明想用插件解决的问题，Agent 就能帮你梳理需求、生成插件，并在你验证并确认后发布。

本文介绍插件的基本概念，以及如何创建、测试、发布和管理插件。

## 了解插件 {#hHyipTqtl}

### 什么是插件 {#hCKW2IeTF}

插件是一组可以安装到 Agent 的能力。安装后，Agent 可以按照预设的方法完成任务、调用外部工具，也可以通过 Panel 和你共同处理同一份内容。

例如，你可以创建一个订单对账插件。它可以定期读取不同平台的订单，按照固定规则核对金额，并把异常订单展示在右侧的对账看板中。之后，无论是继续核对新订单，还是调整筛选条件，都不需要重新解释整套工作方法。

与一次性的对话任务相比，插件更适合承载需要反复执行、持续积累或多人复用的工作。

### 为什么需要插件 {#hUGEWx5aj}

对话适合表达意图。任务涉及大量对象、不断变化的数据或需要反复调整的结果时，只向 Agent 描述需求并接收文字回复，往往不够直观。

插件可以帮助 Agent 完成以下工作：

* **沉淀工作方法。** 将固定步骤、判断标准和注意事项交给 Agent，后续不需要重复说明。
* **连接真实工具和数据。** Agent 可以通过 MCP 查询数据、调用外部服务或执行操作，而不是只给出操作建议。
* **提供更合适的工作界面。** 画布、看板、表格、时间线等内容可以通过 Panel 展示和操作，信息更直观。
* **持续完成同一项工作。** 插件可以保留业务数据。你和 Agent 可以围绕同一份结果继续查看、修改和推进任务。
* **复用成熟能力。** 创建并发布后，可以把插件添加到需要它的 Agent；上架到企业团队商店后，还可以提供给团队成员使用。

插件为 Agent 提供完成任务所需的方法和能力；Panel 提供可以共同查看和操作的工作界面。

### 插件的组成 {#hxYZLKmda}

一个插件可以包含 Skill、MCP 和 Panel。创建插件时不要求三者同时存在，Agent 会根据任务选择需要的组成部分。

<!-- @cols-width: 100,400,328 -->
| **组成部分**  | **作用**  | **适合的场景**  |
| --- | --- | --- |
| Skill  | 为 Agent 提供完成任务所需的步骤、知识和判断规则。  | 按固定标准审阅内容、生成周报、执行团队 SOP。  |
| MCP  | 让 Agent 连接外部工具、服务和数据，并执行查询或操作。  | 查询业务数据、更新第三方系统、操作本地软件。  |
| Panel  | 在对话旁提供可查看、可操作的界面，并将你的选择和修改传递给 Agent。  | 编辑画布、查看数据看板、管理任务、处理音视频时间线。  |

例如，一个客户跟进插件可以使用 Skill 规定客户分级和跟进流程，使用 MCP 读取 CRM 数据，再通过 Panel 展示客户列表和待办事项。

### 插件有哪些类型 {#hXKSb6zUO}

按照是否提供独立界面，插件分为以下两类：

* **能力插件**：不包含独立 Panel，主要通过对话使用。它可以是纯 Skill、纯 MCP，也可以同时包含 Skill 和 MCP。适合结果主要以文字或文件交付、不需要长期操作界面的任务。
* **交互式插件**：包含一个或多个 Panel，并可以按需搭配 Skill 和 MCP。适合需要持续查看信息、选择对象或直接修改内容的任务。

如果用户需要在界面中查看和操作持续变化的内容，例如拖动画布元素、筛选看板数据或管理任务状态，适合创建交互式插件。如果只需要 Agent 按固定流程生成总结或文件，能力插件通常已经足够。

## 创建插件 {#hYg4P4tBi}

你可以使用自然语言从零创建插件，也可以导入已有插件包。

### 使用自然语言创建插件 {#hzL1SkVpd}

创建插件时，不需要先决定具体技术方案。优先说清楚业务问题、使用对象、输入和期望结果，Agent 会据此判断需要哪些能力。

#### 步骤一：描述插件需求 {#hL0qpAtvt}

在 [Agent 私聊或项目](https://www.coze.cn/new-task?surl_token=FJvCs&zlink_code=FFKdE&utm_medium=docs&utm_source=docs&utm_content=landingpage&utm_id=&utm_campaign=&utm_term=docs&utm_source_platform=)中，`@插件创建器`，直接说明你希望创建什么插件。

一段有效的需求通常包含以下信息：

* 要解决什么问题。
* 有哪些可用的 MCP 或技能。
* 是否需要可视化展示。
* 是否需要用户登录或鉴权。

你不需要一次写全。Agent 会继续询问会影响插件形态、权限或安全边界的信息。名称、普通文案、默认布局等细节，可以先让 Agent 给出方案，再在预览阶段调整。

**提示词模板**

```Plain Text
@插件创建器，帮我创建一个插件，名为[插件名称],功能是[功能 1][功能 2][功能 3]，有一个用户界面来[Panel 的作用（可选）]。
```

**提示词示例**

```Plain Text
@插件创建器，帮我创建一个插件，名为[扣子知识问答],功能是通过扣子产品文档 MCP 来查看和检索官方文档、总结提炼信息，并准确回答用户问题。
```

#### 步骤二：补充关键信息 {#hIxtWuQku}

根据 Agent 的提问，确认数据来源、主要操作和使用范围。涉及以下操作时，请重点核对 Agent 给出的说明：

* 付款、下单等交易操作。
* 对外发送消息或发布内容。
* 删除、覆盖或批量修改数据。
* 读取本地目录、操作本地软件或设备。
* 使用敏感数据或扩大账号权限。

这些操作应在真正执行前再次向你展示操作对象、范围和影响。创建插件时同意接入某项能力，不等于提前同意以后发生的每一次敏感操作。

#### 步骤三：等待生成和检查 {#hbTZhQ3Bc}

Agent 会生成插件所需的 Skill、MCP 和 Panel，并自动检查插件结构、能力声明、调用关系和敏感操作确认流程。

生成过程中，你仍然可以补充要求。

生成完成后，插件会进入“草稿预览”。此时可以测试和修改，但还没有正式发布。

### 创建不包含 Panel 的插件 {#hsVIIQWKG}

如果任务主要由 Agent 在后台完成，并且结果可以通过消息或文件返回，可以明确要求创建不包含 Panel 的能力插件。

根据需要，能力插件可以采用以下组合：

* 纯 Skill：主要沉淀知识、规则和工作流程。
* 纯 MCP：主要提供外部数据或工具调用能力。
* Skill + MCP：既规定处理方法，又连接真实工具执行任务。

**示例提示词**

```Plain Text
帮我创建一个合同审阅插件，不需要 Panel。

用户上传合同时，先识别合同类型，再按照我提供的审阅技能来审阅规则检查付款条件、违约责任、知识产权和自动续约条款。输出风险等级、原文位置、风险原因和修改建议。如果信息不足，不要猜测，直接列出需要确认的问题。
```

### 创建包含 Panel 的插件 {#hfX6AOaRY}

如果用户需要持续查看、选择或修改结构化内容，可以要求 Agent 创建交互式插件。

描述 Panel 时，重点说明以下信息即可：

* Panel 中要展示哪些对象，例如订单、图片、任务或指标。
* 用户最常执行哪些操作，例如筛选、拖动、选择、编辑或确认。
* 用户完成操作后，Agent 应如何继续处理。
* 是否需要多个 Panel，以及每个 Panel 分别解决什么问题。

一个插件可以包含多个 Panel。例如，项目管理插件可以分别提供“任务看板”和“进度统计”两个 Panel。它们可以独立打开和调试，但属于同一个插件，共享插件版本和项目业务数据。发布时会发布完整插件，不能只发布其中一个 Panel。

在草稿预览中，你可以切换查看 Web 和移动端的展示效果。

**示例提示词**

```Plain Text
@插件创建器，帮我创建一个插件，名为[扣子知识问答],功能是通过扣子产品文档 MCP 来查看和检索官方文档、总结提炼信息，并准确回答用户问题。需要一个用户界面来让我输入问题/关键词，并展示 Agent 的回复。
```

### 创建需要身份认证的插件 {#hQLIX0u39}

如果插件需要访问飞书、CRM、电商平台等外部服务，你需要在创建时告诉 Agent：连接什么服务、使用什么认证方式、需要哪些权限，以及用户应在什么时候完成认证。

常见认证方式包括：

* **用户自行填写 API Key 或 Token**：在 Skill 中说明配置步骤和使用要求，并让用户通过插件提供的安全配置入口填写。不要把真实 API Key、Token、密码或验证码写进 Skill、提示词或插件包。
* **MCP 身份认证**：MCP 需要用户 Token 或 OAuth 授权时，在插件中声明对应的连接和权限要求。用户首次使用、授权失效或权限范围扩大时，由系统引导其完成认证。
* **本地应用或设备连接**：插件需要操作本地应用、目录或设备时，应声明所需的桌面端环境和连接步骤，并说明未连接时哪些能力不可用。

每位用户使用自己的账号和凭证。团队成员不会继承插件创建者或其他成员的授权，因此测试时要覆盖首次认证、取消认证、凭证失效和重新连接等情况。

**示例提示词**

```Plain Text
@插件创建器，帮我创建一个客户查询插件。插件通过 CRM MCP 查询客户资料，用户首次使用时需要完成 OAuth 授权，只申请读取客户和跟进记录的权限。请不要在插件文件中保存用户 Token；授权失效时，引导用户重新连接账号。
```

### 导入插件包 {#hrilydSgf}

如果你自行开发了插件，或从 Codex、Claude Code 等平台导出了插件包，可以直接导入扣子，不需要重新通过对话创建。插件包需要符合插件规范，并且压缩前、压缩后均小于 500 MB。

1. 进入**扩展 >**[插件](https://www.coze.cn/skills?capability=plugin&tab=space&zlink_code=FFKdE&utm_medium=docs&utm_source=docs&utm_content=landingpage&utm_id=&utm_campaign=&utm_term=docs&utm_source_platform=)，在页面右上角单击**上传插件包。**
2. 点击**选择文件**，上传 ZIP 格式的插件包。
   插件包要求：
   * 符合 [Agent Plugins 1.0.0 协议](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)插件规范，例如在扣子或 Codex 中生成的插件。
   * 压缩前、压缩后均小于 500 MB。
3. 等待系统检查并解析插件包。
4. 在插件资料页面确认插件名称和图标。
5. 点击**保存**。
6. 保存成功后，在**我的插件**中即可查看导入结果。
   如果系统提示该插件已上传，请先到**我的插件**中查找同一插件，不要反复上传。上传失败时，根据页面显示的问题修正插件包，再重新选择文件。
   导入后，建议先检查 Skill、MCP 和 Panel 是否被正确识别，再完成测试和发布。   


## 测试、调优和发布插件 {#hRROPVK9d}

### 预览插件 {#hzvtA4P59}

插件生成并检查通过后，Agent 会发送草稿卡片。点击卡片或对应的 Panel 入口，即可查看草稿。

对于包含 Panel 的插件，你可以分别预览 Web 和移动端效果，检查信息展示、操作流程和多端适配是否符合预期。

### 测试插件 {#hg67HRAFz}

测试时除了检查正常使用流程，还要覆盖失败和异常情况。建议至少检查以下内容：

<!-- @cols-width: 193,531 -->
| **检查项**  | **建议测试方法**  |
| --- | --- |
| 是否会正确使用插件  | 分别输入明确请求、口语化请求和容易混淆的请求，确认 Agent 能在合适的时候调用插件。  |
| MCP 是否可用  | 测试查询、写入和失败场景，确认返回结果来自正确账号和数据范围。  |
| Panel 是否可用  | 点击各个按钮，是否有异常报错、信息展示是否完整。 | \
| | | \
| | 检查信息是否容易找到，选择、编辑和筛选操作是否能被 Agent 正确理解。  |
| 多端是否可用  | 分别预览 Web 和移动端，检查布局、只读能力和不支持状态是否符合预期。  |
| 身份认证是否完整  | 测试首次授权、取消授权、授权失效和重新连接。  |

测试时可以准备一组固定案例，每次修改后重复执行。固定案例应同时包括：最常见的正常任务、信息不完整的任务、边界输入，以及至少一个预期失败的任务。这样更容易判断一次修改是否解决了问题，又是否破坏了原有能力。

### 调优插件 {#hCDDFXh8p}

发现问题后，直接在当前对话中说明出现了什么问题、期望结果是什么，以及如何复现。提供具体案例，可以帮助 Agent 更准确地修改插件。

**示例提示词**

```Plain Text
请修改当前订单对账插件：
1. 退款中的订单不要标记为金额异常，单独归入“退款处理中”。
2. 对账看板默认只显示异常订单，但保留“查看全部”筛选项。
3. 点击订单后，先展示订单号、平台和差额，再让 Agent 分析原因。
4. 保持现有数据，不要创建新的插件。

请修改后重新检查，并停留在草稿预览，不要发布。
```

修改后先复测受影响的场景，再执行一遍原有核心案例。对于多个 Panel 的插件，从任一 Panel 进入调试后，所有 Panel 都属于同一份插件草稿；即使只修改了一个 Panel，再次发布时仍会发布完整插件。

### 发布插件 {#hIrFuZbXU}

草稿测试完成后，发布插件，才能让 Agent 使用正式版本。

你可以使用以下方式触发发布：

* 点击草稿 Panel 顶部的**发布**。
* 在对话中明确要求 Agent 代为发布。

单 Panel 插件或不包含 Panel 的插件会直接进入发布流程。包含多个 Panel 时，如果由你在界面中发布，系统会再次展示本次包含的 Panel 数量；确认后发布完整插件。

发布成功后：

* 插件会出现在[我的插件](https://www.coze.cn/skills?capability=plugin&tab=my?surl_token=FJvCs&zlink_code=FFKdE&utm_medium=docs&utm_source=docs&utm_content=landingpage&utm_id=&utm_campaign=&utm_term=docs&utm_source_platform=)中。
* 在 Agent 私聊中创建插件时，当前 Agent 会安装或更新该插件。
* 在项目中发布插件时，项目会使用最新正式版本；已经启用该插件的 Agent 会自动跟随更新。

如果发布失败，系统会保留当前草稿、上一次成功发布的版本和业务数据。你可以点击**重新尝试**，或选择**交给 Agent 修复**。如果其他人已经发布了更新，系统会阻止当前草稿直接覆盖新版本；Agent 需要基于最新版本重新适配并检查，然后由你再次发布。

## 将插件上架到企业团队商店 {#hTMGDrFQX}

如果希望在团队内共享插件，需要将已经发布的插件上架到企业团队商店。上架后，其他企业成员可以在商店中查看并添加该插件。

企业团队商店默认关闭审核，插件提交后直接自动上架。企业管理员也可以在管理后台开启审核；开启后，插件需要通过审核才能正式上架。正式上架后，企业成员可以在企业团队商店中发现并添加插件。

完成插件发布并准备好展示资料后，可以上架插件：

1. 进入[我的插件](https://www.coze.cn/skills?capability=plugin&tab=my?surl_token=FJvCs&zlink_code=FFKdE&utm_medium=docs&utm_source=docs&utm_content=landingpage&utm_id=&utm_campaign=&utm_term=docs&utm_source_platform=)。
2. 找到要上架的插件，在右侧单击 **···**。
3. 选择**上架到企业商店**。
4. 填写企业商店中的展示名称、简介和截图。
   为了让团队成员快速判断插件是否适用，建议展示信息至少回答三个问题：插件解决什么问题、适合谁使用、使用前需要连接什么账号或设备。截图应展示真实核心界面和关键结果，不要只使用装饰性封面。
5. 点击**确认上架**或**提交审核**。
   提交成功后，在插件列表中查看上架状态。状态显示为“审核中”表示已进入审核流程，不代表已经上架完成。   


如果要修改已经上架的展示信息，可以在插件右侧的**更多**中展开**企业上架管理**，选择**更新上架信息**。如果不再希望团队成员发现该插件，可以在同一位置选择**下架**。下架不会自动移除成员已经添加到 Agent 的插件。

## 相关操作 {#hF969e2pn}

### 修改插件 {#hhHnX2SOE}

你可以在原对话中继续修改插件，也可以在新的对话或项目中提出修改要求。系统会根据当前正式版本创建草稿；只有在你确认并发布新版本后，修改才会在线上生效。

**示例提示词**

```Plain Text
@插件创建器，修改“订单对账”插件：新增“退款处理中”状态；对账看板默认只展示异常订单，并保留“查看全部”筛选项。请保留现有数据，完成后生成草稿供我测试，不要直接发布。
```

### 管理我的插件 {#hQw9sDWLC}

在[我的插件](https://www.coze.cn/skills?capability=plugin&tab=my?surl_token=FJvCs&zlink_code=FFKdE&utm_medium=docs&utm_source=docs&utm_content=landingpage&utm_id=&utm_campaign=&utm_term=docs&utm_source_platform=)中，可以查看当前账号拥有的插件资产。列表会展示插件来源，例如**插件商店**或**我创建的**，并显示连接状态、上架状态和已添加的 Agent 数量。

常用操作包括：

* **修改名称和图标**：点击插件右侧的**更多**，选择**编辑插件信息**，修改后保存。
* **管理 Agent**：点击**X 个 Agent**，查看已添加和未添加的 Agent，并将插件添加到目标 Agent 或从 Agent 移除。
* **停用或重新启用**：停用后，新对话不再加载该插件；重新启用后使用最新正式版本。
* **从 Agent 移除**：只解除插件与当前 Agent 的关系，不会删除插件、正式版本或业务数据。
* **管理企业上架状态**：更新企业商店展示信息，或下架插件。
* **删除插件资产**：在**更多**中选择**删除插件**并确认。删除后，你的所有 Agent 都无法继续使用该插件，且无法恢复。

同一项目中的插件版本和业务数据可以共享，但每个 Agent 是否启用插件需要单独管理。将插件添加到一个 Agent，不会自动让项目中的其他 Agent 获得该插件。

## 常见问题 {#hcNYbdyEU}

### 什么情况下需要创建 Panel？ {#hvBja709B}

当用户需要持续查看或直接操作画布、看板、表格、任务列表等内容时，建议创建 Panel。例如，用户需要筛选订单、拖动画布元素、修改任务状态，或在查看数据后继续让 Agent 处理，都适合使用 Panel。

如果插件只需要让 Agent 按固定流程完成任务，并通过消息或文件返回结果，通常不需要 Panel。例如，合同审阅、资料总结或固定格式周报可以使用能力插件。如果用户需要在界面中持续查看和操作内容，例如筛选订单或调整任务状态，则建议创建 Panel。

### 发布和上架有什么区别？ {#hQy2hsLEp}

发布和上架解决的问题不同。发布会把测试完成的草稿生成正式版本，让当前 Agent 或项目中已经启用该插件的 Agent 使用。发布后，插件不会自动出现在企业团队商店中。

如果希望将插件共享给团队成员，还需要把已发布插件上架到企业团队商店。上架后，其他成员可以在商店中查看并添加插件。企业团队商店默认关闭审核；管理员开启审核后，插件需要通过审核才能正式上架。仅供自己或指定 Agent 使用时，完成发布即可，不需要上架。

### 可以导入 Codex 或 Claude Code 的插件吗？ {#htP24dazZ}

可以。你可以导入在扣子开发或从 Codex、Claude Code 导出的插件包。插件包需要：

* 符合 [Agent Plugins 1.0.0 协议](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)插件规范。
* 压缩前、压缩后均小于 500 MB。