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/源码”。要让这套命令式工作流成立环境默认必须已经具备三个前提已安装social-auto-upload即可执行sau命令或至少有等效调用方式已为patchright安装 Chromium 浏览器内核当前 shell 能实际调用到sau命令——这一点看似显然但在“虚拟环境未激活”“未安装入口脚本”等场景下最容易出问题因此 skill 单独列出了多种回退调用方式。为什么是patchright而不是原生 Playwright从 uploader/xiaohongshu_uploader/main.py 可以看到小红书 uploader 全部基于patchright.async_apiPage、Playwright、async_playwright并且通过playwright.chromium.launch(channelchromium)启动浏览器登录流程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安装后会自动在当前虚拟环境生成sauUnix或sau.exeWindows可执行入口[tool.uv]中package true表明该项目支持uv pip install -e .的可编辑安装[project]中 Python 版本要求为3.10,3.13核心依赖锁定为patchright1.58.2、loguru0.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_HOSThttps://npmmirror.com/mirrors/playwright; patchright install chromiumLinux / macOSbash / zshPLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright patchright install chromium两条命令的差异只是环境变量写法PowerShell 中用$env:前缀bash/zsh 中把变量前缀放在同一条命令前。补充两点源码层面的事实uploader 在 cookie_auth 中保留了分支如果conf中配置了LOCAL_CHROME_PATH会改用本地 Chrome 可执行文件启动executable_pathLOCAL_CHROME_PATH否则使用channelchromium即 patchright 管理的 Chromium。因此“已为 patchright 安装 Chromium”是默认路径本地 Chrome 只是可选替代小红书创作者后台地址默认是https://creator.xiaohongshu.com并可通过环境变量SAU_XHS_CREATOR_BASE_URL覆盖见 模块常量 与 _build_xhs_creator_urldocs/CLI.md 提到海外环境可用SAU_XHS_CREATOR_BASE_URLhttps://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\Scriptssau.exe随即可用。3. 直接调用可执行文件PowerShell.\.venv\Scripts\sau.exe xiaohongshu --help绕过 PATH 与激活步骤直接指定入口文件。适合写批处理脚本或 agent 在不确定 PATH 状态时的保守调用。4. 使用 uv 运行uv run sau xiaohongshu --helpuv 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都不传时默认headlessTrueparser.set_defaults(headlessTrue)。这两个 flag 目前挂在login和两个upload-*子命令上check子命令本身固定以无头方式做校验——从 cookie_auth 可以看到它始终launch(headlessTrue)并打开创作者后台视频发布页判断是否被重定向到/login若是则视为 cookie 失效。无头登录时的二维码处理规范无头模式下扫码登录是 Agent 场景的核心痛点。运行前提文档给出两条约束如果用户明确要求无头登录要预期 CLI 会通过控制台输出或临时图片路径提供二维码相关提示如果登录过程中已生成本地二维码图片agent 应优先直接把图片展示/发送给用户扫码而不是只告诉用户图片路径。这两条约束在源码中完全对得上。小红书登录流程xiaohongshu_cookie_gen的无头分支会打开创作者后台/login页找到“扫一扫”面板中的二维码图片通过 _save_xhs_qrcode 把二维码保存为本地 PNG路径由 build_login_qrcode_path 生成命名为cookies/目录下{账号文件stem}_xhs_login_qrcode_{时间戳}.png若二维码src是data:image/内联格式则直接解码保存save_data_url_image否则对元素截图尝试用 OpenCV 解码二维码并在终端打印 ASCII 二维码print_terminal_qrcode 调用链解码失败时降级为 warning提示“请打开图片路径扫码”轮询等待扫码完成默认每 3 秒检查一次、最多 100 次成功后通过context.storage_state(pathaccount_file)把登录态写入账号文件随后自动再跑一次cookie_auth复核无论成败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 通过channelchromium消费四种调用方式覆盖 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 social-auto-upload 小红书上传运行前提：安装 sau CLI、patchright Chromium 与无头/有头调用方式详解
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/源码”。要让这套命令式工作流成立环境默认必须已经具备三个前提已安装social-auto-upload即可执行sau命令或至少有等效调用方式已为patchright安装 Chromium 浏览器内核当前 shell 能实际调用到sau命令——这一点看似显然但在“虚拟环境未激活”“未安装入口脚本”等场景下最容易出问题因此 skill 单独列出了多种回退调用方式。为什么是patchright而不是原生 Playwright从 uploader/xiaohongshu_uploader/main.py 可以看到小红书 uploader 全部基于patchright.async_apiPage、Playwright、async_playwright并且通过playwright.chromium.launch(channelchromium)启动浏览器登录流程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安装后会自动在当前虚拟环境生成sauUnix或sau.exeWindows可执行入口[tool.uv]中package true表明该项目支持uv pip install -e .的可编辑安装[project]中 Python 版本要求为3.10,3.13核心依赖锁定为patchright1.58.2、loguru0.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_HOSThttps://npmmirror.com/mirrors/playwright; patchright install chromiumLinux / macOSbash / zshPLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright patchright install chromium两条命令的差异只是环境变量写法PowerShell 中用$env:前缀bash/zsh 中把变量前缀放在同一条命令前。补充两点源码层面的事实uploader 在 cookie_auth 中保留了分支如果conf中配置了LOCAL_CHROME_PATH会改用本地 Chrome 可执行文件启动executable_pathLOCAL_CHROME_PATH否则使用channelchromium即 patchright 管理的 Chromium。因此“已为 patchright 安装 Chromium”是默认路径本地 Chrome 只是可选替代小红书创作者后台地址默认是https://creator.xiaohongshu.com并可通过环境变量SAU_XHS_CREATOR_BASE_URL覆盖见 模块常量 与 _build_xhs_creator_urldocs/CLI.md 提到海外环境可用SAU_XHS_CREATOR_BASE_URLhttps://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\Scriptssau.exe随即可用。3. 直接调用可执行文件PowerShell.\.venv\Scripts\sau.exe xiaohongshu --help绕过 PATH 与激活步骤直接指定入口文件。适合写批处理脚本或 agent 在不确定 PATH 状态时的保守调用。4. 使用 uv 运行uv run sau xiaohongshu --helpuv 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都不传时默认headlessTrueparser.set_defaults(headlessTrue)。这两个 flag 目前挂在login和两个upload-*子命令上check子命令本身固定以无头方式做校验——从 cookie_auth 可以看到它始终launch(headlessTrue)并打开创作者后台视频发布页判断是否被重定向到/login若是则视为 cookie 失效。无头登录时的二维码处理规范无头模式下扫码登录是 Agent 场景的核心痛点。运行前提文档给出两条约束如果用户明确要求无头登录要预期 CLI 会通过控制台输出或临时图片路径提供二维码相关提示如果登录过程中已生成本地二维码图片agent 应优先直接把图片展示/发送给用户扫码而不是只告诉用户图片路径。这两条约束在源码中完全对得上。小红书登录流程xiaohongshu_cookie_gen的无头分支会打开创作者后台/login页找到“扫一扫”面板中的二维码图片通过 _save_xhs_qrcode 把二维码保存为本地 PNG路径由 build_login_qrcode_path 生成命名为cookies/目录下{账号文件stem}_xhs_login_qrcode_{时间戳}.png若二维码src是data:image/内联格式则直接解码保存save_data_url_image否则对元素截图尝试用 OpenCV 解码二维码并在终端打印 ASCII 二维码print_terminal_qrcode 调用链解码失败时降级为 warning提示“请打开图片路径扫码”轮询等待扫码完成默认每 3 秒检查一次、最多 100 次成功后通过context.storage_state(pathaccount_file)把登录态写入账号文件随后自动再跑一次cookie_auth复核无论成败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 通过channelchromium消费四种调用方式覆盖 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考