定义 Agent

在 ThePopeBot 中，每个 Agent 都通过一个配置对象来定义。Agent 的定义包含了它的身份、能力和行为规则。

在 src/agents/custom/ 目录下创建一个新文件 code-assistant.ts：

import { defineAgent } from '@thepopebot/core';

export const codeAssistant = defineAgent({
  name: 'code-assistant',
  description: '一个专注于代码生成和审查的自主 Agent',
  model: 'gpt-4',
  temperature: 0.3, // 低温度确保代码输出的一致性
  maxTokens: 8192,
  tools: ['filesystem', 'shell', 'git', 'codeAnalysis'],
  memory: {
    type: 'sliding-window',
    maxMessages: 30,
  },
  autonomy: {
    level: 'semi', // 'full' | 'semi' | 'supervised'
    requireApproval: ['file-delete', 'git-push'],
  },
});

自主等级说明

full：Agent 完全自主执行所有操作，无需人类确认
semi：大部分操作自主执行，敏感操作需要人类确认
supervised：每一步都需要人类确认后才执行

对于初次创建的 Agent，建议使用 semi 级别，在安全和效率之间取得平衡。

编写系统提示

系统提示（System Prompt）决定了 Agent 的”性格”和工作方式。一个好的系统提示应该清晰、具体且有边界。

const systemPrompt = `你是一个专业的代码助手 Agent，专注于以下领域：

## 核心能力
1. **代码生成**：根据需求生成高质量的代码
2. **代码审查**：分析代码质量，发现潜在问题
3. **重构建议**：提供代码优化和重构方案

## 工作原则
- 生成的代码必须包含完整的类型定义（TypeScript）
- 遵循项目现有的代码风格和命名规范
- 每次修改都要说明原因和影响范围
- 对于破坏性操作，先确认再执行

## 输出格式
- 代码块使用正确的语言标记
- 重要变更附带简要说明
- 列出可能的副作用和注意事项

## 限制
- 不要修改配置文件除非被明确要求
- 不要删除测试文件
- 不要自动推送到远程仓库`;

运行代码生成任务

Agent 定义完成后，让我们用它来执行一个实际的代码生成任务：

import { createSession } from '@thepopebot/core';
import { codeAssistant } from './agents/custom/code-assistant';

async function main() {
  // 创建会话
  const session = await createSession(codeAssistant);

  // 发送任务
  const response = await session.send(
    '创建一个用户认证服务，包含登录、注册和令牌刷新功能'
  );

  console.log(response.content);
  console.log('使用的工具:', response.toolCalls);
  console.log('创建的文件:', response.artifacts);
}

main();

Agent 会自动执行以下步骤：

分析需求，拆解为子任务
检查项目现有结构和代码风格
生成认证服务的代码文件
生成对应的类型定义
输出执行报告

用 Agent 审查 PR

ThePopeBot 的一个强大用法是用 Agent 来自动审查 Pull Request：

import { codeAssistant } from './agents/custom/code-assistant';

// 配置 PR 审查任务
const prReviewTask = {
  type: 'pr-review',
  source: 'github',
  config: {
    repository: 'owner/repo',
    prNumber: 42,
    reviewFocus: ['security', 'performance', 'code-quality'],
  },
};

const session = await createSession(codeAssistant);
const review = await session.executeTask(prReviewTask);

// review 包含：
// - 总体评价
// - 逐文件的具体建议
// - 安全风险提示
// - 性能优化建议
console.log(review.summary);
review.fileComments.forEach(comment => {
  console.log(`${comment.file}:${comment.line} - ${comment.suggestion}`);
});

PR 审查的最佳实践

明确审查重点：安全、性能、代码质量等
设置合理的严重等级阈值
将审查结果直接发布为 GitHub PR Comment
对于关键项目，可以设置 Agent 作为必要的审查者

测试你的 Agent

编写测试确保 Agent 按预期工作是非常重要的。ThePopeBot 提供了测试工具来模拟 Agent 交互：

import { testAgent, mockTools } from '@thepopebot/testing';
import { codeAssistant } from './agents/custom/code-assistant';

describe('Code Assistant Agent', () => {
  it('应该能生成 TypeScript 代码', async () => {
    const { session, responses } = await testAgent(codeAssistant, {
      tools: mockTools(['filesystem', 'shell']),
    });

    await session.send('创建一个简单的 HTTP 服务器');

    expect(responses[0].toolCalls).toContainEqual(
      expect.objectContaining({ tool: 'filesystem', action: 'create' })
    );
    expect(responses[0].content).toContain('typescript');
  });

  it('敏感操作应该请求确认', async () => {
    const { session, approvalRequests } = await testAgent(codeAssistant);

    await session.send('删除 src 目录下所有测试文件');

    expect(approvalRequests).toHaveLength(1);
    expect(approvalRequests[0].action).toBe('file-delete');
  });

  it('应该保持对话上下文', async () => {
    const { session } = await testAgent(codeAssistant);

    await session.send('创建一个 User 模型');
    const response = await session.send('给它添加邮箱验证方法');

    // Agent 应该记住之前创建的 User 模型
    expect(response.content).toContain('User');
    expect(response.content).toContain('email');
  });
});

运行测试：

npm test -- --grep "Code Assistant"

小结

今天你学会了如何创建一个功能完整的自主 Agent，包括定义配置、编写系统提示、执行任务和编写测试。明天我们将学习如何让 Agent 支持多渠道交互。

创建第一个自主 Agent