@tencent-ai/codebuddy-code 2.76.0-next.949c0a4.20260403 → 2.77.0

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

@@ -1,427 +1,269 @@
-# CodeBuddy 插件系统
+# 创建插件
 
-CodeBuddy Code 支持强大的插件系统，允许您扩展和定制 CLI 的功能。通过插件，您可以添加新的命令、技能和 Hooks，从而打造符合您工作流程的个性化开发环境。
+插件让你可以通过自定义技能、代理、钩子和 MCP 服务器来扩展 CodeBuddy Code 的功能。本指南涵盖如何创建你自己的插件。
 
-## 核心概念
+要安装已有的插件，请参阅[插件市场](plugin-marketplaces.md)。完整的技术规范请参考[插件参考文档](plugins-reference.md)。
 
-### 什么是插件？
+## 何时使用插件 vs 独立配置
 
-插件是一个可复用的功能包，可以包含以下组件：
+CodeBuddy Code 支持两种添加自定义技能、代理和钩子的方式：
 
-- **Commands（命令）**：用户可以手动触发的斜杠命令
-- **Skills（技能）**: AI 自动识别并调用的专业能力
-- **Hooks（钩子）**：在特定事件触发时自动执行的操作
+| 方式 | 技能名称 | 适用场景 |
+|------|----------|----------|
+| **独立配置**（`.codebuddy/` 目录） | `/hello` | 个人工作流、项目特定定制、快速实验 |
+| **插件**（含 `.codebuddy-plugin/plugin.json` 的目录） | `/plugin-name:hello` | 团队共享、社区分发、版本化发布、跨项目复用 |
 
-### 什么是插件市场？
+**使用独立配置的场景**：
 
-插件市场是插件的发布和分发渠道，CodeBuddy 支持多种类型的插件市场：
+- 为单个项目定制 CodeBuddy Code
+- 配置是个人的，不需要共享
+- 在打包为插件之前实验技能或钩子
+- 需要简短的技能名称，如 `/hello` 或 `/deploy`
 
-- **本地目录市场**：从本地文件系统加载插件
-- **GitHub 仓库市场**：从 GitHub 仓库获取插件
-- **HTTP/HTTPS 市场**：从 HTTP(S) 服务器获取插件清单和插件包
+**使用插件的场景**：
 
-## 快速开始
-
-有三种方式管理插件：**团队配置自动安装**、**交互式界面** 和 **命令行子命令**。
-
-### 方式一：团队配置自动安装（推荐）
-
-团队可以通过在项目的 `.codebuddy/settings.json` 中配置 `extraKnownMarketplaces` 和 `enabledPlugins`，实现插件的自动安装和启用。当团队成员启动 CodeBuddy 时，系统会自动安装配置中指定的插件市场和插件。
+- 需要与团队或社区共享功能
+- 需要在多个项目中使用相同的技能/代理
+- 需要版本控制和便捷的更新机制
+- 通过市场分发
+- 可以接受命名空间化的技能名称如 `/my-plugin:hello`（命名空间防止插件间冲突）
 
-#### 配置示例
+> **提示**：先在 `.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（发现）** - 浏览所有可用插件，查看安装数、描述等信息
-   - 实时搜索插件
-   - 显示插件安装统计
-   - 快速安装插件
+本快速开始将引导你创建一个包含自定义技能的插件。你将创建一个清单文件（定义插件的配置文件）、添加一个技能，并使用 `--plugin-dir` 参数在本地测试。
 
-2. **Browse（浏览）** - 从已配置的市场中浏览和安装插件
-   - 按市场分类浏览
-   - 查看插件详情
-   - 安装插件
+### 前提条件
 
-3. **Installed（已安装）** - 管理已安装的插件
-   - 查看已安装插件列表和状态
-   - 启用/禁用插件
-   - 卸载插件
-   - 查看插件详细信息
+- 已[安装并认证](quickstart.md) CodeBuddy Code
 
-4. **Marketplaces（市场）** - 管理插件市场
-   - 查看已配置的市场列表
-   - 更新市场信息
-   - 移除市场
+> 如果看不到 `/plugin` 命令，请将 CodeBuddy Code 更新到最新版本。参见[故障排除](troubleshooting.md)获取升级说明。
 
-5. **Add Marketplace（添加市场）** - 添加新的插件市场源
-   - 支持本地路径、GitHub 仓库、Git URL 和 HTTP URL
-   - 自动识别市场源类型
-   - 设置市场显示名称
+### 创建你的第一个插件
 
-6. **Errors（错误）** - 查看插件加载和操作过程中发生的错误
-   - 详细的错误信息和错误类型
-   - 错误发生时间和相关上下文
-   - 帮助诊断和解决问题
+#### 第 1 步：创建插件目录
 
-#### 交互式命令示例
+每个插件都有自己的目录，包含清单文件和你的技能、代理或钩子。现在创建一个：
 
 ```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>          # 移除市场
