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

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

@@ -52,6 +52,7 @@
 | `--debug`                        | 启用调试模式,支持可选的类别过滤                                                                                                   | `codebuddy --debug`                                                                                |
 | `--worktree [name]`              | 在独立的 git worktree 中运行（详见 [Worktree 文档](./worktree.md)）                                                               | `codebuddy --worktree` 或 `codebuddy --worktree my-feature`                                        |
 | `--tmux`                         | 在 tmux 会话中运行（与 `--worktree` 配合使用）                                                                                     | `codebuddy --worktree --tmux`                                                                      |
+| `--plugin-dir <dirs...>`         | 从本地目录加载插件（用于开发/测试），可指定多个路径。详见 [插件文档](plugins.md)                                                     | `codebuddy --plugin-dir ./my-plugin ../other-plugin`                                               |
 
 > **重要提示**：在使用 `-p/--print` 参数进行非交互式执行时,涉及文件读写、命令执行、网络请求等操作通常需要添加 `-y` （或 `--dangerously-skip-permissions`)参数才能执行，否则操作会被阻止。
 

package/dist/web-ui/docs/cn/cli/env-vars.md

@@ -54,6 +54,8 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 |---------|------|
 | `CODEBUDDY_DISABLE_HOT_RELOAD` | 设置为 `1` 禁用热更新系统 |
 | `CODEBUDDY_SKIP_BUILTIN_MARKETPLACE` | 设置为 `1` 跳过内置插件市场加载 |
+| `CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES` | 设置为 `true` 或 `1` 启用第三方插件市场自动更新（默认：禁用） |
+| `CODEBUDDY_PLUGIN_DIRS` | 冒号分隔的本地插件目录路径列表（等同于 `--plugin-dir`），插件的 `bin/` 目录会自动注入到 `PATH` |
 | `CODEBUDDY_IMAGE_GEN_ENABLED` | 设置为 `false` 或 `0` 禁用图片生成功能 |
 | `CODEBUDDY_IMAGE_EDIT_ENABLED` | 设置为 `false` 或 `0` 禁用图片编辑功能 |
 | `CODEBUDDY_DEFER_TOOL_LOADING` | 设置为 `false` 或 `0` 禁用 MCP 工具延迟加载 |

package/dist/web-ui/docs/cn/cli/http-api.md

@@ -117,9 +117,11 @@ curl http://host:port/api/v1/sessions?password=YOUR_PASSWORD
 
 | 方法 | 端点 | 说明 |
 |------|------|------|
-| GET | `/api/v1/sessions` | 获取会话列表 |
+| GET | `/api/v1/sessions` | 获取会话列表（支持 cwd 查询参数） |
 | DELETE | `/api/v1/sessions/:id` | 删除会话 |
 | POST | `/api/v1/sessions/:id/rename` | 重命名会话 |
+| GET | `/api/v1/sessions/across-projects` | ⚠️ 已废弃，使用 `GET /api/v1/sessions?cwd=*` 代替 |
+| GET | `/api/v1/sessions/workspaces` | ⚠️ 已废弃 |
 
 ### PTY（终端）
 
@@ -219,6 +221,31 @@ CBC 增强：
 | GET | `/api/v1/file-changes/checkpoints` | 列出可回退的 checkpoint |
 | POST | `/api/v1/file-changes/revert` | 撤回文件变更或回退到 checkpoint |
 
+### 插件管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/v1/plugins` | 列出已安装插件 |
+| POST | `/api/v1/plugins` | 安装插件 |
+| POST | `/api/v1/plugins/validate` | 验证插件/市场清单文件 |
+| POST | `/api/v1/plugins/enable` | 启用插件 |
+| POST | `/api/v1/plugins/disable` | 禁用插件 |
+| POST | `/api/v1/plugins/uninstall` | 卸载插件 |
+| GET | `/api/v1/plugins/marketplaces` | 列出已配置的插件市场 |
+| POST | `/api/v1/plugins/marketplaces` | 添加插件市场 |
+| POST | `/api/v1/plugins/marketplaces/browse` | 浏览市场中的可用插件 |
+| DELETE | `/api/v1/plugins/marketplaces/:name` | 删除插件市场 |
+
+### 配置管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/v1/settings` | 列出所有配置 |
+| GET | `/api/v1/settings/:key` | 获取单个配置值 |
+| PUT | `/api/v1/settings/:key` | 设置配置值 |
+| POST | `/api/v1/settings/:key/items` | 向数组类配置追加值 |
+| POST | `/api/v1/settings/:key/remove` | 从数组类配置移除值 |
+
 ### 任务模板
 
 | 方法 | 端点 | 说明 |
