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 表示禁用

自动安装流程

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

优势

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

方式二：交互式界面

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

打开管理界面

bash

/plugin

界面功能

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

Discover（发现） - 浏览所有可用插件，查看安装数、描述等信息
- 实时搜索插件
- 显示插件安装统计
- 快速安装插件
Browse（浏览） - 从已配置的市场中浏览和安装插件
- 按市场分类浏览
- 查看插件详情
- 安装插件
Installed（已安装） - 管理已安装的插件
- 查看已安装插件列表和状态
- 启用/禁用插件
- 卸载插件
- 查看插件详细信息
Marketplaces（市场） - 管理插件市场
- 查看已配置的市场列表
- 更新市场信息
- 移除市场
Add Marketplace（添加市场） - 添加新的插件市场源
- 支持本地路径、GitHub 仓库、Git URL 和 HTTP URL
- 自动识别市场源类型
- 设置市场显示名称
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>                # 别名形式

插件管理

添加插件市场

使用交互式界面

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

使用子命令

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>：可选，为市场指定显示名称

安装插件

使用交互式界面

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

使用子命令

bash

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

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

# 使用别名
codebuddy plugin i my-plugin

启用和禁用插件

使用交互式界面

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

使用子命令

bash

# 启用插件
codebuddy plugin enable my-plugin

# 禁用插件
codebuddy plugin disable my-plugin

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

卸载插件

使用交互式界面

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

使用子命令

bash

# 卸载插件
codebuddy plugin uninstall my-plugin

# 使用别名
codebuddy plugin remove my-plugin

管理插件市场

列出市场

使用交互式界面：

输入 /plugin
选择 "4. Manage marketplaces"

使用子命令：

bash

codebuddy plugin marketplace list

更新市场

使用交互式界面：

输入 /plugin
选择 "4. Manage marketplaces"
选择要更新的市场

使用子命令：

bash

codebuddy plugin marketplace update my-marketplace

移除市场

使用交互式界面：

输入 /plugin
选择 "4. Manage marketplaces"
选择要移除的市场，确认移除

使用子命令：

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

---
description: "示例命令描述"
argument-hint: "[参数]"
---

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

参数： $1

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

详细说明请参考： Slash Commands 文档

Skills（技能）

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

示例: skills/SKILL.md

markdown

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

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

详细说明请参考： Skills 文档

Hooks（钩子）

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

示例: hooks/hooks.json

json

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

详细说明请参考： Hooks 文档

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)

工作原理

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

最佳实践

提供安装说明：在插件的 README 中明确说明需要安装的语言服务器
版本兼容性：说明支持的语言服务器版本范围
使用官方插件：优先使用官方维护的 LSP 插件，避免重复工作
测试充分：确保 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",
      "path": "plugins/plugin1"
    },
    {
      "name": "plugin2",
      "path": "plugins/plugin2"
    }
  ]
}

HTTP 市场

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

服务器要求:

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

本地目录市场

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

目录结构:

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

最佳实践

插件开发建议

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

安全注意事项

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

插件发布流程

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

故障排除

市场未加载

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

解决方案：

验证市场 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

CodeBuddy 插件系统 ​

核心概念 ​

什么是插件？ ​

什么是插件市场？ ​

快速开始 ​

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

配置示例 ​

配置说明 ​

自动安装流程 ​

优势 ​

方式二：交互式界面 ​

打开管理界面 ​

界面功能 ​

交互式命令示例 ​

方式三：命令行子命令 ​

插件操作 ​

市场管理 ​

插件管理 ​

添加插件市场 ​

使用交互式界面 ​

使用子命令 ​

安装插件 ​

使用交互式界面 ​

使用子命令 ​

启用和禁用插件 ​

使用交互式界面 ​

使用子命令 ​

卸载插件 ​

使用交互式界面 ​

使用子命令 ​

管理插件市场 ​

列出市场 ​

更新市场 ​

移除市场 ​

验证插件或市场清单 ​

插件结构 ​

标准插件目录结构 ​

plugin.json 格式 ​

Commands（命令） ​

Skills（技能） ​

Hooks（钩子） ​

LSP（Language Server Protocol） ​

使用建议 ​

配置 LSP 服务器 ​

配置字段说明 ​

多语言配置示例 ​

安装要求 ​

工作原理 ​

最佳实践 ​

插件市场类型 ​

GitHub 市场 ​

HTTP 市场 ​

本地目录市场 ​

最佳实践 ​

插件开发建议 ​

安全注意事项 ​

插件发布流程 ​

故障排除 ​

市场未加载 ​

插件安装失败 ​

插件未加载 ​

命令不可用 ​

市场连接失败 ​

验证和测试 ​

相关文档 ​

CodeBuddy 插件系统

核心概念

什么是插件？

什么是插件市场？

快速开始

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

配置示例

配置说明

自动安装流程

优势

方式二：交互式界面

打开管理界面

界面功能

交互式命令示例

方式三：命令行子命令

插件操作

市场管理

插件管理

添加插件市场

使用交互式界面

使用子命令

安装插件

使用交互式界面

使用子命令

启用和禁用插件

使用交互式界面

使用子命令

卸载插件

使用交互式界面

使用子命令

管理插件市场

列出市场

更新市场

移除市场

验证插件或市场清单

插件结构

标准插件目录结构

plugin.json 格式

Commands（命令）

Skills（技能）

Hooks（钩子）

LSP（Language Server Protocol）

使用建议

配置 LSP 服务器

配置字段说明

多语言配置示例

安装要求

工作原理

最佳实践

插件市场类型

GitHub 市场

HTTP 市场

本地目录市场

最佳实践

插件开发建议

安全注意事项

插件发布流程

故障排除

市场未加载

插件安装失败

插件未加载

命令不可用

市场连接失败

验证和测试

相关文档