social-auto-upload 安装与配置实战：从 uv 环境搭建到 sau CLI 可用的完整路径-平芜编程栈

social-auto-upload 安装与配置实战：从 uv 环境搭建到 sau CLI 可用的完整路径

【免费下载链接】social-auto-upload自动化上传视频到社交媒体：抖音、小红书、视频号、tiktok、youtube、bilibili项目地址: https://gitcode.com/GitHub_Trending/so/social-auto-upload

本文基于仓库 docs/install.md 展开，完整覆盖 social-auto-upload 的主线安装流程：克隆仓库、用uv创建虚拟环境、通过pyproject.toml安装可编辑包并注册sau命令、为patchright安装 Chromium、配置conf.py，以及抖音/快手/小红书/Bilibili 四个平台的登录与上传验证命令。读完本文，你能独立完成从裸环境到sau <platform> upload-video可运行的全部准备工作，并理解每一步背后的实现依据。

一、文档结构：人读与 Agent 读的两条路径

安装说明明确把读者分成两类：

For Humans：给直接使用仓库的开发者、创作者、CLI 用户看，覆盖从克隆到首次上传的完整手工流程；
For AI Agents：给 OpenClaw、Codex、Claude Code 一类 agent 看的执行清单，约定 agent 应以仓库根目录为工作目录、优先用uv管理环境、不默认回退旧的requirements.txt。

如果你是"正在使用 agent 客户端的人"，想先给 agent 一段启动提示词而不是自己阅读执行细节，文档指向了 Agent Bootstrap Prompt，这份提示词会引导 agent 优先按当前主线安装项目、优先使用uv、sauCLI 和 skills/ 目录，并先验证 bilibili、douyin、kuaishou、xiaohongshu 四个平台入口是否可用。

下面按 For Humans 的 7 个步骤逐一展开，并补充源码级佐证。

二、克隆项目

git clone https://github.com/dreammis/social-auto-upload.git cd social-auto-upload

克隆后进入仓库根目录，后续所有命令（uv venv、sau ...）都以该目录为工作目录。conf.py、cookies/、verify_code.txt等运行产物都相对仓库根目录解析——从源码看，sau_cli.py 中的resolve_runtime_home()直接返回conf.BASE_DIR（即 conf.py 中Path(__file__).parent.resolve()，也就是仓库根目录），账号 cookie 文件统一落在<仓库根>/cookies/<platform>_<account_name>.json。

三、创建虚拟环境（推荐 uv）

Windows PowerShell：

uv venv .venv\Scripts\activate

Linux / macOS：

uv venv source .venv/bin/activate

选择uv的原因可以从 pyproject.toml 看到：文件里显式声明了[tool.uv] package = true（第 30 行），即这个包就是为 uv 工作流准备的，uv pip install -e .能正确识别它作为可安装包。

四、安装主线依赖与 sau 命令

当前主线依赖已经收敛到 pyproject.toml，推荐直接执行：

uv pip install -e .

安装完成后会注册sau命令。这条命令的实质是"可编辑安装（-e）"，它做了两件事：

1. 安装固定版本的主线依赖。pyproject.toml 中声明的依赖为：

依赖	版本约束	作用
`loguru`	`==0.7.3`	日志
`opencv-python`	`>=4.13.0.92`	图像/二维码等处理
`patchright`	`==1.58.2`	浏览器驱动（主线核心）
`qrcode`	`==8.2`	登录二维码生成
`requests`	`==2.32.3`	网络请求
`segno`	`>=1.6.6`	二维码编码

Python 版本要求为>=3.10,<3.13（pyproject.toml），安装前需确认本机解释器落在该区间。

2. 注册命令行入口。pyproject.toml 声明了：

[project.scripts] sau = "sau_cli:main"

也就是说sau命令指向 sau_cli.py 中的main()（入口函数），内部用argparse构建douyin / kuaishou / xiaohongshu / bilibili / tencent / alipay / weibo / hupu / youtube / baijiahao十个平台子命令，再用asyncio.run(dispatch(args))异步执行。这也是"命令行找不到sau"时优先排查的两点来源：当前虚拟环境是否已激活、是否真的执行过uv pip install -e .。

两点补充：

