# CodeBuddy 插件系统

CodeBuddy Code 支持强大的插件系统，允许您扩展和定制 CLI 的功能。通过插件，您可以添加新的命令、技能和 Hooks，从而打造符合您工作流程的个性化开发环境。

## 核心概念

### 什么是插件？

插件是一个可复用的功能包，可以包含以下组件：

- **Commands（命令）**：用户可以手动触发的斜杠命令
- **Skills（技能）**: AI 自动识别并调用的专业能力
- **Hooks（钩子）**：在特定事件触发时自动执行的操作

### 什么是插件市场？

插件市场是插件的发布和分发渠道，CodeBuddy 支持多种类型的插件市场：

- **本地目录市场**：从本地文件系统加载插件
- **GitHub 仓库市场**：从 GitHub 仓库获取插件
- **HTTP/HTTPS 市场**：从 HTTP(S) 服务器获取插件清单和插件包

## 快速开始

有三种方式管理插件：**团队配置自动安装**、**交互式界面** 和 **命令行子命令**。

### 方式一：团队配置自动安装（推荐）

团队可以通过在项目的 `.codebuddy/settings.json` 中配置 `extraKnownMarketplaces` 和 `enabledPlugins`，实现插件的自动安装和启用。当团队成员启动 CodeBuddy 时，系统会自动安装配置中指定的插件市场和插件。

#### 配置示例

在 `.codebuddy/settings.json` 中添加以下配置：

```json
{
  "extraKnownMarketplaces": {
    "team-marketplace": {
      "source": {
        "source": "github",
        "repo": "your-org/team-plugins-marketplace"
      }
    },
    "custom-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/plugins-marketplace"
      }
    }
  },
  "enabledPlugins": {
    "team-plugin-a@team-marketplace": true,
    "team-plugin-b@team-marketplace": true
  }
}
```

#### 配置说明

