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

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

@@ -1,125 +1,109 @@
 # CodeBuddy 插件参考文档
 
-## 概述
+> 完整的 CodeBuddy 插件系统技术参考，包括组件规范、CLI 命令和开发工具。
 
-CodeBuddy 插件系统允许通过标准化的插件机制扩展 AI 助手的功能。插件可以提供自定义命令、代理、技能、钩子和 MCP 服务器等组件。
+**插件**是一个自包含的组件目录，用于扩展 CodeBuddy 的自定义功能。插件组件包括技能 (Skills)、代理 (Agents)、钩子 (Hooks)、MCP 服务器和 LSP 服务器。
 
-description：命令描述
-allowed-tools: Read,Write,Bash
-argument-hint：参数提示
-model：使用的模型ID或名称
+name: agent-name
+description: 代理的专长和调用时机
+model: sonnet
+effort: medium
+maxTurns: 20
+disallowedTools: Write, Edit
 ---
 
-命令的提示词内容
+代理的详细系统提示词，描述其角色、专长和行为。
 ```
 
-**命令文件组织**:
-- 支持子目录嵌套组织
-- 子目录路径会转换为命令名的一部分，使用冒号分隔
-- 例如： `commands/deploy/production.md` → 命令名为 `deploy:production`
+插件代理支持以下 frontmatter 字段：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background` 和 `isolation`。`isolation` 的唯一有效值为 `"worktree"`。出于安全原因，插件代理不支持 `hooks`、`mcpServers` 和 `permissionMode` 字段。
 
-### 2. Agents （代理）
+**集成方式**:
 
-**位置**：插件根目录的 `agents/` 目录
-**格式**：带有 frontmatter 的 Markdown 文件
+- 代理出现在 `/agents` 界面中
+- AI 助手可根据任务上下文自动调用代理
+- 用户也可手动调用代理
+- 插件代理与内置代理协同工作
 
-**Frontmatter 配置**:
-```markdown
----
-name：代理名称（可选，默认使用文件名）
-description：代理描述
-model：使用的模型ID或名称
-tools: Read,Write,Bash（可用工具列表，逗号分隔）
-color: #FF5733（代理显示颜色，可选）
----
+详见 [Subagents](sub-agents.md)。
 
-代理的指令内容
-```
+### 3. Hooks（钩子）
 
-**特性**:
-- 代理可以作为工具被主代理调用
-- 支持自定义工具列表
-- 自动生成源标签标识来源
+插件可以提供事件处理器，自动响应 CodeBuddy 事件。
 
-### 3. Skills （技能）
+**位置**：插件根目录的 `hooks/hooks.json`，或在 `plugin.json` 中内联配置
 