@@ -340,15 +367,32 @@ curl http://127.0.0.1:8080/api/v1/metrics
 ### 会话管理
 
 ```bash
-# 获取会话列表
+# 获取当前工作空间的会话列表
 curl http://127.0.0.1:8080/api/v1/sessions
 
+# 获取所有工作空间的会话列表
+curl http://127.0.0.1:8080/api/v1/sessions?cwd=*
+
+# 获取指定工作目录的会话列表
+curl http://127.0.0.1:8080/api/v1/sessions?cwd=/path/to/workspace
+
+# 获取指定项目的会话列表（按压缩工作目录名过滤）
+curl http://127.0.0.1:8080/api/v1/sessions?cwd=*&projectId=workspace-hash
+
 # 重命名会话
 curl -X POST http://127.0.0.1:8080/api/v1/sessions/SESSION_ID/rename \
   -H "Content-Type: application/json" \
   -d '{"name": "性能优化讨论"}'
 ```
 
+**cwd 查询参数说明**:
+
+| cwd 值 | 说明 |
+|--------|------|
+| 不传 | 返回当前工作空间的会话 |
+| `*` | 返回所有工作空间的会话 |
+| `/path/to/workspace` | 返回指定工作目录的会话 |
+
 ### 文件变更管理
 
 ```bash
@@ -378,6 +422,77 @@ curl -X POST http://127.0.0.1:8080/api/v1/file-changes/revert \
   -d '{}'
 ```
 
+### 插件管理
+
+```bash
+# 列出已安装插件
+curl http://127.0.0.1:8080/api/v1/plugins
+
+# 安装插件（"name@marketplace" 格式）
+curl -X POST http://127.0.0.1:8080/api/v1/plugins \
+  -H "Content-Type: application/json" \
+  -d '{"plugin": "my-plugin@my-marketplace"}'
+
+# 启用插件
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/enable \
+  -H "Content-Type: application/json" \
+  -d '{"plugin": "my-plugin@my-marketplace"}'
+
+# 禁用插件
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/disable \
+  -H "Content-Type: application/json" \
+  -d '{"plugin": "my-plugin@my-marketplace"}'
+
+# 卸载插件
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/uninstall \
+  -H "Content-Type: application/json" \
+  -d '{"plugin": "my-plugin@my-marketplace"}'
+
+# 列出插件市场
+curl http://127.0.0.1:8080/api/v1/plugins/marketplaces
+
+# 添加插件市场
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \
+  -H "Content-Type: application/json" \
+  -d '{"source": "https://example.com/marketplace", "name": "my-marketplace"}'
+
+# 浏览市场中的插件
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \
+  -H "Content-Type: application/json" \
+  -d '{"marketplace": "my-marketplace"}'
+
+# 删除插件市场
+curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace
+```
+
+### 配置管理
+
+```bash
+# 列出所有配置
+curl http://127.0.0.1:8080/api/v1/settings
+
+# 按作用域列出配置
+curl "http://127.0.0.1:8080/api/v1/settings?scope=user"
+
+# 获取单个配置
+curl http://127.0.0.1:8080/api/v1/settings/model
+
+# 设置配置值
+curl -X PUT http://127.0.0.1:8080/api/v1/settings/theme \
+  -H "Content-Type: application/json" \
+  -d '{"value": "dark"}'
+
+# 向数组类配置追加值
+curl -X POST http://127.0.0.1:8080/api/v1/settings/permissions/items \
+  -H "Content-Type: application/json" \
+  -d '{"values": ["Allow: Read(**)"]}'
+
+# 从数组类配置移除值
+curl -X POST http://127.0.0.1:8080/api/v1/settings/permissions/remove \
+  -H "Content-Type: application/json" \
+  -d '{"values": ["Allow: Read(**)"]}'
+```
+
 ## 错误码
 
 | 错误码 | HTTP 状态 | 说明 |

