16gagent/rules/error-handling.md

错误处理规范

从 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. 可能失败？→ 预估风险，必要时先问