python-cli-to-macos-applisted
Install: claude install-skill xingtu1996/xingtu-skills
# Python CLI → macOS .app(零依赖分发)
> 真实案例:`text2vido`(文本→视频)打包成 **114MB** 的 `Text2Vido.app`,拖 PDF 到图标即出片,
> 用户**不需装 Python / Ollama / 任何依赖**。产物见 `~/xingtu/text2vido/packaging/`。
---
## 第 0 步:先算体积账(这一步决定方案成立与否)
**最容易犯的错:拿开发 venv 的体积当安装包体积。**
开发 venv 常是多项目混用,里面一堆无关大包;而**分发只需要代码真正 import 的那几个**。
```bash
# ① 代码真正依赖什么(唯一可信来源)
grep -rhoE "^(import|from) [a-zA-Z_][a-zA-Z0-9_]*" src/**/*.py | awk '{print $2}' | sort -u
# ② 对比:venv 里最大的包 vs 直接依赖
du -sm <venv>/lib/python*/site-packages/* | sort -rn | head -10
```
**真实对照**:venv 1.4 GB(含 torch 437M / mlx 179M / playwright 133M —— 全是别的项目的),
实际只需 4 个包 ≈ **25 MB**。
| 组件 | 典型体积 | 是否内置 |
|---|---|---|
| Python 运行时(python-build-standalone) | 70–80 MB | ✅ |
| 最小依赖集 | 按实际 import 算 | ✅ |
| 原生二进制(ollama / 静态 ffmpeg 等) | 30–100 MB | ✅ |
| LLM 权重 | **GB 级** | ❌ **绝不内置** |
**模型/权重的判断铁律**:**不内置**。所有同类工具(LM Studio / Ollama / ComfyUI)都不内置模型。
安装包保持百 MB 级,权重首次运行下载,并**复用系统已有缓存目录**(别覆盖它的环境变量,否则用户白下几个 G)。
---
## 第 1 步:三条生死线(打包前必验,否则做完才发现不可分发)
### ① Python 运行时换目录还能跑吗?(relocatable)
```bash
cp -R <python-standalone> /tmp/relocate_test/py
/tmp/relocate_test/py/bin/python3 -c "import json, sqlite3, ssl; print('ok')"
cd /tmp && /tmp/relocate_test/py/bin/python3 -c "print('cwd-independent ok')"
```
✅ 通过 → 可内置(python-build-standalone 通常可)。
❌ 失败 → 需 `install_name_tool` 修 rpath,或改用 PyInstaller。
### ② 原生二进制能只拷一个文件吗?
```bash
otool -L $(readlink -f $(which <binary>)) | tail -n +2 | grep -c "/opt/homebrew\|/usr/local"
```
- **0** → 静态,直接拷 ✅
- **>0** → 绑定了包管理器的