# 快速入门指南

欢迎使用 CodeBuddy Code！这份指南将帮助您在 5 分钟内上手，体验自然语言驱动的编程助手。

## 🎯 开始之前

### 系统要求
- **Node.js**：版本 18.20 或更高
- **操作系统**: macOS、Linux 或 Windows

### 验证环境
```bash
# 检查 Node.js 版本
node --version  # 应显示 v18.0.0 或更高

# 检查 npm 版本
npm --version
```

## ⚡ 极速安装

### npm 全局安装

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

### 原生安装器（Beta）

> ⚠️ **Beta 功能**：原生安装器目前处于 Beta 阶段。我们推荐您尝试使用，以获得更快速、独立的安装体验。

原生安装器提供独立的 CodeBuddy 安装，无需 Node.js 环境。

**下载并安装：**

```bash
# macOS/Linux
curl -fsSL https://copilot.tencent.com/cli/install.sh | bash
```

```powershell
# Windows
irm https://copilot.tencent.com/cli/install.ps1 | iex
```

**优势：**
- ✅ 无需 Node.js 依赖
- ✅ 安装和启动速度更快

### 验证安装
```bash
codebuddy --version
```

## 🔐 登录认证

首次使用 CodeBuddy Code 时，您需要完成登录认证。启动后会显示登录方式选择界面：

```
Select login method:
› Log in via Chinese Site
  Log in via International Site
  Log in via Enterprise Domain
  Log in via iOA (Tencent only)
```

### 登录方式说明

| 登录方式 | 适用场景 | 说明 |
|---------|---------|------|
| **Chinese Site** | 国内用户 | 通过腾讯云国内站 (copilot.tencent.com) 进行认证，支持国内主流模型 |
| **International Site** | 海外用户 | 通过腾讯云国际站 (codebuddy.ai) 进行认证，支持海外主流模型 |
| **Enterprise Domain** | 专享版/私有化部署 | 连接企业专享版或自建的 CodeBuddy 服务，需要输入企业提供的服务地址 |
| **iOA** | 腾讯内部员工 | 通过腾讯 iOA 零信任系统进行认证，仅限腾讯内部员工使用 |

使用 `↑↓` 键选择登录方式，按 `Enter` 确认后会自动打开浏览器完成认证。

## 🚀 首次体验

### 1. 进入项目目录
```bash
cd /path/to/your/project
```

### 2. 启动交互模式
```bash
codebuddy
```

您将看到欢迎界面：

> **提示**：如果您希望 CodeBuddy Code 始终使用特定语言回复（如简体中文），可以在启动后运行 `/config` 命令设置 Language 选项。
```
🤖 CodeBuddy Code v1.0.0
💡 输入 /help 查看可用命令
📝 开始对话，让 AI 成为您的编程伙伴

>
```

### 3. 初始化项目上下文（强烈推荐）

在正式开始对话之前，**强烈建议**先使用 `/init` 命令初始化项目上下文：

```
> /init
```

**为什么 /init 如此重要？**

**📊 效果提升：**
- ✅ **理解更准确**：预先构建项目知识图谱，AI 能更准确理解代码结构和业务逻辑
- ✅ **响应更快速**：避免重复扫描文件，后续对话响应速度显著提升
- ✅ **建议更精准**：基于全局视图提供更符合项目架构的建议
- ✅ **减少误判**：了解项目依赖关系，避免提出不兼容的修改方案

**💰 成本优化：**
- ✅ **Token 消耗更少**：一次性建立上下文，避免每次对话都重新分析
- ✅ **减少重复请求**：预加载关键信息，减少 30-50% 的上下文 Token 开销
- ✅ **更高效的对话**：每轮对话携带更少的冗余信息，整体成本更低

**最佳实践：**
```
# 第一次使用项目时
> /init

# 项目结构发生重大变化时（如添加新模块、重构等）
> /clear  # 开启全新对话
> /init   # 重新初始化
```

### 4. 尝试第一个对话
```
> 帮我分析这个项目的结构
```

CodeBuddy 会自动扫描您的项目文件，并提供详细的结构分析。

## 💡 核心使用模式

### 交互式对话模式
最自然的使用方式，适合探索性开发：

```bash
codebuddy
```

**典型对话示例：**
```
> 我想给这个 React 组件添加一个加载状态
> 帮我重构这个函数，让它更易读
> 这段代码有什么潜在的性能问题？
> 为这个 API 接口写单元测试
```

### 单次命令模式
适合脚本化和自动化场景：

```bash
# 直接提问
codebuddy -p "优化这个 SQL 查询的性能"

# 管道输入
cat error.log | codebuddy -p "分析这些错误日志"

# 文件分析（需要授权时必须添加 -y 或 --dangerously-skip-permissions）
codebuddy -p "审查 src/utils.js 的代码质量" -y
```

> **重要提示**：使用 `-p/--print` 参数进行单次执行时,如果操作需要访问文件、执行命令等授权操作,必须添加 `-y` （或 `--dangerously-skip-permissions`) 参数。

### 项目级操作
处理复杂的跨文件任务：

```bash
# 项目重构（需要文件操作授权）
codebuddy -p "将所有组件从 class 组件迁移到函数组件" -y

# 代码规范（需要文件读取授权）
codebuddy -p "检查整个项目的 TypeScript 类型定义" -y

# 测试覆盖（需要文件操作授权）
codebuddy -p "为 services 目录下的所有文件添加单元测试" -y
```

### 快捷键

#### 基础导航
| 快捷键 | 功能 |
|--------|------|
| `↑/↓` | 浏览命令历史 |
| `↓` | 查看后台任务（当有运行中任务时） |
| `Tab` | 命令自动补全 |
| `Esc` | 清空输入（按两次） / 返回上级菜单 |
| `Ctrl+C` | 退出程序 |
| `Ctrl+D` | 退出程序（输入框为空且无进行中对话时，连按两次） |

#### 权限和模式
| 快捷键 | 功能 |
|--------|------|
| `Shift+Tab` (macOS/Linux) 或 `Alt+M` (Windows) | 切换权限模式（default → bypass → accept → plan） |

#### 编辑功能
| 快捷键 | 功能 |
|--------|------|
| `Ctrl+R` | 展开/收起详细输出（在对话中） |
| `Ctrl+G` | 使用外部编辑器编辑提示词 |
| `Enter` | 发送消息 |
| `Shift+Enter` | 换行（多行输入） |
| `\Enter` | 换行（反斜杠转义） |
| `Ctrl+J` | 插入换行（多行输入） |

#### 面板操作
| 快捷键 | 功能 |
|--------|------|
| `↑/↓` | 在面板中导航选项 |
| `Enter` | 选择当前项 |
| `Space` | 切换选择（多选面板） |
| `k` | 终止选中的后台任务 |

#### 专用功能
| 快捷键 | 功能 |
|--------|------|
| `j/k` | Vim风格的上下导航（部分面板支持） |
| `Ctrl+O` | 查看思考详情面板 |

当终端显示“Thinking”指示时，可用 `Ctrl+O` 打开完整推理内容,再按 `Ctrl+O` 退出。

## 🎓 进阶学习

恭喜您完成快速入门！接下来推荐阅读：

- **[常见工作流](common-workflows.md)** - 学习扩展思考、图片分析等高级功能
- **[IDE 集成](ide-integrations.md)** - 在 VS Code、JetBrains 中使用
- **[斜杠命令](slash-commands.md)** - 掌握所有内置命令
- **[MCP 集成](mcp.md)** - 扩展自定义工具

## 💬 获取帮助

遇到问题？我们随时为您提供支持：

- 🐛 [提交 Bug](https://cnb.cool/codebuddy/codebuddy-code/-/issues)
- 📧 技术支持：codebuddy@tencent.com
- 📚 [完整文档](./README.md)
- 🌐 [官方网站](https://copilot.tencent.com/cli)

---

*现在开始，让 AI 成为您的编程伙伴！🚀*
