Claude Code 插件是一个可安装的功能包，它将斜杠命令、子代理、MCP 服务器和钩子等多个自定义项捆绑在一起，通过一条命令完成全部安装与配置。本指南基于 Claude HowTo 教程仓库中的 07-plugins 模块，详细拆解其内部架构、分发生态、语言服务器协议配置及关键版本特性。

Claude Code 插件系统全解：架构、市场分发与 LSP 配置

插件是 Claude Code 中最高级的扩展机制。它并非单一功能，而是一个整合了多种自定义项的“可分发包”。根据源文件，插件将斜杠命令、子代理、MCP 服务器和钩子等组件打包，实现一键安装，极大简化了复杂工作流的部署与团队共享。

插件架构与核心组件

插件的顶层结构由其清单文件 plugin.json 定义，并捆绑了多个功能模块。

graph TB
    A["插件"]
    B["斜杠命令"]
    C["子代理"]
    D["MCP 服务器"]
    E["钩子"]
    F["配置"]

    A -->|捆绑| B
    A -->|捆绑| C
    A -->|捆绑| D
    A -->|捆绑| E
    A -->|捆绑| F

一个完整的插件目录结构如下所示，它清晰地划分了各组件的位置：

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 清单文件 (name, description, version, author)
├── commands/             # 斜杠命令 (Markdown 文件)
├── agents/               # 子代理定义
├── skills/               # 技能定义 (SKILL.md)
├── hooks/                # 事件钩子 (hooks.json)
├── .mcp.json             # MCP 服务器配置
├── .lsp.json             # LSP 服务器配置
├── bin/                  # 可执行文件 (自动添加到 PATH)
├── settings.json         # 默认设置
└── ...                   # 其他目录如 docs, templates, scripts

插件类型与市场分发

插件通过市场进行分发，不同类型决定了其可见性与权威性。

类型	范围	共享范围	权威来源	示例
Official	全局	所有用户	Anthropic	PR Review, Security Guidance
Community	公开	所有用户	社区	DevOps, Data Science
Organization	内部	团队成员	公司	内部标准，工具
Personal	个人	单个用户	开发者	自定义工作流

市场定义与配置

市场通过 marketplace.json 定义。企业管理员可以通过 blockedMarketplaces（支持 hostPattern/pathPattern 正则，v2.1.119+）和 strictKnownMarketplaces 等设置来严格控制插件来源，这些控制在每次插件生命周期事件（安装、更新等）中都会执行（v2.1.117+）。

// .claude-plugin/marketplace.json 示例
{
  "name": "my-team-plugins",
  "owner": "my-org",
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "description": "Enforce team coding standards",
      "version": "1.2.0"
    }
  ]
}

市场管理命令

claude plugin marketplace add <source>       # 添加市场（支持 GitHub、URL、本地路径）
claude plugin marketplace update [name]      # 刷新目录索引（不更新已安装插件）
claude plugin marketplace remove <name>      # 移除市场
claude plugin marketplace list               # 列出已配置市场

LSP 服务器配置

插件可以内嵌语言服务器协议（LSP）支持，提供实时代码智能。配置文件可以是插件根目录的 .lsp.json，或是 plugin.json 中的 lsp 字段。

字段参考：

字段	必需	说明
`command`	是	LSP 服务器二进制文件（必须在 PATH 中）
`extensionToLanguage`	是	将文件扩展名映射到语言 ID
`args`	否	命令行参数
`transport`	否	通信方式：`stdio`（默认）或 `socket`
`env`	否	服务器进程的环境变量
`initializationOptions`	否	LSP 初始化时发送的选项

配置示例：

Go (gopls):

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {".go": "go"}
  }
}

Python (pyright):

{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {".py": "python", ".pyi": "python"}
  }
}

TypeScript:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {".ts": "typescript", ".tsx": "typescriptreact", ".js": "javascript", ".jsx": "javascriptreact"}
  }
}

配置后，LSP 服务器将提供即时诊断、代码导航、悬停信息和符号列表等功能。

关键机制与版本特性

`bin/` 目录与 PATH

当插件启用时，其 bin/ 目录会被前置到当前会话的 PATH 环境变量中。目录下的可执行文件（需 chmod +x）可直接在 Bash 工具中通过名称调用。

# 插件结构
my-plugin/
└── bin/
    └── my-tool          # 可执行文件

# 启用插件后，在会话中直接运行
$ my-tool --help

用户配置与敏感值 (`userConfig`)

插件可在 plugin.json 中声明用户可配置选项。标记为 sensitive: true 的值会存储在系统钥匙串中，而非明文设置文件。

{
  "userConfig": {
    "apiKey": { "description": "API key", "sensitive": true },
    "region": { "description": "Deploy region", "default": "us-east-1" }
  }
}

持久化数据目录 (`${CLAUDE_PLUGIN_DATA}`) (v2.1.78+)

每个插件都有一个通过 ${CLAUDE_PLUGIN_DATA} 环境变量访问的持久状态目录，数据跨会话保存，适用于缓存或数据库。

