Codebuff 简介

Codebuff 是一个开源的 AI 编码助手,它通过自然语言指令来编辑你的代码库。与单一模型不同,Codebuff 协调多个专门的代理,共同理解你的项目并做出精确的修改。

核心数据:Codebuff 在 175+ 个编码任务上的评估结果优于 Claude Code,准确率达到 61% vs 53%。

Codebuff 的工作原理

当你要求 Codebuff "为我的 API 添加身份验证"时,它会调用:

  1. 文件选择代理:扫描代码库以了解架构并找到相关文件
  2. 规划代理:计划需要修改的文件及其顺序
  3. 编辑代理:进行精确的编辑
  4. 审查代理:验证更改

多代理协作架构

用户指令
"添加身份验证"
文件选择代理
扫描代码库
规划代理
制定修改计划
编辑代理
精确修改代码
审查代理
验证变更

为什么选择 Codebuff

精准理解

多代理架构让 Codebuff 能够深入理解项目结构,不像单一模型那样只看到局部代码。

安全编辑

内置审查代理确保每次修改都经过验证,降低引入新 bug 的风险。

开源自托管

完全开源,你可以在自己的环境中运行,代码始终在本地,无需担心数据安全。

Codebuff vs 其他工具

# Codebuff 的独特优势
单一模型工具:
  用户指令 → 模型 → 输出代码
  问题:缺少全局上下文,容易遗漏依赖

Codebuff 多代理:
  用户指令 → 文件选择 → 规划 → 编辑 → 审查
  优势:每一步都有专门的代理负责

单一模型工具往往只能看到你提供的上下文,容易遗漏跨文件的依赖关系。Codebuff 的多代理架构通过分工协作,每个代理专注于一个环节,从全局到细节层层把关。

快速上手:Codebuff 支持所有主流编程语言,无需额外配置。只需要 Node.js 环境即可开始使用。

适用场景

  • 功能开发:描述你想要的功能,Codebuff 自动定位并修改相关文件
  • 漏洞修复:描述问题现象,Codebuff 自动诊断并修复
  • 代码重构:指定重构目标,Codebuff 确保不破坏现有功能
  • 代码审查:让 Codebuff 审查你的改动,提供改进建议
  • 测试编写:为现有代码生成测试用例

性能基准测试

# SWE-bench Lite 基准测试结果
Tool                | Accuracy | Files Modified
--------------------|----------|---------------
Codebuff            | 61.0%    | 1.8 avg
Claude Code         | 53.0%    | 2.3 avg
Aider               | 48.5%    | 2.1 avg
Cursor Agent        | 45.2%    | 2.5 avg
Copilot Workspace   | 42.0%    | 2.8 avg

Codebuff 在 SWE-bench Lite 基准测试中排名第一,准确率 61%,平均每次修改的文件数也更少(1.8 个),说明它更精准地定位到需要修改的文件。

技术架构概览

# Codebuff 技术栈
Language:       TypeScript / Node.js
Agent Model:    Claude Sonnet (默认)
Runtime:        本地 CLI / SDK
Config:         .codebuff/ 目录
Agents:         文件选择 / 规划 / 编辑 / 审查
Extensions:     自定义代理 (.agents/)

Codebuff 使用 TypeScript 构建,默认使用 Claude Sonnet 作为底层模型。你可以通过 .agents/ 目录创建自定义代理来扩展功能。

学习路径提示:本课程将从 Codebuff 的核心概念出发,逐步深入到实践应用和高级主题。学完本课程后,你将能够熟练使用 Codebuff 提升日常开发效率。

Codebuff 的命令行界面

# 安装后即可使用
$ codebuff --help

Usage: codebuff [options] [instruction]

Options:
  --scope <path>     限制操作范围
  --dry-run           预览修改但不实际执行
  --model <model>    指定使用的模型
  --config <file>    指定配置文件路径
  --verbose           显示详细执行日志

Examples:
  codebuff "Add auth middleware"
  codebuff --scope src/api "Fix rate limiting"
  codebuff --dry-run "Refactor database layer"

Codebuff 的 CLI 简洁直观。最常用的选项是 --scope(限制范围)和 --dry-run(预览模式)。建议在大型项目中始终使用 --scope 来控制修改范围。

安全机制详解

本地执行

所有代码处理都在本地完成,你的代码不会上传到云端。API 调用仅用于获取 LLM 推理结果,不传输完整源代码。

变更预览

每次修改都以 diff 格式展示,你可以逐行审核。使用 --dry-run 可以只预览不执行。

Git 集成

Codebuff 会在执行前检查 Git 状态,建议在工作区干净时使用。所有修改都可以通过 Git 轻松撤销。

