# Fuse 新手指南

3 分钟上手熔断器。

## 安装

```bash
moon add fuse
```

## 一分钟快速开始

```moonbit
// 1. 导入（在你的 moon.pkg 中添加 "fuse/lib"）

// 2. 创建熔断器（默认：5次失败熔断/30s冷却/3次半开成功恢复）
let fuse = @fuse.default_fuse()

// 3. 包裹业务调用
match fuse.try_acquire() {
  Ok(_) => {
    // 执行业务...
    let ok = call_external_service()
    if ok {
      fuse.record_success()
    } else {
      fuse.record_failure()
    }
  }
  Err(e) => println(e)  // 熔断中，拒绝请求
}
```

## 常用场景

### 场景1：保护微服务调用

```moonbit
let svc_fuse = @fuse.new_builder()
  .failure_threshold(3)   // 3 次失败就熔断
  .cooldown_secs(15)      // 15 秒后尝试恢复
  .half_open_limit(2)     // 半开状态需 2 次成功才正式恢复
  .on_trip(fn(fails) { alerting.send("服务熔断: " + fails.to_string() + "次失败") })
  .on_restore(fn() { alerting.send("服务恢复") })
  .build()
```

### 场景2：AI Agent 工具执行

```moonbit
// 工具连续失败 5 次 → 暂停调用该工具 60 秒
let tool_fuse = @fuse.strict_fuse()  // threshold=2 cooldown=60s
```

### 场景3：三种预设

```moonbit
let dev    = @fuse.permissive_fuse() // threshold=10 cooldown=10s
let prod   = @fuse.default_fuse()    // threshold=5  cooldown=30s
let strict = @fuse.strict_fuse()     // threshold=2  cooldown=60s
```

## 状态转换

```
[正常] Closed ──连续N次失败──▶ Open [拒绝]
   ▲                              │
   │      [冷却期满]               │
   └── HalfOpen ◀─────────────────┘
        │
        ├── 半开成功 → Closed
        └── 半开失败 → Open
```

## 核心概念

| 概念 | 说明 |
|------|------|
| **failure_threshold** | 连续失败 N 次后熔断 |
| **cooldown_secs** | 熔断后等多少 tick 才进入半开 |
| **half_open_limit** | 半开状态需连续成功多少次才恢复 |
| **try_acquire** | 获取执行许可（Open 状态会被拒绝）|
| **tick** | 手动推进时间计数器 |

## 从 AegisRun monitor 迁移

如果你在用 AegisRun 的 `monitor.mbt` 熔断部分：

```moonbit
// 之前（AegisRun 内嵌）
let monitor = @aegisrun.lib.default_monitor()
monitor.update_metrics(cpu, mem, instances, queue, avg_ms, denial, 1)
if monitor.is_circuit_open() { ... }

// 之后（Fuse 独立库）
let fuse = @fuse.default_fuse()
match fuse.try_acquire() { Ok(_) => ... Err(_) => ... }
```

## 常见问题

**Q: tick 是什么？**
A: Fuse 的时间计数器。每次 `try_acquire()` 自动 +1。如果需要独立控制时间，手动调用 `fuse.tick()`。

**Q: 半开状态做什么？**
A: 熔断后不立即恢复——先放少量请求探测，成功了才正式恢复，失败则重新熔断。

**Q: 和 FlowGate 什么关系？**
A: 互补。FlowGate 管「并发量」，Fuse 管「失败率」。建议一起用。

## 下一步

- [README](README.md) — API 完整参考
- [LICENSE](LICENSE) — Apache-2.0