CodeBuddy Coding Skill

版本： 1.0.0 创建时间： 2026-03-31 作者： OpenClaw Team

---

📋 Skill 概述

CodeBuddy Coding Skill 是一个通用的 AI 编程能力扩展，让任何 OpenClaw agent 都能调用 CodeBuddy CLI 的强大功能。

核心能力

• ✅ AI 编程 - 代码生成、重构、调试、优化
• ✅ 文件操作 - 创建、修改、删除文件
• ✅ 命令执行 - 运行构建、测试、部署命令
• ✅ 进度监控 - 实时报告任务进度和状态
• ✅ 结构化输出 - JSON 格式的可解析输出

适用场景

• Developer Agent - 编写代码、修复 Bug
• Architect Agent - 生成项目脚手架
• Tester Agent - 编写测试用例
• 任何需要编程能力的 Agent - 通用编程支持

---

🚀 快速开始

基本用法

// 1. 加载 Skill
const codebuddy = require('./skill');

// 2. 执行编程任务
const result = await codebuddy.execute({
  task: '创建一个用户登录页面',
  context: {
    projectPath: '/path/to/project',
    techStack: 'Vue 3 + TypeScript'
  },
  options: {
    outputFormat: 'json',
    permissionMode: 'bypassPermissions'
  }
});

// 3. 获取结果
console.log(result.status);      // 'success'
console.log(result.filesModified); // ['src/views/Login.vue']
console.log(result.toolCalls);   // [{tool: 'write_to_file', ...}]

监听进度

// 订阅进度事件
codebuddy.onProgress((progress) => {
  console.log(`进度: ${progress.percentage}%`);
  console.log(`当前任务: ${progress.currentTask}`);
  console.log(`已用时间: ${progress.elapsedTime}s`);
});

---

🔧 配置说明

环境要求

• CodeBuddy CLI v2.68.0+
• Node.js v16.0.0+
• OpenClaw coding-agent skill 框架

Skill 配置

{
  "name": "codebuddy-coding",
  "version": "1.0.0",
  "type": "coding",
  "capabilities": [
    "code-generation",
    "file-operations",
    "command-execution",
    "progress-monitoring"
  ],
  "dependencies": {
    "codebuddy-cli": ">=2.68.0"
  }
}

---

📚 API 文档

execute(options)

执行编程任务。

参数：

interface ExecuteOptions {
  task: string;           // 任务描述
  context?: {             // 任务上下文
    projectPath?: string; // 项目路径
    techStack?: string;   // 技术栈
    files?: string[];     // 相关文件
  };
  options?: {             // 执行选项
    outputFormat?: 'json' | 'text';  // 输出格式
    permissionMode?: 'default' | 'bypassPermissions'; // 权限模式
    timeout?: number;     // 超时时间（秒）
  };
}

返回：

interface ExecuteResult {
  status: 'success' | 'failed' | 'timeout';
  filesModified: string[];      // 修改的文件列表
  toolCalls: ToolCall[];        // 工具调用记录
  reasoning: string[];          // 推理过程
  duration: number;             // 执行时长（秒）
  error?: string;               // 错误信息
}

onProgress(callback)

订阅进度更新事件。

参数：

type ProgressCallback = (progress: {
  percentage: number;     // 完成百分比
  currentTask: string;    // 当前任务描述
  elapsedTime: number;    // 已用时间（秒）
  estimatedTime?: number; // 预计剩余时间（秒）
  filesModified: string[]; // 已修改文件
  toolCalls: number;      // 已调用工具次数
}) => void;

getStatus()

获取当前任务状态。

返回：

interface TaskStatus {
  state: 'idle' | 'running' | 'completed' | 'failed';
  taskId?: string;
  startTime?: Date;
  progress?: Progress;
}

---

🎯 使用示例

示例1：创建新组件

const codebuddy = require('./skill');

// 创建登录组件
const result = await codebuddy.execute({
  task: '创建一个用户登录组件，包含用户名、密码输入框和登录按钮',
  context: {
    projectPath: '/path/to/vue-project',
    techStack: 'Vue 3 Composition API + TypeScript'
  }
});

if (result.status === 'success') {
  console.log('组件创建成功！');
  console.log('创建的文件:', result.filesModified);
}

示例2：修复 Bug

const codebuddy = require('./skill');

// 修复登录验证 Bug
const result = await codebuddy.execute({
  task: '修复用户登录时的验证逻辑，密码应该至少8位且包含数字和字母',
  context: {
    projectPath: '/path/to/project',
    files: ['src/views/Login.vue', 'src/utils/validator.ts']
  }
});

console.log('修复完成:', result.filesModified);

示例3：监听长时间任务进度

const codebuddy = require('./skill');

// 订阅进度
codebuddy.onProgress((progress) => {
  console.log(`[${progress.percentage}%] ${progress.currentTask}`);
  console.log(`  已修改 ${progress.filesModified.length} 个文件`);
  console.log(`  已执行 ${progress.toolCalls} 次操作`);
  console.log(`  用时 ${progress.elapsedTime}s`);
});

