大海
45 lines
1.4 KiB
Markdown
45 lines
1.4 KiB
Markdown
# 错误处理规范
|
|
|
|
> 从 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. 可能失败？→ 预估风险，必要时先问
|
|
```
|