# StateMachineBase 状态机框架

## 概述

`StateMachineBase<TState, TContext>` 是一个通用的有限状态机基类，专为游戏自动化场景设计。

## 核心概念

| 概念 | 说明 |
|------|------|
| **State** | 游戏界面的抽象（如 MainWorld、EventMenu） |
| **Transition** | 状态之间的有向边，定义从一个状态可能到达的下一个状态 |
| **Handler** | 状态处理器，执行当前状态的操作（如点击按钮），返回 `StateHandlerResult` |
| **Detector** | 状态检测器，根据截图判断当前是否处于某个状态 |

## StateHandlerResult

Handler 必须返回 `StateHandlerResult`，状态机根据返回值决定下一步行为：

| 返回值 | 语义 | 状态机行为 | 使用场景 |
|--------|------|-----------|----------|
| `Success` | 操作成功 | 等待邻接状态转换 | 点击按钮后等待界面切换 |
| `Wait` | 可预期的等待 | 继续循环，重新检测 | 动画播放中、已到达目标状态 |
| `Retry` | 意外失败 | 重试计数+1，超限后异常 | 找不到按钮、OCR 识别失败 |
| `Fail` | 无法恢复 | 立即抛出异常 | 严重错误需要停止 |

## 使用步骤

### 1. 定义状态枚举

```csharp
public enum MyState
{
    Unknown,
    MainWorld,
    EventMenu,
    BattleArena
}
```

### 2. 继承 StateMachineBase

```csharp
public class MyTask : StateMachineBase<MyState, BvPage>
{
    protected override ILogger Logger => _logger;
    private readonly ILogger<MyTask> _logger;
}
```

### 3. 注册 Handlers

```csharp
RegisterStateHandlers(
    (MyState.MainWorld, HandleMainWorld),
    (MyState.EventMenu, HandleEventMenu)
);

RegisterUnknownStateHandler(HandleUnknown);
```

### 4. 注册 Detectors

```csharp
RegisterStateDetectors(
    (MyState.MainWorld, DetectMainWorld),
    (MyState.EventMenu, DetectEventMenu),
    (MyState.BattleArena, DetectBattleArena)
);
```

### 5. 注册状态转换

```csharp
RegisterStateTransitions(
    (MyState.MainWorld, [MyState.EventMenu]),
    (MyState.EventMenu, [MyState.BattleArena])
);
```

### 6. 实现 Handler

```csharp
private async Task<StateHandlerResult> HandleMainWorld(BvPage page)
{
    Simulation.SendInput.SimulateAction(GIActions.OpenTheEventsMenu);
    await Delay(500, _ct);
    return StateHandlerResult.Success; // 等待转换到 EventMenu
}

private async Task<StateHandlerResult> HandleEventMenu(BvPage page)
{
    var button = page.GetByText("开始").FindAll().FirstOrDefault();
    if (button == null)
    {
        return StateHandlerResult.Retry; // 找不到按钮，重试
    }
    
    button.Click();
    await Delay(300, _ct);
    return StateHandlerResult.Success;
}

private Task<StateHandlerResult> HandleBattleArena(BvPage page)
{
    // 已到达目标状态
    return Task.FromResult(StateHandlerResult.Wait);
}

private async Task<StateHandlerResult> HandleUnknown(BvPage page)
{
    await new ReturnMainUiTask().Start(_ct);
    return StateHandlerResult.Wait; // 尝试恢复后重新检测
}
```

### 7. 实现 Detector

```csharp
private bool DetectMainWorld(ImageRegion ra)
{
    return ra.Find(MainWorldAssets.Minimap).IsExist();
}

private bool DetectEventMenu(ImageRegion ra)
{
    return ra.FindMulti(RecognitionObject.Ocr(100, 50, 200, 50))
             .Any(t => t.Text.Contains("活动"));
}
```

### 8. 运行状态机

```csharp
public async Task Start(CancellationToken ct)
{
    Initialize(ct, MyState.MainWorld);
    
    using var page = Bv.Page();
    await RunStateMachineUntil(page, MyState.BattleArena);
    
    // 状态机退出后，已到达 BattleArena
    await ExecuteBattle();
}
```

## API 参考

