StageBox 桌面应用构建器

把「会控台 StageBox」这一已验证的 Windows 桌面应用架构，沉淀为可复用的能力，
让你用一句话需求就能生成结构正确、本机可跑、可打包的同类桌面应用。

何时使用

• 用户要「做个 Windows 桌面小工具 / 会控 / 投屏 / 资料管理 / 本地媒体工具」。
• 用户要基于 Tkinter + PIL + pygame 搭桌面程序，且关心打包成 exe、无控制台、现场稳定性。
• 用户要从零生成新应用，并希望复用 StageBox 的分层、配置、日志、资源解析、冒烟测试套路。
• 用户要修复打包/运行时的本机环境问题（找不到 tkinter、exe 旁读不到素材、无控制台看不出报错）。

如何使用（生成新应用的标准流程）

1. 复制骨架：把 assets/template/ 整个目录复制为新项目根目录。它已经是分层、可运行的最小桌面应用。
2. 按分层组织代码（详见 references/architecture.md）：
   - common.py：路径/资源配置、_log 滚动文件日志、主题常量、配置读取三档规则、图标、显示器枚举、字体扫描。它是分层最底层，不依赖其他模块。
   - state.py：全部可编辑状态（含 to_json / from_json）+ 配置落盘（带坏数据回默认、旧数据一次性迁移）。
   - main.py：入口，只做「建窗口 + 组装能力模块 + 事件绑定」，不放业务细节。
   - 按需新增能力模块（如 audio.py / render.py / pptx.py），每个只依赖 common，不互相循环 import。
3. 加能力时查真实实现：StageBox 的完整实现在 F:/workbuddy/会控台 的 sb_*.py / stagebox.py。
   渲染原语、音频 SeekCache、字体扫描、背景分类等进阶模式，先读 references/architecture.md 的要点，再按需深读源码。
4. 配置与打包：严格走 references/build_env.md 的 PyInstaller 配方（onedir、console=False、日志兜底、排除 cv2/numpy 等）。
   一键命令见 scripts/build.py。
5. 无头冒烟测试：改完跑 python tools/smoke_test.py，它会真实创建窗口并驱动若干断言（配置重定向到临时目录，不污染真实数据）。

本机关键约定（不遵守就会踩坑，详见 build_env.md）

• 解释器：WorkBuddy 托管的 Python（~/.workbuddy/binaries/python）是精简版，不含 tkinter，不能用来跑/打包 GUI。
  一律用 C:\py313\python.exe（python-build-standalone 3.13.16，自带 tkinter 8.6）。
  官方 python.org 安装包在本机静默安装会失败（exit 67），别浪费时间。
• 资源解析：打包后 __file__ 指向临时解压目录 _MEIPASS，必须用 sys.executable 所在目录当工作目录，否则读不到随 exe 发布的 data/、素材库。内置只读资源走 sys._MEIPASS 回退。
• 日志：无控制台 exe（console=False）异常不落盘就石沉大海。任何 GUI 程序都必须有 _log 文件日志（滚动 1MB），关键路径与异常都写一句。
• 配置优先级：永远以 exe 旁的 data/ 为准（用户改过的不被内置旧数据覆盖）；旁没有才回退打包内置；都没有用默认。
• pip 镜像：用阿里云镜像（-i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com）；清华镜像在本机不可用。
• PyInstaller：优先 onedir；console=False 必须配日志 + 异常弹窗；别打大字体；打包后用 --selftest 之类的无界面自检入口验证。
• reportlab（若生成 PDF）：设 reportlab.rl_config.useA85 = 0 让 JPEG 原样嵌入，提速 10 倍以上、PDF 更小。

打包 / 发布

• 本机打包：python scripts/build.py（在项目根目录执行，会用项目里的 build.spec）。
• 技能发布：见 references/build_env.md 末尾的发布清单，以及 skill-creator 的 package_skill.py 打包流程。

参考资料

• references/architecture.md — 分层架构、模块职责、关键模式（资源解析/日志/配置/字体/状态/音频/渲染/冒烟）。
• references/build_env.md — Windows 环境坑、PyInstaller 配方、依赖与镜像、发布清单。
• 真实实现（深读）：F:/workbuddy/会控台 下的 sb_common.py sb_state.py sb_audio.py sb_render.py sb_pptx.py stagebox.py。
• 模板：assets/template/（最小可运行骨架，直接复制开改）。