X Publisher

---
name: X-Publisher
description: "Publish tweets to X (Twitter) using the official Tweepy library. Supports text-only tweets, tweets with images or videos, and returns detailed publish results including tweet ID and URL. Requires X API credentials (API Key, API Secret, Access Token, Access Token Secret)."
---

# X (Twitter) 推文发布工具

使用官方 Tweepy 库发布推文，支持纯文本、图片、视频等多种媒体类型。

## 功能特性

- 📝 **纯文本推文** - 快速发布文字内容
- 🖼️ **图片支持** - 支持 JPG、PNG、GIF、WebP 格式（最多4张）
- 🎬 **视频支持** - 支持 MP4、MOV、AVI、WebM 格式
- 📊 **返回结果** - 返回推文 ID、链接、发布时间等详细信息
- ✅ **认证验证** - 支持验证 API 凭证是否有效

## 前提条件

### 1. 安装依赖

```bash
pip3 install tweepy --user
```

### 2. 获取 X API 凭证

1. 访问 https://developer.twitter.com/en/portal/dashboard
2. 创建项目并生成 API 密钥
3. 获取以下凭证：
   - API Key
   - API Secret
   - Access Token
   - Access Token Secret

### 3. 配置环境变量

```bash
# 添加到 ~/.zshrc
export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_TOKEN_SECRET="your-access-token-secret"
export X_BEARER_TOKEN="your-bearer-token"  # 可选
```

然后执行：
```bash
source ~/.zshrc
```

## 使用方法

### 验证认证信息

首次使用前，建议先验证凭证：

```bash
python3 scripts/x_publisher.py verify
```

输出示例：
```
✅ 认证成功!
👤 用户名: @your_username
📛 显示名: Your Name
👥 粉丝: 1,234
📝 推文: 5,678
```

### 发布纯文本推文

```bash
python3 scripts/x_publisher.py tweet "Hello, X! This is my first tweet."
```

### 发布带图片的推文

```bash
# 单张图片
python3 scripts/x_publisher.py tweet "Check out this photo!" --media /path/to/image.jpg

# 多张图片（最多4张）
python3 scripts/x_publisher.py tweet "My photo collection:" \
  --media /path/to/photo1.jpg \
  --media /path/to/photo2.png \
  --media /path/to/photo3.gif
```

### 发布带视频的推文

```bash
python3 scripts/x_publisher.py tweet "Watch this video!" --media /path/to/video.mp4
```

## 输出结果

发布成功后会返回：

```
============================================================
✅ 推文发布成功!
============================================================
📝 推文 ID: 1234567890123456789
🔗 链接: https://twitter.com/user/status/1234567890123456789
⏰ 发布时间: 2024-02-03T15:30:45.123456
📄 内容预览: Hello, X! This is my first tweet.
============================================================

📋 JSON 输出:
{
  "success": true,
  "tweet_id": "1234567890123456789",
  "text": "Hello, X! This is my first tweet.",
  "created_at": "2024-02-03T15:30:45.123456",
  "url": "https://twitter.com/user/status/1234567890123456789"
}
```

## 命令参考

| 命令 | 功能 | 示例 |
|------|------|------|
| `verify` | 验证认证 | `x_publisher.py verify` |
| `tweet` | 发布推文 | `x_publisher.py tweet "Hello" --media photo.jpg` |

### tweet 命令参数

| 参数 | 简写 | 说明 | 必填 |
|------|------|------|------|
| `text` | - | 推文内容 | 是 |
| `--media` | `-m` | 媒体文件路径 | 否 |

## 支持的媒体格式

### 图片
- **JPG/JPEG** - 推荐格式
- **PNG** - 支持透明背景
- **GIF** - 支持动画
- **WebP** - 现代格式

**限制**：
- 最多 4 张图片
- 单张图片最大 5MB

### 视频
- **MP4** - 推荐格式
- **MOV** - QuickTime 格式
- **AVI** - 常见格式
- **WebM** - 现代格式

**限制**：
- 单个视频最大 512MB
- 最长 2 分 20 秒

## 错误处理

### 认证失败

```
❌ 认证失败: 无法获取用户信息
```

**解决方法**：
- 检查 API 密钥和令牌是否正确
- 确认令牌未过期
- 检查网络连接

### 权限不足

```
❌ 推文发布失败
错误类型: 权限不足
错误信息: You are not allowed to create a Tweet with these settings
```

**解决方法**：
- 确认应用有 "Write" 权限
- 检查是否违反 X 平台规则

### 请求过于频繁

```
❌ 推文发布失败
错误类型: 请求过于频繁
错误信息: Rate limit exceeded
```

**解决方法**：
- 等待几分钟后重试
- X API 有速率限制（每15分钟300条推文）

### 媒体上传失败

```
❌ 媒体文件不存在: /path/to/image.jpg
```

**解决方法**：
- 检查文件路径是否正确
- 确认文件格式支持
- 检查文件大小是否超限

## 使用场景

### 场景1：自动化发布

```bash
# 发布每日摘要
python3 scripts/x_publisher.py tweet "📊 今日市场摘要：BTC $43,250 (+2.3%)" 
```

### 场景2：带图发布

```bash
# 发布截图或图表
python3 scripts/x_publisher.py tweet "📈 今日走势图" --media ~/charts/btc_today.png
```

### 场景3：批量发布脚本

```python
#!/bin/bash
# publish_news.sh

CONTENT="🚀 重大新闻：..."
IMAGE="/path/to/news_image.jpg"

python3 scripts/x_publisher.py tweet "$CONTENT" --media "$IMAGE"
```

### 场景4：集成到其他工具

```python
import subprocess
import json

result = subprocess.run(
    ['python3', 'scripts/x_publisher.py', 'tweet', 'Hello!', '--media', 'photo.jpg'],
    capture_output=True,
    text=True
)

# 解析 JSON 输出
output_lines = result.stdout.split('\n')
for line in output_lines:
    if line.strip().startswith('{'):
        tweet_info = json.loads(line)
        print(f"Tweet ID: {tweet_info['tweet_id']}")
        print(f"URL: {tweet_info['url']}")
```

## API 限制

| 限制类型 | 数值 | 说明 |
|----------|------|------|
| 推文长度 | 280 字符 | 超过将自动截断 |
| 媒体数量 | 4 个 | 图片或视频混合 |
| 图片大小 | 5 MB | 单张图片 |
| 视频大小 | 512 MB | 单个视频 |
| 视频时长 | 2分20秒 | 最大时长 |
| 发布频率 | 300条/15分钟 | 速率限制 |

## 注意事项

1. **凭证安全** - 不要泄露 API 密钥，使用环境变量存储
2. **内容合规** - 遵守 X 平台规则，避免发布违规内容
3. **频率控制** - 注意 API 速率限制，避免频繁发布
4. **媒体版权** - 确保上传的媒体文件有版权或使用授权

## 参考

- Tweepy 文档: https://docs.tweepy.org/
- X API 文档: https://developer.twitter.com/en/docs/twitter-api
- X Developer Portal: https://developer.twitter.com/en/portal/dashboard