企业官网建设流程全解析

social-auto-upload 小红书上传运行前提：安装 sau CLI、patchright Chromium 与无头/有头调用方式详解

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

本文基于skills/xiaohongshu-uploadskill 中的运行前提文档（runtime-requirements.md），完整讲解在 Agent 工作流中使用sau xiaohongshu ...系列命令前需要满足的三项运行前提、推荐安装步骤、patchright Chromium 浏览器安装方式，以及无头/有头两种浏览器运行模式下的二维码登录处理规范。读完之后，你可以从零搭建一个可登录、可校验 cookie、可执行小红书视频与图文上传的命令行环境，并理解每个前提在源码中的落点。

一、运行前提总览：三项默认假设

xiaohongshu-upload skill 的核心思想是“优先把sau作为主接口，不要一开始就去读uploader/源码”。要让这套命令式工作流成立，环境默认必须已经具备三个前提：

1. 已安装social-auto-upload（即可执行sau命令，或至少有等效调用方式）；
2. 已为patchright安装 Chromium 浏览器内核；
3. 当前 shell 能实际调用到sau命令——这一点看似显然，但在“虚拟环境未激活”“未安装入口脚本”等场景下最容易出问题，因此 skill 单独列出了多种回退调用方式。

为什么是patchright而不是原生 Playwright？从 uploader/xiaohongshu_uploader/main.py 可以看到，小红书 uploader 全部基于patchright.async_api（Page、Playwright、async_playwright），并且通过playwright.chromium.launch(channel="chromium")启动浏览器；登录流程（xiaohongshu_cookie_gen）和 cookie 校验（cookie_auth）都依赖这个已安装的 Chromium。如果只pip install了 Python 包而没装浏览器内核，所有登录/上传命令都会在启动浏览器这一步失败。

二、推荐安装方式：uv pip install -e .

运行前提文档给出的推荐安装方式是在项目根目录执行：

uv pip install -e .

这条命令之所以能生成sau命令，来自 pyproject.toml 中的配置：

• [project.scripts]声明了入口sau = "sau_cli:main"，安装后会自动在当前虚拟环境生成sau（Unix）或sau.exe（Windows）可执行入口；
• [tool.uv]中package = true表明该项目支持uv pip install -e .的可编辑安装；
• [project]中 Python 版本要求为>=3.10,<3.13，核心依赖锁定为patchright==1.58.2、loguru==0.7.3、opencv-python、qrcode、requests、segno等（见 pyproject.toml）。

也就是说，sau并不是一个独立的二进制，它只是 sau_cli.py 的main()函数入口（入口函数定义）。docs/CLI.md 也明确说明：sau.exe是安装后在 Windows 虚拟环境里自动生成的命令入口，本质上还是调用sau_cli.py。

安装完成后的第一件验证事，是运行一次帮助命令确认 CLI 可被解析：

sau xiaohongshu --help

三、安装 patchright 浏览器（含国内镜像）

uv pip install -e .只安装了 Python 包，Chromium 内核需要单独通过patchright install chromium下载。运行前提文档给出了按操作系统区分的两条命令，统一使用 npmmirror 镜像以加速下载：

Windows PowerShell

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

Linux / macOS（bash / zsh）

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

两条命令的差异只是环境变量写法：PowerShell 中用$env:前缀，bash/zsh 中把变量前缀放在同一条命令前。

补充两点源码层面的事实：

1. uploader 在 cookie_auth 中保留了分支：如果conf中配置了LOCAL_CHROME_PATH，会改用本地 Chrome 可执行文件启动（executable_path=LOCAL_CHROME_PATH），否则使用channel="chromium"即 patchright 管理的 Chromium。因此“已为 patchright 安装 Chromium”是默认路径，本地 Chrome 只是可选替代；
2. 小红书创作者后台地址默认是https://creator.xiaohongshu.com，并可通过环境变量SAU_XHS_CREATOR_BASE_URL覆盖（见 模块常量 与 _build_xhs_creator_url），docs/CLI.md 提到海外环境可用SAU_XHS_CREATOR_BASE_URL=https://creator.rednote.com切换 RedNote 域名，该设置同时作用于登录、cookie 校验、视频发布和图文发布。

四、常见调用方式：四种拿到sau命令的姿势

“环境能调用sau”有多种达成路径。运行前提文档按常见场景列出了四类方式，故障排查文档 在“找不到sau命令”一节也给出了同样的回退顺序：

1.sau已在 PATH 中

sau xiaohongshu --help

这是最理想的状态：uv pip install -e .之后激活了对应虚拟环境，且该环境的 bin/Scripts 目录已加入 PATH。

2. 虚拟环境存在但尚未激活（PowerShell）

.\.venv\Scripts\Activate.ps1 sau xiaohongshu --help

激活后 PATH 中就会出现.venv\Scripts，sau.exe随即可用。

3. 直接调用可执行文件（PowerShell）

.\.venv\Scripts\sau.exe xiaohongshu --help

绕过 PATH 与激活步骤，直接指定入口文件。适合写批处理脚本或 agent 在不确定 PATH 状态时的保守调用。

4. 使用 uv 运行

uv run sau xiaohongshu --help

