douyin-upload

name	douyin-upload
description	当你需要登录抖音账号、检查 Cookie、上传视频或发布图文时使用本技能。基于 `uv run douyin` 执行，无需额外自定义脚本。
tags	["Video","Social","Douyin"]
aliases	["抖音上传","上传视频","发布视频"]

功能概述

功能	说明
账号登录	扫码登录抖音创作者后台并生成 Cookie
Cookie 校验	检查指定账号的 Cookie 是否有效
视频上传	上传并发布抖音视频，支持标题、描述、标签、封面、商品链接、定时发布
图文发布	上传并发布抖音图文，支持多图、标题、正文、标签、定时发布

项目路径

SKILL_DIR=skills/douyin-upload/scripts

所有命令都在该目录执行：

cd skills/douyin-upload/scripts

首次初始化

在安装 uv 或执行 uv sync 之前，必须先判断当前服务器属于 domestic 还是 overseas。

区域判断规则（高优先级）

1. 优先看服务器实际地理区域 / 网络区域，不要看主机名风格
   • 阿里云、腾讯云、AWS、GCP 等厂商都同时有国内和海外机房
   • 例如：阿里云新加坡服务器属于 overseas，不能因为看起来像阿里云机器就误判为 domestic
2. 不要凭主机名、实例 ID、运维命名习惯主观猜测区域
3. 如果用户已经明确说明机器区域，优先使用用户提供的信息
4. 如果不确定，再使用实际部署区域信息或运维上下文确认；仍不确定时，默认按 overseas 处理，避免误走国内镜像路径

首次使用时执行：

国内服务器

cd skills/douyin-upload/scripts
sudo apt install -y pipx
PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple pipx install uv
UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv sync
uv run douyin --help

国外服务器

cd skills/douyin-upload/scripts
pipx install uv
uv sync
uv run douyin --help

说明：

• 国内服务器执行 uv sync 时，优先通过 UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple 使用国内镜像
• 历史上常见问题是：只给 pipx install uv 配了国内镜像，但 uv sync 仍然走默认 pypi.org，导致 opencv-python、patchright 等大包下载很慢；这里必须把 uv sync 的镜像源也显式写出来
• 必须先等 uv sync 完整结束，再执行任何 douyin 命令
• 不要跳过 uv sync 直接运行 uv run douyin ...
• uv run 虽然会隐式同步依赖，但大包下载期间容易让浏览器驱动在未就绪时启动，导致异常

入口交互规则（高优先级）

本技能负责最终登录校验与上传执行。 对于普通“上传抖音视频”“把这个视频发到抖音”这类请求，默认不要只运行本技能，而应把它视为一个多技能完整发布链路。

在聊天 / IM 场景中，默认链路必须按以下顺序执行：

1. 先做环境预热 / 环境检查
   • douyin-upload 环境是否可运行
   • video-analyze 环境是否可运行
   • 如果缺依赖，先补齐依赖，再进入后续步骤
2. 环境就绪后，再判断用户是否已经发送视频文件
   • 如果还没发文件，只引导用户直接发送视频文件
   • 不要一开始就索要服务器绝对路径
   • 不要一开始就要求填写标题、描述、标签等参数
3. 收到视频文件后，进入完整发布链路
   • 先执行 video-analyze
   • 再执行 content-adapt
   • 再让用户确认或修改发布信息
   • 最后才执行 douyin-upload

只有在以下条件同时满足时，才允许直接进入本技能的上传执行阶段：

• 用户已经明确提供完整发布参数
• 用户明确要求跳过分析 / 直接上传
• 视频文件已明确可用（用户已发送，或已明确说明服务器上的绝对路径）

只有在明确属于工程 / 运维场景、且用户自己说明“文件已经在服务器上”时，才可以要求用户提供服务器绝对路径。

推荐对用户的默认引导语：

可以，先把视频文件发给我。收到后我会先检查环境，然后分析视频内容、生成抖音发布信息，确认后再执行上传。

命令约定

登录

# 有头模式：首次登录推荐使用（会生成二维码）
uv run douyin login --account <account_name> --headed

# 无头模式：用于 Cookie 刷新
uv run douyin login --account <account_name> --headless