社区与生态

  • GitHub Stars:Codebuff 在 GitHub 上拥有活跃的开源社区,持续更新迭代
  • 自定义代理市场:社区贡献了大量实用的自定义代理模板
  • 插件系统:通过插件扩展 Codebuff 的功能,支持自定义工具和集成
  • 企业版:提供团队协作、审计日志和企业级支持

Codebuff 安装与环境准备

在开始使用 Codebuff 之前,你需要确保开发环境满足基本要求。Codebuff 基于 Node.js 运行,需要 Node.js 18 或更高版本。

# 检查 Node.js 版本
$ node --version
v20.11.0

# 安装 Codebuff(推荐全局安装)
$ npm install -g codebuff

# 验证安装成功
$ codebuff --version
1.2.0

# 设置 API Key(以 Anthropic 为例)
$ export ANTHROPIC_API_KEY="sk-ant-..."

# 在项目中初始化 Codebuff
$ cd ~/projects/my-app
$ codebuff init
# 生成 .codebuff/ 目录和默认配置

安装过程非常简单。全局安装后,在项目目录中运行 codebuff init 即可创建配置目录。你需要设置 LLM 提供商的 API Key 作为环境变量。

环境要求提醒:确保 Node.js >= 18、Git 已安装(Codebuff 依赖 Git 做变更管理)、API Key 已配置。首次使用建议在一个有 Git 仓库的项目中操作,这样可以随时撤销修改。

Codebuff 工作流全景图

理解 Codebuff 的完整工作流有助于你更高效地使用它。从输入指令到最终输出,每个环节都有明确的职责划分。

端到端工作流

用户输入
自然语言指令
代码上下文
指令解析
意图识别
约束提取
优先级排序
四代理流水线
选择→规划→编辑→审查
输出验证
Diff 预览
测试运行
用户确认

指令质量决定输出质量

模糊的指令会产生模糊的结果。好的指令包含:明确的目标、约束条件、期望的行为描述。例如"添加认证"不如"为 /api/* 路由添加 JWT 认证中间件,未认证返回 401"。

上下文是关键

Codebuff 会自动扫描项目结构获取上下文。你可以通过 .codebuff/config.yaml 补充项目约定,比如命名规范、文件组织偏好等,帮助代理做出更准确的判断。

渐进式确认

对于大型修改,建议使用 --dry-run 先预览,确认方向正确后再实际执行。Codebuff 的审查代理会检查语法和逻辑,但最终的合理性判断仍需要开发者确认。

小测验:Codebuff 使用了多少个代理来完成一个任务?

思考题:Codebuff 相比单一模型工具的核心优势是什么?

核心概念

Codebuff 的核心概念包括多代理协作、自然语言指令处理和精确的代码编辑。理解这些概念是高效使用 Codebuff 的基础。

多代理协作

Codebuff 使用多个专门代理来完成任务,每个代理负责不同的子任务。这种协作方式比单一模型工具提供更好的上下文理解、更准确的编辑和更少的错误。

四代理协作流程

文件选择代理
扫描项目结构
定位相关文件
理解依赖关系
规划代理
分析修改范围
确定执行顺序
评估风险
编辑代理
精确代码修改
保持风格一致
处理边界情况
审查代理
验证变更正确性
检查副作用
确认测试通过

自然语言指令处理

Codebuff 能够理解自然语言指令,并将其转化为具体的代码修改操作。这使得用户无需编写代码即可完成复杂的任务。

# 简单指令示例
codebuff "add authentication to my API"

# 复杂指令示例
codebuff "Refactor the database connection
  code to use connection pooling, update all
  modules that directly create connections,
  and add error handling for pool exhaustion"

# 带上下文的指令
codebuff "Based on the user model in
  src/models/user.ts, create CRUD API
  endpoints with input validation"

Codebuff 可以处理从简单到复杂的各种指令。简单的指令只需一句话,复杂的指令可以包含多个修改要求和约束条件。你还可以引用项目中的具体文件来提供上下文。

文件选择策略

文件选择代理是 Codebuff 最核心的组件之一。它需要准确理解项目结构,找到所有相关文件。

依赖分析

通过分析 import 语句和模块引用,构建完整的依赖图谱,确保修改不会遗漏任何相关文件。

语义搜索

基于代码语义进行搜索,不只是文本匹配。能理解函数调用、类型引用等深层关系。

上下文窗口优化

智能选择最相关的代码片段,在有限的上下文窗口中提供最有价值的信息。

规划代理的工作机制

规划代理接收文件选择代理的结果,制定具体的修改计划。

