ARTICLE · 1090369

CodeBuddy 实操指南(从安装到跑通一个功能)

发布时间：2026-09-28 11:52:07 最近访问：2026-09-28 11:51:19

上一篇讲了 AI Coding 的方法论，这篇全是实操：从下载 CodeBuddy IDE、登录、把项目打开，到用 AI 真的搭出一个能跑的功能，最后部署成一条能发给别人的链接。案例用我自己在做的项目 DataViewAgent，全程真实记录。

01｜CodeBuddy 是什么

CodeBuddy 是腾讯的 AI 编程工具，也是国内生态里我用得最多的一个。它有三种形态，官方给的定位很清楚：

CodeBuddy IDE——产设研一体的工作台，主打「对话即编程」，官方标明的适用人群里就有编程初学者；
CodeBuddy 插件——装进 VS Code、JetBrains 这类 IDE 里，AI 打辅助，适合日常编码的开发者；
CodeBuddy Code——命令行工具，任务编排能力强，面向 DevOps、运维、SRE 和资深开发者。

这篇全程用 IDE 版。它可以把需求澄清、方案、代码、预览、部署放在同一个界面里，不用你在三个工具之间来回搬东西——对刚上手的人来说，门槛明显更低。国内网络直接可用、有免费额度，这一点和海外工具的差别很现实。

案例项目是一个「对话生成数据大屏」的平台：前端用 Vue 3 负责渲染，中间一层用 Node 管 AI 编排，后端用 Spring Boot 算指标，属于中等复杂度的真实工程。

我在 IDE 里打开的就是它。先感受一下这个界面——左边是项目文件树，中间是代码区，右边那块是后面要一直用的对话面板：

02｜第一步：下载、安装、登录

先看环境要求，不满足会直接启动不了：macOS 11（Big Sur）及以上；Windows 10 及以上（不支持 Win 7 / 8 / 8.1）。

下载：访问 CodeBuddy CN 官网（https://www.codebuddy.cn/ide/），按你电脑的处理器选对应版本。

安装：

macOS：把安装包拖进 Applications 就行；
Windows：双击安装包 → 选「确定」（只为当前用户安装）→ 勾「我同意此协议」→ 选安装位置 → 一路「下一步」。

更新：还是右上角那个账户图标 → 菜单里选「检查更新」；有新版本时左下角会推送，点「立即安装」。

03｜第二步：把一个项目放进来

登录之后先看到的是欢迎页。它上面并排放着两块东西，别选错：

编程模式——让 Agent 参与构建与交付代码，就是这篇要用的，下面那三个入口都属于它；
工作模式——AI 原生工作台，把目标委托给多个 Agent 并行执行，不用项目初始化就能开工。写文档、查资料、做分析这类没有代码仓库的活，走这一块更合适。

这篇全程走编程模式。 这个面板里有三种方式把项目放进来：

新建文件夹：在系统用户目录里创建一个新项目（完全从零时用这个）；
打开文件夹：打开本地已经有的项目；
克隆 Git 仓库：填仓库 URL 拉下来（需要先装 Git，可以在终端跑 git --version 确认）。

给新手一个建议：先在系统里自己建一个空文件夹，再用「打开文件夹」把它选中。 目录在哪、叫什么，你心里得有数——直接让它替你决定位置，过两天你自己都找不着。

项目进来之后，界面分三块：

左边栏——项目结构和搜索，改哪个文件就从这儿点进去；
右上角——对话窗口的开关，也就是你后面和 AI 干活的地方；
下方栏——终端、控制台和问题输出，跑命令、看报错都在这儿。

04｜第三步：学会用 @ 喂上下文

在对话框里敲 @（或者点 @ 按钮），会弹出上下文类型列表，上下方向键浏览、回车选中。菜单里能选的一共五类：

