ok-script 1.0.190__tar.gz → 2.0.0__tar.gz

ok_script-2.0.0/LICENSE.txt

@@ -0,0 +1,73 @@
+ok-script License
+================
+
+Copyright (c) 2026 ok-oldking
+
+This project is licensed under the Apache License, Version 2.0, as modified
+by the Commons Clause License Condition v1.0 and the additional terms below.
+The Apache License, Version 2.0, is available at:
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+The Commons Clause License Condition v1.0 is available at:
+
+https://commonsclause.com/
+
+If there is a conflict between the Apache License 2.0 and the Commons Clause
+or additional terms below, the Commons Clause and additional terms control.
+
+Commons Clause
+-------------
+
+Without limiting the conditions of the Apache License 2.0, the grant of
+rights under that license does not include the right to Sell this Software.
+
+For this license, “Sell” means selling, lending, leasing, licensing, offering
+for sale, lease, or license, or otherwise transferring this Software to a
+third party for a fee or other consideration. “Sell” does not include:
+
+* Using the Software internally, including by an organization or its
+  employees, without transferring it to a third party for a fee or other
+  consideration; or
+* Distributing the Software as part of a larger application or product,
+  provided that the larger application or product is not primarily the
+  Software or a competing product.
+
+Additional Terms
+----------------
+
+1. You may use this Software in closed-source and commercial projects. You
+   may charge for your own application, service, support, or other material
+   that incorporates the Software, provided that you do not sell or offer the
+   Software itself, or a competing product based primarily on it, as a product.
+
+2. You may fork the Software, make improvements, and keep the fork open
+   source and freely available. You may not take this project, rename it or
+   make only minor changes, and sell or market it as a competing product.
+
+3. You may not use this Software for hacking, unauthorized access, malware,
+   fraud, or any other illegal activity. You are responsible for complying
+   with all applicable laws and obtaining authorization for any security or
+   automation activity.
+
+4. Any project that uses, incorporates, or is derived from this Software
+   must mention ok-script and link to at least one of the following in at
+   least one of the project's website, GitHub repository, or the software
+   itself:
+
+   * Website: https://ok-script.com/
+   * GitHub: https://github.com/ok-oldking/ok-script
+
+   The notice must be reasonably visible and retained in modified or
+   redistributed versions.
+
+5. Use of the Qt UI, including components based on PyQt-Fluent-Widgets or
+   its related packages, is separately subject to the license and terms of
+   the upstream project:
+
+   https://github.com/zhiyiYo/PyQt-Fluent-Widgets
+
+6. Except for these additional terms, the Apache License 2.0 applies,
+   including its copyright, notice, patent, warranty, and liability
+   provisions. The Software is provided “AS IS”, without warranties or
+   conditions of any kind.