### 核心方法

| 方法 | 说明 |
|------|------|
| `Initialize(ct, initialState)` | 初始化状态机 |
| `RunStateMachineUntil(context, targetStates)` | 运行直到达到目标状态 |
| `RunStateMachineUntil(context, targetState)` | 运行直到达到单个目标状态 |
| `EnsureNextStateTransition(timeout)` | 等待邻接状态转换（供特殊场景使用） |

### 注册方法

| 方法 | 说明 |
|------|------|
| `RegisterStateHandler(state, handler)` | 注册单个状态处理器 |
| `RegisterStateHandlers(...)` | 批量注册状态处理器 |
| `RegisterUnknownStateHandler(handler)` | 注册未知状态处理器 |
| `RegisterStateDetector(state, detector)` | 注册单个状态检测器 |
| `RegisterStateDetectors(...)` | 批量注册状态检测器 |
| `RegisterStateTransitions(...)` | 注册状态转换关系 |

### 可重写属性

| 属性 | 默认值 | 说明 |
|------|--------|------|
| `DefaultDetectionInterval` | 300ms | 状态检测间隔 |
| `DefaultTransitionTimeout` | 10000ms | 状态转换超时 |
| `DefaultMaxRetries` | 3 | 最大重试次数 |
| `StateMachineLoopInterval` | 200ms | 状态机循环间隔 |

## 状态机循环流程

```
┌─────────────────────────────────────────────────────┐
│                  RunStateMachineUntil               │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │  RefreshCurrentState │  ◄─────────────┐
              │  (检测当前状态)       │                │
              └──────────────────────┘                │
                         │                            │
                         ▼                            │
              ┌──────────────────────┐                │
              │ 是否到达目标状态？    │                │
              └──────────────────────┘                │
                    │         │                       │
                   Yes        No                      │
                    │         │                       │
                    ▼         ▼                       │
              ┌────────┐  ┌──────────────────────┐    │
              │  退出  │  │  执行 Handler         │    │
              └────────┘  └──────────────────────┘    │
                                   │                  │
                                   ▼                  │
                    ┌─────────────────────────────┐   │
                    │      Handler 返回值          │   │
                    └─────────────────────────────┘   │
                         │    │    │    │            │
          ┌──────────────┤    │    │    │            │
          │              │    │    │    │            │
          ▼              ▼    ▼    ▼    │            │
    ┌─────────┐    ┌─────┐ ┌───┐ ┌────┐│            │
    │ Success │    │Wait │ │Rty│ │Fail││            │
    └─────────┘    └─────┘ └───┘ └────┘│            │
          │              │    │    │   │            │
          ▼              │    │    ▼   │            │
    ┌───────────────┐    │    │  抛出  │            │
    │EnsureNextState│    │    │  异常  │            │
    │   Transition  │    │    │        │            │
    └───────────────┘    │    │        │            │
          │              │    ▼        │            │
          │              │ ┌────────┐  │            │
          │              │ │重试计数│  │            │
          │              │ │  +1    │  │            │
          │              │ └────────┘  │            │
          │              │    │        │            │
          └──────────────┴────┴────────┴────────────┘
```

## 性能优化

### 检测器顺序

注册检测器时按速度排序（先快后慢）：

1. **模板匹配**（~10ms）- 最快
2. **小范围 OCR**（~50ms）
3. **大范围 OCR**（~100-200ms）- 最慢

### 邻接状态顺序

`RegisterStateTransitions` 中候选状态的顺序影响检测优先级，更具体的状态应放在前面：

```csharp
// 正确：更具体的状态放前面
(TeleportMap, [DomainEntrance, MainWorld])

// 错误：通用状态会被优先检测
(TeleportMap, [MainWorld, DomainEntrance])
```

## 示例

完整示例见 `GameTask/AutoStygianOnslaught/AutoStygianOnslaughtTask.cs`

状态图：
```
MainWorld ─► EventMenu ─► StygianOnslaughtPage ─► TeleportMap
                                                      │
                                                      ▼
DomainLobby ◄── DifficultySelect ◄── DomainEntrance ◄─┘
    │
    ▼
BossSelect ─► BattleArena ─► BattleResult ─► DomainLobby
```