autowsgr 2.2.2__tar.gz → 2.3.0__tar.gz

autowsgr-2.3.0/AGENTS.md

@@ -0,0 +1,105 @@
+# Agent Guidelines
+
+## 开发环境
+
+```bash
+git clone git@github.com:OpenWSGR/AutoWSGR.git
+cd AutoWSGR
+uv sync
+pre-commit install
+```
+
+激活虚拟环境后可直接运行命令（无需 `uv run` 前缀）：
+
+```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`
+
+提交前务必运行：
+
+```bash
+pre-commit run --all-files
+```
+
+## 测试
+
+- 单元测试：`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
+```
+
+## 构建与打包
+
+- Build backend：**hatchling**
+- 包数据（图片、YAML、JAR 等）位于 `autowsgr/data/`，由 hatchling 自动包含，无需 `MANIFEST.in`
+
+```bash
+uv build
+```
+
+## 文档
+
+- 用户文档地址：https://docs-autowsgr.notion.site
+- 代码变更后同步更新文档，并鼓励在代码中编写注释和文档字符串。
+
+## ShiinaKuroko Fork 分支管理
+
+本仓库的个人 Fork 为 `https://github.com/ShiinaKuroko/AutoWSGR.git`。后续 Agent
+必须遵守以下分支职责，不得自行改变分支用途：
+
+- `main` 只用于同步 `OpenWSGR/AutoWSGR:main`，禁止在该分支直接开发、提交或推送功能代码。
+- `ShiinaKuroko` 是个人 Fork 的最新开发分支，经过验证的最新代码才允许推送到这里。
+- `backup/YYYYMMDD-<short-sha>` 是版本备份分支。每次更新 `ShiinaKuroko` 前，先创建一个指向更新前稳定提交的备份；完成更新后，再创建一个指向新稳定提交的备份，最多保留两个备份分支。
+- 备份分支一旦创建不得移动、覆盖或追加提交。超过两个备份时，只删除最旧的备份分支，不删除当前备份和上一个备份。
+- Agent 临时分支、worktree 分支和实验分支不得直接推送到 `main` 或冒充 `ShiinaKuroko`；任务完成后应删除不再需要的临时远程分支。
+- 推送前必须确认工作树、提交范围和目标分支：`git status --short --branch`、`git diff --check`、`git log --oneline -5`。
+- 推送最新代码前必须先创建备份，并使用 `git push --force-with-lease` 更新 `ShiinaKuroko`，禁止无条件 `--force`。
+- 任何删除远程分支的操作都必须先列出将被删除的分支、提交和原因；禁止删除 `main`、`ShiinaKuroko` 或未明确授权的分支。
+- 新功能必须在独立分支或 worktree 中开发，完成测试后才能合并或推送到 `ShiinaKuroko`。
+- 本地独立开发分支只能用于编码、测试和审查，禁止直接推送到 Fork 的任何发布分支。
+- 本地独立分支完成后，必须将已验证提交合并、cherry-pick 或 rebase 整理到本地 `ShiinaKuroko` 分支；只有本地 `ShiinaKuroko` 分支允许执行 `git push origin ShiinaKuroko`。
+- 不得执行 `git push origin <local-feature-branch>` 作为发布流程；远程临时分支如确有协作需要，必须获得明确授权，并不得替代 `ShiinaKuroko` 发布入口。
+- 推送前必须确认当前分支为本地 `ShiinaKuroko`，且 `git log origin/ShiinaKuroko..ShiinaKuroko` 只包含本次计划发布的提交。
+- 后端发布至少执行 `pytest -q` 和 `git diff --check`；无法执行的检查必须在交付说明中明确记录。

