CLI

插件市场（Plugin Marketplaces） ​

插件市场（Plugin Marketplace）是一个插件目录文件，用于分发和管理 CodeBuddy Code 扩展。通过市场，你可以发现并安装来自不同来源的插件，无需自己构建。

核心功能 ​

  • 集中发现：在一个地方浏览来自多个来源的插件
  • 版本管理：自动跟踪和更新插件版本
  • 自动更新：支持启用自动更新，定期同步市场内容
  • 团队分发：在组织内共享必需的插件
  • 灵活来源：支持 GitHub 仓库、Git URL、本地路径和 HTTP URL
  • 两步流程：先添加市场，再安装具体插件

运行时投影与管理所有权 ​

Agent CLI 的首轮插件投影是 cache-first 的：进程只读取各设置作用域中的 enabledPlugins、installed_plugins.json registry，以及 registry 指向的不可变插件 cache。首轮投影不会扫描 Marketplace、访问远端或修复/迁移磁盘状态；已启用插件的 依赖闭包也只从同一份 registry 与 cache 中解析。

具备管理权限的 Agent CLI runtime 会在首轮投影提交后启动一次后台 reconcile。它负责 同步 Marketplace、补齐插件、迁移旧 cache、应用策略和清理孤儿状态；提交后通过同一条 串行事务队列提交 Plugin 活动快照，避免多轮管理和投影交叉。事务内会并行准备 MCP/LSP 与 Product 投影；Product 提交后，Command、Output Style 和 Agent 并行重建。 后台 reconcile 的活动快照没有变化时不重投下游；发生变化时也只刷新受影响的组件。 宿主若在创建 Session 前确实需要某些插件，可调用通用 _codebuddy.ai/reconcilePlugins ACP 方法：Agent CLI 使用同一标准 workflow 重新检查磁盘并幂等物化， 然后只严格校验宿主传入的 required roots 及其依赖闭包。该请求是有界的；与本会话无关的 marketplace 失败不会阻断已健康的 required roots，migration、cleanup 和 auto-update 仍只属于后台维护。

长驻 Host 还可调用 POST /api/v1/plugins/reconcile，幂等物化 Product/settings 声明的 完整 configured state，并在物化后重建运行时投影。这个端点不接受宿主名、marketplace 名或 本地路径，因而不会形成 WorkBuddy 专用的管理分支；并发请求复用同一个底层 pass。HTTP waiter 有固定上限，超时或客户端断开只结束当前等待，不取消仍受跨进程锁保护的底层物化，后续请求仍可 加入或重试。严格聚合失败前已经原子提交的 marketplace/cache 会先投影为 partial/last-good 状态。

普通 TUI、--print、headless 和 stream-json 调用共享同一条首轮边界：启动时从已提交的 registry/cache 构建运行时投影，第一次真正 dispatch Agent 前等待该投影完成；不会在两种 UI 模式之间插入不同的前台 Marketplace 下载。单个 cache 缺失或加载失败只让对应插件缺席并记录 插件错误，其他插件和 Agent 继续运行；缺失插件由后台 reconcile 补齐并在提交后重投影。

长驻 ACP/serve 进程的 startup 只发布 cache-first 快照，不抢先启动可能覆盖 Session 精确选择的 下游投影。宿主显式 reconcile 会成为第一个完整投影；未发送该扩展的标准 ACP client 在首次 Session 消费时只投影已提交的 registry/cache，不会把产品级全量修复重新接入 Agent 首轮。显式 --no-plugin-management 下只从已有 registry/cache 做完整投影，不产生管理写入。

Directory Marketplace 遵循标准安装语义：marketplace 注册记录保留源目录， 但被安装的插件仍经过标准依赖解析，物化到 cache/<marketplace>/<plugin>/<version>，再提交 installed_plugins.json。运行时只从该 版本化快照加载，不直接把 mutable marketplace source 当作已安装插件。Product 声明的 目录与远端 marketplace 也复用这一流程；缺失 cache/registry 会在具备管理权限的进程中 幂等补齐。

