抖音网页版控制

douyin-web 是抖音网页版的底层动作库。这个 skill 的职责是指导 Agent 正确调用 CLI：执行动作、读取 JSON、查看截图、记录限制。它不负责“该看什么视频”“为什么点赞”“怎么做内容创作”等策略问题。

CLI 项目地址：

https://github.com/billwang233/douyin-web-cli

如果系统里还没有安装 CLI，先安装：

python3 -m pip install "git+https://github.com/billwang233/douyin-web-cli.git"
python3 -m playwright install chromium
douyin-web --help

先决策

使用本 skill 的场景：

• 用户要 Agent 操作抖音网页版。
• 用户要测试、验证、扩展 douyin-web CLI。
• 用户要打开抖音、检查登录、控制播放器、截图、录制、点赞、关注当前视频作者、收藏、分享、评论或弹幕。

不要用本 skill 的场景：

• 制定刷视频策略。
• 做推荐判断或内容偏好分析。
• 生成视频创意、脚本、选题。
• 处理创作者中心的完整发布流程。

命令入口

优先使用 skill 自带包装脚本：

skills/douyin-web-control/scripts/douyin-web --json COMMAND

包装脚本会按顺序寻找 CLI：

• $DOUYIN_WEB_CLI
• $DOUYIN_CLI_ROOT/bin/douyin-web
• 当前工作区或父目录下的 bin/douyin-web
• 已安装到 PATH 的 douyin-web
• 已安装到 PATH 的 cli-anything-douyin-web

如果需要指定浏览器会话目录，用：

--home ${DOUYIN_WEB_HOME}

如果没有指定，CLI 会使用自己的默认 home。测试时可以用隔离的临时 home：

--home ${DOUYIN_WEB_HOME:-/tmp/douyin-web-home}

并行多个项目时，优先使用全局 --profile，并且后续每条命令都带同一个 profile：

douyin-web --profile project-a --json launch
douyin-web --profile project-a --json open recommend
douyin-web --profile project-a --json current

douyin-web --profile project-b --json launch
douyin-web --profile project-b --json open jingxuan
douyin-web --profile project-b --json current

--profile NAME 会把会话、截图和浏览器数据隔离到 ~/.douyin-web-cli/profiles/NAME/。不要在同一条命令里混用 --profile 和 --home。

工作原则

• 优先通过 CLI 操作抖音，不要绕过 CLI 直接点网页；只有调试 CLI 实现时才直接检查 DOM 或页面。
• 并行项目必须全程使用各自的 --profile；如果后续命令漏掉 profile，会回到默认会话。
• 页面动作默认截图。读取 JSON 里的 data.screenshot.path 做视觉确认。
• 如果弹出登录页、验证码、滑块验证、短信验证、账号风控或任何真人验证，不要尝试绕过、自动识别或自动填写。立即停下来提示用户人工处理；用户确认完成后，再运行 douyin-web --json status 或 douyin-web --json wait-login --timeout 300 确认状态，然后继续后续动作。
• 对账号有影响的动作，例如 like、follow-author、favorite、share、comment --submit、danmaku-send --submit，执行前确认用户允许。
• 对视觉状态不稳定的动作，例如 danmaku off、loop、点赞/收藏高亮状态，只报告 CLI 结果和截图，不要声称绝对确认。
• 如果用户要求“测试 CLI”，必须用 douyin-web 命令执行测试。

常用工作流

登录、验证码和风控处理：

douyin-web --json status
douyin-web --json wait-login --timeout 300

如果 status 显示未登录，或者截图里出现验证码/登录/验证页面，停止当前自动化流程，向用户说明需要人工登录或验证。不要继续点击、不要尝试破解验证码。用户确认处理完成后，再重新运行 status 或 wait-login。

检查会话和登录：

douyin-web --json state
douyin-web --json status
douyin-web --json wait-login --timeout 300

打开页面：

douyin-web --json launch
douyin-web --json open recommend
douyin-web --json open jingxuan
douyin-web --json open ai-search
douyin-web --json open follow
douyin-web --json open friends
douyin-web --json open mine
douyin-web --json open live
douyin-web --json open vs
douyin-web --json open series

查看当前状态：

douyin-web --json current
douyin-web --json info
douyin-web --json screenshot /tmp/douyin-current.png

播放器控制：

douyin-web --json play state
douyin-web --json play pause
douyin-web --json play resume
douyin-web --json play toggle
douyin-web --json next
douyin-web --json prev
douyin-web --json seek --seconds 30
douyin-web --json seek --percent 50
douyin-web --json rate 1.25
douyin-web --json volume 0.8
douyin-web --json sound on
douyin-web --json sound off

修改倍速或音量后，测试结束时尽量恢复：

douyin-web --json rate 1
douyin-web --json volume 1

显示和沉浸控制：

douyin-web --json clean
douyin-web --json fullscreen
douyin-web --json danmaku off
douyin-web --json loop
douyin-web --json prepare
douyin-web --json dismiss
douyin-web --json press Escape

搜索和互动：

douyin-web --json search "关键词"
douyin-web --json search "关键词" --no-submit
douyin-web --json comments open
douyin-web --json comments close
douyin-web --json comment "评论草稿" --no-submit
douyin-web --json danmaku-send "弹幕草稿" --no-submit
douyin-web --json like
douyin-web --json follow-author
douyin-web --json favorite
douyin-web --json share

录制：

douyin-web --json devices
douyin-web --json record /tmp/douyin-record.mp4 --duration 15 --video-index VIDEO_INDEX --audio-index AUDIO_INDEX --verify

录制注意事项：

• 系统音频优先用 BlackHole 2ch。
• 默认拒绝非 BlackHole 音频，避免误录麦克风。
• 每次录制前先跑 devices，因为 AVFoundation 设备编号可能变化。
• 桌面自动化环境可能把前台窗口切回工具本身，所以 MP4 生成成功不一定代表画面就是抖音；需要截图、抽帧或人工验证。

测试建议

自动测试：

cd ${DOUYIN_CLI_ROOT}/agent-harness
python3 -m pytest -q -rs

真实 CLI 测试：

• 一次测试一个动作，或只做小批量连续动作。
• 查看 JSON 的 ok、message 和关键 data 字段。
• 查看 data.screenshot.path。
• 如果失败，优先修 CLI 或记录为 CLI 限制，不要用直接浏览器操作掩盖失败。

功能矩阵

需要完整功能范围、适合/不适合 CLI 化的边界、下一批待补命令时，读取：

references/feature-matrix.md