插件
插件为 Monstrum 平台添加新的资源类型。平台上的插件均为官方认可并由管理员审核发布，确保安全和质量。如果你需要接入自定义工具，可以通过本地 Agent 加载插件（详见 本地 Agent 接入）。
概述
两种插件使用方式
| 方式 | 说明 | 执行位置 |
|---|---|---|
| 平台插件 | 官方认可的插件，由管理员安装到平台 | 云端（平台侧） |
| Agent 插件 | 用户自行安装到本地 Agent 上 | 本地（Agent 侧） |
平台插件是本文的重点。它们经过官方审核，安装后在平台云端执行，所有用户都可以使用。
Agent 插件由用户自行管理。将 .mst 插件包放到本地 Agent 的配置中，Agent 连接平台后自动注册工具。这种方式适合私有系统集成或尚未上架官方市场的插件。详见 本地 Agent 接入 中的工具注册章节。
平台插件是什么
平台插件是一个资源类型扩展包，包含：
- 资源类型定义：声明工具列表、认证方式、权限维度、配置表单
- 执行器：工具调用的实际执行逻辑
安装一个插件 = 在平台注册一个新的资源类型。之后你可以像内置资源一样为它创建 Resource、添加 Credential、绑定到 Bot。
插件资源与内置资源
| 内置资源 | 插件资源 | |
|---|---|---|
| 来源 | 随平台安装 | 官方市场，管理员安装 |
| 类型 | SSH、MCP、Bot、Web、Web3、Agent | GitHub、GitLab、Notion 等 |
| 配置方式 | 相同 | 相同 |
| 绑定和权限 | 相同 | 相同 |
| 认证方式 | 各类型自有 | 各插件自有（可能包含 OAuth） |
安装后，插件资源与内置资源在资源管理页面并列展示，使用体验一致。
插件市场
- 在左侧导航栏点击 市场 → 插件市场
- 浏览可用插件列表
页面支持：
- 搜索：按关键词搜索插件
- 排序：按下载量 / 收藏数 / 最新发布排序
- 标签筛选：按标签过滤（productivity、database、devops 等）
- 来源筛选：官方插件 / 社区插件
点击插件卡片进入详情页，查看：
- README：插件介绍和使用说明
- 工具列表：插件提供的所有工具，包括名称、描述和参数定义
- 版本历史：版本更新记录
官方插件与社区插件
插件市场同时展示两类插件：
| 官方插件 | 社区插件 | |
|---|---|---|
| 来源 | 平台官方发布 | 社区用户提交 |
| 审核 | 管理员审核 | 社区自治（评分、举报） |
| 执行位置 | 平台云端 | 用户本地 Agent |
| 安装方式 | 管理员在平台安装 | 用户安装到本地 Agent |
| 安全责任 | 平台负责 | 用户自行承担 |
使用官方插件：确认管理员已安装，直接在资源管理中创建 Resource 使用。
使用社区插件：在插件详情页复制安装命令，在本地 Agent 上执行安装。Agent 连接平台后，工具自动注册为资源。
提交社区插件
如果你开发了插件并希望分享给社区：
- 将插件打包为
.mst文件 - 在插件市场提交到社区区域
- 其他用户可以浏览、评分、安装到自己的 Agent
使用官方插件资源
管理员安装官方插件后，对应的资源类型出现在资源管理的”可添加的资源”列表中。使用流程与内置资源完全一致：
1. 创建 Resource
在资源管理页面，找到插件提供的资源类型，点击创建。填写配置信息（表单由插件定义，不同插件不同）。
2. 添加凭据
根据插件支持的认证方式添加凭据：
- API Key / Token：直接填写密钥
- OAuth：通过 OAuth 流程授权（见下方 OAuth 章节）
- 其他方式：由插件声明，平台自动渲染表单
3. 绑定到 Bot
在 Bot 详情页的资源配置中绑定该 Resource，配置权限。插件声明的权限维度会自动出现在配置表单中。
OAuth 认证
部分插件支持 OAuth 认证（如 GitHub、GitLab、Slack）。OAuth 相比手动填写 API Key 有以下优势：
- 自动刷新：平台自动检测即将过期的 Token 并刷新
- 精细权限控制：通过 OAuth scope 限定访问范围
- 安全隔离：用户不需要将长期凭据交给平台，授权随时可撤销
支持的 OAuth 流程
| 模式 | 说明 | 典型场景 |
|---|---|---|
| Authorization Code | 用户在浏览器中授权，最常用 | GitHub、GitLab、Slack 集成 |
| Client Credentials | 机器对机器，无需用户交互 | MCP 服务器 OAuth 2.1 |
| Device Code | 无浏览器环境的授权 | 远程服务器、CLI 环境 |
创建 OAuth 应用
使用 OAuth 前，需要先创建 OAuth 应用（OAuth Provider），存储第三方平台分配的客户端凭据：
- 在资源管理中创建支持 OAuth 的资源类型时，选择 OAuth 认证方式
- 如果尚未配置 OAuth 应用，平台会引导你创建
- 填写：
| 字段 | 说明 |
|---|---|
| 提供商名称 | 如 github-corp、slack-team，工作区内唯一 |
| 资源类型 | 选择该 OAuth 应用对应的资源类型 |
| Client ID | 在第三方平台创建 OAuth App 后获得 |
| Client Secret | 客户端密钥（AES-256 加密存储） |
| 回调地址 | 留空自动生成，格式为 {平台地址}/api/oauth/callback |
| 额外权限范围 | 在默认 scope 之外追加的 OAuth scope |
回调地址配置
回调地址（Redirect URI）是 OAuth 授权码模式的关键。创建 OAuth 应用后，你需要在第三方平台的 OAuth App 设置中填写相同的回调地址：
GitHub： Settings > Developer settings > OAuth Apps > Authorization callback URL
GitLab： Settings > Applications > Redirect URI
Slack： App 管理页面 > OAuth & Permissions > Redirect URLs
回调地址必须与第三方平台配置的完全一致（包括协议、域名、路径），否则授权会失败。
授权流程
Authorization Code：
- 创建资源时选择 OAuth Authorization Code 认证
- 选择已配置的 OAuth 应用
- 点击 授权 → 浏览器跳转到第三方授权页面
- 用户确认授权 → 回调到平台 → Credential 自动创建
Client Credentials：
- 选择 OAuth Client Credentials 认证
- 选择 OAuth 应用
- 点击 获取凭据 → 平台自动用 Client ID + Secret 获取 Token
Device Code：
- 选择 OAuth Device Code 认证
- 点击 授权 → 页面显示用户码和验证地址
- 在任意设备浏览器中打开验证地址，输入用户码完成授权
- 平台自动检测授权完成并创建 Credential
Token 生命周期
平台自动管理 OAuth Token 的生命周期：
- 定期检查：自动扫描即将过期的 Token 并提前刷新
- 执行时重试：工具调用遇到 401 时自动刷新 Token 并重试
- 刷新失败通知：Token 刷新失败时，Credential 标记为过期，平台发送通知
| OAuth 模式 | 刷新方式 |
|---|---|
| Authorization Code | 使用 Refresh Token 刷新。Refresh Token 失效需重新授权 |
| Client Credentials | 直接重新用 Client ID + Secret 获取新 Token |
| Device Code | 有 Refresh Token 时使用；否则需重新走设备码流程 |
如需立即刷新，在 Resource 详情的 Credential 区域点击 刷新 Token。
示例：GitHub 插件配置
以 GitHub 插件为例，展示使用平台插件的完整流程：
1. 确认插件已安装
在插件市场中确认 GitHub 插件已安装。如未安装，联系管理员。
2. 在 GitHub 创建 OAuth App
- 进入 GitHub Settings > Developer settings > OAuth Apps > New OAuth App
- 填写 Application name、Homepage URL
- 将 Monstrum 的回调地址填入 Authorization callback URL
- 记录 Client ID 和 Client Secret
3. 在 Monstrum 创建 GitHub 资源
- 在资源管理中找到 GitHub 类型，点击创建
- 认证方式选择 OAuth Authorization Code
- 创建 OAuth 应用，填入 Client ID 和 Client Secret
- 点击授权，在 GitHub 页面确认
4. 绑定到 Bot
- 在 Bot 的资源配置中绑定该 GitHub 资源
- 选择允许的操作（如
issue.read、pr.read） - 配置仓库白名单（如
org/repo-*）
常见问题
我可以自己上传插件到平台吗
不可以。平台上的插件由管理员统一管理。如果你有自定义工具需要接入，有两种选择：
- 将插件安装到本地 Agent 上，通过 Agent 桥接到平台（详见 本地 Agent 接入）
- 联系管理员申请将插件上架到平台
如何更新已安装的插件
在插件市场中找到该插件，如果有新版本，页面会显示更新选项。更新操作需要管理员权限。
OAuth 授权后仍提示”需要认证”
- Client Secret 不正确：编辑 OAuth 应用，重新填写正确的密钥
- 回调地址不匹配：确认两边配置完全一致
- scope 不足：某些平台 scope 不足会拒绝授权，检查是否需要额外 scope
Token 频繁过期
- Access Token 有效期由第三方平台决定（可能只有 1-2 小时），有 Refresh Token 时平台会自动刷新
- 如果 Refresh Token 被撤销（用户在第三方平台取消授权），需要重新授权
- 如果 Client Secret 被第三方轮换，需要在 OAuth 应用中更新
Client Credentials 获取 Token 失败
- 核对 Client ID 和 Secret 是否正确
- 确认 Token 端点可访问
- 检查请求的 scope 是否被第三方支持