# 错误处理规范

> 从 Claude Code 的 `categorizeRetryableAPIError()` + `isTerminalTaskStatus()` 模式迁移。

## 错误三分类

```
类别         处理方式              例子
─────        ──────────            ──────────
可重试       退避重试（3次）       网络超时、API 限流
不可重试     立即报告              权限不足、参数非法
用户取消     静默终止              用户中断、超时退出
```

## 具体规则

### 网络/API 相关
- 首次失败等待 2s → 第二次 5s → 第三次报告失败
- 网络超时不等同于系统故障，一律重试
- 重试时保持操作幂等（不产生重复副作用）

### 文件操作
- 写文件前置检查路径合法性
- 移动/删除文件用 `mv` 而非 `rm`（保留恢复可能）
- 目录创建用 `mkdir -p` 确保幂等

### 执行命令
- `exec` 失败时先看 stderr，非零退出不等同于失败
- `timeout` 后进程可能仍在运行，需 `process kill` 清理
- 用 `pipefail` 确保中间步骤失败能被检测

### 用户取消
- 用户中断（如 `Ctrl+C`）不做重试
- 已产生的副作用不回滚，但标记状态
- 报告"已处理到哪一步"而非"失败了"

## Fast-Path 模式

```
复杂操作前先问快速路径:
  1. 这个操作我能 10s 内完成吗？→ 直接干
  2. 需要用户决策？→ 先问再干
  3. 可能失败？→ 预估风险，必要时先问
```