@tencent-ai/codebuddy-code 2.67.0 → 2.68.0-next.19b562c.20260330

package/dist/web-ui/docs/cn/cli/plugins.md

@@ -0,0 +1,689 @@
+# 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 更强大 🚀*
+