TrueGrowth/vendor/social-auto-upload/docs/superpowers/specs/2026-03-25-browser-cli-unification-design.md

浏览器平台 CLI 统一与小红书 Skill 设计

日期：2026-03-25

概要

这份设计处理三个浏览器自动化平台的主线接口统一：

• 抖音
• 快手
• 小红书

目标不是重写 uploader，也不是再抽一层复杂框架，而是把当前已经存在但不一致的 CLI、skill、文档、示例收口成一套统一契约。

这次设计同时解决两个现实问题：

1. 小红书虽然已经有可用的浏览器 uploader，但还没有接入 sau CLI，也没有对应 skill。
2. 抖音、快手当前的 CLI 契约还带着历史字段，比如视频没有单独 --desc，而图文正文命名和视频描述语义混杂，不利于三家浏览器平台形成稳定统一的主线接口。

这次统一后的对外入口固定为：

• sau douyin ...
• sau kuaishou ...
• sau xiaohongshu ...

并让三家浏览器平台的视频、图文上传都遵循统一的主线参数模型：

• 视频：title + desc + tags
• 图文：title + note + tags

目标

• 给小红书补齐主线 CLI：
  • login
  • check
  • upload-video
  • upload-note
• 统一抖音、快手、小红书三家浏览器平台的 CLI 上传参数模型
• 补齐小红书 skill、示例脚本、README、CLI 文档、安装/更新文档
• 修正抖音、快手现有 CLI 契约里缺失的 desc 能力
• 保持现有 uploader 主体逻辑不大改，不做过度封装

非目标

• 这次不重构 uploader 架构
• 这次不改 Web 旧路径
• 这次不改 Bilibili 的上传契约
• 这次不做浏览器集成测试
• 这次不保留公开的 --note 主契约

当前项目基础

已有能力

• 抖音、快手已经接入 sau_cli.py
• Bilibili 已经接入 CLI 和 skill
• 小红书已经具备：
  • 登录
  • cookie 校验
  • 视频上传
  • 图文上传
  • 定时发布
• 小红书 uploader 内部已经支持：
  • 视频：title + desc + tags
  • 图文：title + desc + tags
  • 图文里的 desc 可选

当前不一致点

• 抖音视频 CLI：--title、--tags，没有 --desc
• 快手视频 CLI：--title、--tags，没有 --desc
• 抖音图文 CLI：--note、--tags
• 快手图文 CLI：--note、--tags
• 小红书还没有 CLI/skill 接口

也就是说，当前三家浏览器平台的主线能力并不统一，尤其是：

• 视频描述没有统一暴露为 desc
• 图文正文是否应该沿用 note 语义没有统一

统一后的 CLI 设计

支持的平台

• douyin
• kuaishou
• xiaohongshu

支持的动作

每个平台统一支持：

• login
• check
• upload-video
• upload-note

统一后的上传参数模型

视频上传

sau <platform> upload-video \
  --account <account_name> \
  --file <video-path> \
  --title "<title>" \
  [--desc "<description>"] \
  [--tags tag1,tag2] \
  [--schedule "YYYY-MM-DD HH:MM"] \
  [平台特有参数...]

统一规则：

• --title 必填
• --desc 选填
• --tags 选填
• --schedule 选填

平台特有参数：

• 抖音：
  • --thumbnail
  • --product-link
  • --product-title
• 快手：
  • --thumbnail
• 小红书：
  • --thumbnail

图文上传

sau <platform> upload-note \
  --account <account_name> \
  --images <image-1> [image-2 ...] \
  --title "<title>" \
  [--note "<content>"] \
  [--tags tag1,tag2] \
  [--schedule "YYYY-MM-DD HH:MM"]

统一规则：

• --images 必填
• --title 必填
• --note 选填
• --tags 选填
• --schedule 选填

明确决定：

• 图文主线正文统一叫 note
• 视频主线描述统一叫 desc
• 文档、skill、示例统一使用：
  • 视频：--title + --desc + --tags
  • 图文：--title + --note + --tags

数据模型设计

为了让 CLI 层和 uploader 层映射清晰，每个平台都保持各自的 request dataclass，但字段命名统一。

视频请求对象

统一字段：

• account_name
• video_file
• title
• description
• tags
• publish_date
• publish_strategy
• debug
• headless

平台特有字段保留：

• 抖音：
  • thumbnail_file
  • product_link
  • product_title
• 快手：
  • thumbnail_file
• 小红书：
  • thumbnail_file

图文请求对象

统一字段：

• account_name
• image_files
• title
• note
• tags
• publish_date
• publish_strategy
• debug
• headless

这里明确保留 note，因为它更符合图文正文语义，不应强行复用视频里的 description / desc 命名。

与现有 uploader 的映射

抖音

• 视频上传继续复用 DouYinVideo
• 给抖音视频补齐 desc 输入映射
• 图文上传改为显式接收 title + note + tags
• note 在 CLI 层映射到抖音图文正文输入区

快手

• 视频上传继续复用 KSVideo
• 给快手视频补齐 desc 输入映射
• 图文上传改为显式接收 title + note + tags

