pycore 项目特性（框架与约定）
本 skill 描述的是 pycore 的要求与约定（项目特性即 pycore 的框架与开发规范），不涉及项目其他部分。
When to Use
- •Use this skill when developing or modifying code under pycore (pycore_module_caller, callmodule, pylauncher, pythreadpool, native_ui).
- •Use when adding services, changing tray/startup/main window behavior, or touching THREAD_BUS / launcher / config.
Instructions
入口与三层职责
- •根入口：
pycore_module_caller.py→build_launcher_config()→ServiceLauncher(config).start()→register_event_handlers()；主循环等THREAD_BUS.is_shutdown_requested()后launcher.stop()。 - •callmodule：只做配置与事件注册（
config.build_launcher_config、event_handlers.register_event_handlers），不启动线程。 - •pylauncher：单例检测 + 按
config.services调用 pythreadpool 的 starter；不实现具体服务逻辑。 - •pythreadpool：
SERVICE_STARTERS[name](config)启动各服务线程（heartbeat / rpc_v2 / ui / tray），并注册register_shutdown_handler；关机时发tray.request_stop、{app_id}.close等事件。
THREAD_BUS 通信
- •线程间不直接调用，全部通过 THREAD_BUS：
trigger_event、register_event_handler、signal/wait_signal、set_thread_state、register_shutdown_handler、request_shutdown。 - •事件命名带命名空间（如
ui.tray.show、app.close、tray.request_stop）；需要时 event_data 带source。 - •关机按
THREAD_REGISTRY的shutdown_priority逆序执行（数字小的先关）。
Native UI 结构（step0–step10）
- •对外只通过
pycore.pyutils.native_ui的__init__.py暴露；内部按 step 绝对引用。 - •step0_i18n：国际化。step1_config：NativeUIConfig、TrayConfig。step2_port_url：端口与 URL。step3_launcher：
launch_native_app、launcher_with_startup。step4_startup：TkinterStartupThread（唯一 tk 引导窗）。step5_main_ui：PySide6 主窗、WebView、托盘。step6_tray：pystray、AppIndicator（Ubuntu）。step7_managers：thread_bus_manager、shutdown_manager 等。step9_frontend：前端进程。
启动顺序（含 UI 时）
- •先起 TkinterStartupThread（tk 引导），发
TkinterStartup_ready。 - •UI 线程内
wait_signal('TkinterStartup_ready')后再get_third_package_pyside6()，再创建 PySide6Framework 与主窗口。 - •引导结束后可发
STARTUP_REQUEST_CLOSE关 tk；若启用托盘则进 tray（pystray 或 AppIndicator）。 - •关机：
request_shutdown→ 执行 shutdown handler（如 stop_ui 发{app_id}.close，stop_tray 发tray.request_stop）。
平台与托盘
- •platform_adapter：根据 OS、X11、
XDG_CURRENT_DESKTOP给出recommended_tray_backend（APPINDICATOR / PYSTRAY / PYSIDE6 / NONE）。 - •Ubuntu/GNOME 桌面优先用 AppIndicator，不可用时退回 pystray。Linux 无 X11 则无托盘。
- •
start_tray()与_run_tray_mode()根据推荐后端选择 AppIndicatorSystemTrayThread 或 TkinterSystemTrayThread；菜单用build_appindicator_menu_items或_build_tray_menu_items从 TrayConfig 生成。
关键文件
- •配置：
pycore/callmodule/config.py。事件：pycore/callmodule/event_handlers.py。 - •启动器：
pycore/pylauncher/launcher.py。starter 与 registry：pycore/pythreadpool/starters.py、registry.py。 - •THREAD_BUS：
pycore/pyfoundations/thread_bus.py。Native UI 入口：pycore/pyutils/native_ui/step3_launcher/launch_native_app.py。 - •tk 引导：
pycore/pyutils/native_ui/step4_startup/startup_window_thread.py。主窗：step5_main_ui/pyside6/framework.py。平台：pycore/pyutils/native_ui/platform_adapter.py。
开发约定
- •新增服务：在
registry.py的 THREAD_REGISTRY 加条目并设shutdown_priority，在starters.py中实现 starter 并注册到 SERVICE_STARTERS；关机通过 THREAD_BUS 事件或 shutdown handler，不直接调其他线程。 - •修改托盘/引导/主窗：保持「tk 先于 PySide6」「THREAD_BUS 关窗/关托盘」；Ubuntu 桌面优先 AppIndicator，失败再 pystray。