CodeBuddy 使用指南：腾讯云代码助手怎么用
最后更新：2026-09-09
本主题要回答的问题
- CodeBuddy（腾讯云代码助手）到底是什么？它和普通的代码补全、和 ChatGPT 式问答有什么本质区别？
- 它在一个真实工程里是怎么"读懂项目、遵守规矩、自己动手"的？
CODEBUDDY.md、.codebuddy/skills/这些目录各自扮演什么角色？ - 同属腾讯 AI Agent 家族的 WorkBuddy 和它是什么关系？实际选型时该用哪一个？
这个主题域里已有不少讲"通用 Coding Agent 原理"的文章——Coding Agent 工作原理讲任意 Agent 内部的 LLM + 工具 + Plan-Act 循环，我们的技术栈讲团队那套 Cline/Claude Code + 火山方舟的配置。这篇不重复抽象原理，只聚焦一个具体产品：CodeBuddy 是什么、能力边界在哪、在本仓库里怎么被真正用起来。姊妹篇 WorkBuddy 使用指南讲它那位"面向全岗位"的兄弟产品，建议对照着读。
一、CodeBuddy 是什么：先给一个准确的定位
CodeBuddy 是腾讯云推出的 AI 编程助手，官方一句话定位是"AI 时代的智能编程伙伴"。需要先纠正一个常见误解：它不是一个"更强的 Tab 补全"，也不是一个套壳聊天框，而是一个能理解整个项目、能调用工具、能在你授权下自主完成多步任务的 Coding Agent（编码智能体）。
把它放到本主题域反复使用的"AI 编程工具四级演化"坐标里，CodeBuddy 横跨了 L2 到 L4：
| 级别 | 形态 | CodeBuddy 对应的能力 |
|---|---|---|
| L1 代码补全 | 按 Tab 接受下一行 | 行内/多行补全（Inline Completion） |
| L2 对话式编码 | Chat 窗口里问代码 | 智能问答、解释代码、生成函数、写单测 |
| L3 文件级 Agent | 理解项目、改文件、跑命令 | 对话式 Agent：读多文件、改代码、执行命令并自我修正 |
| L4 自主 Agent | 终端/独立环境完成任务链 | Craft 智能体：一句话下发目标，自主规划并交付结果 |
也就是说，同一个产品里同时装着"补全的手""问答的嘴"和"自主干活的 Agent"。它的价值密度集中在 L3/L4——你描述"要什么"，它负责摸索"怎么做"，这也正是 AI 编程工具导读给整套范式下的定义。
产品形态上，CodeBuddy 主要通过 IDE 插件（嵌入主流编辑器，在你熟悉的开发环境里工作）与独立 AI 代码编辑器提供；其文档体系（workbuddy.ai 的 CodeBuddy 文档）也列出了 IDE / CLI 两个入口。具体的版本号、上架渠道与菜单名称会随官方迭代变化，安装时以 腾讯云代码助手官网与官方文档的当期说明为准——这类产品迭代极快，把某个按钮位置写死在文章里，几个月后就会误导人，所以本文只钉稳定的能力与机制，不钉易变的 UI。
模型层面，CodeBuddy 背后是腾讯的代码大模型能力（混元系列等），并在智能体场景支持多模型协同/切换。对使用者来说，不必纠结底层路由到哪个模型，真正决定效果的是你给的项目上下文和约束是否清晰——这正是下面两节的重点。
二、核心能力拆解：它到底能干哪些活
抛开营销话术，把 CodeBuddy 这类编码 Agent 的能力按"和代码的距离"从近到远排开，共有六块。每一块解决的问题不同，使用姿势也不同。
| 能力 | 解决什么 | 典型触发方式 | 你要做的事 |
|---|---|---|---|
| 代码补全 | 写下一行/下一段，减少机械输入 | 写代码时自动出现，Tab 接受 | 保持上下文清晰，写好前几行引导 |
| 智能问答 | 解释陌生代码、给方案、查 API | Chat 面板直接问 | 用 @ 引用具体文件/符号，别让它盲猜 |
| Craft 智能体 | 一句话目标，自主完成多文件改动 | 选中 Craft/Agent 模式下发任务 | 先讲清目标、范围、约束与验收标准 |
| 代码评审/单测 | 找缺陷、提改进、补测试 | 对某次 diff 或某文件发起 | 提供团队规范，结论仍需人工把关 |
| 知识库 / Codebase | 让回答基于你的私有代码与文档 | 关联仓库/知识库 | 控制纳入范围，注意敏感代码边界 |
| 工具扩展（MCP） | 接上数据库、接口、内部平台等外部能力 | 配置 MCP Server | 最小授权，只开任务必需的工具 |
这里最值得展开的是 Craft 智能体。它体现了 Agent 与"补全/问答"的代差：你给的是一个目标（比如"把这个 VitePress 站所有 PlantUML 块做一次语法体检，输出坏块清单"），它会自己把目标拆成步骤——读脚本、扫全仓 .md、抽取 @startuml…@enduml 代码块、调用本地 plantuml.jar 渲染、解析 stderr、生成 JSON 报告——中间可能失败重试、可能回来读更多文件，最后只把结论交给你。这条"理解 → 规划 → 调用工具执行 → 观察结果 → 再规划"的回路，就是 Coding Agent 工作原理里讲的 Plan-Act 循环；Craft 只是这套循环在 CodeBuddy 产品里的名字。
MCP（Model Context Protocol，模型上下文协议） 是另一块容易被忽略但很关键的能力。可以把它理解成"AI 世界的 USB-C / TCP-IP"：只要外部工具按 MCP 标准封装一次，任何支持 MCP 的 Agent（CodeBuddy、Claude Code、Cline 等）都能即插即用，不必为每个客户端单独写插件。协议细节在 MCP 协议里，这里只要记住：MCP 决定了 Agent"手能伸多长"——没接 MCP 时它只能读写你本地文件；接上数据库 MCP 它能查表，接上内部发布平台 MCP 它能触发发布（所以授权必须格外谨慎）。
三、它凭什么"懂"你的项目：CODEBUDDY.md 与三层上下文
很多人用 AI 编程助手的第一感受是"时灵时不灵"，根子往往不在模型，而在上下文。模型本身不知道你这个项目用什么框架、目录怎么分、哪条命令不能乱碰。CodeBuddy 解决这个问题的核心约定，是项目根目录的 CODEBUDDY.md——它等价于 Claude Code 世界里的 CLAUDE.md、Cursor 世界里的 Rules，是你写给 AI 的"入职培训手册 / 项目记忆"。写法上完全可以照搬 CLAUDE.md 编写指南的方法论，那份指南里连 .codebuddy/rules/ 的拆目录结构都是现成的。
一个成熟工程里，喂给 Agent 的上下文其实分三层，理解这三层就理解了为什么"同样的模型，不同项目效果天差地别"：
| 层 | 载体 | 何时加载 | 放什么 | 本仓库对应物 |
|---|---|---|---|---|
| 常驻规则 | CODEBUDDY.md / CLAUDE.md | 每次会话自动加载 | 每次都必须知道的事实与红线 | 根目录 CODEBUDDY.md（约 190 行） |
| 细分规则 | .codebuddy/rules/*.md | 按主题组织、被索引引用 | 编码风格、Git 流程等可拆分长规则 | 指南中给出的 coding-style.md 等 |
| 技能包 | .codebuddy/skills/<name>/SKILL.md | 命中任务时才加载全文 | 某类专活的标准作业流程（SOP） | .codebuddy/skills/site-publish/、traffic-report-30d/ |
这三层的分工，正是 Agent 与 Skill 分工模型的核心结论：常驻规则回答"你需要知道什么"，Skill 回答"这件事怎么做"，Agent 回答"谁来独立做这件事"。把每次对话都用得上的东西塞进 CODEBUDDY.md（否则白占上下文窗口），把流程很长但不常用的操作手册做成 Skill（用到才加载，省 token），是回报率最高的一条配置原则。
以本仓库的 CODEBUDDY.md 为例，它之所以能让 Agent"一上来就像老员工"，是因为里面写的全是模型最容易猜错、且猜错代价很大的硬事实，而不是正确的废话：
- 项目是什么：一个 Linux CPU 性能剖析中文知识库，VitePress 构建；新增正文必须中文，代码标识符保持英文。
- 常用命令：
make run、npm run check:links、npm run build各自做什么。 - 目录约定：
tools/讲工具用法、concepts/讲原理、demos/放可运行实验，避免 Agent 把文件放错位置。 - 写作规范：PlantUML 图 + 对比表 + 末尾"一句话总结"、篇幅档位、配色统一、术语首现给全称。
- 环境事实：本机没有 python、node 不在系统 PATH 而在某个特定目录、跑构建要设
--max-old-space-size=8192。 - 行为红线：没有用户当次明确下令，绝不执行构建/部署——这条我们下一节细讲。
对比一下"没写好"的项目记忆长什么样：满篇"代码要优雅、要注重性能、要有注释"。这些话模型本来就知道，写了等于没写；真正值钱的是"这个项目、这台机器、这个团队才有的特殊信息"。
四、Skill：把一次踩坑，沉淀成以后每次都对的流程
如果说 CODEBUDDY.md 是"宪法"，Skill（技能包）就是某道具体工序的操作手册。它是一个带 YAML 头（name / description / updated）的 SKILL.md，可选地自带脚本与模板，放进 .codebuddy/skills/<名称>/。最精妙的设计是渐进式披露：会话启动时 Agent 只加载每个 Skill 的一句 description（约几十个 token），等用户的话匹配到某个技能，才把整篇手册读进来。这样你可以沉淀几十上百个技能，却不会撑爆日常对话的上下文。
本仓库目前就真实沉淀了两个 Skill，它们特别能说明"什么东西值得做成技能"：
| Skill | 触发场景 | 把什么经验固化了下来 |
|---|---|---|
site-publish | "部署 / 发布 / 上线 / 更新线上" | 本地构建→站内搜索索引→sitemap→打包→免密预检→字节比对→服务器校验→快照→rsync→健康检查的完整 SOP，以及"禁止服务端构建、禁止手跑 rsync --delete"等红线 |
traffic-report-30d | "分析最近 30 天流量 / 出一份流量报告" | 拉日志、按日志内时间过滤窗口、UA 分类器、用分析后台交叉核对真人流量、多节报告结构、脱敏要求 |
为什么这两件事必须做成 Skill，而不是每次口头交代？因为它们都具备三个特征：流程长（十几步）、不常做（不会天天部署）、错一次代价大（空源 rsync 能清空线上）。把它们写成手册后，新人（或新的 AI 会话）不必重新踩坑。以 site-publish 为例，它把一次真实事故的教训固化成了机器会遵守的步骤：一台内存偏小的服务器跑不动需要大堆内存的构建，所以构建只能在本地做，服务器只接收产物包；rsync --delete 最怕用空源清空线上，于是脚本在触碰线上目录前设了"压缩包校验 → 独立暂存 → 文件数量校验 → 回滚快照"四道闸，任一不过就中止、线上原封不动。
一个 Skill 通常包含四块内容，照着写就行：
- 何时使用：列出触发说法（"部署""上线""deploy"……），这是 Agent 判断要不要加载它的依据，描述里的触发词要贴近真实口语。
- 红线/铁律：先讲不能做什么（脱敏、禁止高危动作、需用户授权的边界）。
- 环境速查表：脚本路径、服务器占位符、产物位置、关键环境变量——只放脱敏占位符，真实凭据走会话记忆，绝不入库。
- 标准流程 + 常见坑表：正常路径一步步怎么做，再附一张"坑→表现→处理"对照表。
值得强调的是脱敏纪律：这两个 Skill 都随公开仓库提交，所以里面一律用 <user>@<server>、<sudo_pass> 这类占位符，真实地址、账号、口令只存在 AI 的会话记忆里，执行时代入。服务器 IP 不进 git——这条和整个仓库的合规要求一致。
五、安全边界：能力越强，越要给 Agent 装刹车
一个能读写文件、能跑终端命令的 Agent，本质上握着你这台机器的很大一部分权限。CodeBuddy 这类产品通常用"人在回路（Human-in-the-loop）审批 + 工作区隔离 + 日志可追溯"来兜底，但工具只是机制，真正的安全来自你把规矩写清楚。本仓库的实践是把刹车直接焊死在 CODEBUDDY.md 的"红线"条款里，摘录其精神如下：
- 读文件、分析、常规修改直接做，不要反复求确认；全部改完后统一汇总变更。避免把 Agent 调成"每步都问"，那样人会疲劳到无脑点同意，审批反而失效。
- 只有高危场景才必须停下：删除大量文件、执行破坏性命令、大范围重构、架构上有多种实质不同方案。
- 构建/部署是单独的最高级授权：没有用户当次明确下令，绝不执行
npm run build、部署脚本、向服务器 rsync 等动作；"改完顺手发一版""顺便构建验证下"也算违规。内容编辑和git add/commit/push不属于部署，可正常进行。
最后这条值得多说一句。对普通项目"顺手 build 一下"或许无妨，但在一个构建吃 4GB 内存、部署连着线上服务器的环境里，一次未经授权的构建可能拖垮机器，一次手滑的 rsync 可能清空线上。把"哪些动作永远不能自作主张"写成显式红线，比指望模型每次都判断正确可靠得多。
| 风险动作 | 为什么危险 | 本仓库的做法 |
|---|---|---|
| 自主执行部署/发布 | 直接影响线上，难撤回 | 红线：必须用户当次明确下令 |
| 服务端构建 | 3.7GB 内存跑 4GB 堆，OOM 并挤占线上业务 | 只允许本地构建，服务器只收产物 |
rsync --delete 空源 | 可瞬间清空线上目录 | 禁止手工执行，只能走带闸门与快照的脚本 |
| 凭据入库 | 公开仓库泄露服务器/密钥 | 一律占位符，凭据走会话记忆 |
| 全库无边界扫描 | 800+ 文档、上万产物文件，浪费且误读 | 精确路径引用，排除 node_modules/dist/cache |
这套"默认放手常规操作、硬性锁定高危操作"的分寸，和 VSCode 三剑客实战手册里讲的审批模式选择是同一个思路：审批不是越多越安全，而是要加在真正不可逆的那几类动作上。
六、落地工作流：把 Agent 用对的六步法
工具再强，没有稳定用法也会"看天吃饭"。结合本主题域的 标准工作流 SOP 与本仓库实践，用 CodeBuddy 完成一个真实任务建议走这六步：
第 2 步的"对齐目标"是分水岭。一个好任务描述应当包含 **Context（背景在哪做）+ Task（具体做什么）+ Constraint（约束与验收）**三要素，这正是 Prompt 方法论里 ROI 最高的结论。与其反复喊"好好写"，不如直接把 CODEBUDDY.md、相关文件路径、"不许碰部署"这类约束摆给它。第 3 步对复杂改动尤其重要：先让它出方案、你确认方向，再放权执行，成本远低于让它闷头改完二十个文件再返工。
七、横向对比：CodeBuddy、WorkBuddy 与其他 Agent 怎么选
腾讯这一波 AI Agent 是"兄弟连"布局：CodeBuddy 面向开发者、扎根代码场景；WorkBuddy 面向全岗位、是覆盖办公/代码/设计的桌面工作台（后者详解见姊妹篇 WorkBuddy 使用指南）。再放到更宽的市场里看：
| 维度 | CodeBuddy | WorkBuddy | Claude Code | Cursor / Windsurf |
|---|---|---|---|---|
| 厂商 | 腾讯云 | 腾讯 | Anthropic | Anysphere / 前 Codeium |
| 主要用户 | 开发者 | 全岗位（含开发者） | 开发者 | 开发者 |
| 主战场 | 编码、评审、仓库级 Agent | 文档/表格/PPT/数据/调研 + 代码 + 设计 | 终端里的自主编码 | AI-Native IDE 内编码 |
| 典型形态 | IDE 插件 / 独立 AI 编辑器 / CLI | 桌面工作台 + 云端托管 + 移动端遥控 | 终端 CLI | 独立 IDE（VS Code fork） |
| 项目记忆 | CODEBUDDY.md / rules / skills | 记忆 + 专家 + Skill | CLAUDE.md / agents / skills | .cursorrules / Rules |
| 长任务 | Agent 模式 | 云端 7×24 托管，关机也能跑 | 本地/终端进程 | 本地 IDE 进程 |
选型其实不复杂：纯研发提效、希望 AI 深扎在 IDE 与代码库里，选 CodeBuddy 这一类编码 Agent；需要让"不会写代码的同事"也能一句话交付文档/表格/PPT，或要云端长时间托管任务、移动端随时遥控，选 WorkBuddy。两者并不互斥——同一条 AI Agent 家族体系，记忆/Skill/连接器的理念相通，开发岗完全可以"写代码用 CodeBuddy、做周报和数据汇报用 WorkBuddy"。和 Claude Code、Cursor 的取舍，则更多看你习惯在终端还是 IDE 里工作，以及模型供给与合规要求，这部分的通用判断框架见 AI 编程工具导读。
八、用好它的几条实践与常见疑问
- 先投资项目记忆，再钻研提示词：花二十分钟把
CODEBUDDY.md写扎实，后面每次对话都受益。只写"本项目特有、模型易猜错"的事实，不写正确的废话。 - 用
@给精确上下文：问某个函数就引用那个文件，别让它全库盲扫；大仓库里无边界搜索既慢又容易带偏。 - 把高频踩坑沉淀成 Skill：凡是"流程长、不常做、错了代价大"的操作（部署、出报告），写成带红线和常见坑表的技能包。
- 权限最小化：MCP 工具按需开启，凭据不入库，高危动作走人工审批与 git 快照双保险。
- 把它当聪明但需要管理的初级同事：目标要清楚、过程要抽检、结果要验收，而不是当全自动黑盒。
| 常见疑问 | 简答 |
|---|---|
| CodeBuddy 会不会把我的私有代码上传？ | 代码补全/问答需要把相关上下文发给模型服务；敏感仓库应先看清当期官方的数据与隐私政策，知识库纳入范围可控，必要时用企业版/私有化方案。 |
| 装了它就不需要会写代码了吗 | 不会。它放大的是"你判断和验收的能力"，不懂基础的人无法判断它给的方案对不对，更容易接受貌似合理的错误。 |
CODEBUDDY.md 和 CLAUDE.md 写哪个 | 理念与结构完全一致；主用 CodeBuddy 就维护 CODEBUDDY.md，两个客户端都用时保持内容同步即可。 |
| 改了规则要重启吗 | 一般下次新会话或上下文重载即生效，不必重启整个 IDE。 |
与本主题其他文档的关系
| 文档 | 关系 |
|---|---|
| AI 编程工具导读 | CodeBuddy 在四级演化与选型矩阵中的位置 |
| Coding Agent 工作原理 | Craft 背后的 LLM + 工具 + Plan-Act 通用原理 |
| CLAUDE.md 编写指南 | CODEBUDDY.md 的完整写法，两者同构 |
| Agent vs Skill | 常驻规则 / Skill / Agent 的三层分工 |
| MCP 协议 | Agent 接外部工具的标准总线 |
| WorkBuddy 使用指南 | 腾讯 AI Agent 家族里面向全岗位的兄弟产品 |
一句话总结
CodeBuddy 的本质是一个扎根在你代码库里的编码智能体：补全和问答只是表层，真正拉开差距的是 Craft 式的自主规划执行，而它"懂不懂你的项目、守不守规矩"，取决于你有没有用
CODEBUDDY.md把项目事实讲清、用 Skill 把高风险流程固化、用审批红线把不可逆动作锁死——模型决定下限，你的上下文工程决定上限。