--no-plugin-management 是通用的显式只读开关，仅适用于宿主已能保证完整 registry/cache 闭包的特殊运行时。该模式下 Marketplace 与插件的安装、更新、删除、启停和修复 API 都会在任何 I/O 前拒绝。普通 CLI 和会话 runtime 默认保留标准管理能力；Agent CLI 不根据宿主品牌或拓扑自动切换该模式。

Marketplace 写操作统一按 source → stable storage name 获取跨进程锁；add 在任何 clone/download/swap 之前就持有 source 锁，并在锁内再次按规范化 source 查重，关闭并发 check/install 间的 TOCTOU 窗口。远端 add 先写入独立 staging 目录，registry 提交成功后 才清理旧目录；同进程并发 update 共享一次远端同步，跨进程 update/remove 也遵守同一锁序。 remove 会清理该 Marketplace 在 user/project/local scope 的全部 registry/settings 记录、孤儿 cache、插件配置 和 MCP OAuth 凭证。产品管理的内置 Marketplace 不允许被普通 remove/replace。

远端 Marketplace 也只有 Agent CLI 一套生命周期：Product 只声明 source、url、可选 versionUrl 和 autoUpdate。ZIP 源按 versionUrl → ZIP URL 版本 → ETag/Last-Modified 检查新鲜度；普通自动更新不会清空这些检查元数据或强制下载。ZIP 的 freshness 只在 marketplace.json 与其中声明的全部本地插件目录都完整时生效；任何目录缺失都会绕过 version/ETag short-circuit，重新下载完整快照。ZIP 和 URL 源都先在独立目录完成下载与完整 清单校验，再原子替换 live source；URL 源中任一插件清单失败会让整次刷新失败，不会发布 部分目录。Git 源也先在 live checkout 旁完成浅克隆和完整清单校验，仅在新 commit 就绪后才通过 backup + rename 原子晋升；同 commit 是 no-op，克隆、鉴权、网络或清单失败都保留旧 checkout。 任何 remote registry 记录指向缺失或不完整的本地 source 快照时，后台 reconcile 会把它视为需要重新物化， 而不是只因 source 元数据相同就误判为已安装。声明式 Directory 源临时不可达时则保守保留注册记录和已有 插件 cache，不用空目录覆盖 last-good。刷新失败时不提交新的 marketplace 记录，也不改写已安装 registry/cache；现有版本继续作为 last-good 运行。只有源内容真的变化 时才重新物化该市场中已安装的插件；声明换源和中断状态修复也复用同一条物化路径，而不是只改 marketplace 元数据后留下旧插件 cache。force 只用于用户显式恢复/诊断，不是另一套宿主更新器。

Product 声明的稳定 marketplace 名优先于同源的历史 URL 派生别名：标准注册事务会在新记录 提交后退休旧别名。Agent CLI 不识别 WorkBuddy、Desktop 或任何平台品牌；宿主不应维护额外 版本文件、定时器或强制刷新 RPC。

官方市场 ​

官方市场在 CodeBuddy Code 启动时自动可用。运行 /plugin 并进入发现标签页浏览可用插件。

安装官方市场的插件 ​

使用以下命令从官方市场安装插件：

bash
/plugin install <插件名>@<官方市场名>

例如，安装 GitHub 集成：

bash
/plugin install github@codebuddy-plugins-official

添加市场 ​

使用 /plugin marketplace add 命令从不同来源添加市场。

💡 快捷方式：可以使用 /plugin market 代替 /plugin marketplace，rm 代替 remove

GitHub 仓库 ​

添加包含 .codebuddy-plugin/marketplace.json 文件的 GitHub 仓库，使用 owner/repo 格式：

bash
/plugin marketplace add your-org/codebuddy-plugins

其他 Git 主机 ​

添加来自 GitLab、Bitbucket 或其他 Git 服务的仓库：

使用 HTTPS：

bash
/plugin marketplace add https://gitlab.com/company/plugins.git

使用 SSH：

bash
/plugin marketplace add git@gitlab.com:company/plugins.git

指定特定分支或标签：

bash
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

本地路径 ​

