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

# 安装后即可使用
$ 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 "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"

# 规划代理的输出示例
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

// 编辑前：原始代码
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
npm install -g codebuff

# 验证安装
codebuff --version

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

# 交互模式 — 持续对话
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"

// 漏洞代码 — 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 });
    }
  });
});

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

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

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

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

# 为现有代码生成测试
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');
  });
});

# 在 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

# .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/**"

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

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

# .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/

// 基础 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);

// 流式执行 — 实时获取进度
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 个文件
  }
);

# 安装 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

# .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/**"]

# 练习 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"

# 练习 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)