+mkdir my-first-plugin
 ```
 
-### 方式三：命令行子命令
+#### 第 2 步：创建插件清单
 
-在终端中使用 `codebuddy plugin` 命令进行管理。
+清单文件位于 `.codebuddy-plugin/plugin.json`，定义插件的身份信息：名称、描述和版本。CodeBuddy Code 使用这些元数据在插件管理器中展示你的插件。
 
-#### 插件操作
+在插件目录内创建 `.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>               # 验证本地插件或市场
+mkdir my-first-plugin/.codebuddy-plugin
 ```
 
-#### 市场管理
+然后创建 `my-first-plugin/.codebuddy-plugin/plugin.json`，内容如下：
 
-```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>                # 别名形式
+```json
+{
+  "name": "my-first-plugin",
+  "description": "A greeting plugin to learn the basics",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name"
+  }
+}
 ```
 
-## 插件管理
+| 字段 | 用途 |
+|------|------|
+| `name` | 唯一标识符和技能命名空间。技能以此为前缀（如 `/my-first-plugin:hello`） |
+| `description` | 在插件管理器中浏览或安装插件时显示 |
+| `version` | 使用[语义化版本](plugins-reference.md#版本管理)跟踪发布 |
+| `author` | 可选。用于归属标注 |
 
-### 添加插件市场
+更多字段如 `homepage`、`repository` 和 `license`，参见[完整清单 Schema](plugins-reference.md)。
 
-#### 使用交互式界面
+#### 第 3 步：添加技能
 
-1. 输入 `/plugin`
-2. 选择 "3. Add marketplace"
-3. 输入市场源地址
-4. 等待自动识别市场类型和加载插件清单
+技能放在 `skills/` 目录中。每个技能是一个包含 `SKILL.md` 文件的文件夹。文件夹名称成为技能名称，并以插件命名空间为前缀（在名为 `my-first-plugin` 的插件中，`hello/` 创建 `/my-first-plugin:hello`）。
 
-#### 使用子命令
+在插件目录中创建技能目录：
 
 ```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
+mkdir -p my-first-plugin/skills/hello
 ```
 
-**参数说明**:
-- `<source>`：市场源地址（本地路径、GitHub URL 或 HTTP(S) URL）
-- `-n, --name <name>`：可选，为市场指定显示名称
-
-### 安装插件
+然后创建 `my-first-plugin/skills/hello/SKILL.md`，内容如下：
 
-#### 使用交互式界面
-
-1. 输入 `/plugin`
-2. 选择 "1. Browse and install plugins"
-3. 选择插件市场
-4. 浏览可用插件并选择安装
-
-#### 使用子命令
-
-```bash
-# 从默认市场安装
-codebuddy plugin install my-plugin
-
-# 从指定市场安装
-codebuddy plugin install my-plugin@marketplace-name
+```markdown
 
-# 使用别名
-codebuddy plugin i my-plugin
+Greet the user warmly and ask how you can help them today.
 ```
 
-### 启用和禁用插件
+#### 第 4 步：测试你的插件
 
-#### 使用交互式界面
-
-1. 输入 `/plugin`
-2. 选择 "2. Manage plugins"
-3. 选择要启用或禁用的插件
-
-#### 使用子命令
+使用 `--plugin-dir` 参数运行 CodeBuddy Code 以加载你的插件：
 
 ```bash
-# 启用插件
-codebuddy plugin enable my-plugin
-
-# 禁用插件
-codebuddy plugin disable my-plugin
+codebuddy --plugin-dir ./my-first-plugin
 ```
 
-**注意**：启用/禁用插件后需要重启 CodeBuddy 才能生效。
-
-### 卸载插件
+启动后，尝试你的新技能：
 
-#### 使用交互式界面
+```
+/my-first-plugin:hello
+```
 
-1. 输入 `/plugin`
-2. 选择 "2. Manage plugins"
-3. 选择要卸载的插件，确认卸载
+你会看到 CodeBuddy 回复一个问候语。运行 `/help` 可以看到你的技能列在插件命名空间下。
 
-#### 使用子命令
+> **为什么要命名空间？** 插件技能始终带有命名空间（如 `/my-first-plugin:hello`），以防止多个插件中同名技能产生冲突。要更改命名空间前缀，请更新 `plugin.json` 中的 `name` 字段。
 
-```bash
-# 卸载插件
-codebuddy plugin uninstall my-plugin
+#### 第 5 步：添加技能参数
 
-# 使用别名
-codebuddy plugin remove my-plugin
-```
+通过接受用户输入使技能更加动态。`$ARGUMENTS` 占位符捕获用户在技能名称后提供的任何文本。
 
-### 管理插件市场
+更新你的 `SKILL.md` 文件：
 
-#### 列出市场
+```markdown
+---
+description: Greet the user with a personalized message
+---
 
-使用交互式界面：
-1. 输入 `/plugin`
-2. 选择 "4. Manage marketplaces"
+# Hello Skill
 
-使用子命令：
-```bash
-codebuddy plugin marketplace list
+Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
 ```
 
-#### 更新市场
-
-使用交互式界面：
-1. 输入 `/plugin`
-2. 选择 "4. Manage marketplaces"
-3. 选择要更新的市场
+运行 `/reload-plugins` 以获取更改，然后用你的名字尝试技能：
 
-使用子命令：
-```bash
-codebuddy plugin marketplace update my-marketplace
+```
+/my-first-plugin:hello Alex
 ```
 
-#### 移除市场
+CodeBuddy 会按名字问候你。更多关于向技能传递参数的信息，参见 [Skills 文档](skills.md)。
 
-使用交互式界面：
-1. 输入 `/plugin`
-2. 选择 "4. Manage marketplaces"
-3. 选择要移除的市场，确认移除
+---
 
-使用子命令：
-```bash
-codebuddy plugin marketplace remove my-marketplace
-codebuddy plugin marketplace rm my-marketplace
-```
+你已成功创建并测试了一个包含以下关键组件的插件：
 
-### 验证插件或市场清单
+- **插件清单**（`.codebuddy-plugin/plugin.json`）：描述插件的元数据
+- **技能目录**（`skills/`）：包含你的自定义技能
+- **技能参数**（`$ARGUMENTS`）：捕获用户输入实现动态行为
 
-```bash
-# 验证插件清单格式
-codebuddy plugin validate /path/to/plugin
+> `--plugin-dir` 参数适用于开发和测试。当你准备与他人共享插件时，参见[插件市场](plugin-marketplaces.md)。
 
-# 验证市场清单格式
-codebuddy plugin validate /path/to/marketplace
+## 插件结构概述
 
-# 验证来自 GitHub 的插件清单
-codebuddy plugin validate https://github.com/username/plugin-repo
-```
+你已经创建了一个包含技能的插件，但插件还可以包含更多内容：自定义代理、钩子、MCP 服务器和 LSP 服务器。
 
-验证命令会检查 `plugin.json` 或 `marketplace.json` 的格式和完整性。
+> **常见错误**：不要将 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.codebuddy-plugin/` 目录内。只有 `plugin.json` 放在 `.codebuddy-plugin/` 内。所有其他目录必须在插件根目录层级。
 
-## 插件结构
+| 目录 | 位置 | 用途 |
+|------|------|------|
+| `.codebuddy-plugin/` | 插件根目录 | 包含 `plugin.json` 清单 |
+| `commands/` | 插件根目录 | Markdown 格式的斜杠命令 |
+| `agents/` | 插件根目录 | 自定义代理定义 |
+| `skills/` | 插件根目录 | 包含 `SKILL.md` 文件的代理技能 |
+| `hooks/` | 插件根目录 | `hooks.json` 事件处理器 |
+| `.mcp.json` | 插件根目录 | MCP 服务器配置 |
+| `.lsp.json` | 插件根目录 | LSP 服务器配置（代码智能） |
+| `bin/` | 插件根目录 | 插件启用时添加到 Bash 工具 `PATH` 的可执行文件 |
+| `settings.json` | 插件根目录 | 插件启用时应用的默认[设置](settings.md) |
 
-### 标准插件目录结构
+**示例完整结构**：
 
 ```
 my-plugin/
-├── .codebuddy-plugin/     # 元数据目录（必需）
-│   └── plugin.json        # 插件清单文件
-├── commands/              # 命令目录（可选）
+├── .codebuddy-plugin/        # 元数据目录（必需）
+│   └── plugin.json           # 插件清单文件
+├── commands/                  # 命令目录（可选）
 │   └── example.md
-├── agents/                # 代理目录（可选）
+├── agents/                    # 代理目录（可选）
 │   └── example.md
-├── skills/                # 技能目录（可选）
-│   └── example/
+├── skills/                    # 技能目录（可选）
+│   └── code-review/
 │       └── SKILL.md
-├── hooks/                 # Hooks 目录（可选）
+├── hooks/                     # Hooks 目录（可选）
 │   └── hooks.json
-├── .mcp.json              # MCP 配置文件（可选）
-└── .lsp.json              # LSP 配置文件（可选）
+├── bin/                       # 可执行文件目录（可选）
+│   └── my-tool
+├── .mcp.json                  # MCP 配置文件（可选）
+├── .lsp.json                  # LSP 配置文件（可选）
+└── settings.json              # 默认设置文件（可选）
 ```
 
-### 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（命令）
+插件可以包含[代理技能](skills.md)来扩展 CodeBuddy 的能力。技能是模型调用的：CodeBuddy 会根据任务上下文自动使用它们。
 
-插件可以提供自定义斜杠命令，用户可以手动触发。命令定义为 Markdown 文件。
+在插件根目录添加 `skills/` 目录，其中包含带有 `SKILL.md` 文件的技能文件夹：
 
-**示例**: `commands/example.md`
+```
+my-plugin/
+├── .codebuddy-plugin/
+│   └── plugin.json
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
 
-```markdown
+每个 `SKILL.md` 需要包含 `name` 和 `description` 字段的 frontmatter，后跟指令：
 
-这是一个示例命令。当用户输入 /my-plugin:example 时会执行此命令。
+```markdown
+---
+name: code-review
+description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
+---
 
-参数： $1
+When reviewing code, check for:
+1. Code organization and structure
+2. Error handling
+3. Security concerns
+4. Test coverage
 ```
 
-命令会以 `/plugin-name:command-name` 的格式注册。
-
-详细说明请参考： [Slash Commands 文档](slash-commands.md)
+安装插件后，运行 `/reload-plugins` 加载技能。完整的技能编写指南，包括渐进式披露和工具限制，参见[代理技能](skills.md)。
 
-### Skills（技能）
+### 添加命令
 
-技能是 AI 可以自动识别和调用的专业能力模板。
+插件可以提供自定义斜杠命令，用户可以手动触发。命令定义为 Markdown 文件。
 
-**示例**: `skills/SKILL.md`
+**示例**：`commands/example.md`
 
 ```markdown
 ---
-description: "技能描述"
+description: "示例命令描述"
+argument-hint: "[参数]"
 ---
 
-技能的详细说明和使用场景...
+这是一个示例命令。当用户输入 /my-plugin:example 时会执行此命令。
+
+参数：$ARGUMENTS
 ```
 
-详细说明请参考： [Skills 文档](skills.md)
+命令会以 `/plugin-name:command-name` 的格式注册。
 
-### Hooks（钩子）
+详细说明请参考 [Slash Commands 文档](slash-commands.md)。
 
-Hooks 允许在特定事件发生时自动执行操作。
+### 添加 Hooks
 
-**示例**: `hooks/hooks.json`
+Hooks 允许在特定事件发生时自动执行操作。命令通过标准输入接收 hook 输入的 JSON 数据，可以使用 `jq` 提取字段。
+
+**示例**：`hooks/hooks.json`
 
 ```json
 {
   "hooks": {
-    "user-prompt-submit-hook": [
+    "PostToolUse": [
       {
+        "matcher": "Write|Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'User submitted: $INPUT'",
-            "timeout": 5000
+            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
           }
         ]
       }
@@ -430,21 +272,13 @@ Hooks 允许在特定事件发生时自动执行操作。
 }
 ```
 
-详细说明请参考： [Hooks 文档](hooks.md)
-
-### LSP（Language Server Protocol）
-
-LSP 插件为 AI 提供实时代码智能功能，使其能够理解代码结构、类型定义、函数签名等信息。
+详细说明请参考 [Hooks 文档](hooks.md)。
 
-#### 使用建议
+### 添加 LSP 服务器
 
-对于常见语言（如 TypeScript、Python、Rust 等），建议直接从官方插件市场安装预构建的 LSP 插件。仅在需要支持尚未覆盖的语言时，才需要创建自定义 LSP 插件。
+> 对于常见语言如 TypeScript、Python 和 Rust，建议直接从官方插件市场安装预构建的 LSP 插件。仅当需要支持尚未覆盖的语言时才创建自定义 LSP 插件。
 
-#### 配置 LSP 服务器
-
-通过在插件根目录添加 `.lsp.json` 文件来配置 LSP 服务器：
-
-**示例**: `.lsp.json`
+LSP（Language Server Protocol）插件为 CodeBuddy 提供实时代码智能。如果需要支持没有官方 LSP 插件的语言，可以在插件中添加 `.lsp.json` 文件：
 
 ```json
 {
@@ -458,12 +292,7 @@ LSP 插件为 AI 提供实时代码智能功能，使其能够理解代码结构
 }
 ```
 
-#### 配置字段说明
-
-- **语言标识符** (如 `"go"`)：定义 LSP 服务器支持的语言
-  - `command`：LSP 服务器可执行文件的命令名称
-  - `args`：传递给命令的参数数组
-  - `extensionToLanguage`：文件扩展名到语言标识符的映射
+安装插件的用户必须在其机器上预装语言服务器二进制文件。
 
 #### 多语言配置示例
 
@@ -488,105 +317,190 @@ LSP 插件为 AI 提供实时代码智能功能，使其能够理解代码结构
 
 #### 安装要求
 
-用户在安装包含 LSP 配置的插件时，必须在其系统上预先安装相应的语言服务器二进制文件。例如：
+用户在安装包含 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`)
+- **Go**: `go install golang.org/x/tools/gopls@latest`
+- **Python**: `pip install python-lsp-server`
+- **Rust**: `rustup component add rust-analyzer`
 
-#### 工作原理
+### 携带默认设置
 
-1. CodeBuddy 启动时读取 `.lsp.json` 配置
-2. 根据文件扩展名自动启动对应的 LSP 服务器
-3. AI 通过 LSP 协议获取代码智能信息
-4. 提供更准确的代码建议和修改
+插件可以在根目录包含 `settings.json` 文件，在插件启用时应用默认配置。目前仅支持 `agent` 键。
 
-#### 最佳实践
+设置 `agent` 会将插件的一个[自定义代理](sub-agents.md)激活为主线程，应用其系统提示词、工具限制和模型。这让插件在启用时可以改变 CodeBuddy Code 的默认行为。
 
-1. **提供安装说明**：在插件的 README 中明确说明需要安装的语言服务器
-2. **版本兼容性**：说明支持的语言服务器版本范围
-3. **使用官方插件**：优先使用官方维护的 LSP 插件，避免重复工作
-4. **测试充分**：确保 LSP 配置在不同操作系统上都能正常工作
+```json
+{
+  "agent": "security-reviewer"
+}
+```
 
-## 插件市场类型
+此示例激活插件 `agents/` 目录中定义的 `security-reviewer` 代理。`settings.json` 中的设置优先于 `plugin.json` 中声明的 `settings`。未知键会被静默忽略。
 
-### GitHub 市场
+### 本地测试插件
 
-从 GitHub 仓库发布和获取插件。
+使用 `--plugin-dir` 参数在开发过程中测试插件。这会直接加载你的插件，无需安装。
 
-**仓库结构**:
+```bash
+codebuddy --plugin-dir ./my-plugin
+```
+
+当 `--plugin-dir` 插件与已安装的市场插件同名时，本地副本在该会话中优先使用。这让你可以测试已安装插件的改动而无需卸载它。通过托管设置强制启用的市场插件是唯一的例外，不能被覆盖。
+
+在修改插件时，运行 `/reload-plugins` 无需重启即可获取更新。这会重新加载插件、技能、代理、钩子、插件 MCP 服务器和插件 LSP 服务器。测试你的插件组件：
+
+- 使用 `/plugin-name:skill-name` 尝试技能
+- 在 `/agents` 中检查代理是否出现
+- 验证钩子是否按预期工作
+
+> 可以通过多次指定参数同时加载多个插件：
+>
+> ```bash
+> codebuddy --plugin-dir ./plugin-one --plugin-dir ./plugin-two
+> ```
+
+### 调试插件问题
 
+如果插件没有按预期工作：
+
+1. **检查结构**：确保目录在插件根目录，而不是在 `.codebuddy-plugin/` 内
+2. **单独测试组件**：分别检查每个命令、代理和钩子
+3. **使用调试模式**：用 `--debug` 参数启动 CodeBuddy 查看详细日志
+
+## 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"
+}
 ```
-plugin-repo/
-├── .codebuddy-plugin/
-│   └── marketplace.json       # 市场清单
-└── plugins/
-    ├── plugin1/
-    │   ├── .codebuddy-plugin/
-    │   │   └── plugin.json
-    │   └── ...
-    └── plugin2/
-        ├── .codebuddy-plugin/
-        │   └── plugin.json
-        └── ...
+
+完整的清单 Schema 说明参见[插件参考文档](plugins-reference.md)。
+
+## 共享你的插件
+
+当插件准备好共享时：
+
+1. **添加文档**：包含一个 `README.md`，说明安装和使用方式
+2. **版本管理**：在 `plugin.json` 中使用[语义化版本](plugins-reference.md#版本管理)
+3. **创建或使用市场**：通过[插件市场](plugin-marketplaces.md)分发
+4. **与他人测试**：在更广泛分发之前，让团队成员测试插件
+
+插件上线到市场后，其他人可以按照[插件市场](plugin-marketplaces.md)中的说明安装使用。
+
+## 将现有配置转换为插件
+
+如果你已经在 `.codebuddy/` 目录中有技能或钩子，可以将它们转换为插件以便于共享和分发。
+
+### 迁移步骤
+
+#### 第 1 步：创建插件结构
+
+创建新的插件目录：
+
+```bash
+mkdir -p my-plugin/.codebuddy-plugin
 ```
 
-**marketplace.json** 格式：
+创建清单文件 `my-plugin/.codebuddy-plugin/plugin.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"
-    }
-  ]
+  "name": "my-plugin",
+  "description": "Migrated from standalone configuration",
+  "version": "1.0.0"
 }
 ```
 
-### HTTP 市场
+#### 第 2 步：复制现有文件
 
-通过 HTTP(S) 服务器提供插件。
+将现有配置复制到插件目录：
 
-**服务器要求**:
+```bash
+# 复制命令
+cp -r .codebuddy/commands my-plugin/
 
-- 提供 `/marketplace.json` - 市场清单
-- 提供 `/plugins/<plugin-name>/plugin.json` - 插件清单
-- 提供插件文件下载
+# 复制代理（如有）
+cp -r .codebuddy/agents my-plugin/
 
-### 本地目录市场
+# 复制技能（如有）
+cp -r .codebuddy/skills my-plugin/
+```
 
-从本地文件系统加载插件，适用于开发和测试。
+#### 第 3 步：迁移 Hooks
 
-**目录结构**:
+如果你的设置中有 hooks，创建 hooks 目录：
 
+```bash
+mkdir my-plugin/hooks
 ```
-local-plugins/
-├── .codebuddy-plugin/
-│   └── marketplace.json
-└── plugins/
-    └── my-plugin/
-        ├── .codebuddy-plugin/
-        │   └── plugin.json
-        └── ...
+
+创建 `my-plugin/hooks/hooks.json`，将 hooks 配置放入其中。从 `.codebuddy/settings.json` 或 `settings.local.json` 中复制 `hooks` 对象，格式是一样的。命令通过标准输入接收 hook 输入的 JSON 数据，可以使用 `jq` 提取字段：
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
+          }
+        ]
+      }
+    ]
+  }
+}
 ```
 
+#### 第 4 步：测试迁移后的插件
+
+加载插件验证一切正常：
+
+```bash
+codebuddy --plugin-dir ./my-plugin
+```
+
+测试每个组件：运行你的命令、在 `/agents` 中检查代理、验证钩子正确触发。
+
+### 迁移前后对比
+
+| 独立配置（`.codebuddy/`） | 插件 |
+|---------------------------|------|
+| 仅在一个项目中可用 | 可通过市场共享 |
+| 文件在 `.codebuddy/commands/` | 文件在 `plugin-name/commands/` |
+| Hooks 在 `settings.json` 中 | Hooks 在 `hooks/hooks.json` 中 |
+| 需要手动复制来共享 | 使用 `/plugin install` 安装 |
+
+> 迁移后，可以删除 `.codebuddy/` 中的原始文件以避免重复。加载时插件版本会优先使用。
+
 ## 最佳实践
 
 ### 插件开发建议
 
-1. **遵循命名规范**：使用清晰、描述性的插件名称
+1. **遵循命名规范**：使用清晰、描述性的插件名称（kebab-case，无空格）
 2. **提供完整元数据**：在 `plugin.json` 中提供详细的描述和作者信息
 3. **版本管理**：使用语义化版本号（Semantic Versioning）
 4. **文档完善**：为每个命令和技能提供清晰的描述
-5. **测试充分**：在本地市场中测试插件后再发布
+5. **测试充分**：使用 `--plugin-dir` 在本地测试插件后再发布
 
 ### 安全注意事项
 
@@ -594,49 +508,18 @@ local-plugins/
 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` 进入 "Installed" 标签页查看