# 规划代理的输出示例
Plan for "Add rate limiting to API":

Step 1: Install rate-limit package
  File: package.json
  Action: Add dependency

Step 2: Create rate limiter middleware
  File: src/middleware/rateLimit.ts
  Action: Create new file

Step 3: Apply to routes
  Files: src/routes/*.ts
  Action: Import and use middleware

Step 4: Add configuration
  File: src/config/rateLimit.ts
  Action: Create config file

Step 5: Update tests
  Files: tests/routes/*.test.ts
  Action: Add rate limit tests

规划代理会将任务分解为有序的步骤,每步指定目标文件和操作类型。这种结构化的规划确保了修改的完整性和正确顺序。

编辑代理的精确性

编辑代理是执行实际代码修改的组件,它的精确性直接决定了 Codebuff 的输出质量。

// 编辑前:原始代码
app.post('/api/users', (req, res) => {
  const user = createUser(req.body);
  res.json(user);
});

// 编辑后:添加验证
app.post('/api/users', validateUserInput,
  (req, res) => {
    const user = createUser(req.body);
    res.json(user);
});

编辑代理会进行精确的代码插入和修改,而不是替换整个文件。这减少了对代码风格和格式的干扰,保持了与现有代码的一致性。

审查代理的验证机制

审查代理在编辑完成后进行最终检查,确保修改的正确性和完整性。

审查清单:审查代理会检查——语法正确性、逻辑一致性、副作用评估、测试覆盖率、代码风格匹配、边界情况处理。

  • 语法验证:确保修改后的代码没有语法错误
  • 逻辑检查:验证修改是否实现了预期功能
  • 副作用分析:评估修改对其他模块的影响
  • 测试运行:自动运行相关测试确保不引入回归

代理间的信息传递

# 代理间传递的信息结构
{
  "task": "Add authentication to API",
  "selected_files": [
    "src/routes/auth.ts",
    "src/middleware/auth.ts",
    "src/models/user.ts"
  ],
  "plan": [
    {"step": 1, "file": "...", "action": "..."},
    {"step": 2, "file": "...", "action": "..."}
  ],
  "edits": [
    {"file": "...", "diff": "...", "reason": "..."}
  ],
  "review": {
    "passed": true,
    "warnings": [],
    "suggestions": []
  }
}

每个代理将处理结果以结构化的方式传递给下一个代理,包含任务描述、选中的文件、修改计划、具体编辑和审查结果。

代理协作中的上下文传递机制

Codebuff 的多代理架构中,上下文的传递方式直接影响最终的编辑质量。每个代理接收到的不仅是前一个代理的输出,还有累积的项目知识。

# 上下文传递的数据结构
{
  "project_context": {
    "language": "TypeScript",
    "framework": "NestJS",
    "structure": {
      "src/": ["controllers/", "services/",
               "modules/", "dto/"],
      "test/": ["unit/", "e2e/"]
    },
    "conventions": {
      "naming": "camelCase",
      "file_structure": "feature-based"
    }
  },
  "agent_chain": [
    {
      "agent": "file_selector",
      "output": {
        "selected": ["src/auth/auth.service.ts",
                     "src/auth/auth.module.ts"],
        "reason": "Auth-related files identified
                   via import analysis"
      }
    },
    {
      "agent": "planner",
      "input": "",
      "output": {
        "steps": [...],
        "risk_assessment": "LOW"
      }
    }
  ]
}

上下文传递采用累积式设计——每个代理都能看到之前所有代理的输出。这种设计确保了编辑代理不仅知道"改什么",还知道"为什么改"和"改了什么相关的内容"。

上下文窗口优化策略:Codebuff 会在传递上下文时自动压缩不相关的信息。例如,编辑代理不需要知道文件选择代理是如何找到文件的,只需要知道哪些文件被选中以及为什么。这种选择性传递确保了有限上下文窗口的高效利用。

编辑代理的 Diff 算法

编辑代理不会替换整个文件,而是生成精确的 diff(差异)来描述修改。这种设计保持了代码的原始风格和格式。

// 编辑代理生成的 diff 示例
--- a/src/auth/auth.service.ts
+++ b/src/auth/auth.service.ts
@@ -15,6 +15,12 @@
   async login(dto: LoginDto) {
     const user = await this.validateUser(dto);
+
+    // Rate limiting check
+    const attempts = await this.getRecentAttempts(
+      dto.email
+    );
+    if (attempts > 5) {
+      throw new TooManyAttemptsException();
+    }
+
     const token = this.generateToken(user);
     return { access_token: token };
   }

编辑代理使用精确的行级 diff,只插入或修改必要的部分。这种方式不会干扰文件的其余内容,保持了代码风格的一致性。上例中,代理仅在登录方法中插入了速率限制检查逻辑。

最小改动原则

编辑代理遵循最小改动原则——只修改完成任务所必需的代码。它不会"顺手"重构、格式化或添加注释,除非你明确要求。

风格匹配

编辑代理会分析周围代码的缩进风格(空格 vs Tab)、引号类型、命名约定等,确保新代码与现有代码风格一致。

边界安全

编辑代理在修改代码时会特别关注函数边界、条件分支和异常处理路径,确保不会因为遗漏边界条件而引入新的 bug。

小测验:Codebuff 使用哪种方式来处理用户的指令?

深度思考:为什么多代理协作比单一模型更有效?

实践应用

Codebuff 可以应用于各种实际场景,如修复漏洞、添加功能和重构代码。本模块将通过具体示例展示如何在日常开发中使用 Codebuff。

安装与配置

安装 Codebuff 非常简单,只需运行以下命令:

# 全局安装 Codebuff
npm install -g codebuff

# 验证安装
codebuff --version

# 在项目目录中初始化
cd your-project
codebuff init

全局安装后,在任何项目目录中运行 codebuff init 会创建 .codebuff/ 配置目录,包含项目特定的设置和自定义代理。

基本用法模式

# 交互模式 — 持续对话
cd your-project
codebuff
> Fix the SQL injection vulnerability
  in the user registration handler
> Now add input validation to all forms
> Create unit tests for the auth module

# 单次命令模式
codebuff "Add error handling to
  src/utils/database.ts"

# 指定文件范围
codebuff --scope src/api "Add rate limiting"

Codebuff 支持交互模式和单次命令模式。交互模式适合多步任务,可以连续给出指令;单次命令模式适合简单的修改。你还可以用 --scope 限制操作范围。

实战场景 1:安全漏洞修复

让我们通过一个实际案例来看 Codebuff 如何修复 SQL 注入漏洞:

// 漏洞代码 — SQL 注入风险
app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const query = `SELECT * FROM users
    WHERE username='${username}'
    AND password='${password}'`;
  db.query(query, (err, results) => {
    if (results.length > 0) {
      res.json({ success: true });
    }
  });
});

这段代码直接将用户输入拼接到 SQL 查询中,存在严重的 SQL 注入风险。攻击者可以通过构造恶意输入来绕过身份验证。

使用 Codebuff 修复:只需告诉 Codebuff "Fix SQL injection in login handler, use parameterized queries",它会自动定位漏洞代码、修改为参数化查询,并添加输入验证。

实战场景 2:API 速率限制

# 告诉 Codebuff
codebuff "Add rate limiting to all API
  endpoints, 100 requests per minute per
  IP, return 429 when exceeded"

# Codebuff 的执行过程:
# 1. 文件选择:找到所有路由文件
# 2. 规划:创建中间件 → 应用到路由
# 3. 编辑:编写中间件代码
# 4. 审查:检查所有端点是否覆盖

对于 API 速率限制这样的跨文件修改,Codebuff 会自动识别所有需要修改的路由文件,创建中间件,并确保所有端点都被覆盖。

实战场景 3:代码重构

# 重构数据库连接代码
codebuff "Refactor database connection
  code to use connection pooling, update
  all modules that directly create
  connections"

# Codebuff 的处理流程:
# 1. 找到所有创建数据库连接的文件
# 2. 创建连接池管理器
# 3. 替换所有直接连接为池连接
# 4. 添加连接池配置
# 5. 运行测试验证

重构类任务需要同时修改多个文件,这正是 Codebuff 多代理架构的强项。文件选择代理找到所有相关文件,编辑代理确保每处修改都正确。

实战场景 4:测试生成

# 为现有代码生成测试
codebuff "Write comprehensive tests
  for src/services/payment.ts, cover
  success cases, error handling, and
  edge cases"

# 生成的测试结构:
describe('PaymentService', () => {
  describe('processPayment', () => {
    it('should process valid payment');
    it('should reject expired card');
    it('should handle network timeout');
    it('should validate amount > 0');
    it('should handle concurrent charges');
  });
});

Codebuff 会分析源代码的功能和边界情况,生成覆盖正常流程、错误处理和极端情况的完整测试套件。

最佳实践:指令编写

编写清晰的指令:描述目标而非过程、指定约束条件、说明期望的行为。越具体的指令,Codebuff 的输出越准确。

最佳实践:范围控制

使用 --scope 限制操作范围,避免 Codebuff 修改不相关的文件。对于大型项目,分步骤执行复杂的修改。

最佳实践:结果验证

始终检查 Codebuff 的修改。虽然审查代理会验证,但作为开发者你应该理解并确认每处修改的合理性。

项目管理集成

# 在 CI/CD 中使用 Codebuff SDK
name: Auto-fix lint errors
on: [push]
jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          npx codebuff "Fix all ESLint errors
            and warnings, maintain existing
            code style"
      - name: Create PR with fixes
        uses: peter-evans/create-pull-request@v5

你可以在 CI/CD 流程中集成 Codebuff,自动修复 lint 错误、更新依赖或处理安全警告。

Codebuff 会找到正确的文件,在整个代码库中进行修改,并运行测试以确保不会破坏任何功能。

实战场景 5:国际化支持

国际化(i18n)是典型的跨文件修改场景——需要修改多个组件、创建翻译文件、更新配置。这非常适合 Codebuff 的多代理架构。

# 让 Codebuff 添加国际化支持
codebuff "Add i18n support to the application,
  extract all hardcoded strings from src/components/
  into translation files, support English and Chinese,
  use react-intl library"

# Codebuff 的执行计划:
# 1. 扫描所有组件文件,提取硬编码字符串
# 2. 创建翻译文件结构
# 3. 在组件中替换为 intl formatMessage
# 4. 配置 i18n Provider
# 5. 生成翻译模板文件

国际化任务涉及大量文件的统一修改。Codebuff 会自动找到所有包含硬编码字符串的组件,提取到翻译文件中,并替换为国际化 API 调用。这种跨文件的一致性修改是 Codebuff 最擅长的场景之一。

效率提示:对于类似 i18n 这种模式统一的批量修改,使用 --scope 限定范围可以显著提高准确性。例如 --scope src/components/ 确保只修改组件文件。

实战场景 6:依赖升级与兼容性修复

依赖升级是开发者最头疼的任务之一。当主要依赖更新大版本时,通常需要修改大量代码来适配新的 API。

# 升级 Express 到 v5 并修复兼容问题
codebuff "Upgrade Express from v4 to v5,
  review the migration guide, update all
  deprecated API calls, fix the router
  path syntax changes, update error handler
  middleware signature"

# Codebuff 处理步骤:
# Step 1: 读取 package.json,更新版本
# Step 2: 扫描所有路由文件
# Step 3: 识别废弃的 API 调用
# Step 4: 逐一修复为新的 API
# Step 5: 更新错误处理中间件签名
# Step 6: 运行测试验证

依赖升级需要理解旧 API 和新 API 的差异,并在整个代码库中找到所有使用点。Codebuff 的文件选择代理会精确找到所有受影响的文件,规划代理会按依赖顺序排列修改步骤。

升级前准备

使用 --dry-run 先预览所有修改,评估影响范围。确保有完整的 Git 提交记录,方便回滚。

分步执行

对于大型升级(如 v4 到 v5),建议分步执行:先更新 package.json,再逐模块修复兼容性问题。

验证策略

升级后立即运行测试套件。如果测试不充分,先用 Codebuff 补充测试再进行升级。

性能调优技巧

# .codebuff/config.yaml — 性能优化配置
performance:
  # 限制上下文大小,加快响应速度
  max_context_files: 15

  # 启用增量分析,只处理变更文件
  incremental: true

  # 并行编辑多个文件
  parallel_edits: true

  # 缓存文件分析结果
  cache_analysis: true
  cache_ttl: 3600  # 1 小时

  # 跳过大型生成文件
  skip_patterns:
    - "*.generated.ts"
    - "dist/**"
    - "coverage/**"
    - "node_modules/**"

在大型项目中,性能配置尤为重要。增量分析只处理变更文件,缓存避免重复分析,跳过生成文件减少不必要的处理。这些设置可以将响应时间减少 50% 以上。

团队协作最佳实践

共享配置

.codebuff/ 配置目录纳入版本控制,团队成员共享相同的代理设置和自定义规则,确保一致性。

Code Review 集成

在 PR 提交前让 Codebuff 进行预审查,检查代码风格、潜在问题和遗漏的测试。减少人工 review 的负担。

知识传递

自定义代理可以作为团队知识的载体——新人可以通过代理了解项目的编码规范和最佳实践。

小测验:Codebuff 如何处理代码库中的修改?

场景题:你的项目有 50 个 API 端点需要添加统一的认证中间件,使用 Codebuff 最佳的做法是?

进阶主题

Codebuff 提供了多种进阶功能,如自定义代理、SDK 集成和 Freebuff 免费版本。掌握这些高级特性可以让你充分发挥 Codebuff 的潜力。

自定义代理

你可以创建自己的代理,定义专用工作流。使用 /init 命令初始化一个自定义代理结构:

# 初始化自定义代理
codebuff
> /init

# 生成的 .agents/ 目录结构
.agents/
├── custom-agent.md    # 代理指令文件
├── context.md         # 上下文说明
└── tools/             # 自定义工具
    └── my-tool.md     # 工具定义

/init 命令会在 .agents/ 目录中创建自定义代理的骨架结构。代理指令使用 Markdown 编写,定义了代理的行为、可用工具和输出格式。

自定义代理实战示例

# .agents/api-docs-generator.md
---
name: API Documentation Generator
description: Generates comprehensive API
  documentation from route definitions
triggers:
  - "generate api docs"
  - "document api"
---

## Instructions
1. Scan all route files in src/routes/
2. Extract HTTP method, path, parameters
3. Identify request/response schemas
4. Generate OpenAPI 3.0 specification
5. Create markdown documentation

## Output Format
- OpenAPI YAML file in docs/api.yaml
- Markdown files in docs/api/

这是一个 API 文档生成器的自定义代理。它会在触发词匹配时被激活,自动扫描路由文件并生成文档。通过 Markdown 格式定义代理行为,简单直观。

SDK 集成

Codebuff 提供了 SDK,允许你将 Codebuff 集成到应用程序中。你可以创建自定义工具、集成 CI/CD 或将编码助手嵌入到产品中。

// 基础 SDK 使用
import { CodebuffClient } from '@codebuff/sdk';

const client = new CodebuffClient({
  apiKey: 'your-api-key',
  cwd: '/path/to/your/project',
  onError: (error) =>
    console.error('Error:', error.message),
});

// 执行单个任务
const result = await client.execute(
  'Add input validation to the registration form'
);
console.log('Changes:', result.changes);

SDK 的基础用法非常简单:创建客户端实例、指定项目路径、执行任务。结果包含所有修改的文件和变更详情。

SDK 高级用法

// 流式执行 — 实时获取进度
const stream = client.executeStream(
  'Refactor the authentication module',
  {
    onFileSelected: (file) =>
      console.log(`Selected: ${file}`),
    onEditApplied: (edit) =>
      console.log(`Edited: ${edit.file}`),
    onReviewComplete: (review) =>
      console.log(`Review: ${review.status}`),
  }
);

for await (const event of stream) {
  updateUI(event);
}

// 带约束的执行
const result = await client.execute(
  'Update database schema',
  {
    scope: ['src/models/', 'src/migrations/'],
    dryRun: true,  // 只预览不实际修改
    maxFiles: 10,  // 最多修改 10 个文件
  }
);

SDK 支持流式执行,可以实时获取文件选择、编辑和审查的进度。你还可以设置约束条件,如操作范围、文件数量上限和干跑模式。

Freebuff 免费版

Freebuff 是 Codebuff 的免费版本,无需订阅、无积分、无需配置。只需安装即可开始编码。

# 安装 Freebuff
npm install -g freebuff

# 直接使用
cd your-project
freebuff

# Freebuff vs Codebuff 对比
Feature        | Freebuff | Codebuff
---------------|----------|--------
Core editing   | ✅       | ✅
Multi-agent    | ✅       | ✅
Custom agents  | ❌       | ✅
SDK access     | ❌       | ✅
API rate limit | Standard | Priority
Support        | Community| Priority

Freebuff 包含 Codebuff 的核心功能(多代理编辑),但不支持自定义代理和 SDK。适合个人开发者快速上手,需要高级功能时可以升级。

配置文件详解

# .codebuff/config.yaml
version: 1
model:
  provider: anthropic
  name: claude-sonnet-4-6
  temperature: 0.1

agents:
  file_selector:
    max_files: 20
    exclude:
      - "node_modules/**"
      - "*.test.ts"
      - "dist/**"

  editor:
    style: "match-existing"
    max_changes_per_file: 5

  reviewer:
    run_tests: true
    test_command: "npm test"
    fail_on_test_failure: true

scope:
  default: ["src/**"]
  exclude: ["src/generated/**"]

配置文件允许你自定义模型选择、代理行为和操作范围。最常用的配置包括模型提供商、测试命令和排除目录。

与其他工具集成

VS Code 集成

通过 Codebuff 扩展,可以在 VS Code 中直接使用 Codebuff,修改实时显示在编辑器中。

Git Hooks 集成

在 pre-commit hook 中运行 Codebuff 进行自动格式化和 lint 修复。

Docker 集成

在 Docker 容器中运行 Codebuff,确保环境一致性。

安全提示:在使用 Codebuff 时,确保你的 API Key 安全存储。建议使用环境变量而非硬编码。Codebuff 会在本地处理所有代码,不会上传到云端。

自定义代理进阶:代码质量守护者

除了文档生成器,你还可以创建一个持续监控代码质量的代理。这个代理会在每次代码变更时自动执行质量检查。

# .agents/quality-guard.md
---
name: Quality Guard
description: Monitors code quality on every change
triggers:
  - "check quality"
  - "quality guard"
  - "guard"
---

## Quality Rules

### Security
- No hardcoded secrets or API keys
- All user inputs must be validated
- SQL queries must use parameterized statements
- Authentication checks on all sensitive endpoints

### Performance
- No N+1 database queries
- Pagination on all list endpoints
- Proper indexing on frequently queried fields
- Caching for read-heavy data

### Code Style
- Consistent naming conventions
- No functions longer than 50 lines
- No files longer than 500 lines
- Proper TypeScript typing (no `any`)

## Output Format
Score: 0-100
Issues by severity: CRITICAL | WARNING | INFO
Suggested fixes for each issue

这个质量守护者代理定义了安全、性能和代码风格三方面的检查规则。当你触发它时,它会扫描代码库并生成一个带有评分和具体建议的质量报告。

代理链式调用:你可以让质量守护者代理在代码审查代理完成后自动触发。在 .agents/quality-guard.md 中添加 chain: code-reviewer,两个代理会依次执行,结果会合并输出。

Codebuff 在团队中的最佳实践

当整个团队都使用 Codebuff 时,统一的配置和规范尤为重要。以下是一些团队协作的最佳实践。

共享配置

.codebuff/ 目录提交到 Git 仓库,这样团队成员共享相同的代理配置、工具定义和项目约定。

代码审查流程

Codebuff 的修改应该和人工编写的代码一样经过 Code Review。建议在 PR 模板中标注"Codebuff 生成"以便审查者重点关注。

指令日志

在 commit message 中记录使用的 Codebuff 指令,便于团队理解修改的意图和复现修改过程。

# 团队统一的 commit message 格式
git commit -m "feat(auth): add rate limiting
  to login endpoint

  Codebuff instruction: 'Add rate limiting
  to /api/auth/login, max 5 attempts per
  minute per IP, return 429 when exceeded'

  Files changed:
  - src/auth/auth.service.ts (rate limit logic)
  - src/auth/auth.module.ts (import RateLimiterModule)
  - src/guards/rate-limit.guard.ts (new guard)"

规范的 commit message 不仅记录了修改内容,还包含了 Codebuff 指令和变更文件清单。这对于团队理解和回溯修改非常有帮助。

小测验:Freebuff 与 Codebuff 的主要区别是什么?

进阶题:如何确保 Codebuff 不会修改不想被改动的文件?

总结与练习

恭喜你完成了 Codebuff 课程!让我们回顾一下所学内容,并通过实践练习巩固知识。

关键要点

多代理协作

Codebuff 使用文件选择、规划、编辑、审查四个代理分工协作,每个代理专注单一职责,确保修改的准确性和安全性。

自然语言驱动

通过自然语言描述需求,Codebuff 自动理解意图并转化为代码修改。从简单的单文件修改到复杂的跨文件重构都能处理。

可扩展架构

通过自定义代理和 SDK,Codebuff 可以适应各种开发场景,从个人项目到企业级 CI/CD 集成。

开源生态

Freebuff 免费版降低了使用门槛,SDK 为高级用户提供了完整的编程接口。

知识图谱

Codebuff 核心知识体系

基础层
安装配置
基本指令
项目初始化
核心层
四代理架构
自然语言处理
文件选择策略
应用层
安全修复
代码重构
测试生成
进阶层
自定义代理
SDK 集成
CI/CD 集成

练习项目

尝试以下任务来巩固你的知识:

练习 1:入门级 — 漏洞修复

  1. 创建一个简单的 Express.js 项目
  2. 故意引入一个 XSS 漏洞
  3. 使用 Codebuff 修复这个漏洞
  4. 验证修复是否完整
# 练习 1 的操作步骤
mkdir my-test-project && cd my-test-project
npm init -y
npm install express

# 创建带有 XSS 漏洞的代码
cat > app.js << 'EOF'
app.get('/search', (req, res) => {
  const results = searchDB(req.query.q);
  res.send(`
    

Search Results

You searched: ${req.query.q}

`); }); EOF # 使用 Codebuff 修复 codebuff "Fix XSS vulnerability in search, sanitize user input before rendering"

这个练习帮助你理解 Codebuff 如何处理安全漏洞。先引入一个典型问题,然后用 Codebuff 修复,对比修复前后的代码。

练习 2:中级 — 功能开发

  1. 创建一个待办事项 API
  2. 使用 Codebuff 添加用户认证功能
  3. 使用 Codebuff 添加速率限制
  4. 使用 Codebuff 为所有功能编写测试

练习 3:高级 — 自定义代理

  1. 创建一个自定义代码审查代理
  2. 定义审查规则和输出格式
  3. 在真实项目中测试自定义代理
  4. 使用 SDK 将 Codebuff 集成到你的工具链
# 练习 3:自定义审查代理
# .agents/code-reviewer.md
---
name: Code Reviewer
description: Reviews code for best practices
triggers:
  - "review code"
  - "check code quality"
---

## Review Checklist
1. Error handling completeness
2. Input validation coverage
3. Performance considerations
4. Security best practices
5. Code style consistency
6. Test coverage assessment

## Output Format
Return a structured review with:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (nice to have)
- Overall quality score (1-10)

这个练习让你创建一个实用的代码审查代理。通过 Markdown 定义审查规则,Codebuff 会在触发时自动执行审查并返回结构化的结果。

常见问题解答

Q: Codebuff 会修改 Git 未追踪的文件吗?
A: 默认不会。Codebuff 尊重 .gitignore 规则,只修改已追踪的文件。你可以通过配置覆盖这个行为。

Q: 如何撤销 Codebuff 的修改?
A: Codebuff 的每次修改都可以通过 git checkout .git stash 撤销。建议在使用前确保工作目录干净。

Q: Codebuff 支持哪些编程语言?
A: Codebuff 支持所有主流编程语言,包括 JavaScript/TypeScript、Python、Java、Go、Rust、C++ 等。

延伸学习资源

  • Codebuff 官方文档:https://docs.codebuff.com
  • GitHub 仓库:https://github.com/codebuff/codebuff
  • 社区 Discord:加入 Codebuff 社区获取帮助
  • 示例项目:官方提供的多个示例项目展示各种用法

不要害怕尝试!Codebuff 是开源的,你可以随时查看源代码来了解其工作原理。

进阶练习:构建自定义代理生态系统

掌握了 Codebuff 的基础和进阶功能后,你可以构建一套完整的自定义代理生态系统,覆盖项目开发的各个方面。

# 完整的自定义代理生态系统
.agents/
├── code-reviewer.md       # 代码审查代理
├── quality-guard.md       # 质量守护代理
├── api-docs-generator.md  # API 文档生成
├── db-migration-helper.md # 数据库迁移助手
├── test-generator.md      # 测试生成代理
└── tools/
    ├── database-query.md  # 数据库查询工具
    ├── http-client.md     # HTTP 请求工具
    └── schema-validator.md # Schema 验证工具

# 代理之间的协作关系
code-reviewer → quality-guard → test-generator
api-docs-generator ← db-migration-helper
test-generator → quality-guard

一个完整的代理生态系统包含多个专用代理和共享工具。代理之间通过 chain 配置形成工作流,工具则提供可复用的能力扩展。这种设计让每个代理保持单一职责,同时通过组合实现复杂功能。

练习 4:专家级 — 构建完整的代理生态:在一个真实项目中创建上述所有代理,配置代理间的链式调用,编写统一的工具定义,并用 SDK 创建一个管理面板来触发和监控代理执行。

Codebuff 未来发展与社区贡献

Codebuff 作为一个活跃的开源项目,正在快速发展。了解其路线图和贡献方式,有助于你更好地规划使用策略。

多模型支持增强

未来版本将支持更多 LLM 提供商,包括本地模型(Ollama)、开源模型(Llama 3)和国内模型(通义千问、GLM)。你可以为不同的代理选择最适合的模型。

IDE 深度集成

除了 VS Code 扩展,未来将支持 JetBrains 全家桶、Neovim 和 Emacs。Codebuff 的修改将实时反映在编辑器中,支持 inline diff 和交互式确认。

团队协作功能

计划中的团队功能包括:共享代理市场、统一配置管理、使用统计和成本分析、权限控制和审计日志。

如何参与贡献:Codebuff 欢迎社区贡献。你可以通过提交自定义代理模板、改进文档、报告 Bug 或贡献代码来参与。GitHub 仓库有详细的贡献指南和 Good First Issue 标签。

最终测验:以下哪项是 Codebuff 的核心优势?

综合测验:在使用 Codebuff SDK 时,如何安全地预览修改而不实际改变文件?