-**位置**：插件根目录的 `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
-        }
-      ]
-    }
-  ]
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/format-code.sh"
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
 **可用事件**:
-- `PreToolUse`：在工具使用之前触发
-- `PostToolUse`：在工具使用之后触发
-- `UserPromptSubmit`：用户提交提示时触发
-- `Notification`：发送通知时触发
-- `Stop`：尝试停止时触发
-- `SubagentStop`：子代理尝试停止时触发
-- `SessionStart`：会话开始时触发
-- `SessionEnd`：会话结束时触发
-- `PreCompact`：对话历史压缩之前触发
+
+插件钩子响应与用户定义钩子相同的生命周期事件：
+
+| 事件 | 触发时机 |
+|------|----------|
+| `SessionStart` | 会话开始或恢复时 |
+| `UserPromptSubmit` | 用户提交提示时，在 AI 处理之前 |
+| `PreToolUse` | 工具调用执行前，可以阻断 |
+| `PermissionRequest` | 权限对话框出现时 |
+| `PermissionDenied` | 工具调用被自动模式分类器拒绝时。返回 `{retry: true}` 告知模型可重试 |
+| `PostToolUse` | 工具调用成功后 |
+| `PostToolUseFailure` | 工具调用失败后 |
+| `Notification` | CodeBuddy 发送通知时 |
+| `SubagentStart` | 子代理启动时 |
+| `SubagentStop` | 子代理完成时 |
+| `TaskCreated` | 通过 `TaskCreate` 创建任务时 |
+| `TaskCompleted` | 任务被标记为已完成时 |
+| `Stop` | AI 完成响应时 |
+| `StopFailure` | 轮次因 API 错误结束时。输出和退出码被忽略 |
+| `TeammateIdle` | 团队成员即将进入空闲时 |
+| `InstructionsLoaded` | CODEBUDDY.md 或 `.codebuddy/rules/*.md` 文件加载到上下文时 |
+| `ConfigChange` | 会话期间配置文件变更时 |
+| `CwdChanged` | 工作目录变更时（例如 AI 执行 `cd` 命令） |
+| `FileChanged` | 监视的文件在磁盘上变更时。`matcher` 字段指定要监视的文件名 |
+| `WorktreeCreate` | 通过 `--worktree` 或 `isolation: "worktree"` 创建工作树时 |
+| `WorktreeRemove` | 工作树被移除时（会话退出或子代理完成时） |
+| `PreCompact` | 上下文压缩之前 |
+| `PostCompact` | 上下文压缩完成后 |
+| `Elicitation` | MCP 服务器在工具调用期间请求用户输入时 |
+| `ElicitationResult` | 用户响应 MCP elicitation 后，响应发回服务器之前 |
+| `SessionEnd` | 会话终止时 |
 
 **钩子类型**:
+
 - `command`：执行 shell 命令或脚本
+- `http`：将事件 JSON 作为 POST 请求发送到 URL
+- `prompt`：使用 LLM 评估提示词（使用 `$ARGUMENTS` 占位符获取上下文）
+- `agent`：运行带工具的代理验证器，用于复杂验证任务
+
+### 4. MCP Servers（MCP 服务器）
 
-**Matcher 规则**:
-- 支持正则表达式匹配工具名称
-- 例如： `"Write|Edit"` 匹配 Write 或 Edit 工具
+插件可以捆绑 Model Context Protocol (MCP) 服务器，将 CodeBuddy 与外部工具和服务连接。
 
-### 5. MCP Servers (MCP 服务器）
+**位置**：插件根目录的 `.mcp.json`，或在 `plugin.json` 中内联配置
 
-**位置**:
-- 插件根目录的 `.mcp.json` 配置文件
-- 或在 `plugin.json` 中通过 PluginInfo 扩展字段配置
+**格式**: 标准 MCP 服务器配置
+
+**配置示例**:
 
-**配置示例** (.mcp.json):
 ```json
 {
   "mcpServers": {
@@ -140,11 +124,13 @@ allowed-tools: Read,Write,Bash（允许使用的工具列表）
 ```
 
 **集成行为**:
+
 - 插件启用时自动启动 MCP 服务器
 - 服务器作为标准 MCP 工具出现在工具包中
 - 服务器功能与现有工具无缝集成
+- 插件服务器可独立于用户 MCP 服务器进行配置
 
-### 6. LSP Servers（LSP 服务器）
+### 5. LSP Servers（LSP 服务器）
 
 > **提示**: 需要使用 LSP 插件? 可从官方市场安装——在 `/plugin` Discover 标签中搜索 "lsp"。本节介绍如何为官方市场未涵盖的语言创建 LSP 插件。
 
@@ -212,7 +198,6 @@ LSP 集成提供:
 | `shutdownTimeout` | 等待优雅关闭的最大时间（毫秒） |
 | `restartOnCrash` | 服务器崩溃时是否自动重启 |
 | `maxRestarts` | 放弃前的最大重启尝试次数 |
-| `loggingConfig` | 调试日志配置（见下文） |
 
 > **警告**: **您必须单独安装语言服务器二进制文件。** LSP 插件配置 CodeBuddy 如何连接到语言服务器，但不包含服务器本身。如果在 `/plugin` Errors 标签中看到 `Executable not found in $PATH` 错误，请为您的语言安装所需的二进制文件。
 
@@ -228,7 +213,26 @@ LSP 集成提供:
 
 ---
 
-## 二、插件清单架构 （plugin.json)
+## 二、插件安装作用域
+
+安装插件时，选择一个**作用域**来决定插件的可用范围：
+
+| 作用域 | 设置文件 | 使用场景 |
+| :--- | :--- | :--- |
+| `user` | `~/.codebuddy/settings.json` | 个人插件，所有项目可用（默认） |
+| `project` | `.codebuddy/settings.json` | 团队插件，通过版本控制共享 |
+| `local` | `.codebuddy/settings.local.json` | 项目特定插件，被 gitignore |
+| `managed` | 托管设置 | 托管插件（只读，仅支持更新） |
+
+插件使用与其他 CodeBuddy 配置相同的作用域系统。详见 [Settings](settings.md)。
+
+---
+
+## 三、插件清单架构（plugin.json）
+
+`.codebuddy-plugin/plugin.json`（或 `.claude-plugin/plugin.json`）文件定义插件的元数据和配置。本节记录所有支持的字段和选项。
+
+清单是可选的。如果省略，CodeBuddy 会自动发现[默认位置](#文件位置参考)中的组件，并从目录名派生插件名称。当需要提供元数据或自定义组件路径时使用清单。
 
 ### 完整架构示例
 
@@ -246,108 +250,131 @@ LSP 集成提供:
   "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/",
+  "skills": "./custom/skills/",
   "hooks": "./config/hooks.json",
-  "mcpServers": [
-    {
-      "name": "custom-server",
-      "command": "node",
-      "args": ["./servers/custom.js"],
-      "env": {
-        "SERVER_PORT": "3000"
-      }
-    }
-  ],
+  "mcpServers": "./mcp-config.json",
+  "outputStyles": "./styles/",
   "lspServers": "./.lsp.json"
 }
 ```
 
 ### 必需字段
 
+如果包含清单，`name` 是唯一必需字段。
+
 | 字段 | 类型 | 描述 | 示例 |
 |------|------|------|------|
-| name | string | 唯一标识符（kebab-case，无空格） | "deployment-tools" |
-| description | string | 插件用途简述 | "部署自动化工具" |
+| `name` | string | 唯一标识符（kebab-case，无空格） | `"deployment-tools"` |
+
+此名称用于组件命名空间。例如在 UI 中，插件 `plugin-dev` 的代理 `agent-creator` 将显示为 `plugin-dev:agent-creator`。
 
 ### 元数据字段
 
 | 字段 | 类型 | 描述 | 示例 |
 |------|------|------|------|
-| 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 | 功能列表 | `["自动部署", "日志分析"]` |
+| `version` | string | 语义化版本。如果在 marketplace 条目中也设置了，`plugin.json` 优先。只需在一处设置。 | `"2.1.0"` |
+| `description` | string | 插件用途简述 | `"部署自动化工具"` |
+| `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"]` |
 
-### 组件路径字段（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"` |
+| `commands` | string \| array | 自定义命令文件/目录（替换默认 `commands/`） | `"./custom/cmd.md"` 或 `["./cmd1.md"]` |
+| `agents` | string \| array | 自定义代理文件（替换默认 `agents/`） | `"./custom/agents/reviewer.md"` |
+| `skills` | string \| array | 自定义技能目录（替换默认 `skills/`） | `"./custom/skills/"` |
+| `hooks` | string \| array \| object | 钩子配置路径或内联配置 | `"./my-extra-hooks.json"` |
+| `mcpServers` | string \| array \| object | MCP 配置路径或内联配置 | `"./my-extra-mcp-config.json"` |
+| `outputStyles` | string \| array | 自定义输出样式文件/目录（替换默认 `output-styles/`） | `"./styles/"` |
+| `lspServers` | string \| array \| object | LSP 配置路径或内联配置 | `"./.lsp.json"` |
+| `userConfig` | object | 启用时提示用户配置的值。详见[用户配置](#用户配置) | 见下方 |
+| `channels` | array | 消息注入的频道声明。详见[频道](#频道) | 见下方 |
 
-### MCPServerConfig 结构
+### 用户配置
 
-```typescript
+`userConfig` 字段声明在插件启用时 CodeBuddy 提示用户输入的值。用此替代要求用户手动编辑 `settings.json`。
+
+```json
 {
-  "name": "服务器名称",
-  "command": "执行命令",
-  "args": ["命令参数数组"],
-  "env": {
-    "环境变量名": "值"
+  "userConfig": {
+    "api_endpoint": {
+      "description": "您团队的 API 端点",
+      "sensitive": false
+    },
+    "api_token": {
+      "description": "API 认证令牌",
+      "sensitive": true
+    }
   }
 }
 ```
 
-### 运行时扩展字段（PluginInfo）
+键必须是有效标识符。每个值可作为 `${user_config.KEY}` 在 MCP 和 LSP 服务器配置、钩子命令中替换，以及（仅非敏感值）在技能和代理内容中替换。值也作为 `CODEBUDDY_PLUGIN_OPTION_<KEY>` 环境变量导出到插件子进程。
 
-插件在运行时会扩展以下字段，支持更灵活的配置方式：
+非敏感值存储在 `settings.json` 的 `pluginConfigs[<plugin-id>].options` 中。敏感值存储到系统密钥链（或在密钥链不可用时存储到 `~/.codebuddy/.credentials.json`）。密钥链存储与 OAuth 令牌共享，总限制约 2 KB，因此敏感值应保持较小。
 
-| 字段 | 类型 | 描述 | 示例 |
-|------|------|------|------|
-| 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 中配置插件的加载方式
-- 支持直接配置对象或文件路径字符串
-- 加载器会智能合并配置路径和默认目录扫描的结果
+### 频道
+
+`channels` 字段允许插件声明一个或多个消息频道，用于向对话中注入内容。每个频道绑定到插件提供的一个 MCP 服务器。
+
+```json
+{
+  "channels": [
+    {
+      "server": "telegram",
+      "userConfig": {
+        "bot_token": { "description": "Telegram bot token", "sensitive": true },
+        "owner_id": { "description": "您的 Telegram 用户 ID", "sensitive": false }
+      }
+    }
+  ]
+}
+```
+
+`server` 字段是必需的，必须匹配插件 `mcpServers` 中的一个键。可选的按频道 `userConfig` 使用与顶层相同的 schema，允许在启用插件时提示输入 bot token 或 owner ID。
 
 ### 路径行为规则
 
-**重要**：自定义路径是对默认目录的**补充**，而不是替换。
+对于 `commands`、`agents`、`skills` 和 `outputStyles`，自定义路径会**替换**默认目录。如果清单指定了 `commands`，则不会扫描默认的 `commands/` 目录。Hooks、MCP servers 和 LSP servers 对处理多个来源有不同的语义。
 
-- 如果 `commands/` 目录存在，它会与自定义命令路径一起加载
-- 所有路径必须相对于插件根目录，并以 `./` 开头
-- 可以将多个路径指定为数组以提高灵活性
-- 路径可以指向单个文件或目录
+- 所有路径必须相对于插件根目录并以 `./` 开头
+- 自定义路径中的组件使用相同的命名和命名空间规则
+- 可以将多个路径指定为数组
+- 要保留默认目录并添加更多路径，在数组中包含默认目录：`"commands": ["./commands/", "./extras/deploy.md"]`
 
-**路径解析规则**:
-- 文件路径： 必须以 `.md` 结尾（对于 commands/agents）或为 `SKILL.md`（对于 skills）
-- 目录路径： 会递归扫描目录中的所有符合条件的文件
+**路径示例**:
+
+```json
+{
+  "commands": [
+    "./specialized/deploy.md",
+    "./utilities/batch-process.md"
+  ],
+  "agents": [
+    "./custom-agents/reviewer.md",
+    "./custom-agents/tester.md"
+  ]
+}
+```
 
 ### 环境变量
 
-**`${CODEBUDDY_PLUGIN_ROOT}`**：包含插件目录的绝对路径。在钩子、MCP 服务器和脚本中使用此变量，以确保无论安装位置如何都能使用正确的路径。
+CodeBuddy 提供两个变量用于引用插件路径。两者都在技能内容、代理内容、钩子命令、MCP 或 LSP 服务器配置中的任何位置进行内联替换。两者也作为环境变量导出到钩子进程和 MCP 或 LSP 服务器子进程。
+
+**`${CODEBUDDY_PLUGIN_ROOT}`**：插件安装目录的绝对路径。用于引用插件捆绑的脚本、二进制文件和配置文件。此路径在插件更新时会变化，因此写入此处的文件不会在更新后保留。
 
 **兼容性**：同时支持 `${CLAUDE_PLUGIN_ROOT}` 变量名以兼容 Claude Code 插件。
 
+**`${CODEBUDDY_PLUGIN_DATA}`**：用于插件状态的持久化目录，在更新后保留。用于已安装的依赖项（如 `node_modules` 或 Python 虚拟环境）、生成的代码、缓存以及任何需要跨插件版本持久化的文件。首次引用时自动创建该目录。
+
+**兼容性**：同时支持 `${CLAUDE_PLUGIN_DATA}` 变量名。
+
 ```json
 {
   "hooks": {
@@ -365,355 +392,414 @@ LSP 集成提供:
 }
 ```
 
+#### 持久化数据目录
+
+`${CODEBUDDY_PLUGIN_DATA}` 目录解析为 `~/.codebuddy/plugins/data/{id}/`，其中 `{id}` 是插件标识符，`a-z`、`A-Z`、`0-9`、`_` 和 `-` 之外的字符替换为 `-`。例如安装为 `formatter@my-marketplace` 的插件，目录为 `~/.codebuddy/plugins/data/formatter-my-marketplace/`。
+
+常见用法是安装语言依赖一次并跨会话和插件更新重用。由于数据目录的生命周期超越任何单一插件版本，仅检查目录存在性无法检测更新何时更改了插件的依赖清单。推荐的模式是将捆绑的清单与数据目录中的副本进行比较，不同时重新安装。
+
+以下 `SessionStart` 钩子在首次运行时安装 `node_modules`，并在插件更新包含更改的 `package.json` 时再次安装：
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CODEBUDDY_PLUGIN_ROOT}/package.json\" \"${CODEBUDDY_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CODEBUDDY_PLUGIN_DATA}\" && cp \"${CODEBUDDY_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CODEBUDDY_PLUGIN_DATA}/package.json\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`diff` 在存储副本缺失或与捆绑副本不同时以非零退出，涵盖首次运行和依赖变更更新。如果 `npm install` 失败，尾部的 `rm` 删除已复制的清单，以便下次会话重试。
+
+捆绑在 `${CODEBUDDY_PLUGIN_ROOT}` 中的脚本可以针对持久化的 `node_modules` 运行：
+
+```json
+{
+  "mcpServers": {
+    "routines": {
+      "command": "node",
+      "args": ["${CODEBUDDY_PLUGIN_ROOT}/server.js"],
+      "env": {
+        "NODE_PATH": "${CODEBUDDY_PLUGIN_DATA}/node_modules"
+      }
+    }
+  }
+}
+```
+
+卸载插件（从最后一个安装作用域）时数据目录会自动删除。`/plugin` 界面显示目录大小并在删除前提示。CLI 默认删除；传递 `--keep-data` 可保留。
+
 ---
 
-## 三、插件目录结构
+## 四、插件缓存和文件解析
+
+插件有两种指定方式：
+
+- 通过 `codebuddy --plugin-dir`，仅在会话期间有效
+- 通过市场安装，适用于未来会话
+
+出于安全和验证目的，CodeBuddy 将**市场**插件复制到用户的本地**插件缓存**（`~/.codebuddy/plugins/cache`），而不是原地使用。理解此行为对于开发引用外部文件的插件很重要。
+
+### 路径遍历限制
+
+已安装的插件无法引用其目录之外的文件。遍历到插件根目录之外的路径（如 `../shared-utils`）在安装后不会工作，因为那些外部文件不会被复制到缓存中。
+
+### 使用外部依赖
+
+如果插件需要访问其目录之外的文件，可以在插件目录中创建指向外部文件的符号链接。符号链接在复制过程中会被保留：
+
+```bash
+# 在插件目录内
+ln -s /path/to/shared-utils ./shared-utils
+```
+
+符号链接的内容将被复制到插件缓存中。这在保持缓存系统安全优势的同时提供了灵活性。
+
+---
+
+## 五、插件目录结构
 
 ### 标准插件布局
 
+完整的插件遵循以下结构：
+
 ```
 enterprise-plugin/
-├── .codebuddy-plugin/       # 元数据目录
-│   └── plugin.json          # 必需：插件清单
-├── commands/                # 默认命令位置
+├── .codebuddy-plugin/        # 元数据目录（可选）
+│   └── plugin.json             # 插件清单
+├── commands/                 # 默认命令位置
 │   ├── status.md
 │   └── logs.md
-├── agents/                  # 默认代理位置
+├── agents/                   # 默认代理位置
 │   ├── security-reviewer.md
 │   ├── performance-tester.md
 │   └── compliance-checker.md
-├── skills/                  # 代理技能
+├── skills/                   # 代理技能
 │   ├── code-reviewer/
 │   │   └── SKILL.md
 │   └── pdf-processor/
 │       ├── SKILL.md
 │       └── scripts/
-├── hooks/                   # 钩子配置
-│   └── hooks.json           # 钩子配置文件
-├── .mcp.json               # MCP 服务器定义
-├── .lsp.json               # LSP 服务器配置
-├── scripts/                # 钩子和实用脚本
+├── output-styles/            # 输出样式定义
+│   └── terse.md
+├── hooks/                    # 钩子配置
+│   ├── hooks.json            # 主钩子配置
+│   └── security-hooks.json   # 额外钩子
+├── bin/                      # 插件可执行文件，添加到 PATH
+│   └── my-tool               # 可在 Bash 工具中作为裸命令调用
+├── settings.json             # 插件默认设置
+├── .mcp.json                 # MCP 服务器定义
+├── .lsp.json                 # LSP 服务器配置
+├── scripts/                  # 钩子和实用脚本
 │   ├── security-scan.sh
 │   ├── format-code.py
 │   └── deploy.js
-├── LICENSE                 # 许可证文件
-└── README.md               # 插件说明
+├── LICENSE                   # 许可证文件
+└── CHANGELOG.md              # 版本历史
 ```
 
-**重要**:
-- `.codebuddy-plugin/` 或 `.claude-plugin/` 目录包含 `plugin.json` 文件
-- 所有其他目录（`commands/`、`agents/`、`skills/`、`hooks/`）必须位于插件根目录
-- 系统优先识别 `.codebuddy-plugin/`,同时兼容 `.claude-plugin/`
+> **重要**: `.codebuddy-plugin/` 目录包含 `plugin.json` 文件。所有其他目录（`commands/`、`agents/`、`skills/`、`output-styles/`、`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 | 语言服务器配置 |
+| **Manifest** | `.codebuddy-plugin/plugin.json` | 插件元数据和配置（可选） |
+| **Commands** | `commands/` | 技能 Markdown 文件（旧版；新技能使用 `skills/`） |
+| **Agents** | `agents/` | 子代理 Markdown 文件 |
+| **Skills** | `skills/` | 带有 `<name>/SKILL.md` 结构的技能 |
+| **Output styles** | `output-styles/` | 输出样式定义 |
+| **Hooks** | `hooks/hooks.json` | 钩子配置 |
+| **MCP servers** | `.mcp.json` | MCP 服务器定义 |
+| **LSP servers** | `.lsp.json` | 语言服务器配置 |
+| **Executables** | `bin/` | 添加到 Bash 工具 PATH 的可执行文件。启用插件时此目录中的文件可在任何 Bash 工具调用中作为裸命令调用 |
+| **Settings** | `settings.json` | 启用插件时应用的默认配置。目前仅支持 [agent](sub-agents.md) 设置 |
 
 ---
 
-## 四、市场清单架构 （marketplace.json)
+## 六、CLI 命令参考
 
-### 完整架构示例
+CodeBuddy 提供 CLI 命令用于非交互式插件管理，适用于脚本和自动化。
 
-```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"
-      }
-    }
-  ]
-}
-```
+### plugin install
 
-### 必需字段
+从可用市场安装插件。
 
-| 字段 | 类型 | 描述 | 示例 |
-|------|------|------|------|
-| name | string | 市场名称 | "企业插件市场" |
-| plugins | array | 插件列表 | 见下方 |
+```bash
+codebuddy plugin install <plugin> [options]
+```
 
-### 元数据字段
+**参数**:
 
-| 字段 | 类型 | 描述 | 示例 |
-|------|------|------|------|
-| description | string | 市场描述 | "企业内部插件集合" |
-| version | string | 市场版本 | "1.0.0" |
-| owner | object | 所有者信息 | `{"name": "团队", "email": "..."}` |
+- `<plugin>`: 插件名称或 `plugin-name@marketplace-name`（指定特定市场）
 
-### 插件条目 （MarketplacePluginEntry)
+**选项**:
 
-每个插件条目包含以下字段：
+| 选项 | 描述 | 默认 |
+|------|------|------|
+| `-s, --scope <scope>` | 安装作用域：`user`、`project` 或 `local` | `user` |
+| `-h, --help` | 显示命令帮助 | |
 
-| 字段 | 类型 | 必需 | 描述 |
-|------|------|------|------|
-| name | string | ✓ | 插件唯一标识符 |
-| description | string | ✓ | 插件描述 |
-| version | string | | 插件版本号 |
-| source | string \| PluginSource | ✓ | 插件源配置 |
-| strict | boolean | | 严格模式（兼容 superpowers-marketplace） |
+作用域决定已安装插件添加到哪个设置文件。例如 `--scope project` 写入 `.codebuddy/settings.json` 中的 `enabledPlugins`，使插件对所有克隆该项目仓库的人可用。
 
-### PluginSource 配置
+**示例**:
 
-插件源支持三种类型：
+```bash
+# 安装到用户作用域（默认）
+codebuddy plugin install formatter@my-marketplace
 
-#### 1. 本地相对路径（字符串）
-```json
-{
-  "source": "plugins/my-plugin"
-}
-```
+# 安装到项目作用域（与团队共享）
+codebuddy plugin install formatter@my-marketplace --scope project
 
-#### 2. 本地路径（对象）
-```json
-{
-  "source": {
-    "source": "local",
-    "path": "plugins/my-plugin"
-  }
-}
+# 安装到本地作用域（被 gitignore）
+codebuddy plugin install formatter@my-marketplace --scope local
 ```
 
-#### 3. GitHub 仓库
-```json
-{
-  "source": {
-    "source": "github",
-    "repo": "owner/repo-name"
-  }
-}
+### plugin uninstall
+
+移除已安装的插件。
+
+```bash
+codebuddy plugin uninstall <plugin> [options]
 ```
 
-#### 4. Git URL
-```json
-{
-  "source": {
-    "source": "url",
-    "url": "https://github.com/owner/repo.git"
-  }
-}
+**参数**:
+
+- `<plugin>`: 插件名称或 `plugin-name@marketplace-name`
+
+**选项**:
+
+| 选项 | 描述 | 默认 |
+|------|------|------|
+| `-s, --scope <scope>` | 从指定作用域卸载：`user`、`project` 或 `local` | `user` |
+| `--keep-data` | 保留插件的[持久化数据目录](#持久化数据目录) | |
+| `-h, --help` | 显示命令帮助 | |
+
+**别名**: `remove`, `rm`
+
+默认情况下，从最后一个剩余作用域卸载时也会删除插件的 `${CODEBUDDY_PLUGIN_DATA}` 目录。使用 `--keep-data` 可保留它，例如在测试新版本后重新安装时。
+
+### plugin enable
+
+启用已禁用的插件。
+
+```bash
+codebuddy plugin enable <plugin> [options]
 ```
 
-### 市场类型
+**参数**:
 
-CodeBuddy 支持四种市场类型：
+- `<plugin>`: 插件名称或 `plugin-name@marketplace-name`
 
-| 类型 | 说明 | source 字段 |
-|------|------|-------------|
-| Directory | 本地文件系统目录 | path：本地目录绝对路径 |
-| Github | GitHub 仓库 | repo: owner/repo 格式 |
-| Git | Git 仓库 | url: Git 仓库 URL |
-| URL | HTTP/HTTPS 远端 | url: marketplace.json 的 URL |
+**选项**:
 
----
+| 选项 | 描述 | 默认 |
+|------|------|------|
+| `-s, --scope <scope>` | 启用作用域：`user`、`project` 或 `local` | `user` |
+| `-h, --help` | 显示命令帮助 | |
 
-## 五、插件加载机制
+### plugin disable
 
-### 加载流程
+禁用插件但不卸载。
 
-1. **市场安装**:
-   - 从配置的源安装市场
-   - 读取 `marketplace.json` 获取插件列表
+```bash
+codebuddy plugin disable <plugin> [options]
+```
 
-2. **插件安装**:
-   - 根据 `source` 配置选择合适的安装器（Local/Git）
-   - 将插件内容安装到目标位置
+**参数**:
 
-3. **插件启用**:
-   - 读取插件的 `plugin.json` 清单
-   - 根据清单配置加载各类组件
+- `<plugin>`: 插件名称或 `plugin-name@marketplace-name`
 
-4. **组件加载**:
-   - 并发加载所有类型的扩展组件
-   - 合并配置路径和默认目录扫描的结果
-   - 缓存加载的组件以提高性能
+**选项**:
 
-### 加载器智能合并
+| 选项 | 描述 | 默认 |
+|------|------|------|
+| `-s, --scope <scope>` | 禁用作用域：`user`、`project` 或 `local` | `user` |
+| `-h, --help` | 显示命令帮助 | |
 
-每个扩展加载器都会智能合并两个来源的内容：
+### plugin update
 
-1. **配置路径**：在 `plugin.json` 或运行时配置中指定的路径
-2. **默认扫描**：默认目录（如 `commands/`、`agents/`）中的文件
+更新插件到最新版本。
 
-**示例**:
-```json
-{
-  "commands": ["./custom/deploy.md"],
-  // 实际加载：
-  // - ./custom/deploy.md （配置路径）
-  // - commands/ 目录中的所有 .md 文件 （默认扫描）
-}
+```bash
+codebuddy plugin update <plugin> [options]
 ```
 
-### 命令名称生成规则
+**参数**:
 
-- 文件名： `command.md` → 命令名: `command`
-- 子目录： `deploy/prod.md` → 命令名: `deploy:prod`
-- 插件前缀： 自动添加插件名作为前缀，如 `plugin-name:command`
+- `<plugin>`: 插件名称或 `plugin-name@marketplace-name`
 
-### 代理和技能标签
+**选项**:
 
-所有从插件加载的代理和技能都会自动添加以下标签：
-- 来源标签： `(plugin-name@marketplace-name)`
-- 类型标签： `plugin`
-- 自定义标签： `custom-agent` 或 `custom-command`
+| 选项 | 描述 | 默认 |
+|------|------|------|
+| `-s, --scope <scope>` | 更新作用域：`user`、`project`、`local` 或 `managed` | `user` |
+| `-h, --help` | 显示命令帮助 | |
 
----
+### 市场管理
 
-## 六、调试和开发工具
+```bash
+# 添加市场
+codebuddy plugin marketplace add <source> [--name <name>]
 
-### 查看插件加载日志
+# 列出市场
+codebuddy plugin marketplace list
 
-使用 `--verbose` 参数查看详细的插件加载信息：
+# 更新市场
+codebuddy plugin marketplace update <name>
+
+# 删除市场
+codebuddy plugin marketplace remove <name>
+```
+
+**市场源格式**:
 
 ```bash
-codebuddy --verbose
+# 本地目录
+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
 ```
 
+---
+
+## 七、调试和开发工具
+
+### 调试命令
+
+使用 `codebuddy --debug` 查看插件加载详情：
+
 **显示内容**:
+
 - 正在加载哪些插件
 - 插件清单中的任何错误
-- 命令、代理和技能注册
+- 命令、代理和钩子注册
 - MCP 服务器初始化
-- Hooks 配置加载
 
 ### 常见问题排查
 
 | 问题 | 原因 | 解决方案 |
 |------|------|----------|
-| 插件未加载 | 无效的 plugin.json | 验证 JSON 语法，检查必需字段 |
-| 命令未出现 | 错误的目录结构 | 确保 commands/ 在插件根目录 |
+| 插件未加载 | 无效的 `plugin.json` | 运行 `codebuddy plugin validate` 或 `/plugin validate` 检查 `plugin.json`、skill/agent/command frontmatter 和 `hooks/hooks.json` 的语法和 schema 错误 |
+| 命令未出现 | 错误的目录结构 | 确保 `commands/` 在插件根目录，而不是 `.codebuddy-plugin/` 内部 |
 | 钩子未触发 | 脚本不可执行 | 运行 `chmod +x script.sh` |
-| MCP 服务器失败 | 缺少环境变量 | 使用 `${CODEBUDDY_PLUGIN_ROOT}` |
+| 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. **测试覆盖**：在不同环境下测试插件的安装和功能
+**清单验证错误**:
 
----
+- `Invalid JSON syntax: Unexpected token } in JSON at position 142`: 检查缺少的逗号、多余的逗号或未引用的字符串
+- `Plugin has an invalid manifest file at .codebuddy-plugin/plugin.json. Validation errors: name: Required`: 缺少必需字段
+- `Plugin has a corrupt manifest file at .codebuddy-plugin/plugin.json. JSON parse error: ...`: JSON 语法错误
 
-## 七、版本管理参考
+**插件加载错误**:
 
-### 语义化版本控制
+- `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: 命令路径存在但不包含有效的命令文件
+- `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: marketplace.json 中的 `source` 路径指向不存在的目录
+- `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: 删除重复的组件定义或在 marketplace 条目中移除 `strict: false`
 
-遵循语义化版本控制进行插件发布：
+### 钩子排查
 
-- **主版本号 （MAJOR)**：不兼容的 API 更改
-- **次版本号 （MINOR)**：向后兼容的功能添加
-- **修订号 （PATCH)**：向后兼容的错误修复
+**钩子脚本未执行**:
 
-示例： `1.2.0` → `1.2.1` （修复） → `1.3.0` （新功能） → `2.0.0` （破坏性更改）
+1. 检查脚本是否可执行：`chmod +x ./scripts/your-script.sh`
+2. 验证 shebang 行：第一行应为 `#!/bin/bash` 或 `#!/usr/bin/env bash`
+3. 检查路径是否使用 `${CODEBUDDY_PLUGIN_ROOT}`：`"command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/your-script.sh"`
+4. 手动测试脚本：`./scripts/your-script.sh`
 
-### 插件更新流程
+**钩子未在预期事件上触发**:
 
-1. 修改插件代码和资源
-2. 更新 `plugin.json` 中的 version 字段
-3. 在 CHANGELOG.md 中记录变更
-4. 提交到版本控制系统
-5. 用户通过 marketplace 更新插件
+1. 验证事件名称正确（区分大小写）：`PostToolUse`，而不是 `postToolUse`
+2. 检查 matcher 模式是否匹配目标工具：`"matcher": "Write|Edit"` 用于文件操作
+3. 确认钩子类型有效：`command`、`http`、`prompt` 或 `agent`
 
----
+### MCP 服务器排查
 
-## 八、CLI 命令参考
+**服务器未启动**:
 
-### 市场管理
+1. 检查命令是否存在且可执行
+2. 验证所有路径使用 `${CODEBUDDY_PLUGIN_ROOT}` 变量
+3. 检查 MCP 服务器日志：`codebuddy --debug` 显示初始化错误
+4. 在 CodeBuddy 之外手动测试服务器
 
-```bash
-# 添加市场
-codebuddy plugin marketplace add <source> [--name <name>]
+**服务器工具未出现**:
 
-# 列出市场
-codebuddy plugin marketplace list
+1. 确保服务器在 `.mcp.json` 或 `plugin.json` 中正确配置
+2. 验证服务器正确实现了 MCP 协议
+3. 检查调试输出中的连接超时
 
-# 更新市场
-codebuddy plugin marketplace update <name>
+### 目录结构错误
+
+**症状**: 插件加载但组件（命令、代理、钩子）缺失。
+
+**正确结构**: 组件必须在插件根目录，而不是 `.codebuddy-plugin/` 内部。只有 `plugin.json` 属于 `.codebuddy-plugin/`。
 
-# 删除市场
-codebuddy plugin marketplace remove <name>
+```
+my-plugin/
+├── .codebuddy-plugin/
+│   └── plugin.json      <- 只有清单在这里
+├── commands/             <- 在根级别
+├── agents/               <- 在根级别
+└── hooks/                <- 在根级别
 ```
 
-### 插件管理
+如果组件在 `.codebuddy-plugin/` 内部，将它们移到插件根目录。
 
-```bash
-# 安装插件
-codebuddy plugin install <plugin-name> <marketplace-name>
+**调试检查清单**:
 
-# 列出已安装插件
-codebuddy plugin list [--marketplace <name>]
+1. 运行 `codebuddy --debug` 并查找 "loading plugin" 消息
+2. 检查每个组件目录是否在调试输出中列出
+3. 验证文件权限允许读取插件文件
 
-# 启用插件
-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>
+```json
+{
+  "name": "my-plugin",
+  "version": "2.1.0"
+}
 ```
 
-### 市场源格式
+**版本格式**: `MAJOR.MINOR.PATCH`
 
-支持以下格式添加市场：
+- **MAJOR**: 不兼容的 API 更改
+- **MINOR**: 向后兼容的功能添加
+- **PATCH**: 向后兼容的错误修复
 
-```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
+- 第一个稳定版本从 `1.0.0` 开始
+- 分发更改前更新 `plugin.json` 中的版本
+- 在 `CHANGELOG.md` 文件中记录变更
+- 使用预发布版本（如 `2.0.0-beta.1`）进行测试
 
-# HTTP URL (marketplace.json)
-codebuddy plugin marketplace add https://example.com/marketplace.json
-```
+> **注意**: CodeBuddy 使用版本来判断是否需要更新插件。如果更改了插件代码但未更新 `plugin.json` 中的版本，由于缓存机制，现有用户不会看到变更。
+>
+> 如果插件在[市场](plugin-marketplaces.md)目录中，可以通过 `marketplace.json` 管理版本，并从 `plugin.json` 中省略 `version` 字段。
 
 ---
 
@@ -725,16 +811,9 @@ 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-plugin/` | `.codebuddy-plugin/`（优先）或 `.claude-plugin/`（兼容） |
+| 环境变量 | `${CLAUDE_PLUGIN_ROOT}` | `${CODEBUDDY_PLUGIN_ROOT}`（优先）或 `${CLAUDE_PLUGIN_ROOT}`（兼容） |
+| 数据目录变量 | `${CLAUDE_PLUGIN_DATA}` | `${CODEBUDDY_PLUGIN_DATA}`（优先）或 `${CLAUDE_PLUGIN_DATA}`（兼容） |
 
 ### 迁移指南
 
@@ -742,7 +821,7 @@ CodeBuddy 在 Claude Code 基础上提供了以下扩展：
 
 1. 可选择将 `.claude-plugin/` 重命名为 `.codebuddy-plugin/`
 2. 可选择将脚本中的 `${CLAUDE_PLUGIN_ROOT}` 替换为 `${CODEBUDDY_PLUGIN_ROOT}`
-3. 如果使用了 `mcpServers` 字段,需要重命名为 `mcpServers`
+3. 可选择将 `${CLAUDE_PLUGIN_DATA}` 替换为 `${CODEBUDDY_PLUGIN_DATA}`
 
 **注意**：保持原有命名也完全兼容，CodeBuddy 会自动识别。
 
@@ -750,25 +829,10 @@ CodeBuddy 在 Claude Code 基础上提供了以下扩展：
 
 ## 相关资源
 
-- **插件开发教程** - 如何创建自定义插件
-- **市场创建指南** - 创建和管理插件市场
-- **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 插件。
+- [插件](plugins.md) - 教程和实用指南
+- [插件市场](plugin-marketplaces.md) - 创建和管理市场
+- [Skills](skills.md) - 技能开发详情
+- [Subagents](sub-agents.md) - 代理配置和能力
+- [Hooks](hooks.md) - 事件处理和自动化
+- [MCP](mcp.md) - 外部工具集成
+- [Settings](settings.md) - 插件配置选项