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

# 插件开发与上架指南

> MiniMax Plugin 的能力选择、目录结构、Manifest 字段、Skill 与 MCP 编写、包体限制和提交流程。

> [!NOTE]
>
> **当前投稿范围（2026-09-08 核验）**：本表单受理 App、MCP、Skill Plugin。提交时可选择**桌面端（MiniMax Code）**、**云端（MiniMax Agent）**，或两端同时启用。启用端与目标区域（CN/US）是两个独立维度；端范围由 Marketplace catalog 管理，不写入 Plugin 包内的 `plugin.json`。

> **[准备提交](https://vrfi1sk8a0.feishu.cn/share/base/form/shrcnbnpeor3z72fUkeHzrOE7vb)**
>
> 支持通过 ZIP 附件或公开 GitHub 仓库提交。GitHub 可指定 branch、tag、commit 或 Plugin 子目录；两种来源进入相同的校验、审核与发布流程。

> **[查询进度](https://vrfi1sk8a0.feishu.cn/share/base/form/shrcncjiq3QJqP0IYEFOytcEqrh)**
>
> 查询时必须使用原提交所用的飞书账号，并填写 submission\_id 与提交邮箱；三者匹配后，结果通过飞书消息返回。

## 1. 先选择要提供的能力

| 能力 | 适用场景 | 如何接入 |
| - | - | - |
| **Skill** | 为 Agent 提供领域知识、操作流程和使用指导 | 直接放入 Plugin 的 `skills/<skill-name>/SKILL.md` |
| **MCP** | 提供无需 MiniMax 代管用户授权的本地或远程 MCP 工具 | 直接在 Plugin 中放置并引用 `*.mcp.json` |
| **App** | 由 Connector 统一管理远程 MCP 接入。可使用 OAuth、用户填写的 API Key/Token，也支持不要求用户提供凭据的平台托管 MCP；是否需要连接账号取决于具体 App。 | 提交前联系 MiniMax，按 App（MCP Server）接入规范完成 Connector 配置与联调；MiniMax 确认 provider 后再制作 Plugin |

> [!WARNING]
>
> **不要把 OAuth、access token、refresh token、client secret 或 API key 写入 Plugin**。需要用户身份的能力应先走 App/Connector 接入。若无法判断属于 App 还是普通 MCP，请在提交前联系 MiniMax 技术接口人。

一个 Plugin 可以只包含一种能力，也可以组合 App、MCP 和 Skill；每个 Plugin 至少包含一种能力。**当前第三方表单尚不受理 Hook**，请勿提交 `hooks` 字段或 Hook JSON 文件。桌面端可直接导入的其他插件格式，也需要先转换为本指南规定的 MiniMax Plugin 包才能投稿。

## 2. 标准目录结构

```plaintext theme={null}
acme-research/
  .minimax-plugin/
    plugin.json
  icon.png
  research.mcp.json
  calendar.app.json
  skills/
    literature-review/
      SKILL.md
  # 其他被 Skill 或 MCP 引用的普通文件

```

* ZIP 根目录必须直接包含 `.minimax-plugin/plugin.json`，不能在 ZIP 外再套一层目录。
* 文件名和路径只使用 ASCII 字母、数字、点、下划线和连字符；路径统一使用 `/`。
* 不接受符号链接、硬链接、Git LFS 指针、Git submodule、包安装生命周期脚本、平台专属二进制或依赖可执行位的文件。包安装生命周期脚本指 `package.json` 中的 `preinstall`、`install`、`postinstall` 等。Skill/MCP 可携带普通可移植脚本，通过明确的解释器调用。
* 文本文件使用 UTF-8、无 BOM；JSON 必须是 object，不能包含重复 key。

## 3. 编写 Plugin Manifest

`.minimax-plugin/plugin.json` 是包的入口。以下示例同时包含 MCP 与 Skill；没有的能力使用空数组。

```json theme={null}
{
  "schemaVersion": 1,
  "name": "acme-research",
  "displayName": "Acme 研究助手",
  "version": "1.0.0",
  "description": "检索研究资料并生成结构化综述。",
  "author": "Acme",
  "icon": "icon.png",
  "category": "Science & Healthcare",
  "exampleQueries": [
    "检索近期研究并总结主要结论",
    "根据这些资料生成一份文献综述"
  ],
  "apps": [],
  "mcpServers": ["research.mcp.json"],
  "skills": ["skills/literature-review/SKILL.md"]
}

```

| 字段 | 要求 |
| - | - |
| `name` | 小写机器名，最长 80 个字符；以字母开头，可使用数字及 `._-` 分隔，例如 `acme-research` |
| `version` | SemVer，例如 `1.0.0`。包内任意内容发生变化时必须提升版本号；仅调整区域、启用端等 Catalog 元数据且包内容完全不变时，可以保持版本不变。 |
| `displayName` | 可选，面向用户的展示名，建议简短明确；省略时使用 `name`。提供时，去除首尾空白后必须非空，UTF-8 编码长度不得超过 1,024 字节。 |
| `description` | 说明能解决什么问题，不写内部技术实现 |
| `author` | 开发者、团队或公司名称；去除首尾空白后必须非空，UTF-8 编码长度不得超过 1,024 字节。 |
| `icon` | 包内相对路径；仅支持小写扩展名 `.png`、`.jpg`、`.jpeg`、`.webp`，建议使用清晰的方形正式图标。当前生产发布仅接受默认 `icon`，请勿声明 `darkIcon`，也不要将该字段保留为空值或 `null`。 |
| `category` | 从下方固定分类中选择一项 |
| `exampleQueries` | 0–3 条真实示例，每条非空且最多 4,096 个字符 |
| `apps / mcpServers / skills` | 填写包内相对路径；未使用的能力必须保留为空数组。`deliveryTargets`、`installationPolicy`、`listed` 和排序配置不属于 `plugin.json` 字段；本表单也不提供排序、上下架或默认安装策略选项。 |

**可选分类：**`Office`（办公）、`Studio`（创作）、`Design & Sites`（设计与网站）、`Code`（代码）、`Business`（商业）、`Sales`（销售）、`Productivity`（效率）、`Science & Healthcare`（科技与医疗）、`Education`（教育）、`Other`（其他）。

## 4. 添加 Skill

每个 Skill 放在 `skills/<skill-name>/SKILL.md`，并在 manifest 的 `skills` 中引用。文件必须以 YAML frontmatter 开始：

```markdown theme={null}
---
name: literature-review
description: 检索、筛选并总结研究资料，生成结构化文献综述。
---

先确认研究主题、时间范围与输出格式。
检索资料后，按研究问题、方法、主要结论与局限进行归纳……

```

* `name` 必须与 Skill 目录名完全一致，`description` 必须非空。
* 正文应是模型可以直接执行的完整指导，不要只写功能宣传。
* Skill 引用的模板、资料或脚本应一并放入包内，并使用相对路径。
* 同一 Plugin 内 Skill 名不能重复；运行时会以 `<plugin-name>:<skill-name>` 暴露，避免与其他 Plugin 冲突。

## 5. 添加 MCP

每个 `*.mcp.json` 可以声明一个或多个 MCP Server，并在 manifest 的 `mcpServers` 中引用。

```json theme={null}
{
  "schemaVersion": 1,
  "mcpServers": {
    "acme-search": {
      "type": "streamable-http",
      "url": "https://mcp.acme.example/mcp",
      "description": "检索 Acme 公开知识库",
      "timeout": 30000
    }
  }
}

```

```json theme={null}
{
  "schemaVersion": 1,
  "mcpServers": {
    "local-analyzer": {
      "type": "stdio",
      "command": "python3",
      "args": ["./server.py"],
      "description": "分析本地输入文件",
      "timeout": 30000
    }
  }
}

```

* 支持 `stdio`、`streamable-http`、`sse`；不支持 `http` alias。
* `timeout` 表示单次工具调用超时，单位为毫秒；例如 `30000` 表示 30 秒。未填写时使用运行时默认值。
* `stdio.command` 只能写 PATH 中的解释器或可执行名，不能包含路径；包内脚本通过相对 `args` 引用。
* 远程 MCP 必须使用真实 HTTP(S) 地址并可稳定访问；建议在提交前完成 `initialize`、`tools/list`、`tools/call` 验证。
* 不得在 `headers`、`env` 或其他文件中写入任何密钥与用户凭据。需要鉴权时请先联系 MiniMax 评估 App/Connector 接入。

## 6. App 接入前置

App 不是在 Plugin 中直接填写 OAuth 参数、API Key 或其他鉴权信息。第三方需先提供符合 [MiniMax App（MCP Server）接入规范](https://vrfi1sk8a0.feishu.cn/wiki/HPtLwSJnHi2KMWkgUtfcWnk8nDc) 的远程 MCP Server，由 MiniMax 完成 Connector 接入与联调，并确认每个目标区域可用的稳定 `provider`。投稿时的 provider 静态检查不能代替实际连通性和鉴权验证。完成接入后，MiniMax 才会确认如下引用文件：

```json theme={null}
{
  "schemaVersion": 1,
  "provider": "acme"
}

```

联系 MiniMax 时请准备：测试与正式 MCP endpoint、transport、建议的 provider 与展示信息、目标区域、鉴权方式、测试凭据、限流和错误码说明。OAuth 还需提供 issuer、discovery metadata、scope/resource、DCR/PKCE 与回调要求；API Key/Token 等方式还需提供表单字段、静态 HTTPS 获取链接及 Header 映射。

> [!TIP]
>
> 当前无需定制开发的标准接入包括：无需用户凭据的远程 MCP；Authorization Code + PKCE S256、DCR 与 refresh token 的 OAuth MCP；以及由用户填写 API Key/Token、由 Connector 按受控模板注入 HTTP Header 的非 OAuth MCP。新接入应优先使用 HTTPS Streamable HTTP；固定 client secret、query/body/cookie 鉴权或动态签名需单独评估。

## 7. 包体与安全限制

| 项目 | 上限 |
| - | - |
| ZIP 原始大小 | 64 MiB |
| ZIP entries（含目录） | 2,048 |
| 普通文件数量 | 1,024 |
| 单文件解包后大小 | 16 MiB |
| 全部普通文件解包后总大小 | 64 MiB |
| 完整路径 / 单个路径段 / 路径深度 | 512 bytes / 128 bytes / 16 段 |

ZIP 使用无 wrapper directory 的标准包结构即可。上传源包支持未加密的 STORE 或 DEFLATE 压缩；系统会拒绝路径穿越、绝对路径、反斜杠、Unicode 文件名、大小写冲突、Windows 保留名、特殊文件和加密 ZIP，并执行上表中的文件数与大小限制。校验通过后，系统会将内容规范化为确定性的 STORE-only Marketplace 包。

## 8. 提交新 Plugin 或更新

![](https://mintcdn.com/agent-cn/WdlLac58s2Dq4rMn/images/code/plugin-submission-flow.png?fit=max\&auto=format\&n=WdlLac58s2Dq4rMn\&q=85\&s=d1d4b22870903d29f4d767b5211846f5)

1. 在提交表单中选择“上架新 Plugin”或“更新已有 Plugin”，并分别选择目标区域（CN/US）与启用端（桌面端/云端，可多选）。
2. 选择来源并只填写对应内容：ZIP 根目录必须直接包含 `.minimax-plugin/plugin.json`；GitHub 填写公开仓库根地址，可选填写 Ref 与 Plugin 子目录。系统会冻结本次来源，确保后续审核与发布使用同一份内容。
3. 更新已有 Plugin 时，`name` 必须保持不变，并提供维护权证明。包内内容变化时必须提升 `version`；仅调整已有区域的启用端等 Catalog 元数据且包内容完全不变时，可保持版本。首次向另一区域发布同名 Plugin 仍须选择“新插件”。具体变更由系统生成的 MR diff 展示，无需另填“变更摘要”。
4. 提交成功后保存 `submission_id`。系统会完成来源规范化与脚本校验；失败原因会写回记录并主动发送飞书消息。AI 预审为可选能力，当前未启用，不影响流程继续。
5. 脚本校验通过后，系统按所选区域自动创建指向 CN/US Marketplace `main` 的 Release MR，并在人工审核群卡片中提供 MR 链接。审核人员直接检查 MR diff、Markdown 校验报告、图标与 CI；确认无误后由仓库 owner 合入。
6. MR 合入后，Marketplace `main` Pipeline 自动打包并分发。Intake 会跟踪发布任务，将状态更新为“发布中”“已发布”或“发布失败”，并主动发送飞书消息。查询时需使用原提交飞书账号，并提供 `submission_id` 与提交邮箱。
   **跨区域提交**：一份提交的操作类型适用于所有目标区域。如果插件已在 CN 存在、但首次提交到 US，请拆成两份提交：CN 选择“更新插件”，US 选择“新插件”。
   **发布与上架：**“已发布”是本次提交的包分发状态，不代表插件当前一定在市场中可见。市场展示顺序及上下架由 MiniMax 运营独立管理；首次发布的新插件默认上架，但不因此自动安装。更新已有插件会保留原有顺序及上下架状态，更新已下架插件不会自动恢复上架。
   下架不会改写用户已有的安装、卸载、启用或停用选择，恢复上架后保留这些选择。客户端通过已有刷新流程同步最新运营状态，变更可能不会立即生效。查询表单返回提交与发布状态，不查询当前运营上架状态；如显示“已发布”但在预期区域和端仍不可见，请携带 `submission_id` 联系 MiniMax 核查。

## 9. 提交前自查

* [ ] ZIP 根目录或 GitHub 指定子目录直接包含 `.minimax-plugin/plugin.json`
* [ ] `name`、包目录与 manifest 一致；如包内内容变化，已提升版本号
* [ ] 图标、名称、描述、分类和不超过 3 条示例 query 均为正式内容
* [ ] 至少包含一种能力，所有 App/MCP/Skill 文件都被 manifest 引用
* [ ] Skill frontmatter 完整，MCP endpoint/命令已验证
* [ ] 包内不含 Token、Secret、个人数据、包安装生命周期脚本、软链接或平台专属二进制；普通 Skill/MCP 脚本通过明确的解释器调用
* [ ] 拥有代码、文案、图标和引用资料的提交与分发权利
* [ ] 如包含 App，已经提前联系 MiniMax 并完成 Connector provider 确认

## 10. 常见驳回原因

* ZIP 多套一层目录、GitHub 子目录定位错误，或目标根目录缺少 `.minimax-plugin/plugin.json`。
* Plugin 名称、版本、路径、JSON Schema 或 Skill frontmatter 不符合规范。
* 能力文件未被 manifest 引用，或 manifest 引用了不存在的文件。
* MCP 使用了不支持的 transport、绝对路径、平台专属依赖，或包含 OAuth/密钥。
* App provider 尚未完成 Connector 接入，或目标环境尚未验证。
* 示例 query、描述或图标仍是测试内容；版权、隐私或数据合规说明不完整。
* 更新已有 Plugin 时修改了包内内容却未提升版本、无法证明维护权，或 MR diff 暴露不兼容变更。

## 11. 数据与沟通说明

* GitLab 中冻结的提交包、脚本校验报告和可选 AI 预审报告保留 180 天。飞书 Base 中的运营记录与附件不自动清理，将按平台现状保留，并在确有运营需要时由 owner 人工处理。
* 请勿在提交包或表单中填写生产密钥、用户 token 或不必要的个人敏感信息。
* AI 预审是可选的提效能力，当前暂未启用；无论是否启用，最终上架决定均由 MiniMax 人工审核人员作出。
* 规范与校验规则可能随平台演进更新，请按本指南当前投稿范围准备材料。自动预检通过不等于最终接收或上架，仍需通过人工审核与生产发布校验；市场当前可见性还受区域、启用端和运营上下架状态影响。