XAgent：智能X.com自动化框架

基于Claude Agent SDK和Chrome DevTools MCP的强大X.com自动化框架，支持智能浏览、点赞、评论、发帖以及全面的社会媒体自动化操作。

🎬 演示

30秒演示展示了XAgent在X.com上的操作：搜索、点赞和评论帖子

---

📖 目录

• 项目概述
• 核心功能
• 架构设计
• 技术栈
• 快速开始
• 项目结构
• 核心概念
• API参考
• 实际用例
• 开发指南
• 最佳实践
• 故障排除
• 扩展与定制

---

项目概述

XAgent是一个企业级X.com（推特）自动化框架，结合了Anthropic的Claude AI与Chrome浏览器自动化能力，执行复杂的社交媒体任务。

为什么选择XAgent？

• 🤖 AI驱动：使用具有真正语义理解能力的Claude Sonnet 4.5模型
• 🌐 实际浏览器：基于Chrome DevTools协议，完全模拟真实用户行为
• 🔧 高度可扩展：模块化设计，易于添加新功能和自定义行为
• 📊 生产就绪：包括错误处理、重试机制和详细的日志记录
• 💰 成本透明：实时跟踪API调用成本和使用情况

使用场景

• 社交媒体营销自动化
• 内容发现和策划
• 社区管理和互动
• 研究和数据收集
• 品牌监控和声誉管理

---

核心功能

基础功能

• ✅ 浏览和导航：智能浏览X.com并理解页面结构
• ✅ 搜索：按关键词、主题或用户搜索内容
• ✅ 点赞：自动点赞帖子
• ✅ 评论：生成并发布上下文感知的评论
• ✅ 发帖：创建并发布新的推文
• ✅ 关注/取消关注：管理关注者列表
• ✅ 转发：分享有趣的内容
• ✅ 时间线分析：分析和总结时间线内容

高级功能

• 🎯 批量操作：一次处理多个帖子
• 🧠 智能评论：根据内容生成相关且有价值的评论
• 📈 进度追踪：使用TodoWrite工具追踪任务进度
• 🔄 会话管理：支持长时间运行的自动化任务
• 🎨 自定义行为：通过自然语言定义任何自定义动作

---

架构设计

总体架构

┌─────────────────────────────────────────────────────────────┐
│                      用户脚本层                           │
│  (llm-explorer.ts, vlm-explorer.ts, 自定义脚本)         │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                     Claude Agent SDK                          │
│  - query() 函数：核心查询接口                            │
│  - 配置选项：配置MCP服务器、权限、系统提示              │
│  - 消息流：异步消息流处理                              │
└────────────┬────────────────────────────┬────────────────────┘
             │                                │
             ▼                                ▼
┌─────────────────────────┐    ┌──────────────────────────────┐
│   Chrome DevTools MCP   │    │    XAgent 包装类            │
│  - navigate_page        │    │  - navigateToX()             │
│  - click                │    │  - likePost()                │
│  - fill                 │    │  - commentOnPost()           │
│  - evaluate_script      │    │  - createPost()              │
│  - take_snapshot        │    │  - search()                  │
│  - wait_for             │    │  - customAction()            │
└────────────┬────────────┘    └──────────────┬───────────────┘
             │                                │
             ▼                                ▼
┌─────────────────────────────────────────────────────────────┐
│                    Chrome 浏览器                             │
│  - 在端口9222上进行远程调试                             │
│  - 用户数据目录：~/Library/.../Chrome-Remote-Debug         │
│  - 具有持久会话的真实浏览器实例                        │
└─────────────────────────────────────────────────────────────┘

核心组件解释

1. Claude Agent SDK

Claude Agent SDK是整个系统的“大脑”，负责：

• 理解自然语言指令
• 规划执行步骤
• 调用MCP工具
• 处理错误和重试
• 生成智能响应

关键概念：

// SDK的核心是query函数
const queryResult = query({
  prompt: "您的指令",
  options: {
    systemPrompt: "定义代理角色和能力的系统提示",
    mcpServers: { /* MCP服务器配置 */ },
    permissionMode: 'bypassPermissions',
    maxTurns: 50,  // 最大交互轮数
  }
});

// 返回异步迭代器以处理消息流
for await (const message of queryResult) {
  if (message.type === 'assistant') {
    // 代理的思考和操作
  } else if (message.type === 'result') {
    // 最终结果
  }
}

