@tencent-ai/codebuddy-code 2.67.0 → 2.68.0

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

@@ -0,0 +1,774 @@
+# CodeBuddy 插件参考文档
+
+## 概述
+
+CodeBuddy 插件系统允许通过标准化的插件机制扩展 AI 助手的功能。插件可以提供自定义命令、代理、技能、钩子和 MCP 服务器等组件。
+
+description：命令描述
+allowed-tools: Read,Write,Bash
+argument-hint：参数提示
+model：使用的模型ID或名称
+---
+
+命令的提示词内容
+```
+
+**命令文件组织**:
+- 支持子目录嵌套组织
+- 子目录路径会转换为命令名的一部分，使用冒号分隔
+- 例如： `commands/deploy/production.md` → 命令名为 `deploy:production`
+
+### 2. Agents （代理）
+
+**位置**：插件根目录的 `agents/` 目录
+**格式**：带有 frontmatter 的 Markdown 文件
+
+**Frontmatter 配置**:
+```markdown
+---
+name：代理名称（可选，默认使用文件名）
+description：代理描述
+model：使用的模型ID或名称
+tools: Read,Write,Bash（可用工具列表，逗号分隔）
+color: #FF5733（代理显示颜色，可选）
+---
+
+代理的指令内容
+```
+
+**特性**:
+- 代理可以作为工具被主代理调用
+- 支持自定义工具列表
+- 自动生成源标签标识来源
+
+### 3. Skills （技能）
+
+**位置**：插件根目录的 `skills/` 目录
+**格式**：每个技能一个子目录，包含 `SKILL.md` 文件
+
+**目录结构**:
+```
+skills/
+├── pdf-processor/
+│   ├── SKILL.md
+│   ├── reference.md （可选）
+│   └── scripts/ （可选）
+└── code-reviewer/
+    └── SKILL.md
+```
+
+**SKILL.md Frontmatter 配置**:
+```markdown
+---
+name：技能名称（可选，默认使用目录名）
+description：技能描述
+allowed-tools: Read,Write,Bash（允许使用的工具列表）
+---
+
+技能的指令内容
+```
+
+**特性**:
+- 技能可以包含辅助文件和脚本
+- 技能的 `baseDirectory` 指向技能目录，可访问同目录下的资源文件
+
+### 4. Hooks （钩子）
+
+**位置**：插件根目录的 `hooks/hooks.json`,或在 `plugin.json` 中通过 PluginInfo 扩展字段配置
+**格式**: JSON 配置，包含事件匹配器和操作
+
+**配置示例**:
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/format-code.sh",
+          "timeout": 30000
+        }
+      ]
+    }
+  ]
+}
+```
+
+**可用事件**:
+- `PreToolUse`：在工具使用之前触发
+- `PostToolUse`：在工具使用之后触发
+- `UserPromptSubmit`：用户提交提示时触发
+- `Notification`：发送通知时触发
+- `Stop`：尝试停止时触发
+- `SubagentStop`：子代理尝试停止时触发
+- `SessionStart`：会话开始时触发
+- `SessionEnd`：会话结束时触发
+- `PreCompact`：对话历史压缩之前触发
+
+**钩子类型**:
+- `command`：执行 shell 命令或脚本
+
+**Matcher 规则**:
+- 支持正则表达式匹配工具名称
+- 例如： `"Write|Edit"` 匹配 Write 或 Edit 工具
+
+### 5. MCP Servers (MCP 服务器）
+
+**位置**:
+- 插件根目录的 `.mcp.json` 配置文件
+- 或在 `plugin.json` 中通过 PluginInfo 扩展字段配置
+
+**配置示例** (.mcp.json):
+```json
+{
+  "mcpServers": {
+    "plugin-database": {
+      "command": "${CODEBUDDY_PLUGIN_ROOT}/servers/db-server",
+      "args": ["--config", "${CODEBUDDY_PLUGIN_ROOT}/config.json"],
+      "env": {
+        "DB_PATH": "${CODEBUDDY_PLUGIN_ROOT}/data"
+      }
+    },
+    "plugin-api-client": {
+      "command": "npx",
+      "args": ["@company/mcp-server", "--plugin-mode"],
+      "cwd": "${CODEBUDDY_PLUGIN_ROOT}"
+    }
+  }
+}
+```
+
+**集成行为**:
+- 插件启用时自动启动 MCP 服务器
+- 服务器作为标准 MCP 工具出现在工具包中
+- 服务器功能与现有工具无缝集成
+
+### 6. LSP Servers（LSP 服务器）
+
+> **提示**: 需要使用 LSP 插件? 可从官方市场安装——在 `/plugin` Discover 标签中搜索 "lsp"。本节介绍如何为官方市场未涵盖的语言创建 LSP 插件。
+
+插件可以提供 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) 服务器，为 AI 助手在代码库上工作时提供实时代码智能支持。
+
+LSP 集成提供:
+
+* **即时诊断**: AI 助手在每次编辑后立即看到错误和警告
+* **代码导航**: 跳转到定义、查找引用和悬停信息
+* **语言感知**: 代码符号的类型信息和文档
+
+**位置**: 插件根目录的 `.lsp.json` 文件，或在 `plugin.json` 中内联配置
+
+**格式**: JSON 配置，将语言服务器名称映射到其配置
+
+**`.lsp.json` 文件格式**:
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+**在 `plugin.json` 中内联配置**:
+
+```json
+{
+  "name": "my-plugin",
+  "lspServers": {
+    "go": {
+      "command": "gopls",
+      "args": ["serve"],
+      "extensionToLanguage": {
+        ".go": "go"
+      }
+    }
+  }
+}
+```
+
+**必需字段**:
+
+| 字段 | 描述 |
+| :--- | :--- |
+| `command` | 要执行的 LSP 二进制文件（必须在 PATH 中） |
+| `extensionToLanguage` | 将文件扩展名映射到语言标识符 |
+
+**可选字段**:
+
+| 字段 | 描述 |
+| :--- | :--- |
+| `args` | LSP 服务器的命令行参数 |
+| `transport` | 通信传输方式: `stdio`（默认）或 `socket` |
+| `env` | 启动服务器时设置的环境变量 |
+| `initializationOptions` | 在初始化期间传递给服务器的选项 |
+| `settings` | 通过 `workspace/didChangeConfiguration` 传递的设置 |
+| `workspaceFolder` | 服务器的工作区文件夹路径 |
+| `startupTimeout` | 等待服务器启动的最大时间（毫秒） |
+| `shutdownTimeout` | 等待优雅关闭的最大时间（毫秒） |
+| `restartOnCrash` | 服务器崩溃时是否自动重启 |
+| `maxRestarts` | 放弃前的最大重启尝试次数 |
+| `loggingConfig` | 调试日志配置（见下文） |
+
+> **警告**: **您必须单独安装语言服务器二进制文件。** LSP 插件配置 CodeBuddy 如何连接到语言服务器，但不包含服务器本身。如果在 `/plugin` Errors 标签中看到 `Executable not found in $PATH` 错误，请为您的语言安装所需的二进制文件。
+
+**可用的 LSP 插件**:
+
+| 插件 | 语言服务器 | 安装命令 |
+| :--- | :--- | :--- |
+| `pyright-lsp` | Pyright (Python) | `pip install pyright` 或 `npm install -g pyright` |
+| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
+| `rust-lsp` | rust-analyzer | [参见 rust-analyzer 安装](https://rust-analyzer.github.io/manual.html#installation) |
+
+先安装语言服务器，然后从市场安装插件。
+
+---
+
+## 二、插件清单架构 （plugin.json)
+
+### 完整架构示例
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.2.0",
+  "description": "插件简短描述",
+  "author": {
+    "name": "作者名称",
+    "email": "[email protected]",
+    "url": "https://github.com/author"
+  },
+  "homepage": "https://docs.example.com/plugin",
+  "repository": "https://github.com/author/plugin",
+  "license": "MIT",
+  "keywords": ["keyword1", "keyword2"],
+  "category": "开发工具",
+  "features": ["特性1", "特性2"],
+  "requirements": {
+    "node": ">=16.0.0"
+  },
+  "commands": ["./custom/commands/special.md"],
+  "agents": "./custom/agents/",
+  "hooks": "./config/hooks.json",
+  "mcpServers": [
+    {
+      "name": "custom-server",
+      "command": "node",
+      "args": ["./servers/custom.js"],
+      "env": {
+        "SERVER_PORT": "3000"
+      }
+    }
+  ],
+  "lspServers": "./.lsp.json"
+}
+```
+
+### 必需字段
+
+| 字段 | 类型 | 描述 | 示例 |
+|------|------|------|------|
+| name | string | 唯一标识符（kebab-case，无空格） | "deployment-tools" |
+| description | string | 插件用途简述 | "部署自动化工具" |
+
+### 元数据字段
+
+| 字段 | 类型 | 描述 | 示例 |
+|------|------|------|------|
+| version | string | 语义化版本 | "2.1.0" |
+| author | object | 作者信息 | `{"name": "开发团队", "email": "[email protected]"}` |
+| homepage | string | 文档 URL | "https://docs.example.com" |
+| repository | string | 源代码 URL | "https://github.com/user/plugin" |
+| license | string | 许可证标识符 | "MIT", "Apache-2.0" |
+| keywords | array | 发现标签 | `["deployment", "ci-cd"]` |
+| category | string | 插件分类 | "开发工具" |
+| features | array | 功能列表 | `["自动部署", "日志分析"]` |
+
+### 组件路径字段（PluginManifest）
+
+| 字段 | 类型 | 描述 | 示例 |
+|------|------|------|------|
+| commands | string / string[] | 额外的命令文件路径数组 | `["./custom/cmd.md"]` |
+| agents | string / string[] | 额外 Agent 文件目录路径 | "./custom/agents/" |
+| hooks | string / object | 额外 Hook 文件或配置 | "./custom/hooks.json" |
+| mcpServers | string / `Record<string,MCPServerConfig>` | MCP服务器配置文件路径或配置对象 | 见下方 MCPServerConfig |
+| lspServers | string / object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 配置，用于代码智能（跳转定义、查找引用等） | `"./.lsp.json"` |
+
+### MCPServerConfig 结构
+
+```typescript
+{
+  "name": "服务器名称",
+  "command": "执行命令",
+  "args": ["命令参数数组"],
+  "env": {
+    "环境变量名": "值"
+  }
+}
+```
+
+### 运行时扩展字段（PluginInfo）
+
+插件在运行时会扩展以下字段，支持更灵活的配置方式：
+
+| 字段 | 类型 | 描述 | 示例 |
+|------|------|------|------|
+| agents | string[] | Agent 文件或目录路径 | `["./custom/agents/"]` |
+| commands | string[] | Command 文件或目录路径 | `["./custom/commands/"]` |
+| skills | string[] | Skill 文件或目录路径 | `["./custom/skills/"]` |
+| hooks | `Record<string, any>` \| string | Hook 配置对象或文件路径 | "./hooks/custom.json" |
+| mcpServers | `Record<string, McpConfig>` \| string | MCP 配置对象或文件路径 | "./mcp-config.json" |
+| lspServers | `Record<string, LspConfig>` \| string | LSP 配置对象或文件路径 | "./.lsp.json" |
+
+**说明**:
+- 这些扩展字段用于 marketplace.json 中配置插件的加载方式
+- 支持直接配置对象或文件路径字符串
+- 加载器会智能合并配置路径和默认目录扫描的结果
+
+### 路径行为规则
+
+**重要**：自定义路径是对默认目录的**补充**，而不是替换。
+
+- 如果 `commands/` 目录存在，它会与自定义命令路径一起加载
+- 所有路径必须相对于插件根目录，并以 `./` 开头
+- 可以将多个路径指定为数组以提高灵活性
+- 路径可以指向单个文件或目录
+
+**路径解析规则**:
+- 文件路径： 必须以 `.md` 结尾（对于 commands/agents）或为 `SKILL.md`（对于 skills）
+- 目录路径： 会递归扫描目录中的所有符合条件的文件
+
+### 环境变量
+
+**`${CODEBUDDY_PLUGIN_ROOT}`**：包含插件目录的绝对路径。在钩子、MCP 服务器和脚本中使用此变量，以确保无论安装位置如何都能使用正确的路径。
+
+**兼容性**：同时支持 `${CLAUDE_PLUGIN_ROOT}` 变量名以兼容 Claude Code 插件。
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/process.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 三、插件目录结构
+
+### 标准插件布局
+
+```
+enterprise-plugin/
+├── .codebuddy-plugin/       # 元数据目录
+│   └── plugin.json          # 必需：插件清单
+├── commands/                # 默认命令位置
+│   ├── status.md
+│   └── logs.md
+├── agents/                  # 默认代理位置
+│   ├── security-reviewer.md
+│   ├── performance-tester.md
+│   └── compliance-checker.md
+├── skills/                  # 代理技能
+│   ├── code-reviewer/
+│   │   └── SKILL.md
+│   └── pdf-processor/
+│       ├── SKILL.md
+│       └── scripts/
+├── hooks/                   # 钩子配置
+│   └── hooks.json           # 钩子配置文件
+├── .mcp.json               # MCP 服务器定义
+├── .lsp.json               # LSP 服务器配置
+├── scripts/                # 钩子和实用脚本
+│   ├── security-scan.sh
+│   ├── format-code.py
+│   └── deploy.js
+├── LICENSE                 # 许可证文件
+└── README.md               # 插件说明
+```
+
+**重要**:
+- `.codebuddy-plugin/` 或 `.claude-plugin/` 目录包含 `plugin.json` 文件
+- 所有其他目录（`commands/`、`agents/`、`skills/`、`hooks/`）必须位于插件根目录
+- 系统优先识别 `.codebuddy-plugin/`,同时兼容 `.claude-plugin/`
+
+### 文件位置参考
+
+| 组件 | 默认位置 | 用途 |
+|------|----------|------|
+| Manifest | .codebuddy-plugin/plugin.json | 必需的元数据文件 |
+| Commands | commands/ | 斜杠命令 markdown 文件 |
+| Agents | agents/ | 子代理 markdown 文件 |
+| Skills | skills/ | 带有 SKILL.md 文件的代理技能 |
+| Hooks | hooks/hooks.json | 钩子配置 |
+| MCP servers | .mcp.json | MCP 服务器定义 |
+| LSP servers | .lsp.json | 语言服务器配置 |
+
+---
+
+## 四、市场清单架构 （marketplace.json)
+
+### 完整架构示例
+
+```json
+{
+  "name": "企业插件市场",
+  "description": "企业内部插件集合",
+  "version": "1.0.0",
+  "owner": {
+    "name": "企业开发团队",
+    "email": "[email protected]"
+  },
+  "plugins": [
+    {
+      "name": "deployment-tool",
+      "description": "自动化部署工具",
+      "version": "1.0.0",
+      "source": "plugins/deployment-tool"
+    },
+    {
+      "name": "code-review-bot",
+      "description": "代码审查机器人",
+      "version": "2.1.0",
+      "source": {
+        "source": "github",
+        "repo": "company/code-review-bot"
+      }
+    },
+    {
+      "name": "security-scanner",
+      "description": "安全扫描工具",
+      "version": "1.5.0",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/company/security-scanner.git"
+      }
+    }
+  ]
+}
+```
+
+### 必需字段
+
+| 字段 | 类型 | 描述 | 示例 |
+|------|------|------|------|
+| name | string | 市场名称 | "企业插件市场" |
+| plugins | array | 插件列表 | 见下方 |
+
+### 元数据字段
+
+| 字段 | 类型 | 描述 | 示例 |
+|------|------|------|------|
+| description | string | 市场描述 | "企业内部插件集合" |
+| version | string | 市场版本 | "1.0.0" |
+| owner | object | 所有者信息 | `{"name": "团队", "email": "..."}` |
+
+### 插件条目 （MarketplacePluginEntry)
+
+每个插件条目包含以下字段：
+
+| 字段 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| name | string | ✓ | 插件唯一标识符 |
+| description | string | ✓ | 插件描述 |
+| version | string | | 插件版本号 |
+| source | string \| PluginSource | ✓ | 插件源配置 |
+| strict | boolean | | 严格模式（兼容 superpowers-marketplace） |
+
+### PluginSource 配置
+
+插件源支持三种类型：
+
+#### 1. 本地相对路径（字符串）
+```json
+{
+  "source": "plugins/my-plugin"
+}
+```
+
+#### 2. 本地路径（对象）
+```json
+{
+  "source": {
+    "source": "local",
+    "path": "plugins/my-plugin"
+  }
+}
+```
+
+#### 3. GitHub 仓库
+```json
+{
+  "source": {
+    "source": "github",
+    "repo": "owner/repo-name"
+  }
+}
+```
+
+#### 4. Git URL
+```json
+{
+  "source": {
+    "source": "url",
+    "url": "https://github.com/owner/repo.git"
+  }
+}
+```
+
+### 市场类型
+
+CodeBuddy 支持四种市场类型：
+
+| 类型 | 说明 | source 字段 |
+|------|------|-------------|
+| Directory | 本地文件系统目录 | path：本地目录绝对路径 |
+| Github | GitHub 仓库 | repo: owner/repo 格式 |
+| Git | Git 仓库 | url: Git 仓库 URL |
+| URL | HTTP/HTTPS 远端 | url: marketplace.json 的 URL |
+
+---
+
+## 五、插件加载机制
+
+### 加载流程
+
+1. **市场安装**:
+   - 从配置的源安装市场
+   - 读取 `marketplace.json` 获取插件列表
+
+2. **插件安装**:
+   - 根据 `source` 配置选择合适的安装器（Local/Git）
+   - 将插件内容安装到目标位置
+
+3. **插件启用**:
+   - 读取插件的 `plugin.json` 清单
+   - 根据清单配置加载各类组件
+
+4. **组件加载**:
+   - 并发加载所有类型的扩展组件
+   - 合并配置路径和默认目录扫描的结果
+   - 缓存加载的组件以提高性能
+
+### 加载器智能合并
+
+每个扩展加载器都会智能合并两个来源的内容：
+
+1. **配置路径**：在 `plugin.json` 或运行时配置中指定的路径
+2. **默认扫描**：默认目录（如 `commands/`、`agents/`）中的文件
+
+**示例**:
+```json
+{
+  "commands": ["./custom/deploy.md"],
+  // 实际加载：
+  // - ./custom/deploy.md （配置路径）
+  // - commands/ 目录中的所有 .md 文件 （默认扫描）
+}
+```
+
+### 命令名称生成规则
+
+- 文件名： `command.md` → 命令名: `command`
+- 子目录： `deploy/prod.md` → 命令名: `deploy:prod`
+- 插件前缀： 自动添加插件名作为前缀，如 `plugin-name:command`
+
+### 代理和技能标签
+
+所有从插件加载的代理和技能都会自动添加以下标签：
+- 来源标签： `(plugin-name@marketplace-name)`
+- 类型标签： `plugin`
+- 自定义标签： `custom-agent` 或 `custom-command`
+
+---
+
+## 六、调试和开发工具
+
+### 查看插件加载日志
+
+使用 `--verbose` 参数查看详细的插件加载信息：
+
+```bash
+codebuddy --verbose
+```
+
+**显示内容**:
+- 正在加载哪些插件
+- 插件清单中的任何错误
+- 命令、代理和技能注册
+- MCP 服务器初始化
+- Hooks 配置加载
+
+### 常见问题排查
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+| 插件未加载 | 无效的 plugin.json | 验证 JSON 语法，检查必需字段 |
+| 命令未出现 | 错误的目录结构 | 确保 commands/ 在插件根目录 |
+| 钩子未触发 | 脚本不可执行 | 运行 `chmod +x script.sh` |
+| MCP 服务器失败 | 缺少环境变量 | 使用 `${CODEBUDDY_PLUGIN_ROOT}` |
+| 路径错误 | 使用了绝对路径 | 所有路径必须是相对路径并以 `./` 开头 |
+| 元数据目录未识别 | 使用了错误的目录名 | 使用 `.codebuddy-plugin/` 或 `.claude-plugin/` |
+| LSP `Executable not found in $PATH` | 语言服务器未安装 | 安装二进制文件（例如：`npm install -g typescript-language-server typescript`） |
+
+### 插件开发最佳实践
+
+1. **使用相对路径**：所有文件引用使用相对路径，确保跨环境兼容
+2. **环境变量**：在脚本中使用 `${CODEBUDDY_PLUGIN_ROOT}` 引用插件目录
+3. **错误处理**：为钩子脚本添加适当的错误处理和超时设置
+4. **文档完善**：在 README.md 中提供清晰的安装和使用说明
+5. **语义化版本**：遵循语义化版本规范管理插件版本
+6. **测试覆盖**：在不同环境下测试插件的安装和功能
+
+---
+
+## 七、版本管理参考
+
+### 语义化版本控制
+
+遵循语义化版本控制进行插件发布：
+
+- **主版本号 （MAJOR)**：不兼容的 API 更改
+- **次版本号 （MINOR)**：向后兼容的功能添加
+- **修订号 （PATCH)**：向后兼容的错误修复
+
+示例： `1.2.0` → `1.2.1` （修复） → `1.3.0` （新功能） → `2.0.0` （破坏性更改）
+
+### 插件更新流程
+
+1. 修改插件代码和资源
+2. 更新 `plugin.json` 中的 version 字段
+3. 在 CHANGELOG.md 中记录变更
+4. 提交到版本控制系统
+5. 用户通过 marketplace 更新插件
+
+---
+
+## 八、CLI 命令参考
+
+### 市场管理
+
+```bash
+# 添加市场
+codebuddy plugin marketplace add <source> [--name <name>]
+
+# 列出市场
+codebuddy plugin marketplace list
+
+# 更新市场
+codebuddy plugin marketplace update <name>
+
+# 删除市场
+codebuddy plugin marketplace remove <name>
+```
+
+### 插件管理
+
+```bash
+# 安装插件
+codebuddy plugin install <plugin-name> <marketplace-name>
+
+# 列出已安装插件
+codebuddy plugin list [--marketplace <name>]
+
+# 启用插件
+codebuddy plugin enable <plugin-name> <marketplace-name>
+
+# 禁用插件
+codebuddy plugin disable <plugin-name> <marketplace-name>
+
+# 卸载插件
+codebuddy plugin uninstall <plugin-name> <marketplace-name>
+
+# 更新插件
+codebuddy plugin update <plugin-name> <marketplace-name>
+```
+
+### 市场源格式
+
+支持以下格式添加市场：
+
+```bash
+# 本地目录
+codebuddy plugin marketplace add /path/to/marketplace
+
+# GitHub 简写
+codebuddy plugin marketplace add owner/repo
+
+# Git URL
+codebuddy plugin marketplace add https://github.com/owner/repo.git
+
+# HTTP URL (marketplace.json)
+codebuddy plugin marketplace add https://example.com/marketplace.json
+```
+
+---
+
+## 九、与 Claude Code 的兼容性
+
+CodeBuddy 插件系统在设计上兼容 Claude Code 插件规范，但存在以下差异：
+
+### 命名差异
+
+| 概念 | Claude Code | CodeBuddy |
+|------|-------------|-----------|
+| 元数据目录 | `.claude-plugin/` | `.codebuddy-plugin/` （优先） 或 `.claude-plugin/` （兼容） |
+| 环境变量 | `${CLAUDE_PLUGIN_ROOT}` | `${CODEBUDDY_PLUGIN_ROOT}` （优先） 或 `${CLAUDE_PLUGIN_ROOT}` （兼容） |
+
+### 扩展功能
+
+CodeBuddy 在 Claude Code 基础上提供了以下扩展：
+
+1. **运行时配置**: PluginInfo 支持运行时扩展字段配置
+2. **多元数据目录**：同时支持 `.codebuddy-plugin/` 和 `.claude-plugin/`
+3. **灵活的配置**：支持配置对象和文件路径两种配置方式
+
+### 迁移指南
+
+从 Claude Code 迁移到 CodeBuddy：
+
+1. 可选择将 `.claude-plugin/` 重命名为 `.codebuddy-plugin/`
+2. 可选择将脚本中的 `${CLAUDE_PLUGIN_ROOT}` 替换为 `${CODEBUDDY_PLUGIN_ROOT}`
+3. 如果使用了 `mcpServers` 字段,需要重命名为 `mcpServers`
+
+**注意**：保持原有命名也完全兼容，CodeBuddy 会自动识别。
+
+---
+
+## 相关资源
+
+- **插件开发教程** - 如何创建自定义插件
+- **市场创建指南** - 创建和管理插件市场
+- **Hooks 深入指南** - 事件处理和自动化
+- **MCP 集成文档** - 外部工具集成
+- **Settings 配置** - 插件配置选项
+
+---
+
+## 总结
+
+本文档提供了 CodeBuddy 插件系统的完整技术规范，涵盖：
+
+1. 六种插件组件类型（Commands、Agents、Skills、Hooks、MCP Servers、LSP Servers）
+2. 完整的 plugin.json 清单架构和字段说明
+3. marketplace.json 市场清单架构
+4. 标准目录结构和文件位置
+5. 插件加载机制和智能合并规则
+6. CLI 命令和调试工具
+7. 版本管理最佳实践
+8. 与 Claude Code 的兼容性说明
+
+开发者可以使用此参考文档创建功能完整、结构规范的 CodeBuddy 插件。