- **`extraKnownMarketplaces`**：定义额外的插件市场
  - 键名为市场名称（如 `team-marketplace`）
  - `source.source`:市场类型,支持 `github`、`git` 和 `url`
  - `source.repo`: GitHub 仓库路径(格式:`owner/repo`,仅当 source 为 `github` 时）
  - `source.url`: Git 仓库 URL 或 HTTP(S) marketplace.json URL（仅当 source 为 `git` 或 `url` 时）

- **`enabledPlugins`**：指定要启用的插件
  - 键名格式：`插件名@市场名`
  - 值为 `true` 表示启用,`false` 表示禁用

#### 自动安装流程

1. **启动检测**: CodeBuddy 启动时会自动检测配置文件
2. **市场安装**：自动安装 `extraKnownMarketplaces` 中未安装的市场
3. **插件安装**：自动安装 `enabledPlugins` 中已启用但未安装的插件
4. **后台执行**：安装过程在后台异步执行，不阻塞启动流程
5. **日志记录**：安装过程会记录详细日志，可通过 `--debug` 查看

#### 优势

- **团队统一**：确保团队成员使用相同的插件配置
- **自动化**：无需手动安装，提升开发效率
- **版本控制**：配置文件可提交到 Git，便于团队协作
- **灵活覆盖**：个人可在本地配置中覆盖团队配置

### 方式二：交互式界面

在 CodeBuddy 对话中输入 `/plugin`，会打开交互式插件管理界面。

#### 打开管理界面

```bash
/plugin
```

#### 界面功能

交互式界面包含以下 6 个 tab：

1. **Discover（发现）** - 浏览所有可用插件，查看安装数、描述等信息
   - 实时搜索插件
   - 显示插件安装统计
   - 快速安装插件

2. **Browse（浏览）** - 从已配置的市场中浏览和安装插件
   - 按市场分类浏览
   - 查看插件详情
   - 安装插件

3. **Installed（已安装）** - 管理已安装的插件
   - 查看已安装插件列表和状态
   - 启用/禁用插件
   - 卸载插件
   - 查看插件详细信息

4. **Marketplaces（市场）** - 管理插件市场
   - 查看已配置的市场列表
   - 更新市场信息
   - 移除市场

5. **Add Marketplace（添加市场）** - 添加新的插件市场源
   - 支持本地路径、GitHub 仓库、Git URL 和 HTTP URL
   - 自动识别市场源类型
   - 设置市场显示名称

6. **Errors（错误）** - 查看插件加载和操作过程中发生的错误
   - 详细的错误信息和错误类型
   - 错误发生时间和相关上下文
   - 帮助诊断和解决问题

#### 交互式命令示例

```bash
/plugin                                    # 打开管理界面
/plugin install my-plugin                  # 安装插件
/plugin install my-plugin@marketplace      # 从指定市场安装
/plugin enable my-plugin                   # 启用禁用的插件
/plugin disable my-plugin                  # 禁用启用的插件
/plugin uninstall my-plugin                # 卸载插件
/plugin marketplace add <source>           # 添加市场
/plugin marketplace list                   # 列出市场
/plugin marketplace update <name>          # 更新市场
/plugin marketplace remove <name>          # 移除市场
```

### 方式三：命令行子命令

在终端中使用 `codebuddy plugin` 命令进行管理。

#### 插件操作

```bash
# 安装插件
codebuddy plugin install <plugin>              # 从默认市场安装
codebuddy plugin install <plugin>@<marketplace> # 从指定市场安装
codebuddy plugin i <plugin>                    # 简写形式

# 启用和禁用插件
codebuddy plugin enable <plugin>               # 启用插件
codebuddy plugin disable <plugin>              # 禁用插件

# 卸载插件
codebuddy plugin uninstall <plugin>            # 卸载插件
codebuddy plugin remove <plugin>               # 别名形式

# 验证插件或市场清单
codebuddy plugin validate <path>               # 验证本地插件或市场
```

#### 市场管理

```bash
# 添加市场
codebuddy plugin marketplace add <source>
codebuddy plugin marketplace add <source> -n <name>   # 指定市场名称

# 列出市场
codebuddy plugin marketplace list

# 更新市场
codebuddy plugin marketplace update <name>

# 移除市场
codebuddy plugin marketplace remove <name>
codebuddy plugin marketplace rm <name>                # 别名形式
```

## 插件管理

### 添加插件市场

#### 使用交互式界面

1. 输入 `/plugin`
2. 选择 "3. Add marketplace"
3. 输入市场源地址
4. 等待自动识别市场类型和加载插件清单

#### 使用子命令

```bash
# 添加 GitHub 仓库市场
codebuddy plugin marketplace add https://github.com/username/plugin-repo

# 添加市场并指定显示名称
codebuddy plugin marketplace add https://github.com/username/plugin-repo -n my-marketplace

# 添加本地目录市场
codebuddy plugin marketplace add /path/to/local/plugins

# 添加 HTTP 市场
codebuddy plugin marketplace add https://example.com/plugins
```

**参数说明**:
- `<source>`：市场源地址（本地路径、GitHub URL 或 HTTP(S) URL）
- `-n, --name <name>`：可选，为市场指定显示名称

### 安装插件

#### 使用交互式界面

1. 输入 `/plugin`
2. 选择 "1. Browse and install plugins"
3. 选择插件市场
4. 浏览可用插件并选择安装

#### 使用子命令

```bash
# 从默认市场安装
codebuddy plugin install my-plugin

# 从指定市场安装
codebuddy plugin install my-plugin@marketplace-name

# 使用别名
codebuddy plugin i my-plugin
```

### 启用和禁用插件

#### 使用交互式界面

1. 输入 `/plugin`
2. 选择 "2. Manage plugins"
3. 选择要启用或禁用的插件

#### 使用子命令

```bash
# 启用插件
codebuddy plugin enable my-plugin

# 禁用插件
codebuddy plugin disable my-plugin
```

**注意**：启用/禁用插件后需要重启 CodeBuddy 才能生效。

### 卸载插件

#### 使用交互式界面

1. 输入 `/plugin`
2. 选择 "2. Manage plugins"
3. 选择要卸载的插件，确认卸载

#### 使用子命令

```bash
# 卸载插件
codebuddy plugin uninstall my-plugin

# 使用别名
codebuddy plugin remove my-plugin
```

### 管理插件市场

#### 列出市场

使用交互式界面：
1. 输入 `/plugin`
2. 选择 "4. Manage marketplaces"

使用子命令：
```bash
codebuddy plugin marketplace list
```

#### 更新市场

使用交互式界面：
1. 输入 `/plugin`
2. 选择 "4. Manage marketplaces"
3. 选择要更新的市场

使用子命令：
```bash
codebuddy plugin marketplace update my-marketplace
```

#### 移除市场

使用交互式界面：
1. 输入 `/plugin`
2. 选择 "4. Manage marketplaces"
3. 选择要移除的市场，确认移除

使用子命令：
```bash
codebuddy plugin marketplace remove my-marketplace
codebuddy plugin marketplace rm my-marketplace
```

### 验证插件或市场清单

```bash
# 验证插件清单格式
codebuddy plugin validate /path/to/plugin

# 验证市场清单格式
codebuddy plugin validate /path/to/marketplace

# 验证来自 GitHub 的插件清单
codebuddy plugin validate https://github.com/username/plugin-repo
```

验证命令会检查 `plugin.json` 或 `marketplace.json` 的格式和完整性。

## 插件结构

### 标准插件目录结构

```
my-plugin/
├── .codebuddy-plugin/     # 元数据目录（必需）
│   └── plugin.json        # 插件清单文件
├── commands/              # 命令目录（可选）
│   └── example.md
├── agents/                # 代理目录（可选）
│   └── example.md
├── skills/                # 技能目录（可选）
│   └── example/
│       └── SKILL.md
├── hooks/                 # Hooks 目录（可选）
│   └── hooks.json
├── .mcp.json              # MCP 配置文件（可选）
└── .lsp.json              # LSP 配置文件（可选）
```

### plugin.json 格式

插件清单文件定义插件的元数据和包含的组件，位于 `.codebuddy-plugin/plugin.json`：

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "插件描述",
  "author": {
    "name": "作者名称",
    "email": "author@example.com"
  },
  "homepage": "https://github.com/username/my-plugin",
  "repository": "https://github.com/username/my-plugin",
  "keywords": ["example"],
  "category": "开发工具",
  "commands": [],
  "agents": [],
  "skills": [],
  "hooks": "./hooks/hooks.json"
}
```

### Commands（命令）

插件可以提供自定义斜杠命令，用户可以手动触发。命令定义为 Markdown 文件。

**示例**: `commands/example.md`

```markdown

