@tencent-ai/agent-sdk 0.3.99 → 0.3.100

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

@@ -0,0 +1,533 @@
+# 插件市场 （Plugin Marketplaces)
+
+插件市场（Plugin Marketplace）是一个插件目录文件，用于分发和管理 CodeBuddy 扩展。它是一个 JSON 格式的配置文件，列出了可用的插件及其来源信息。
+
+## 核心功能
+
+- **集中发现**：在一个地方浏览来自多个来源的插件
+- **版本管理**：自动跟踪和更新插件版本
+- **自动更新**：支持启用自动更新，定期同步市场内容
+- **团队分发**：在组织内共享必需的插件
+- **灵活来源**：支持 Git 仓库、GitHub 仓库、本地路径和 HTTP URL
+
+## 使用插件市场
+
+### 前置要求
+
+- 已安装并运行 CodeBuddy
+- 基本了解 JSON 文件格式
+- 创建 marketplace 需要：Git 仓库或本地开发环境
+
+### 添加插件市场
+
+#### 1. 添加 GitHub 市场
+
+```bash
+/plugin marketplace add owner/repo
+```
+
+要求仓库包含 `.codebuddy-plugin/marketplace.json` 文件。
+
+#### 2. 添加 Git 仓库市场
+
+```bash
+# HTTPS 格式
+/plugin marketplace add https://gitlab.com/company/plugins.git
+
+# SSH 格式 （git@)
+/plugin marketplace add git@gitlab.com:company/plugins.git
+
+# .git 后缀格式
+/plugin marketplace add https://example.com/repo.git
+```
+
+#### 3. 添加本地市场（用于开发）
+
+```bash
+# 添加包含 .codebuddy-plugin/marketplace.json 的本地目录
+/plugin marketplace add ./my-marketplace
+
+# 直接添加 marketplace.json 文件路径
+/plugin marketplace add ./path/to/marketplace.json
+```
+
+#### 4. 添加 HTTP 市场
+
+```bash
+# 通过 URL 添加远程 marketplace.json
+/plugin marketplace add https://url.of/marketplace.json
+```
+
+### 从市场安装插件
+
+```bash
+# 从已知的 marketplace 安装
+/plugin install plugin-name@marketplace-name
+
+# 交互式浏览可用插件
+/plugin
+```
+
+### 验证市场安装
+
+1. **列出市场**：运行 `/plugin marketplace list` 确认已添加
+2. **浏览插件**：使用 `/plugin` 查看 marketplace 中的可用插件
+3. **测试安装**：尝试安装一个插件以验证 marketplace 正常工作
+
+## 团队配置
+
+### 自动安装团队市场
+
+在 `.codebuddy/settings.json` 中配置：
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "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` 字段中指定的插件。
+
+### 自动安装流程
+
+1. **启动检测**：CodeBuddy 启动时会自动检测配置文件
+2. **市场安装**：自动安装 `extraKnownMarketplaces` 中未安装的市场
+3. **插件安装**：自动安装 `enabledPlugins` 中已启用但未安装的插件
+4. **后台执行**：安装过程在后台异步执行，不阻塞启动流程
+5. **日志记录**：安装过程会记录详细日志，可通过 `--debug` 查看
+
+## 创建自己的市场
+
+### 创建前置要求
+
+- Git 仓库（GitHub、GitLab 或其他 git 托管服务）
+- 了解 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"
+    }
+  ]
+}
+```
+
+### 市场配置结构 （Marketplace Schema)
+
+#### 必需字段
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| name | string | 市场标识符（kebab-case，无空格）|
+| owner | object | 市场维护者信息 |
+| plugins | array | 可用插件列表 |
+
+#### 可选元数据字段
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| description | string | 市场简要描述 |
+| version | string | 市场版本 |
+
+### 插件条目配置
+
+#### 必需字段
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| name | string | 插件标识符（kebab-case，无空格）|
+| source | string/object | 插件获取来源 |
+| description | string | 插件简要描述 |
+
+#### 可选元数据字段
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| version | string | 插件版本 |
+| author | object | 插件作者信息 |
+| homepage | string | 插件主页或文档 URL |
+| repository | string | 源代码仓库 URL |
+| license | string | SPDX 许可证标识符（如 MIT、Apache-2.0）|
+| keywords | array | 用于插件发现和分类的标签 |
+| category | string | 插件分类 |
+| strict | boolean | 要求插件文件夹中有 plugin.json（默认：true）|
+
+#### 组件配置字段
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| commands | string/array | 命令文件或目录的自定义路径 |
+| agents | string/array | Agent 文件的自定义路径 |
+| skills | string/array | Skill 文件的自定义路径 |
+| hooks | string/object | 自定义 hooks 配置或 hooks 文件路径 |
+| mcpServers | string/object | MCP 服务器配置或 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. 运行 `/plugin` 命令进入插件管理界面
+2. 选择「Marketplaces」查看市场列表
+3. 选择需要配置的市场
+4. 选择「Enable auto-update」或「Disable auto-update」切换状态
+
+**自动更新机制**：
+
+- 启动时延迟 5 秒后执行，不影响主流程
+- 仅更新距上次更新超过 24 小时的市场
+- 多个市场间隔 2 秒依次更新，避免资源竞争
+- 更新失败不影响其他市场，错误记录到日志
+
+## 实现原理
+
+### 市场类型
+
+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
+```
+
+2. **手动验证市场文件**：
+
+```bash
+# 检查 marketplace.json 格式
+cat .codebuddy-plugin/marketplace.json | jq
+```
+
+3. **测试 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
+- 治理策略：建立插件审批和安全审查指南
+- 培训资源：帮助团队有效发现和采用有用的插件
+
+## 相关资源
+
+- [插件系统](./plugins.md) - 插件系统总览
+- [技能系统](./skills.md) - 创建和使用技能
+- [斜杠命令](./slash-commands.md) - 创建自定义命令
+- [Hooks](./hooks.md) - 创建事件钩子
+- [设置](./settings.md) - 插件配置选项