{autowsgr-2.2.2 → autowsgr-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autowsgr
-Version: 2.2.2
+Version: 2.3.0
 Summary: Auto Warship Girls Framework.
 Project-URL: Documentation, https://docs-autowsgr.notion.site
 Project-URL: Repository, https://github.com/OpenWSGR/AutoWSGR
@@ -12,7 +12,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: System :: Distributed Computing
 Requires-Python: <3.14,>=3.12
 Requires-Dist: adbutils<3.0,>=2.0
-Requires-Dist: autowsgr-native>=0.2.0
+Requires-Dist: autowsgr-native==0.3.0
 Requires-Dist: av>=12.0
 Requires-Dist: easyocr>=1.7.1
 Requires-Dist: fastapi>=0.100.0

{autowsgr-2.2.2 → autowsgr-2.3.0}/autowsgr/__init__.py

@@ -1,3 +1,3 @@
 """AutoWSGR - 战舰少女R 自动化框架(v2)"""
 
-__version__ = '2.2.2'
+__version__ = '2.3.0'

{autowsgr-2.2.2 → autowsgr-2.3.0}/autowsgr/combat/__init__.py

@@ -1,6 +1,16 @@
 """战斗系统 — 独立于 UI 框架的战斗状态机引擎。"""
 
 from .engine import CombatEngine, run_combat
+from .fleet import (
+    ALLOWED_SHIP_TYPE_CODES,
+    FleetPreset,
+    FleetSelectionSource,
+    FleetSlotRule,
+    ResolvedFleetSelection,
+    ShipSelector,
+    fleet_slot_from_api,
+    resolve_fleet_selection,
+)
 from .history import CombatEvent, CombatHistory, CombatResult, FightResult
 from .node_tracker import MapNodeData, NodeTracker
 from .plan import CombatMode, CombatPlan, NodeDecision
@@ -15,6 +25,7 @@ from .state import CombatPhase
 
 
 __all__ = [
+    'ALLOWED_SHIP_TYPE_CODES',
     'SHIP_DROP_PAGE_SIGNATURE',
     'CombatEngine',
     'CombatEvent',
@@ -24,13 +35,20 @@ __all__ = [
     'CombatPlan',
     'CombatResult',
     'FightResult',
+    'FleetPreset',
+    'FleetSelectionSource',
+    'FleetSlotRule',
     'MapNodeData',
     'NodeDecision',
     'NodeTracker',
+    'ResolvedFleetSelection',
     'RuleEngine',
     'RuleResult',
     'ShipDropResult',
+    'ShipSelector',
+    'fleet_slot_from_api',
     'recognize_enemy_formation',
     'recognize_ship_drop',
+    'resolve_fleet_selection',
     'run_combat',
 ]

{autowsgr-2.2.2 → autowsgr-2.3.0}/autowsgr/combat/actions.py

@@ -133,7 +133,9 @@ def click_fight_condition(device: AndroidController, condition: FightCondition)
         目标战况。
     """
     x, y = condition.relative_click_position
-    device.click(x, y)
+
+    # 选择战况后，舰队会在地图上移动，不能添加延迟，否则会出现识别不到下一个点的问题
+    device.click(x, y, delay=False)
 
 
 def click_night_battle(device: AndroidController, pursue: bool) -> None:
@@ -186,14 +188,19 @@ def click_speed_up(device: AndroidController, *, battle_mode: bool = False) -> N
         ``True`` 使用战役加速坐标，``False`` 使用常规战坐标。
     """
     coords = Coords.SPEED_UP_BATTLE if battle_mode else Coords.SPEED_UP_NORMAL
-    device.click(*coords)
+
+    # 由于加速过快可能导致卡顿, 增加极短延迟以确保点击生效
+    time.sleep(0.05)
+    device.click(*coords, delay=False)
 
 
 def click_skip_missile_animation(device: AndroidController) -> None:
     """跳过导弹支援动画。"""
-    device.click(*Coords.SPEED_UP_BATTLE)
-    time.sleep(0.2)
-    device.click(*Coords.SPEED_UP_BATTLE)
+
+    # 快速点击不需要增加操作后的 delay
+    device.click(*Coords.SPEED_UP_BATTLE, delay=False)
+    time.sleep(1)
+    device.click(*Coords.SPEED_UP_BATTLE, delay=False)
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -298,7 +305,7 @@ def click_image(device: AndroidController, template_key: TemplateKey, timeout: f
     return False
 
 
-def get_ship_drop(device: AndroidController) -> str | None:
+def get_ship_drop(device: AndroidController, ocr: OCREngine) -> str | None:
     """获取掉落舰船名称。
 
     Parameters
@@ -311,10 +318,8 @@ def get_ship_drop(device: AndroidController) -> str | None:
     str | None
         掉落的舰船名称，或 ``None`` 如果未获取到。
     """
-    from autowsgr.vision import EasyOCREngine
 
     screen = device.screenshot()
-    ocr = EasyOCREngine.create(gpu=False)
     result = recognize_ship_drop(screen, ocr)
     if result.ship_name:
         _log.info('[Combat] 掉落识别: {} ({})', result.ship_name, result.ship_type or '未知')
@@ -420,7 +425,9 @@ def dismiss_resource_confirm(device: AndroidController, screen: ndarray) -> None
     )
     if detail is not None:
         time.sleep(0.25)
-        device.click(*detail.center)
+
+        # 由于在地图移动的过程中，点击后必须立刻获取当前画面，因此不能加延迟
+        device.click(*detail.center, delay=False)
         _log.info(
             "[Combat] 点掉资源确认弹窗: '{}' ({:.4f}, {:.4f})",
             detail.template_name,

{autowsgr-2.2.2 → autowsgr-2.3.0}/autowsgr/combat/engine.py

@@ -126,7 +126,12 @@ class CombatEngine(PhaseHandlersMixin):
                     plan.map_id,
                 )
         elif plan.mode == CombatMode.EVENT and plan.event_name:
-            map_data = MapNodeData.load_event(plan.event_name, plan.chapter, plan.map_id)
+            map_data = MapNodeData.load_event(
+                plan.event_name,
+                plan.chapter,
+                plan.map_id,
+                plan.entrance,
+            )
             if map_data is not None:
                 self._tracker = NodeTracker(map_data)
                 _log.info(

autowsgr-2.3.0/autowsgr/combat/fleet.py

@@ -0,0 +1,434 @@
+"""舰队规则领域模型和入口转换。
+
+YAML 与 HTTP 请求只在各自入口转换一次。执行器和 UI 只接收本模块定义的
+不可变对象，不再解释字典、Pydantic DTO 或旧 candidates 字符串格式。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from autowsgr.contracts.vessel_types import (
+    FLEET_VESSEL_TYPE_BY_CODE,
+    FLEET_VESSEL_TYPES,
+)
+from autowsgr.types import ShipType
+
+
+if TYPE_CHECKING:
+    from autowsgr_native.vessel_type import VesselType
+
+    from autowsgr.combat.plan import CombatPlan
+
+
+NATIVE_FLEET_VESSEL_TYPES = tuple(vessel_type.native for vessel_type in FLEET_VESSEL_TYPES)
+"""由公共 native 契约提供的普通舰种。"""
+
+_NATIVE_CODE_TO_SHIP_TYPE: Mapping[str, ShipType] = MappingProxyType(
+    {
+        'cv': ShipType.CV,
+        'cvl': ShipType.CVL,
+        'av': ShipType.AV,
+        'bb': ShipType.BB,
+        'bbv': ShipType.BBV,
+        'bc': ShipType.BC,
+        'ca': ShipType.CA,
+        'cav': ShipType.CAV,
+        'clt': ShipType.CLT,
+        'cl': ShipType.CL,
+        'bm': ShipType.BM,
+        'dd': ShipType.DD,
+        'ssg': ShipType.SSG,
+        'ss': ShipType.SS,
+        'sc': ShipType.SC,
+        'ap': ShipType.NAP,
+        'asdg': ShipType.ASDG,
+        'aadg': ShipType.AADG,
+        'kp': ShipType.KP,
+        'cg': ShipType.CG,
+        'bbg': ShipType.BG,
+        'bg': ShipType.CBG,
+    },
+)
+"""native 0.3 舰种代码到 AutoWSGR 领域枚举的显式映射。"""
+
+VESSEL_TYPE_TO_SHIP_TYPE: tuple[tuple[VesselType, ShipType], ...] = tuple(
+    (vessel_type.native, _NATIVE_CODE_TO_SHIP_TYPE[vessel_type.code])
+    for vessel_type in FLEET_VESSEL_TYPES
+)
+
+for _native_type, _ship_type in VESSEL_TYPE_TO_SHIP_TYPE:
+    if _native_type.as_chinese() != _ship_type.value:
+        raise RuntimeError(
+            f'native 舰种中文语义不一致: {_native_type.as_english()}',
+        )
+
+
+def ship_type_from_native(vessel_type: VesselType) -> ShipType:
+    """把 native 普通舰种转换为 AutoWSGR 领域枚举。"""
+    for native_type, ship_type in VESSEL_TYPE_TO_SHIP_TYPE:
+        if vessel_type == native_type:
+            return ship_type
+    message = f'不支持的 native 舰种: {vessel_type!r}'
+    raise ValueError(message)
+
+
+NATIVE_VESSEL_TYPE_BY_CODE: Mapping[str, VesselType] = MappingProxyType(
+    {code: vessel_type.native for code, vessel_type in FLEET_VESSEL_TYPE_BY_CODE.items()},
+)
+"""API 使用的 native 0.3 canonical 舰种代码。"""
+
+
+SHIP_TYPE_BY_CODE: Mapping[str, tuple[ShipType, ...]] = MappingProxyType(
+    {
+        **{
+            code: (ship_type_from_native(vessel_type),)
+            for code, vessel_type in NATIVE_VESSEL_TYPE_BY_CODE.items()
+        },
+        'ss_or_ssg': (ShipType.SS, ShipType.SSG),
+    },
+)
+"""API 舰种代码到后端领域枚举的唯一映射。"""
+
+LEGACY_SHIP_TYPE_ALIASES: Mapping[str, str] = MappingProxyType(
+    {
+        'cf': 'cv',
+        'cgaa': 'cg',
+        'cbg': 'bg',
+        'ddg': 'asdg',
+        'ddgaa': 'aadg',
+    },
+)
+"""旧版 API/GUI 舰种代码到 canonical code 的兼容映射。"""
+
+_ALL_SHIP_TYPE_CODES = {
+    *SHIP_TYPE_BY_CODE,
+    *LEGACY_SHIP_TYPE_ALIASES,
+}
+
+ALLOWED_SHIP_TYPE_CODES = frozenset(_ALL_SHIP_TYPE_CODES)
+
+
+def parse_ship_type_codes(raw: object) -> tuple[ShipType, ...]:
+    """校验舰种缩写并转换为去重后的领域枚举。"""
+    if raw is None or raw == '':
+        return ()
+    values = [raw] if isinstance(raw, str) else raw
+    if not isinstance(values, Sequence):
+        raise TypeError('ship_type 必须是非空字符串列表')
+
+    result: list[ShipType] = []
+    for value in values:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError('ship_type 必须是非空字符串列表')
+        code = value.strip().lower()
+        canonical_code = LEGACY_SHIP_TYPE_ALIASES.get(code, code)
+        ship_types = SHIP_TYPE_BY_CODE.get(canonical_code)
+        if ship_types is None:
+            allowed = ', '.join(sorted(ALLOWED_SHIP_TYPE_CODES))
+            raise ValueError(f'ship_type 不合法: {value!r}, 可选值: {allowed}')
+        for ship_type in ship_types:
+            if ship_type not in result:
+                result.append(ship_type)
+    return tuple(result)
+
+
+@dataclass(frozen=True, slots=True)
+class ShipSelector:
+    """一艘主选或备选舰船的完整选择规则。"""
+
+    name: str
+    search_name: str | None = None
+    ship_types: tuple[ShipType, ...] = ()
+    min_level: int | None = None
+    max_level: int | None = None
+    relaxed_constraints: bool = False
+
+    def __post_init__(self) -> None:
+        name = self.name.strip()
+        if not name:
+            raise ValueError('name 不能为空')
+        object.__setattr__(self, 'name', name)
+
+        search_name = self.search_name.strip() if self.search_name else None
+        object.__setattr__(self, 'search_name', search_name)
+        if self.min_level is not None and self.min_level < 1:
+            raise ValueError('min_level 必须大于等于 1')
+        if self.max_level is not None and self.max_level < 1:
+            raise ValueError('max_level 必须大于等于 1')
+        if (
+            self.min_level is not None
+            and self.max_level is not None
+            and self.max_level < self.min_level
+        ):
+            raise ValueError('max_level 必须大于或等于 min_level')
+
+
+@dataclass(frozen=True, slots=True)
+class FleetSlotRule:
+    """一个舰队槽位的严格主选和有序宽泛备选。"""
+
+    primary: ShipSelector | None = None
+    candidates: tuple[ShipSelector, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.primary is None and not self.candidates:
+            raise ValueError('位置至少需要一艘主选或备选舰船')
+
+    @property
+    def options(self) -> tuple[ShipSelector, ...]:
+        """返回智能编队按顺序尝试的完整规则。"""
+        if self.primary is None:
+            return self.candidates
+        return (self.primary, *self.candidates)
+
+    @property
+    def preferred_name(self) -> str:
+        """返回集合分配开始时使用的首个舰名。"""
+        return self.options[0].name
+
+
+@dataclass(frozen=True, slots=True)
+class FleetPreset:
+    """YAML 中一套已经完成入口转换的舰队预设。"""
+
+    name: str
+    slots: tuple[FleetSlotRule, ...]
+
+
+class FleetSelectionSource(StrEnum):
+    """最终舰队选择的数据来源。"""
+
+    OVERRIDE_RULES = 'override_rules'
+    OVERRIDE_FLEET = 'override_fleet'
+    PLAN_PRESET = 'plan_preset'
+    PLAN_FLEET = 'plan_fleet'
+    NONE = 'none'
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedFleetSelection:
+    """runner 启动前确定的唯一舰队选择结果。"""
+
+    fleet_id: int
+    slot_rules: tuple[FleetSlotRule, ...] | None
+    plain_fleet: tuple[str, ...] | None
+    source: FleetSelectionSource
+
+    @property
+    def primary_names(self) -> list[str | None] | None:
+        """返回战斗记录可使用的显式主选舰名。"""
+        if self.slot_rules is not None:
+            return [
+                rule.primary.name if rule.primary is not None else None
+                for rule in self.slot_rules[:6]
+            ]
+        return list(self.plain_fleet) if self.plain_fleet is not None else None
+
+
+def _optional_text(value: object) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TypeError('舰船名称必须是字符串')
+    return value.strip() or None
+
+
+def _optional_level(rule: Mapping[str, Any], field: str) -> int | None:
+    value = rule.get(field)
+    if value is None:
+        return None
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise TypeError(f'{field} 必须是整数')
+    return value
+
+
+def _selector_from_mapping(
+    raw: Mapping[str, Any],
+    *,
+    relaxed: bool,
+    inherited: Mapping[str, Any] | None = None,
+) -> ShipSelector:
+    name = _optional_text(raw.get('name'))
+    if name is None:
+        raise ValueError('name 不能为空')
+    source = raw if inherited is None else inherited
+    inherited_search_name = inherited.get('search_name') if inherited is not None else None
+    return ShipSelector(
+        name=name,
+        search_name=_optional_text(raw.get('search_name', inherited_search_name)),
+        ship_types=parse_ship_type_codes(source.get('ship_type')),
+        min_level=_optional_level(source, 'min_level'),
+        max_level=_optional_level(source, 'max_level'),
+        relaxed_constraints=relaxed,
+    )
+
+
+def _deduplicate_selectors(selectors: Sequence[ShipSelector]) -> tuple[ShipSelector, ...]:
+    """按完整规则去重，保留同名但约束不同的有序候选。"""
+    result: list[ShipSelector] = []
+    for selector in selectors:
+        if selector not in result:
+            result.append(selector)
+    return tuple(result)
+
+
+def fleet_slot_from_api(raw: str | Mapping[str, Any]) -> FleetSlotRule:
+    """把已经通过 HTTP schema 的槽位转换成 canonical 规则。"""
+    if isinstance(raw, str):
+        return FleetSlotRule(primary=ShipSelector(name=raw))
+    if not isinstance(raw, Mapping):
+        raise TypeError('舰队槽位必须是字符串或规则对象')
+
+    name = _optional_text(raw.get('name'))
+    primary = _selector_from_mapping(raw, relaxed=False) if name is not None else None
+    raw_candidates = raw.get('candidates', [])
+    if not isinstance(raw_candidates, Sequence) or isinstance(raw_candidates, str):
+        raise TypeError('candidates 必须是规则对象列表')
+    candidates = _deduplicate_selectors(
+        tuple(
+            ShipSelector(
+                name=candidate,
+                search_name=_optional_text(raw.get('search_name')),
+                ship_types=parse_ship_type_codes(raw.get('ship_type')),
+                min_level=_optional_level(raw, 'min_level'),
+                max_level=_optional_level(raw, 'max_level'),
+            )
+            if isinstance(candidate, str)
+            else _selector_from_mapping(candidate, relaxed=False)
+            for candidate in raw_candidates
+        )
+    )
+    return FleetSlotRule(primary=primary, candidates=candidates)
+
+
+def fleet_slot_from_yaml(raw: object) -> FleetSlotRule:
+    """把 YAML 槽位转换成 canonical 规则，并仅在此兼容旧字符串候选。"""
+    if isinstance(raw, str):
+        return FleetSlotRule(primary=ShipSelector(name=raw))
+    if not isinstance(raw, Mapping):
+        raise TypeError('舰队槽位必须是字符串或规则对象')
+
+    raw_candidates = raw.get('candidates', [])
+    if not isinstance(raw_candidates, Sequence) or isinstance(raw_candidates, str):
+        raise TypeError('candidates 必须是列表')
+    candidates = list(raw_candidates)
+
+    primary: ShipSelector | None = None
+    if _optional_text(raw.get('name')) is not None:
+        primary = _selector_from_mapping(raw, relaxed=False)
+    normalized_candidates: list[ShipSelector] = []
+    for candidate in candidates:
+        if isinstance(candidate, str):
+            selector = _selector_from_mapping(
+                {'name': candidate},
+                relaxed=False,
+                inherited=raw,
+            )
+        elif isinstance(candidate, Mapping):
+            selector = _selector_from_mapping(candidate, relaxed=False)
+        else:
+            raise TypeError('candidates 只能包含舰名字符串或规则对象')
+        normalized_candidates.append(selector)
+    return FleetSlotRule(
+        primary=primary,
+        candidates=_deduplicate_selectors(normalized_candidates),
+    )
+
+
+def fleet_presets_from_yaml(raw: object) -> tuple[FleetPreset, ...] | None:
+    """解析 YAML 的舰队预设列表。"""
+    if raw is None:
+        return None
+    if not isinstance(raw, list):
+        raise TypeError('fleet_presets 必须是列表')
+
+    presets: list[FleetPreset] = []
+    for raw_preset in raw:
+        if not isinstance(raw_preset, Mapping):
+            raise TypeError('fleet_presets 每一项必须是对象')
+        name = _optional_text(raw_preset.get('name')) or ''
+        raw_slots = raw_preset.get('ships')
+        if not isinstance(raw_slots, list):
+            raise TypeError('fleet_presets.ships 必须是非空列表')
+        if not raw_slots:
+            raise ValueError('fleet_presets 不能包含空 ships')
+        presets.append(
+            FleetPreset(
+                name=name,
+                slots=tuple(fleet_slot_from_yaml(slot) for slot in raw_slots),
+            ),
+        )
+    return tuple(presets)
+
+
+def exact_fleet_rules(names: Sequence[str]) -> tuple[FleetSlotRule, ...]:
+    """把普通舰名列表转换成精确槽位规则。"""
+    return tuple(FleetSlotRule(primary=ShipSelector(name=name)) for name in names)
+
+
+def resolve_fleet_selection(
+    plan: CombatPlan,
+    *,
+    fleet_id: int | None = None,
+    fleet: Sequence[str] | None = None,
+    slot_rules: Sequence[FleetSlotRule] | None = None,
+) -> ResolvedFleetSelection:
+    """按 override rules > override fleet > plan preset > plan fleet 集中解析。"""
+    if fleet is not None and len(fleet) == 0:
+        raise ValueError('fleet 不能为空')
+    if slot_rules is not None and len(slot_rules) == 0:
+        raise ValueError('fleet_rules 不能为空')
+    resolved_id = fleet_id if fleet_id is not None else plan.fleet_id
+    if slot_rules is not None:
+        return ResolvedFleetSelection(
+            fleet_id=resolved_id,
+            slot_rules=tuple(slot_rules),
+            plain_fleet=None,
+            source=FleetSelectionSource.OVERRIDE_RULES,
+        )
+    if fleet is not None:
+        return ResolvedFleetSelection(
+            fleet_id=resolved_id,
+            slot_rules=None,
+            plain_fleet=tuple(fleet),
+            source=FleetSelectionSource.OVERRIDE_FLEET,
+        )
+    if plan.fleet_presets:
+        return ResolvedFleetSelection(
+            fleet_id=resolved_id,
+            slot_rules=plan.fleet_presets[0].slots,
+            plain_fleet=None,
+            source=FleetSelectionSource.PLAN_PRESET,
+        )
+    if plan.fleet is not None:
+        return ResolvedFleetSelection(
+            fleet_id=resolved_id,
+            slot_rules=None,
+            plain_fleet=tuple(plan.fleet),
+            source=FleetSelectionSource.PLAN_FLEET,
+        )
+    return ResolvedFleetSelection(
+        fleet_id=resolved_id,
+        slot_rules=None,
+        plain_fleet=None,
+        source=FleetSelectionSource.NONE,
+    )
+
+
+def validate_fleet_selection_arguments(
+    fleet_selection: ResolvedFleetSelection | None,
+    *,
+    fleet_id: int | None,
+    fleet: Sequence[str] | None,
+    slot_rules: Sequence[FleetSlotRule] | None,
+) -> None:
+    """拒绝同时提供 canonical selection 和旧式舰队 override。"""
+    if fleet_selection is not None and any(
+        value is not None for value in (fleet_id, fleet, slot_rules)
+    ):
+        raise ValueError('fleet_selection 不能同时传入 fleet_id、fleet 或 fleet_rules')