@Files & Folders——文件或文件夹，选中文件夹会给路径加内容概览。平时用得最多的一类；
@Git——写 @Git:uncommitted 是未提交的改动，@Git:commit:abc123 是某个历史提交；
@Docs——技术文档，内置了一批常用框架和库，也可以自己加知识库；
@Terminal——终端最近执行的命令和输出，报错了把现场直接给它；
@Rules——项目的编码规范，让它按你们定的规矩写（官方说明目前只支持「手动」类型的规则）。

选完类型还要继续选具体内容。比如点 File & Folders，它会列出项目里的文件，你接着敲文件名往下筛：

官方文档里还有第六类 @Code，但它不在这个菜单里——它是「精确到函数、类」的那一类，用法是在编辑器里选中一段代码，再点自动弹出的「添加到对话」，或者右键选同一项：

三条官方使用要点，既省事又省钱：

@ 过的内容会一直留在对话上下文里，不用每条消息重复 @ 同一个文件；
从侧边栏把文件拖进对话框，或者右键选「添加到 CodeBuddy 对话」，效果和 @ 一样；
官方明确不建议 @整个项目文件夹，要像 @src/auth/login.ts 这样精准引用。

拿 DataViewAgent 举个真实的对比。项目里有个「热力图」组件，到现在还是个空壳——整个文件只有 32 行，里面只留了一句「第二步还没做」的注释。我想把它补完，两种问法：

❌「帮我实现大屏的热力图组件」
✅「@热力图组件 @仪表盘组件 @组件注册表这是 DataViewAgent 的 Vue 3 前端。渲染组件有三条硬规矩：不取数（数据全部由外部传入）、不写死颜色（只用主题令牌）、不额外做统一出口。请参照已经做好的仪表盘，把热力图渲染补上。先给方案，不要写代码。」

差别在哪？❌ 那句，AI 只能猜你的项目长什么样——它可能自己跑去请求数据、可能写死一个颜色值、可能顺手多建一层导出文件。这三条，恰好每一条都踩在这个工程的红线上。✅ 挂上真实的两个组件和注册表之后，AI 读的是你已经跑通的代码，照着抄就行。

（@ 后面实际要写完整文件路径，上面为便于阅读只写了组件名。）

猜，就是幻觉的来源。

05｜第四步：用 Plan Mode，先审方案再动手

IDE 里有两个写作模式，别搞混：

Plan Mode：先规划后执行，动代码之前先把方案摆给你看；
Craft Mode：直接执行，响应快，适合局部修改和 Bug 修复。

官方给的判断法则很干脆：架构级改动用 Plan，细节级调整用 Craft。 手头没把握的活，一律先用 Plan。Plan Mode 从侧栏进入，那里能看到已保存的计划列表，也能新建计划。

一次 Plan 协作被拆成五步：

需求澄清（Prepare）——你描述目标，AI 会提 1~2 个关键问题（技术栈、功能范围、限制条件），你回答；反过来问你，是它这一步的正常行为；
方案制定（Prepare）——它在你项目里搜相关的代码、设计、文档，然后生成方案草稿；
方案编辑 / 确认（Ready）——改就在这里改：正文、技术方案、任务列表都能直接编辑；
方案实施（Building）——点执行按钮，按任务列表一步步做，进度实时可见，随时能暂停改方向；
方案完成（Finished）——计划自动存成 Markdown，能下载、能分享、能当上下文复用。

第三步的界面长这样：右边是方案正文，上面那一小块是任务列表——这时候它还一条都没执行：

（我这份版本上开始执行的按钮写的是「构建」，官方文档里叫「开始执行」——同一个东西，别被字样绕住。）

方案里一共五块：需求分析、技术方案、视觉设计、任务列表（标明依赖关系和优先级）、推荐的扩展能力（MCP、Skill、SubAgent）。

动手之前，官方给了四个检查项，照着过一遍就行：技术方案符不符合项目现有架构？任务拆解完不完整、依赖顺序对不对？设计规范跟现有 UI 风格一致吗？选的扩展能力合不合理？

