AALC 开发指南：从 Python 3.12 环境搭建、热重载开发到 Qt 翻译流水线

• 桌面应用
• RPA
• 计算机视觉

本文是 AhabAssistantLimbusCompany（AALC，PC 端 Limbus Company 小助手）的开发者上手指南，完整覆盖开发环境配置（uv / Conda 双方案）、热重载开发服务器（main_dev.py）的原理与用法，以及 Qt Linguist 翻译流水线的提取、编辑与编译闭环。读完本文，你将能够在本机搭建 AALC 的可开发环境，理解自动重启与Ctrl+R手动重载的底层实现，并掌握向项目新增/维护多语言翻译的标准流程。

本文基于仓库内官方文档 assets/doc/zh/develop_guide.md 展开，并结合 main_dev.py、pyproject.toml、app/language_manager.py 等源码进行深度印证。文章只涉及查看、安装、运行和配置层面的开发操作，仓库为只读资源，请勿在生成文章的过程中修改其内容。

环境配置

前置要求

• Python 版本：项目要求 Python 3.12。pyproject.toml中通过requires-python = ">=3.12"明确声明，代码中的match等 3.12 新语法也需要该版本支持。
• 操作系统：目前仅支持Windows环境开发。这从源码可以印证：main.py 与 main_dev.py 都直接通过ctypes.windll调用user32/shcore设置进程 DPI 感知，而windll仅存在于 Windows 平台；依赖中也包含pywin32、windows-toasts、pyreadline3 (sys_platform == 'win32')等 Windows 专属库（见 requirements.txt）。

开发模式与正式启动的区别：正式入口 main.py 会通过pyuac.isUserAdmin()请求管理员权限、通过端口62333的单实例互斥逻辑防止多开；而开发模式会跳过这些检查（详见下文"热重载原理"）。

方案一：使用 uv（推荐）

项目使用 uv 管理依赖，pyproject.toml中[tool.uv] managed = true，依赖与开发依赖分别声明在dependencies与[dependency-groups].dev（包含pyinstaller、pytest、ruff、watchdog等）。推荐流程如下：

# 创建 Python 3.12 虚拟环境 uv venv --python=3.12 # 激活环境后同步依赖（会同时安装 dev 依赖，含热重载所需的 watchdog） uv sync

• uv venv --python=3.12会为当前目录创建.venv虚拟环境；若本机没有 3.12，uv 会自动下载对应解释器。
• uv sync依据pyproject.toml+uv.lock精确锁定版本安装全部依赖。热重载依赖watchdog与pynput位于 dev 组中，因此开发务必使用uv sync（而非仅安装运行依赖），否则 main_dev.py 会报watchdog not installed并直接退出。
• 若你只想拿到可运行的依赖清单，requirements.txt由uv export --no-hashes --no-annotate --no-dev自动生成，同样可配合 pip 使用。

方案二：使用 Conda

不习惯 uv 时，可以用 Conda 创建环境并安装依赖：

# 创建 Python 3.12 虚拟环境 conda create -n aalc python=3.12 conda activate aalc # 升级 pip 并安装依赖 python -m pip install --upgrade pip pip install -r requirements.txt

注意：此方案安装的是 requirements.txt 中锁定的运行期依赖，不含watchdog等 dev 依赖。若需在 Conda 环境下使用热重载，还需手动补装watchdog、pynput等开发依赖（可参考pyproject.toml的[dependency-groups].dev列表）。

启动开发服务器

AALC 提供了独立的开发入口 main_dev.py，它与正式入口 main.py 相互独立：

# 默认：启用热重载（自动重启 + Ctrl+R） python main_dev.py # 仅手动重载：禁用自动热重载，但保留 Ctrl+R python main_dev.py --no-reload

两种模式的行为差异：

启动时会打印清晰的模式提示（Hot Reload Enabled/Hot Reload Disabled），并显示被监听目录Watching directory: <cwd>。

开发特性与热重载原理

热重载

开发模式的核心价值是"改代码即重启"。其实现集中在 main_dev.py 的AALCReloader与FileChangeHandler两个类中，要点如下：

