Cursor 插件机制：plugin 与 VS Code 扩展不在同一层

一个很容易走错的第一步

假设你要把一套团队约定发给组里所有人：几条 rules、一个做代码评审的 skill、一个内部的 MCP server。如果你的经验来自 VS Code，第一反应多半是”打个扩展包发出去”。在 Cursor 里这条路会拐偏——官方文档把这些东西全部归到 plugin 上，而 plugin 和 Cursor 里那套 VS Code 式的 extension，在文档中是两条互不相干的分发链路。

先把两边的原文摆出来。

cursor.com/docs/plugins 开篇写明：plugin 把 rules、skills、agents、commands、MCP servers、hooks 打包成可分发的 bundle。cursor.com/help/customization/plugins 补了一句更关键的：plugin 在 Cursor desktop、web 和 CLI 上都可用。

cursor.com/help/customization/extensions 讲的完全是另一件事：Cursor 的第三方 extension 走 Open VSX registry，搜索与下载经由 Cursor 自己的 marketplace 代理 marketplace.cursorapi.com，在展示与分发之前跑自动化的恶意代码与供应链分析；文档同时写明，并不是每一个 Microsoft Marketplace 上的扩展都在 Open VSX 上有登记，部分被 Anysphere 自建的替代版本顶上。

两段话放在一起，分层就清楚了：extension 是编辑器那一层的东西，注册表、审查方式、装载入口都跟着 VS Code 生态走；plugin 是 agent 那一层的东西，连 CLI 这种根本没有编辑器界面的地方也照样加载。你要分发的是”agent 该怎么干活”，那就是 plugin 的事。

前置条件：先确认你在哪个端、什么身份

这一段最容易被跳过，但它决定了后面每一步能不能走通。

端。 按 cursor.com/help/customization/plugins 的说法，plugin 在桌面端、web 和 CLI 上都能用。extension 那一侧的安装入口，文档里只给了编辑器的 Extensions 面板，快捷键写明 Mac 是 Cmd + Shift + X、Windows/Linux 是 Ctrl + Shift + X——而 plugin 的安装入口，文档给的是 Customize，两页各说各的，没有任何一页把 plugin 的安装挂在 Extensions 面板上。

身份。 文档写明安装 plugin 时可以选 project 或 user 两种 scope，个人安装这一段没有提到身份要求。但团队分发是另一回事：cursor.com/docs/plugins 写明 team marketplace 面向 Teams 与 Enterprise 套餐，管理入口是 Dashboard -> Plugins；在 Enterprise 套餐下，只有 admin 能添加 team marketplace。各套餐能建几个 team marketplace 属于会变的商务条款，本文不抄具体数值，以官方页面为准。

版本。 这三页文档都没有写”某个功能需要哪个版本起”。CLI 侧的 plugin 能力散落在 cursor.com/docs/cli/changelog 的多条记录里（例如 2026-03 的条目写”Plugins arrived”、2026-05-07 的条目写 plugin marketplace 与 --plugin-dir），也就是说旧版 CLI 上不一定有。要确认自己手上这版有没有，changelog 页写明用 agent --version 看版本、agent update 就地升级。

两种清单格式，决定文件放在哪

Cursor 同时支持两种 plugin 格式，cursor.com/docs/plugins 把区别落在清单文件的位置上：

格式	清单位置	文档写明可打包的组件
Agent Plugins	插件根目录的 plugin.json	skills、MCP servers
Cursor Plugins	.cursor-plugin/plugin.json	在上者基础上增加 rules、agents、commands、hooks 与 variables

文档给的两个目录骨架可以直接照抄。Agent Plugin：

my-plugin/
├── plugin.json
├── skills/
│   └── code-reviewer/
│       └── SKILL.md
└── mcp.json

Agent Plugin 的根 plugin.json 必须带标准的 schema 标识符，文档给的示例是：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "description": "Portable code review tools",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Cursor Plugin 则是把清单挪进 .cursor-plugin/，多出 rules/ 这类目录：

my-plugin/
├── .cursor-plugin/
│   └── plugin.json
├── rules/
│   └── coding-standards.mdc
├── skills/
│   └── code-reviewer/
│       └── SKILL.md
└── mcp.json

文档写明 Cursor Plugin 的清单只强制要求 name，组件从各自的默认目录里被发现，也可以在清单里指定自定义路径。至于完整的清单 schema，官方指向的是 cursor.com/docs/reference/plugins 这一页——它不在我们这次采集到的文档范围内，所以本文不复述那一页的任何字段名。

安装位置：四个入口，别记混

桌面端。 文档写的路径是打开 Customize，找到目标 plugin，选择安装并挑一个 project 或 user scope。两种格式共用同一套安装流程，Cursor 从清单判断格式。安装后的管理也在同一页：可以按 user、workspace、team 三种 scope 过滤看装了什么，MCP server 可以在这里开关（文档写明被禁用的 server 不会加载、也不会出现在聊天里），rules 可以在 Always、Agent Decides、Manual 三档之间切换，skills 出现在 Agent Decides 一档下、也可以在聊天里用 /skill-name 手动调用。

本地开发。 两种格式都可以直接从 ~/.cursor/plugins/local 加载。文档给的步骤是：建一个 ~/.cursor/plugins/local/my-plugin 目录，把插件文件拷进去（根 plugin.json 或者 .cursor-plugin/plugin.json 二选一），然后重启 Cursor 或执行 Developer: Reload Window，再确认 rules、skills、MCP servers 这些组件有没有加载进来。想少拷一遍文件，文档给的是一条 bash 命令：

ln -s /path/to/my-plugin ~/.cursor/plugins/local/my-plugin

