build: configure ty and fix type annotations

Author: 0xWelt

.pre-commit-config.yaml

@@ -27,3 +27,13 @@ repos:
     hooks:
       - id: codespell
         additional_dependencies: [".[toml]"]
+  - repo: local
+    hooks:
+      - id: ty-check
+        name: ty type check
+        description: Run Astral's ty type checker.
+        entry: uvx ty check
+        language: system
+        pass_filenames: false
+        require_serial: true
+        types: [python]

AGENTS.md

@@ -1,6 +1,6 @@
 # Agent Guidelines
 
-## 开发环境
+## 安装
 
 ```bash
 git clone git@github.com:OpenWSGR/AutoWSGR.git
@@ -14,70 +14,25 @@ pre-commit install
 ```bash
 source .venv/bin/activate   # Linux/macOS
 # .venv\Scripts\activate    # Windows
-pytest
-pre-commit run --all-files
 ```
 
-## 代码风格
-
-- Python 版本：3.12+
-- 格式化与 lint：**Ruff**（已覆盖 isort / black 功能），配置见 `pyproject.toml`
-- 目标行宽 100，单引号字符串
-- 禁止相对导入（`ban-relative-imports = all`）
-- 英语拼写检查：**codespell**，忽略词表见 `docs/spelling_wordlist.txt`
-
-提交前务必运行：
+## pytest
 
 ```bash
-pre-commit run --all-files
+pytest -n auto
 ```
 
-## 测试
+## pre-commit 检查
 
-- 单元测试：`pytest`（测试目录 `testing/`）
-- 功能测试：运行 `examples/` 目录中的脚本进行端到端验证
+提交前务必运行：
 
 ```bash
-pytest
-```
-
-## 约定式提交（Conventional Commits）
-
-提交信息格式：
-
-```
-<type>(<scope>): <简短描述>
-
-<正文>
-```
-
-常用类型：
-
-- `feat`：新功能
-- `fix`：修复
-- `build`：构建系统或依赖变更
-- `docs`：文档
-- `style`：不影响代码逻辑的格式调整
-- `refactor`：重构
-- `test`：测试
-
-示例：
-
-```
-build: migrate from setuptools to hatchling
-
-- Replace setuptools with hatchling as build backend
-- Remove obsolete MANIFEST.in
+pre-commit run --all-files
 ```
 
-## 构建与打包
-
-- Build backend：**hatchling**
-- 包数据（图片、YAML、JAR 等）位于 `autowsgr/data/`，由 hatchling 自动包含，无需 `MANIFEST.in`
+包含 **Ruff**（格式化与 lint）和 **ty**（类型检查）。
 
-```bash
-uv build
-```
+## 约定式提交
 
 ## 文档
 

autowsgr/combat/engine.py

@@ -62,7 +62,7 @@ def __init__(
 
         # 运行时状态 (由 fight() 重置)
         self._plan: CombatPlan = CombatPlan(name='', mode=CombatMode.BATTLE)
-        self._recognizer: CombatRecognizer = None  # type: ignore[assignment]  # set in fight()
+        self._recognizer: CombatRecognizer | None = None  # set in fight()
         self._phase = CombatPhase.PROCEED
         self._last_action = 'yes'
         self._node = '0'

autowsgr/combat/handlers.py

@@ -163,7 +163,9 @@ def _handle_spot_enemy(self) -> ConditionFlag:  # noqa: PLR0912
         # ── 信息采集 ──
         mode = 'exercise' if self._plan.mode == CombatMode.EXERCISE else 'fight'
         enemies = get_enemy_info(self._device, mode=mode)
-        enemy_formation = get_enemy_formation(self._device, self._ocr)
+        enemy_formation = (
+            get_enemy_formation(self._device, self._ocr) if self._ocr is not None else ''
+        )
         _log.info('[Combat] 敌方编成: {} 阵型: {}', enemies, enemy_formation)
 
         decision = self._get_current_decision()

autowsgr/combat/history.py

@@ -94,7 +94,7 @@ class CombatEvent:
     extra: dict[str, Any] = field(default_factory=dict)
 
     def __str__(self) -> str:
-        parts = [f'[{self.event_type.name}]']
+        parts: list[str] = [f'[{self.event_type.name}]']
         if self.node:
             parts.append(f'节点={self.node}')
         if self.action:

autowsgr/combat/rules.py

@@ -30,12 +30,16 @@
 import re
 from dataclasses import dataclass, field
 from enum import Enum, auto
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from autowsgr.infra.logger import get_logger
 from autowsgr.types import Formation
 
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
 # 允许在规则中出现的舰种标识符
 _log = get_logger('combat.recognition')
 
@@ -134,7 +138,7 @@ def __post_init__(self) -> None:
         if self.op not in _OPERATORS:
             raise ValueError(f"不支持的操作符: '{self.op}'，支持: {list(_OPERATORS)}")
 
-    def evaluate(self, context: dict[str, int | float]) -> bool:
+    def evaluate(self, context: Mapping[str, int | float]) -> bool:
         """在给定上下文中评估此条件。"""
         if '+' in self.field:
             parts = [p.strip() for p in self.field.split('+')]
@@ -159,7 +163,7 @@ class Rule:
     conditions: list[Condition]
     action: RuleAction
 
-    def evaluate(self, context: dict[str, int | float]) -> bool:
+    def evaluate(self, context: Mapping[str, int | float]) -> bool:
         """所有条件是否均满足。"""
         return all(c.evaluate(context) for c in self.conditions)
 
@@ -184,7 +188,7 @@ class RuleEngine:
     rules: list[Rule] = field(default_factory=list)
     default: RuleAction = field(default_factory=RuleAction.no_action)
 
-    def evaluate(self, context: dict[str, int | float]) -> RuleAction:
+    def evaluate(self, context: Mapping[str, int | float]) -> RuleAction:
         """对敌方编成上下文评估所有规则。
 
         Parameters

autowsgr/context/game_context.py

@@ -66,7 +66,7 @@ class GameContext:
 
     # ── 基础设施引用 (可选) ──
 
-    ocr: OCREngine
+    ocr: OCREngine | None = None
     """OCR 引擎实例 (章节/阵型识别等)。"""
 
     # ── 游戏运行时状态 ──

autowsgr/emulator/os_control/windows.py

@@ -93,6 +93,7 @@ def stop(self) -> None:
                     _log.info('云手机无需关闭')
                     return
                 case _:
+                    assert self._process_name is not None
                     subprocess.run(  # noqa: S603
                         ['taskkill', '-f', '-im', self._process_name],  # noqa: S607
                         check=True,

autowsgr/infra/config.py

@@ -486,7 +486,7 @@ def load(path: str | Path | None = None) -> UserConfig:
                     return UserConfig()
                 except ValidationError:
                     # WSL/Linux 下默认配置缺少 serial/path 无法通过验证，提供占位值
-                    return UserConfig(emulator={'serial': '', 'path': ''})
+                    return UserConfig(emulator=EmulatorConfig(serial='', path=''))
             config = UserConfig.from_yaml(path)
             _log.info('已加载配置: {}', path)
             return config

autowsgr/infra/logger.py

@@ -66,7 +66,7 @@
     from collections.abc import Callable
 
     import numpy as np
-    from loguru import Logger
+    from loguru import Logger, Record
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -103,7 +103,7 @@
 # ═══════════════════════════════════════════════════════════════════════════════
 
 
-def _src_patcher(record: dict) -> None:
+def _src_patcher(record: Record) -> None:
     """将 record["file"].path 转为以项目根目录为基准的相对路径，并存入 extra["src"]。
 
     格式示例：``emulator/controller.py:346``