插件

#插件是什么

插件让 ta 用上自己没有的工具。Quetzal 沿用业界通行的三种格式，不自造一套：

• MCP 工具来源：Model Context Protocol 服务器。可以是这台设备上运行的一条命令（stdio），也可以是一个远程地址（Streamable HTTP，或旧版 HTTP+SSE）。它提供的工具、资源（文件、文档、记录）和提示词模板都会交给 ta。
• Claude Code 插件：带 .claude-plugin/plugin.json 的目录或 git 仓库，里面可以有技能（skills/）、MCP 服务器（.mcp.json）、命令（commands/）和子 agent 定义（agents/）。
• Agent Skills：skills/<名字>/SKILL.md 形式的技能说明书，和 ta 自己写的技能是同一种格式。

插件都在 控制 → 高级 → 插件 里管理。

#一键安装推荐的插件

插件页下方的「推荐目录」是运行基座内置的一份精选清单，只收公开、有名的项目，每一项都写明了维护者与许可：

除 MCP 官方参考实现外，这些都是第三方项目，行为与安全由各自的维护者负责。装之前长按条目可以打开它的来源页面，看看许可和说明。

点「安装」后先出现一份清单：会添加哪些工具来源、要填哪些值（令牌、密码、目录等）、要写进灵魂仓库的技能、命令与子 agent，以及需要注意的事。你确认后才真正安装。令牌和密码的输入框是遮住的，值只存进这台设备运行基座的 secrets/，之后不再显示。有的插件第一次用前还要登录或授权，清单里会写明怎么做。

本机运行的插件大多用 npx（Node.js）或 uvx（Python）启动。npx 直接用运行基座自带的 Node，不用另装；uvx 需要先在这台设备上装好 uv，没装时清单里会提示，那一项装不上。第一次启动时它们会下载对应的软件包。

#自己添加一个工具来源

插件页右上角的「添加工具来源」：

• 远程：填服务的地址。只收 HTTPS 地址（同一台设备上的 127.0.0.1 除外）；内网地址、云服务的元数据地址一律拒绝。服务要 API Key 时填在 Authorization 一栏，旧服务选「远程（旧版 SSE）」。
• 本机命令：填命令的绝对路径、参数和环境变量。缺省在沙箱里运行；关掉沙箱后它能读这台设备上你的一切文件，只对你信任的程序这么做。

#登录（OAuth）

有的远程服务要你登录才能用（如 Notion、Linear、Sentry），状态会显示「需要登录」。点进这个来源，点「登录」，控制台用系统浏览器打开它的授权页；你同意后，浏览器回到运行基座的本机地址，登录就完成了，这里自动连上。

如果控制台和运行基座不在同一台设备上（例如用手机管理电脑上的 ta），浏览器最后会停在一个 http://127.0.0.1:…/mcp/oauth/callback?… 开头、打不开的页面。把这个完整地址复制下来，粘贴到来源页的「完成登录」框里即可。

登录得到的令牌只存在这台设备上，不进日志、不进灵魂仓库、不交给模型，也不同步到别的设备。「退出登录」会删掉它。

#多端同步 / 仅本机

每个工具来源都可以选多端同步或仅本机，做法和保密库一样：

• 远程来源缺省多端同步：地址和公开的设置经身体之间加密的直连传到 ta 的其他身体；登录和凭据不同步，每台设备各自登录、各自填。
• 本机命令缺省仅本机：命令的路径属于这台设备。改成多端同步后，其他设备上也要有同样路径的命令才能用。

在来源页里随时可以切换；改成仅本机时，其他设备上的副本会删掉。

#装插件包与插件目录

插件页右上角的菜单里：

• 从目录或 git 仓库安装插件：填本地目录的绝对路径、https:// 开头的 git 仓库地址，或 GitHub 的 owner/repo 简写。git 仓库只做浅克隆，不执行仓库里的钩子、不拉子模块；安装时包里的任何程序都不运行。
• 添加插件目录：兼容 Claude Code 插件市场的 marketplace.json（git 仓库里的 .claude-plugin/marketplace.json，或直接指向它的 HTTPS 地址）。添加后可以展开浏览里面的插件，点「安装」。

装好的插件：技能写进灵魂仓库的 skills/，随灵魂同步到 ta 的每一具身体；工具来源加入配置；命令与子 agent 定义留在这台设备上，ta 需要时取用。包里的 hooks（Claude Code 自己的生命周期命令）不会执行。卸载时它加的工具来源（连同登录与凭据）和技能一起去掉，技能的历史在「记忆历史」里能找回。

#ta 的主动推荐

聊着聊着，ta 发现某个还没装的插件能帮上忙——比如你让 ta 帮你填报名表、整理邮件、约时间——会向你推荐，说明为什么。推荐出现在插件页最上面，「高级」和「插件」上带着角标；点「安装」一样先看清单再确认，不需要就点「不用了」。ta 自己不能安装插件、改配置或替你登录。

#发邮件、改日历、提交表单：先问你

这类操作做了就收不回来。规矩是：

• ta 先把要发送或提交的内容——收件人和正文、事件的时间和参与者、表单里的每一项——给你过目，得到你明确同意再做。
• 插件来源启动前要你批准一次，它的每次工具调用缺省也都会问你，在审批里能看到具体参数。
• 在插件页点进这个来源，「权限」一节里调（只对这台设备）：某个来源的启动是 mcp_start.<来源>，它的全部工具是 mcp.<来源>，单个工具是 mcp.<来源>.<工具>。例如可以让只读的查询工具「允许」，把发邮件的工具留在「询问」。没单独设置的，按来源级、再按总类别继承，缺省都是询问。

#边界

• 本机命令缺省在沙箱里运行，看不到运行基座的密钥目录；远程来源的每个请求（包括登录用的请求）都经出站检查，到不了这台设备的网关和局域网。
• 凭据和令牌只在 secrets/，从不进入模型上下文；工具返回的内容交给 ta 前会把已知的保密值替换掉。
• 技能只把文档写进灵魂仓库，包里的脚本和程序不进。
• 插件返回的网页、邮件、文档都是资料，不是指令：里面让 ta 做事的话，ta 不照做。
• 被批准的插件能做它有权限做的事。只装你信任的插件，用不上的就停用或卸载。