Track bundled vendor runtime sources

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

@@ -0,0 +1,279 @@
+# Bilibili CLI 设计
+
+日期：2026-03-25
+
+## 概要
+
+这份设计要把 `bilibili` 挂到 `sau` 下面，用户侧体验尽量和现在的 `douyin`、`kuaishou` 保持一致。
+
+核心约束只有两个：
+
+- 用户不需要自己安装 `biliup`
+- 外部统一走 `sau bilibili ...`
+
+程序会把 `biliup` 当作内部运行时依赖来处理：
+
+- `sau bilibili ...` 是唯一公开入口
+- 本地没有 `biliup` 时自动下载
+- 每次运行都检查 GitHub Release 最新版本
+- 如果发现有更新，先自动更新，再继续执行当前命令
+
+这份设计刻意保持轻量，不重新发明一套 B 站上传语义，而是直接复用仓库里现有的 B 站上传模型。
+
+## 目标
+
+- 让 `sau bilibili ...` 和 `sau douyin ...`、`sau kuaishou ...` 保持统一心智
+- 隐藏 `biliup` 的安装细节，降低用户使用成本
+- 复用项目里已经存在的账号文件、`VideoZoneTypes`、定时发布等能力
+- 不做过度封装
+
+## 非目标
+
+- 第一版不把 `biliup` 二进制直接提交进仓库
+- 第一版不维护本地 release manifest
+- 第一版不做 B 站图文发布
+- 第一版不重做现有的 B 站上传领域模型
+
+## 当前项目基础
+
+仓库里已经有 B 站上传能力：
+
+- `uploader/bilibili_uploader/main.py` 目前直接封装了 `biliup.plugins.bili_webup`
+- `examples/upload_video_to_bilibili.py` 已经在使用现有上传参数
+- `utils/constant.py` 已经定义了完整的 `VideoZoneTypes`
+
+也就是说，你现在项目里的 B 站上传语义已经很明确，核心就是：
+
+- `file`
+- `title`
+- `desc`
+- `tid`
+- `tags`
+- `dtime`
+
+所以第一版 CLI 不需要重新造模型，直接沿用这套。
+
+## 用户侧 CLI 设计
+
+### 支持的命令
+
+- `sau bilibili login`
+- `sau bilibili check`
+- `sau bilibili upload-video`
+
+### 命令契约
+
+#### `sau bilibili login`
+
+作用：
+
+- 自动准备 `biliup`
+- 如果有更新则先升级
+- 然后调用 `biliup` 完成登录
+- 将账号数据按项目自己的账号文件规则保存下来
+
+第一版行为：
+
+- 本地没有 `biliup` 时自动下载最新 release
+- 本地已有但上游有更新时自动升级
+- 升级完成后继续执行登录流程
+
+#### `sau bilibili check`
+
+作用：
+
+- 自动准备 `biliup`
+- 检查当前账号是否可用
+
+第一版行为：
+
+- 结合本地账号文件存在性和 `biliup` 实际可用性来判断
+- 输出风格和其他平台保持一致：
+  - `valid`
+  - `invalid`
+
+#### `sau bilibili upload-video`
+
+作用：
+
+- 自动准备 `biliup`
+- 走项目当前已有的 B 站上传参数体系完成视频上传
+
+第一版参数：
+
+- `--account` 必填
+- `--file` 必填
+- `--title` 必填
+- `--desc` 必填
+- `--tid` 必填
+- `--tags` 选填
+- `--schedule` 选填
+
+明确决定：
+
+- `tid` 在第一版里必须传
+- 不给默认分区，避免猜测和隐式错误
+
+## 运行时依赖策略
+
+### 选定方案
+
+`biliup` 不提交进仓库，也不要求用户手工安装。
+
+`sau bilibili ...` 在运行时自动处理它：
+
+1. 查找本地是否已有 `biliup`
+2. 检查 GitHub Release 最新版本
+3. 如果缺失或过期，则自动下载最新版本
+4. 替换本地运行时副本
+5. 继续执行本次命令
+
+### 选择这个方案的原因
+
+- 仓库体积更干净
+- 用户不需要自己找 release、自己下载
+- 对外仍然只有一个统一入口 `sau`
+- 不需要使用 `git submodule`
+
+### 接受的代价
+
+这套方案明确接受一个现实：
+
+- 每次运行都会检查上游 release
+- 上游如果改 CLI 行为，可能会影响这层适配
+
+所以这里的应对方式不是做重封装，而是保持 wrapper 很薄，减少被动维护成本。
+
+## 存储与解析
+
+`biliup` 应该存放在本地运行时缓存目录中，而不是源码目录中。
+
+缓存目录只需要满足：
+
+- 当前用户可写
+- 可跨命令复用
+- 不进入 git 管理
+
+解析器的职责应当是：
+
+- 识别当前操作系统
+- 选择对应平台的 release asset
+- 下载并替换可执行文件
+- 返回最终可执行路径
+
+## 轻量封装边界
+
+为了避免过度封装，第一版只建议拆成 3 个很薄的部分。
+
+### 1. Resolver
+
+职责：
+
+- 判断本地是否已有 `biliup`
+- 检查 GitHub Release 最新版本
+- 下载或更新可执行文件
+- 返回最终可执行文件路径
+
+### 2. Runner
+
+职责：
+
+- 调用解析出来的 `biliup`
+- 收集退出码、标准输出、标准错误
+- 对明显的进程级错误做一层项目内友好的报错转换
+
+### 3. `sau_cli.py` 中的 bilibili 子命令
+
+职责：
+
+- 解析 `sau bilibili ...` 参数
+- 把这些参数翻译成底层运行逻辑
+- 让帮助信息风格和其他平台一致
+
+第一版不需要更多层，也不需要再抽一套很重的统一框架。
+
+## 与现有项目概念的映射
+
+### 账号文件
+
+B 站也继续沿用现在项目的账号别名机制：
+
+- 用户传 `--account <name>`
+- 程序解析成对应的账号文件路径
+
+### 分区
+
+`tid` 保持为一等参数。
+
+`VideoZoneTypes` 继续保留并服务于：
+
+- example
+- 文档
+- 后续可能的辅助工具
+
+### 定时发布
+
+`--schedule` 保持和当前 `sau` 其他平台一致的使用方式：
+
+- 不传就是立即发布
+- 传了就是定时发布
+
+具体如何映射到底层 B 站执行逻辑，由 adapter 负责，不暴露给用户。
+
+## 错误处理
+
+第一版错误处理保持直接，不做花哨包装：
+
+- 下载失败：明确告诉用户自动下载 `biliup` 失败
+- 更新失败：明确告诉用户最新 release 准备失败
+- 登录失败：保留 `biliup` 登录失败上下文
+- 检查失败：输出 `invalid`
+- 上传失败：返回非零退出码，并展示上游错误摘要
+
+第一版不追求把所有 `biliup` 错误文本都重新翻译一遍。
+
+## 文档影响范围
+
+实现完成后，至少需要补齐这些地方：
+
+- `README.md`
+- `docs/CLI.md`
+- 安装与更新文档
+- 一套对应的 Bilibili skill
+- Bilibili example 脚本
+
+对外表达应当统一成：
+
+- 用户使用的是 `sau bilibili ...`
+- `biliup` 由程序自动准备
+
+## 测试策略
+
+第一版最少需要验证这些路径：
+
+- `sau bilibili login --account <name>`
+- `sau bilibili check --account <name>`
+- `sau bilibili upload-video ...`
+- 本地没有 `biliup` 时能自动下载
+- 本地已有旧版本时能先升级再执行
+- 本地已有最新版本时能直接复用
+
+因为登录和上传涉及真实外部平台，第一版以手工验证为主是可以接受的。
+
+## 推荐实现顺序
+
+1. 在 `sau_cli.py` 中加入 `bilibili` 子命令
+2. 增加一个最小可用的 `biliup` resolver
+3. 增加一个最小可用的 `biliup` runner
+4. 接上 `login / check / upload-video`
+5. 补文档、example、skill
+
+## 最终结论
+
+- 对外入口固定为 `sau bilibili ...`
+- 第一版支持 `login`、`check`、`upload-video`
+- `tid` 必填
+- `biliup` 不需要用户手动安装
+- 每次运行都检查 GitHub Release
+- 有新版本时先自动更新，再继续执行
+- 整体实现保持轻量，不做过度封装

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

@@ -0,0 +1,407 @@
+# 浏览器平台 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`
+- 实现保持轻量，不做过度封装