这是一个示例命令。当用户输入 /my-plugin:example 时会执行此命令。

参数： $1
```

命令会以 `/plugin-name:command-name` 的格式注册。

详细说明请参考： [Slash Commands 文档](slash-commands.md)

### Skills（技能）

技能是 AI 可以自动识别和调用的专业能力模板。

**示例**: `skills/SKILL.md`

```markdown
---
description: "技能描述"
---

技能的详细说明和使用场景...
```

详细说明请参考： [Skills 文档](skills.md)

### Hooks（钩子）

Hooks 允许在特定事件发生时自动执行操作。

**示例**: `hooks/hooks.json`

```json
{
  "hooks": {
    "user-prompt-submit-hook": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'User submitted: $INPUT'",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}
```

详细说明请参考： [Hooks 文档](hooks.md)

### LSP（Language Server Protocol）

LSP 插件为 AI 提供实时代码智能功能，使其能够理解代码结构、类型定义、函数签名等信息。

#### 使用建议

对于常见语言（如 TypeScript、Python、Rust 等），建议直接从官方插件市场安装预构建的 LSP 插件。仅在需要支持尚未覆盖的语言时，才需要创建自定义 LSP 插件。

#### 配置 LSP 服务器

通过在插件根目录添加 `.lsp.json` 文件来配置 LSP 服务器：

**示例**: `.lsp.json`

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

#### 配置字段说明

- **语言标识符** (如 `"go"`)：定义 LSP 服务器支持的语言
  - `command`：LSP 服务器可执行文件的命令名称
  - `args`：传递给命令的参数数组
  - `extensionToLanguage`：文件扩展名到语言标识符的映射

#### 多语言配置示例

```json
{
  "python": {
    "command": "pylsp",
    "args": [],
    "extensionToLanguage": {
      ".py": "python"
    }
  },
  "rust": {
    "command": "rust-analyzer",
    "args": [],
    "extensionToLanguage": {
      ".rs": "rust"
    }
  }
}
```

#### 安装要求

用户在安装包含 LSP 配置的插件时，必须在其系统上预先安装相应的语言服务器二进制文件。例如：

- **Go**: 需要安装 `gopls` (`go install golang.org/x/tools/gopls@latest`)
- **Python**: 需要安装 `python-lsp-server` (`pip install python-lsp-server`)
- **Rust**: 需要安装 `rust-analyzer` (`rustup component add rust-analyzer`)

#### 工作原理

1. CodeBuddy 启动时读取 `.lsp.json` 配置
2. 根据文件扩展名自动启动对应的 LSP 服务器
3. AI 通过 LSP 协议获取代码智能信息
4. 提供更准确的代码建议和修改

#### 最佳实践

1. **提供安装说明**：在插件的 README 中明确说明需要安装的语言服务器
2. **版本兼容性**：说明支持的语言服务器版本范围
3. **使用官方插件**：优先使用官方维护的 LSP 插件，避免重复工作
4. **测试充分**：确保 LSP 配置在不同操作系统上都能正常工作

## 插件市场类型

### GitHub 市场

从 GitHub 仓库发布和获取插件。

**仓库结构**:

```
plugin-repo/
├── .codebuddy-plugin/
│   └── marketplace.json       # 市场清单
└── plugins/
    ├── plugin1/
    │   ├── .codebuddy-plugin/
    │   │   └── plugin.json
    │   └── ...
    └── plugin2/
        ├── .codebuddy-plugin/
        │   └── plugin.json
        └── ...
```

**marketplace.json** 格式：

```json
{
  "name": "My Plugin Marketplace",
  "plugins": [
    {
      "name": "plugin1",
      "source": "plugins/plugin1",
      "description": "Plugin 1 description"
    },
    {
      "name": "plugin2",
      "source": "plugins/plugin2",
      "description": "Plugin 2 description"
    }
  ]
}
```

### HTTP 市场

通过 HTTP(S) 服务器提供插件。

**服务器要求**:

- 提供 `/marketplace.json` - 市场清单
- 提供 `/plugins/<plugin-name>/plugin.json` - 插件清单
- 提供插件文件下载

### 本地目录市场

从本地文件系统加载插件，适用于开发和测试。

**目录结构**:

```
local-plugins/
├── .codebuddy-plugin/
│   └── marketplace.json
└── plugins/
    └── my-plugin/
        ├── .codebuddy-plugin/
        │   └── plugin.json
        └── ...
```

## 最佳实践

### 插件开发建议

1. **遵循命名规范**：使用清晰、描述性的插件名称
2. **提供完整元数据**：在 `plugin.json` 中提供详细的描述和作者信息
3. **版本管理**：使用语义化版本号（Semantic Versioning）
4. **文档完善**：为每个命令和技能提供清晰的描述
5. **测试充分**：在本地市场中测试插件后再发布

### 安全注意事项

1. **仅从可信源安装插件**：插件可以执行命令和访问文件系统
2. **审查插件代码**：安装前检查插件的命令和 Hooks
3. **使用权限控制**：通过 CodeBuddy 的权限系统限制插件访问

### 插件发布流程

1. 创建插件目录和文件
2. 编写 `plugin.json`
3. 在本地市场测试插件
4. 创建 GitHub 仓库或 HTTP 服务器
5. 添加 `marketplace.json`
6. 分享市场地址给用户

## 故障排除

### 市场未加载

**问题**：无法添加市场或看不到来自它的插件

**解决方案**：

* 验证市场 URL 是否可访问
* 检查 `.codebuddy-plugin/marketplace.json` 是否存在于指定路径
* 使用 `codebuddy plugin validate` 确保 JSON 语法有效
* 对于私有存储库，确认您有访问权限

#### 插件安装失败

**问题**：市场出现但插件安装失败

**解决方案**：

* 验证插件源 URL 是否可访问
* 检查插件目录是否包含所需文件
* 对于 GitHub 来源，确保存储库是公开的或您有访问权限
* 通过手动克隆/下载来测试插件来源

### 插件未加载

**问题**：插件已安装但不工作

**解决方案**：

* 确认插件已启用：`/plugin` → "3. Installed"
* 检查 `plugin.json` 格式是否正确
* 重启 CodeBuddy 以加载新插件
* 使用 `--debug` 模式查看加载日志

### 命令不可用

**问题**：插件已安装但命令无法使用

**解决方案**：

* 确认命令路径在 `plugin.json` 中正确配置
* 检查命令文件是否存在
* 验证命令文件格式符合 Markdown 规范

### 市场连接失败

**问题**：无法连接到市场或获取插件列表

**解决方案**：

* **GitHub 市场**：检查网络连接和仓库访问权限
* **HTTP 市场**：确认服务器可访问
* **本地市场**：验证目录路径和权限

### 验证和测试

在共享前测试您的市场和插件：

```bash
# 验证市场 JSON 语法
codebuddy plugin validate .

# 验证特定插件
codebuddy plugin validate /path/to/plugin

# 添加本地市场用于测试
codebuddy plugin marketplace add ./path/to/marketplace

# 测试插件安装
codebuddy plugin install test-plugin@marketplace-name
```

## 相关文档

- **[插件参考文档](plugins-reference.md)** - 插件开发完整技术规范
- **[Slash Commands](slash-commands.md)** - 了解命令系统
- **[Skills](skills.md)** - 学习技能系统
- **[Hooks](hooks.md)** - 掌握 Hooks 机制

---

*通过插件系统，让 CodeBuddy 更强大 🚀*

