插件参考 - OpenClaude 中文社区

想要安装插件？请参阅发现和安装插件。如需创建插件，请参阅插件。如需分发插件，请参阅插件市场。

本参考提供了 Claude Code 插件系统的完整技术规范，包括组件架构、CLI 命令和开发工具。

插件组件参考

本部分记录了插件可以提供的组件类型。

Skills

插件向 Claude Code 添加 skills，创建可由您或 Claude 调用的 /name 快捷方式。位置：插件根目录中的 skills/ 或 commands/ 目录 文件格式：Skills 是包含 SKILL.md 的目录；commands 是简单的 markdown 文件 Skill 结构：

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (可选)
│   └── scripts/ (可选)
└── code-reviewer/
    └── SKILL.md

集成行为：

安装插件时会自动发现 Skills 和 commands
Claude 可以根据任务上下文自动调用它们
Skills 可以在 SKILL.md 旁边包含支持文件

有关完整详情，请参阅 Skills。

Agents

插件可以为特定任务提供专门的 subagents，Claude 可以在适当时自动调用。位置：插件根目录中的 agents/ 目录 文件格式：描述代理功能的 Markdown 文件 Agent 结构：

---
name: agent-name
description: 该代理的专长以及 Claude 应何时调用它
---

详细的系统提示，描述代理的角色、专业知识和行为。

集成点：

Agents 出现在 /agents 界面中
Claude 可以根据任务上下文自动调用 agents
Agents 可以由用户手动调用
插件 agents 与内置 Claude agents 一起工作

有关完整详情，请参阅 Subagents。

Hooks

插件可以提供事件处理程序，自动响应 Claude Code 事件。位置：插件根目录中的 hooks/hooks.json，或在 plugin.json 中内联格式：具有事件匹配器和操作的 JSON 配置 Hook 配置：

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

可用事件：

PreToolUse：Claude 使用任何工具之前
PostToolUse：Claude 成功使用任何工具之后
PostToolUseFailure：Claude 工具执行失败之后
PermissionRequest：显示权限对话框时
UserPromptSubmit：用户提交提示时
Notification：Claude Code 发送通知时
Stop：Claude 尝试停止时
SubagentStart：启动 subagent 时
SubagentStop：subagent 尝试停止时
SessionStart：会话开始时
SessionEnd：会话结束时
PreCompact：压缩对话历史之前

Hook 类型：

command：执行 shell 命令或脚本
prompt：使用 LLM 评估提示（使用 $ARGUMENTS 占位符表示上下文）
agent：运行具有工具的代理验证器以完成复杂验证任务

MCP servers

插件可以捆绑 Model Context Protocol (MCP) 服务器，将 Claude Code 与外部工具和服务连接。位置：插件根目录中的 .mcp.json，或在 plugin.json 中内联格式：标准 MCP 服务器配置 MCP 服务器配置：