1. 文件监听：基于watchdog的Observer递归监听app、module、tasks、utils、i18n五个源码目录，同时以非递归方式监听项目根目录（main_dev.py）。只有后缀为.py的文件变更才会触发重启（reload_suffixes = {".py"}）。
2. 变更判定：FileChangeHandler对每个源文件先记录 SHA-256 内容哈希（_prime_content_hashes），事件到来时先sleep(0.2)等待编辑器落盘，再重新计算哈希做内容级对比，避免"仅 touched 未改内容"的假事件触发无谓重启（main_dev.py）。
3. 重启冷却：两次重启之间至少有 1 秒冷却（restart_cooldown = 1.0），防止快速连续保存造成重启风暴（main_dev.py）。
4. 忽略规则：.git、.idea、.venv、__pycache__等目录，以及config.yaml、theme_pack_list.yaml等运行时用户数据文件均被排除在触发条件之外（main_dev.py），因此修改配置文件不会触发重启。
5. 进程托管：restart_app先terminate()旧进程（超时 5 秒则kill()），再以subprocess.Popen拉起新进程，并打印新进程 PID 便于排查（main_dev.py）。

开发模式的环境变量与入口改造

AALCReloader.start()会向子进程注入三个环境变量（main_dev.py）：

• AALC_DEV_MODE=1：标记开发模式。在 app/my_app.py 中会据此判断是否加载非冻结（非打包）状态下的资源路径；
• AALC_SKIP_ADMIN=1：跳过管理员权限检查；
• AALC_FAST_START=1：加速启动流程。

同时，create_dev_main()会读取正式入口 main.py 的源码，生成临时文件__main_dev_temp__.py，通过字符串替换把两处关键检查"短路"掉（main_dev.py）：

• 管理员检查：if not pyuac.isUserAdmin():→if False and not pyuac.isUserAdmin():
• 单实例互斥检查：if not mutex or last_error > 0:→if False and (not mutex or last_error > 0):

也就是说，开发模式不会弹 UAC 管理员授权窗口、允许多实例同时运行，这对反复调试非常友好。临时文件会在退出时被cleanup()自动清理。

快捷键

• Ctrl+R：手动触发重载。即使使用--no-reload也始终生效——只要pynput可用，就会启动键盘监听线程，捕获Ctrl+R（字符码\x12）后置should_restart = True（main_dev.py）；若pynput未安装，则会打印警告并禁用快捷键。
• Ctrl+C：退出程序，AALCReloader捕获KeyboardInterrupt后执行清理（终止子进程、停止 observer、删除临时文件）并退出（main_dev.py）。

从源码结构可推断的实现细节

• 开发模式要求main.py必须存在于当前目录（否则报错退出），说明热重载以"替换后的正式入口"为子进程目标，属于进程级重启而非进程内 reload；
• 监听目录集合写死在watch_dirs = ["app", "module", "tasks", "utils", "i18n"]中，若未来新增顶层源码包，需要同步修改此处；
• main_dev.py自身只做 DPI 与日志初始化，不承载任何业务逻辑，业务代码全部在子进程中运行，因此即使热重载脚本本身出问题，也不影响对main.py逻辑的排查。

翻译

AALC 的界面国际化基于 Qt 的 Linguist 工具链：源码中的中文文本通过pyside6-project lupdate提取为.ts翻译文件，人工编辑后经pyside6-lrelease编译为二进制.qm，运行时由 app/language_manager.py 中的LanguageManager加载并驱动界面重译。整体流程如下：

源码中文文本 → lupdate 提取 → .ts 翻译文件 → Linguist 人工翻译 → lrelease 编译 → .qm → LanguageManager 运行时加载

提取可翻译文本到 .ts 文件

# 使用 uv 运行（推荐，会自动使用项目环境） uv run .\scripts\translation_files_build.py # 或者直接用系统 python python scripts\translation_files_build.py

该脚本（scripts/translation_files_build.py）内部实质执行的是：

pyside6-project lupdate