{
  "hooks": {
    "PostToolUse": [
      { "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" }
    ]
  }
}

背景监控器 (v2.1.105)

插件可以注册背景监控器，在会话开始或技能调用时自动启动。

{
  "monitors": [
    { "command": "tail -f /var/log/app.log", "trigger": "session_start" }
  ]
}

trigger 接受 "session_start" 或 "skill_invoke"。

内联插件定义 (`source: 'settings'`) (v2.1.80+)

可以在设置文件中直接内联定义插件，无需单独仓库。

{
  "pluginMarketplaces": [
    {
      "name": "inline-tools",
      "source": "settings",
      "plugins": [
        { "name": "quick-lint", "source": "./local-plugins/quick-lint" }
      ]
    }
  ]
}

重要版本特性

斜杠命令空格调用 (v2.1.136+)：插件斜杠命令支持使用空格调用，例如 /myplugin review 等同于 /myplugin:review。冒号形式是规范形式。
单技能插件模式 (v2.1.142+)：一个在根目录拥有 SKILL.md 且没有 skills/ 子目录的插件，其自身就会作为一个单一技能被呈现。这适用于小型单技能插件。
上下文成本预估 (v2.1.143)：在 /plugin 市场浏览器中，会显示每个插件的预计每轮上下文令牌成本（即始终加载的技能、钩子和 MCP 服务器描述符的总和），帮助用户在安装前评估。安装后可通过 claude plugin details <name> 查看。
```
NAME              VERSION   AUTHOR     CTX/TURN   DESCRIPTION
code-reviewer     1.2.0     anthropic  +1,420     Multi-agent PR review
```

插件安装、管理与 CLI 命令

安装来源：

市场：/plugin install plugin-name 或 claude plugin install plugin-name@marketplace
Git 仓库：/plugin install github:username/repo
本地路径：claude --plugin-dir ./path/to/plugin （v2.1.128+ 也支持 .zip 文件）

核心 CLI 管理命令：

claude plugin install <name>                # 安装插件
claude plugin uninstall <name> [--prune]    # 卸载插件 (--prune 清理孤立依赖)
claude plugin update <name>                 # 更新插件
claude plugin list                          # 列出已安装插件
claude plugin enable/disable <name>         # 启用/禁用插件
claude plugin details <name>                # 查看插件详情与预估成本 (v2.1.139+)
claude plugin tag <version>                 # 创建发布标签 (v2.1.118+)
claude plugin prune                         # 清理孤立的自动安装依赖 (v2.1.121+)

依赖管理 (v2.1.143)：claude plugin disable <name> 会拒绝禁用被其他启用插件依赖的插件。claude plugin enable <name> 会强制启用传递性依赖。

何时创建插件

创建插件的决策流程如下，应优先考虑打包、团队共享和自动配置的需求。

graph TD
    A["是否应该创建插件?"]
    A -->|需要多个组件| B{"多个命令<br/>或子代理<br/>或MCP?"}
    B -->|是| C["✅ 创建插件"]
    B -->|否| D["使用独立功能"]
    A -->|团队工作流| E{"与团队共享?"}
    E -->|是| C
    E -->|否| F["保持为本地设置"]
    A -->|复杂设置| G{"需要自动配置?"}
    G -->|是| C
    G -->|否| D

最佳实践：保持插件聚焦和内聚，使用清晰的命名，编写全面的 README，正确进行语义化版本控制，并在发布前使用 claude --plugin-dir ./my-plugin 进行充分测试。

FAQ

Q: 插件和独立的斜杠命令/技能有什么区别？ A: 独立的功能（如单个斜杠命令）适合个人、项目特定的快速自动化。插件则是一个“捆绑包”，能将多个功能（命令、子代理、MCP、钩子等）打包成一个可一键安装、便于版本控制和团队共享的单元。

Q: 如何为我的插件添加代码智能（LSP）支持？ A: 在插件根目录创建 .lsp.json 文件，或在 plugin.json 中添加 lsp 字段。你需要为每种目标语言配置 command（LSP 服务器二进制）和 extensionToLanguage（文件扩展名到语言 ID 的映射）。例如，为 Python 配置 pyright。

Q: 管理插件版本和依赖的推荐做法是什么？ A: 使用 claude plugin tag <version> 创建带验证的发布标签。对于依赖关系，利用 claude plugin disable 的保护机制防止破坏依赖图，并使用 claude plugin prune 或 uninstall --prune 清理卸载后遗留的孤立依赖。

Claude Code 插件系统全解：架构、市场分发与 LSP 配置 #

插件架构与核心组件 #

插件类型与市场分发 #

市场定义与配置 #

市场管理命令 #

LSP 服务器配置 #

关键机制与版本特性 #

bin/ 目录与 PATH #

用户配置与敏感值 (userConfig) #

持久化数据目录 (${CLAUDE_PLUGIN_DATA}) (v2.1.78+) #

背景监控器 (v2.1.105) #

内联插件定义 (source: 'settings') (v2.1.80+) #

重要版本特性 #

插件安装、管理与 CLI 命令 #

何时创建插件 #

FAQ #