20.3 安装与管理插件

插件安装基础

1. 安装前准备

# 检查系统要求
claude plugin requirements

# 更新 Claude Code 到最新版本
claude update

# 检查插件市场连接
claude plugin marketplace ping

2. 安装方式比较

安装方式	优点	缺点	使用场景
命令行安装	灵活、自动化、脚本化	需要记住命令	批量安装、自动化脚本
斜杠命令安装	快捷、交互式	功能有限	快速安装单个插件
UI 界面安装	直观、易用	手动操作	探索和发现插件
本地文件安装	离线可用、自定义	需要手动管理版本	开发和测试插件

高级安装选项

1. 版本管理

# 安装特定版本
claude plugin install formatter@your-org@1.0.0

# 安装最新版本
claude plugin install formatter@your-org@latest

# 安装预发布版本
claude plugin install formatter@your-org@beta

# 安装特定范围的版本
claude plugin install formatter@your-org@"^1.0.0"
claude plugin install formatter@your-org@">=1.0.0 <2.0.0"

2. 安装源管理

# 从官方市场安装
claude plugin install formatter@anthropic

# 从自定义市场安装
claude plugin install formatter@your-org

# 从 Git 仓库安装
claude plugin install git://github.com/your-org/formatter-plugin.git
claude plugin install git://github.com/your-org/formatter-plugin.git#branch-name
claude plugin install git://github.com/your-org/formatter-plugin.git#tag-name

# 从本地目录安装
claude plugin install ./formatter-plugin

# 从压缩包安装
claude plugin install ./formatter-plugin.zip

3. 批量安装

# 从文件批量安装插件
claude plugin install --file plugins.txt

# plugins.txt 格式：
# formatter@your-org@1.0.0
# linter@your-org@2.5.0
# tester@your-org@3.1.0

插件管理高级功能

1. 插件状态管理

# 查看插件状态
claude plugin status formatter@your-org

# 插件状态说明：
# - installed: 已安装但未启用
# - enabled: 已启用并正在运行
# - disabled: 已禁用
# - outdated: 需要更新
# - error: 安装或运行出错

# 查看所有插件状态
claude plugin status --all

2. 插件配置

# 查看插件配置
claude plugin config formatter@your-org

# 修改插件配置
claude plugin config formatter@your-org --set indent_size=4
claude plugin config formatter@your-org --set line_length=120

# 重置插件配置
claude plugin config formatter@your-org --reset

# 导出插件配置
claude plugin config formatter@your-org --export config.json

# 导入插件配置
claude plugin config formatter@your-org --import config.json

3. 插件依赖管理

# 查看插件依赖
claude plugin dependencies formatter@your-org

# 安装插件依赖
claude plugin dependencies --install formatter@your-org

# 检查依赖冲突
claude plugin dependencies --check formatter@your-org

# 解决依赖冲突
claude plugin dependencies --resolve formatter@your-org

4. 插件日志管理

# 查看插件日志
claude plugin logs formatter@your-org

# 查看实时日志
claude plugin logs --follow formatter@your-org

# 过滤日志级别
claude plugin logs --level error formatter@your-org
claude plugin logs --level warning formatter@your-org
claude plugin logs --level info formatter@your-org

# 导出日志
claude plugin logs --export logs.txt formatter@your-org

插件生命周期管理

1. 安装阶段

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User          │────▶│  Plugin        │────▶│  Plugin        │
│  initiates      │     │   Manager      │     │   Repository   │
│  installation   │     │                │     │                │
└─────────────────┘     └─────────────────┘     └─────────────────┘
          │                        │                        │
          ▼                        ▼                        ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Download       │     │  Verify        │     │  Extract        │
│  plugin         │     │  integrity     │     │  plugin files   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
          │                        │                        │
          ▼                        ▼                        ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Install        │     │  Register      │     │  Notify         │
│  dependencies   │     │  plugin        │     │  user           │
└─────────────────┘     └─────────────────┘     └─────────────────┘

2. 启用阶段

