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 会在运行时扩展该令牌，并将其作为环境变量设置在钩子或服务器进程中。

插件中的钩子 (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 服务器并列显示。您可以通过相同的工具管理它们

• 在聊天视图中选择配置工具以查看来自所有 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 remote：以 .git 结尾的完整 URL。例如，https://github.com/anthropics/claude-code.git。
• SCP 风格 git remote：SSH 风格的引用。例如，git@github.com:anthropics/claude-code.git。
• file 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 中的名称为纯 Kebab-case。命名空间前缀（如 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 字段。名称必须是纯 Kebab-case，不能带有命名空间前缀（例如 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 服务器
• 使用钩子进行生命周期自动化
• 创建自定义代理