Skip to content

fix(task): 启动游戏改为等窗口真正就绪,并收敛重复的窗口辅助 - #2091

Merged
1w1w11w1 merged 3 commits into
devfrom
fix/game-window-ready-wait
Nov 21, 2026
Merged

1w1w11w1 merged 3 commits into
devfrom
fix/game-window-ready-wait

Conversation

@1w1w11w1

Copy link
Copy Markdown
Contributor

摘要

  • 五个专项(通用脚本 / 绝区零一条龙 / ok-nte / ok-ww / MaaEnd)启动游戏后不再固定 sleep(Game.WaitTime),改为等主窗口可见且客户区有面积再继续;到上限仍未就绪直接报错中止本轮
  • 新增公共等待 app.utils.wait_process_window_ready 与平台层缺失的 window.get_client_size(GetClientRect)
  • 七个专项的窗口定位、前置与截图实现收敛到 app/utils/common/game_window.py,本地实现改为薄封装
  • 各专项原有的窗口称呼、16:9 校验方式、停止信号响应、诊断截图跳过校验等差异按原样保留

测试与验证

  • 自动化测试:uv run --no-sync python -m pytest tests/task tests/platform tests/utils tests/models -q → 200 passed;ruff check app tests → All checks passed;mypy --config-file mypy-platform.ini → Success(23 files)
  • 新增测试:tests/utils/test_process_window_ready.py。现有测试没有任何一条能发现「窗口可见但客户区 0×0 被当成就绪」——把判定改成「只要取到尺寸就算就绪」时,新用例里 3 条立刻失败,说明它守的是这个真实故障而不是当前实现
  • 环境与提交:f5f9361ba(基于 origin/dev e0380ba92),Windows 11 + CPython 3.12.13
  • 未覆盖范围:tests/api tests/core tests/services tests/tools tests/scripts 在本机工作树有 3 条 ModuleNotFoundError: maa_adapter 的失败,是因为该工作树没有准备 .test-plugins 插件目录,与本次改动无关;未在本工作树内证明它们本来通过
  • 作者本机真实流程:N/A(尚未在真实游戏上验收,见下)

给审核者的背景

12:50 的一次生产运行里,绝区零被拉起后窗口已经可见但客户区还是 0×0(Unity 停在 WwiseUnity: Sound engine initialize 之后),脚本按固定秒数开跑,截图拿到空图,一连串应用在 0.3 秒内被判成「应用已完成」,随后一条龙按 after_done: 关闭游戏 关掉游戏,任务仍被记成 Success!。固定秒数等不出「窗口能截图」,所以这里换成等就绪。

需要重点看的两处行为变化:

  1. 通用脚本 WaitTime 默认 0 的用户,从「完全不等」变成「最多等 60 秒窗口就绪」。这是有意的:0 现在表示不等画面稳定,但仍要等到窗口可用。
  2. 真画不出客户区窗口的游戏(安装损坏、引擎卡死)现在会在上限后报「游戏启动失败」,而不是带着没起来的游戏继续跑。

另外有一条已知缺口:各专项「检测到游戏已在运行,跳过启动」的早返回分支没有加窗口就绪检查,is_process_running 只保证存在可见窗口。这次没有扩大范围。

尚未验证

没有在真实游戏上做冷启动验收(WaitTime 设小触发失败路径、设正常值确认就绪即继续)。这需要作者本机的游戏与账号,请在合入前补一次。

1w1w11w1 and others added 2 commits November 20, 2026 19:03
游戏拉起后固定 sleep(Game.WaitTime) 会在引擎还在初始化时就把控制权交给
脚本:窗口已经可见,客户区却仍是 0×0,截图拿到空图,脚本把一连串应用判成
已完成,随后按 after_done 关掉游戏,任务仍被记成成功。

新增 app.utils.wait_process_window_ready:主窗口可见且客户区宽高均大于 0
才放行,就绪即继续;到上限仍未就绪则抛 RuntimeError,交由各专项现有的启动
失败处理。启动等待时间填 0 时按 60 秒兜底,参数留空或非 Windows 平台不等待。
平台层补上缺失的 window.get_client_size(GetClientRect)。

general / ZzzOd / OkNte / Okww / MaaEnd 的固定启动等待全部换用该工具,
含启动器助手已确认窗口出现的路径——那些助手只判可见性。

Co-Authored-By: Claude Code <[email protected]>
原神、终末地、异环、鸣潮的启动器交互与账号切换共七处各存一份逐字相同的
窗口辅助:进程名/exe 读取、窗口面积、按进程找最大可见窗口、前置窗口、
客户区尺寸与按客户区截图。行为差异只有异常文案、16:9 校验方式和是否响应
停止信号,却要七处同步维护。