ok_script-2.0.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: ok-script
+Version: 2.0.0
+Summary: Automation with Computer Vision for Python
+Author-email: ok-oldking <firedcto@gmail.com>
+License: ok-script License
+        ================
+        
+        Copyright (c) 2026 ok-oldking
+        
+        This project is licensed under the Apache License, Version 2.0, as modified
+        by the Commons Clause License Condition v1.0 and the additional terms below.
+        The Apache License, Version 2.0, is available at:
+        
+        https://www.apache.org/licenses/LICENSE-2.0
+        
+        The Commons Clause License Condition v1.0 is available at:
+        
+        https://commonsclause.com/
+        
+        If there is a conflict between the Apache License 2.0 and the Commons Clause
+        or additional terms below, the Commons Clause and additional terms control.
+        
+        Commons Clause
+        -------------
+        
+        Without limiting the conditions of the Apache License 2.0, the grant of
+        rights under that license does not include the right to Sell this Software.
+        
+        For this license, “Sell” means selling, lending, leasing, licensing, offering
+        for sale, lease, or license, or otherwise transferring this Software to a
+        third party for a fee or other consideration. “Sell” does not include:
+        
+        * Using the Software internally, including by an organization or its
+          employees, without transferring it to a third party for a fee or other
+          consideration; or
+        * Distributing the Software as part of a larger application or product,
+          provided that the larger application or product is not primarily the
+          Software or a competing product.
+        
+        Additional Terms
+        ----------------
+        
+        1. You may use this Software in closed-source and commercial projects. You
+           may charge for your own application, service, support, or other material
+           that incorporates the Software, provided that you do not sell or offer the
+           Software itself, or a competing product based primarily on it, as a product.
+        
+        2. You may fork the Software, make improvements, and keep the fork open
+           source and freely available. You may not take this project, rename it or
+           make only minor changes, and sell or market it as a competing product.
+        
+        3. You may not use this Software for hacking, unauthorized access, malware,
+           fraud, or any other illegal activity. You are responsible for complying
+           with all applicable laws and obtaining authorization for any security or
+           automation activity.
+        
+        4. Any project that uses, incorporates, or is derived from this Software
+           must mention ok-script and link to at least one of the following in at
+           least one of the project's website, GitHub repository, or the software
+           itself:
+        
+           * Website: https://ok-script.com/
+           * GitHub: https://github.com/ok-oldking/ok-script
+        
+           The notice must be reasonably visible and retained in modified or
+           redistributed versions.
+        
+        5. Use of the Qt UI, including components based on PyQt-Fluent-Widgets or
+           its related packages, is separately subject to the license and terms of
+           the upstream project:
+        
+           https://github.com/zhiyiYo/PyQt-Fluent-Widgets
+        
+        6. Except for these additional terms, the Apache License 2.0 applies,
+           including its copyright, notice, patent, warranty, and liability
+           provisions. The Software is provided “AS IS”, without warranties or
+           conditions of any kind.
+        
+Project-URL: Homepage, https://github.com/ok-oldking/ok-script
+Project-URL: Repository, https://github.com/ok-oldking/ok-script
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pywin32>=306
+Requires-Dist: pyappify>=1.0.9
+Requires-Dist: typing-extensions>=4.11.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: pydirectinput==1.0.4
+Requires-Dist: pycaw==20240210
+Requires-Dist: mouse==0.7.1
+Requires-Dist: pynput>=1.8.1
+Provides-Extra: default
+Requires-Dist: numpy>=1.26.4; extra == "default"
+Requires-Dist: Pillow>=10.0; extra == "default"
+Requires-Dist: ok-d3dshot>=0.1.5; extra == "default"
+Requires-Dist: OpenCC==1.2.0; extra == "default"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115.0; extra == "web"
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == "web"
+Requires-Dist: pywebview>=5.4; extra == "web"
+Provides-Extra: qt
+Requires-Dist: PySide6-Essentials>=6.7.0; extra == "qt"
+Requires-Dist: PySideSix-Frameless-Window>=0.3.12; extra == "qt"
+Requires-Dist: darkdetect>=0.8.0; extra == "qt"
+Requires-Dist: PySide6-Fluent-Widgets>=1.8.3; extra == "qt"
+Provides-Extra: adb
+Requires-Dist: adbutils>=2.2.1; extra == "adb"
+Provides-Extra: ocr
+Requires-Dist: onnxocr-ppocrv5; extra == "ocr"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: get-pypi-latest-version; extra == "dev"
+Requires-Dist: mkdocs-material==9.7.7; extra == "dev"
+Dynamic: license-file
+
+# ok-script
+
+## 无界面、桌面与 Web 模式
+
+自动化核心现已与 Qt 解耦。使用 `ok-script` 可无界面运行，使用
+`ok-script[qt]` 启用原有桌面界面，或使用 `ok-script[web]` 启用 FastAPI
+浏览器界面；对应命令为 `ok run_task`、`ok gui` 和 `ok web`。详见
+[运行时架构](docs/architecture.md)。
+
+[简体中文](README.md) | [English](README_en.md)
+
+[![Discord](https://img.shields.io/discord/296598043787132928?color=5865f2&label=%20Discord)](https://discord.gg/vVyCatEBgA)
+
+基于计算机视觉的 Python 自动化框架，面向 Windows 应用、Windows 游戏、安卓模拟器和 ADB 设备。
+
+ok-script 提供 UI、截图与输入、设备控制、OCR、模板匹配、调试浮层、自动化测试、打包和增量更新能力。它使用 COCO 格式管理模板素材，并支持分辨率自适应与多语言界面。
+
+## 特性
+
+- 纯 Python 实现，免费开源，可直接使用 pip 生态中的第三方库
+- 同一套任务代码可支持 Windows 客户端、安卓模拟器和 ADB 设备
+- 支持 OCR、OpenCV 模板匹配以及 YOLO 等视觉方案
+- 基于 COCO 标注管理模板素材，并根据屏幕分辨率自动缩放
+- 内置截图、输入、设备控制和可视化调试工具
+- 支持自动化测试、GitHub Actions 构建和安装包发布
+- 支持多语言国际化和在线增量更新
+
+## 快速安装
+
+ok-script 支持 Python 3.11 及以上版本，推荐使用 Python 3.12。
+
+```powershell
+python -m pip install ok-script
+```
+
+只安装应用所需的依赖配置。`default` 为无界面模式，Web、Qt、ADB 和 OCR
+能力分别按需安装：
+
+```powershell
+python -m pip install "ok-script[default]"
+python -m pip install "ok-script[qt]"
+python -m pip install "ok-script[web]"
+python -m pip install "ok-script[adb]"
+python -m pip install "ok-script[ocr]"
+```
+
+ok-script 不会自动选择 OpenCV。用户必须根据自己的应用选择版本，并且只安装
+一个变体：`opencv-python`、`opencv-contrib-python`、`opencv-python-headless`
+或 `opencv-contrib-python-headless`。
+
+以无界面模式开发本仓库时，同时安装 `pyproject.toml` 中的 `default` 和 `dev`
+依赖组；再根据需要添加 `--group web`、`--group qt`、`--group adb` 或
+`--group ocr`：
+
+```powershell
+python -m pip install --editable . --group default --group dev
+```
+
+如果要创建完整的自动化项目，建议从 [`ok-script-app`](https://github.com/ok-oldking/ok-script-app) 模板开始，而不是直接在本仓库中编写业务脚本。
+
+## 文档
+
+从[文档中心](docs/index.md)选择适合你的阅读路径：
+
+1. [游戏自动化入门](docs/intro_to_automation/README.md)：了解截图、识别、决策和输入的基本原理
+2. [快速开始](docs/quick_start/README.md)：从模板仓库创建并运行第一个项目
+3. [进阶指南](docs/after_quick_start/README.md)：模板匹配、国际化、测试和发布
+4. [API 参考](docs/api_doc/README.md)：`Box`、`BaseTask` 及常用任务 API
+
+想先体验完整工具链，也可以使用基于 ok-script 的按键精灵项目 [`ok-py`](https://github.com/ok-oldking/ok-py)。
+
+## 界面预览
+
+| 任务配置 | 截图与交互 |
+| --- | --- |
+| ![任务配置界面](docs/ok_py/image_tasks.png) | ![截图与交互界面](docs/ok_py/image_capture.png) |
+
+| 脚本与 API | 模板管理 |
+| --- | --- |
+| ![脚本与 API 界面](docs/ok_py/image_scripting.png) | ![模板管理界面](docs/ok_py/image_template.png) |
+
+[查看界面与开发工具完整说明](docs/interface.md)，包括模板识别调试浮层。
+
+## 使用 ok-script 的项目
+
+- [ok-script 应用模板](https://github.com/ok-oldking/ok-script-app)
+- [鸣潮](https://github.com/ok-oldking/ok-wuthering-waves)
+- [原神](https://github.com/ok-oldking/ok-genshin-impact)（停止维护，后台过剧情仍可用）
+- [少女前线 2](https://github.com/ok-oldking/ok-gf2)
+- [崩坏：星穹铁道](https://github.com/Shasnow/ok-starrailassistant)
+- [星痕共鸣](https://github.com/Sanheiii/ok-star-resonance)
+- [二重螺旋](https://github.com/BnanZ0/ok-duet-night-abyss)
+- [卡厄思梦境](https://github.com/baoxin1100/ok-kes)
+- [阴阳师](https://github.com/YunLiuZ/ok-Onmyoji)
+- [白荆回廊](https://github.com/ok-oldking/ok-baijing)（停止维护）
+- [明日方舟：终末地](https://github.com/AliceJump/ok-end-field)
+- [异环](https://github.com/BnanZ0/ok-nte)
+
+## 社区与发布
+
+- 开发者 QQ 群：938132715
+- [PyPI](https://pypi.org/project/ok-script/)
+- [GitHub](https://github.com/ok-oldking/ok-script)
+
+## 致谢
+
+ok-script 的开发离不开以下开源项目：
+
+- [PyAppify](https://github.com/ok-oldking/pyappify)：用于应用更新和打包。
+- [OnnxOCR](https://github.com/ok-oldking/OnnxOCR)：提供支持 Intel NPU 的 OCR，
+  支持通过 OpenVINO 或 ONNX Runtime 推理，并使用 PaddleOCR v5 模型。
+- [PySide6](https://wiki.qt.io/Qt_for_Python)：提供基于 Qt 的桌面界面绑定。
+- [PyQt-Fluent-Widgets](https://github.com/zhiyiYo/PyQt-Fluent-Widgets)：Qt
+  界面使用的 Fluent UI 组件。
+- [OpenCV](https://opencv.org/)、[NumPy](https://numpy.org/) 和
+  [Pillow](https://python-pillow.org/)：用于图像处理和计算机视觉。
+- [FastAPI](https://fastapi.tiangolo.com/)、[Uvicorn](https://www.uvicorn.org/)
+  和 [pywebview](https://pywebview.flowrl.com/)：用于 Web 界面支持。
+- [adbutils](https://github.com/openatx/adbutils)：用于 Android 设备连接。
+
+上述依赖均受其各自许可证约束，详情请参阅对应项目页面。
+
+## 许可证
+
+本项目采用 [Apache License 2.0 + Commons Clause 及附加条款](LICENSE.txt)。
+
+允许的使用方式：
+
+- 可用于闭源项目或商业项目。
+- 可以 fork、本项目改进，并保持 fork 开源且免费。
+
+限制：
+
+- 禁止直接出售本项目，或仅改名、稍作修改后将其作为竞争产品出售或推广。
+- 禁止将本项目用于黑客攻击、未授权访问、恶意软件、欺诈或其他违法活动。
+- 任何使用 ok-script 的项目，都必须在项目网站、GitHub 或软件本身至少一处提及并链接 [ok-script.com](https://ok-script.com/) 或 [ok-script GitHub](https://github.com/ok-oldking/ok-script)。
+- Qt UI 的使用还必须遵守 [PyQt-Fluent-Widgets](https://github.com/zhiyiYo/PyQt-Fluent-Widgets) 的许可证。

ok_script-1.0.190/ok_script.egg-info/PKG-INFO → ok_script-2.0.0/README.md

@@ -1,43 +1,12 @@
-Metadata-Version: 2.4
-Name: ok-script
-Version: 1.0.190
-Summary: Automation with Computer Vision for Python
-Home-page: https://github.com/ok-oldking/ok-script
-Author: ok-oldking
-Author-email: firedcto@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: Microsoft :: Windows
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE.txt
-Requires-Dist: pywin32>=306
-Requires-Dist: pyappify>=1.0.6
-Requires-Dist: PySide6-Fluent-Widgets>=1.8.3
-Requires-Dist: typing-extensions>=4.11.0
-Requires-Dist: requests>=2.32.3
-Requires-Dist: psutil>=6.0.0
-Requires-Dist: pydirectinput==1.0.4
-Requires-Dist: pycaw==20240210
-Requires-Dist: mouse==0.7.1
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
 # ok-script
 
+## 无界面、桌面与 Web 模式
+
+自动化核心现已与 Qt 解耦。使用 `ok-script` 可无界面运行，使用
+`ok-script[qt]` 启用原有桌面界面，或使用 `ok-script[web]` 启用 FastAPI
+浏览器界面；对应命令为 `ok run_task`、`ok gui` 和 `ok web`。详见
+[运行时架构](docs/architecture.md)。
+
 [简体中文](README.md) | [English](README_en.md)
 
 [![Discord](https://img.shields.io/discord/296598043787132928?color=5865f2&label=%20Discord)](https://discord.gg/vVyCatEBgA)
@@ -64,6 +33,29 @@ ok-script 支持 Python 3.11 及以上版本，推荐使用 Python 3.12。
 python -m pip install ok-script
 ```
 
+只安装应用所需的依赖配置。`default` 为无界面模式，Web、Qt、ADB 和 OCR
+能力分别按需安装：
+
+```powershell
+python -m pip install "ok-script[default]"
+python -m pip install "ok-script[qt]"
+python -m pip install "ok-script[web]"
+python -m pip install "ok-script[adb]"
+python -m pip install "ok-script[ocr]"
+```
+
+ok-script 不会自动选择 OpenCV。用户必须根据自己的应用选择版本，并且只安装
+一个变体：`opencv-python`、`opencv-contrib-python`、`opencv-python-headless`
+或 `opencv-contrib-python-headless`。
+
+以无界面模式开发本仓库时，同时安装 `pyproject.toml` 中的 `default` 和 `dev`
+依赖组；再根据需要添加 `--group web`、`--group qt`、`--group adb` 或
+`--group ocr`：
+
+```powershell
+python -m pip install --editable . --group default --group dev
+```
+
 如果要创建完整的自动化项目，建议从 [`ok-script-app`](https://github.com/ok-oldking/ok-script-app) 模板开始，而不是直接在本仓库中编写业务脚本。
 
 ## 文档
@@ -110,6 +102,36 @@ python -m pip install ok-script
 - [PyPI](https://pypi.org/project/ok-script/)
 - [GitHub](https://github.com/ok-oldking/ok-script)
 
+## 致谢
+
+ok-script 的开发离不开以下开源项目：
+
+- [PyAppify](https://github.com/ok-oldking/pyappify)：用于应用更新和打包。
+- [OnnxOCR](https://github.com/ok-oldking/OnnxOCR)：提供支持 Intel NPU 的 OCR，
+  支持通过 OpenVINO 或 ONNX Runtime 推理，并使用 PaddleOCR v5 模型。
+- [PySide6](https://wiki.qt.io/Qt_for_Python)：提供基于 Qt 的桌面界面绑定。
+- [PyQt-Fluent-Widgets](https://github.com/zhiyiYo/PyQt-Fluent-Widgets)：Qt
+  界面使用的 Fluent UI 组件。
+- [OpenCV](https://opencv.org/)、[NumPy](https://numpy.org/) 和
+  [Pillow](https://python-pillow.org/)：用于图像处理和计算机视觉。
+- [FastAPI](https://fastapi.tiangolo.com/)、[Uvicorn](https://www.uvicorn.org/)
+  和 [pywebview](https://pywebview.flowrl.com/)：用于 Web 界面支持。
+- [adbutils](https://github.com/openatx/adbutils)：用于 Android 设备连接。
+
+上述依赖均受其各自许可证约束，详情请参阅对应项目页面。
+
 ## 许可证
 
-本项目采用 [AGPL-3.0 许可证](LICENSE.txt)。
+本项目采用 [Apache License 2.0 + Commons Clause 及附加条款](LICENSE.txt)。
+
+允许的使用方式：
+
+- 可用于闭源项目或商业项目。
+- 可以 fork、本项目改进，并保持 fork 开源且免费。
+
+限制：
+
+- 禁止直接出售本项目，或仅改名、稍作修改后将其作为竞争产品出售或推广。
+- 禁止将本项目用于黑客攻击、未授权访问、恶意软件、欺诈或其他违法活动。
+- 任何使用 ok-script 的项目，都必须在项目网站、GitHub 或软件本身至少一处提及并链接 [ok-script.com](https://ok-script.com/) 或 [ok-script GitHub](https://github.com/ok-oldking/ok-script)。
+- Qt UI 的使用还必须遵守 [PyQt-Fluent-Widgets](https://github.com/zhiyiYo/PyQt-Fluent-Widgets) 的许可证。

ok_script-2.0.0/diagnostics/qq_trace.py

@@ -0,0 +1,101 @@
+"""Trace QQ notification navigation without sending a message.
+
+Usage: .venv\\Scripts\\python.exe diagnostics\\qq_trace.py [nickname]
+"""
+from __future__ import annotations
+
+import logging
+import sys
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+from types import SimpleNamespace
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from ok.notification.windows_messenger import MessengerAutomation
+
+
+OUT = Path(__file__).resolve().parents[1] / "logs" / "qq_trace"
+OUT.mkdir(parents=True, exist_ok=True)
+logging.basicConfig(
+    filename=OUT / "trace.log",
+    level=logging.INFO,
+    format="%(asctime)s.%(msecs)03d %(levelname)s %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+log = logging.getLogger("qq_trace")
+
+
+def snap(automation: MessengerAutomation, hwnd: int, label: str) -> None:
+    try:
+        frame = automation._capture(hwnd)
+        path = OUT / f"{time.time_ns()}_{label}.png"
+        cv2.imwrite(str(path), frame)
+        log.info("screenshot label=%s path=%s shape=%s", label, path, frame.shape)
+    except Exception:
+        log.exception("screenshot_failed label=%s", label)
+
+
+def main() -> int:
+    nickname = (sys.argv[1] if len(sys.argv) > 1 else "文件传输助手").strip()
+    log.info("START nickname=%r", nickname)
+    automation = MessengerAutomation(
+        ("QQ.exe",), SimpleNamespace(), window_titles=("QQ",),
+        dismiss_search_after_contact=True, post_activate=False,
+    )
+    hwnd = automation._find_hwnd()
+    log.info("find_hwnd hwnd=%s foreground=%s", hwnd, __import__("win32gui").GetForegroundWindow())
+    if not hwnd:
+        log.error("QQ window not found")
+        return 2
+    snap(automation, hwnd, "01_initial")
+    if not automation._wait_until_background(hwnd):
+        log.warning("wait_until_background returned false")
+        return 3
+    log.info("background_ready foreground=%s", __import__("win32gui").GetForegroundWindow())
+    snap(automation, hwnd, "02_background_ready")
+    search_region, contact_region, send_region = automation._layout_regions(hwnd)
+    log.info("layout search=%s contact=%s send=%s", search_region, contact_region, send_region)
+    search = automation._wait_text(hwnd, {"Search", "搜索"}, region=search_region, timeout=1.5)
+    log.info("search_ocr point=%s", search)
+    if search is None:
+        search = automation._search_field_point(hwnd)
+        log.info("search_fallback point=%s", search)
+    snap(automation, hwnd, "03_before_search_click")
+    target = automation._click(hwnd, search)
+    log.info("click search target=%s point=%s", target, search)
+    snap(automation, hwnd, "04_after_search_click")
+    time.sleep(1)
+    automation._clear_text(target)
+    log.info("clear search")
+    time.sleep(1)
+    automation._type_text(target, nickname)
+    log.info("type nickname=%r", nickname)
+    time.sleep(1)
+    snap(automation, hwnd, "05_after_typing")
+    contact_hwnd, contact = automation._wait_contact(hwnd, nickname, contact_region, timeout=8)
+    log.info("contact_result hwnd=%s point=%s", contact_hwnd, contact)
+    if contact is None:
+        log.error("contact not found")
+        automation._send_key(hwnd, 0x1B)
+        snap(automation, hwnd, "06_contact_not_found_escape")
+        return 4
+    automation._click(contact_hwnd, contact, focus=contact_hwnd == hwnd)
+    log.info("click contact target=%s point=%s", contact_hwnd, contact)
+    snap(automation, hwnd, "06_after_contact_click")
+    time.sleep(1)
+    automation._send_key(hwnd, 0x1B)
+    log.info("send escape to dismiss search overlay")
+    time.sleep(1)
+    snap(automation, hwnd, "07_after_escape")
+    send_box = automation._wait_text(hwnd, {"Send", "发送"}, region=send_region, timeout=3)
+    log.info("send_box=%s (dry-run; no message sent)", send_box)
+    snap(automation, hwnd, "08_final_dry_run")
+    log.info("END")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())