Windows 这里要注意：这条 ln -s 是官方文档以 bash 形式给出的，文档没有提供 Windows 侧的等价写法，~/.cursor/plugins/local 在 Windows 上对应哪个绝对路径文档也没有说明。hooks 文档里写出绝对 Windows 路径的地方，是 MDM 管理的全局配置 C:\ProgramData\Cursor\hooks.json，plugin 的本地目录并没有对应的说明。所以在 Windows 上，最稳的做法是先按后文「怎么验证配对了」那一节的动作确认它到底读没读到，而不是照着 macOS 的路径直觉猜。

CLI。 cursor.com/docs/cli/reference/parameters 里有一个参数：

参数	文档描述
--plugin-dir <path>	加载一个本地 plugin 目录，可以重复指定多次

cursor.com/docs/cli/reference/slash-commands 里对应的是 /plugin [subcommand]，说明写的是”管理 plugin 与 marketplace”。CLI changelog 里还提到过若干 CLI 侧的行为，例如用 ~/.cursor/settings.json 里的 enabled_plugins 指向本地插件目录、不走 marketplace，以及 agent plugin marketplace add <git-url> 这类脚本化管理（可以用 --git-ref 钉住分支、标签或 commit）。这些出现在 changelog 而非参数参考页里，用之前值得先跑一次 --help 对一下。以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

团队分发。 team marketplace 在 Dashboard -> Plugins 里配置，导入 GitHub 仓库后可以给每个 plugin 选一种分发模式，文档列了三档：Default Off（开发者自己决定装不装）、Default On（默认装上但可以退出）、Required（始终安装且不能卸载）。另外还有一个动态入口：workspaceOpen 这个 hook 可以返回 plugin 路径，让当前工作区加载。hooks 参考页写明它的输出结构是

{
  "pluginPaths": ["<absolute path>", "..."]
}

字段说明是”要为当前工作区加载的 plugin 目录的绝对路径”。同一页也写明 workspaceOpen 是 IDE 生命周期 hook，不适用于 cloud agent。

边界：几处文档自己就划清楚了的地方

审查方式不一样。 plugin 侧，cursor.com/help/security-and-privacy/marketplace-security 写明每个 plugin 上架前人工评审，全部必须开源，每次更新也要重新评审；文档还写明 plugin 以 markdown 和配套文件为主，不分发二进制。extension 侧靠的是前面说的自动化恶意代码与供应链分析加黑名单，另有安装冷却（extensions.installCooldownHours）、允许清单（MDM 的 AllowedExtensions）、签名校验这些客户端侧控制。两套机制的性质不同，别把对其中一边的信任直接搬到另一边。这里也要照实说一句：文档写明 plugin 属于第三方软件，安装由使用者自行承担风险，官方的建议是装之前看源码。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

权限是继承的，不是新开的。 文档写明 plugin 受你的 MCP allowlist 与 blocklist 约束；如果一个 plugin 里带了被封禁的 MCP server，它照样能装上，但那个 server 发不出调用。既有的 MCP 治理策略无需额外配置即可延续。

术语撞名，看文档时得留神。 cursor.com/docs/customize-cursor 这一页把 plugins、rules、skills、subagents、hooks、commands 统称为 “Cursor extensions” 的可组合部件——同一个英文词，在 help 那边指的是 Open VSX 上那种扩展。同一处还有个小出入：cursor.com/docs/plugins 的组件表里那一行写的是 Agents（描述为自定义 agent 配置与提示词），而 customize 页写的是 Subagents。两页的措辞不一致，我们只指出这一点，不替官方解释哪个是准的。

没有标注不等于稳定。 这几页 plugin 文档里没有出现 beta、preview、experimental、deprecated 之类的标记，本文也就不给任何功能贴这类标签。但 plugin 与 marketplace 这块在 CLI changelog 里改动相当密集，命令、子命令和配置键随版本变动，请以官方文档最新内容为准。

怎么验证配对了

• 本地插件有没有被读到：按文档的步骤，重启 Cursor 或执行 Developer: Reload Window 之后，去 Customize 里按 scope 过滤，确认 rules、skills、MCP servers 这些组件出现在预期的 scope 下。文档把「确认组件已加载」单列为本地测试流程的最后一步，别当它是可选的。
• CLI 侧：用 /plugin 看管理面，或按 changelog 提到的 agent plugin marketplace list 打印各 marketplace 的名称、scope 与 git URL（该条记录提到 --format json 便于脚本处理）。
• MCP 组件是否真的生效：装上不等于能调。先确认它没被 MCP blocklist 挡住，再确认它在 Customize 里是启用状态——文档明说被禁用的 server 不加载也不出现在聊天里。团队分发的 server 还有一句要记住：把 Team MCP server 加进 Default marketplace 并不等于给每个开发者装上并启用，每个开发者可能还需要单独完成对 MCP 提供方的认证。
• 团队 marketplace 的更新有没有生效：文档写明从 GitHub 导入时，plugin 在首次导入时被索引，之后可以开自动刷新，也可以手动刷新。这里有个坑值得单独记：用 “Import from Repo” 建的 marketplace，自动刷新会在每次推送时重读完整清单，新加的 plugin 能自动带进来；而逐个添加 plugin 建起来的 marketplace，自动刷新只更新已有的 plugin，新增的必须重新导入仓库 URL 才会出现。如果你加了新 plugin 却始终看不到，先回头确认这个 marketplace 当初是怎么建的。

回到开头那个问题：要分发的东西如果是”告诉 agent 该怎么做”——rules、skills、commands、hooks、MCP server——那就是 plugin，走 Customize 与 marketplace，格式由清单文件的位置决定；如果要动的是编辑器本身的能力，那才是 extension，走 Open VSX 与 Extensions 面板。两者的注册表、审查流程和装载位置都不一样，混着记迟早会在某一端上找不到东西。

---

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。 该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。 该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。 本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。