VS Code 中的智能体插件（预览版）

智能体插件是智能体自定义功能的预打包集合，你可以在 Visual Studio Code 的插件市场中发现并安装它们。单个插件可以提供斜杠命令、智能体技能、自定义智能体、钩子和 MCP 服务器的任意组合。

插件与你本地定义的自定义项协同工作。当你安装一个插件时，它的命令、技能、智能体、钩子和 MCP 服务器将出现在聊天中。

关于插件如何融入更广泛的自定义选项中，请参阅自定义概念。

插件提供的内容

智能体插件可以打包以下一种或多种自定义类型：

• 斜杠命令：可以在聊天中通过 / 调用的附加命令
• 技能：包含按需加载的说明、脚本和资源的智能体技能
• 智能体：具有专门角色和工具配置的自定义智能体
• 钩子：在智能体生命周期节点执行 shell 命令的钩子
• MCP 服务器：用于外部工具集成的MCP 服务器

例如，一个测试插件可能包含一个带脚本的 test-runner 技能、一个带有只读工具的 test-reviewer 智能体，以及一个用于测试报告仪表板的 MCP 服务器。插件目录结构如下所示：

my-testing-plugin/
  plugin.json              # Plugin metadata and configuration
  skills/
    test-runner/
      SKILL.md             # Testing skill instructions
      run-tests.sh         # Supporting script
  agents/
    test-reviewer.agent.md # Code review agent
  hooks/
    hooks.json             # Hook configuration
  scripts/
    validate-tests.sh      # Hook script
  .mcp.json                # MCP server definitions

安装后，插件提供的自定义项将与你本地定义的自定义项一起显示。例如，来自插件的技能会显示在配置技能菜单中，而来自插件的 MCP 服务器会显示在 MCP 服务器列表中。

插件元数据 (plugin.json)

每个插件的根目录中都需要一个 plugin.json 清单文件。该文件定义了插件的身份，并告诉 VS Code 在哪里可以找到其组件。

必填字段

可选字段

有关完整的字段参考，请参阅 GitHub Copilot CLI 插件参考。

示例 plugin.json

{
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe"
  },
  "skills": "skills/",
  "agents": "agents/",
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

插件格式

VS Code 通过检查特定于格式的清单路径来自动检测插件格式。当未找到其他格式标记时，默认使用 Copilot 格式。

插件环境变量

某些插件格式提供了一个根令牌，你可以在钩子命令和 MCP 服务器配置中使用它来引用插件目录中的文件。VS Code 会在运行时扩展该令牌，并将其设置为钩子或服务器进程中的环境变量。

插件中的钩子

插件可以包含在智能体生命周期点运行 shell 命令的钩子。插件钩子与你的工作区和用户级钩子协同工作。启用插件后，其钩子会在针对同一事件配置的其他任何钩子之外触发。

钩子文件位置

钩子文件的位置取决于插件格式：

VS Code 会自动检测插件格式并自动发现钩子文件。

my-plugin/
  hooks/
    hooks.json           # Hook configuration (Claude format)
  scripts/
    format.sh            # Hook script referenced by hooks.json

钩子配置格式

插件钩子使用与工作区钩子相同的基本格式。VS Code 会解析 Claude Code 钩子配置，包括匹配器语法。目前，VS Code 会忽略匹配器值，因此钩子会在每个匹配事件上运行。

扁平格式（与工作区钩子相同）

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
      }
    ]
  }
}

匹配器格式（Claude 兼容性语法）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

为了兼容 Claude Code，VS Code 会解析 matcher 字段，但目前会忽略匹配器值。如果你需要在 VS Code 中过滤钩子行为，请在钩子脚本内部检查事件输入。

在钩子命令中引用插件路径

