CodeBuddy Coding Skill\r

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

📋 Skill 概述\r

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

核心能力\r

\r

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

适用场景\r

\r

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

🚀 快速开始\r

\r

基本用法\r

\r

// 1. 加载 Skill\r
const codebuddy = require('./skill');\r
\r
// 2. 执行编程任务\r
const result = await codebuddy.execute({\r
  task: '创建一个用户登录页面',\r
  context: {\r
    projectPath: '/path/to/project',\r
    techStack: 'Vue 3 + TypeScript'\r
  },\r
  options: {\r
    outputFormat: 'json',\r
    permissionMode: 'bypassPermissions'\r
  }\r
});\r
\r
// 3. 获取结果\r
console.log(result.status);      // 'success'\r
console.log(result.filesModified); // ['src/views/Login.vue']\r
console.log(result.toolCalls);   // [{tool: 'write_to_file', ...}]\r
```\r
\r
### 监听进度\r
\r
```javascript\r
// 订阅进度事件\r
codebuddy.onProgress((progress) => {\r
  console.log(`进度: ${progress.percentage}%`);\r
  console.log(`当前任务: ${progress.currentTask}`);\r
  console.log(`已用时间: ${progress.elapsedTime}s`);\r
});\r
```\r
\r
---\r
\r
## 🔧 配置说明\r
\r
### 环境要求\r
\r
- **CodeBuddy CLI** v2.68.0+\r
- **Node.js** v16.0.0+\r
- **OpenClaw** coding-agent skill 框架\r
\r
### Skill 配置\r
\r
```json\r
{\r
  "name": "codebuddy-coding",\r
  "version": "1.0.0",\r
  "type": "coding",\r
  "capabilities": [\r
    "code-generation",\r
    "file-operations",\r
    "command-execution",\r
    "progress-monitoring"\r
  ],\r
  "dependencies": {\r
    "codebuddy-cli": ">=2.68.0"\r
  }\r
}\r
```\r
\r
---\r
\r
## 📚 API 文档\r
\r
### `execute(options)`\r
\r
执行编程任务。\r
\r
**参数：**\r
```typescript\r
interface ExecuteOptions {\r
  task: string;           // 任务描述\r
  context?: {             // 任务上下文\r
    projectPath?: string; // 项目路径\r
    techStack?: string;   // 技术栈\r
    files?: string[];     // 相关文件\r
  };\r
  options?: {             // 执行选项\r
    outputFormat?: 'json' | 'text';  // 输出格式\r
    permissionMode?: 'default' | 'bypassPermissions'; // 权限模式\r
    timeout?: number;     // 超时时间（秒）\r
  };\r
}\r
```\r
\r
**返回：**\r
```typescript\r
interface ExecuteResult {\r
  status: 'success' | 'failed' | 'timeout';\r
  filesModified: string[];      // 修改的文件列表\r
  toolCalls: ToolCall[];        // 工具调用记录\r
  reasoning: string[];          // 推理过程\r
  duration: number;             // 执行时长（秒）\r
  error?: string;               // 错误信息\r
}\r
```\r
\r
### `onProgress(callback)`\r
\r
订阅进度更新事件。\r
\r
**参数：**\r
```typescript\r
type ProgressCallback = (progress: {\r
  percentage: number;     // 完成百分比\r
  currentTask: string;    // 当前任务描述\r
  elapsedTime: number;    // 已用时间（秒）\r
  estimatedTime?: number; // 预计剩余时间（秒）\r
  filesModified: string[]; // 已修改文件\r
  toolCalls: number;      // 已调用工具次数\r
}) => void;\r
```\r
\r
### `getStatus()`\r
\r
获取当前任务状态。\r
\r
**返回：**\r
```typescript\r
interface TaskStatus {\r
  state: 'idle' | 'running' | 'completed' | 'failed';\r
  taskId?: string;\r
  startTime?: Date;\r
  progress?: Progress;\r
}\r
```\r
\r
---\r
\r
## 🎯 使用示例\r
\r
### 示例1：创建新组件\r
\r
```javascript\r
const codebuddy = require('./skill');\r
\r
// 创建登录组件\r
const result = await codebuddy.execute({\r
  task: '创建一个用户登录组件，包含用户名、密码输入框和登录按钮',\r
  context: {\r
    projectPath: '/path/to/vue-project',\r
    techStack: 'Vue 3 Composition API + TypeScript'\r
  }\r
});\r
\r
if (result.status === 'success') {\r
  console.log('组件创建成功！');\r
  console.log('创建的文件:', result.filesModified);\r
}\r
```\r
\r
### 示例2：修复 Bug\r
\r
```javascript\r
const codebuddy = require('./skill');\r
\r
// 修复登录验证 Bug\r
const result = await codebuddy.execute({\r
  task: '修复用户登录时的验证逻辑，密码应该至少8位且包含数字和字母',\r
  context: {\r
    projectPath: '/path/to/project',\r
    files: ['src/views/Login.vue', 'src/utils/validator.ts']\r
  }\r
});\r
\r
console.log('修复完成:', result.filesModified);\r
```\r
\r
### 示例3：监听长时间任务进度\r
\r
```javascript\r
const codebuddy = require('./skill');\r
\r
// 订阅进度\r
codebuddy.onProgress((progress) => {\r
  console.log(`[${progress.percentage}%] ${progress.currentTask}`);\r
  console.log(`  已修改 ${progress.filesModified.length} 个文件`);\r
  console.log(`  已执行 ${progress.toolCalls} 次操作`);\r
  console.log(`  用时 ${progress.elapsedTime}s`);\r
});\r
\r
// 执行长时间任务\r
const result = await codebuddy.execute({\r
  task: '重构整个用户管理模块，使用更清晰的架构',\r
  context: {\r
    projectPath: '/path/to/project'\r
  },\r
  options: {\r
    timeout: 600  // 10分钟超时\r
  }\r
});\r
```\r
\r
---\r
\r
## 🔍 进度监控原理\r
\r
### JSON 输出解析\r
\r
CodeBuddy CLI 支持 `--output-format json` 输出结构化数据：\r
\r
```bash\r
codebuddy -p "任务描述" --output-format json --permission-mode bypassPermissions\r
```\r
\r
**输出格式：**\r
```json\r
{\r
  "status": "running",\r
  "tool_calls": [\r
    {\r
      "tool": "write_to_file",\r
      "parameters": {\r
        "filePath": "src/Login.vue",\r
        "content": "..."\r
      },\r
      "result": "success"\r
    }\r
  ],\r
  "files_modified": ["src/Login.vue"],\r
  "reasoning": [\r
    "分析任务需求",\r
    "设计组件结构",\r
    "编写代码"\r
  ],\r
  "progress": {\r
    "percentage": 45,\r
    "current_task": "编写登录表单"\r
  }\r
}\r
```\r
\r
### 进度解析流程\r
\r
```mermaid\r
graph LR\r
  A[CodeBuddy CLI] -->|JSON Stream| B[Progress Monitor]\r
  B -->|Parse JSON| C[Progress Data]\r
  C -->|Emit Event| D[Event Callbacks]\r
  D -->|Update| E[Agent UI]\r
