安装与使用插件

插件把 Mosael 之外的能力接进来 —— 一段本地脚本，或者一个现成的 MCP 服务。接进来之后， 它的工具智能体和工作流都直接能用，不需要为哪一边再做一次适配。

想自己写一个？见写一个插件。

两种插件#

越来越多平台自己就发 MCP 服务。碰到那种情况，再写一个脚本去把 stdin 的 JSON 翻译成一次 HTTP 调用、再把结果翻译回 stdout，是在重新实现一个已经存在的东西 —— 而且每加一个端点都要改代码。 声明式接进来就够了：

{
  "id": "com.example.thing", "name": "示例", "version": "1.0.0",
  "kind": "mcp",
  // 本地进程:spawn 一个子进程
  "mcp": { "transport": "stdio", "command": "npx", "args": ["-y", "@scope/server"] },
  // 或者远端:url / headers 里可以用 ${KEY} 引用下面声明的凭据
  // "mcp": { "transport": "http", "url": "https://example.com/mcp",
  //          "headers": { "Authorization": "Bearer ${SOME_API_KEY}" } },
  "credentials": [{ "key": "SOME_API_KEY", "label": "API Key", "secret": true }]
}

MCP 插件的工具清单在启用时、填完凭据后各拉一次，之后可以在插件页点「刷新工具」。 服务升级加了新工具，刷一下就有了。

包 / 连接 / 能力#

• 包是磁盘上装了什么(一个目录 + 一份清单)。
• 连接是一次具体接入：一组配置 + 一组凭据 + 一个名字 + 启用开关。一个包可以接多次 —— TikHub 一个包对应十几个平台端点，B站一个连接、抖音一个连接，各有各的 Key。
• 能力是这个连接开放了哪些工具，逐个勾选，默认不开。

界面上这三层是从左到右、从上到下排的：左栏是已安装的插件包，右侧上半是这个包的连接，下半是这个 连接开放的工具。默认一个都不开是有意的 —— 一个 MCP 服务动辄几十个工具，全开会把节点面板 和智能体的工具表淹掉，模型在几十个名字里挑，反而更容易挑错。

右侧最上面是这个插件的页头：名字、状态(内置 / 已安装 / 可更新)、一句话简介、版本和作者(能点的是链接)，右边是「新建连接」「文档」， 卸载收在「⋯」里；有新版时多一颗「更新」，点了打开市场里它那一页。页头下面分两页：连接(默认停在这儿)和关于 —— 能做什么、介绍、工具、权限、插件 ID，和市场里的详情是同一份。

连接能收起。 一个包下面连接多了(几台 ComfyUI、几个平台的 TikHub)，每张卡可以收成一行：名字、关键地址(比如服务器地址)、 状态(可用、已停用、出错了、待授权……)、开了几个工具和常用的几个动作都在这一行里。要你处理的(要重新授权、缺配置)收起时也标出来， 点开就定位到那一项。只有一个连接时默认展开，有好几个时默认收起，刚建的那个展开；哪个收着记在本机，「连接」页签那一行右边有「全部收起 / 全部展开」。

出错时先说人话。 连接标题行上的出错原因、「可生成的…」那一行刷不出来的原因，只写第一行 —— 出了什么事、下一步怎么办； 地址、errno 这类原文悬停看全文(连接收起时悬停标题行，说明里先是原文、再是「展开」)，或者在页面里展开「详情」。出错原因按看的人的界面语言说 —— 后台刷新时记下的也一样，切了界面语言跟着换。

装一个#

插件页左栏是装好的插件，页头有「扫描插件」和「浏览插件市场」。市场是一个卡片网格：顶上能搜（也搜工具名），筛「全部 / 已安装 / 有新版」， 还能「按能力筛」—— 降噪、转写、翻译、配音、文档解析……只列市场里真有插件能做的那几项，各带条数。点开一张卡是详情：页头是名字、状态、 一句话简介和要做的事(「安装」「更新」，装着的是「管理」—— 回到插件页打开它；还有「文档」)；下面「能做什么」一项一块，写着装上之后出现在哪； 介绍先折成三行，点「展开」看全；工具一行一个，说明截两行；右栏的权限按联网、文件、程序分组说人话(权限码悬停看)。