对于 Claude 格式的插件，请在钩子命令中使用 ${CLAUDE_PLUGIN_ROOT} 令牌来引用插件目录中的脚本和文件。VS Code 会在运行时将此令牌扩展为插件的绝对路径，并为钩子进程设置 CLAUDE_PLUGIN_ROOT 环境变量。在你的脚本中，可以将其作为 $CLAUDE_PLUGIN_ROOT（在 Windows 上为 %CLAUDE_PLUGIN_ROOT%）进行访问。

这一点很重要，因为插件被安装在工作区之外的位置，因此你无法使用相对路径。

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-tool.sh"
      }
    ]
  }
}

支持的钩子事件

插件钩子支持与工作区钩子相同的生命周期事件：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、SubagentStart、SubagentStop 和 Stop。有关每个事件的详细信息，请参阅钩子生命周期事件。

插件钩子如何与其他钩子交互

插件钩子与工作区级和用户级钩子同时运行。当多个钩子针对同一事件时，它们全都会执行。对于 PreToolUse 钩子，所有钩子中最严格的权限决策获胜：deny 优先于 ask，而 ask 优先于 allow。

禁用插件也会禁用其钩子。你可以从“扩展”视图中全局或针对特定工作区启用或禁用插件。

插件中的 MCP 服务器

插件可以捆绑 MCP 服务器，以为智能体提供额外的工具和数据源。插件 MCP 服务器在启用插件时自动启动，在禁用插件时停止。

MCP 配置文件

将 MCP 服务器定义放在插件根目录下的 .mcp.json 中。当 VS Code 加载插件时会自动发现该文件。

my-plugin/
  .mcp.json              # MCP server definitions
  servers/
    db-server             # Server executable
  config.json             # Server configuration

MCP 配置格式

插件 MCP 服务器在顶层的 mcpServers 对象中定义。每个服务器条目指定一个命令、参数和可选的环境变量：

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

在服务器配置中引用插件路径

对于 Claude 格式的插件，请在 MCP 服务器字段中使用 ${CLAUDE_PLUGIN_ROOT} 令牌来引用插件目录中的可执行文件和文件。VS Code 会在以下字段中扩展此令牌：

• command：可执行文件路径
• args：命令行参数
• cwd：工作目录
• env：环境变量值
• envFile：环境文件的路径
• url：用于基于 HTTP 的 MCP 服务器
• headers：HTTP 请求头值

VS Code 还将 CLAUDE_PLUGIN_ROOT 环境变量注入到服务器进程中，因此服务器代码可以在运行时访问插件路径。

插件 MCP 服务器如何与其他服务器交互

插件 MCP 服务器与工作区级和用户级 MCP 服务器一起显示。你可以通过相同的工具来管理它们：

• 在“聊天”视图中选择配置工具以查看来自所有 MCP 服务器（包括插件服务器）的工具。
• 从命令面板运行 MCP: List Servers，以查看插件服务器与其他服务器。

安装插件时，插件 MCP 服务器会被隐式信任。与工作区 MCP 服务器不同，它们在启动时不会显示单独的信任提示。

禁用插件会停止其 MCP 服务器。停止的服务器所提供的工具将不再在聊天中可用。

发现并安装插件

VS Code 在“扩展”侧边栏中提供了一个专用视图，用于浏览和管理智能体插件。

浏览可用的插件

1. 打开“扩展”视图（⇧⌘X（Windows、Linux Ctrl+Shift+X）），并在搜索框中输入 @agentPlugins。

   或者，选择“扩展”侧边栏中的更多操作（三个点）图标，然后选择视图 > 智能体插件。

2. 浏览来自你已配置的市场的可用插件列表。

   

3. 选择安装将插件安装到你的用户配置文件中。

   首次从新市场安装插件时，VS Code 会显示信任提示。在确认之前，请检查市场来源。

从源码安装插件

你可以直接从 Git 仓库 URL 安装插件，而无需先添加完整的市场。

• 从命令面板运行 Chat: Install Plugin From Source。
• 或者，在智能体自定义编辑器的插件页面上选择 + 按钮。