新增 app.utils.common.game_window,按统一语义各留一份:
- find_window / wait_window:进程名必选,窗口类、pid 集合、exe 路径、
  自定义归属判定为可选收窄条件;wait_window 负责重试与进程退出快速失败
- activate_window / capture_window:空等由调用方传入,异常称呼由 label 区分
- process_name / process_exe / window_area / client_size / warn_non_16_9

七个文件的本地实现改为薄封装,保留各自原有的异常文案与校验时机,
非 16:9 的告警/抛错、诊断截图跳过尺寸校验这些差异都按原样保留。

Co-Authored-By: Claude Code <[email protected]>
@github-actions github-actions Bot added 专项: 通用脚本 类型: 变更 按更新日志碎片自动设置 labels Nov 20, 2026
Comment on lines +147 to +154
try:
if not window.is_visible(hwnd):
return False
size = window.get_client_size(hwnd)
except Exception:
# 轮询期间窗口被销毁属预期状态, 按「还没就绪」处理, 下一轮重新取句柄
return False
return size is not None and size[0] > 0 and size[1] > 0

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: _is_client_ready fails for minimized windows because GetClientRect returns a 0x0 size, causing timeouts when attaching to an already-running, minimized game.
Severity: MEDIUM

Suggested Fix

In _is_client_ready, handle minimized windows using IsIconic(hwnd) or GetWindowPlacement, or check the window's restored bounds instead of failing when the client area size is 0x0.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: app/utils/common/process/manager.py#L147-L154

Potential issue: `_is_client_ready` requires `window.is_visible(hwnd)` and a client
rectangle with dimensions greater than 0x0. On Windows, `GetClientRect` returns a zero
rectangle for minimized (iconic) windows, even though `IsWindowVisible` returns true due
to the `WS_VISIBLE` style. In the general script, `_wait_game_window_ready` is now
called when attaching to an already-running process. If the game process is minimized,
it passes visibility but fails the client size check, timing out after `WaitTime` (or 60
seconds) and raising a `RuntimeError` stating that launch failed.

Also affects:

  • app/task/general/AutoProxy.py:389~397
  • app/task/general/AutoProxy.py:413~424

Did we get this right? 👍 / 👎 to inform future reviews.

Comment on lines +54 to +64
code = int(
not asyncio.run(
wait_process_window_ready(
ProcessInfo(
pid=arguments.get("pid"),
name=arguments.get("name"),
exe=arguments.get("exe"),
),
float(arguments["timeout"]),
)
)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Worker timeout raises an unhandled RuntimeError and holds the global _action_lock throughout the window ready wait, blocking concurrent desktop clone operations.
Severity: LOW

Suggested Fix

Catch RuntimeError inside process_worker.run to return a distinct exit code for timeouts, and avoid holding the global _action_lock during long polling operations in run_desktop_action.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: app/utils/windows/desktop_session/process_worker.py#L52-L64

Potential issue: In `process_worker.py`, `wait_process_window_ready` raises a
`RuntimeError` on timeout instead of returning `False`. This causes the exception
handler to exit with an error payload rather than returning exit code 1, preventing the
parent process from properly reporting the specific 'window not ready within timeout'
message. Furthermore, running the wait inside `run_desktop_action` holds the
module-level `_action_lock` in `process_runner.py` for up to 90 seconds, blocking other
desktop actions (such as activation or minimization) across all clones.

Also affects:

  • app/utils/common/process/manager.py:224~242

Did we get this right? 👍 / 👎 to inform future reviews.

):
return False

timeout = timeout_seconds if timeout_seconds > 0 else _WINDOW_READY_FALLBACK_SECONDS

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Replacing unconditional sleep(WaitTime) with immediate return on window creation causes downstream actions to execute before game loading completes.
Severity: MEDIUM

Suggested Fix

Preserve a settle delay or sleep period after _find_ready_window succeeds if WaitTime is configured, rather than treating WaitTime exclusively as a timeout.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: app/utils/common/process/manager.py#L216

Potential issue: `wait_process_window_ready` returns immediately once a non-zero client
area is detected, using `WaitTime` only as an upper-bound timeout. Previously, callers
relied on `sleep(WaitTime)` to wait out splash and loading screens until the game
reached an interactive state. Because a window client area is created long before assets
finish loading, downstream OCR and click operations may run prematurely against black
screens or loading frames.

Also affects:

  • app/task/general/AutoProxy.py:661~679

Did we get this right? 👍 / 👎 to inform future reviews.

@1w1w11w1
1w1w11w1 merged commit a63f493 into dev Nov 21, 2026
9 checks passed
@1w1w11w1
1w1w11w1 deleted the fix/game-window-ready-wait branch November 21, 2026 06:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

专项: 通用脚本 类型: 变更 按更新日志碎片自动设置

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant