用 CodeBuddy Code 命令行完成项目初始化与首次对话

CodeBuddy Code 是一个以命令行方式运行的 AI 编程助手：在项目目录里启动它，用自然语言描述需求，它会读取代码、给出分析、生成修改，必要时还会请求执行命令的权限。它适合已经习惯终端工作流、希望把 AI 辅助嵌进日常开发与脚本自动化的人；如果你更习惯图形界面，它同样提供 IDE 集成路径，但本文只讲命令行这一条主线。想先了解这个工具的整体定位，可以看站内的 CodeBuddy 条目，再回到这里按步骤动手。

下面按「准备环境 → 安装 → 登录 → 初始化项目上下文 → 第一次对话 → 两种使用模式 → 完整示例 → 注意事项」的顺序展开，每一步都给出可以直接复制执行的命令。涉及版本号、模型可用范围、配额与计费的内容，请以官网当前信息为准。

准备工作

系统与运行时要求

CodeBuddy Code 对运行环境的要求很克制，主要卡在 Node.js 版本上：

• Node.js：18.20 或更高版本。
• 操作系统：macOS、Linux 或 Windows。

在安装之前先确认本机环境，避免装到一半才发现版本不够：

# 检查 Node.js 版本
node --version
# 应显示 v18.20.0 或更高

# 检查 npm 版本
npm --version

如果 node --version 的输出低于 18.20，先升级 Node.js 再继续。用版本管理工具（如 nvm 一类）切换版本比直接覆盖系统 Node 更稳妥，尤其是机器上还有其他项目依赖旧版本时。

账号与登录方式的选择

首次使用需要完成登录认证。启动后会出现登录方式选择界面，用上下方向键选中、回车确认，随后会自动打开浏览器完成认证。可选的登录方式有四种，适用场景不同：

登录方式	适用场景	说明
Chinese Site	在中国大陆使用的用户	通过腾讯云中国站完成认证，支持中国主流模型
International Site	中国大陆以外地区的用户	通过腾讯云国际站完成认证，支持海外主流模型
Enterprise Domain	专享版 / 私有化部署	连接企业专享版或自建的 CodeBuddy 服务，需要输入企业提供的服务地址
iOA	腾讯内部员工	通过腾讯 iOA 零信任系统认证，仅限腾讯内部员工

选择哪一项取决于你的账号归属和所在网络环境。企业用户如果拿到的是一份服务地址，就走 Enterprise Domain；个人开发者按自己所在地区选前两项之一即可。登录方式与可用模型范围可能随产品调整，具体以官网当前信息为准。

操作步骤

第一步：安装 CodeBuddy Code

常规做法是用 npm 全局安装：

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

全局安装意味着 codebuddy 命令在任何目录下都可用，这也是后续所有命令的前提。

此外还提供原生安装器，目前处于 Beta 阶段。它的价值在于安装包独立、不依赖 Node.js 环境，安装与启动速度也更快。macOS 与 Linux 下执行：

curl -fsSL https://copilot.tencent.com/cli/install.sh | bash

Windows 下在 PowerShell 中执行：

irm https://copilot.tencent.com/cli/install.ps1 | iex

因为标注为 Beta，生产环境或团队统一部署时建议先在小范围验证，再决定是否替换 npm 安装方式。两种方式选其一即可，不必同时安装。

第二步：验证安装结果

安装完成后确认命令已经进入 PATH：

codebuddy --version

能打印出版本号就说明安装成功。如果提示找不到命令，通常是 npm 全局 bin 目录不在 PATH 中，或者安装过程中权限不足导致包没有写入全局目录。

第三步：进入项目并启动

CodeBuddy Code 的工作范围是当前目录，所以先切到目标项目再启动：

cd /path/to/your/project
codebuddy

启动后会看到欢迎界面，包含版本号、/help 提示和一个等待输入的提示符。此时已经可以对话，但先别急着提问，下一步的初始化更值得优先做。

如果你希望它固定用某种语言回复（例如始终用简体中文），在启动后运行 /config 命令，找到 Language 选项设置即可。这样能避免每次对话都要额外交代语言。

第四步：用 /init 建立项目上下文

在正式对话之前，强烈建议先执行一次初始化：

> /init

这一步会预先构建项目知识图谱，让助手理解代码结构与业务逻辑。它带来的差别体现在几个方面：

• 理解更准确：基于预先建立的项目视图，对代码结构和业务逻辑的判断更贴近实际。
• 响应更快速：不必每次对话都重新扫描文件，后续交互明显更快。
• 建议更精准：站在全局视角给建议，更符合项目既有架构。
• 减少误判：了解依赖关系后，不容易提出与现有依赖不兼容的改法。
• 成本更低：上下文一次性建立，避免每轮重复分析，减少冗余信息带来的 Token 开销。

什么时候需要重新初始化？项目结构发生重大变化时，例如新增了模块、做了较大规模的重构。推荐的做法是先清空对话再重新初始化：

> /clear
> /init

这样能保证上下文与当前代码状态一致，而不是在旧认知上继续叠加。

第五步：发起第一次对话

初始化完成后，用一句自然语言描述你想了解或想做的事，例如：

> 帮我分析这个项目的结构

