1. 重构快手

- 图文增加 - 封面增加 2. 快手skill,cli支持
2026-03-25 02:25:02 +08:00
parent 2934328888
commit b415613b38
25 changed files with 1343 additions and 227 deletions
@@ -0,0 +1,95 @@
+# 快手 CLI 契约
+
+这个 skill 默认假设当前环境已经安装并可调用 `sau` 命令。
+
+## 命令列表
+
+### 登录
+
+```bash
+sau kuaishou login --account <account>
+```
+
+- 必填参数:
+  - `--account`
+- 作用:
+  - 启动快手登录流程，为指定账号生成或刷新 cookie 文件
+  - 如果登录过程中生成本地二维码图片，agent 应优先直接把图片展示/发送给用户扫码，而不是只回传路径
+
+### 校验 cookie
+
+```bash
+sau kuaishou check --account <account>
+```
+
+- 必填参数:
+  - `--account`
+- 预期输出:
+  - `valid`：cookie 可用
+  - `invalid`：cookie 缺失或已失效
+
+### 上传视频
+
+```bash
+sau kuaishou upload-video \
+  --account <account> \
+  --file <video-path> \
+  --title "<title>" \
+  [--tags tag1,tag2] \
+  [--schedule "YYYY-MM-DD HH:MM"] \
+  [--thumbnail <image-path>] \
+  [--debug] \
+  [--headless | --headed]
+```
+
+- 必填参数:
+  - `--account`
+  - `--file`
+  - `--title`
+- 可选参数:
+  - `--tags`
+  - `--schedule`
+  - `--thumbnail`
+  - `--debug`
+  - `--headless`
+  - `--headed`
+
+### 上传图文
+
+```bash
+sau kuaishou upload-note \
+  --account <account> \
+  --images <image-1> [image-2 ...] \
+  --note "<content>" \
+  [--tags tag1,tag2] \
+  [--schedule "YYYY-MM-DD HH:MM"] \
+  [--debug] \
+  [--headless | --headed]
+```
+
+- 必填参数:
+  - `--account`
+  - `--images`
+  - `--note`
+- 可选参数:
+  - `--tags`
+  - `--schedule`
+  - `--debug`
+  - `--headless`
+  - `--headed`
+
+## 发布策略
+
+- 如果不传 `--schedule`，CLI 使用立即发布
+- 如果传了 `--schedule`，CLI 自动切换为定时发布
+- 时间格式为:
+
+```text
+YYYY-MM-DD HH:MM
+```
+
+## 额外说明
+
+- `upload-video` 每次命令只支持一个视频文件
+- `upload-note` 每次命令支持多张图片
+- `upload-note` 当前要求传入真实的多张图片文件，而不是同一路径重复多次
@@ -0,0 +1,67 @@
+# 运行前提
+
+这个 skill 默认假设当前环境已经具备：
+
+- 已安装 `social-auto-upload`
+- 可以调用 `sau` 命令，或至少有等效调用方式
+- 已为 `patchright` 安装 Chromium
+
+## 推荐安装方式
+
+在项目根目录执行：
+
+```bash
+uv pip install -e .
+```
+
+## 安装 patchright 浏览器
+
+Windows PowerShell：
+
+```powershell
+$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium
+```
+
+Linux / macOS（bash / zsh）：
+
+```bash
+PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium
+```
+
+## 常见调用方式
+
+### 如果 `sau` 已经在 PATH 中
+
+```bash
+sau kuaishou --help
+```
+
+### 如果虚拟环境存在，但还没有激活
+
+PowerShell：
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+sau kuaishou --help
+```
+
+### 如果你想直接调用可执行文件
+
+PowerShell：
+
+```powershell
+.\.venv\Scripts\sau.exe kuaishou --help
+```
+
+### 如果你更倾向于使用 uv
+
+```bash
+uv run sau kuaishou --help
+```
+
+## 无头和有头模式
+
+- 使用 `--headless` 表示无头模式
+- 使用 `--headed` 表示有头模式
+- 快手登录如果遇到二维码展示问题，优先切到 `--headed`
+- 如果登录过程中已经生成了本地二维码图片，agent 应优先直接把图片展示/发送给用户扫码，不要只告诉用户图片路径
@@ -0,0 +1,82 @@
+# 故障排查
+
+## 找不到 `sau` 命令
+
+可以尝试以下方式：
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+sau kuaishou --help
+```
+
+```powershell
+.\.venv\Scripts\sau.exe kuaishou --help
+```
+
+```bash
+uv run sau kuaishou --help
+```
+
+如果当前环境还没有安装项目：
+
+```bash
+uv pip install -e .
+```
+
+## cookie 无效或已过期
+
+先检查 cookie 状态：
+
+```bash
+sau kuaishou check --account <account>
+```
+
+如果无效，就重新登录：
+
+```bash
+sau kuaishou login --account <account>
+```
+
+## 登录二维码问题
+
+如果用户反馈二维码在终端里不好扫：
+
+- 优先让用户切到 `--headed`
+- 如果 CLI / uploader 已经生成临时二维码图片，agent 不要只回图片路径
+- agent 应优先直接把本地二维码图片展示/发送给用户扫码
+- 图片路径只作为补充信息
+
+## 上传参数缺失
+
+### 视频上传
+
+最少需要：
+
+- `--account`
+- `--file`
+- `--title`
+
+### 图文上传
+
+最少需要：
+
+- `--account`
+- `--images`
+- `--note`
+
+## 图文上传只有一张生效
+
+如果用户一次传了多张图片，但页面只识别到一张，先确认：
+
+- `--images` 里传的是不是真正不同的文件
+- 不是同一路径重复多次
+
+## 定时发布
+
+时间格式使用：
+
+```text
+YYYY-MM-DD HH:MM
+```
+
+如果不需要定时发布，去掉 `--schedule` 即可改为立即发布。