从市场装：翻到你要的那个，点「安装」。它不会直接装上 —— 先把包下下来读一遍清单， 把它声明的权限(按种类分组)和会带来的工具摊开给你看，确认了才落地；左下角的「文档」能先看它怎么用。 装插件是在你这台机器上放一份会被执行的代码，那份清单值得看一眼。

随应用内置的（ComfyUI、对象存储、MinerU 文档解析）在市场里也搜得到，标着「内置」：它已经装好了、跟着应用更新(页头写着「随 Mosael 更新」)， 没有「安装」也卸不掉，点「管理」回到插件页、新建一个连接就能用。

从链接装：有一个 zip 的地址就能装，同样先过一遍那张确认。公司内网可以架自己的市场索引 （一份普通 JSON，格式见写一个插件），在设置里换掉地址即可。

手动放：把插件目录拷进插件目录（那个路径由插件页告诉你 —— 别照着 ~/.mosael/plugins 去找，Windows 上它不存在），点「扫描插件」。写插件的时候走这条最快。

装上之后：没有配置的包自带一个连接，有配置的自己「新建连接」；清单声明的权限逐项授权， 未授权的连接不可用。

插件更新后多要了权限，已有的连接会先停用 —— 它提供的模型和工具暂时用不了，而不是悄悄多拿了权限。连接卡片最上面写明停用的原因、 多要了哪几项，点「授予这 N 项」马上恢复，之前授予的不受影响；插件列表上它标着「待授权」。

卸载会删掉磁盘上的插件目录，连同它的权限、凭据与调用记录。只清记录是不够的 —— 下一次扫描又把它装回来，用户看到的是「我删了它怎么又回来了」。手动删掉目录之后，下一次 扫描会自动清掉那条记录。

凭据#

manifest 里 credentials 声明要哪些密钥，用户在插件页填，运行时注入到这个插件自己的进程。

Mosael 不会把自身的供应商密钥或 API 会话令牌注入插件环境。这个边界不等于操作系统沙箱：本地插件以当前用户权限运行，可能访问该用户有权读取的文件和网络。只安装可信插件，并检查其声明的工具与权限。

必填凭据没填的插件不进工具表 —— 让智能体去调一个必定 401 的工具，只会烧掉一轮对话来复述 一句设置页早就写着的话。

每个连接上还有两样宿主给的设置：

• 网络：「跟随 Mosael」(默认，走「管理 → 部署设置」里的出站代理)、「直连(不走代理)」或「走指定代理」(填一个代理地址)。 比如 MinerU 只在中国大陆提供服务：人在境外选一个进大陆的代理，人在境内开着全局代理时选直连。
• PyPI 镜像 / npm 镜像：要装依赖的插件（Manim、Remotion）才有，默认跟随「管理 → 引擎 → 下载源」，也可以单独换预设或自定义地址。

出站代理的那几个环境变量（HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 等）由宿主按这一项注入，插件清单不能自己声明。

让它自己走一次授权#

要 OAuth 令牌的插件(网盘、云相册这类),清单里可以声明 oauth。声明了,每个连接的第一行就是 授权：标题旁写着这个连接未授权 / 已授权 / 需要重新授权，右边是「去授权」(授权过的是「重新授权」)。 填好 AppKey、SecretKey 这些应用凭据后点它，打开对方的登录页，登完把它给的授权码贴进下面多出来的「授权码」一行，令牌自动存进对应的凭据格。

授权会填的那几格(比如 Refresh Token、Access Token)不和 AppKey 摆在一起当主输入，归「授权」那一行管。 手里已经有令牌的话，点「手动填写令牌」在授权下面展开，照样能自己填。

