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,65 @@ 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
 ```
 
-## 测试
+测试目录结构：
+
+| 目录 | 说明 |
+|------|------|
+| `tests/unit/` | pytest 自动运行的单元测试 |
+| `tests/manual/` | 需真实设备的手动 e2e 测试 |
 
-- 单元测试：`pytest`（测试目录 `testing/`）
-- 功能测试：运行 `examples/` 目录中的脚本进行端到端验证
+## pre-commit 检查
+
+提交前务必运行：
 
 ```bash
-pytest
+pre-commit run --all-files
 ```
 
-## 约定式提交（Conventional Commits）
+包含 **Ruff**（格式化与 lint）和 **ty**（类型检查）。
 
-提交信息格式：
+## 类型检查
 
-```
-<type>(<scope>): <简短描述>
+本项目使用 **ty**（Astral 出品的 Python 类型检查器）进行静态类型检查。
 
-<正文>
-```
+- 优先通过正确的类型注解、返回值标注和类型窄化来消除类型错误。
+- **禁止**在工作代码中使用 `typing.cast` 来掩盖类型问题；`cast` 只允许在测试文件的 Mock 场景中使用。
+- 若类型检查器因容器型变（如 `list` 的 invariant）报错，优先考虑将函数参数改为 `Sequence`、`Mapping` 等协变抽象基类，而非使用 `cast`。
+- 修复类型问题时尽量保持最小改动，避免不必要的重构。
 
-常用类型：
+### `ty: ignore` 注释规范
 
-- `feat`：新功能
-- `fix`：修复
-- `build`：构建系统或依赖变更
-- `docs`：文档
-- `style`：不影响代码逻辑的格式调整
-- `refactor`：重构
-- `test`：测试
+当必须通过注释忽略类型错误时，**必须使用 ty 原生格式**：
 
-示例：
+```python
+# 正确
+c.r = 10  # ty: ignore[invalid-assignment]
+ctrl._device.shell.assert_called_once_with('input tap 480 270')  # ty: ignore[unresolved-attribute]
 
-```
-build: migrate from setuptools to hatchling
+# 错误 —— ty 无法识别 mypy 的 error code
+# type: ignore[invalid-assignment]
+# type: ignore[misc]
 
-- Replace setuptools with hatchling as build backend
-- Remove obsolete MANIFEST.in
+# 错误 —— 裸 ignore 会被 ruff PGH003 拦截，且无法精确控制
+# type: ignore
+# type: ignore  # noqa: PGH003
 ```
 
-## 构建与打包
+> 项目已启用 `unused-type-ignore-comment = "error"`，未使用的 `# ty: ignore[...]` 会导致 CI 失败。
 
-- Build backend：**hatchling**
-- 包数据（图片、YAML、JAR 等）位于 `autowsgr/data/`，由 hatchling 自动包含，无需 `MANIFEST.in`
+## 单元测试要求
 
-```bash
-uv build
-```
+新增功能或修改核心逻辑时，必须在 `tests/unit/` 下提供对应的 pytest 单元测试。测试文件应与被测源文件一一对应。
+
+## 约定式提交
 
 ## 文档
 

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'
@@ -83,7 +83,7 @@ def __init__(
     def fight(  # noqa: PLR0912
         self,
         plan: CombatPlan,
-        initial_ship_stats: list[ShipDamageState],
+        initial_ship_stats: list[ShipDamageState] | None,
     ) -> CombatResult:
         """执行一次完整的战斗循环。
 

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/image_resources/keys.py

@@ -106,6 +106,8 @@ def _build_map() -> dict[TemplateKey, list[ImageTemplate]]:
         TemplateKey.END_EXERCISE_PAGE: [T.END_EXERCISE_PAGE],
         # 船坞已满
         TemplateKey.DOCK_FULL: [T.DOCK_FULL],
+        # 战役次数耗尽
+        TemplateKey.BATTLE_TIMES_EXCEED: [T.BATTLE_TIMES_EXCEED],
         # 战果评级
         TemplateKey.GRADE_SS: [T.Result.SS],
         TemplateKey.GRADE_S: [T.Result.S],

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