输入 Git 仓库 URL（例如 https://github.com/rwoll/markdown-review），VS Code 将克隆并安装该插件。

通过 GitHub Copilot CLI 安装的插件

VS Code 会自动发现你使用 GitHub Copilot CLI 安装的插件，以便你也能在 VS Code 中使用它们。来自 ~/.copilot/installed-plugins/ 的插件会与你从市场或源码安装的插件一起显示在智能体插件 - 已安装视图中。

CLI 将插件存储在 ~/.copilot/installed-plugins/<marketplace>/<plugin>/ 下。直接从 Git URL（而不是从市场）安装的插件位于 _direct 存储桶下，例如 ~/.copilot/installed-plugins/_direct/github--moda-linter--copilot-plugin/。

查看已安装的插件

“扩展”视图中的智能体插件 - 已安装视图显示了你已安装的插件。从此视图中，你可以启用、禁用或卸载插件。

你还可以通过在“聊天”视图中选择齿轮图标 > 插件来管理已安装的插件。

启用或禁用插件

你可以全局或针对特定工作区启用或禁用插件：

• 使用“扩展”视图的智能体插件 - 已安装部分中插件上的上下文菜单。
• 使用智能体自定义编辑器来切换插件的启用状态。

启用/禁用状态与插件配置是分开存储的，因此它不会影响共享的工作区设置。

禁用插件后，其技能、智能体、钩子、MCP 服务器和斜杠命令将不再可用。例如，来自禁用插件的技能不会出现在聊天：配置技能中。禁用的插件在智能体自定义编辑器和“扩展”视图中会以变暗的样式显示。

卸载插件

要移除插件，请在智能体插件 - 已安装视图中右键单击它，然后选择卸载。从外部源（如 npm、PyPI 或外部 Git 仓库）安装的插件将从磁盘中删除。内联在市场仓库中的插件将保留在磁盘上，但不再处于活动状态。

配置插件市场

默认情况下，VS Code 会从 copilot-plugins 和 awesome-copilot 中发现插件。你可以通过 chat.plugins.marketplaces 在 VS Code 中打开 在 VS Code Insiders 中打开 设置添加其他市场。

市场是包含插件定义的 Git 仓库。你可以用以下几种格式来引用它们：

• 简写：适用于公开 GitHub 仓库的 owner/repo。例如，anthropics/claude-code。
• HTTPS git 远程地址：以 .git 结尾的完整 URL。例如，https://github.com/anthropics/claude-code.git。
• SCP 风格的 git 远程地址：SSH 风格的引用。例如，git@github.com:anthropics/claude-code.git。
• 文件 URI：指向已在磁盘上克隆的市场仓库的 file:/// 路径。

还支持私有仓库。如果公共查询失败，VS Code 会退回到直接克隆仓库。

市场插件还可以引用外部包源，例如 npm 或 PyPI 包。有关完整的市场插件架构，请参阅 Claude Code 插件市场文档。

// settings.json
"chat.plugins.marketplaces": [
    "anthropics/claude-code"
]

使用本地插件

如果你手动克隆或下载了一个插件，你可以通过 chat.pluginLocations 在 VS Code 中打开 在 VS Code Insiders 中打开 设置来注册它。此设置将本地插件目录路径映射到启用或禁用状态。

// settings.json
"chat.pluginLocations": {
    "/path/to/my-plugin": true,
    "/path/to/another-plugin": false
}

将值设置为 true 以启用该插件，或设置为 false 以保持其已注册但处于禁用状态。

更新插件

当你从命令面板运行 Extensions: Check for Extension Updates 时，或者当启用了 extensions.autoUpdate 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置可由你的组织管理。请联系你的管理员进行更改。组织 时，VS Code 会每 24 小时自动检查一次插件更新。

更新操作会从克隆的市场仓库中拉取更改，并检查外部源插件的新版本。

