Claude-Code-Workflow/docs/zh/agents/custom.md

自定义代理

创建和配置自定义 CCW 代理指南。

代理结构

~/.claude/agents/my-agent/
├── AGENT.md          # 代理定义
├── index.ts          # 代理逻辑
├── tools/            # 代理专用工具
└── examples/         # 使用示例

创建代理

1. 定义代理

创建 AGENT.md:

---
name: my-agent
type: development
version: 1.0.0
capabilities: [react, typescript, testing]
---

# 我的自定义代理

专门用于 React 组件开发的 TypeScript 代理。

## 功能

- 使用 hooks 生成 React 组件
- TypeScript 类型定义
- Vitest 测试设置
- Tailwind CSS 样式

## 使用

\`\`\`javascript
Task({
  subagent_type: "my-agent",
  prompt: "创建用户配置文件组件"
})
\`\`\`

2. 实现代理逻辑

创建 index.ts:

import type { AgentContext, AgentResult } from '@ccw/types'

export async function execute(
  prompt: string,
  context: AgentContext
): Promise<AgentResult> {
  // 分析请求
  const intent = analyzeIntent(prompt)

  // 根据意图执行
  switch (intent.type) {
    case 'generate-component':
      return await generateComponent(intent.options)
    case 'add-tests':
      return await addTests(intent.options)
    default:
      return await handleGeneral(prompt)
  }
}

function analyzeIntent(prompt: string) {
  // 从提示词解析用户意图
  // 返回结构化意图对象
}

代理功能

代码生成

async function generateComponent(options: ComponentOptions) {
  return {
    files: [
      {
        path: 'src/components/UserProfile.tsx',
        content: generateReactComponent(options)
      },
      {
        path: 'src/components/UserProfile.test.tsx',
        content: generateTests(options)
      }
    ]
  }
}

分析

async function analyzeCodebase(context: AgentContext) {
  const files = await context.filesystem.read('src/**/*.ts')
  const patterns = identifyPatterns(files)
  return {
    patterns,
    recommendations: generateRecommendations(patterns)
  }
}

测试

async function generateTests(options: TestOptions) {
  return {
    framework: 'vitest',
    files: [
      {
        path: `${options.file}.test.ts`,
        content: generateTestCode(options)
      }
    ]
  }
}

代理工具

代理可以定义自定义工具:

export const tools = {
  'my-tool': {
    description: '我的自定义工具',
    parameters: {
      type: 'object',
      properties: {
        input: { type: 'string' }
      }
    },
    execute: async (params) => {
      // 工具实现
    }
  }
}

代理通信

代理通过消息总线通信:

// 向另一个代理发送消息
await context.messaging.send({
  to: 'tester',
  type: 'task-complete',
  data: { files: generatedFiles }
})

// 接收消息
context.messaging.on('task-complete', async (message) => {
  if (message.from === 'executor') {
    await startTesting(message.data.files)
  }
})

代理配置

在 ~/.claude/agents/config.json 中配置代理:

{
  "my-agent": {
    "enabled": true,
    "priority": 10,
    "capabilities": {
      "frameworks": ["react", "vue"],
      "languages": ["typescript", "javascript"],
      "tools": ["vitest", "playwright"]
    },
    "limits": {
      "maxFiles": 100,
      "maxSize": "10MB"
    }
  }
}

代理最佳实践

1. 明确目的

定义特定的、集中的功能:

# 好: 专注
name: react-component-agent
purpose: 使用 TypeScript 生成 React 组件

# 坏: 太宽泛
name: fullstack-agent
purpose: 处理一切

2. 工具选择

为任务使用适当的工具:

// 文件操作
context.filesystem.read(path)
context.filesystem.write(path, content)

// 代码分析
context.codebase.search(query)
context.codebase.analyze(pattern)

// 通信
context.messaging.send(to, type, data)

3. 错误处理

try {
  const result = await executeTask(prompt)
  return { success: true, result }
} catch (error) {
  return {
    success: false,
    error: error.message,
    recovery: suggestRecovery(error)
  }
}

测试代理

import { describe, it, expect } from 'vitest'
import { execute } from '../index'

describe('my-agent', () => {
  it('应该生成组件', async () => {
    const result = await execute(
      '创建 UserCard 组件',
      mockContext
    )
    expect(result.success).toBe(true)
    expect(result.files).toHaveLength(2) // 组件 + 测试
  })
})

::: info 另请参阅

• 内置代理 - 预配置代理
• 代理概述 - 代理系统介绍 :::