video-uploader

视频上传技能

使用 Playwright 浏览器自动化，结合全面的反检测措施和字段生成功能，自动将视频上传至中国及国际主流社交媒体平台。

支持的平台

抖音（Douyin）：中国领先的短视频平台，全面支持封面图、商品链接、定时发布，以及同步至头条／西瓜视频等第三方平台。

快手（Kuaishou）：热门中国短视频平台，支持标题、话题标签（最多 3 个）以及带确认对话框的定时发布。

小红书（Xiaohongshu）：中国生活方式与社交电商平台，支持图文和视频笔记；上传使用 API，并需要签名服务。

TikTok：国际短视频平台，使用 Firefox 浏览器，支持标题、话题标签、定时发布（按 5 分钟为间隔）和隐私控制。

腾讯视频／微信视频号（Tencent Video / WeChat Channels）：微信集成的视频平台，支持短标题格式、合集、原创内容声明和分类选择。

前置条件

Python 环境：已安装 Python 3.8+ 和 pip。

依赖项：从 references/requirements.txt 安装：

sudo pip3 install playwright==1.52.0 loguru==0.7.3 requests==2.32.3 PyYAML==6.0.2

Playwright 浏览器：安装软件包后进行安装：

playwright install chromium firefox

账号 Cookie：每个平台都需要 Cookie 文件进行身份验证（Playwright storage state JSON 格式）。首次使用时会触发浏览器登录窗口。

核心脚本

1. 直接上传脚本

scripts/upload_video.py — 用于直接上传的命令行界面。

基本用法：

python scripts/upload_video.py \
  --platform douyin \
  --title "Video Title" \
  --video /path/to/video.mp4 \
  --tags "tag1,tag2,tag3" \
  --account /path/to/cookie.json

必需参数：

• --platform：目标平台（douyin/kuaishou/tiktok/tencent/xhs）
• --title：视频标题（长度限制因平台而异）
• --video：MP4 视频文件的绝对路径
• --tags：以逗号分隔的话题标签，不带 # 前缀
• --account：Cookie JSON 文件的绝对路径

可选参数：

• --publish-date：定时发布时间，格式为 "YYYY-MM-DD HH:MM:SS"；输入 0 则立即发布
• --thumbnail：封面图片路径（仅限抖音）
• --product-link：商品 URL（仅限抖音）
• --product-title：商品短标题（仅限抖音）
• --category：视频分类（仅限腾讯视频）

2. 基于配置的上传

scripts/upload_from_config.py — 从 JSON/YAML 配置文件上传。

单个上传：

python scripts/upload_from_config.py config.json

批量上传：

python scripts/upload_from_config.py batch_config.json --batch

配置格式（JSON）：

{
  "platform": "douyin",
  "video": {
    "path": "/path/to/video.mp4",
    "title": "Video Title",
    "description": "Description text",
    "tags": ["tag1", "tag2", "tag3"]
  },
  "account": {
    "cookie_file": "/path/to/cookie.json"
  },
  "options": {
    "publish_date": "2024-12-31 18:00:00",
    "thumbnail": "/path/to/thumbnail.jpg"
  }
}

配置格式（YAML）：

platform: douyin
video:
  path: /path/to/video.mp4
  title: Video Title
  description: Description text
  tags:
    - tag1
    - tag2
    - tag3
account:
  cookie_file: /path/to/cookie.json
options:
  publish_date: "2024-12-31 18:00:00"
  thumbnail: /path/to/thumbnail.jpg

3. 字段生成工具

scripts/generate_upload_config.py — 根据视频文件自动生成上传配置。

生成配置：

python scripts/generate_upload_config.py \
  --platform douyin \
  --video /path/to/video.mp4 \
  --output json

自动生成的内容：

• 标题：从文件名提取并智能格式化
• 标签：从标题提取并过滤停用词
• 描述：根据标题扩展生成
• 短标题：为腾讯视频自动格式化（6-16 个字符，并遵循特殊规则）

输出格式：

• --output json：JSON 配置文件
• --output yaml：YAML 配置文件
• --output command：可直接使用的命令行
• --output-file：保存到文件，而不是标准输出

生成定时发布时间：

python scripts/generate_upload_config.py \
  --platform douyin \
  --video /path/to/video.mp4 \
  --schedule-days 1 \
  --schedule-hour 18 \
  --output command

平台专属字段

抖音（Douyin）

必需字段：title（最多 30 个字符）、video_path、tags、account_file

可选字段：publish_date、thumbnail_path（竖版）、product_link、product_title（最多 10 个字符）、description、location、sync_third_party

自动生成字段：title、tags、description、thumbnail（从视频帧生成）

注意：自动检测两种页面版本（v1/v2）；支持同步至头条／西瓜视频等第三方平台

快手（Kuaishou）

必需字段：title、video_path、tags（最多 3 个）、account_file

可选字段：publish_date、description

自动生成字段：title、tags（最多 3 个）、description

注意：话题标签最多 3 个；需要确认对话框

TikTok

必填：title、video_path、tags、account_file

可选：publish_date（以 5 分钟为间隔）、description、privacy（public/friends/private）、allow_comments、allow_duet、allow_stitch

自动生成：title、tags、description

备注：使用 Firefox（而非 Chromium），有两种 UI 版本（iframe/直接）

腾讯视频 / 微信视频号（视频号）

必填：title、video_path、tags、account_file

可选：publish_date、short_title（6-16 个字符）、category、is_original、collection_id、description