// 执行长时间任务
const result = await codebuddy.execute({
  task: '重构整个用户管理模块，使用更清晰的架构',
  context: {
    projectPath: '/path/to/project'
  },
  options: {
    timeout: 600  // 10分钟超时
  }
});

---

🔍 进度监控原理

JSON 输出解析

CodeBuddy CLI 支持

--output-format json

输出结构化数据：

codebuddy -p "任务描述" --output-format json --permission-mode bypassPermissions

输出格式：

{
  "status": "running",
  "tool_calls": [
    {
      "tool": "write_to_file",
      "parameters": {
        "filePath": "src/Login.vue",
        "content": "..."
      },
      "result": "success"
    }
  ],
  "files_modified": ["src/Login.vue"],
  "reasoning": [
    "分析任务需求",
    "设计组件结构",
    "编写代码"
  ],
  "progress": {
    "percentage": 45,
    "current_task": "编写登录表单"
  }
}

进度解析流程

graph LR
  A[CodeBuddy CLI] -->|JSON Stream| B[Progress Monitor]
  B -->|Parse JSON| C[Progress Data]
  C -->|Emit Event| D[Event Callbacks]
  D -->|Update| E[Agent UI]

---

⚙️ 高级配置

自定义输出解析器

const codebuddy = require('./skill');

// 自定义解析器
codebuddy.setOutputParser((jsonLine) => {
  // 自定义解析逻辑
  return {
    percentage: jsonLine.progress?.percentage || 0,
    task: jsonLine.progress?.current_task || '处理中'
  };
});

超时和重试

const result = await codebuddy.execute({
  task: '复杂重构任务',
  options: {
    timeout: 1200,        // 20分钟超时
    retryCount: 3,        // 失败重试3次
    retryDelay: 5000      // 重试间隔5秒
  }
});

---

🐛 调试和日志

启用详细日志

const codebuddy = require('./skill');

// 启用调试模式
codebuddy.setDebugMode(true);

// 所有 CLI 输出会被记录到控制台
const result = await codebuddy.execute({
  task: '创建测试文件'
});

查看执行日志

// 获取最近的执行日志
const logs = codebuddy.getExecutionLogs();
console.log(logs);
// [
//   { time: '11:30:01', event: 'CLI_START', command: '...' },
//   { time: '11:30:02', event: 'TOOL_CALL', tool: 'write_to_file' },
//   { time: '11:30:05', event: 'CLI_END', status: 'success' }
// ]

---

🚨 错误处理

错误类型

enum CodeBuddyErrorType {
  CLI_NOT_FOUND = 'CLI_NOT_FOUND',        // CodeBuddy CLI 未安装
  INVALID_TASK = 'INVALID_TASK',          // 无效的任务描述
  TIMEOUT = 'TIMEOUT',                     // 执行超时
  PERMISSION_DENIED = 'PERMISSION_DENIED', // 权限被拒绝
  CLI_ERROR = 'CLI_ERROR'                  // CLI 执行错误
}

错误处理示例

try {
  const result = await codebuddy.execute({
    task: '创建文件'
  });
} catch (error) {
  if (error.type === 'CLI_NOT_FOUND') {
    console.error('请先安装 CodeBuddy CLI');
  } else if (error.type === 'TIMEOUT') {
    console.error('任务超时，请增加超时时间');
  } else {
    console.error('执行失败:', error.message);
  }
}

---

📦 集成到 Agent

Developer Agent 集成

// developer/agent.js
const codebuddy = require('codebuddy-coding');

class DeveloperAgent {
  async implementFeature(task) {
    // 使用 CodeBuddy 实现功能
    const result = await codebuddy.execute({
      task: task.description,
      context: {
        projectPath: this.projectPath,
        files: task.relatedFiles
      }
    });

    return result;
  }
}

Architect Agent 集成

// architect/agent.js
const codebuddy = require('codebuddy-coding');

class ArchitectAgent {
  async generateProjectScaffold(requirements) {
    // 使用 CodeBuddy 生成脚手架
    const result = await codebuddy.execute({
      task: `创建项目脚手架：${requirements}`,
      options: {
        permissionMode: 'bypassPermissions'
      }
    });

    return result;
  }
}

---

🧪 测试

运行测试

# 运行所有测试
npm test

# 运行特定测试
npm test -- --grep "CLI Wrapper"

测试覆盖

• ✅ CLI Wrapper 单元测试
• ✅ Progress Monitor 单元测试
• ✅ Integration 集成测试
• ✅ E2E 端到端测试

---

📄 许可证

MIT License

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📞 支持

如有问题，请联系：

• GitHub Issues: [OpenClaw Repository]
• Email: support@openclaw.ai

---

让每个 Agent 都拥有 AI 编程能力！ 🚀