媒体功能说明.md•9.83 kB
# 媒体功能详细说明
## 功能概述
本项目现已支持完整的媒体功能，包括上传图片、视频、GIF动图，创建带媒体的推文，以及无障碍Alt文本支持，为用户提供丰富的多媒体推文体验。
## 新增工具说明
### 1. `upload_media` - 上传媒体文件
上传图片、视频或GIF文件到Twitter，获取媒体ID用于后续推文。
**参数说明：**
- `file_path` (字符串，必需): 媒体文件的本地路径
- `media_type` (字符串，必需): 媒体类型，可选值：`"image"`, `"video"`, `"gif"`
- `alt_text` (字符串，可选): 图片的替代文本，用于无障碍访问
**支持的文件格式：**
- **图片**: JPG, JPEG, PNG, WebP
- **视频**: MP4, MOV, AVI
- **GIF**: GIF动图
**使用场景：**
- 为推文准备媒体内容
- 批量上传多个媒体文件
- 为图片添加无障碍描述
**示例：**
```json
{
"name": "upload_media",
"arguments": {
"file_path": "/Users/username/Pictures/sunset.jpg",
"media_type": "image",
"alt_text": "山峦上的美丽日落，天空呈现橙红色渐变"
}
}
```
### 2. `create_tweet_with_media` - 创建带媒体的推文
使用已上传的媒体ID创建推文。
**参数说明：**
- `content` (字符串，必需): 推文的文本内容
- `media_ids` (数组，必需): 媒体ID列表，最多4个
**使用场景：**
- 发布带图片的推文
- 分享视频内容
- 发布GIF动图
**示例：**
```json
{
"name": "create_tweet_with_media",
"arguments": {
"content": "今天拍到的美丽日落！🌅",
"media_ids": ["1234567890123456789"]
}
}
```
### 3. `create_draft_tweet_with_media` - 创建带媒体的推文草稿
创建包含媒体文件的推文草稿，支持稍后发布。
**参数说明：**
- `content` (字符串，必需): 推文的文本内容
- `media_files` (数组，必需): 媒体文件信息列表
**媒体文件对象结构：**
```json
{
"file_path": "文件路径",
"media_type": "媒体类型",
"alt_text": "Alt文本（可选）"
}
```
**使用场景：**
- 准备包含多个媒体的推文
- 需要审核的媒体内容
- 定时发布的媒体推文
**示例：**
```json
{
"name": "create_draft_tweet_with_media",
"arguments": {
"content": "我的摄影作品集 📸",
"media_files": [
{
"file_path": "/path/to/photo1.jpg",
"media_type": "image",
"alt_text": "城市夜景，灯火通明"
},
{
"file_path": "/path/to/photo2.jpg",
"media_type": "image",
"alt_text": "自然风光，绿树成荫"
}
]
}
}
```
### 4. `get_media_info` - 获取媒体信息
获取已上传媒体的详细信息。
**参数说明：**
- `media_id` (字符串，必需): 要查询的媒体ID
**返回信息：**
- 媒体ID
- 媒体类型
- 文件大小
- 媒体URL（如果可用）
**示例：**
```json
{
"name": "get_media_info",
"arguments": {
"media_id": "1234567890123456789"
}
}
```
## 增强的现有功能
### `publish_draft` 功能增强
现在支持发布带媒体的草稿，系统会自动：
1. **上传媒体文件** - 自动上传草稿中的媒体文件
2. **应用Alt文本** - 为图片和GIF添加无障碍描述
3. **创建推文** - 使用上传的媒体ID创建推文
4. **清理草稿** - 发布成功后删除草稿文件
### `list_drafts` 功能增强
现在会显示媒体草稿的详细信息：
- 推文内容预览
- 媒体文件数量和类型
- 每个媒体文件的路径和Alt文本
- 草稿类型标识（tweet_with_media）
**显示示例：**
```
📷 媒体推文草稿: media_draft_1234567890.json
内容: 我的摄影作品集 📸
媒体文件: 2 个
- image: /path/to/photo1.jpg (Alt: 城市夜景，灯火通明)
- image: /path/to/photo2.jpg (Alt: 自然风光，绿树成荫)
```
## 数据结构说明
### 媒体推文草稿的JSON结构
```json
{
"content": "推文文本内容",
"media_files": [
{
"file_path": "/path/to/file.jpg",
"media_type": "image",
"alt_text": "图片的Alt文本描述"
}
],
"timestamp": "2025-09-17T10:30:00.000000",
"type": "tweet_with_media"
}
```
**字段说明：**
- `content`: 推文的文本内容
- `media_files`: 媒体文件信息数组
- `timestamp`: 草稿创建时间
- `type`: 草稿类型标识，值为 "tweet_with_media"
## 使用工作流程
### 工作流程1：直接发布媒体推文
1. **上传媒体**
- 用户：`"上传图片 /path/to/sunset.jpg，Alt文本为'美丽的日落'"`
- 系统调用 `upload_media`
- 返回媒体ID
2. **创建推文**
- 用户：`"使用媒体ID 123456789 创建推文'今天的日落真美！'"`
- 系统调用 `create_tweet_with_media`
- 立即发布带媒体的推文
### 工作流程2：草稿模式媒体推文
1. **创建媒体草稿**
- 用户：`"创建带媒体的推文草稿'我的作品集'，附加图片 /path/to/photo.jpg"`
- 系统调用 `create_draft_tweet_with_media`
- 草稿保存到本地文件系统
2. **查看和管理草稿**
- 用户：`"显示我的草稿"`
- 系统调用 `list_drafts`
- 显示包括媒体草稿在内的所有草稿
3. **发布草稿**
- 用户：`"发布这个媒体草稿"`
- 系统调用 `publish_draft`
- 自动上传媒体文件并发布推文
## 无障碍功能
### Alt文本支持
- **自动应用** - 为图片和GIF自动添加Alt文本
- **可选设置** - 用户可以为每个媒体文件单独设置Alt文本
- **无障碍合规** - 符合Web内容无障碍指南(WCAG)
### 文件验证
- **类型检查** - 验证文件类型与指定的媒体类型匹配
- **存在性检查** - 确保文件在指定路径存在
- **格式支持** - 支持主流的图片、视频和GIF格式
## 错误处理机制
### 🔧 媒体上传错误处理
**常见错误类型：**
1. **文件不存在**
```
File not found: /path/to/image.jpg
```
2. **文件类型不匹配**
```
File is not an image: /path/to/document.pdf
```
3. **文件大小限制**
```
File size exceeds Twitter's limits
```
4. **格式不支持**
```
Cannot determine media type for file
```
### 草稿保留机制
与其他功能一致，媒体功能也支持草稿保留：
- ✅ **上传失败时草稿被保留** - 用户可以修复文件问题后重试
- ✅ **发布成功时草稿被删除** - 避免重复发布
- ✅ **部分上传失败处理** - 记录已成功上传的媒体
## 技术实现细节
### 媒体上传流程
1. **文件验证** - 检查文件存在性和类型
2. **MIME类型检测** - 使用mimetypes库检测文件类型
3. **Twitter上传** - 使用tweepy的media_upload方法
4. **Alt文本应用** - 调用create_media_metadata添加描述
5. **返回媒体ID** - 提供给后续推文使用
### 支持的媒体限制
- **图片**: 最大5MB，支持JPG、PNG、WebP、GIF
- **视频**: 最大512MB，支持MP4、MOV
- **GIF**: 最大15MB
- **数量限制**: 每条推文最多4个媒体文件
### API调用说明
```python
# 上传媒体
media_upload = client.media_upload(filename=file_path)
media_id = media_upload.media_id_string
# 添加Alt文本
client.create_media_metadata(media_id=media_id, alt_text=alt_text)
# 创建带媒体的推文
response = client.create_tweet(text=content, media_ids=media_ids)
```
## 最佳实践建议
### 媒体文件准备
- **优化文件大小** - 压缩图片和视频以加快上传速度
- **选择合适格式** - 使用Twitter推荐的文件格式
- **准备Alt文本** - 为所有图片提供有意义的描述
### Alt文本编写指南
- **描述内容** - 简洁描述图片的主要内容
- **避免冗余** - 不要重复推文中已有的信息
- **保持简洁** - 控制在125个字符以内
- **关注重点** - 突出图片的关键信息
### 性能优化
- **批量上传** - 一次性准备多个媒体文件
- **本地缓存** - 保存媒体ID避免重复上传
- **异步处理** - 大文件上传时使用异步方式
### 安全考虑
- **文件扫描** - 确保上传的文件安全无害
- **路径验证** - 验证文件路径的合法性
- **权限检查** - 确保有读取文件的权限
## 兼容性说明
### Twitter API 兼容性
- 支持 Twitter API v2 媒体上传
- 兼容 tweepy 库的媒体功能
- 遵循 Twitter 的媒体政策和限制
### 文件系统兼容性
- 支持 Windows、macOS、Linux 文件路径
- 自动处理不同操作系统的路径分隔符
- 支持相对路径和绝对路径
## 使用示例
### 基础媒体上传
```bash
# 上传图片
"上传图片 /Users/username/photos/sunset.jpg，媒体类型为image，Alt文本为'海边的美丽日落'"
# 上传视频
"上传视频 /Users/username/videos/demo.mp4，媒体类型为video"
# 上传GIF
"上传GIF /Users/username/gifs/funny.gif，媒体类型为gif，Alt文本为'搞笑的猫咪动图'"
```
### 创建媒体推文
```bash
# 直接创建带媒体推文
"使用媒体ID 1234567890123456789 创建推文'今天的摄影作品 📸'"
# 创建多媒体推文
"使用媒体ID 123456789,987654321 创建推文'我的旅行照片合集 🌍'"
```
### 媒体草稿管理
```bash
# 创建媒体草稿
"创建带媒体的推文草稿'我的新项目展示'，附加文件 /path/to/screenshot.png，媒体类型image，Alt文本'项目界面截图'"
# 发布媒体草稿
"发布媒体草稿 media_draft_1234567890.json"
```
## 功能扩展可能性
未来可以考虑添加的相关功能：
- 媒体文件预处理（压缩、裁剪）
- 批量媒体上传管理
- 媒体文件本地缓存
- 视频缩略图生成
- 媒体文件元数据提取
- 自动Alt文本生成（AI辅助）
这个媒体功能的实现大大增强了用户创建丰富多媒体内容的能力，提供了完整、易用、无障碍的媒体推文解决方案。
