| 1 | # 安装说明 |
| 2 | |
| 3 | 这个文档分成两部分： |
| 4 | |
| 5 | - `For Humans`：给正常使用仓库的开发者、创作者、CLI 用户看 |
| 6 | - `For AI Agents`：给 OpenClaw、Codex、Claude Code 一类 agent 看 |
| 7 | |
| 8 | 如果你是“正在使用 agent 客户端的人”，想先给 agent 一段启动提示词，而不是直接阅读下面的执行细节，先看： |
| 9 | |
| 10 | - [Agent Bootstrap Prompt](./agent-bootstrap.md) |
| 11 | |
| 12 | ## For Humans |
| 13 | |
| 14 | ### 1. 克隆项目 |
| 15 | |
| 16 | ```bash |
| 17 | git clone https://github.com/dreammis/social-auto-upload.git |
| 18 | cd social-auto-upload |
| 19 | ``` |
| 20 | |
| 21 | ### 2. 创建虚拟环境 |
| 22 | |
| 23 | 推荐使用 `uv`： |
| 24 | |
| 25 | Windows PowerShell： |
| 26 | |
| 27 | ```powershell |
| 28 | uv venv |
| 29 | .venv\Scripts\activate |
| 30 | ``` |
| 31 | |
| 32 | Linux / macOS： |
| 33 | |
| 34 | ```bash |
| 35 | uv venv |
| 36 | source .venv/bin/activate |
| 37 | ``` |
| 38 | |
| 39 | ### 3. 安装主线依赖 |
| 40 | |
| 41 | 当前主线依赖已经放到 `pyproject.toml`，推荐直接执行： |
| 42 | |
| 43 | ```bash |
| 44 | uv pip install -e . |
| 45 | ``` |
| 46 | |
| 47 | 安装完成后，会注册 `sau` 命令。 |
| 48 | |
| 49 | ### 4. 安装 patchright Chromium |
| 50 | |
| 51 | 当前主线使用 `patchright` 驱动浏览器。 |
| 52 | |
| 53 | 国内用户推荐先指定镜像，再安装 Chromium。 |
| 54 | |
| 55 | Windows PowerShell： |
| 56 | |
| 57 | ```powershell |
| 58 | $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium |
| 59 | ``` |
| 60 | |
| 61 | Linux / macOS： |
| 62 | |
| 63 | ```bash |
| 64 | PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium |
| 65 | ``` |
| 66 | |
| 67 | ### 5. 配置 conf.py |
| 68 | |
| 69 | 复制一份配置： |
| 70 | |
| 71 | ```bash |
| 72 | cp conf.example.py conf.py |
| 73 | ``` |
| 74 | |
| 75 | Windows 也可以直接手动复制并重命名。 |
| 76 | |
| 77 | 当前通常还会用到这些配置项： |
| 78 | |
| 79 | - `LOCAL_CHROME_PATH` |
| 80 | - `LOCAL_CHROME_HEADLESS` |
| 81 | - `DEBUG_MODE` |
| 82 | |
| 83 | `XHS_SERVER` 目前只和小红书旧流程相关。 |
| 84 | |
| 85 | ### 6. 验证 CLI 是否可用 |
| 86 | |
| 87 | ```bash |
| 88 | sau --help |
| 89 | sau douyin --help |
| 90 | sau kuaishou --help |
| 91 | sau xiaohongshu --help |
| 92 | sau bilibili --help |
| 93 | ``` |
| 94 | |
| 95 | 如果命令找不到，优先确认： |
| 96 | |
| 97 | - 当前虚拟环境是否已激活 |
| 98 | - 是否执行过 `uv pip install -e .` |
| 99 | |
| 100 | ### 7. 抖音主线示例 |
| 101 | |
| 102 | ```bash |
| 103 | sau douyin login --account <account_name> |
| 104 | sau douyin check --account <account_name> |
| 105 | sau douyin upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" |
| 106 | 图文正文1: |
| 107 | $noteText = @"图文正文"@ |
| 108 | sau douyin upload-note --account <account_name> --images videos/demo1.png videos/demo2.png --title "图文标题" --note $noteText --tags 'tag1,tag2' |
| 109 | 图文正文2: |
| 110 | sau douyin upload-note --account <account_name> --images videos/demo1.png videos/demo2.png --title "图文标题" --notef '图文文件路径' --tags 'tag1,tag2' |
| 111 | 添加 BGM（可选）: |
| 112 | sau douyin upload-note --account <account_name> --images videos/demo1.png videos/demo2.png --title "图文标题" --note $noteText --tags 'tag1,tag2' --bgm '音乐名称' |
| 113 | ``` |
| 114 | |
| 115 | 抖音短信验证码补充说明： |
| 116 | |
| 117 | - 视频发布过程中如果触发短信二次验证，程序会优先读取项目根目录下的 `verify_code.txt` |
| 118 | - 如果当前是你手动运行的交互式终端，没提供 `verify_code.txt` 时，CLI 会直接提示你在终端输入验证码 |
| 119 | - 如果是 agent 或自动化桥接场景，仍然可以继续通过写入 `verify_code.txt` 来提供验证码 |
| 120 | - 验证通过后，程序会自动删除 `verify_code.txt` |
| 121 | |
| 122 | 抖音卡login手动获取cookie: |
| 123 | |
| 124 | - 目标服务器使用vnc |
| 125 | - 浏览器登录抖音创作者中心https://creator.douyin.com/ |
| 126 | - 执行`bash export_douyin_cookie.sh --account <account_name>` |
| 127 | - 检查cookie可用性,执行`sau douyin check --account <account_name>` |
| 128 | |
| 129 | ### 8. 快手主线示例 |
| 130 | |
| 131 | ```bash |
| 132 | sau kuaishou login --account <account_name> |
| 133 | sau kuaishou check --account <account_name> |
| 134 | sau kuaishou upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" |
| 135 | sau kuaishou upload-note --account <account_name> --images videos/demo1.png videos/demo2.png videos/demo.png --title "图文标题" --note "图文正文" |
| 136 | ``` |
| 137 | |
| 138 | ### 9. 小红书主线示例 |
| 139 | |
| 140 | ```bash |
| 141 | sau xiaohongshu login --account <account_name> |
| 142 | sau xiaohongshu check --account <account_name> |
| 143 | sau xiaohongshu upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" |
| 144 | sau xiaohongshu upload-note --account <account_name> --images videos/demo1.png videos/demo2.png videos/demo.png --title "图文标题" --note "图文正文" |
| 145 | ``` |
| 146 | |
| 147 | ### 10. Bilibili 主线示例 |
| 148 | |
| 149 | ```bash |
| 150 | sau bilibili login --account <account_name> |
| 151 | sau bilibili check --account <account_name> |
| 152 | sau bilibili upload-video --account <account_name> --file videos/demo.mp4 --title "示例标题" --desc "示例简介" --tid 249 |
| 153 | ``` |
| 154 | |
| 155 | 补充说明： |
| 156 | |
| 157 | - `creator` 之类的名字只是示例值，真正传的是用户自定义的 `account_name` |
| 158 | - 一个 `account_name` 对应一个账号文件，可以准备多个账号并发使用 |
| 159 | - 浏览器平台统一元数据约定： |
| 160 | - 视频使用 `title + desc + tags` |
| 161 | - 图文使用 `title + note + tags` |
| 162 | - 用户不需要手动安装 `biliup` |
| 163 | - 首次运行 Bilibili 相关命令时，程序会自动下载 `biliup` |
| 164 | - 后续运行会自动检查上游 release 并自动更新 |
| 165 | - Bilibili 登录建议由用户自己在本地真实终端里执行；如果终端里的二维码显示不完整，可直接打开当前目录下的 `qrcode.png` 扫码 |
| 166 | - 如果国内网络访问 GitHub Release 较慢，可先用 `https://gh-proxy.com/` 或 `https://gh-proxy.org/` 辅助访问对应 release 地址排障 |
| 167 | - 示例： |
| 168 | - `https://gh-proxy.org/https://github.com/biliup/biliup/releases/download/v1.1.29/biliupR-v1.1.29-aarch64-linux.tar.xz` |
| 169 | |
| 170 | ## For AI Agents |
| 171 | |
| 172 | 如果你是一个可执行命令的 agent，请优先按下面顺序处理： |
| 173 | |
| 174 | 1. 先假设仓库根目录就是当前工作目录 |
| 175 | 2. 优先使用 `uv` 管理环境，不要默认回退到旧的 `requirements.txt` |
| 176 | 3. 安装命令优先使用： |
| 177 | |
| 178 | ```bash |
| 179 | uv pip install -e . |
| 180 | ``` |
| 181 | |
| 182 | 4. 如需浏览器驱动，优先使用： |
| 183 | |
| 184 | Windows PowerShell： |
| 185 | |
| 186 | ```powershell |
| 187 | $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; patchright install chromium |
| 188 | ``` |
| 189 | |
| 190 | Linux / macOS： |
| 191 | |
| 192 | ```bash |
| 193 | PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" patchright install chromium |
| 194 | ``` |
| 195 | |
| 196 | 5. 安装完成后，优先检查： |
| 197 | |
| 198 | ```bash |
| 199 | sau --help |
| 200 | sau douyin --help |
| 201 | sau kuaishou --help |
| 202 | sau xiaohongshu --help |
| 203 | sau bilibili --help |
| 204 | ``` |
| 205 | |
| 206 | 6. 如果用户的目标是抖音或快手的登录、cookie 校验、视频上传、图文上传，优先走 CLI： |
| 207 | |
| 208 | ```bash |
| 209 | sau douyin login |
| 210 | sau douyin check |
| 211 | sau douyin upload-video |
| 212 | sau douyin upload-note |
| 213 | |
| 214 | sau kuaishou login |
| 215 | sau kuaishou check |
| 216 | sau kuaishou upload-video |
| 217 | sau kuaishou upload-note |
| 218 | |
| 219 | sau xiaohongshu login |
| 220 | sau xiaohongshu check |
| 221 | sau xiaohongshu upload-video |
| 222 | sau xiaohongshu upload-note |
| 223 | |
| 224 | sau bilibili login |
| 225 | sau bilibili check |
| 226 | sau bilibili upload-video |
| 227 | ``` |
| 228 | |
| 229 | 7. 如果用户明确在使用 skill 系统，再引导其阅读： |
| 230 | |
| 231 | - `skills/douyin-upload/SKILL.md` |
| 232 | - `skills/douyin-upload/references/cli-contract.md` |
| 233 | - `skills/kuaishou-upload/SKILL.md` |
| 234 | - `skills/kuaishou-upload/references/cli-contract.md` |
| 235 | - `skills/xiaohongshu-upload/SKILL.md` |
| 236 | - `skills/xiaohongshu-upload/references/cli-contract.md` |
| 237 | - `skills/bilibili-upload/SKILL.md` |
| 238 | - `skills/bilibili-upload/references/cli-contract.md` |
| 239 | |
| 240 | ### 对 agent 的额外说明 |
| 241 | |
| 242 | - 当登录流程生成本地二维码图片时，不要只把图片路径发给用户 |
| 243 | - 这类二维码图片本身就是给用户扫码的，agent 应优先直接展示/发送本地图片给用户扫码 |
| 244 | - 如果环境支持查看本地图片，优先用查看图片能力把二维码展示出来；路径只作为补充信息 |
| 245 | - Bilibili 登录当前不建议 agent 在非交互环境里直接代跑 |
| 246 | - 正确做法是让用户自己在本地终端执行 `sau bilibili login --account <name>`；如果二维码显示不完整，再提示用户打开 `qrcode.png` |
| 247 | - `requirements.txt` 目前是历史兼容文件，不是主安装入口 |
| 248 | - `uploader/` 是核心实现目录 |
| 249 | - `sau_cli.py` 是当前 CLI 主入口 |
| 250 | - `docs/legacy-web.md` 是历史 Web 版本说明，不保证当前可用 |
| 251 | - Bilibili 首次运行时可能自动下载 `biliup` |
| 252 |