打包规则上，pyproject.toml 将uploader、utils、myUtils三个包以及顶层conf、sau_cli等模块纳入分发，并把utils/stealth.min.js作为 package-data 一起打包（浏览器反检测脚本）。从源码结构看，uploader/ 目录就是各平台上传实现的所在位置，与安装文档"对 agent 的额外说明"中uploader/是核心实现目录、sau_cli.py是 CLI 主入口的表述一致。
requirements.txt目前是历史兼容文件，不是主安装入口，安装阶段不需要它。

五、安装 patchright Chromium

当前主线使用patchright驱动浏览器（Playwright 的补丁分支，用于降低自动化指纹特征）。Chromium 需要单独下载。国内用户推荐先指定镜像再安装：

Windows PowerShell：

$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium

Linux / macOS：

PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium

PLAYWRIGHT_DOWNLOAD_HOST是下载源环境变量，patchright与playwright共用这套下载协议，所以设置后生效的是patchright自己的浏览器缓存目录。若你在能直连官方源的网络环境，也可以去掉镜像前缀直接执行patchright install chromium。

六、配置 conf.py

复制一份配置：

cp conf.example.py conf.py

Windows 也可以直接手动复制并重命名。示例配置 conf.example.py 的完整内容只有 6 个变量，逐项说明如下：

配置项	默认值	含义与取值
`BASE_DIR`	仓库根目录	运行时根目录，cookie、二维码等产物都相对它解析，通常无需改动
`XHS_SERVER`	`http://127.0.0.1:11901`	目前只和小红书旧流程相关，走浏览器版小红书 CLI 时无需配置
`LOCAL_CHROME_PATH`	`""`（空）	可选，指定本机 Chrome 可执行文件路径，例如`C:/Program Files/Google/Chrome/Application/chrome.exe`；为空则用`patchright`下载的 Chromium
`LOCAL_CHROME_HEADLESS`	`True`	uploader/examples 的默认无头行为；无头模式指浏览器后台运行、不弹窗口，适合 CLI、服务端、定时任务和 agent 场景
`DEBUG_MODE`	`True`	默认调试行为
`YT_PROXY`	`None`	可选的 YouTube 代理，例如`http://127.0.0.1:7890`。注释里特别说明：`patchright`驱动的 chromium 不走系统代理，youtube.com 被墙的地区必须显式配置此项，否则直连超时无响应

注意 sau_cli.py 中from conf import BASE_DIR——CLI 直接 import 仓库根目录的conf.py，所以第 5 步的复制不能省：没有conf.py时 CLI 会在导入阶段失败。

七、验证 CLI 是否可用

安装完成后逐条执行：

sau --help sau douyin --help sau kuaishou --help sau xiaohongshu --help sau bilibili --help

如果命令找不到，优先确认：当前虚拟环境是否已激活、是否执行过uv pip install -e .。

八、平台主线示例

安装文档按平台给出了"登录 → 校验 → 上传"的标准动作序列，全部命令统一遵循元数据约定：视频使用title + desc + tags，图文使用title + note + tags。<account_name>是用户自定义的账号名（文档里出现的creator之类只是示例值），一个account_name对应cookies/目录下一个账号文件，因此可以准备多个账号并发使用。

8.1 抖音

sau douyin login --account <account_name> sau douyin check --account <account_name> sau douyin upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介"

图文（图文正文1，直接内联正文）：

$noteText = @"图文正文"@ sau douyin upload-note --account <account_name> --images videos/demo1.png videos/demo2.png --title "图文标题" --note $noteText --tags 'tag1,tag2'

图文正文2，从文件读取正文（支持 txt/md）：

sau douyin upload-note --account <account_name> --images videos/demo1.png videos/demo2.png --title "图文标题" --notef '图文文件路径' --tags 'tag1,tag2'

添加 BGM（可选，传音乐名称，程序会自动搜索并选中）：

sau douyin upload-note --account <account_name> --images videos/demo1.png videos/demo2.png --title "图文标题" --note $noteText --tags 'tag1,tag2' --bgm '音乐名称'

--notef与--bgm在 CLI 中的实现可以直接对应到 sau_cli.py：--notef读取指定文件（txt/md）作为图文正文，在 dispatch 里若--notef存在则用文件内容覆盖--note；--bgm对应DouyinNoteUploadRequest.bgm字段（请求数据结构），最终传给DouYinNote的上传流程。