这就是上一节那句「先给方案」实际产出的东西。我在 DataViewAgent 里补那个热力图组件时，Plan Mode 列出的五条任务，每条都标着状态和依赖关系：先补数据转换、先收紧颜色契约，这两条是并行的前置；渲染要等它俩做完；渲染做完才轮到验证；验证过了才是文档归档。任务不是平铺的清单，是一条有先后顺序的链——这也正是它敢自动往下跑的前提。

真正值钱的是方案里另外两段。

第一段，它在写代码之前先揪出一个契约漏洞。 那一段的小标题是「色带契约：把 colorRamp 收紧为固定的语义色名」。项目规范里明明写着「颜色只能取主题令牌、不许从数据里读色值」，但数据里 colorRamp 这个参数是个没有任何约束的数组，模型完全可以随手填两个色值进去。两条规则打架，而且谁都不会报错——图就是颜色不对而已，这种问题最难查。所以它的第一步不是写渲染，是先把契约从「随便填」收紧成「只能填五个预设的语义色名」。

第二段更细：它顺手排除了一个看着最合适、实际会静默失效的选项。accent 这个色名在代码里有映射，看起来该进白名单；但它查下来——六个主题里没有一个定义过对应的颜色变量。一旦放进去，图表会读到一个空色值，然后静默画不出来。所以白名单里刻意不写它，并把这条落差如实记进「遗留」。

这两处都不是「AI 写出了什么」，而是「AI 在动手前先拦住了什么」。

顺带还有两件事值得记一笔：

它在「执行注意」里主动划了边界——项目里另一个图表组件有一模一样的写死颜色问题，但它写着「重构跟需求分开，另立任务」，这次不碰；
它在「验证方式」里如实写了落差：目前没有任何指标会产出「行×列」的二维数据，所以真实大屏上这个热力图只会落空态，要看到真东西还得先补一个产出数据的指标逻辑。

审方案这一步，就是你花 30 秒能省 3 小时返工的地方。 五个任务跑完之后，同一块面板会变成这样：

还有一个容易被忽略的实用点：计划完成后会自动存进项目里的 .codebuddy/plans/ 目录。上面那两份计划就躺在这儿：

历史计划可以当上下文引用，新对话里挂上它，AI 立刻知道你的架构和规范，不用你重复解释一遍。

06｜第五步：7 个斜杠命令 + 项目规则

在对话框里敲 /，会弹出一份指令列表。官方口径是内置 7 个，只在输入框为空时出现，而且一条消息只能用一个：

/init——初始化项目结构，并生成 CODEBUDDY.md 配置文件；
/rules——按项目情况自动生成代码规范、命名规范、Git 提交规范这些文件；
/explain——用大白话讲清一段代码到底怎么工作的；
/fix——自动识别并修复 bug、编译错误、类型错误、逻辑错误；
/tests——生成单元测试，正常场景、边界条件、异常情况三类都给；
/cr——代码审查，查规范性、性能、安全、可维护性；
/summarize——对话太长时压缩上下文。官方建议把上下文控制在 100K 以内。

同一个列表里还能建自定义斜杠指令，把团队固定的流程封成一条命令。

（补一句实测：我这份版本敲 / 出来的列表里是 8 条，比官方文档多一条 help——那是看帮助的入口，不算开发流程里的指令。数量对上就行，不用纠结。）

然后是规则——这是新手最容易漏、但收益最大的一步。 CodeBuddy 的项目规则有两层：

CODEBUDDY.md：放在项目根目录的纯 Markdown，默认全文进上下文。这里有个官方兼容设计很关键——根目录有 AGENTS.md 而没有 CODEBUDDY.md 时，它会自动加载 AGENTS.md 的全文；
.codebuddy/rules/：更结构化的规则，进版本控制、跟团队共享，有三种生效方式——总是（每个会话都加载全文，放核心编码规范和架构约束）、智能体请求（只加载名称和描述，AI 判断相关了再读原文，适合文档和参考资料）、手动（要用 @规则名 才生效，放可选的最佳实践）。

