VS Code 中的智能体插件 (预览版)

智能体插件是聊天自定义配置的预打包集合，您可以从 Visual Studio Code 中的插件市场发现并安装它们。单个插件可以提供斜杠命令、智能体技能 (agent skills)、自定义智能体、钩子和 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

安装后，插件提供的自定义项将与您本地定义的自定义项一起显示。例如，来自插件的技能会出现在“配置技能 (Configure Skills)”菜单中，来自插件的 MCP 服务器会出现在 MCP 服务器列表中。

插件中的钩子 (Hooks)

插件可以包含在智能体生命周期节点运行 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 钩子配置，包括匹配器 (matcher) 语法。目前，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"
          }
        ]
      }
    ]
  }
}

VS Code 会解析 matcher 字段以兼容 Claude Code，但目前会忽略匹配器值。如果您需要在 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 服务器一起显示。您可以使用相同的工具管理它们

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

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

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

发现并安装插件

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

浏览可用插件

1. 打开扩展视图（⇧⌘X (Windows, Linux Ctrl+Shift+X)），并在搜索字段中输入 @agentPlugins。

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

2. 从已配置的市场中浏览可用插件列表。

   

3. 选择“安装 (Install)”以在您的用户配置文件中安装插件。

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

从源安装插件

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

• 从命令面板运行“Chat: Install Plugin From Source”。
• 或者，在聊天自定义编辑器的“插件 (Plugins)”页面上选择“+”按钮。

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

查看已安装插件

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

您还可以通过选择齿轮图标 > “插件 (Plugins)”从聊天视图管理已安装的插件。

启用或禁用插件

您可以全局或为特定工作区启用或禁用插件

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

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

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

卸载插件

要删除插件，请在“智能体插件 - 已安装”视图中右键单击它，然后选择“卸载 (Uninstall)”。从外部源（如 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 中打开 的情况下每 24 小时，VS Code 都会检查插件更新。

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

从 npm 或 PyPI 获取的插件永远不会自动更新。相反，它们会在扩展视图中显示一个“更新 (Update)”按钮。选择该按钮会提示您在运行安装命令前进行确认。如果在后台检查期间发现更新，除非您明确选择“更新”，否则不会采取任何操作。

工作区插件推荐

项目可以通过在工作区设置中配置插件设置来为团队成员推荐插件。

• enabledPlugins：列出应默认启用的插件。VS Code 在首次发送聊天消息时会显示通知，并在扩展视图的 @agentPlugins @recommended 下列出这些插件。
• extraKnownMarketplaces：为项目注册额外的市场。当您在扩展视图中搜索 @agentPlugins 时，这些市场会出现。

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

相关资源

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