+- 检查 `plugin.json` 格式是否正确
+- 运行 `/reload-plugins` 重新加载插件
+- 使用 `--debug` 模式查看加载日志
 
 ### 命令不可用
 
@@ -644,46 +527,38 @@ local-plugins/
 
 **解决方案**：
 
-* 确认命令路径在 `plugin.json` 中正确配置
-* 检查命令文件是否存在
-* 验证命令文件格式符合 Markdown 规范
-
-### 市场连接失败
-
-**问题**：无法连接到市场或获取插件列表
-
-**解决方案**：
-
-* **GitHub 市场**：检查网络连接和仓库访问权限
-* **HTTP 市场**：确认服务器可访问
-* **本地市场**：验证目录路径和权限
+- 确认命令文件放在插件根目录的 `commands/` 中，而不是 `.codebuddy-plugin/` 内
+- 检查命令文件是否存在且格式正确
+- 运行 `/reload-plugins` 刷新
 
 ### 验证和测试
 
-在共享前测试您的市场和插件：
+在共享前测试你的插件：
 
 ```bash
-# 验证市场 JSON 语法
-codebuddy plugin validate .
-
-# 验证特定插件
+# 验证插件格式
 codebuddy plugin validate /path/to/plugin
 
-# 添加本地市场用于测试
-codebuddy plugin marketplace add ./path/to/marketplace
+# 使用 --plugin-dir 本地测试
+codebuddy --plugin-dir ./my-plugin
 
-# 测试插件安装
-codebuddy plugin install test-plugin@marketplace-name
+# 测试插件的技能
+/my-plugin:skill-name
 ```
 
-## 相关文档
+## 后续步骤
 
-- **[插件参考文档](plugins-reference.md)** - 插件开发完整技术规范
-- **[Slash Commands](slash-commands.md)** - 了解命令系统
-- **[Skills](skills.md)** - 学习技能系统
-- **[Hooks](hooks.md)** - 掌握 Hooks 机制
+### 对于插件用户
 
----
+- [插件市场](plugin-marketplaces.md) - 浏览市场并安装插件
+- [设置](settings.md) - 了解插件配置选项
 
-*通过插件系统，让 CodeBuddy 更强大 🚀*
+### 对于插件开发者
 
+- [插件市场](plugin-marketplaces.md) - 打包和共享你的插件
+- [插件参考文档](plugins-reference.md) - 完整技术规范
+- 深入了解具体的插件组件：
+  - [Skills](skills.md) - 技能开发详情
+  - [子代理](sub-agents.md) - 代理配置和能力
+  - [Hooks](hooks.md) - 事件处理和自动化
+  - [MCP](mcp.md) - 外部工具集成