插件续令牌时对方不认了(refresh_token 作废、应用被停用)，连接会标成需要重新授权 —— 点「重新授权」走一遍就好。

替代不了的那一步是注册应用拿 AppKey / SecretKey —— 那是你和开放平台之间的事。能替代的是 后面那一段：拼授权链接、拿 code 换令牌、把令牌存进哪几个键。每一步抄错，换回来的都是一句 invalid_client 之类的英文报错，看不出错在哪一格。

为什么还要粘一次授权码。 回调不走自定义协议(任何网页都能触发它)，也不在本机开监听端口 (重定向地址要在对方控制台预先登记，而本机端口会变)。多这一次粘贴，换来的是这条路上没有 任何可伪造的输入。

令牌会自己续：插件撞上「过期」时换一个新的、原样重试一次，并把换来的新令牌交回来存好。 刷新时对方常常只回 access_token —— 没回的字段不会被写，否则已有的 refresh_token 会被抹掉， 而那一份丢了就得重新授权一遍。

写法见仓库里的 docs/PLUGIN_MANIFEST.md「instance.oauth」一节。

在智能体里用#

已启用、已授权、凭据齐全的插件工具，直接出现在智能体的工具表里(名字形如 plugin__<插件>__<工具>)，和内置工具没有区别 —— 模型直接看到名字和入参模式，不需要先 「想到」可能有插件能帮忙、再花一轮去列清单。

为什么工具默认不开：一个 MCP 服务可能报四十上百个工具。全放出去，节点面板要人从四十行里 找一行，智能体每轮对话为四十条描述付 token，还挤占模型在内置工具之间的选择权。插件页的工具 列表可以搜索(名称和说明都参与匹配)，也能按当前筛选批量开关。

有后果的工具先问你。 每个工具声明它的后果：不花钱不出门、花钱、对外、在本机跑代码。智能体（应用里的助手、Claude CLI 这类 MCP 客户端） 直接调花钱、对外或跑代码的插件工具时先出确认卡，写明哪个工具、哪条连接、参数摘要和为什么要确认（如「会在你的电脑上运行代码」）；批准后用你自己的 连接跑。只读的照旧直接跑。插件页工具表和市场详情里，这些工具旁标着「需确认」。没声明的按「对外」算。

子智能体默认拿不到插件工具。子智能体只用只读工具，而一个没有确认门的插件工具照样可能 发请求、写文件。要放开，在 manifest 的对应工具上写 "read_only": true —— 这是装插件的人的 判断，不该由被接入的一方自己声称。MCP 插件同理：在 manifest 的 tools 里按名字覆盖即可， 那不是第二份清单，只有 read_only 这一个键会被采纳。

在工作流里用#

每个插件工具就是一个节点，在「添加节点」面板的「插件」组里各占一行。它跟内置节点没有 区别：一样的表单、一样的输入输出、一样的校验 —— 表单直接从工具的入参模式生成。

插件也可以自己声明节点长什么样(标签、说明、表单、输出口子)，参照 ComfyUI 的自定义节点。 具体写法见仓库里的 docs/PLUGIN_MANIFEST.md「工作流节点」一节。

工作流导出到没装这个插件的机器上，打开时会明确告诉你缺的是哪个插件的哪个工具。

调用记录#

最近的调用逐条记录(成功 / 失败 + 输入输出)，点击展开；支持逐条删除或清空。 智能体和工作流的调用同样留痕 —— 插件只有一条执行路径，没有谁能绕过它。

替 Mosael 做事的插件#

有的插件不给智能体和工作流提供工具,而是替 Mosael 做生成:它列出自己有哪些模型(每个模型收什么参数、 有哪些参考图槽位),这些模型就和内置供应商的模型一样出现在 AI Studio、画板和工作流的模型选择器里; 生成走的是同一套任务 —— 任务中心看得到进度、能取消,产出进素材库,用量照常记账。