短信二次验证码。抖音视频发布过程中如果触发短信二次验证，行为如下：

程序会优先读取项目根目录下的verify_code.txt；
如果当前是手动运行的交互式终端且没提供verify_code.txt，CLI 会直接提示你在终端输入验证码；
如果是 agent 或自动化桥接场景，仍然可以继续通过写入verify_code.txt来提供验证码；
验证通过后，程序会自动删除verify_code.txt。

这与 uploader/douyin_uploader/main.py 中_read_verify_code()的实现一致：先查文件是否存在并读取其内容；文件不存在且sys.stdin.isatty()为真（交互式终端）时，阻塞等待用户输入；否则返回空串等待重试。验证码文件路径拼接在 main.py：os.path.join(BASE_DIR, "verify_code.txt")。

卡 login 时的手动 cookie 方案。如果sau douyin login在服务器环境卡住（例如无桌面/无 VNC 可见窗口），可以人工在浏览器登录创作者中心后导出 cookie：

目标服务器使用 VNC；
浏览器登录抖音创作者中心https://creator.douyin.com/；
执行bash export_douyin_cookie.sh --account <account_name>；
检查 cookie 可用性：sau douyin check --account <account_name>。

export_douyin_cookie.sh 的原理是通过 Chrome DevTools HTTP API（默认9222端口）连接已开启 remote debugging 的 Chrome：用curl http://localhost:9222/json确认调试端口存活并找到creator.douyin.com页面，再经该页面的 WebSocket 调用Network.getAllCookies拉取全部 cookie、过滤douyin.com域，同时用Page.getResourceTree+Runtime.evaluate收集相关 frame 的localStorage，最后组装成cookies+origins结构的 JSON 写入cookies/douyin_<account_name>.json（不传--account时使用 8 位随机文件名）。脚本还依赖curl、python3、websocket-client，并会打印sessionid、uid_tt、ssid、ttwid等关键 cookie 前 30 字符便于人工核对。导出格式与sau douyin login生成的账号文件结构一致，因此sau douyin check可以直接复用。

8.2 快手

sau kuaishou login --account <account_name> sau kuaishou check --account <account_name> sau kuaishou upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" sau kuaishou upload-note --account <account_name> --images videos/demo1.png videos/demo2.png videos/demo.png --title "图文标题" --note "图文正文"

8.3 小红书

sau xiaohongshu login --account <account_name> sau xiaohongshu check --account <account_name> sau xiaohongshu upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" sau xiaohongshu upload-note --account <account_name> --images videos/demo1.png videos/demo2.png videos/demo.png --title "图文标题" --note "图文正文"

从源码看，小红书对标签数量有校验：解析后的标签超过 10 个时直接报错退出（sau_cli.py），命令行传入--tags时注意控制数量。

8.4 Bilibili

sau bilibili login --account <account_name> sau bilibili check --account <account_name> sau bilibili upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" --tid 249

Bilibili 与其他三个平台的机制不同，安装文档给出的补充说明需要重点理解：

不需要手动安装biliup：首次运行 Bilibili 相关命令时，程序会自动下载biliup；后续运行会自动检查上游 release 并自动更新。这一点在 uploader/bilibili_uploader/runtime.py 中可以得到印证：文件里定义了GITHUB_RELEASE_API（指向 biliup 上游 latest release 的接口）和download_biliup_asset()下载函数，run_biliup_command()负责定位/准备二进制并执行子命令。sau bilibili check底层实际是biliup -u <account_file> renew（sau_cli.py），即刷新/校验 cookie；upload-video则是把--title/--desc/--tid/--tags/--thumbnail/--schedule翻译为biliup upload的参数（upload_bilibili_video）。
登录建议人工执行：Bilibili 登录建议由用户自己在本地真实终端里执行sau bilibili login --account <name>；如果终端里的二维码显示不完整，可直接打开当前目录下的qrcode.png扫码。CLI 对此有硬性防护：login_bilibili_account()会先用sys.stdin.isatty()判断是否交互终端，非交互环境（例如 agent 代跑）直接返回失败并提示用户自行在本地终端执行（sau_cli.py）。
国内网络下载排障：如果访问 GitHub Release 较慢，可先用https://gh-proxy.com/或https://gh-proxy.org/这类代理前缀辅助访问对应 release 地址，例如https://gh-proxy.org/https://github.com/biliup/biliup/releases/download/v1.1.29/biliupR-v1.1.29-aarch64-linux.tar.xz。
示例值提醒：creator之类的名字只是示例，真正传的是用户自定义的account_name，账号文件同样落在cookies/bilibili_<account_name>.json。