pyside6-project会依据 pyproject.toml 中[tool.pyside6-project].files配置的清单提取翻译上下文——该清单列出了main.py、app/my_app.py、app/setting_interface.py、app/farming_interface.py、tasks/tools/production_module.py等 20 余个需要参与翻译的源文件，以及已有的i18n/myapp_en.ts。新增了带 UI 文本的源文件时，记得把它加入该清单，否则文本不会被提取。

手动编辑翻译

提取完成后，用 Qt 官方翻译编辑器打开.ts文件进行人工翻译：

pyside6-Linguist .\i18n\myapp_en.ts

仓库中现存的 i18n/myapp_en.ts 是标准 TS 2.1 格式（<TS version="2.1" language="en_US">），每条<message>记录source（中文原文）与translation（英文译文），并带location标注来源文件与行号，例如来自app/farming_interface.py的"退出游戏 → Exit Game"等条目。文件规模达 3000 余行，覆盖界面文本、提示信息等完整翻译单元。

项目当前支持的语言代码定义在 app/language_manager.py：

SUPPORTED_LANG_CODE = { "zh_cn": "简体中文", # 暂时是zh_cn 等之后全局替换 "en": "English", }

LanguageManager（单例）通过register_component注册实现了retranslateUi方法的 UI 组件，set_language切换语言时先重载qt_<lang>与myapp_<lang>两套QTranslator，再调用所有已注册组件的retranslateUi完成界面刷新。因此在 UI 组件中新增文本后，需要同步实现/更新其retranslateUi方法并注册到LanguageManager，否则切换语言时该组件不会刷新。

编译生成 .qm 文件

翻译编辑完成后，编译生成 Qt 运行时实际加载的.qm二进制文件。三种方式等价：

# 方式一：脚本批量编译（遍历 i18n 下所有 .ts，并确保 dist/AALC/i18n 目录存在） uv run .\scripts\translation_files_compile.py # 方式二：直接用 python 运行同一脚本 python scripts\translation_files_compile.py # 方式三：手动对单个文件编译 pyside6-lrelease i18n/myapp_en.ts -qm i18n/myapp_en.qm

scripts/translation_files_compile.py 会遍历./i18n目录下所有.ts文件，逐个调用pyside6-lrelease生成同名的.qm文件并打印Generated: <path>；同时会预先创建dist/AALC/i18n目录，与打包产物结构对齐。注意：编译后.qm文件需与源码目录中的.ts保持同步更新，运行时LanguageManager.reload_translator会尝试从i18n/路径加载myapp_<lang_code>.qm（app/language_manager.py）。

常见问题与排查建议

• 提示watchdog not installed：开发依赖未安装。使用uv sync（而非仅pip install -r requirements.txt）安装完整 dev 依赖后重试。
• Ctrl+R无响应：pynput未安装时控制台会打印pynput not available, keyboard shortcuts disabled。安装pynput后重启开发服务器即可。
• 修改config.yaml却触发/不触发重启：设计上配置文件被显式忽略（ignored_names含config.yaml及config.yaml.bak/backup/old、theme_pack_list.yaml），修改它们不会触发重启。
• 热重载循环重启：检查是否频繁保存大文件（内容哈希对比只对.py生效），并留意 1 秒重启冷却；若确实干扰调试，改用python main_dev.py --no-reload仅保留手动Ctrl+R。
• 新增翻译不生效：依次检查——源文件是否加入 pyproject.toml 的[tool.pyside6-project].files、是否执行过translation_files_build.py重新提取、UI 组件是否实现并注册了retranslateUi、是否执行translation_files_compile.py重新编译.qm。

小结

AALC 的开发链路是一条完整的"配置 → 运行 → 翻译"闭环：环境层面优先使用 uv 管理 Python 3.12 依赖；开发层面通过 main_dev.py 获得免管理员、可多实例、改码即重启（Ctrl+R手动兜底）的开发体验，其哈希对比与冷却机制保证了热重载的稳定性；翻译层面则由lupdate → Linguist → lrelease → LanguageManager构成标准 Qt 国际化流水线。掌握这三部分，即可在本仓库中开展日常开发与多语言维护工作。

• 桌面应用
• RPA
• 计算机视觉