cmbot/docs/09-packaging-release.md

打包发布设计

1. 文档定位

本文档定义第一阶段的本地打包和发布规则。当前阶段只考虑将软件打包为可在 Windows 电脑上运行的桌面程序。

暂不包含：

• 局域网分发。
• 自动更新。
• 多版本启动器。
• 强制升级策略。
• 远程版本策略管理。

这些能力后续需要时再单独补充设计文档。

2. 打包目标

• 将 PySide6 桌面程序打包为 Windows 可运行程序。
• 目标电脑无需预装 Python 环境。
• 打包产物应包含运行所需依赖、资源文件、默认配置和模板。
• 打包后的程序应能在 Windows 10 / Windows 11 上启动。
• 打包结构应方便排查 Qt 插件、资源、配置和日志问题。

3. 推荐打包方式

使用 PyInstaller。

第一阶段推荐使用 onedir 模式：

pyinstaller --onedir --windowed src/main.py

原因：

• PySide6 / Qt 依赖文件较多，onedir 更容易排查问题。
• 启动速度通常优于 onefile。
• 资源文件、配置文件、模板文件更容易随程序目录管理。
• 后续如需局域网分发或增量替换，目录模式更合适。

不推荐第一阶段使用 onefile：

• 启动时需要解压临时文件。
• Qt 插件问题更难排查。
• 日志、模板和配置路径更容易混乱。

4. Python 与依赖要求

必须遵守：

• Python 版本：Python 3.7。
• GUI 框架：PySide6。
• 推荐 PySide6 版本：PySide6==6.5.3。
• 图片处理：Pillow。
• 打包工具：PyInstaller。

依赖版本应在项目根目录的 requirements.txt 中锁定。

打包前必须确认依赖可以在 Python 3.7 环境中安装。

5. 发布目录结构

推荐打包后的发布目录：

CMBot/
  CMBot.exe
  _internal/
  config/
    app_config.json
    templates.json
  resources/
    icons/
    styles/
  logs/
  output/
  README.txt

说明：

• CMBot.exe：主程序入口。
• _internal/：PyInstaller 依赖目录。
• config/：默认配置和模板配置。
• resources/：图标、样式等资源。
• logs/：运行日志目录，程序启动时可自动创建。
• output/：默认输出目录，可自动创建。
• README.txt：给用户的简短使用说明。

6. 可写目录规则

程序运行时可能写入：

• 日志文件。
• 用户配置。
• 自定义模板。
• 导出图片。

规则：

• 程序必须确保 logs/ 目录存在。
• 程序必须确保默认 output/ 目录存在。
• 配置和模板写入前必须确认目录可写。
• 如果安装目录不可写，应提示用户选择可写目录，或后续改用用户数据目录。

第一阶段可以默认将配置、模板、日志和输出放在程序目录下，但必须处理目录不可写的错误。

7. 资源文件打包

需要随程序打包的资源：

• 应用图标。
• UI 样式文件。
• 默认模板文件。
• 默认配置文件。
• AI 穿搭出厂配置：ai_models.json（不含真实 key）、outfit_prompt.txt、title_prompt.txt。这些文件应进入发布包的 app\config\，用于首次播种和运行时兜底补种；用户目录已有同名文件时不得覆盖。

规则：

• 资源文件路径不能写死为开发机绝对路径。
• 程序需要通过统一的资源路径函数获取资源。
• 打包环境和开发环境应使用同一套路径访问规则。

建议提供路径辅助函数：

get_app_dir()
get_resource_path(relative_path)
get_config_path(relative_path)
get_log_dir()
get_output_dir()

8. PyInstaller 配置

第一阶段可以先使用命令行打包；项目稳定后应维护 .spec 文件。

建议命令：

pyinstaller ^
  --onedir ^
  --windowed ^
  --name CMBot ^
  --add-data "resources;resources" ^
  --add-data "config;config" ^
  src/main.py

注意：

• Windows 下 --add-data 的源路径和目标路径使用分号 ; 分隔。
• 如果在 PowerShell 中执行，换行符和引号需要按实际环境调整。
• 打包命令应后续固化到脚本中，例如 scripts/build.ps1。

9. 版本号规则

软件需要有明确版本号。

规则：

• 当前版本号必须显示在标题栏软件名称右侧。
• 版本号应从统一位置读取，不应在多个 UI 文件中硬编码。
• 打包产物的版本号、窗口显示版本号和发布目录版本号应一致。

建议维护：

src/version.py

示例：

APP_NAME = "自动合成印花服饰效果图工具"
APP_VERSION = "1.0.0"

发布目录建议带版本号：

CMBot-1.0.0/

10. 打包前检查

打包前必须检查：

• Python 版本是否为 3.7。
• 依赖是否安装成功。
• 程序是否可以在开发环境启动。
• 默认配置文件是否存在。
• 默认模板文件是否存在。
• 资源文件路径是否正确。
• 应用版本号是否正确。

建议命令：

python --version
pip freeze
python src/main.py

11. 打包后验证

打包后必须验证：

• 双击 CMBot.exe 可以启动。
• 标题栏显示正确版本号。
• 可以打开衣服图片文件夹。
• 可以打开印花图片文件夹。
• 可以显示预览区。
• 可以拖动、缩放、旋转印花。
• 可以导出当前单张图片。
• 可以生成日志文件。
• 程序关闭后再次启动正常。

若测试机器没有 Python 环境，应优先在该机器上验证。

12. 发布产物

第一阶段发布产物建议为压缩包：

CMBot-1.0.0.zip

压缩包内包含：

CMBot-1.0.0/
  CMBot.exe
  _internal/
  config/
  resources/
  README.txt

不应包含：

• 源代码。
• 测试文件。
• 开发环境缓存。
• 临时输出图片。
• 本机私人配置。
• 打包中间目录。

13. 暂不做

第一阶段不做：

• 局域网共享目录发布。
• 自动检查新版本。
• 自动下载更新。
• 多版本共存启动器。
• 按电脑名控制版本。
• 安装程序。
• Windows 注册表写入。
• 开机自启动。

如果后续要增加这些能力，应新增或扩展发布分发文档，不能直接混入当前第一阶段打包规则。