随 Mosael 一起发的 ComfyUI 就是这样一个插件,装好就在插件页里,卸不掉(不想用就停用它的连接)。 怎么接、怎么用见 用 ComfyUI 生成。这类插件的连接卡片上显示「N 个… · 何时刷新」, 交出来的东西叫什么由插件自己说(ComfyUI 是「工作流」):ComfyUI 里新存了工作流,点「刷新工作流」即可。

插件还能给一个连接带来目录：ComfyUI 连接的标题行上有「打开模型库」「打开工作流库」两颗图标按钮，打开就是那台服务器上的模型文件和存着的工作流 —— 看预览、下载缺的模型、导入别处的工作流、装缺的节点包，都在这里做，见 用 ComfyUI 生成。

插件还能在 Mosael 的能力表里登记，和本机引擎并列：文档解析、降噪、分离人声、转写、翻译、配音、素材外链。装了这种插件，它出现在 「设置 → 能力提供方」对应那一项里（可以设成默认），也出现在工作流节点的引擎下拉、剪辑页、素材库、智能体里，点名就用它。认领了能力的工具 不藏起来：它就在插件页的工具表里，行上标着它认领的能力，展开能看到它还用在哪（比如 MinerU 的「用 MinerU 解析文档」—— 文档「重新解析」、 「文档转 Markdown」节点调的也是它）；勾上之后智能体和工作流也能直接用。有的插件只替 Mosael 做事、不单独开放工具，插件页会写明它做哪几件事。

范例#

仓库的 plugins/examples/ 下这些都是范例，也是官方插件：

• text-toolkit —— 纯函数，零依赖零凭据：统计字数、提取话题标签、断成字幕行、按字数截短、清理文案、Markdown 转纯文本、提取链接与提及，全在本机、只读。
• tikhub —— 零代码接 MCP：一个包建多个连接，每个连接选一个平台、各填各的 Key，工具清单从 TikHub 的 MCP 服务现拉。读抖音 / TikTok / 小红书 / B站 / 快手等平台的公开数据。
• baidu-pan —— 带 OAuth 的那种：自己走授权、自己续令牌，还演示了怎么把大文件 交给宿主去下(插件只换到下载地址，进度、取消、重试都归宿主)。
• blender —— 接一台本机跑着的 Blender。它把已有的 MCP Add-on 包成插件，工具按只读/可写分开申报(查看场景、查看物体是只读，改建模是可写)，所以哪些能让智能体自己用、哪些要你点确认，是你逐项定的。
• remotion —— 用代码做动画，零生成费用：知识点讲解、公式推导、代码演示、数据图。 给内容就能出一段讲解视频(公式由 KaTeX 排版、代码逐行出现)，更自由的画面写一段 Remotion 组件。它还演示了插件怎么声明自己的预算、怎么把几百 MB 的依赖放进跨更新的持久目录。 需要本机装有 Node.js 18+；Remotion 对个人与 3 人以内的公司免费，更大的公司需要购买它的公司许可。
• manim —— 用 Manim 做教学动画(3Blue1Brown 数学动画那套引擎的社区版)，零生成费用：公式推导、 几何关系、函数图像、算法步骤、代码讲解。见下面「Manim 教学动画」一节。

对象存储(随应用内置)#

「对象存储」插件跟着 Mosael 一起发,装好就在插件页里。它解决的是一个具体的断链:Mosael 是本地优先的, 素材在你自己的盘上、没有公网地址,而有些供应商只收链接 —— 方舟 Seedance 的参考视频就是一例 (参考图可以走 Base64,参考视频不行)。它把素材传到你自己的桶里,交回一条限时直链 (签名在查询串里,桶不必设成公共读)。

