cmshoppe/docs/packaging.md

打包与分发

T-524 目标：先把当前 Windows 桌面工具打成免安装 onedir .exe，方便第一版交付使用。暂不做自动更新器、安装器、增量补丁或在线升级。

一、打包前提

• 在 Windows 环境执行。
• Python 环境已能运行源码版 python main.py。
• 打包脚本使用当前 PATH 中的 python；正式出包前先确认 python --version 符合项目目标 Python 3.10+。
• 安装运行依赖和打包依赖：

python -m pip install -r requirements-build.txt

requirements-build.txt 会先安装 requirements.txt 的运行依赖，再安装 PyInstaller。

二、打包命令

powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1

脚本会执行：

python -m PyInstaller --noconfirm --clean cmshopee.spec

成功后输出：

dist\cmshopee\cmshopee.exe

发布给用户时，以整个 dist\cmshopee\ 文件夹为单位压缩分发，用户双击 cmshopee.exe 启动。

三、绝不打包的本地数据

发布包里不能包含以下本地数据、密钥、业务数据或登录态：

• config.json
• config/ai_models.json
• cmshopee.db、cmshopee.db-wal、cmshopee.db-shm
• db.sqlite
• chrome_user_data_dir/
• images/
• logs/
• prompts/
• title_prompt.txt
• 运营填写后的 Excel 文件

cmshopee.spec 不声明任何 datas；scripts/build_exe.ps1 会在打包后检查 dist\cmshopee\，如果发现上述路径会直接失败。

四、首次运行与本地数据位置

打包版启动时，main.py 会把工作目录切到 cmshopee.exe 所在目录。

因此首次运行时，现有代码会按默认值在 exe 同级目录生成或使用本地文件：

• config.json
• config/ai_models.json
• cmshopee.db
• chrome_user_data_dir/
• images/
• logs/
• prompts/、title_prompt.txt（用户维护提示词时生成）

这些文件属于用户本地数据，不随新版本程序包覆盖。

五、用户后续更新方式

第一版不做自动更新。给用户发新版本时：

1. 让用户先关闭 cmshopee。
2. 建议用户备份当前整个程序文件夹。
3. 解压新版 dist\cmshopee\。
4. 只覆盖程序文件，例如 cmshopee.exe 和 _internal/。
5. 不删除也不覆盖用户原有的 config.json、config/ai_models.json、cmshopee.db、chrome_user_data_dir/、images/、logs/、prompts/、title_prompt.txt。

如果用户把整个旧目录删除再放新版，账号、任务记录、图片和登录态也会一起丢失，只能从备份恢复。

六、验证清单

打包前后至少执行：

python -m compileall app main.py
python -m unittest discover -s tests
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1

打包成功后确认：

• dist\cmshopee\cmshopee.exe 存在。
• dist\cmshopee\ 中没有第三节列出的本地数据。
• 在干净目录首次启动时能生成默认配置并进入 GUI。
• 在目标 Windows 10/11 机器或虚拟机上启动 release exe 后，主窗口标题栏完整可见，左边缘不出屏，用户能用标题栏拖动窗口；小分辨率环境不得出现窗口卡在左上角且标题栏不可拖动的问题（见 T-541）。

涉及 Shopee/CDP 的真实更新能力，仍按任务文档要求用测试商品做人工回归；打包任务本身不新增自动绕过登录、验证码或风控的能力。