0. 学前须知

来源：CodeBuddy

先解决一个误会

你在网上搜"CodeBuddy"，会看到三种完全不同的东西：一个装进 VS Code 的插件、一个独立的开发软件、一个在终端里敲命令的工具。

它们都叫 CodeBuddy，都是腾讯出的，但确实是三个不同的产品。

这不是营销上的混乱，是有意的设计——三种形态覆盖三种人。但如果你在不知道这件事的情况下开始用，很容易出现"我装了半天，怎么跟教程里长得不一样"这种问题。

所以这一章先把这件事讲清楚。

三种形态，一句话一个

形态	它是什么	长什么样
CodeBuddy 插件	装进你现有编辑器的插件	VS Code、JetBrains 系列里多一个侧边栏
CodeBuddy IDE	一个独立的桌面开发环境	单独安装的软件，打开就是它的界面
CodeBuddy Code	终端里的命令行工具	在终端敲 codebuddy，进入一个对话界面

再往下说一层，它们的定位差别很大：

插件版——你还是你，编辑器还是那个编辑器，它只是在旁边帮你补全代码、回答问题、改个 bug。传统模式下"人主导、AI 打辅助"。适合本来就天天写代码的开发者。

IDE 版——主打"对话即编程"。你不写代码，你描述需求，它从需求规划、设计、写代码一直做到部署。官方定位是"产品—设计—研发—部署"一体化，还带可视化调试和设计稿转代码。完全不懂编程的人也能从这里入门。

CLI 版（CodeBuddy Code）——本教程的主角。它在你的终端里运行，能读文件、跑命令、操作 Git、访问网络，还能接进自动化流水线。适合习惯命令行的人、需要批量处理的人、要把它塞进 CI/CD 的人。

为什么这套教程选 CLI

三个理由。

第一，它是能力最完整的一个。 插件只能在编辑器里活动；CLI 能碰的东西是系统级的——你的文件、你的命令、你的 Git 仓库、你的网络。批量处理两百个文件、给整个项目做重构、写个脚本让它自己定时跑，这些只有 CLI 顺手。

第二，它最容易被低估。 很多人装了插件就以为"AI 编程就那样"，没意识到终端里还有一个能真正替你干活的东西。

第三，它逼着你养成好习惯。 CLI 会真的执行命令、真的改文件，你不得不学会"先要方案""看完 diff 再收工""先提交再动手"。这些习惯换成任何工具都受用。

至于 IDE 版和插件版，第 12 章会讲，到时候你会发现它们和 CLI 共享同一套记忆和规则文件——学完 CLI 再去用它们，几乎没有额外成本。

**本套教程配套代码：**https://gitee.com/geektime-geekbang_admin/ai-tutorial-material/tree/master/codebuddy-materials

它到底能干什么

说几个具体的，你感受一下：

用说话的方式完成开发任务。 "给我这个项目加上单元测试"、"把这个函数的性能问题找出来"、"把 util 目录下的代码风格统一一下"。它自己去读代码、改代码、跑命令、跑测试。

它是 Unix 工具链的一员。 这一点很多人不知道。它支持管道：

cat error.log | codebuddy -p "分析这些报错，找出根因"
git log --oneline -20 | codebuddy -p "看看这些提交里有没有可疑的"

就像 grep、awk 一样，可以塞进你的脚本里。

它能批量干活。 一个目录下三百个文件要重命名、老项目里所有 class 组件要改函数组件、几十个文件要加统一的错误处理——这类活它最擅长，也是手工做最痛苦的部分。

它能自动化。 因为它是命令行程序，所以可以被 cron 调用、被 CI 流水线调用、被你自己的脚本调用。第 9 章就干这个。

它能扩展。 MCP 可以接外部工具，子代理可以让不同的"专家"分工干活，规则文件可以让它记住你项目的规矩。

说清楚它不干什么

它不会替你做判断。 该不该这么重构、这个方案的风险在哪、这个数据能不能信——这些是你的活。它给的是选项和依据。

它会真的执行命令。 这是 CLI 和对话框最大的区别，也是最大的风险。它会跑 rm、会改文件、会提交 Git。所以"先让它给方案"不是一个建议，是必须。

它不是一次就对的。 第一版不满意是常态。正确做法是接着说哪里不对，而不是推倒重来——它记得前面所有的上下文。

它读到的信息要你把关。 联网查到的东西、对陌生代码的推测，都可能不准。教程里会反复提醒你验一遍。

你需要什么样的基础

这套教程的门槛不高，但你得满足这几条：

• 会在终端里敲命令，知道 cd、ls 是干什么的
• 有自己的电脑，并且愿意在上面装东西
• 知道 Git 是什么（不熟没关系，教程会带着用）
• 能看懂简单的代码。案例用的是 Python，但你不需要会写——看懂大概意思就行

如果你完全没碰过终端，我建议你先花半小时熟悉一下基本命令再回来，不然每个命令都要现查，会很累。

如果你已经是熟练开发者，这套教程对你最有价值的应该是第 4 章（接手陌生仓库）、第 9 章（Git hook 与 CI）、第 10 章（规则与子代理）、**第 11 章（Plan 模式 / 子代理 / Skills / Hooks）**那几章——那些是真正能把日常流程重做一遍的地方。

这门课怎么学

七个案例，就是开发者日常会遇到的七件事：

1. 接手陌生仓库：从 clone 到跑起来
2. 给没测试的项目补上测试
3. 从报错到修复：完整走一次 debug
4. 重构那个没人敢动的臃肿模块
5. 从零做一个小服务并部署上线
6. 把重复活自动化：脚本、hook、CI
7. 让它守规矩：规则、子代理、MCP

不是玩具需求，也不是假想的大企业系统——规模都在个人项目、开源贡献、小团队日常这个量级，你在工作里大概率遇到过。

每个案例你都会带走一个真的能跑的东西。贯穿全程的有三条规矩：动手前先让它给方案、改完先看 diff、每一步都有 Git 兜底。

关于命令的写法

这是本教程的一个规矩，先说明白：

凡是涉及命令的地方，我都会把三个环境分开写——macOS / Linux、Windows PowerShell、WSL2。因为它们的路径写法、环境变量配置方式、定时任务机制都不一样，混着写一定会出问题。

格式长这样：

macOS / Linux

mkdir -p ~/playground && cd ~/playground

Windows PowerShell

New-Item -ItemType Directory -Path "$HOME\playground" -Force
Set-Location "$HOME\playground"

WSL2

# 命令和 Linux 一样，但项目要放在 WSL 自己的文件系统里
mkdir -p ~/playground && cd ~/playground

你只需要看自己那一行。

另外提醒一句：WSL2 是 Windows 里跑 Linux，它的行为跟"Windows PowerShell 原生"是两回事。 如果你分不清自己在哪个环境里，先敲一行 uname -a（macOS/Linux/WSL2 会有输出，PowerShell 里会报错），确认一下再继续。

开始吧

下一章，把它装好。

四个平台我都写了，包括最麻烦的 WSL2。照着敲，中间别跳步——尤其是配置 PATH 那一段，那是新手卡住最多的地方。