| 1 | # Skill 分发与发布说明 |
| 2 | |
| 3 | 这份文档是给 `social-auto-upload` 后续做独立 skill 分发时用的。 |
| 4 | |
| 5 | 当前仓库已经具备两层能力： |
| 6 | |
| 7 | - 一个可安装的 CLI：`sau` |
| 8 | - 一个可被安装到 Codex 的内置 skill：`douyin-cli` |
| 9 | |
| 10 | 后续当主流程和 bug 修复完成后，可以再继续做 PyPI 发布、安装优化、以及更多平台的独立 skill。 |
| 11 | |
| 12 | ## 先说结论 |
| 13 | |
| 14 | `skill` 不一定必须是一个 Python 包。 |
| 15 | |
| 16 | 它可以是： |
| 17 | |
| 18 | - 一个 skill 目录 |
| 19 | - 一个独立仓库 |
| 20 | - 一个安装器脚本 |
| 21 | - 一个 Docker 镜像 |
| 22 | - 一个包管理器可安装的分发物 |
| 23 | |
| 24 | 但从“别人最快安装和使用”的角度看，最常见、最省事的仍然是： |
| 25 | |
| 26 | 1. 用一个安装包分发真正的运行能力 |
| 27 | 2. 用一个 skill 安装动作把 skill 放到 AI 工具的技能目录 |
| 28 | |
| 29 | 对这个项目来说，最推荐的形式是： |
| 30 | |
| 31 | - Python 包负责提供 `sau` 命令 |
| 32 | - `sau skill install` 负责把 skill 安装到 `~/.codex/skills/` |
| 33 | |
| 34 | 也就是： |
| 35 | |
| 36 | ```bash |
| 37 | pip install social-auto-upload |
| 38 | sau skill install |
| 39 | ``` |
| 40 | |
| 41 | ## skill 一定要是包吗 |
| 42 | |
| 43 | 不是。 |
| 44 | |
| 45 | ### 1. skill 只是一个目录 |
| 46 | |
| 47 | 这是最原始也最常见的形式。 |
| 48 | |
| 49 | 通常内容是： |
| 50 | |
| 51 | - `SKILL.md` |
| 52 | - `agents/openai.yaml` |
| 53 | - `references/` |
| 54 | - `scripts/` |
| 55 | |
| 56 | 这种形式本身已经是一个可用 skill 了，不一定需要打包。 |
| 57 | |
| 58 | 问题在于： |
| 59 | |
| 60 | - 用户要知道把它复制到哪里 |
| 61 | - 用户要手动安装 |
| 62 | - skill 如果依赖额外脚本或运行时，安装体验会比较差 |
| 63 | |
| 64 | 适合： |
| 65 | |
| 66 | - 内部团队 |
| 67 | - 仓库内开发规范 |
| 68 | - 还在快速迭代的 skill |
| 69 | |
| 70 | ### 2. skill 是一个独立仓库 |
| 71 | |
| 72 | 这也完全成立。 |
| 73 | |
| 74 | 例如： |
| 75 | |
| 76 | - 一个仓库专门放 `SKILL.md` |
| 77 | - 附带 `scripts/install.py` |
| 78 | - 或者 README 教用户复制到 `~/.codex/skills/` |
| 79 | |
| 80 | 这种模式的优点是： |
| 81 | |
| 82 | - skill 自己独立版本管理 |
| 83 | - 不依赖主业务仓库 |
| 84 | - 可以公开发布 |
| 85 | |
| 86 | 缺点是： |
| 87 | |
| 88 | - 用户还是可能要 clone |
| 89 | - 或者还需要执行安装脚本 |
| 90 | |
| 91 | 适合： |
| 92 | |
| 93 | - 想把 skill 当产品独立维护 |
| 94 | - skill 和业务代码已经明显拆开 |
| 95 | |
| 96 | ### 3. skill 跟随一个包分发 |
| 97 | |
| 98 | 这是当前这个项目最适合的方向。 |
| 99 | |
| 100 | 思路是： |
| 101 | |
| 102 | - Python 包里内置一份 skill 资源 |
| 103 | - 安装包后即可执行 `sau skill install` |
| 104 | - CLI 和 skill 一起发版 |
| 105 | |
| 106 | 优点是： |
| 107 | |
| 108 | - 用户体验最好 |
| 109 | - skill 和实际命令保持一致 |
| 110 | - 版本对应关系清晰 |
| 111 | - 不需要用户 clone 仓库 |
| 112 | |
| 113 | 适合： |
| 114 | |
| 115 | - skill 背后有真实 CLI/SDK/工具 |
| 116 | - 用户最终是要“使用能力”而不只是“阅读说明” |
| 117 | |
| 118 | ### 4. skill 用 Docker 交付 |
| 119 | |
| 120 | 也可以。 |
| 121 | |
| 122 | 常见方式是： |
| 123 | |
| 124 | - Docker 里装好运行环境 |
| 125 | - skill 告诉 AI 通过 `docker run ...` 去执行命令 |
| 126 | |
| 127 | 优点是： |
| 128 | |
| 129 | - 环境一致性很好 |
| 130 | - 本地依赖复杂时特别有用 |
| 131 | |
| 132 | 缺点是： |
| 133 | |
| 134 | - 用户必须先装 Docker |
| 135 | - 浏览器自动化、桌面登录、cookie、本地文件挂载都会更复杂 |
| 136 | - 对抖音这种需要本地浏览器交互的流程不一定更友好 |
| 137 | |
| 138 | 对当前项目来说，Docker 更适合： |
| 139 | |
| 140 | - 后端服务 |
| 141 | - 批处理任务 |
| 142 | - 服务器环境 |
| 143 | |
| 144 | 不太适合作为“普通用户首次使用抖音登录 skill”的唯一交付方式。 |
| 145 | |
| 146 | ## AI 安装环境、启动脚本、仓库，这些算不算 skill |
| 147 | |
| 148 | 算，但要区分“skill 本体”和“skill 的安装/运行载体”。 |
| 149 | |
| 150 | 可以这样理解： |
| 151 | |
| 152 | - `SKILL.md` 是 skill 本体 |
| 153 | - 仓库、包、Docker、安装脚本，是 skill 的分发和运行载体 |
| 154 | |
| 155 | 所以： |
| 156 | |
| 157 | - skill 可以住在仓库里 |
| 158 | - skill 可以被包一起带出去 |
| 159 | - skill 也可以借助 Docker 运行它依赖的环境 |
| 160 | |
| 161 | 只要最终用户能： |
| 162 | |
| 163 | 1. 安装它 |
| 164 | 2. 让 AI 发现它 |
| 165 | 3. 真正调用它依赖的能力 |
| 166 | |
| 167 | 那它就是成立的。 |
| 168 | |
| 169 | ## 对这个项目最合适的方案 |
| 170 | |
| 171 | ### 当前推荐方案 |
| 172 | |
| 173 | 第一阶段： |
| 174 | |
| 175 | - 继续在这个仓库里修主流程和 bug |
| 176 | - 保持 `sau` 命令稳定 |
| 177 | - 保持包内 skill 与 CLI 契约一致 |
| 178 | |
| 179 | 第二阶段： |
| 180 | |
| 181 | - 打包并发布到 PyPI |
| 182 | - 用户通过 `pip install social-auto-upload` 安装 |
| 183 | - 用户执行 `sau skill install` |
| 184 | |
| 185 | 第三阶段： |
| 186 | |
| 187 | - 根据需要把更多平台拆成独立 skill |
| 188 | - 例如 `douyin-cli`、`tencent-cli`、`tiktok-cli` |
| 189 | |
| 190 | ### 为什么现在不优先做“独立 skill 仓库” |
| 191 | |
| 192 | 因为当前最核心的问题还不是“skill 放哪”，而是： |
| 193 | |
| 194 | - 上传流程是否稳定 |
| 195 | - CLI 契约是否稳定 |
| 196 | - 实际用户安装后能不能跑通 |
| 197 | |
| 198 | 在这些都还在收敛的阶段，先让 skill 随包分发是最稳妥的。 |
| 199 | |
| 200 | ## 未来可选的三种正式发布路线 |
| 201 | |
| 202 | ### 路线 A：PyPI 包 + 包内 skill |
| 203 | |
| 204 | 用户安装： |
| 205 | |
| 206 | ```bash |
| 207 | pip install social-auto-upload |
| 208 | sau skill install |
| 209 | ``` |
| 210 | |
| 211 | 优点： |
| 212 | |
| 213 | - 最容易传播 |
| 214 | - 安装简单 |
| 215 | - 版本管理清晰 |
| 216 | |
| 217 | 这是当前首选路线。 |
| 218 | |
| 219 | ### 路线 B：独立 skill 仓库 + PyPI 包 |
| 220 | |
| 221 | 用户安装能力： |
| 222 | |
| 223 | ```bash |
| 224 | pip install social-auto-upload |
| 225 | ``` |
| 226 | |
| 227 | 用户安装 skill： |
| 228 | |
| 229 | - clone skill 仓库 |
| 230 | - 或跑 skill 仓库提供的安装脚本 |
| 231 | |
| 232 | 优点： |
| 233 | |
| 234 | - skill 可以单独演进 |
| 235 | - 可以给不同 AI 工具维护不同 metadata |
| 236 | |
| 237 | 缺点： |
| 238 | |
| 239 | - 安装链路更长 |
| 240 | |
| 241 | ### 路线 C：Docker + skill |
| 242 | |
| 243 | 用户： |
| 244 | |
| 245 | - 安装 Docker |
| 246 | - 拉镜像 |
| 247 | - 安装 skill |
| 248 | - skill 内部调用 docker 命令 |
| 249 | |
| 250 | 优点： |
| 251 | |
| 252 | - 依赖环境最稳定 |
| 253 | |
| 254 | 缺点： |
| 255 | |
| 256 | - 对本地浏览器自动化和交互式登录不够友好 |
| 257 | |
| 258 | 更适合服务端任务，不是当前首选。 |
| 259 | |
| 260 | ## 当前项目的发布建议 |
| 261 | |
| 262 | 当主流程稳定后，建议按这个顺序走： |
| 263 | |
| 264 | 1. 先保证 `sau douyin login/check/upload` 真机可用 |
| 265 | 2. 验证 `sau skill install` 安装后的 skill 可以被 Codex 正常识别 |
| 266 | 3. 本地打 wheel 做一次冷启动安装测试 |
| 267 | 4. 再发布 PyPI |
| 268 | |
| 269 | 建议的最终用户路径是： |
| 270 | |
| 271 | ```bash |
| 272 | pip install social-auto-upload |
| 273 | playwright install chromium |
| 274 | sau skill install |
| 275 | sau douyin login --account my-account |
| 276 | ``` |
| 277 | |
| 278 | ## 一句话回答 |
| 279 | |
| 280 | `skill` 不是必须做成包，但如果你想让别人“最快安装、最少理解成本、最少手工操作”，那就最好让“运行能力”走包分发，让 `skill` 跟着包一起被安装。 |
| 281 | |
| 282 | 对这个项目来说，最佳落地方案不是“只发一个 skill 仓库”，而是： |
| 283 | |
| 284 | - `social-auto-upload` 作为可安装包 |
| 285 | - `douyin-cli` 作为包内 skill |
| 286 | - `sau skill install` 作为安装桥梁 |
| 287 |