fix: resolve ty type errors and update AGENTS rules

Author: 0xWelt

AGENTS.md

@@ -22,6 +22,13 @@ source .venv/bin/activate   # Linux/macOS
 pytest -n auto
 ```
 
+测试目录结构：
+
+| 目录 | 说明 |
+|------|------|
+| `tests/unit/` | pytest 自动运行的单元测试 |
+| `tests/manual/` | 需真实设备的手动 e2e 测试 |
+
 ## pre-commit 检查
 
 提交前务必运行：
@@ -32,6 +39,39 @@ pre-commit run --all-files
 
 包含 **Ruff**（格式化与 lint）和 **ty**（类型检查）。
 
+## 类型检查
+
+本项目使用 **ty**（Astral 出品的 Python 类型检查器）进行静态类型检查。
+
+- 优先通过正确的类型注解、返回值标注和类型窄化来消除类型错误。
+- **禁止**在工作代码中使用 `typing.cast` 来掩盖类型问题；`cast` 只允许在测试文件的 Mock 场景中使用。
+- 若类型检查器因容器型变（如 `list` 的 invariant）报错，优先考虑将函数参数改为 `Sequence`、`Mapping` 等协变抽象基类，而非使用 `cast`。
+- 修复类型问题时尽量保持最小改动，避免不必要的重构。
+
+### `ty: ignore` 注释规范
+
+当必须通过注释忽略类型错误时，**必须使用 ty 原生格式**：
+
+```python
+# 正确
+c.r = 10  # ty: ignore[invalid-assignment]
+ctrl._device.shell.assert_called_once_with('input tap 480 270')  # ty: ignore[unresolved-attribute]
+
+# 错误 —— ty 无法识别 mypy 的 error code
+# type: ignore[invalid-assignment]
+# type: ignore[misc]
+
+# 错误 —— 裸 ignore 会被 ruff PGH003 拦截，且无法精确控制
+# type: ignore
+# type: ignore  # noqa: PGH003
+```
+
+> 项目已启用 `unused-type-ignore-comment = "error"`，未使用的 `# ty: ignore[...]` 会导致 CI 失败。
+
+## 单元测试要求
+
+新增功能或修改核心逻辑时，必须在 `tests/unit/` 下提供对应的 pytest 单元测试。测试文件应与被测源文件一一对应。
+
 ## 约定式提交
 
 ## 文档

autowsgr/combat/engine.py

@@ -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/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/logger.py

@@ -382,11 +382,11 @@ def save_image(
         保存的文件路径，未保存时返回 None。
     """
 
-    target_dir = str(img_dir or _image_dir)
-    target_dir = Path(target_dir)
+    target_dir = img_dir or _image_dir
     if target_dir is None:
         raise ValueError('未配置图片保存目录，请在 setup_logger 中设置 log_dir 并启用 save_images')
 
+    target_dir = Path(target_dir)
     target_dir.mkdir(parents=True, exist_ok=True)
     ts = _time.strftime('%H%M%S') + f'_{int(_time.monotonic() * 1000) % 1000:03d}'
     filename = f'{tag}_{ts}.png'

pyproject.toml

@@ -35,6 +35,7 @@ dev = [
     "pytest>=8.0",
     "pytest-cov",
     "pytest-xdist",
+    "httpx>=0.28.0",
     "requests>=2.32.5",
     "beautifulsoup4",
 ]
@@ -50,7 +51,8 @@ path = "autowsgr/__init__.py"
 ignore-words = "docs/spelling_wordlist.txt"
 
 [tool.pytest.ini_options]
-testpaths = ["testing"]
+testpaths = ["tests/unit"]
+addopts = ["--import-mode=importlib"]
 
 [tool.ruff]
 target-version = "py312"
@@ -170,7 +172,7 @@ extend-safe-fixes = [
 "__init__.py" = [
     "F401",    # unused-import
 ]
-"testing/**" = [
+"tests/**" = [
     "T201",    # print
 ]
 "tools/**" = [