添加本地目录或 marketplace.json 文件（用于开发和测试）：

bash
# 添加包含 .codebuddy-plugin/marketplace.json 的本地目录
/plugin marketplace add ./my-marketplace

# 直接添加 marketplace.json 文件路径
/plugin marketplace add ./path/to/marketplace.json

远程 URL ​

通过 HTTP(S) URL 添加托管的 marketplace.json 文件：

bash
/plugin marketplace add https://example.com/marketplace.json

⚠️ 注意：URL 型市场相比 Git 型市场有一些限制。如果安装插件时遇到"路径未找到"错误，参见故障排除

安装插件 ​

添加市场后，你可以直接安装插件（默认安装到用户作用域）：

bash
/plugin install <插件名>@<市场名>

选择安装作用域 ​

使用交互式界面选择安装作用域：

  1. 运行 /plugin 打开插件管理器
  2. 进入发现标签页
  3. 按 Enter 选择一个插件，查看作用域选项：
    • 用户作用域（默认）：为你自己在所有项目中安装
    • 项目作用域：为所有协作者在此仓库中安装（添加到 .codebuddy/settings.json）
    • 本地作用域：仅为你自己在此仓库中安装（不与协作者共享）
    • 托管作用域：由管理员通过托管设置安装（不可修改）

📌 提示：运行 /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 和所有插件的自动更新。参见自动更新。

保持插件自动更新，禁用 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 连接，与 VS Code 的代码智能相同。

这些插件要求在你的系统上安装语言服务器二进制文件。如果已经安装了语言服务器，打开项目时 CodeBuddy Code 可能会提示你安装对应的插件。

语言插件所需二进制文件
C/C++clangd-lspclangd
C#csharp-lspcsharp-ls
Gogopls-lspgopls
Javajdtls-lspjdtls
Kotlinkotlin-lspkotlin-language-server
Lualua-lsplua-language-server
PHPphp-lspintelephense
Pythonpyright-lsppyright-langserver
Rustrust-analyzer-lsprust-analyzer
Swiftswift-lspsourcekit-lsp
TypeScripttypescript-lsptypescript-language-server

你也可以为其他语言创建自己的 LSP 插件

⚠️ 注意：如果在 /plugin 错误标签页中看到 Executable not found in $PATH，请从上表中安装所需的二进制文件。

代码智能插件的作用 ​

安装代码智能插件并且语言服务器二进制文件可用后，CodeBuddy Code 获得两个能力：

  • 自动诊断：每次编辑后，语言服务器会自动分析更改并报告错误和警告。CodeBuddy Code 可以看到类型错误、缺失的导入和语法问题，无需运行编译器或 linter。如果引入错误，会在同一轮中注意到并修复。无需任何配置即可工作。按 Ctrl+O 可以内联查看诊断。
  • 代码导航：CodeBuddy Code 可以使用语言服务器跳转到定义、查找引用、获取类型信息等。这些操作提供比基于 grep 搜索更精确的导航，尽管可用性可能因语言和环境而异。

遇到问题参见代码智能故障排除

外部集成 ​

这些插件捆绑了预配置的 MCP 服务器，让你无需手动设置即可连接 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
/plugin marketplace add your-org/codebuddy-plugins

这会下载市场目录，使其插件对你可用。

2. 浏览可用插件 ​

运行 /plugin 打开插件管理器。这打开一个选项卡界面，你可以使用 Tab 切换标签页（或使用 Shift+Tab 向后切换）：

  • 发现：浏览所有市场中的可用插件
  • 已安装：查看和管理已安装的插件
  • 市场：添加、移除或更新市场
  • 错误：查看任何插件加载错误

进入发现标签页查看你刚添加的市场中的插件。

3. 安装插件 ​

选择一个插件查看其详情，然后选择安装作用域：

  • 用户作用域：在所有项目中为你自己安装
  • 项目作用域：为此仓库的所有协作者安装
  • 本地作用域：仅在此仓库中为你自己安装

例如，选择 commit-commands（添加 Git 工作流命令的插件）并将其安装到用户作用域。

你也可以直接从命令行安装：