package/dist/web-ui/docs/cn/cli/plugin-marketplaces.md

@@ -1,6 +1,6 @@
-# 插件市场 （Plugin Marketplaces)
+# 插件市场（Plugin Marketplaces）
 
-插件市场（Plugin Marketplace）是一个插件目录文件，用于分发和管理 CodeBuddy 扩展。它是一个 JSON 格式的配置文件，列出了可用的插件及其来源信息。
+插件市场（Plugin Marketplace）是一个插件目录文件，用于分发和管理 CodeBuddy Code 扩展。通过市场，你可以发现并安装来自不同来源的插件，无需自己构建。
 
 ## 核心功能
 
@@ -8,40 +8,63 @@
 - **版本管理**：自动跟踪和更新插件版本
 - **自动更新**：支持启用自动更新，定期同步市场内容
 - **团队分发**：在组织内共享必需的插件
-- **灵活来源**：支持 Git 仓库、GitHub 仓库、本地路径和 HTTP URL
+- **灵活来源**：支持 GitHub 仓库、Git URL、本地路径和 HTTP URL
+- **两步流程**：先添加市场，再安装具体插件
 
-## 使用插件市场
+## 官方市场
 
-### 前置要求
+官方市场在 CodeBuddy Code 启动时自动可用。运行 `/plugin` 并进入**发现**标签页浏览可用插件。
 
-- 已安装并运行 CodeBuddy
-- 基本了解 JSON 文件格式
-- 创建 marketplace 需要：Git 仓库或本地开发环境
+### 安装官方市场的插件
 
-### 添加插件市场
+使用以下命令从官方市场安装插件：
 
-#### 1. 添加 GitHub 市场
+```bash
+/plugin install <插件名>@<官方市场名>
+```
+
+例如，安装 GitHub 集成：
 
 ```bash
-/plugin marketplace add owner/repo
+/plugin install github@codebuddy-plugins-official
 ```
 
-要求仓库包含 `.codebuddy-plugin/marketplace.json` 文件。
+## 添加市场
+
+使用 `/plugin marketplace add` 命令从不同来源添加市场。
+
+> 💡 **快捷方式**：可以使用 `/plugin market` 代替 `/plugin marketplace`，`rm` 代替 `remove`
 
-#### 2. 添加 Git 仓库市场
+### GitHub 仓库
+
+添加包含 `.codebuddy-plugin/marketplace.json` 文件的 GitHub 仓库，使用 `owner/repo` 格式：
 
 ```bash
-# HTTPS 格式
+/plugin marketplace add your-org/codebuddy-plugins
+```
+
+### 其他 Git 主机
+
+添加来自 GitLab、Bitbucket 或其他 Git 服务的仓库：
+
+使用 HTTPS：
+```bash
 /plugin marketplace add https://gitlab.com/company/plugins.git
+```
 
-# SSH 格式 （git@)
+使用 SSH：
+```bash
 /plugin marketplace add git@gitlab.com:company/plugins.git
+```
 
-# .git 后缀格式
-/plugin marketplace add https://example.com/repo.git
+指定特定分支或标签：
+```bash
+/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0
 ```
 
-#### 3. 添加本地市场（用于开发）
+### 本地路径
+
+添加本地目录或 `marketplace.json` 文件（用于开发和测试）：
 
 ```bash
 # 添加包含 .codebuddy-plugin/marketplace.json 的本地目录
@@ -51,79 +74,314 @@
 /plugin marketplace add ./path/to/marketplace.json
 ```
 