```\r
\r
---\r
\r
## ⚙️ 高级配置\r
\r
### 自定义输出解析器\r
\r
```javascript\r
const codebuddy = require('./skill');\r
\r
// 自定义解析器\r
codebuddy.setOutputParser((jsonLine) => {\r
  // 自定义解析逻辑\r
  return {\r
    percentage: jsonLine.progress?.percentage || 0,\r
    task: jsonLine.progress?.current_task || '处理中'\r
  };\r
});\r
```\r
\r
### 超时和重试\r
\r
```javascript\r
const result = await codebuddy.execute({\r
  task: '复杂重构任务',\r
  options: {\r
    timeout: 1200,        // 20分钟超时\r
    retryCount: 3,        // 失败重试3次\r
    retryDelay: 5000      // 重试间隔5秒\r
  }\r
});\r
```\r
\r
---\r
\r
## 🐛 调试和日志\r
\r
### 启用详细日志\r
\r
```javascript\r
const codebuddy = require('./skill');\r
\r
// 启用调试模式\r
codebuddy.setDebugMode(true);\r
\r
// 所有 CLI 输出会被记录到控制台\r
const result = await codebuddy.execute({\r
  task: '创建测试文件'\r
});\r
```\r
\r
### 查看执行日志\r
\r
```javascript\r
// 获取最近的执行日志\r
const logs = codebuddy.getExecutionLogs();\r
console.log(logs);\r
// [\r
//   { time: '11:30:01', event: 'CLI_START', command: '...' },\r
//   { time: '11:30:02', event: 'TOOL_CALL', tool: 'write_to_file' },\r
//   { time: '11:30:05', event: 'CLI_END', status: 'success' }\r
// ]\r
```\r
\r
---\r
\r
## 🚨 错误处理\r
\r
### 错误类型\r
\r
```typescript\r
enum CodeBuddyErrorType {\r
  CLI_NOT_FOUND = 'CLI_NOT_FOUND',        // CodeBuddy CLI 未安装\r
  INVALID_TASK = 'INVALID_TASK',          // 无效的任务描述\r
  TIMEOUT = 'TIMEOUT',                     // 执行超时\r
  PERMISSION_DENIED = 'PERMISSION_DENIED', // 权限被拒绝\r
  CLI_ERROR = 'CLI_ERROR'                  // CLI 执行错误\r
}\r
```\r
\r
### 错误处理示例\r
\r
```javascript\r
try {\r
  const result = await codebuddy.execute({\r
    task: '创建文件'\r
  });\r
} catch (error) {\r
  if (error.type === 'CLI_NOT_FOUND') {\r
    console.error('请先安装 CodeBuddy CLI');\r
  } else if (error.type === 'TIMEOUT') {\r
    console.error('任务超时，请增加超时时间');\r
  } else {\r
    console.error('执行失败:', error.message);\r
  }\r
}\r
```\r
\r
---\r
\r
## 📦 集成到 Agent\r
\r
### Developer Agent 集成\r
\r
```javascript\r
// developer/agent.js\r
const codebuddy = require('codebuddy-coding');\r
\r
class DeveloperAgent {\r
  async implementFeature(task) {\r
    // 使用 CodeBuddy 实现功能\r
    const result = await codebuddy.execute({\r
      task: task.description,\r
      context: {\r
        projectPath: this.projectPath,\r
        files: task.relatedFiles\r
      }\r
    });\r
\r
    return result;\r
  }\r
}\r
```\r
\r
### Architect Agent 集成\r
\r
```javascript\r
// architect/agent.js\r
const codebuddy = require('codebuddy-coding');\r
\r
class ArchitectAgent {\r
  async generateProjectScaffold(requirements) {\r
    // 使用 CodeBuddy 生成脚手架\r
    const result = await codebuddy.execute({\r
      task: `创建项目脚手架：${requirements}`,\r
      options: {\r
        permissionMode: 'bypassPermissions'\r
      }\r
    });\r
\r
    return result;\r
  }\r
}\r
```\r
\r
---\r
\r
## 🧪 测试\r
\r
### 运行测试\r
\r
```bash\r
# 运行所有测试\r
npm test\r
\r
# 运行特定测试\r
npm test -- --grep "CLI Wrapper"\r
```\r
\r
### 测试覆盖\r
\r
- ✅ CLI Wrapper 单元测试\r
- ✅ Progress Monitor 单元测试\r
- ✅ Integration 集成测试\r
- ✅ E2E 端到端测试\r
\r
---\r
\r
## 📄 许可证\r
\r
MIT License\r
\r
---\r
\r
## 🤝 贡献\r
\r
欢迎提交 Issue 和 Pull Request！\r
\r
---\r
\r
## 📞 支持\r
\r
如有问题，请联系：\r
- GitHub Issues: [OpenClaw Repository]\r
- Email: [email protected]\r
\r
---\r
\r
**让每个 Agent 都拥有 AI 编程能力！** 🚀\r