官方的最佳实践也直接抄走：单条规则控制在 500 行以内，设成「总是」的核心规范只留 3~5 个，其余走「智能体请求」或「手动」。规则改完要新建对话才生效——规则只在会话开头注入一次。

DataViewAgent 走的就是这条路：仓库根目录放了一份 AGENTS.md，一万八千多字，写着三块代码各自的职责、五条工程红线、「禁止兜底、禁止兼容」这些约定，还带一张「改什么 → 动哪里」的对照表：

挂了它之后，即使我某次忘了 @ 某个文件，AI 也不会顺手写一段「取不到就用默认值」把失败糊过去。规则能在面板里集中管理和切换：

07｜从零到一：一个真实功能是怎么跑通的

把前面几步串起来。新项目和存量项目，区别只在前两步：

新项目：自己建个空文件夹 → 「打开文件夹」选中它 → 从需求开始走 Plan；
存量项目：直接「打开文件夹」→ 用 @ 挂上关键文件 → Plan 会先摸清现状再给方案。

下面这段是存量项目的真实流程——给 DataViewAgent 的顶栏加一个「账号下拉菜单」（个人中心 / 设置 / 管理入口 / 退出登录）：

进项目：「打开文件夹」选中 DataViewAgent，打开右侧聊天窗口；
喂上下文：@ 上顶栏目录、全局样式表、用户状态、路由配置四样东西，再补一句「这是 Vue 3 + TS + Pinia 工程，浮层按项目里现成的下拉组件惯例做（组件内自己存开关状态 + 点击页面别处关闭 + Esc 关闭），样式统一写在全局样式表里，不要在组件里另开一段」；
切 Plan Mode，下指令：「新增顶栏账号下拉菜单：个人中心 / 设置 / 管理入口（仅管理员）/ 退出登录；要支持键盘操作和读屏，窄屏只显示头像。」——它会先反问你 1~2 个问题（管理入口对哪些角色可见、退出要不要二次确认），然后列出要新建的组件、要改的顶栏、样式表、图标表和路由配置，再加上新开一个「个人中心」页面；
审方案：对着官方那四个检查项过一遍，重点补三件事——键盘可达性（Esc 关闭后焦点要还回触发按钮）、退出登录的二次确认，以及它在方案里就揪出来的「影院模式冲突」：大屏查看页会按鼠标位置自动隐藏顶栏，而隐藏态的顶栏不接收鼠标事件，菜单一旦伸到顶部就会点不动。它连解法都给了——菜单打开期间给页面根节点打个标记，让顶栏保持展开。改完点执行；
收尾：用 /cr 过一遍本次变更，再跑一遍类型检查，然后到浏览器里做验证——1440 / 1340 / 1080 / 980 / 760 五档窗口各看一遍，确认面板右缘不溢出、窄屏下每个条目高度不低于 44 像素；再用键盘从触发按钮一路 Tab 进去、上下选、回车确认、Esc 关闭，确认焦点能正确归还。哪里报错，/fix 顶上。

这是带键盘导航、读屏属性、响应式断点、危险操作二次确认的完整控件。 跑出来的菜单是这样：

08｜跑通之后：一键部署，拿到能分享的链接

代码在自己电脑上跑起来，只有你一个人看得见。IDE 的「集成」面板里内置了四个部署入口，官方的选型建议很直白：

Cloud Studio——临时预览、快速演示。即时部署、不用域名，发布到云端沙箱后给你一条可公开访问的临时地址（有有效期），不适合生产；
EdgeOne Makers——纯静态网站和前端应用。全球 CDN 加速、自动 CI/CD、免费 HTTPS，适合个人博客、官网、单页应用；
CloudBase——前后端一体化项目。要用户认证和数据库、需要开发/测试/生产环境隔离时用它；
Tencent Lighthouse——全栈应用。需要完整服务器控制权、要跑非静态的后端服务时选它。