多渠道交互

Web UI 配置

ThePopeBot 内置了一个功能丰富的 Web UI，让你可以直接在浏览器中与 Agent 交互。

基本配置

// config/channels/web.ts
export const webConfig = {
  enabled: true,
  port: 3000,
  host: '0.0.0.0',
  cors: {
    origin: ['http://localhost:5173'],
    credentials: true,
  },
  auth: {
    type: 'basic', // 'basic' | 'jwt' | 'none'
    users: [
      { username: 'admin', password: process.env.WEB_PASSWORD },
    ],
  },
  ui: {
    theme: 'dark',
    title: 'My Agent Dashboard',
    showToolCalls: true,    // 显示工具调用过程
    showThinking: true,     // 显示思考过程
    maxHistoryLength: 100,  // 历史消息数量
  },
};

启动 Web 服务

# 仅启动 Web 渠道
npm run dev -- --channel web

# 指定端口
PORT=8080 npm run dev -- --channel web

Web UI 提供了以下功能：

• 实时对话界面
• 工具调用可视化
• 任务执行日志
• Agent 配置管理面板
• 会话历史导出

Telegram Bot 集成

将 Agent 接入 Telegram，让你可以随时随地通过手机与 Agent 交互。

创建 Telegram Bot

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot 命令
3. 按照提示设置 Bot 名称
4. 保存获得的 Bot Token

配置集成

// config/channels/telegram.ts
export const telegramConfig = {
  enabled: true,
  token: process.env.TELEGRAM_BOT_TOKEN,
  webhook: {
    url: 'https://your-domain.com/telegram/webhook',
    secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
  },
  allowedUsers: [
    123456789,  // 你的 Telegram 用户 ID
  ],
  commands: [
    { command: 'start', description: '开始对话' },
    { command: 'status', description: '查看 Agent 状态' },
    { command: 'task', description: '创建新任务' },
    { command: 'history', description: '查看任务历史' },
  ],
  rateLimit: {
    maxMessages: 30,
    windowMs: 60000, // 每分钟最多 30 条消息
  },
};

环境变量配置

TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_WEBHOOK_SECRET=your-secret-here

启动 Telegram 渠道

npm run dev -- --channel telegram

现在你可以在 Telegram 中与 Bot 对话了。试试发送：

/task 帮我检查项目中的安全漏洞

Webhook 配置

Webhook 允许外部系统主动向 Agent 发送事件，非常适合与 CI/CD、监控系统等集成。

基本配置

// config/channels/webhook.ts
export const webhookConfig = {
  enabled: true,
  path: '/api/webhook',
  auth: {
    type: 'hmac-sha256',
    secret: process.env.WEBHOOK_SECRET,
  },
  endpoints: [
    {
      path: '/github',
      source: 'github',
      events: ['push', 'pull_request', 'issues'],
      agent: 'code-assistant',
    },
    {
      path: '/monitor',
      source: 'monitoring',
      events: ['alert', 'recovery'],
      agent: 'ops-agent',
    },
  ],
};

GitHub Webhook 示例

配置 GitHub 仓库的 Webhook，让 Agent 自动响应代码事件：

// handlers/github-webhook.ts
export async function handleGitHubEvent(event: GitHubEvent) {
  switch (event.type) {
    case 'pull_request.opened':
      // 自动审查新的 PR
      await agent.executeTask({
        type: 'pr-review',
        prNumber: event.payload.number,
      });
      break;

    case 'issues.opened':
      // 自动分析新的 Issue
      await agent.executeTask({
        type: 'issue-analysis',
        issueNumber: event.payload.number,
      });
      break;

    case 'push':
      // 推送后自动运行检查
      await agent.executeTask({
        type: 'code-check',
        ref: event.payload.ref,
        commits: event.payload.commits,
      });
      break;
  }
}

Cron 定时任务

通过定时任务，Agent 可以在指定时间自动执行预设的任务。

配置定时任务

// config/cron.ts
export const cronConfig = {
  tasks: [
    {
      name: 'daily-security-scan',
      schedule: '0 9 * * *', // 每天早上 9 点
      agent: 'security-agent',
      task: {
        type: 'security-scan',
        scope: 'full',
        reportTo: ['email', 'telegram'],
      },
    },
    {
      name: 'weekly-dependency-check',
      schedule: '0 10 * * 1', // 每周一上午 10 点
      agent: 'code-assistant',
      task: {
        type: 'dependency-audit',
        autoFix: false,
        createPR: true,
      },
    },
    {
      name: 'hourly-health-check',
      schedule: '0 * * * *', // 每小时
      agent: 'ops-agent',
      task: {
        type: 'health-check',
        services: ['api', 'database', 'cache'],
        alertThreshold: 'warning',
      },
    },
  ],
};

Cron 表达式速查

表达式	含义
* * * * *	每分钟
0 * * * *	每小时
0 9 * * *	每天 9:00
0 9 * * 1-5	工作日 9:00
0 0 * * 0	每周日午夜
0 0 1 * *	每月 1 号午夜

各渠道的最佳实践

安全性

• 所有渠道都应启用身份验证
• Webhook 使用 HMAC 签名验证
• Telegram 限制允许的用户列表
• 定期轮换 API 密钥和 Token

性能优化

• 为不同渠道设置合理的速率限制
• 长时间运行的任务使用异步处理
• 启用消息队列处理高并发场景

消息格式

// 根据渠道自动适配输出格式
const formatConfig = {
  web: { format: 'markdown', maxLength: 10000 },
  telegram: { format: 'html', maxLength: 4096 },
  webhook: { format: 'json', maxLength: 65536 },
};

小结

今天你学习了如何配置和使用 ThePopeBot 的四种交互渠道：Web UI、Telegram Bot、Webhook 和定时任务。每种渠道都有其独特的优势和适用场景。明天我们将学习如何让多个 Agent 协同工作。