bash
/plugin install commit-commands@your-org-codebuddy-plugins

参见配置作用域了解更多关于作用域的信息。

4. 使用新插件 ​

安装后，运行 /reload-plugins 激活插件。插件命令按插件名称进行命名空间化，所以 commit-commands 提供命令如 /commit-commands:commit。

尝试通过修改文件并运行来使用：

bash
/commit-commands:commit

这会暂存你的更改，生成提交信息并创建提交。

每个插件工作方式都不同。查看发现标签页中的插件描述或其主页了解它提供的命令和功能。

团队市场配置 ​

团队管理员可以通过将市场配置添加到 .codebuddy/settings.json 来为项目自动安装市场。当团队成员信任仓库文件夹时，CodeBuddy Code 会提示他们安装这些市场和插件。

在项目的 .codebuddy/settings.json 中添加 extraKnownMarketplaces：

json
{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/codebuddy-plugins"
      }
    }
  }
}

完整配置选项（包括 extraKnownMarketplaces 和 enabledPlugins），参见插件设置

安全性 ​

插件和市场是高度受信任的组件，可以以你的用户权限在你的计算机上执行任意代码。仅从你信任的来源安装插件和添加市场。组织可以使用托管市场限制限制用户允许添加的市场。

故障排除 ​

/plugin 命令未识别 ​

如果看到"未知命令"或 /plugin 命令不出现：

  1. 检查版本：运行 codebuddy --version 查看已安装的版本
  2. 更新 CodeBuddy Code：
    • npm：npm update -g @tencent-ai/codebuddy-code
    • 本地安装器：重新运行安装中的安装命令
  3. 重启 CodeBuddy Code：更新后，重启终端并再次运行 codebuddy

常见问题 ​

  • 市场无法加载：验证 URL 可访问且路径中存在 .codebuddy-plugin/marketplace.json
  • 插件安装失败：检查插件源 URL 可访问且仓库为公开（或你有访问权限）
  • 安装后文件未找到：插件被复制到缓存，所以引用插件目录外的文件路径无法工作
  • 插件技能不显示：清除缓存 rm -rf ~/.codebuddy/plugins/cache，重启 CodeBuddy Code 并重新安装插件

更多故障排除方案参见完整故障排除指南。调试工具参见调试和开发工具

代码智能问题 ​

  • 语言服务器未启动：验证二进制文件已安装且在 $PATH 中。检查 /plugin 错误标签页了解详情
  • 高内存使用：rust-analyzer 和 pyright 等语言服务器在大型项目上可能消耗大量内存。如果遇到内存问题，使用 /plugin disable <插件名> 禁用插件并依赖 CodeBuddy Code 的内置搜索工具
  • Monorepo 中误报诊断：如果工作区配置不正确，语言服务器可能报告内部包的未解析导入错误。这不影响 CodeBuddy Code 编辑代码的能力

URL 型市场的相对路径问题 ​

URL 型市场是 catalog 分发方式：Agent CLI 获取 marketplace.json，并为相对路径条目获取 plugin.json，但无法通过 HTTP 目录列表递归镜像任意插件文件。因此，只有功能完全由清单内联的插件可以使用 相对路径；包含 skills/commands/hooks/本地代码的插件应在条目中声明 Git/NPM 等可物化的远端源， 或把整个 Marketplace 改用 Git/ZIP 发布。这样 catalog 和插件 payload 的边界是显式的，不会把只下载到的 plugin.json 误当成完整插件目录。

创建自己的市场 ​

在仓库中创建 .codebuddy-plugin/marketplace.json：