源自 npm 或 PyPI 的插件绝不会自动更新。相反，它们会在“扩展”视图中显示一个更新按钮。选择该按钮会提示你在运行安装命令之前进行确认。如果在后台检查期间发现了更新，在你显式选择更新之前不会采取任何操作。

工作区插件推荐

项目可以通过在工作区设置（.claude/settings.json 或 .github/copilot/settings.json）中配置插件设置，来为团队成员推荐插件。

首次发送聊天消息时，VS Code 会显示一条通知。你可以通过打开“扩展”视图并通过 @agentPlugins @recommended 进行过滤来查看推荐的插件。

在设置文件中指定以下字段以配置工作区插件推荐：

• extraKnownMarketplaces：为项目注册额外的市场。这些市场会在你在“扩展”视图中搜索 @agentPlugins 时显示。

• enabledPlugins：列出应默认启用的插件。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/plugin-marketplace"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true
  }
}

跨工具兼容性

插件格式在 VS Code、GitHub Copilot CLI 和 Claude Code 之间共享。单个插件仓库可以同时在这三个工具中工作。

VS Code 通过在多个位置寻找 plugin.json 来自动检测插件格式，检查顺序如下：

1. .plugin/plugin.json
2. plugin.json（位于插件根目录）
3. .github/plugin/plugin.json
4. .claude-plugin/plugin.json

如果你为多个工具编写插件，你可以将 plugin.json 放在根目录，并在特定于格式的目录中使用符号链接或副本。请保持所有副本中的 name 字段相同，以避免冲突。

跨工具需要注意的关键差异

• 钩子文件位置：Claude 格式的插件期望钩子位于 hooks/hooks.json 中，而 Copilot 格式的插件使用根目录下的 hooks.json。VS Code 会自动检测该格式。
• 插件根令牌：Claude 格式的插件使用 ${CLAUDE_PLUGIN_ROOT} 来引用插件目录中的文件。此令牌在 Copilot 格式的插件中不可用。
• 技能命名：所有工具都要求 SKILL.md 中使用简单的短横线命名法。命名空间前缀（如 myorg/skillname）会导致加载失败且不予提示。

有关工具特定的详细信息，请参阅 GitHub Copilot CLI 插件参考和 Claude Code 插件市场文档。

疑难解答

安装后插件未显示

• 确认智能体插件已启用：检查 chat.plugins.enabled 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置可由你的组织管理。请联系你的管理员进行更改。组织 是否设置为 true。
• 验证 plugin.json 中的插件 name 字段仅使用小写字母、数字和连字符。斜杠、冒号或其他特殊字符会导致插件加载失败且不予提示。
• 检查 plugin.json 是否在识别的位置（请参阅跨工具兼容性）。

插件中的技能未加载

• 打开 SKILL.md 文件并检查 YAML frontmatter 中的 name 字段。名称必须是不带命名空间前缀的纯短横线命名法（例如 test-runner，而不是 myorg/test-runner）。无效的名称会导致该技能被跳过且不予提示。
• 确保技能目录名称与 SKILL.md frontmatter 中的 name 字段匹配。

插件版本未更新

• 在推送更改之前，提高 plugin.json（以及 marketplace.json 插件条目，如果适用）中的 version 字段。
• 从命令面板运行 Extensions: Check for Extension Updates 以触发更新检查。

安装失败，提示“目标路径已存在 (destination path already exists)”

当先前安装留下缓存数据时，可能会发生这种情况。删除缓存的插件目录并重试：

• macOS: ~/Library/Application Support/Code/agentPlugins/github.com/{org}/{repo}
• Linux: ~/.config/Code/agentPlugins/github.com/{org}/{repo}
• Windows: %APPDATA%\Code\agentPlugins\github.com\{org}\{repo}

相关资源

• 为 GitHub Copilot CLI 查找和安装插件
• GitHub Copilot CLI 插件参考
• 使用 Agent 技能
• 添加和管理 MCP 服务器
• 使用钩子实现生命周期自动化
• 创建自定义代理