重构douyin上传，增加douyin图文

修复douyin视频封面上传
2026-03-24 23:02:22 +08:00
parent fe6e9f4af9
commit 90845f50ad
18 changed files with 1303 additions and 230 deletions
@@ -0,0 +1,92 @@
+# CLI 使用说明
+
+项目现在提供一个更直接的抖音 CLI 入口，默认推荐使用 `sau`。
+
+实现说明：
+
+- `sau_cli.py` 是当前 CLI 的主入口和唯一主要实现文件
+- `sau.exe` 是安装后在 Windows 虚拟环境里自动生成的命令入口，本质上还是调用 `sau_cli.py`
+- 如果需要给 OpenClaw、Codex 等 agent 使用，可参考仓库内 skill：`skills/douyin-upload/`
+
+## 安装 CLI 入口
+
+如果你希望直接使用 `sau` 命令，而不是手动执行 `python sau_cli.py`，先在项目根目录安装一次：
+
+```bash
+uv pip install -e .
+```
+
+安装后就可以直接使用：
+
+```bash
+sau douyin --help
+```
+
+## 安装 patchright 浏览器
+
+Windows 下推荐先指定镜像，再安装 Chromium：
+
+```powershell
+$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium
+```
+
+## 抖音 CLI 子命令
+
+```bash
+sau douyin login --account creator
+sau douyin login --account creator --headless
+sau douyin check --account creator
+sau douyin upload-video --account creator --file videos/demo.mp4 --title "示例标题" --tags 运动,训练
+sau douyin upload-note --account creator --images videos/1.png videos/2.png --note "图文示例" --tags 图文,测试
+```
+
+## 定时发布
+
+视频和图文都支持 `--schedule`。只要传了 `--schedule`，CLI 就会自动切换到 `scheduled` 发布策略；不传则默认立即发布。
+
+```bash
+sau douyin upload-video --account creator --file videos/demo.mp4 --title "示例标题" --schedule "2026-03-24 21:30"
+sau douyin upload-note --account creator --images videos/1.png videos/2.png --note "图文示例" --schedule "2026-03-24 21:30"
+```
+
+## 运行时参数
+
+CLI 将 `debug` 和 `headless` 拆成了两个独立维度：
+
+```bash
+--debug
+--headless
+--headed
+```
+
+- `--debug`: 打开调试行为，例如失败时保留更多调试信息
+- `--headless`: 无头模式运行
+- `--headed`: 有头模式运行
+
+如果都不传，CLI 当前默认按 `headless=True` 运行。
+
+## 视频上传参数
+
+```bash
+--file videos/demo.mp4
+--title "示例标题"
+--tags 运动,训练
+--thumbnail videos/demo.png
+--product-link https://example.com/item
+--product-title 示例商品
+```
+
+## 图文上传参数
+
+```bash
+--images videos/1.png videos/2.png videos/3.png
+--note "图文内容"
+--tags 图文,测试
+```
+
+图文上传当前限制：
+
+- 最多 35 张图片
+- 不支持 GIF
+
+后续维护 CLI 时，优先看 `sau_cli.py` 和 `uploader/`。
@@ -0,0 +1,153 @@
+# 安装说明
+
+这个文档分成两部分：
+
+- `For Humans`：给正常使用仓库的开发者、创作者、CLI 用户看
+- `For AI Agents`：给 OpenClaw、Codex、Claude Code 一类 agent 看
+
+## For Humans
+
+### 1. 克隆项目
+
+```bash
+git clone https://github.com/dreammis/social-auto-upload.git
+cd social-auto-upload
+```
+
+### 2. 创建虚拟环境
+
+推荐使用 `uv`：
+
+Windows PowerShell：
+
+```powershell
+uv venv
+.venv\Scripts\activate
+```
+
+Linux / macOS：
+
+```bash
+uv venv
+source .venv/bin/activate
+```
+
+### 3. 安装主线依赖
+
+当前主线依赖已经放到 `pyproject.toml`，推荐直接执行：
+
+```bash
+uv pip install -e .
+```
+
+安装完成后，会注册 `sau` 命令。
+
+### 4. 安装 patchright Chromium
+
+当前主线使用 `patchright` 驱动浏览器。
+
+国内用户推荐先指定镜像，再安装 Chromium。
+
+Windows PowerShell：
+
+```powershell
+$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium
+```
+
+Linux / macOS：
+
+```bash
+PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium
+```
+
+### 5. 配置 conf.py
+
+复制一份配置：
+
+```bash
+cp conf.example.py conf.py
+```
+
+Windows 也可以直接手动复制并重命名。
+
+当前通常还会用到这些配置项：
+
+- `LOCAL_CHROME_PATH`
+- `LOCAL_CHROME_HEADLESS`
+- `DEBUG_MODE`
+
+`XHS_SERVER` 目前只和小红书旧流程相关。
+
+### 6. 验证 CLI 是否可用
+
+```bash
+sau --help
+sau douyin --help
+```
+
+如果命令找不到，优先确认：
+
+- 当前虚拟环境是否已激活
+- 是否执行过 `uv pip install -e .`
+
+### 7. 抖音主线示例
+
+```bash
+sau douyin login --account creator
+sau douyin check --account creator
+sau douyin upload-video --account creator --file videos/demo.mp4 --title "示例标题"
+```
+
+## For AI Agents
+
+如果你是一个可执行命令的 agent，请优先按下面顺序处理：
+
+1. 先假设仓库根目录就是当前工作目录
+2. 优先使用 `uv` 管理环境，不要默认回退到旧的 `requirements.txt`
+3. 安装命令优先使用：
+
+```bash
+uv pip install -e .
+```
+
+4. 如需浏览器驱动，优先使用：
+
+Windows PowerShell：
+
+```powershell
+$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium
+```
+
+Linux / macOS：
+
+```bash
+PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium
+```
+
+5. 安装完成后，优先检查：
+
+```bash
+sau --help
+sau douyin --help
+```
+
+6. 如果用户的目标是抖音登录、cookie 校验、视频上传、图文上传，优先走 CLI：
+
+```bash
+sau douyin login
+sau douyin check
+sau douyin upload-video
+sau douyin upload-note
+```
+
+7. 如果用户明确在使用 skill 系统，再引导其阅读：
+
+- `skills/douyin-upload/SKILL.md`
+- `skills/douyin-upload/references/cli-contract.md`
+
+### 对 agent 的额外说明
+
+- `requirements.txt` 目前是历史兼容文件，不是主安装入口
+- `uploader/` 是核心实现目录
+- `sau_cli.py` 是当前 CLI 主入口
+- `docs/legacy-web.md` 是历史 Web 版本说明，不保证当前可用
@@ -0,0 +1,49 @@
+# 历史 Web 版本说明
+
+这套 Web 相关代码主要包括：
+
+- `sau_backend.py`
+- `sau_backend/`
+- `sau_frontend/`
+
+它们属于项目过去阶段的实现，当前已经不是主线维护方向。
+
+## 当前定位
+
+- 作为历史版本保留
+- 作为过去 API / Web 封装思路的参考
+- 不承诺当前一定可直接运行
+- 不承诺和当前 `uploader/`、`sau_cli.py` 的最新实现完全同步
+
+## 为什么单独拆出来说明
+
+当前工程正在整体重构，主线已经切到：
+
+- `uploader/`：核心平台实现
+- `sau_cli.py`：CLI 主入口
+- `skills/`：面向 agent 的 skill
+
+所以 README 不再把 Web 版本当成主入口来介绍，避免让新用户误以为这是当前最稳定的使用方式。
+
+## 如果你仍然想研究这套历史 Web 版本
+
+可以参考这些文件：
+
+- `sau_backend/README.md`
+- `sau_frontend/README.md`
+- `sau_backend.py`
+
+但请预期：
+
+- 接口契约可能与当前主线不一致
+- 平台能力覆盖可能落后于当前 `uploader/`
+- 依赖和运行方式可能需要自行排障
+
+## 当前推荐入口
+
+如果你要使用当前主线能力，优先看：
+
+- `uploader/`
+- `sau_cli.py`
+- `docs/CLI.md`
+- `skills/douyin-upload/SKILL.md`
@@ -0,0 +1,286 @@
+# Skill 分发与发布说明
+
+这份文档是给 `social-auto-upload` 后续做独立 skill 分发时用的。
+
+当前仓库已经具备两层能力：
+
+- 一个可安装的 CLI：`sau`
+- 一个可被安装到 Codex 的内置 skill：`douyin-cli`
+
+后续当主流程和 bug 修复完成后，可以再继续做 PyPI 发布、安装优化、以及更多平台的独立 skill。
+
+## 先说结论
+
+`skill` 不一定必须是一个 Python 包。
+
+它可以是：
+
+- 一个 skill 目录
+- 一个独立仓库
+- 一个安装器脚本
+- 一个 Docker 镜像
+- 一个包管理器可安装的分发物
+
+但从“别人最快安装和使用”的角度看，最常见、最省事的仍然是：
+
+1. 用一个安装包分发真正的运行能力
+2. 用一个 skill 安装动作把 skill 放到 AI 工具的技能目录
+
+对这个项目来说，最推荐的形式是：
+
+- Python 包负责提供 `sau` 命令
+- `sau skill install` 负责把 skill 安装到 `~/.codex/skills/`
+
+也就是：
+
+```bash
+pip install social-auto-upload
+sau skill install
+```
+
+## skill 一定要是包吗
+
+不是。
+
+### 1. skill 只是一个目录
+
+这是最原始也最常见的形式。
+
+通常内容是：
+
+- `SKILL.md`
+- `agents/openai.yaml`
+- `references/`
+- `scripts/`
+
+这种形式本身已经是一个可用 skill 了，不一定需要打包。
+
+问题在于：
+
+- 用户要知道把它复制到哪里
+- 用户要手动安装
+- skill 如果依赖额外脚本或运行时，安装体验会比较差
+
+适合：
+
+- 内部团队
+- 仓库内开发规范
+- 还在快速迭代的 skill
+
+### 2. skill 是一个独立仓库
+
+这也完全成立。
+
+例如：
+
+- 一个仓库专门放 `SKILL.md`
+- 附带 `scripts/install.py`
+- 或者 README 教用户复制到 `~/.codex/skills/`
+
+这种模式的优点是：
+
+- skill 自己独立版本管理
+- 不依赖主业务仓库
+- 可以公开发布
+
+缺点是：
+
+- 用户还是可能要 clone
+- 或者还需要执行安装脚本
+
+适合：
+
+- 想把 skill 当产品独立维护
+- skill 和业务代码已经明显拆开
+
+### 3. skill 跟随一个包分发
+
+这是当前这个项目最适合的方向。
+
+思路是：
+
+- Python 包里内置一份 skill 资源
+- 安装包后即可执行 `sau skill install`
+- CLI 和 skill 一起发版
+
+优点是：
+
+- 用户体验最好
+- skill 和实际命令保持一致
+- 版本对应关系清晰
+- 不需要用户 clone 仓库
+
+适合：
+
+- skill 背后有真实 CLI/SDK/工具
+- 用户最终是要“使用能力”而不只是“阅读说明”
+
+### 4. skill 用 Docker 交付
+
+也可以。
+
+常见方式是：
+
+- Docker 里装好运行环境
+- skill 告诉 AI 通过 `docker run ...` 去执行命令
+
+优点是：
+
+- 环境一致性很好
+- 本地依赖复杂时特别有用
+
+缺点是：
+
+- 用户必须先装 Docker
+- 浏览器自动化、桌面登录、cookie、本地文件挂载都会更复杂
+- 对抖音这种需要本地浏览器交互的流程不一定更友好
+
+对当前项目来说，Docker 更适合：
+
+- 后端服务
+- 批处理任务
+- 服务器环境
+
+不太适合作为“普通用户首次使用抖音登录 skill”的唯一交付方式。
+
+## AI 安装环境、启动脚本、仓库，这些算不算 skill
+
+算，但要区分“skill 本体”和“skill 的安装/运行载体”。
+
+可以这样理解：
+
+- `SKILL.md` 是 skill 本体
+- 仓库、包、Docker、安装脚本，是 skill 的分发和运行载体
+
+所以：
+
+- skill 可以住在仓库里
+- skill 可以被包一起带出去
+- skill 也可以借助 Docker 运行它依赖的环境
+
+只要最终用户能：
+
+1. 安装它
+2. 让 AI 发现它
+3. 真正调用它依赖的能力
+
+那它就是成立的。
+
+## 对这个项目最合适的方案
+
+### 当前推荐方案
+
+第一阶段：
+
+- 继续在这个仓库里修主流程和 bug
+- 保持 `sau` 命令稳定
+- 保持包内 skill 与 CLI 契约一致
+
+第二阶段：
+
+- 打包并发布到 PyPI
+- 用户通过 `pip install social-auto-upload` 安装
+- 用户执行 `sau skill install`
+
+第三阶段：
+
+- 根据需要把更多平台拆成独立 skill
+- 例如 `douyin-cli`、`tencent-cli`、`tiktok-cli`
+
+### 为什么现在不优先做“独立 skill 仓库”
+
+因为当前最核心的问题还不是“skill 放哪”，而是：
+
+- 上传流程是否稳定
+- CLI 契约是否稳定
+- 实际用户安装后能不能跑通
+
+在这些都还在收敛的阶段，先让 skill 随包分发是最稳妥的。
+
+## 未来可选的三种正式发布路线
+
+### 路线 A：PyPI 包 + 包内 skill
+
+用户安装：
+
+```bash
+pip install social-auto-upload
+sau skill install
+```
+
+优点：
+
+- 最容易传播
+- 安装简单
+- 版本管理清晰
+
+这是当前首选路线。
+
+### 路线 B：独立 skill 仓库 + PyPI 包
+
+用户安装能力：
+
+```bash
+pip install social-auto-upload
+```
+
+用户安装 skill：
+
+- clone skill 仓库
+- 或跑 skill 仓库提供的安装脚本
+
+优点：
+
+- skill 可以单独演进
+- 可以给不同 AI 工具维护不同 metadata
+
+缺点：
+
+- 安装链路更长
+
+### 路线 C：Docker + skill
+
+用户：
+
+- 安装 Docker
+- 拉镜像
+- 安装 skill
+- skill 内部调用 docker 命令
+
+优点：
+
+- 依赖环境最稳定
+
+缺点：
+
+- 对本地浏览器自动化和交互式登录不够友好
+
+更适合服务端任务，不是当前首选。
+
+## 当前项目的发布建议
+
+当主流程稳定后，建议按这个顺序走：
+
+1. 先保证 `sau douyin login/check/upload` 真机可用
+2. 验证 `sau skill install` 安装后的 skill 可以被 Codex 正常识别
+3. 本地打 wheel 做一次冷启动安装测试
+4. 再发布 PyPI
+
+建议的最终用户路径是：
+
+```bash
+pip install social-auto-upload
+playwright install chromium
+sau skill install
+sau douyin login --account my-account
+```
+
+## 一句话回答
+
+`skill` 不是必须做成包，但如果你想让别人“最快安装、最少理解成本、最少手工操作”，那就最好让“运行能力”走包分发，让 `skill` 跟着包一起被安装。
+
+对这个项目来说，最佳落地方案不是“只发一个 skill 仓库”，而是：
+
+- `social-auto-upload` 作为可安装包
+- `douyin-cli` 作为包内 skill
+- `sau skill install` 作为安装桥梁
@@ -0,0 +1,98 @@
+# 更新说明
+
+这个文档分成两部分：
+
+- `For Humans`：给正常使用仓库的人看
+- `For AI Agents`：给能执行命令和自动排查的 agent 看
+
+## For Humans
+
+### 1. 拉取最新代码
+
+```bash
+git pull
+```
+
+如果你平时是切分支开发，请先确认当前所在分支。
+
+### 2. 更新本地可编辑安装
+
+如果仓库最近改了 CLI、入口脚本、依赖配置，建议重新执行：
+
+```bash
+uv pip install -e .
+```
+
+### 3. 如有需要，更新浏览器依赖
+
+当前主线使用 `patchright`。
+
+Windows PowerShell：
+
+```powershell
+$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium
+```
+
+Linux / macOS：
+
+```bash
+PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium
+```
+
+### 4. 更新后自检
+
+建议至少检查：
+
+```bash
+sau --help
+sau douyin --help
+sau douyin check --account your_account
+```
+
+如果你在使用 skill，也建议同步看一下：
+
+- `skills/douyin-upload/SKILL.md`
+- `docs/CLI.md`
+
+## For AI Agents
+
+如果你是 agent，更新仓库后建议按下面顺序做最小验证：
+
+1. 拉取最新代码：
+
+```bash
+git pull
+```
+
+2. 重新同步本地安装：
+
+```bash
+uv pip install -e .
+```
+
+3. 如需浏览器驱动，更新 `patchright` Chromium
+
+4. 重新验证 CLI：
+
+```bash
+sau --help
+sau douyin --help
+```
+
+5. 如果任务是抖音链路，再继续验证：
+
+```bash
+sau douyin check --account test
+```
+
+6. 如果用户依赖 skill，再检查这些路径是否仍存在且契约没变：
+
+- `skills/douyin-upload/SKILL.md`
+- `skills/douyin-upload/references/cli-contract.md`
+- `skills/douyin-upload/references/runtime-requirements.md`
+
+### 对 agent 的额外说明
+
+- 优先相信 `pyproject.toml`，不要把 `requirements.txt` 视为当前主线真相
+- 当前 README 只做总览，安装和更新以 `docs/install.md`、`docs/update.md` 为准
+- Web 相关内容属于历史路径，见 `docs/legacy-web.md`