uv run会自动解析项目环境并在其中执行sau，等价于“临时激活 + 执行”，适合不想手动管理 venv 的场景。

这四种方式对底层是等价的——最终都执行 sau_cli.py 的main()，其中小红书子命令由 build_parser 注册的xiaohongshu解析器处理，动作包括login、check、upload-video、upload-note四个。

五、无头与有头模式：--headless与--headed

运行前提文档的最后一节约定了浏览器窗口策略，这里结合源码展开。

CLI 将两个维度拆开（见 docs/CLI.md 的“运行时参数”一节与 add_runtime_flags）：

• --headless：无头模式运行（不显示浏览器窗口）；
• --headed：有头模式运行（显示浏览器窗口，适合人工观察页面）；
• 两者互斥（add_mutually_exclusive_group），都不传时默认headless=True（parser.set_defaults(headless=True)）。

这两个 flag 目前挂在login和两个upload-*子命令上；check子命令本身固定以无头方式做校验——从 cookie_auth 可以看到它始终launch(headless=True)，并打开创作者后台视频发布页判断是否被重定向到/login（若是则视为 cookie 失效）。

无头登录时的二维码处理规范

无头模式下扫码登录是 Agent 场景的核心痛点。运行前提文档给出两条约束：

• 如果用户明确要求无头登录，要预期 CLI 会通过控制台输出或临时图片路径提供二维码相关提示；
• 如果登录过程中已生成本地二维码图片，agent 应优先直接把图片展示/发送给用户扫码，而不是只告诉用户图片路径。

这两条约束在源码中完全对得上。小红书登录流程（xiaohongshu_cookie_gen）的无头分支会：

1. 打开创作者后台/login页，找到“扫一扫”面板中的二维码图片；
2. 通过 _save_xhs_qrcode 把二维码保存为本地 PNG：路径由 build_login_qrcode_path 生成，命名为cookies/目录下{账号文件stem}_xhs_login_qrcode_{时间戳}.png；若二维码src是data:image/内联格式则直接解码保存（save_data_url_image），否则对元素截图；
3. 尝试用 OpenCV 解码二维码并在终端打印 ASCII 二维码（print_terminal_qrcode 调用链），解码失败时降级为 warning，提示“请打开图片路径扫码”；
4. 轮询等待扫码完成（默认每 3 秒检查一次、最多 100 次），成功后通过context.storage_state(path=account_file)把登录态写入账号文件，随后自动再跑一次cookie_auth复核；
5. 无论成败，finally中清理临时二维码文件（remove_qrcode_file）。

也就是说：终端能完整渲染 ASCII 二维码时用户可直接扫终端；渲染不完整时唯一的可靠通道就是那张临时 PNG——这正是“agent 必须直接把图片发出去”的原因。SKILL.md 的“执行前检查”小节重复强调同一点：二维码图片本身就是给用户扫码的，只回传路径会阻塞整个登录流程。

六、前提落实后的最小验证链

当三项运行前提全部满足后，可以用最短的命令链验证环境，这也是 xiaohongshu_commands.sh 模板脚本的执行顺序：

sau xiaohongshu login --account "$account" --headless sau xiaohongshu check --account "$account"

从 dispatch 可以确认两条命令的可观察行为：

• login成功时打印Xiaohongshu login flow completed: <account_file>并返回退出码 0；失败会抛出带具体原因的 RuntimeError 并以退出码 1 结束；
• check只输出valid或invalid二选一，退出码分别为 0 或 1，非常适合脚本判断；
• 账号文件由 resolve_account_file 统一解析为cookies/xiaohongshu_<account_name>.json，一个account_name对应一个独立账号文件，天然支持多账号隔离与并发任务；
• 上传类命令在正式上传前会再跑一次 cookie 校验（upload_xiaohongshu_video 等），失效时直接报错并提示先执行sau xiaohongshu login --account <name>；上传完成后还会把刷新过的storage_state写回账号文件（见 upload 方法 中的cookie 更新完毕日志）。

后续要执行真正的视频/图文上传、定时发布（--schedule "YYYY-MM-DD HH:MM"，发布时间需晚于当前时间至少 2 小时，见 validate_publish_date）、标签上限（CLI 层最多 10 个，见 dispatch）等参数细节，应继续阅读 cli-contract.md；命令失败时的排查顺序（找不到sau、cookie 失效、无头二维码、参数缺失）则见 troubleshooting.md。单元测试 tests/test_xiaohongshu_uploader.py 使用 FakeLocator/RecordingPage 等 mock 对象覆盖了标题、描述、话题填充与二维码链路，可作为理解各步骤行为的佐证。

小结

运行前提文档看似简短，实际勾勒出整条小红书自动化链路的“地基”：uv pip install -e .提供sau入口（由pyproject.toml的[project.scripts]生成），patchright install chromium（建议配 npmmirror 镜像）提供浏览器内核（uploader 通过channel="chromium"消费），四种调用方式覆盖 PATH/venv/直调 exe/uv 四类环境，而--headless/--headed默认无头的约定配合“二维码图片优先直接展示”的规则，保证了 Agent 在无人值守终端下也能完成扫码登录。把这一节的前提逐项核对后，再进入 cli-contract.md 的命令契约，就是 skill 推荐的完整工作路径。

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