json
{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

参见插件引用了解完整的市场和插件配置选项。

后续步骤 ​

字段类型描述
namestring市场标识符（kebab-case，无空格）
ownerobject市场维护者信息
pluginsarray可用插件列表

可选元数据字段 ​

字段类型描述
descriptionstring市场简要描述
versionstring市场版本

插件条目配置 ​

必需字段 ​

字段类型描述
namestring插件标识符（kebab-case，无空格）
sourcestring/object插件获取来源
descriptionstring插件简要描述

可选元数据字段 ​

字段类型描述
versionstring插件版本
authorobject插件作者信息
homepagestring插件主页或文档 URL
repositorystring源代码仓库 URL
licensestringSPDX 许可证标识符（如 MIT、Apache-2.0）
keywordsarray用于插件发现和分类的标签
categorystring插件分类
strictboolean要求插件文件夹中有 plugin.json（默认：true）

组件配置字段 ​

字段类型描述
commandsstring/array命令文件或目录的自定义路径
agentsstring/arrayAgent 文件的自定义路径
skillsstring/arraySkill 文件的自定义路径
hooksstring/object自定义 hooks 配置或 hooks 文件路径
mcpServersstring/objectMCP 服务器配置或 MCP 配置路径

关于 strict 字段：

  • strict: true(默认):插件必须包含 plugin.json 清单文件，marketplace 字段补充这些值
  • strict: false:plugin.json 是可选的。如果缺失，marketplace 条目作为完整的插件清单

插件来源类型 ​

1. 相对路径（Local） ​

用于同一仓库中的插件：

json
{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "My local plugin"
}

2. GitHub 仓库 ​

json
{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  },
  "description": "Plugin from GitHub"
}

3. Git URL ​

json
{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  },
  "description": "Plugin from Git URL"
}

高级插件条目示例 ​

json
{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.company.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": [
    "./agents/security-reviewer.md",
    "./agents/compliance-checker.md"
  ],
  "skills": [
    "./skills/deployment.md",
    "./skills/monitoring.md"
  ],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/validate.sh"
        }]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CODEBUDDY_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CODEBUDDY_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

注意：${CODEBUDDY_PLUGIN_ROOT} 是一个环境变量，解析为插件的安装目录。

托管和分发市场 ​

1. 在 GitHub 上托管（推荐） ​

步骤：

  1. 创建仓库：为 marketplace 设置新仓库
  2. 添加 marketplace 文件：创建 .codebuddy-plugin/marketplace.json 并定义插件
  3. 与团队共享：团队成员使用 /plugin marketplace add owner/repo 添加

优势：内置版本控制、问题跟踪和团队协作功能

2. 在其他 Git 服务上托管 ​

任何 git 托管服务都可以用于 marketplace 分发。例如使用 GitLab：

bash
/plugin marketplace add https://gitlab.com/company/plugins.git

3. 使用 HTTP URL 托管 ​

可以将 marketplace.json 文件托管在任何 HTTP(S) 服务器上：

bash
/plugin marketplace add https://example.com/path/to/marketplace.json

4. 使用本地市场进行开发 ​

在分发前本地测试 marketplace：

bash
# 添加本地 marketplace 进行测试
/plugin marketplace add ./my-local-marketplace

# 测试插件安装
/plugin install test-plugin@my-local-marketplace

市场管理操作 ​

列出已知的市场 ​

bash
/plugin marketplace list

显示所有配置的 marketplace 及其来源和状态。

更新市场元数据 ​

bash
/plugin marketplace update marketplace-name

从 marketplace 来源刷新插件列表和元数据。

移除市场 ​

bash
/plugin marketplace remove marketplace-name

从配置中移除 marketplace。

⚠️ 警告：移除 marketplace 将卸载从中安装的所有插件。

管理自动更新 ​

可以为市场启用自动更新功能，CodeBuddy 会在启动时自动检查并更新已启用的市场。

内置市场：默认启用自动更新

第三方市场：默认禁用自动更新，可通过以下方式启用：

方式 1：通过环境变量全局启用 ​

为所有第三方市场启用自动更新：

bash
export CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES=true
codebuddy

方式 2：通过 UI 单个管理 ​

  1. 运行 /plugin 命令进入插件管理界面
  2. 选择「Marketplaces」查看市场列表
  3. 选择需要配置的市场
  4. 选择「Enable auto-update」或「Disable auto-update」切换状态

自动更新机制：

  • 启动时延迟 5 秒后执行，不影响主流程
  • 仅更新距上次更新超过 24 小时的市场
  • 多个市场间隔 2 秒依次更新，避免资源竞争
  • 更新失败不影响其他市场，错误记录到日志