小红书

• 登录、校验直接接 xiaohongshu_setup / cookie_auth
• 视频上传复用 XiaoHongShuVideo
• 图文上传复用 XiaoHongShuNote
• 因为小红书 uploader 已经支持 title + desc + tags，CLI 层把 note 稳定映射到图文正文即可

兼容与迁移策略

这次采用“直接统一，不保留旧的模糊公开契约”的策略。

具体表现：

• README.md
• docs/CLI.md
• docs/install.md
• docs/update.md
• skills/douyin-upload/...
• skills/kuaishou-upload/...
• 新增 skills/xiaohongshu-upload/...
• scripts/examples/...

都会在同一轮里切换到新契约，避免出现：

• 一部分文档把图文正文写成 --note
• 一部分文档把图文正文写成 --desc

这样做的代价是旧示例命令会失效，但换来的是主线契约彻底统一：

• 视频永远是 desc
• 图文永远是 note

Skill 设计

新增：

• skills/xiaohongshu-upload/SKILL.md
• skills/xiaohongshu-upload/references/cli-contract.md
• skills/xiaohongshu-upload/references/runtime-requirements.md
• skills/xiaohongshu-upload/references/troubleshooting.md
• skills/xiaohongshu-upload/scripts/examples/xiaohongshu_commands.ps1
• skills/xiaohongshu-upload/scripts/examples/xiaohongshu_commands.sh
• skills/xiaohongshu-upload/scripts/examples/xiaohongshu_cli_template.py

并同步更新：

• skills/douyin-upload/SKILL.md
• skills/douyin-upload/references/cli-contract.md
• skills/kuaishou-upload/SKILL.md
• skills/kuaishou-upload/references/cli-contract.md

skill 原则继续保持：

• 优先走 sau
• agent 不要先读 uploader 源码
• CLI 失败时再看 troubleshooting
• 登录二维码图片优先直接展示给用户扫码

文档设计

至少更新：

• README.md
• docs/CLI.md
• docs/install.md
• docs/update.md

统一后的表达口径：

• 三家浏览器平台都已经接入 CLI
• 三家浏览器平台都已经接入 skill
• 视频上传统一字段：
  • title
  • desc
  • tags
• 图文上传统一字段：
  • title
  • note
  • tags
• account_name 是用户自定义账号名，不是固定只能叫 creator
• 一个 account_name 对应一个账号文件，可多账号隔离并发

Example 设计

examples 保留两类路径：

1. CLI 主线示例
2. 历史直连 uploader 示例

小红书需要补到和其他平台同等级的主线表达里：

• examples/get_xiaohongshu_cookie.py
• examples/upload_video_to_xiaohongshu.py
• 如有必要，补一份更贴近 CLI 契约的调用示例

README 和 docs 中要明确说明：

• 推荐优先使用 sau xiaohongshu ...
• 历史直连 uploader 示例只是调试入口

错误处理

参数级错误

由 CLI parser 负责：

• 文件不存在
• 时间格式非法
• 缺少 --title
• 缺少 --images

业务级错误

由 uploader 和现有校验负责：

• cookie 不存在
• cookie 已失效
• 上传失败
• 页面结构异常

二维码口径

三家浏览器平台统一保留这条说明：

• 如果登录流程生成了本地二维码图片，agent 应优先直接展示/发送图片给用户扫码，而不是只返回路径

测试策略

这次只做最小但有价值的 CLI 级验证，不做浏览器集成测试。

至少补这些测试：

• parser 能识别 xiaohongshu
• 三个平台新契约能正确解析：
  • upload-video --title --desc --tags
  • upload-note --images --title --note --tags
• dispatch 能正确把参数转成对应 request
• 小红书 login/check/upload-video/upload-note 分支能被正确路由

保留现有：

• tests/test_xiaohongshu_uploader.py

文件影响范围

必改

• sau_cli.py
• README.md
• docs/CLI.md
• docs/install.md
• docs/update.md

新增

• skills/xiaohongshu-upload/ 全套文件
• 对应 CLI 单测文件

同步修改

• skills/douyin-upload/...
• skills/kuaishou-upload/...
• examples/get_xiaohongshu_cookie.py
• examples/upload_video_to_xiaohongshu.py

推荐实现顺序

1. 先改 sau_cli.py 和 request 模型
2. 接上小红书 CLI 路由
3. 给抖音、快手补 desc / 图文新字段映射
4. 补 CLI 单测
5. 新增小红书 skill
6. 更新抖音、快手 skill 契约
7. 更新 README / CLI / install / update 文档
8. 更新 examples

最终结论

• 三家浏览器平台统一成同一套 CLI 动作：
  • login
  • check
  • upload-video
  • upload-note
• 三家浏览器平台统一成同一套主线元数据模型：
  • 视频：title + desc + tags
  • 图文：title + note + tags
• 小红书补齐 CLI 与 skill
• 抖音、快手补齐 desc 能力，并统一图文正文字段为 note
• 实现保持轻量，不做过度封装