{
  "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-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

集成行为：

启用插件时，插件 MCP 服务器会自动启动
服务器在 Claude 的工具包中显示为标准 MCP 工具
服务器功能与 Claude 的现有工具无缝集成
插件服务器可以独立于用户 MCP 服务器进行配置

LSP servers

想要使用 LSP 插件？从官方市场安装它们：在 /plugin 发现选项卡中搜索”lsp”。本部分记录如何为官方市场未涵盖的语言创建 LSP 插件。

插件可以提供 Language Server Protocol (LSP) 服务器，在处理代码库时为 Claude 提供实时代码智能。 LSP 集成提供：

即时诊断：Claude 在每次编辑后立即看到错误和警告
代码导航：转到定义、查找引用和悬停信息
语言感知：代码符号的类型信息和文档

位置：插件根目录中的 .lsp.json，或在 plugin.json 中内联格式：将语言服务器名称映射到其配置的 JSON 配置 .lsp.json 文件格式：

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

在 plugin.json 中内联：

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

必需字段：

字段	描述
`command`	要执行的 LSP 二进制文件（必须在 PATH 中）
`extensionToLanguage`	将文件扩展名映射到语言标识符

可选字段：

字段	描述
`args`	LSP 服务器的命令行参数
`transport`	通信传输：`stdio`（默认）或 `socket`
`env`	启动服务器时要设置的环境变量
`initializationOptions`	在初始化期间传递给服务器的选项
`settings`	通过 `workspace/didChangeConfiguration` 传递的设置
`workspaceFolder`	服务器的工作区文件夹路径
`startupTimeout`	等待服务器启动的最长时间（毫秒）
`shutdownTimeout`	等待正常关闭的最长时间（毫秒）
`restartOnCrash`	服务器崩溃时是否自动重启
`maxRestarts`	放弃前的最大重启尝试次数

您必须单独安装语言服务器二进制文件。 LSP 插件配置 Claude Code 如何连接到语言服务器，但它们不包括服务器本身。如果您在 /plugin 错误选项卡中看到 Executable not found in $PATH，请为您的语言安装所需的二进制文件。

可用的 LSP 插件：

插件	语言服务器	安装命令
`pyright-lsp`	Pyright (Python)	`pip install pyright` 或 `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-lsp`	rust-analyzer	参阅 rust-analyzer 安装

首先安装语言服务器，然后从市场安装插件。

插件安装范围

安装插件时，您选择一个范围，确定插件的可用位置和谁可以使用它：

范围	设置文件	用例
`user`	`~/.claude/settings.json`	在所有项目中可用的个人插件（默认）
`project`	`.claude/settings.json`	通过版本控制共享的团队插件
`local`	`.claude/settings.local.json`	项目特定的插件，gitignored
`managed`	`managed-settings.json`	托管插件（只读，仅更新）

插件使用与其他 Claude Code 配置相同的范围系统。有关安装说明和范围标志，请参阅安装插件。有关范围的完整说明，请参阅配置范围。

插件清单架构

.claude-plugin/plugin.json 文件定义了您的插件的元数据和配置。本部分记录了所有支持的字段和选项。清单是可选的。如果省略，Claude Code 会自动发现默认位置中的组件，并从目录名称派生插件名称。当您需要提供元数据或自定义组件路径时，使用清单。

完整架构

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "简要插件描述",
  "author": {
    "name": "作者名称",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

必需字段

如果您包含清单，name 是唯一必需的字段。

字段	类型	描述	示例
`name`	string	唯一标识符（kebab-case，无空格）	`"deployment-tools"`

此名称用于命名空间组件。例如，在 UI 中，名为 plugin-dev 的插件的 agent agent-creator 将显示为 plugin-dev:agent-creator。

元数据字段

字段	类型	描述	示例
`version`	string	语义版本。如果也在市场条目中设置，`plugin.json` 优先。您只需在一个地方设置它。	`"2.1.0"`
`description`	string	插件目的的简要说明	`"部署自动化工具"`
`author`	object	作者信息	`{"name": "Dev Team", "email": "dev@company.com"}`
`homepage`	string	文档 URL	`"https://docs.example.com"`
`repository`	string	源代码 URL	`"https://github.com/user/plugin"`
`license`	string	许可证标识符	`"MIT"`、`"Apache-2.0"`
`keywords`	array	发现标签	`["deployment", "ci-cd"]`

组件路径字段

字段	类型	描述	示例
`commands`	string\|array	其他命令文件/目录	`"./custom/cmd.md"` 或 `["./cmd1.md"]`
`agents`	string\|array	其他 agent 文件	`"./custom/agents/reviewer.md"`
`skills`	string\|array	其他 skill 目录	`"./custom/skills/"`
`hooks`	string\|array\|object	Hook 配置路径或内联配置	`"./my-extra-hooks.json"`
`mcpServers`	string\|array\|object	MCP 配置路径或内联配置	`"./my-extra-mcp-config.json"`
`outputStyles`	string\|array	其他输出样式文件/目录	`"./styles/"`
`lspServers`	string\|array\|object	Language Server Protocol 配置用于代码智能（转到定义、查找引用等）	`"./.lsp.json"`

路径行为规则

重要：自定义路径补充默认目录 - 它们不替换默认目录。

如果 commands/ 存在，除了自定义命令路径外，它也会被加载
所有路径必须相对于插件根目录，并以 ./ 开头
来自自定义路径的命令使用相同的命名和命名空间规则
可以将多个路径指定为数组以获得灵活性

路径示例：

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

环境变量

${CLAUDE_PLUGIN_ROOT}：包含插件目录的绝对路径。在 hooks、MCP 服务器和脚本中使用此变量，以确保无论安装位置如何都能使用正确的路径。

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

插件缓存和文件解析

出于安全和验证目的，Claude Code 将插件复制到缓存目录，而不是就地使用它们。在开发引用外部文件的插件时，理解此行为很重要。

插件缓存如何工作

插件通过以下两种方式之一指定：

通过 claude --plugin-dir，在会话期间。
通过市场，安装到本地插件缓存。

安装插件时，Claude Code 会定位其市场和该市场内插件的 source 字段。源可以是以下五种类型之一：

相对路径：递归复制到插件缓存。例如，如果您的市场条目指定 "source": "./plugins/my-plugin"，整个 ./plugins/my-plugin 目录会被复制。
npm - 从 npm 复制到插件缓存
pip - 从 pip 复制到插件缓存
url - 任何以 .git 结尾的 https:// URL
github - 任何 owner/repo 简写

路径遍历限制

插件无法引用其复制目录结构之外的文件。遍历插件根目录之外的路径（例如 ../shared-utils）在安装后将不起作用，因为这些外部文件不会被复制到缓存。

使用外部依赖

如果您的插件需要访问其目录之外的文件，您有两个选项： 选项 1：使用符号链接 在插件目录中创建指向外部文件的符号链接。在复制过程中会遵守符号链接：

# 在您的插件目录中
ln -s /path/to/shared-utils ./shared-utils

符号链接的内容将被复制到插件缓存中。 选项 2：重组您的市场 将插件路径设置为包含所有必需文件的父目录，然后直接在市场条目中提供插件清单的其余部分：

{
  "name": "my-plugin",
  "source": "./",
  "description": "需要根级访问的插件",
  "commands": ["./plugins/my-plugin/commands/"],
  "agents": ["./plugins/my-plugin/agents/"],
  "strict": false
}

此方法复制整个市场根目录，使您的插件可以访问兄弟目录。

指向插件逻辑根目录之外位置的符号链接在复制期间会被跟随。这在保持缓存系统安全优势的同时提供了灵活性。

插件目录结构

标准插件布局

完整的插件遵循此结构：

enterprise-plugin/
├── .claude-plugin/           # 元数据目录（可选）
│   └── plugin.json             # 插件清单
├── commands/                 # 默认命令位置
│   ├── status.md
│   └── logs.md
├── agents/                   # 默认 agent 位置
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Agent Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Hook 配置
│   ├── hooks.json           # 主 hook 配置
│   └── security-hooks.json  # 其他 hooks
├── .mcp.json                # MCP 服务器定义
├── .lsp.json                # LSP 服务器配置
├── scripts/                 # Hook 和实用脚本
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # 许可证文件
└── CHANGELOG.md             # 版本历史

.claude-plugin/ 目录包含 plugin.json 文件。所有其他目录（commands/、agents/、skills/、hooks/）必须在插件根目录，而不是在 .claude-plugin/ 内。

文件位置参考

组件	默认位置	目的
清单	`.claude-plugin/plugin.json`	插件元数据和配置（可选）
Commands	`commands/`	Skill Markdown 文件（遗留；新 skills 使用 `skills/`）
Agents	`agents/`	Subagent Markdown 文件
Skills	`skills/`	具有 `<name>/SKILL.md` 结构的 Skills
Hooks	`hooks/hooks.json`	Hook 配置
MCP 服务器	`.mcp.json`	MCP 服务器定义
LSP 服务器	`.lsp.json`	语言服务器配置

CLI 命令参考

Claude Code 提供了用于非交互式插件管理的 CLI 命令，对脚本和自动化很有用。

plugin install

从可用市场安装插件。

claude plugin install <plugin> [options]

参数：

<plugin>：插件名称或 plugin-name@marketplace-name 用于特定市场

选项：

选项	描述	默认值
`-s, --scope <scope>`	安装范围：`user`、`project` 或 `local`	`user`
`-h, --help`	显示命令帮助

范围确定将安装的插件添加到哪个设置文件。例如，—scope project 写入 .claude/settings.json 中的 enabledPlugins，使插件对克隆项目存储库的每个人都可用。 示例：

# 安装到用户范围（默认）
claude plugin install formatter@my-marketplace

# 安装到项目范围（与团队共享）
claude plugin install formatter@my-marketplace --scope project

# 安装到本地范围（gitignored）
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

删除已安装的插件。

claude plugin uninstall <plugin> [options]

参数：

<plugin>：插件名称或 plugin-name@marketplace-name

选项：

选项	描述	默认值
`-s, --scope <scope>`	从范围卸载：`user`、`project` 或 `local`	`user`
`-h, --help`	显示命令帮助

别名： remove、rm

plugin enable

启用禁用的插件。

claude plugin enable <plugin> [options]

参数：

<plugin>：插件名称或 plugin-name@marketplace-name

选项：

选项	描述	默认值
`-s, --scope <scope>`	启用范围：`user`、`project` 或 `local`	`user`
`-h, --help`	显示命令帮助

plugin disable

禁用插件而不卸载它。

claude plugin disable <plugin> [options]

参数：

<plugin>：插件名称或 plugin-name@marketplace-name

选项：

选项	描述	默认值
`-s, --scope <scope>`	禁用范围：`user`、`project` 或 `local`	`user`
`-h, --help`	显示命令帮助

plugin update

将插件更新到最新版本。

claude plugin update <plugin> [options]

参数：

<plugin>：插件名称或 plugin-name@marketplace-name

选项：

选项	描述	默认值
`-s, --scope <scope>`	更新范围：`user`、`project`、`local` 或 `managed`	`user`
`-h, --help`	显示命令帮助

调试和开发工具

调试命令

使用 claude --debug（或 TUI 中的 /debug）查看插件加载详情：这显示：

正在加载哪些插件
插件清单中的任何错误
命令、agent 和 hook 注册
MCP 服务器初始化

常见问题

问题	原因	解决方案
插件未加载	无效的 `plugin.json`	使用 `claude plugin validate` 或 `/plugin validate` 验证 JSON 语法
命令未出现	目录结构错误	确保 `commands/` 在根目录，而不是在 `.claude-plugin/` 中
Hooks 未触发	脚本不可执行	运行 `chmod +x script.sh`
MCP 服务器失败	缺少 `${CLAUDE_PLUGIN_ROOT}`	对所有插件路径使用变量
路径错误	使用了绝对路径	所有路径必须是相对的，并以 `./` 开头
LSP `Executable not found in $PATH`	未安装语言服务器	安装二进制文件（例如，`npm install -g typescript-language-server typescript`）

示例错误消息

清单验证错误：

Invalid JSON syntax: Unexpected token } in JSON at position 142：检查缺少的逗号、多余的逗号或未引用的字符串
Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required：缺少必需字段
Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...：JSON 语法错误

插件加载错误：

Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.：命令路径存在但不包含有效的命令文件
Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.：市场条目中的 source 路径指向不存在的目录
Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.：删除重复的组件定义或删除市场条目中的 strict: false

Hook 故障排除

Hook 脚本未执行：

检查脚本是否可执行：chmod +x ./scripts/your-script.sh
验证 shebang 行：第一行应该是 #!/bin/bash 或 #!/usr/bin/env bash
检查路径是否使用 ${CLAUDE_PLUGIN_ROOT}："command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
手动测试脚本：./scripts/your-script.sh

Hook 未在预期事件上触发：

验证事件名称是否正确（区分大小写）：PostToolUse，而不是 postToolUse
检查匹配器模式是否与您的工具匹配："matcher": "Write|Edit" 用于文件操作
确认 hook 类型有效：command、prompt 或 agent

MCP 服务器故障排除

服务器未启动：

检查命令是否存在且可执行
验证所有路径是否使用 ${CLAUDE_PLUGIN_ROOT} 变量
检查 MCP 服务器日志：claude --debug 显示初始化错误
在 Claude Code 外手动测试服务器

服务器工具未出现：

确保服务器在 .mcp.json 或 plugin.json 中正确配置
验证服务器是否正确实现 MCP 协议
检查调试输出中的连接超时

目录结构错误

症状：插件加载但组件（命令、agents、hooks）缺失。 正确结构：组件必须在插件根目录，而不是在 .claude-plugin/ 内。只有 plugin.json 属于 .claude-plugin/。

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 仅清单在此处
├── commands/            ← 在根级别
├── agents/              ← 在根级别
└── hooks/               ← 在根级别

如果您的组件在 .claude-plugin/ 内，请将它们移到插件根目录。 调试清单：

运行 claude --debug 并查找”loading plugin”消息
检查每个组件目录是否在调试输出中列出
验证文件权限允许读取插件文件

分发和版本管理参考

版本管理

遵循语义版本控制进行插件发布：

{
  "name": "my-plugin",
  "version": "2.1.0"
}

版本格式：MAJOR.MINOR.PATCH

MAJOR：破坏性更改（不兼容的 API 更改）
MINOR：新功能（向后兼容的添加）
PATCH：错误修复（向后兼容的修复）

最佳实践：

从 1.0.0 开始进行第一个稳定版本
在分发更改之前更新 plugin.json 中的版本
在 CHANGELOG.md 文件中记录更改
使用预发布版本，如 2.0.0-beta.1 进行测试

另请参阅

插件 - 教程和实际用法
插件市场 - 创建和管理市场
Skills - Skill 开发详情
Subagents - Agent 配置和功能
Hooks - 事件处理和自动化
MCP - 外部工具集成
设置 - 插件的配置选项

​插件组件参考

​Skills

​Agents

​Hooks

​MCP servers

​LSP servers

​插件安装范围

​插件清单架构

​完整架构

​必需字段

​元数据字段

​组件路径字段

​路径行为规则

​环境变量

​插件缓存和文件解析

​插件缓存如何工作

​路径遍历限制

​使用外部依赖

​插件目录结构

​标准插件布局

​文件位置参考

​CLI 命令参考

​plugin install

​plugin uninstall

​plugin enable

​plugin disable

​plugin update

​调试和开发工具

​调试命令

​常见问题

​示例错误消息

​Hook 故障排除

​MCP 服务器故障排除

​目录结构错误

​分发和版本管理参考

​版本管理

​另请参阅

插件组件参考

Skills

Agents

Hooks

MCP servers

LSP servers

插件安装范围

插件清单架构

完整架构

必需字段

元数据字段

组件路径字段

路径行为规则

环境变量

插件缓存和文件解析

插件缓存如何工作

路径遍历限制

使用外部依赖

插件目录结构

标准插件布局

文件位置参考

CLI 命令参考

plugin install

plugin uninstall

plugin enable

plugin disable

plugin update

调试和开发工具

调试命令

常见问题

示例错误消息

Hook 故障排除

MCP 服务器故障排除

目录结构错误

分发和版本管理参考

版本管理

另请参阅