1. 在插件页的「对象存储」里新建连接,选服务商:阿里云 OSS / 腾讯云 COS / 火山引擎 TOS / Amazon S3 / S3 兼容服务(MinIO、Cloudflare R2 等)。一个连接对一个桶;要用几个桶就建几个连接。
2. 填桶名、地域和一对访问密钥(建一个只对这个桶有读写权限的子用户,别用主账号的)。接入点通常留空, 按地域自动拼;S3 兼容服务要填它自己的地址(如 http://localhost:9000)。腾讯云的桶名要带 APPID 后缀。
3. 授权它的网络权限。

之后生成时遇到只收链接的那一格、而你给的是本地素材,它会自动传上去再发出去;配了几个桶的话, 在「设置 → 能力提供方 → 素材外链」里选默认用哪一个。同一份素材链接没过期就复用,不重复上传。它也是一组普通工具: 上传(大文件分片、边传边报进度)、给已有对象签直链、列目录、把对象拉回素材库。

以前的「阿里云 OSS / 腾讯云 COS / 火山引擎 TOS / Amazon S3」四个插件已经合进来了:升级时连接、密钥、 授权、默认选择和工作流里的节点都原样搬过去,不用重配。

MinerU 文档解析(随应用内置)#

扫描件、图片版 PDF、多栏排版、带公式和复杂表格的文档，交给 MinerU 解析：版面分析、OCR、表格和公式识别，比本地解析好得多。

1. 在 mineru.net 的「API 管理」里建一个 API Token。
2. 在插件页启用「MinerU 文档解析」，新建连接、填上 Token；可以选模型、文档语言、要不要强制 OCR。
3. 用法：某一份文档在阅读器里「重新解析 → 用 MinerU 解析」；以后都用它就在「设置 → 能力提供方 → 文档解析」里设成默认；智能体和工作流用 「用 MinerU 解析文档」这个工具（结果存成这份文档的一次解析）。

导入时 Mosael 总是先用本地解析，交给 MinerU 必须是你点名的 —— 文档会上传到 MinerU。单个文件最多 200 MB、200 页，免费额度每天有页数上限。 MinerU 只在中国大陆区域提供服务，在境外或开着全局代理时看上面「凭据」里的网络一项。文档怎么导入和阅读见文档。

Manim 教学动画#

要讲的东西必须对、而且要「一步一步地变」(这一项移过去、那条边转过来、这一行代码亮起来)时，用 Manim 插件。 视频生成模型给的是像样的画面，不是对的推导；Remotion 插件擅长排版精致的图文卡片，讲数学、几何、算法时 Manim 更顺手。

1. 在插件市场安装「Manim 教学动画」，新建连接、授权。
2. 在插件页运行一次**「准备 Manim 环境」**：它在插件自己的数据目录里建 Python 环境、装 Manim，查 LaTeX，试渲一帧。 第一次要一到几分钟；缺系统组件时会逐条说怎么装：
   • Windows：什么都不用装。
   • macOS：终端里运行 brew install cairo pkg-config 和 xcode-select --install。
   • Linux：sudo apt install build-essential pkg-config libcairo2-dev libpango1.0-dev(Fedora 用 dnf 装同名的 devel 包)。
   • 不需要 ffmpeg(Manim 自带编码库)。LaTeX 可选：装了 MiKTeX / MacTeX / TeX Live，公式按 LaTeX 排版； 没装的话讲解视频把公式写成一行纯文字，照样出片。
3. 让智能体或工作流调用**「Manim 讲解视频」**：给标题和每一步的标题、旁白、要点，再配一样公式、函数图像(sin(x) + x^2/8) 或代码(按行依次框住讲解)。每步多长按旁白的朗读时长算，结果里有每一步的起止时间，可选同时交出 .srt 字幕。

「Manim 自定义动画」和「Manim 静帧」会在本机执行一段 Python 代码，所以默认不开放，要在插件页的工具列表里自己勾上。 它们默认只准 import 画图用的模块、不准读写文件和起进程 —— 这是一道护栏，不是沙箱。详见 Manim 插件页。

创建连接#

选中插件后，点击页头「新建连接」，在弹窗中填写配置。配置、权限与工具选择属于这一个连接；可以为同一插件创建不同的连接。Blender 互通的完整工作台说明见 3D 场景与动画。