# 启用插件时的操作：
# 1. 加载插件代码
# 2. 初始化插件上下文
# 3. 注册插件扩展点
# 4. 启动插件服务
# 5. 通知插件已启用

3. 运行阶段

# 插件运行时监控：
claude plugin monitor formatter@your-org

# 监控指标：
# - CPU 使用率
# - 内存占用
# - 响应时间
# - 错误率
# - 吞吐量

4. 卸载阶段

# 卸载插件时的操作：
# 1. 停止插件服务
# 2. 注销插件扩展点
# 3. 清理插件文件
# 4. 移除插件配置
# 5. 通知插件已卸载

插件管理最佳实践

1. 组织插件

# 创建插件组
claude plugin group create development "开发工具"
claude plugin group create testing "测试工具"
claude plugin group create deployment "部署工具"

# 将插件添加到组
claude plugin group add development formatter@your-org
claude plugin group add development linter@your-org
claude plugin group add development debugger@your-org

# 批量管理组内插件
claude plugin group enable development
claude plugin group disable development
claude plugin group update development

2. 自动化管理

# 插件管理脚本示例
#!/bin/bash

# 备份当前插件配置
claude plugin export plugins-backup.json

# 更新所有插件
claude plugin update --all

# 检查插件状态
claude plugin status --all > plugins-status.txt

# 清理未使用的插件
claude plugin prune

3. 版本控制策略

# 稳定版本策略
claude plugin install formatter@your-org@"~1.0.0"  # 安装 1.0.x 系列的最新版本

# 自动更新策略
claude plugin install formatter@your-org@"^1.0.0"  # 安装 >=1.0.0 <2.0.0 的最新版本

# 固定版本策略
claude plugin install formatter@your-org@1.0.0      # 精确安装 1.0.0 版本

故障排除

1. 常见安装错误

错误：依赖冲突

Error: Dependency conflict: plugin A requires version 1.0.0 of library X, but plugin B requires version 2.0.0

解决方案：

# 检查依赖树
claude plugin dependencies --tree plugin-a
claude plugin dependencies --tree plugin-b

# 尝试安装兼容版本
claude plugin install plugin-a@1.0.0
claude plugin install plugin-b@2.0.0

# 或者使用隔离模式
claude plugin install --isolated plugin-a

错误：权限不足

Error: Permission denied: plugin requires file system access

解决方案：

# 查看权限请求
claude plugin permissions plugin-name

# 授予权限
claude plugin permissions --allow file:read plugin-name

错误：网络问题

Error: Network error: unable to connect to plugin marketplace

解决方案：

# 检查网络连接
claude plugin marketplace ping

# 使用代理
claude plugin marketplace --proxy http://proxy:port

# 从本地安装
claude plugin install ./plugin-file.zip

2. 插件诊断工具

# 运行插件诊断
claude plugin diagnose plugin-name

# 诊断内容包括：
# - 插件状态检查
# - 依赖检查
# - 权限检查
# - 配置检查
# - 日志分析

# 生成诊断报告
claude plugin diagnose --report plugin-name > plugin-diagnosis.txt

插件管理自动化

1. CI/CD 集成

# GitHub Actions 示例
name: Install Plugins
on: [push]

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Claude Code
        run: curl -sSL https://claude.ai/install | sh
      - name: Install plugins
        run: claude plugin install --file plugins.txt

2. 配置即代码

// plugins.json
{
  "plugins": [
    {
      "name": "formatter@your-org",
      "version": "1.0.0",
      "enabled": true,
      "config": {
        "indent_size": 4,
        "line_length": 120
      }
    },
    {
      "name": "linter@your-org",
      "version": "2.5.0",
      "enabled": true
    }
  ]
}

# 从配置文件安装插件
claude plugin import plugins.json

小结

插件的安装与管理是 Claude Code 扩展功能的核心技能。通过掌握不同的安装方式、版本管理策略和自动化技巧，开发者可以高效地管理插件生态系统，保持开发环境的稳定性和安全性。

下一节我们将介绍插件权限管理的重要性和最佳实践。