优先级：环境变量优先于单个市场的 UI 开关

实现原理 ​

市场类型 ​

CodeBuddy 支持以下几种市场类型：

  1. Directory（本地目录）：从本地文件系统加载插件
  2. GitHub：从 GitHub 仓库克隆和更新插件
  3. Git：从任意 Git 仓库克隆和更新插件
  4. URL（HTTP）：从 HTTP(S) URL 下载 marketplace.json

市场工厂模式 ​

通过 MarketplaceFactory 根据配置创建不同类型的市场实例：

typescript
// 根据源类型创建对应的市场实例
switch (sourceType) {
    case MarketplaceType.Directory:
        marketplace = new DirectoryMarketplace();
        break;
    case MarketplaceType.Github:
    case MarketplaceType.Git:
        marketplace = new GithubMarketplace();
        break;
    case MarketplaceType.URL:
        marketplace = new HttpMarketplace();
        break;
    default:
        marketplace = new BaseMarketplace();
        break;
}

安装流程 ​

  1. 解析源：根据输入字符串判断市场类型（本地路径、GitHub 仓库、Git URL、HTTP URL）
  2. 下载/克隆：根据市场类型下载或克隆市场内容
  3. 读取清单：解析 .codebuddy-plugin/marketplace.json 文件
  4. 保存配置：将市场信息保存到本地存储
  5. 更新缓存：刷新插件缓存和市场列表

插件安装器 ​

CodeBuddy 使用插件安装器（PluginInstaller）来处理不同类型的插件源：

  • 本地安装器：处理相对路径插件
  • Git 安装器：处理 GitHub 和 Git URL 插件

每个安装器实现以下方法：

  • support(source)：判断是否支持该插件源
  • isInstalled(plugin, targetDir)：检查插件是否已安装
  • install(plugin, targetDir)：安装插件
  • update(plugin, installedPath)：更新插件

故障排除 ​

常见问题 ​

1. 市场无法加载 ​

症状：无法添加 marketplace 或看不到其中的插件

解决方案：

  • 验证 marketplace URL 可访问
  • 检查指定路径是否存在 .codebuddy-plugin/marketplace.json
  • 确保 JSON 语法有效
  • 对于私有仓库，确认您有访问权限

2. 插件安装失败 ​

症状：Marketplace 显示但插件安装失败

解决方案：

  • 验证插件源 URL 可访问
  • 检查插件目录是否包含必需文件
  • 对于 GitHub 源，确保仓库是公开的或您有访问权限
  • 通过克隆/下载手动测试插件源

3. Git 操作失败 ​

症状：克隆或拉取仓库时出错

解决方案：

  • 确保已安装 Git 并可在命令行使用
  • 检查网络连接和代理设置
  • 验证 Git 凭据配置正确
  • 使用 --debug 标志查看详细日志

调试技巧 ​

  1. 启用调试日志：
bash
codebuddy --debug
  1. 手动验证市场文件：
bash
# 检查 marketplace.json 格式
cat .codebuddy-plugin/marketplace.json | jq
  1. 测试 Git 克隆：
bash
# 手动测试 Git 克隆是否成功
git clone https://github.com/owner/repo.git /tmp/test-clone

下一步 ​

对于市场用户 ​

  • 发现社区 marketplaces：在 GitHub 上搜索 CodeBuddy 插件集合
  • 贡献反馈：向 marketplace 维护者报告问题和建议改进
  • 分享有用的 marketplaces：帮助团队发现有价值的插件集合

对于市场创建者 ​

  • 构建插件集合：围绕特定用例创建主题 marketplace
  • 建立版本控制：实施清晰的版本控制和更新策略
  • 社区参与：收集反馈并维护活跃的 marketplace 社区
  • 文档：提供清晰的 README 文件解释 marketplace 内容

对于组织 ​

  • 私有 marketplaces：为专有工具设置内部 marketplace
  • 治理策略：建立插件审批和安全审查指南
  • 培训资源：帮助团队有效发现和采用有用的插件

相关资源 ​