Cookie 校验

uv run douyin check --account <account_name>

视频上传

上传过程必须放到后台执行，并把日志重定向到文件，Agent 通过轮询日志判断进度与验证码状态。

cd skills/douyin-upload/scripts
uv run douyin upload-video \
  --account <account_name> \
  --file <视频绝对路径> \
  --title "视频标题" \
  --desc "视频描述" \
  --tags "标签1,标签2,标签3" \
  --headed > /tmp/douyin_upload.log 2>&1 &

启动后，持续轮询日志直到出现终态信号：

while true; do
  cat /tmp/douyin_upload.log
  grep -q "视频发布成功\|cookie 更新完毕\|upload.*success\|UPLOAD_FAILED\|ERROR" /tmp/douyin_upload.log 2>/dev/null && break
  sleep 5
done

⛔ 不要使用 sleep N && cat 这种一次性读日志方式。必须持续轮询，才能及时捕获 [VERIFY_REQUIRED] 和成功信号。

可选参数：

参数	说明	示例
--thumbnail <path>	竖版封面图	--thumbnail /path/to/cover.jpg
--product-link <url>	商品链接（需要店铺权限）	--product-link https://...
--product-title <text>	商品短标题，最多 10 字	--product-title "入门套餐"
--schedule "YYYY-MM-DD HH:MM"	定时发布，至少晚于当前 2 小时	--schedule "2026-04-20 18:00"
--headless / --headed	无头 / 有头模式	默认有头
--debug	开启调试模式，异常时截图	无

默认用 --headed，这样用户可以看到浏览器页面并在必要时配合验证。只有用户明确要求静默后台上传时，才使用 --headless。

图文上传

uv run douyin upload-note \
  --account <account_name> \
  --images <图片1路径> <图片2路径> \
  --title "图文标题" \
  --note "图文正文" \
  --tags "标签1,标签2" \
  --headed > /tmp/douyin_upload.log 2>&1 &

标准工作流

新账号首次使用

1. 先判断服务器区域
   - 中国大陆机器 → domestic
   - 新加坡 / 日本 / 美国 / 欧洲等海外机器 → overseas
   - 不确定时，默认按 overseas 处理，不要凭主机名猜测
2. domestic：安装 uv + 镜像 uv sync
   overseas：安装 uv + 普通 uv sync
3. 执行登录工作流（包含完整 check → login → check）
4. 再执行上传任务

日常上传

1. 先执行：uv run douyin check --account <name>
2. Cookie 有效 → 直接上传
3. Cookie 无效 → 先登录，再上传

批量上传（用户给目录或多个文件）

CLI 只支持单文件 --file，不支持直接传目录，所以批量上传时要拆成多个单文件上传。

流程：

1. 列出文件
   - 用户给目录 → 找出所有视频文件（mp4/mov/avi/flv/mkv）
   - 用户给多个文件路径 → 直接使用这些路径

2. 与用户确认上传列表
   - 哪些文件要上传
   - 标题规则：逐个指定 / 统一前缀 + 序号 / 直接用文件名
   - 标签是否统一
   ⛔ 未确认前不要开始上传

3. 只做一次登录校验
   uv run douyin check --account <name>

4. 顺序逐个上传
   - 单个文件失败时，记录失败原因，继续下一个
   - 不要因为一个文件失败就终止整个批量任务

5. 最后汇总
   - 成功 N 个
   - 失败 M 个（列出文件名和原因）

登录工作流（⛔ 必须严格按顺序执行）

第 0 步：先检查 Cookie 是否有效

uv run douyin check --account <account_name>

• 输出 valid → Cookie 有效，直接进入用户原始任务
• 输出 invalid 或文件不存在 → 继续后续登录流程

⛔ 不要跳过这一步直接登录。

第 1 步：清理旧二维码

