social-auto-upload 快手 CLI 契约详解sau kuaishou 登录、校验与视频/图文上传全命令解析【免费下载链接】social-auto-upload自动化上传视频到社交媒体抖音、小红书、视频号、tiktok、youtube、bilibili项目地址: https://gitcode.com/GitHub_Trending/so/social-auto-upload本文基于skills/kuaishou-upload/references/cli-contract.md中的快手 CLI 契约展开完整覆盖sau kuaishou的登录、cookie 校验、视频上传与图文发布四类命令的参数规范与发布策略并结合sau_cli.py与uploader/ks_uploader/main.py的源码实现说明每条命令背后的调用链、账号文件机制与底层浏览器自动化流程。读完本文你可以直接复制可运行的快手上传命令也能在命令失败时定位到源码级的具体环节。契约前提sau 命令必须可调用该 skill 默认假设当前环境已经安装并可调用sau命令。这一前提在仓库中对应的就是 pyproject.toml 中声明的命令行入口[project.scripts] sau sau_cli:main也就是说sau是sau_cli.py中main()函数的可执行脚本别名安装项目后即可获得该命令。运行环境要求为 Python3.10,3.13浏览器驱动依赖固定版本patchright1.58.2见 pyproject.toml。推荐的安装与浏览器准备方式来自 skills/kuaishou-upload/references/runtime-requirements.md# 在项目根目录执行 uv pip install -e .# Windows PowerShell 安装 patchright 的 Chromium $env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright; patchright install chromium# Linux / macOS PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright patchright install chromium如果sau不在 PATH 中可以通过激活虚拟环境、直接调用.venv\Scripts\sau.exe或使用uv run sau kuaishou --help等方式调用细节见 skills/kuaishou-upload/references/troubleshooting.md。命令一sau kuaishou login 登录并生成 cookie 文件sau kuaishou login --account account契约要点必填参数--account作用启动快手登录流程为指定账号生成或刷新 cookie 文件如果登录过程中生成本地二维码图片agent 应优先直接把图片展示/发送给用户扫码而不是只回传路径--account传的是用户自定义的account_name不是固定只能叫creator一个account_name对应一个账号文件可用于多账号隔离和并发任务源码印证账号文件与登录流程在 sau_cli.py 中账号名到账号文件的映射规则被明确定义def resolve_account_file(platform: str, account_name: str) - Path: account_file resolve_runtime_home() / cookies / f{platform}_{account_name}.json account_file.parent.mkdir(exist_okTrue) return account_file即--account demo会对应运行时目录下的cookies/kuaishou_demo.json。这也是契约中“一个 account_name 对应一个账号文件”的实现来源——多账号天然隔离可以并行准备多组账号文件。login的分发逻辑位于 sau_cli.pyif args.action login: result await login_kuaishou_account(args.account, headlessargs.headless) if not result[success]: raise RuntimeError(result[message]) print(fKuaishou login flow completed: {result[account_file]}) return 0login_kuaishou_accountsau_cli.py最终调用uploader/ks_uploader/main.py中的ks_setup(..., handleTrue, return_detailTrue)。当 cookie 文件不存在或已失效时ks_setup会转入get_ks_cookie执行完整扫码登录uploader/ks_uploader/main.py。get_ks_cookie的实际流程uploader/ks_uploader/main.py值得了解它解释了契约中“二维码图片”这条约定的由来打开快手创作者中心登录页KUAISHOU_LOGIN_URL从登录表单中抽取二维码图片保存为本地图片文件并尝试在终端内直接渲染二维码_save_ks_qrcodeuploader/ks_uploader/main.py轮询登录状态默认 3 秒一次、最多 100 次期间若检测到二维码过期会自动点击刷新按钮并重新保存图片检测到登录页消失后写入storage_state生成账号文件并立即用cookie_auth复核一次 cookie全部通过才返回success。登录成功后 CLI 输出形如Kuaishou login flow completed: cookies/kuaishou_demo.json失败则抛出带具体原因的RuntimeError如timeout、cookie_invalid等状态均会体现在返回结果的message中。命令二sau kuaishou check 校验 cookie 有效性sau kuaishou check --account account契约要点必填参数--account预期输出validcookie 可用invalidcookie 缺失或已失效分发逻辑在 sau_cli.pyif args.action check: is_valid await check_kuaishou_account(args.account) print(valid if is_valid else invalid) return 0 if is_valid else 1注意退出码语义valid返回 0invalid返回 1因此可以直接在 shell 脚本中用$?判断账号状态。check_kuaishou_account的第一步是文件存在性检查不存在直接判invalid否则委托给 uploader/ks_uploader/main.py 的cookie_auth。后者的判定相当严谨可以印证“invalid 不只是文件缺失”这一契约描述启动 headless Chromium以storage_stateaccount_file载入 cookie访问快手发布页KUAISHOU_UPLOAD_URL若被重定向到passport.kuaishou.com登录页→ 判定失效若页面出现“立即登录”按钮未登录介绍页→ 判定失效正向证明等待发布按钮button[class^_upload-btn]在 10 秒内可见 → 判定有效兜底旧版“机构服务”元素检测以及无法确认时保守按失效处理避免假阳性。也就是说check不是简单的文件探测而是一次真实的“无头浏览器回源验证”。命令三sau kuaishou upload-video 上传视频契约给出的完整命令形态sau kuaishou upload-video \ --account account \ --file video-path \ --title title \ [--desc description] \ [--tags tag1,tag2] \ [--schedule YYYY-MM-DD HH:MM] \ [--thumbnail image-path] \ [--debug] \ [--headless | --headed]参数一览结合 sau_cli.py 的参数注册补充默认值与取值细节参数必填默认值/取值说明--account是无用户自定义的 account_name对应cookies/kuaishou_account.json--file是无视频文件路径必须真实存在见下方文件校验--title是无视频标题--desc否空字符串视频描述从源码看描述为空时上传流程会用 title 顶替描述区输入--tags否空字符串逗号分隔如tag1,tag2解析时会自动去除每项的#前缀--schedule否无定时发布时间格式必须为YYYY-MM-DD HH:MM否则参数解析阶段直接报错--thumbnail否无封面图片路径同样要求文件存在--debug否关闭开启调试模式发布环节失败时会额外保存整页截图--headless/--headed否--headless互斥参数组默认无头模式运行几个参数在源码中的具体行为文件存在性校验。--file与--thumbnail都通过 sau_cli.py 的existing_file_path做参数类型校验文件不存在时命令在解析阶段就会以File not found: path退出不会进入浏览器流程。标签解析。parse_tagssau_cli.py按逗号切分逐项strip并去掉前导#因此--tags #a,b, c与--tags a,b,c等价。定时时间解析。parse_schedulesau_cli.py使用SCHEDULE_FORMAT %Y-%m-%d %H:%M严格解析格式错误会抛出Invalid schedule .... Expected format: ...的ArgumentTypeError。无头/有头互斥。add_runtime_flagssau_cli.py将--headed与--headless放入互斥组并set_defaults(headlessTrue)——这与契约中“快手 CLI 默认按无头模式运行”一致。此外从源码结构看upload-video还支持一个契约文档未列出的可选参数--collectionsau_cli.py用于把作品归入已存在的合集uploader/ks_uploader/main.py 的apply_collection实现中找不到匹配合集时会跳过归集、不阻断发布主流程。上传前的双重 cookie 检查dispatch在组装KuaishouVideoUploadRequest之前先根据是否传了--schedule决定发布策略sau_cli.pypublish_strategy KUAISHOU_PUBLISH_STRATEGY_SCHEDULED if args.schedule else KUAISHOU_PUBLISH_STRATEGY_IMMEDIATE随后upload_kuaishou_videosau_cli.py会先以handleFalse调用ks_setup校验 cookie失败即抛出Kuaishou cookie is missing or expired: cookies/kuaishou_account.json. Run sau kuaishou login --account account first.进入KSVideouploader/ks_uploader/main.py后validate_base_args还会再做一次 cookie 文件存在性与有效性校验确保不会在无效凭据下打开发布页。KSVideo 的浏览器自动化主流程KSVideo.uploaduploader/ks_uploader/main.py以storage_stateaccount_file打开快手发布页随后依次点击上传按钮通过expect_file_chooser注入--file指定的视频关闭可能出现的 Joyride 引导遮罩close_guide_overlay多策略定位“描述”编辑区并清空后输入--desc为空则输入 title逐个输入话题——注意源码中只取前 3 个标签self.tags[:3]uploader/ks_uploader/main.py多出的标签不会被添加轮询“上传中”文案最长 60 次、每次 2 秒检测到“上传失败”会自动重新set_input_files重传若传了--thumbnail打开“封面设置”弹窗上传封面并确认若为定时策略执行set_schedule_time点击“定时发布”单选、向 ant-design 日期输入框以 React 兼容方式写入YYYY-MM-DD HH:MM:SS并回车确认uploader/ks_uploader/main.py循环点击“发布”与“确认发布”直到 URL 跳转到作品管理页KUAISHOU_MANAGE_URL_PATTERN判定发布成功成功收尾时用context.storage_state(pathself.account_file)回写最新 cookieuploader/ks_uploader/main.py保证下次上传仍能通过check校验。发布成功时 CLI 输出Kuaishou video upload submitted: video-filesau_cli.py。命令四sau kuaishou upload-note 上传图文契约给出的完整命令形态sau kuaishou upload-note \ --account account \ --images image-1 [image-2 ...] \ --title title \ [--note content] \ [--tags tag1,tag2] \ [--schedule YYYY-MM-DD HH:MM] \ [--debug] \ [--headless | --headed]参数一览参数注册见 sau_cli.py参数必填默认值/取值说明--account是无同上--images是无一个或多个图片路径nargs每项都要求文件真实存在--title是无图文标题--note否空字符串图文正文--tags否空字符串逗号分隔解析规则同upload-video--schedule否无YYYY-MM-DD HH:MM传了即切换为定时发布--debug否关闭调试模式--headless/--headed否--headless互斥参数组契约的“额外说明”中明确upload-note当前要求传入真实的多张图片文件而不是同一路径重复多次。这一点与 uploader/ks_uploader/main.py 的validate_upload_args相呼应——它会逐张校验图片文件validate_image_file并规范化路径列表而KSNote将全部路径一次性交给file_chooser.set_filesuploader/ks_uploader/main.py重复的相同路径会被页面去重这正是“多传图片但页面只识别到一张”这一常见故障的根因对应 troubleshooting.md 的排查项。KSNote.upload_note_content的执行链路uploader/ks_uploader/main.py切换到发布页“图文”标签页 → 点击“上传图片”按钮注入全部图片 → 清空描述区并输入--note正文 → 输入前 3 个话题标签 → 轮询上传状态直至“上传中”消失 → 按需set_schedule_time定时 → 循环点击“发布/确认发布”直至跳转到作品管理页。成功时 CLI 输出Kuaishou note upload submitted: N imagessau_cli.py。发布策略立即发布与定时发布的切换规则契约原文的发布策略三句话与源码完全对应如果不传--scheduleCLI 使用立即发布如果传了--scheduleCLI 自动切换为定时发布时间格式为YYYY-MM-DD HH:MM底层常量定义在 uploader/ks_uploader/main.pyKUAISHOU_PUBLISH_STRATEGY_IMMEDIATE immediate KUAISHOU_PUBLISH_STRATEGY_SCHEDULED scheduledKSBaseUploader.validate_base_argsuploader/ks_uploader/main.py进一步保证了策略的自洽未显式传入策略时按publish_date ! 0自动推导定时策略会再走validate_publish_date校验时间合法性而立即发布会把publish_date归零避免脏数据流入页面操作环节。契约之外的行为边界源码级补充以下细节契约文档未展开但会影响实际使用均来自源码可确认的行为元数据约定视频使用title desc tags图文使用title note tags见 skills/kuaishou-upload/SKILL.md与本文两条上传命令的参数分工一致视频描述字段统一用--desc图文正文统一用--note。视频单文件约束upload-video的--file是单值参数每次命令只支持一个视频文件需要发多条时循环执行命令即可upload-note的--images才是多值参数。cookie 会随成功发布自动续期KSVideo/KSNote在发布成功收尾阶段都会回写storage_state因此高频发布场景下不必每次先跑login用check兜底即可。运行参数来源uploader 侧的DEBUG_MODE、LOCAL_CHROME_HEADLESS、LOCAL_CHROME_PATH等默认值来自配置模块conf示例见 conf.example.pyCLI 显式传入的--debug/--headless会覆盖这些默认值。测试覆盖仓库 tests/test_sau_browser_cli.py 中包含针对sauCLI 行为的测试用例可用于回归验证命令解析与调度逻辑。命令模板与排障路径skill 自带可复制的命令模板覆盖登录、校验、视频与图文的完整组合bash 模板skills/kuaishou-upload/scripts/examples/kuaishou_commands.shPowerShell 模板skills/kuaishou-upload/scripts/examples/kuaishou_commands.ps1Python 模板skills/kuaishou-upload/scripts/examples/kuaishou_cli_template.pybash 模板的最小可用组合如下模板文件中的原始写法#!/usr/bin/env bash set -euo pipefail # account_name is user-defined. One account_name maps to one account file. accountaccount_a videovideos/demo.mp4 thumbnailvideos/demo.png sau kuaishou login --account $account sau kuaishou check --account $account sau kuaishou upload-video \ --account $account \ --file $video \ --title Kuaishou video from bash \ --desc Kuaishou video description from bash \ --tags cli,video \ --thumbnail $thumbnail \ --headless sau kuaishou upload-note \ --account $account \ --images videos/1.png videos/2.png videos/3.png \ --title Kuaishou note title from bash \ --note Kuaishou note from bash \ --tags cli,note \ --headless当命令执行失败时排障顺序建议参照 skills/kuaishou-upload/references/troubleshooting.md先确认sau可调用必要时uv pip install -e .cookie 失效先check再login二维码不好扫时优先直接展示本地二维码图片其次才切--headed上传报参数缺失时回到本文的参数表核对必填项图文“只有一张生效”时确认--images传的是真正不同的文件。小结快手 CLI 契约的本质是把“登录态管理 双形态发布”收敛成四个稳定命令login产出并刷新cookies/kuaishou_account.jsoncheck以无头浏览器回源方式给出valid/invalid与对应退出码upload-video与upload-note分别以单视频、多图片的约束完成立即或定时发布。契约文档定义了命令面而 sau_cli.py 的参数注册、uploader/ks_uploader/main.py 的cookie_auth/get_ks_cookie/KSVideo/KSNote则完整支撑了契约中每一条行为约定——从多账号隔离、二维码交付到定时发布的自动切换与 cookie 自动续期均可在源码中找到一一对应这也是把该 skill 用于多账号、并发化快手发布工作流时最可靠的依据。【免费下载链接】social-auto-upload自动化上传视频到社交媒体抖音、小红书、视频号、tiktok、youtube、bilibili项目地址: https://gitcode.com/GitHub_Trending/so/social-auto-upload创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考