它会自动扫描项目文件并给出结构分析。这一步的意义不只是拿到答案，也是检验 /init 是否生效——如果分析结果能准确指出模块划分和关键入口，说明上下文建立成功。

两种使用模式

交互式对话模式

直接运行 codebuddy 进入的就是交互模式，适合探索性开发：边看边问，逐步收敛需求。典型的提问方式包括：

• 「我想给这个 React 组件添加一个加载状态」
• 「帮我重构这个函数，让它更易读」
• 「这段代码有什么潜在的性能问题？」
• 「为这个 API 接口写单元测试」

这类问题的共同点是范围明确、上下文就在当前仓库里，交互模式能让你在得到初步结果后继续追问、逐步修正。

单次命令模式

用 -p（即 --print）参数可以执行一次性任务，适合脚本化和自动化场景。三种常见用法：

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

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

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

这里有一个必须记住的点：使用 -p 做单次执行时，如果操作需要访问文件、执行命令等授权动作，必须加上 -y（或完整写法 --dangerously-skip-permissions），否则会因为无法获得授权而中断。

但 -y 并不等于「什么都不问」。仅加 -y 时，被判定为 HIGH 或 CRITICAL 级别的危险命令仍可能要求确认。如果确实需要在隔离沙箱里完全不询问地执行，需要额外设置环境变量：

export CODEBUDDY_IS_SANDBOX=1 && codebuddy -p -y ...

这一组合属于高危用法，只应在确认隔离的沙箱环境中使用，不要在存放真实凭据或生产配置的机器上随手打开。

项目级批量操作

单次命令模式也适合处理跨文件的复杂任务，例如：

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

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

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

这类任务改动面大，建议在版本控制干净的工作区里执行，执行后先看 diff 再决定是否保留。

一个完整示例

下面把前面的步骤串成一条从零到跑通的路径，假设你刚拿到一台新机器和一个待分析的前端项目。

1. 确认环境

node --version
npm --version

输出满足 Node.js 18.20 以上即可继续。

2. 安装

npm install -g @tencent-ai/codebuddy-code
codebuddy --version

第二条命令能打印版本号，说明安装完成。

3. 进入项目并启动

cd ~/work/my-web-app
codebuddy

4. 完成登录

在登录方式选择界面用方向键选中与你账号匹配的一项，回车后浏览器会打开认证页面，完成后回到终端。

5. 设置回复语言（可选）

> /config

在配置中找到 Language，设为简体中文。

6. 初始化项目上下文

> /init

7. 第一次提问

> 帮我分析这个项目的结构

观察它给出的模块划分是否与你的认知一致。如果偏差较大，检查是否在正确的目录下启动。

8. 用单次命令做一次自动化检查

退出交互模式后，在同一个目录执行：

codebuddy -p "检查整个项目的 TypeScript 类型定义" -y

这条命令把同样的能力放进了可脚本化的入口，之后可以接进 CI 或本地提交前检查。

至此，安装、认证、上下文初始化、交互与单次两种模式都已经跑通。

常用快捷键

熟悉快捷键能明显减少操作摩擦，下面按用途分组。

基础导航

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

权限与模式

快捷键	功能
Shift+Tab（Windows 也支持 Alt+M）	切换权限模式（default → bypass → accept → plan）

权限模式决定了它对文件写入、命令执行等动作的放行程度。日常开发建议保持在需要确认的模式，只有在明确知道后果时才切到更宽松的模式。

编辑与输入

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

需要写较长的提示词时，Ctrl+G 打开外部编辑器会比在终端里硬敲舒服得多。

面板与专用功能

快捷键	功能
↑ / ↓ 或 j / k	在面板中导航选项（支持 Vim 风格）
Enter	选择当前项
Space	切换选择（多选面板）
x	终止选中的后台任务
Ctrl+O	查看思考详情面板

当终端显示「Thinking」指示时，按 Ctrl+O 可以打开完整推理内容，再按一次退出。排查它为什么给出某个结论时，这个面板很有用。

注意事项

• Node.js 版本是硬门槛：低于 18.20 无法正常安装或运行，先升级再排查其他问题。
• 原生安装器仍是 Beta：它免去 Node.js 依赖、安装更快，但稳定性尚未与 npm 方式等同，团队统一部署前先小范围验证。
• -p 与 -y 要配对使用：单次执行涉及文件访问或命令执行时，缺 -y 会因无法授权而中断；这是最常见的失败原因之一。
• -y 不是万能放行：仅加 -y 时，HIGH / CRITICAL 级别的危险命令仍可能要求确认。真正不询问需要 CODEBUDDY_IS_SANDBOX=1 配合，且属于高危用法，只在隔离沙箱中使用。
• 启动目录决定工作范围：在错误的目录启动，/init 建立的就是错误的上下文，后续建议也会跟着偏。
• 结构大改后要重新初始化：先 /clear 再 /init，避免在过期认知上继续对话。
• 登录方式与可用模型相关：不同站点支持的模型范围不同，企业用户需要企业提供的服务地址。具体可用范围、配额与计费以官网当前信息为准。
• 批量改动前保持工作区干净：项目级重构、批量补测试这类任务改动面大，先提交或暂存现有改动，执行后逐项检查 diff。