九、For AI Agents：给 Agent 的执行清单

docs/install.md 的后半部分面向可执行命令的 agent，处理顺序固定为：

先假设仓库根目录就是当前工作目录；
优先使用uv管理环境，不要默认回退到旧的requirements.txt；
安装命令优先使用uv pip install -e .；
如需浏览器驱动，优先使用：

# Windows PowerShell $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium

# Linux / macOS PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium

安装完成后优先检查：

sau --help sau douyin --help sau kuaishou --help sau xiaohongshu --help sau bilibili --help

如果用户目标是抖音/快手/小红书/Bilibili 的登录、cookie 校验、视频上传、图文上传，优先走 CLI：sau <platform> login / check / upload-video / upload-note（Bilibili 当前只有upload-video）。
如果用户明确在使用 skill 系统，再引导其阅读对应平台的 skill 文档：

skills/douyin-upload/SKILL.md 与 skills/douyin-upload/references/cli-contract.md
skills/kuaishou-upload/SKILL.md 与 skills/kuaishou-upload/references/cli-contract.md
skills/xiaohongshu-upload/SKILL.md 与 skills/xiaohongshu-upload/references/cli-contract.md
skills/bilibili-upload/SKILL.md 与 skills/bilibili-upload/references/cli-contract.md

对 agent 的额外说明（均来自原文档）：

登录流程生成本地二维码图片时，不要只把图片路径发给用户——二维码图片本身就是给用户扫码的，应优先直接展示/发送本地图片；路径只作为补充信息；
Bilibili 登录当前不建议 agent 在非交互环境里直接代跑，正确做法是让用户在本地终端执行sau bilibili login --account <name>，二维码显示不完整再提示打开qrcode.png；
requirements.txt是历史兼容文件；uploader/是核心实现目录；sau_cli.py是当前 CLI 主入口；docs/legacy-web.md 是历史 Web 版本说明，不保证当前可用；
Bilibili 首次运行时可能自动下载biliup。

十、安装完成后的自检清单

把整个流程压缩成一张可执行的核对表：

步骤	命令/动作	判定标准
克隆	`git clone`后进入`social-auto-upload`	根目录下可见 pyproject.toml、conf.example.py、sau_cli.py
虚拟环境	`uv venv`+ 激活	提示符前出现`(.venv)`，`python -V`在 3.10–3.12
依赖安装	`uv pip install -e .`	无报错，`sau`可执行
浏览器	`patchright install chromium`（可带镜像）	Chromium 下载成功
配置	`cp conf.example.py conf.py`	存在`conf.py`，按需改`LOCAL_CHROME_PATH`/`LOCAL_CHROME_HEADLESS`/`DEBUG_MODE`
CLI 验证	`sau --help`及各平台`--help`	五个平台子命令全部可列出参数
账号链路	`login`→`check`→`upload-*`	`check`输出`valid`且退出码 0

其中check的语义在各平台是一致的：先确认cookies/<platform>_<account_name>.json存在，再调用对应平台的cookie_auth（Bilibili 走biliup renew），在 sau_cli.py 的dispatch中打印valid/invalid并返回 0/1 退出码——这意味着它可以直接作为脚本和 agent 流程中的断言点。

十一、延伸阅读

docs/CLI.md：sau各平台子命令的完整参数说明；
docs/update.md：依赖与biliup的更新方式；
docs/agent-bootstrap.md：交给 agent 的启动提示词；
skills/douyin-upload/SKILL.md 等四个平台的 skill 文档：面向 agent 的调用契约；
tests/ 目录下的test_sau_browser_cli.py、test_sau_bilibili_cli.py等用例：可参考 CLI 参数与行为的回归验证方式。

再次强调适用范围：本文所有命令与配置以当前仓库的 pyproject.toml（Python>=3.10,<3.13、patchright==1.58.2）和 docs/install.md 为准；历史 Web 版本（sau_backend/sau_frontend）不属于当前主线，其说明见 docs/legacy-web.md，不保证可直接运行。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考