2. Chrome DevTools MCP

Chrome DevTools MCP提供浏览器自动化能力：

可用工具：

• navigate_page：导航到URL
• click：点击元素
• fill：填写表单
• evaluate_script：执行JavaScript
• take_snapshot：获取页面可访问性树
• take_screenshot：截图
• wait_for：等待元素出现
• press_key：键盘输入

配置（.claude/settings.json）：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  },
  "permissionMode": "bypassPermissions"
}

3. XAgent 包装类（可选）

XAgent 类提供了高级抽象以简化常见操作：

export class XAgent {
  private options: Options;

  constructor(options: Options) {
    this.options = options;
  }

  private async executeQuery(prompt: string): Promise<string> {
    // 包装query调用并处理消息流
  }

  // 高级方法
  async likePost(postUrl: string): Promise<void>
  async commentOnPost(postUrl: string, comment: string): Promise<void>
  async createPost(content: string): Promise<void>
  // ... 更多方法
}

数据流

用户指令 → Claude 分析 → 生成执行计划 →
调用 Chrome MCP 工具 → 浏览器执行 →
获取结果 → Claude 理解 → 继续或返回结果

---

技术栈

核心依赖

技术	版本	目的
TypeScript	5.7.0	类型安全的JavaScript超集
Node.js	18+	JavaScript运行时
Claude Agent SDK	0.1.43	AI代理框架
Chrome DevTools MCP	最新	浏览器自动化
ts-node	10.9.2	TypeScript执行器

开发工具

• ESM 模块：使用现代ES模块系统
• 类型检查：严格的TypeScript配置
• 自动重新加载：开发模式下的文件监视

---

快速开始

前提条件

• Node.js 18或更高版本
• npm或yarn包管理器
• Google Chrome浏览器
• Anthropic API密钥（如果需要）

安装步骤

1. 克隆或下载项目

   cd XAgent
   

2. 安装依赖项

   npm install
   

3. 配置API密钥（可选）

   cp .env.example .env
   # 编辑.env文件并添加您的ANTHROPIC_API_KEY
   

4. 启动Chrome远程调试

   # macOS
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
     --remote-debugging-port=9222 \
     --user-data-dir="$HOME/Library/Application Support/Google/Chrome-Remote-Debug" &
   
   # Linux
   /usr/bin/google-chrome \
     --remote-debugging-port=9222 \
     --user-data-dir=/tmp/chrome-profile-stable &
   
   # Windows
   "C:\Program Files\Google\Chrome\Application\chrome.exe" \
     --remote-debugging-port=9222 \
     --user-data-dir="%TEMP%\chrome-profile-stable"
   

5. 运行示例

   # 基本示例
   npm run example
   
   # LLM主题探索
   npm run explore-llm
   
   # VLM主题探索
   npm run explore-vlm
   

验证安装

# 检查TypeScript编译
npm run typecheck

# 构建项目
npm run build

# 检查Chrome远程调试
curl http://127.0.0.1:9222/json/version

---

项目结构

XAgent/
├── src/                          # 源代码目录
│   ├── index.ts                  # 主入口点
│   ├── XAgent.ts                # XAgent包装类
│   ├── example.ts                # 基本示例
│   ├── llm-explorer.ts           # LLM主题探索示例
│   ├── vlm-explorer.ts           # VLM主题探索示例（1-4）
│   └── vlm-continue.ts           # VLM主题探索示例（5-10）
│
├── .claude/                      # Claude配置目录
│   └── settings.json             # MCP服务器和权限配置
│
├── dist/                         # 编译输出目录（自动生成）
│
├── node_modules/                 # 依赖项（自动生成）
│
├── package.json                  # 项目配置和脚本
├── tsconfig.json                 # TypeScript配置
├── .env.example                  # 环境变量模板
├── .gitignore                    # Git忽略配置
└── README.md                     # 项目文档（此文件）

核心文件描述

src/index.ts - 主入口点

基本导航和查询示例，展示SDK的基本用法：

// 加载设置
const settings = await loadSettings();

// 执行查询
const navigationQuery = query({
  prompt: '导航到X.com并确认已加载',
  options: { ...settings, systemPrompt }
});

// 处理消息流
for await (const message of navigationQuery) {
  // 处理助理消息和结果
}

src/XAgent.ts - 包装类

提供高级抽象的XAgent类：

