408 lines
9.4 KiB
Markdown
408 lines
9.4 KiB
Markdown
# 浏览器平台 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`
|
||
|
||
### 统一后的上传参数模型
|
||
|
||
#### 视频上传
|
||
|
||
```bash
|
||
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`
|
||
|
||
#### 图文上传
|
||
|
||
```bash
|
||
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`
|
||
- 实现保持轻量，不做过度封装
|