cd skills/douyin-upload/scripts
rm -f cookies/*_login_qrcode_*.png

第 2 步：后台启动登录并重定向日志

cd skills/douyin-upload/scripts && uv run douyin login --account <account_name> --headed > /tmp/douyin_login.log 2>&1 &

说明：

• Linux 服务器上不要使用 xvfb-run
• 当前项目已针对服务器端 headless 场景做了适配
• 即使命令里传了 --headed，Linux 运行时也会内部自动切到稳定的 headless 路径

第 3 步：持续监控 [QRCODE_READY]，第一时间把二维码发给用户

启动登录后，必须持续观察 /tmp/douyin_login.log，一旦出现：

[QRCODE_READY] path=...

就立即取图并发给用户。

重要规则：

• 不要使用 sleep 10 && cat ... 或 sleep 15 && cat ...
• 不要等登录命令结束后才发二维码
• 不要轮询文件系统查找 *_login_qrcode_*.png
• 优先持续盯日志，而不是低频一次性读取
• 如果二维码过期，脚本会自动刷新并再次输出新的 [QRCODE_READY]

参考轮询方式：

while true; do
  QR=$(grep -o '\[QRCODE_READY\] path=.*' /tmp/douyin_login.log 2>/dev/null | tail -1 | sed 's/\[QRCODE_READY\] path=//')
  if [ -n "$QR" ]; then echo "$QR"; break; fi
  sleep 1
done

拿到二维码路径后，立即把图片发给用户。

发图规则：

• 如果当前渠道有专门的图片 / 文件发送能力，就优先用该能力
• 不要默认假设 MEDIA:绝对路径 在所有运行时都可用
• 某些运行时 / 渠道会因为安全策略拦截绝对路径媒体引用
• 在 IM 渠道（例如飞书类集成）里，优先用原生文件 / 图片发送方式
• 不要用 read_file 把图片当文本 / 二进制替代发送

发图后，再附带如下提示语（原样发送，不要改写）：

请使用抖音 App 扫描此二维码登录。

⚠️ 如果扫码后抖音出现“身份验证”页面，系统会自动选择“接收短信验证码”。收到验证码后请直接告诉我。

如果 90 秒内仍没有 [QRCODE_READY]：

• 检查日志里是否出现 Target page, context or browser has been closed
• 若出现，通常说明 Chromium 驱动未安装，执行：

uv run python -m patchright install chromium

第 4 步：继续监控身份验证与登录结果

二维码发出后，继续轮询日志：

while true; do
  cat /tmp/douyin_login.log
  grep -q '\[VERIFY_REQUIRED\]' /tmp/douyin_login.log 2>/dev/null && break
  grep -q '\[LOGIN_SUCCESS\]\|🥳 扫码成功' /tmp/douyin_login.log 2>/dev/null && break
  grep -q '\[LOGIN_FAILED\]' /tmp/douyin_login.log 2>/dev/null && break
  sleep 3
done

如果检测到 [VERIFY_REQUIRED]

脚本已经自动点击了“接收短信验证码”。 这时要：

1. 从日志中解析手机号提示，例如： [VERIFY_REQUIRED] phone=188******75 account=xxx
2. 立刻向用户索要验证码
3. 用户一回复验证码，不要沉默，必须先回一句确认，例如：
   • 已收到验证码，正在提交。
   • 收到，我现在提交验证码并检查登录状态。

然后执行：

cd skills/douyin-upload/scripts && uv run douyin verify --account <account_name> --code <user_code>

如果命令返回 [VERIFY_WRITTEN]，要立刻再同步一次进度，例如：

• 验证码已提交，正在等待抖音完成验证。
• 验证码已写入，正在检查是否登录成功。

如果检测到登录成功

不要闷头继续跑后续步骤，先同步进度，例如：

• 登录成功，正在校验账号状态并继续上传。
• 登录完成，我现在继续后续上传流程。

然后直接继续执行用户原始任务，不要再问“是否继续”。

如果检测到 [LOGIN_FAILED]

不要立即告诉用户失败，先做一次校验：

cd skills/douyin-upload/scripts && uv run douyin check --account <account_name>

• 如果返回 valid → 说明 Cookie 实际已保存成功，只是登录验证阶段超时，应视为登录成功
• 如果返回 invalid → 才视为真实失败，再询问用户是否重试

第 5 步：登录结束后做最终校验

uv run douyin check --account <account_name>

• 返回 valid → 继续用户任务
• 返回 invalid → 告知用户登录可能未完成，并询问是否重试

Cookie 管理

Cookie 文件位置：

skills/douyin-upload/scripts/cookies/douyin_<account_name>.json

说明：

• 每次成功上传后会自动刷新 Cookie
• Cookie 失效时重新执行登录工作流
• 不要在对话中输出 Cookie 内容

上传监控规则（⛔ 必须遵守）

后台启动上传后，持续观察 /tmp/douyin_upload.log：

1. 启动后先等 20–30 秒，再第一次读日志，确认进程已启动
2. 日志出现“uploading video” → 正常上传阶段
3. 日志出现“video upload complete” → 视频已传完，进入发布等待阶段
4. 日志出现“rushing to publish video” → 正常，开始计时
5. 日志出现 [VERIFY_REQUIRED] phone=xxx account=yyy → 立即进入短信验证码流程
6. 如果“rushing to publish”持续超过 2 分钟且没有 [VERIFY_REQUIRED] → 判定卡住
7. 如果整个上传流程超过 10 分钟仍无成功信号 → 判定卡住
8. 成功信号：日志出现“video published successfully” 且出现“cookie updated”
9. 长耗时阶段不要沉默：
   - 上传启动后要主动回一句：`视频开始上传了，我正在跟进发布进度。`
   - 发布成功但还没清理完成前，要主动回一句：`视频已发布成功，正在清理临时文件。`

上传阶段短信验证码流程

当日志里出现：

[VERIFY_REQUIRED] phone=xxx account=yyy

执行顺序：

1. 立刻通知用户（可按下面文案发送）：

抖音触发了短信验证，“获取验证码”按钮已自动点击。请查看 {phone} 收到的短信验证码，并直接告诉我。

2. 用户回复验证码后，立即执行：

uv run douyin verify --account <account> --code <user_code>

3. 如果输出 [VERIFY_WRITTEN]，立刻回复：

   • 验证码已提交，正在等待验证结果。

4. 如果验证码通过后上传继续推进，要同步阶段变化，例如：

   • 验证通过，正在继续发布流程。
   • 视频已发布成功，正在清理临时文件。

⛔ 同一状态不要无动作等待超过 2 分钟。

故障排查

现象	原因	处理方式
douyin: command not found	uv sync 未完成或环境未初始化	先判断服务器区域；domestic 执行 UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv sync，overseas 执行 uv sync
uv: command not found	系统未安装 uv	先判断服务器区域；domestic 执行 sudo apt install -y pipx && PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple pipx install uv，overseas 执行 pipx install uv，然后回到标准初始化流程
浏览器启动后立刻关闭 / Target page, context or browser has been closed	patchright Chromium 驱动未安装	执行 uv run python -m patchright install chromium
Linux 服务器上出现 Xvfb not found / no display	误用了旧的 xvfb-run 思路	不要使用 xvfb-run，直接按当前技能里的标准登录命令执行
Cookie 失效	长时间未使用或被平台踢下线	重新执行登录工作流
商品链接未生效	账号没有店铺权限	视频仍可正常发布，只是商品链接不会生效
上传失败	网络波动或平台异常	项目会自动重试一次；若仍失败，再向用户说明情况
定时发布时间报错	时间格式错误或不足 2 小时	检查 YYYY-MM-DD HH:MM 格式，并保证时间足够靠后
二维码过期	用户扫码过慢或二维码刷新未及时发送	脚本会自动刷新二维码，继续监控 [QRCODE_READY] 即可
扫码后卡住	抖音要求身份验证，但用户未完成	继续等待 [VERIFY_REQUIRED] 并引导用户提供验证码
发布阶段长时间卡住	平台风控或安全验证卡住	杀掉上传进程，必要时改用 --debug 重新尝试

降级策略

不可用项	影响	降级方式
浏览器不可用	无法登录 / 上传	无法降级，先修复浏览器与驱动问题
patchright Chromium 驱动未安装	浏览器启动失败	执行 uv run python -m patchright install chromium
Cookie 失效	无法直接上传	重新执行登录工作流
网络不稳定	上传过程中断	自动重试一次；仍失败则提示用户
定时时间不足 2 小时	参数校验失败	改为立即发布，但应先告知用户
商品链接权限缺失	商品链接设置失败	视频照常发布，并告知用户商品链接未生效