class XAgent {
  // 私有方法：执行查询
  private async executeQuery(prompt: string): Promise<string>

  // 公共方法：具体操作
  public async navigateToX(): Promise<void>
  public async likePost(postUrl: string): Promise<void>
  public async commentOnPost(url: string, comment: string): Promise<void>
  // ... 更多方法
}

src/llm-explorer.ts - LLM探索器

完整的自动化脚本示例，展示如何：

• 搜索特定主题
• 批量处理帖子
• 生成智能评论
• 追踪进度

.claude/settings.json - MCP配置

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  },
  "permissionMode": "bypassPermissions"
}

---

核心概念

1. 系统提示

系统提示定义了代理的角色、能力和行为标准：

const systemPrompt = `您是具有Chrome DevTools MCP的X.com自动化代理。

可用工具：
- navigate_page：导航到URL
- click：点击元素
- fill：填写表单
- evaluate_script：执行JavaScript
- take_snapshot：获取页面结构

您的任务：
1. 导航到X.com
2. 搜索特定主题
3. 与帖子互动（点赞、评论）

指导方针：
- 尊重并保持真实性
- 生成有意义的评论
- 等待元素加载
- 优雅地处理错误`;

关键要素：

• 角色定义：告诉代理它是什么
• 可用工具：明确指定可以使用的哪些MCP工具
• 任务目标：指定需要完成什么
• 行为准则：如何行为和约束

2. 消息类型

SDK返回不同类型的消

---

API参考

XAgent类方法

navigateToX(): Promise<void>

导航到X.com首页

示例：

await xAgent.navigateToX();

likePost(postUrl: string): Promise<void>

点赞指定的帖子

参数：

• postUrl：帖子的完整URL

示例：

await xAgent.likePost('https://x.com/elonmusk/status/1234567890');

commentOnPost(postUrl: string, comment: string): Promise<void>

在帖子上发表评论

参数：

• postUrl：帖子的完整URL
• comment：评论内容

示例：

await xAgent.commentOnPost(
  'https://x.com/user/status/123',
  '关于AI的伟大见解！ 🤖'
);

createPost(content: string): Promise<void>

发布新的推文

参数：

• content：推文内容（最多280个字符）

示例：

await xAgent.createPost('刚刚用Claude构建了一个AI代理！ 🚀');

viewTimeline(): Promise<void>

查看并分析时间线

示例：

await xAgent.viewTimeline();
// 代理将总结时间线内容

followUser(username: string): Promise<void>

关注用户

参数：

• username：用户名（不带@符号）

示例：

await xAgent.followUser('elonmusk');

unfollowUser(username: string): Promise<void>

取消关注用户

参数：

• username：用户名（不带@符号）

示例：

await xAgent.unfollowUser('someuser');

repost(postUrl: string): Promise<void>

转发帖子

参数：

• postUrl：帖子的完整URL

示例：

await xAgent.repost('https://x.com/user/status/123');

search(query: string, type?: 'posts' | 'users'): Promise<void>

搜索帖子或用户

参数：

• query：搜索关键词
• type：搜索类型，默认为'posts'

示例：

await xAgent.search('人工智能', 'posts');
await xAgent.search('sama', 'users');

customAction(instruction: string): Promise<string>

执行自定义指令

参数：

• instruction：自然语言指令

返回值：

• 执行结果的文本描述

示例：

const result = await xAgent.customAction(
  '找到今天最受欢迎的5篇AI文章并总结它们'
);
console.log(result);

低级API（直接SDK使用）

query(params): Query

Claude Agent SDK的核心查询函数

参数：

interface QueryParams {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: {
    systemPrompt?: string | { type: 'preset'; preset: 'claude_code'; append?: string };
    mcpServers?: Record<string, McpServerConfig>;
    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
    allowDangerouslySkipPermissions?: boolean;
    maxTurns?: number;
    maxBudgetUsd?: number;
    model?: string;
    // ... 更多选项
  };
}

返回值： 异步迭代器产生SDKMessage类型的消息

示例：

const queryResult = query({
  prompt: '导航到X.com并点赞第一个帖子',
  options: {
    systemPrompt: '您是X.com自动化代理',
    permissionMode: 'bypassPermissions',
    maxTurns: 20,
    mcpServers: {
      'chrome-devtools': { /* 配置 */ }
    }
  }
});

for await (const message of queryResult) {
  // 处理消息
}

---

实际用例

案