-#### 4. 添加 HTTP 市场
+### 远程 URL
+
+通过 HTTP(S) URL 添加托管的 `marketplace.json` 文件：
+
+```bash
+/plugin marketplace add https://example.com/marketplace.json
+```
+
+> ⚠️ **注意**：URL 型市场相比 Git 型市场有一些限制。如果安装插件时遇到"路径未找到"错误，参见[故障排除](#url-型市场的相对路径问题)
+
+## 安装插件
+
+添加市场后，你可以直接安装插件（默认安装到用户作用域）：
+
+```bash
+/plugin install <插件名>@<市场名>
+```
+
+### 选择安装作用域
+
+使用交互式界面选择[安装作用域](./settings.md#配置作用域)：
+
+1. 运行 `/plugin` 打开插件管理器
+2. 进入**发现**标签页
+3. 按 **Enter** 选择一个插件，查看作用域选项：
+   - **用户作用域**（默认）：为你自己在所有项目中安装
+   - **项目作用域**：为所有协作者在此仓库中安装（添加到 `.codebuddy/settings.json`）
+   - **本地作用域**：仅为你自己在此仓库中安装（不与协作者共享）
+   - **托管作用域**：由管理员通过[托管设置](./settings.md#托管设置)安装（不可修改）
+
+> 📌 **提示**：运行 `/plugin` 进入**已安装**标签页，查看按作用域分组的插件
+
+## 管理已安装的插件
+
+运行 `/plugin` 并进入**已安装**标签页来查看、启用、禁用或卸载插件。输入文本筛选插件列表。
+
+### 快速管理命令
+
+禁用插件（不卸载）：
+```bash
+/plugin disable <插件名>@<市场名>
+```
+
+重新启用已禁用的插件：
+```bash
+/plugin enable <插件名>@<市场名>
+```
+
+完全卸载插件：
+```bash
+/plugin uninstall <插件名>@<市场名>
+```
+
+指定特定作用域：
+```bash
+/plugin install <插件名>@<市场名> --scope project
+/plugin uninstall <插件名>@<市场名> --scope project
+```
+
+### 无需重启应用更改
+
+安装、启用或禁用插件后，运行 `/reload-plugins` 无需重启即可加载所有更改：
+
+```bash
+/reload-plugins
+```
+
+CodeBuddy Code 重新加载所有活跃插件，并显示插件数、技能数、代理数、钩子数、插件 MCP 服务器数和插件 LSP 服务器数的统计。
+
+## 管理市场
+
+通过交互式 `/plugin` 界面或命令行管理市场。
+
+### 交互式界面管理
+
+运行 `/plugin` 并进入**市场**标签页来：
+
+- 查看所有已添加的市场及其来源和状态
+- 添加新市场
+- 更新市场列表以获取最新插件
+- 移除不再需要的市场
+
+### 命令行管理
+
+列出所有已配置的市场：
+```bash
+/plugin marketplace list
+```
+
+刷新市场的插件列表：
+```bash
+/plugin marketplace update <市场名>
+```
+
+移除市场：
+```bash
+/plugin marketplace remove <市场名>
+```
+
+> ⚠️ **警告**：移除市场将卸载从该市场安装的所有插件
+
+### 配置自动更新
+
+CodeBuddy Code 可以在启动时自动更新市场及其已安装的插件。启用市场自动更新后，CodeBuddy Code 会刷新市场数据并将已安装插件更新到最新版本。如果任何插件被更新，你会看到提示运行 `/reload-plugins` 的通知。
+
+**通过 UI 为单个市场切换自动更新**：
+
+1. 运行 `/plugin` 打开插件管理器
+2. 选择**市场**
+3. 从列表中选择一个市场
+4. 选择**启用自动更新**或**禁用自动更新**
+
+官方市场默认启用自动更新。第三方和本地开发市场默认禁用自动更新。
+
+**禁用所有自动更新**：
+
+设置 `DISABLE_AUTOUPDATER` 环境变量可以禁用 CodeBuddy Code 和所有插件的自动更新。参见[自动更新](./env-vars.md#自动更新)。
+
+**保持插件自动更新，禁用 CodeBuddy 自动更新**：
+
+设置 `FORCE_AUTOUPDATE_PLUGINS=1` 和 `DISABLE_AUTOUPDATER=1`：
+
+```bash
+export DISABLE_AUTOUPDATER=1
+export FORCE_AUTOUPDATE_PLUGINS=1
+```
+
+这样你可以手动管理 CodeBuddy Code 更新，同时自动接收插件更新。
+
+## 官方市场内容
+
+官方市场包含多个类别的插件：
+
+### 代码智能
+
+代码智能插件启用 CodeBuddy Code 内置的 LSP 工具，让 AI 能够跳转到定义、查找引用、查看类型错误等。这些插件配置 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 连接，与 VS Code 的代码智能相同。
+
+这些插件要求在你的系统上安装语言服务器二进制文件。如果已经安装了语言服务器，打开项目时 CodeBuddy Code 可能会提示你安装对应的插件。
+
+| 语言 | 插件 | 所需二进制文件 |
+|------|------|----------------|
+| C/C++ | `clangd-lsp` | `clangd` |
+| C# | `csharp-lsp` | `csharp-ls` |
+| Go | `gopls-lsp` | `gopls` |
+| Java | `jdtls-lsp` | `jdtls` |
+| Kotlin | `kotlin-lsp` | `kotlin-language-server` |
+| Lua | `lua-lsp` | `lua-language-server` |
+| PHP | `php-lsp` | `intelephense` |
+| Python | `pyright-lsp` | `pyright-langserver` |
+| Rust | `rust-analyzer-lsp` | `rust-analyzer` |
+| Swift | `swift-lsp` | `sourcekit-lsp` |
+| TypeScript | `typescript-lsp` | `typescript-language-server` |
+
+你也可以为其他语言[创建自己的 LSP 插件](./plugins-reference.md#lsp-servers)
+
+> ⚠️ **注意**：如果在 `/plugin` 错误标签页中看到 `Executable not found in $PATH`，请从上表中安装所需的二进制文件。
+
+#### 代码智能插件的作用
+
+安装代码智能插件并且语言服务器二进制文件可用后，CodeBuddy Code 获得两个能力：
+
+* **自动诊断**：每次编辑后，语言服务器会自动分析更改并报告错误和警告。CodeBuddy Code 可以看到类型错误、缺失的导入和语法问题，无需运行编译器或 linter。如果引入错误，会在同一轮中注意到并修复。无需任何配置即可工作。按 **Ctrl+O** 可以内联查看诊断。
+* **代码导航**：CodeBuddy Code 可以使用语言服务器跳转到定义、查找引用、获取类型信息等。这些操作提供比基于 grep 搜索更精确的导航，尽管可用性可能因语言和环境而异。
+
+遇到问题参见[代码智能故障排除](#代码智能问题)
+
+### 外部集成
+
+这些插件捆绑了预配置的 [MCP 服务器](./mcp.md)，让你无需手动设置即可连接 CodeBuddy Code 到外部服务：
+
+* **源代码管理**：`github`、`gitlab`
+* **项目管理**：`atlassian`（Jira/Confluence）、`asana`、`linear`、`notion`
+* **设计**：`figma`
+* **基础设施**：`vercel`、`firebase`、`supabase`
+* **通信**：`slack`
+* **监控**：`sentry`
+
+### 开发工作流
+
+为常见开发任务添加命令和代理的插件：
+
+* **commit-commands**：Git 提交工作流，包括提交、推送和 PR 创建
+* **pr-review-toolkit**：用于审查拉取请求的专用代理
+* **plugin-dev**：创建自己的插件的工具包
+
+### 输出样式
+
+自定义 CodeBuddy Code 的响应方式：
+
+* **explanatory-output-style**：关于实现选择的教育性见解
+* **learning-output-style**：用于技能建设的交互式学习模式
+
+## 试用：添加第三方市场
+
+除了官方市场，你还可以添加第三方市场来获取更多插件。以下是完整的使用流程：
+
+### 1. 添加市场
+
+从 CodeBuddy Code 内运行 `plugin marketplace add` 命令添加市场：
 
 ```bash
-# 通过 URL 添加远程 marketplace.json
-/plugin marketplace add https://url.of/marketplace.json
+/plugin marketplace add your-org/codebuddy-plugins
 ```
 
-### 从市场安装插件
+这会下载市场目录，使其插件对你可用。
+
+### 2. 浏览可用插件
+
+运行 `/plugin` 打开插件管理器。这打开一个选项卡界面，你可以使用 **Tab** 切换标签页（或使用 **Shift+Tab** 向后切换）：
+
+* **发现**：浏览所有市场中的可用插件
+* **已安装**：查看和管理已安装的插件
+* **市场**：添加、移除或更新市场
+* **错误**：查看任何插件加载错误
+
+进入**发现**标签页查看你刚添加的市场中的插件。
+
+### 3. 安装插件
+
+选择一个插件查看其详情，然后选择安装作用域：
+
+* **用户作用域**：在所有项目中为你自己安装
+* **项目作用域**：为此仓库的所有协作者安装
+* **本地作用域**：仅在此仓库中为你自己安装
+
+例如，选择 **commit-commands**（添加 Git 工作流命令的插件）并将其安装到用户作用域。
+
+你也可以直接从命令行安装：
 
 ```bash
-# 从已知的 marketplace 安装
-/plugin install plugin-name@marketplace-name
+/plugin install commit-commands@your-org-codebuddy-plugins
+```
 
-# 交互式浏览可用插件
-/plugin
+参见[配置作用域](./settings.md#配置作用域)了解更多关于作用域的信息。
+
+### 4. 使用新插件
+
+安装后，运行 `/reload-plugins` 激活插件。插件命令按插件名称进行命名空间化，所以 **commit-commands** 提供命令如 `/commit-commands:commit`。
+
+尝试通过修改文件并运行来使用：
+
+```bash
+/commit-commands:commit
 ```
 
-### 验证市场安装
+这会暂存你的更改，生成提交信息并创建提交。
 
-1. **列出市场**：运行 `/plugin marketplace list` 确认已添加
-2. **浏览插件**：使用 `/plugin` 查看 marketplace 中的可用插件
-3. **测试安装**：尝试安装一个插件以验证 marketplace 正常工作
+每个插件工作方式都不同。查看**发现**标签页中的插件描述或其主页了解它提供的命令和功能。
 
-## 团队配置
+## 团队市场配置
 
-### 自动安装团队市场
+团队管理员可以通过将市场配置添加到 `.codebuddy/settings.json` 来为项目自动安装市场。当团队成员信任仓库文件夹时，CodeBuddy Code 会提示他们安装这些市场和插件。
 
-在 `.codebuddy/settings.json` 中配置：
+在项目的 `.codebuddy/settings.json` 中添加 `extraKnownMarketplaces`：
 
 ```json
 {
   "extraKnownMarketplaces": {
-    "team-tools": {
+    "my-team-tools": {
       "source": {
         "source": "github",
         "repo": "your-org/codebuddy-plugins"
       }
-    },
-    "project-specific": {
-      "source": {
-        "source": "git",
-        "url": "https://git.company.com/project-plugins.git"
-      }
     }
-  },
-  "enabledPlugins": {
-    "plugin-a@team-tools": true,
-    "plugin-b@team-tools": true
   }
 }
 ```
 
-当团队成员启动 CodeBuddy 时，系统会自动安装这些 marketplace 和 `enabledPlugins` 字段中指定的插件。
+完整配置选项（包括 `extraKnownMarketplaces` 和 `enabledPlugins`），参见[插件设置](./settings.md#插件设置)
 
-### 自动安装流程
+## 安全性
 
-1. **启动检测**：CodeBuddy 启动时会自动检测配置文件
-2. **市场安装**：自动安装 `extraKnownMarketplaces` 中未安装的市场
-3. **插件安装**：自动安装 `enabledPlugins` 中已启用但未安装的插件
-4. **后台执行**：安装过程在后台异步执行，不阻塞启动流程
-5. **日志记录**：安装过程会记录详细日志，可通过 `--debug` 查看
+插件和市场是高度受信任的组件，可以以你的用户权限在你的计算机上执行任意代码。仅从你信任的来源安装插件和添加市场。组织可以使用[托管市场限制](./settings.md#托管市场限制)限制用户允许添加的市场。
 
-## 创建自己的市场
+## 故障排除
+
+### /plugin 命令未识别
 
-### 创建前置要求
+如果看到"未知命令"或 `/plugin` 命令不出现：
 
-- Git 仓库（GitHub、GitLab 或其他 git 托管服务）
-- 了解 JSON 文件格式
-- 一个或多个要分发的插件
+1. **检查版本**：运行 `codebuddy --version` 查看已安装的版本
+2. **更新 CodeBuddy Code**：
+   * **npm**：`npm update -g @tencent-ai/codebuddy-code`
+   * **本地安装器**：重新运行[安装](./installation.md)中的安装命令
+3. **重启 CodeBuddy Code**：更新后，重启终端并再次运行 `codebuddy`
+
+### 常见问题
 
-### 创建市场文件
+* **市场无法加载**：验证 URL 可访问且路径中存在 `.codebuddy-plugin/marketplace.json`
+* **插件安装失败**：检查插件源 URL 可访问且仓库为公开（或你有访问权限）
+* **安装后文件未找到**：插件被复制到缓存，所以引用插件目录外的文件路径无法工作
+* **插件技能不显示**：清除缓存 `rm -rf ~/.codebuddy/plugins/cache`，重启 CodeBuddy Code 并重新安装插件
 
-在仓库根目录创建 `.codebuddy-plugin/marketplace.json`：
+更多故障排除方案参见[完整故障排除指南](./troubleshooting.md)。调试工具参见[调试和开发工具](./plugins-reference.md#调试和开发工具)
+
+### 代码智能问题
+
+* **语言服务器未启动**：验证二进制文件已安装且在 `$PATH` 中。检查 `/plugin` 错误标签页了解详情
+* **高内存使用**：`rust-analyzer` 和 `pyright` 等语言服务器在大型项目上可能消耗大量内存。如果遇到内存问题，使用 `/plugin disable <插件名>` 禁用插件并依赖 CodeBuddy Code 的内置搜索工具
+* **Monorepo 中误报诊断**：如果工作区配置不正确，语言服务器可能报告内部包的未解析导入错误。这不影响 CodeBuddy Code 编辑代码的能力
+
+### URL 型市场的相对路径问题
+
+如果从 URL 型市场安装插件时遇到"路径未找到"错误，这是因为相对路径参考问题。使用 Git 型市场（GitHub、GitLab 等）或将所有路径更改为绝对 URL 作为解决方案。
+
+## 创建自己的市场
+
+在仓库中创建 `.codebuddy-plugin/marketplace.json`：
 
 ```json
 {
@@ -151,9 +409,9 @@
 }
 ```
 
-### 市场配置结构 （Marketplace Schema)
+参见[插件引用](./plugins-reference.md)了解完整的市场和插件配置选项。
 
-#### 必需字段
+## 后续步骤
 
 | 字段 | 类型 | 描述 |
 |------|------|------|
@@ -374,7 +632,24 @@
 
 可以为市场启用自动更新功能，CodeBuddy 会在启动时自动检查并更新已启用的市场。
 
-**启用方式**：
+**内置市场**：默认启用自动更新
+
+**第三方市场**：默认禁用自动更新，可通过以下方式启用：
+
+#### 方式 1：通过环境变量全局启用
+
+为所有第三方市场启用自动更新：
+
+```bash
+export CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES=true
+codebuddy
+```
+
+#### 方式 2：通过产品配置启用
+
+在 product 配置中设置 `autoUpdateThirdPartyMarketplaces: true`，为所有第三方市场启用自动更新。
+
+#### 方式 3：通过 UI 单个管理
 
 1. 运行 `/plugin` 命令进入插件管理界面
 2. 选择「Marketplaces」查看市场列表
@@ -388,6 +663,8 @@
 - 多个市场间隔 2 秒依次更新，避免资源竞争
 - 更新失败不影响其他市场，错误记录到日志
 
+**优先级**：环境变量 > 产品配置 > UI 配置
+
 ## 实现原理
 
 ### 市场类型