# CodeBuddy Code 安装指南

## 安装方式

### 📦 使用包管理器安装

#### Node.js 包管理器

**前置要求:** Node.js 18.20 或更高版本

选择你喜欢的包管理器执行以下命令:

::: code-group

```bash [npm]
npm install -g @tencent-ai/codebuddy-code
```

```bash [pnpm]
pnpm add -g @tencent-ai/codebuddy-code
```

```bash [yarn]
yarn global add @tencent-ai/codebuddy-code
```

```bash [bun]
bun install -g @tencent-ai/codebuddy-code
```

:::

#### Homebrew (macOS/Linux)

无需 Node.js，直接安装:

::: code-group

```bash [两步安装]
# 添加 tap
brew tap Tencent-CodeBuddy/tap

# 安装工具
brew install codebuddy-code
```

```bash [单命令安装]
brew install Tencent-CodeBuddy/tap/codebuddy-code
```

```ruby [Brewfile]
tap "Tencent-CodeBuddy/tap"
brew "codebuddy-code"
```

:::

#### 验证安装

安装完成后,运行以下命令验证是否安装成功:

```bash
codebuddy --version
```


### ⚙️ 使用原生二进制安装（Beta）

> ⚠️ **Beta 测试阶段**
>
> 原生二进制安装目前处于 Beta 测试阶段，功能仍在完善中。
> 如遇到任何问题，请在 [Issues 页面](https://cnb.cool/codebuddy/codebuddy-code/-/issues) 提交问题报告，或联系技术支持（codebuddy@tencent.com）。

#### 特性说明

原生二进制安装相比 npm 版本提供以下特性：

- 单一可执行文件，无需额外依赖
- 无需 Node.js 运行时
- 改进的自动更新机制

#### 支持平台

- macOS (Apple Silicon M1/M2/M3 或 Intel x86_64)
- Linux (arm64 或 x86_64)
- Windows (x86_64)

#### 从 npm 版本迁移

如果你已经通过 npm 安装了 CodeBuddy Code，可以使用以下命令迁移到原生二进制版本：

```bash
codebuddy install
```

#### 全新安装

::: code-group

```bash [macOS / Linux]
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

```powershell [Windows]
irm https://www.codebuddy.cn/cli/install.ps1 | iex
```

:::

#### 验证安装

安装脚本会自动下载最新版本并配置环境变量。安装完成后，运行以下命令验证：

```bash
codebuddy --version
```

**如果命令不可用**,请手动将安装路径添加到环境变量 `PATH`:

::: code-group

```bash [macOS / Linux]
export PATH="$HOME/.local/bin:$PATH"

# 为了永久生效,建议添加到 shell 配置文件:
# Bash: ~/.bashrc 或 ~/.bash_profile
# Zsh: ~/.zshrc
```

```powershell [Windows]
# 添加以下路径到用户环境变量:
# %USERPROFILE%\AppData\Local\codebuddy\bin
```

:::


## 📁 配置目录

CodeBuddy Code 默认将配置文件存储在以下目录:

| 平台 | 默认配置目录 |
|------|-------------|
| macOS / Linux | `~/.codebuddy` |
| Windows | `%USERPROFILE%\.codebuddy` |

### 配置目录内容

```
~/.codebuddy/
├── settings.json      # 用户设置
├── mcp.json           # MCP 服务器配置
├── .mcp.json          # MCP 服务器配置（备选位置）
└── skills/            # 用户自定义 Skills
```

### 自定义配置目录

通过设置环境变量 `CODEBUDDY_CONFIG_DIR` 可以自定义配置目录位置:

```bash
export CODEBUDDY_CONFIG_DIR="$HOME/.my-codebuddy-config"
```

这在以下场景中非常有用:

- 多个 CodeBuddy 实例需要独立配置
- 企业环境中需要统一管理配置位置
- 与其他使用 CodeBuddy 引擎的应用（如 WorkBuddy）共存时避免配置冲突


## 🔄 更新

### 自动更新

CodeBuddy Code 默认会自动保持最新状态，以确保你拥有最新的功能和安全修复。

#### 关闭自动更新

如需关闭自动更新，可设置环境变量：

```bash
export DISABLE_AUTOUPDATER=1
```

### 手动更新

使用以下命令手动更新到最新版本：

```bash
codebuddy update
```

`update` 命令会自动检测你的安装方式并执行相应的更新操作。

#### 使用包管理器更新

如果 `codebuddy update` 命令未能成功更新，你也可以使用包管理器重新安装：

```bash
npm install -g @tencent-ai/codebuddy-code
```

或使用其他包管理器（pnpm、yarn、bun）执行相应的安装命令。


## 🔧 故障排查

### 命令不可用

**问题：** 安装后提示 `codebuddy: command not found`

**解决方案：**

1. 检查安装路径是否在 `PATH` 环境变量中：
   ```bash
   echo $PATH
   ```

2. 将 CodeBuddy 安装路径添加到 `PATH`（参考上方[验证安装](#验证安装）部分）

3. 重启终端或重新加载配置文件：
   ```bash
   source ~/.bashrc  # 或 ~/.zshrc
   ```

### 网络问题

**问题：** 安装或更新时网络连接失败

**解决方案：**

1. 检查网络连接
2. 配置 npm 镜像源（如果使用 npm 安装）：
   ```bash
   npm config set registry https://registry.npmmirror.com
   ```

## 🗑️ 卸载

### 包管理器版本卸载

::: code-group

```bash [Homebrew]
# 卸载工具
brew uninstall codebuddy-code

# 移除 tap (可选)
brew untap Tencent-CodeBuddy/tap
```

```bash [npm]
npm uninstall -g @tencent-ai/codebuddy-code
```

```bash [pnpm]
pnpm remove -g @tencent-ai/codebuddy-code
```

```bash [yarn]
yarn global remove @tencent-ai/codebuddy-code
```

```bash [bun]
bun remove -g @tencent-ai/codebuddy-code
```

:::

### 原生二进制版本卸载

#### macOS / Linux

删除可执行文件:

```bash
rm -f ~/.local/bin/codebuddy
```

### 清理配置文件(可选)

如需完全清理,可删除配置目录:

**macOS / Linux:**
```bash
rm -rf ~/.codebuddy
rm -rf ~/.local/share/codebuddy
```

> 💡 **提示:** 如果你使用了 `CODEBUDDY_CONFIG_DIR` 环境变量自定义了配置目录，请删除对应的目录。