自动生成：title、tags、short_title（自动格式化）、description、category

备注：短标题格式规则（允许使用的字符： 《》"":+?%°），需要系统 Chrome

小红书（小红书）

必填：title、video_path、tags、account_file

可选：publish_date、description、cover_path、location、post_type（视频/图片）、images

自动生成：title、tags、description、cover_path

备注：需要单独的 Flask 签名服务，支持视频和图片帖子

浏览器反检测配置

该技能在 scripts/utils/browser_config.py 中包含全面的反检测措施：

Chromium 参数：

• 禁用自动化控制标志
• 禁用 blink 特性检测
• 自定义 user agent 和视口
• 地理位置伪装（中国平台使用北京）
• 时区配置
• 插件和语言伪装

Firefox 参数：

• 语言和区域设置配置
• 自定义 user agent
• 时区设置

运行时脚本：

• 覆盖 navigator.webdriver
• 覆盖 navigator.plugins
• 覆盖 navigator.languages
• 添加 chrome 属性
• 覆盖权限查询

平台专属配置：每个平台都有经过优化的浏览器配置，由 get_platform_specific_config(platform) 返回。

身份验证和 Cookie 管理

首次登录：当 Cookie 文件缺失或过期时，脚本会打开浏览器窗口以便手动登录（二维码/凭据）。成功登录后，会话 Cookie 将保存到指定文件。

Cookie 验证：每次上传前，脚本都会通过访问上传页面验证 Cookie。若验证失败，则会触发登录流程。

Cookie 存储：Playwright 存储状态格式（JSON），包含会话数据、令牌和身份验证信息。

Cookie 重用：有效的 Cookie 文件可重复用于多次上传，直至过期（通常为 7-30 天）。

推荐的组织方式：

/home/ubuntu/cookies/
├── douyin_account1.json
├── douyin_account2.json
├── kuaishou_account.json
├── tiktok_account.json
└── tencent_account.json

OpenClaw 集成工作流

步骤 1：准备视频文件

• 确保视频文件位于可访问的路径
• 确认格式为 MP4
• 检查平台要求（时长、大小、分辨率）

步骤 2：生成配置

python scripts/generate_upload_config.py \
  --platform douyin \
  --video /path/to/video.mp4 \
  --schedule-days 1 \
  --output-file config.json

步骤 3：审核并自定义

• 编辑生成的 config.json
• 添加平台专属选项
• 根据需要调整标题、标签和描述

步骤 4：执行上传

python scripts/upload_from_config.py config.json

步骤 5：验证上传

• 查看控制台输出中的成功/错误消息
• 在平台上检查已发布的视频
• 如适用，确认预约发布时间

批量上传工作流

创建批量配置：

[
  {
    "platform": "douyin",
    "video": {
      "path": "/path/to/video1.mp4",
      "title": "Video 1 Title",
      "tags": ["tag1", "tag2"]
    },
    "account": {
      "cookie_file": "/path/to/douyin.json"
    }
  },
  {
    "platform": "tiktok",
    "video": {
      "path": "/path/to/video2.mp4",
      "title": "Video 2 Title",
      "tags": ["tag3", "tag4"]
    },
    "account": {
      "cookie_file": "/path/to/tiktok.json"
    }
  }
]

执行批量上传：

python scripts/upload_from_config.py batch.json --batch

批量摘要：显示上传总数、成功数、失败数和错误详情。

故障排除

Cookie 过期错误：删除旧 Cookie 文件并运行脚本，以触发重新登录。

上传失败错误：检查视频格式、大小、网络连接和平台专属要求。

找不到浏览器错误：安装 Playwright 浏览器：playwright install chromium firefox

页面结构已更改错误：平台 UI 可能已更改。检查脚本更新，或手动检查页面结构。

无头模式问题：大多数平台都需要使用非无头模式。上传期间浏览器窗口会显示。

反检测绕过：如果平台检测到自动化，请检查 scripts/utils/browser_config.py 中的浏览器配置，并确保已加载 stealth.min.js。

参考文件

platform_fields.md：所有平台的完整字段规范，包括必填／可选／自动生成的字段、示例和限制。

platform_details.md：各平台的详细信息，包括 URL、身份验证方式、功能和特别说明。

requirements.txt：Python 包依赖。

模板

upload_config_template.json：包含所有字段的 JSON 配置模板。

upload_config_template.yaml：包含所有字段的 YAML 配置模板。

高级编程用法

直接导入上传器模块进行自定义集成：

import asyncio
from scripts.douyin_uploader.main import DouYinVideo, douyin_setup

async def upload():
    account_file = "/path/to/cookie.json"
    await douyin_setup(account_file, handle=True)
    
    video = DouYinVideo(
        title="My Video Title",
        file_path="/path/to/video.mp4",
        tags=["tag1", "tag2", "tag3"],
        publish_date=0,
        account_file=account_file
    )
    
    await video.main()

asyncio.run(upload())

限制

小红书集成：由于签名服务要求复杂，尚未完全集成。签名生成需要单独的 Flask 服务。

浏览器可见性：大多数平台要求使用非无头模式。上传期间浏览器窗口会保持可见。

手动登录：首次身份验证需要手动操作（扫描二维码／输入凭据）。由于平台安全要求，无法完全自动化。

平台变更：社交媒体平台会频繁更新界面和安全机制。平台更改上传界面后，脚本可能需要更新。

沙盒测试：无法在无头沙盒环境中测试实际上传。已验证浏览器配置，但实际上传测试需要图形环境。