# 错误处理与降级策略

## 设计理念

> 任何错误都不应中断用户的创造流程。降级，不中断。

## 错误分类与降级矩阵

### 类型 A：环境缺失

| 错误场景 | 检测方式 | 降级策略 | 告知用户 |
|----------|---------|---------|---------|
| Python 3 不可用 | `python3 --version` 失败 | 跳过 gacha.py，从 10 类预设方向中随机选择 | "抽卡引擎需要 Python 3，已改用内置随机选择" |

### 类型 B：可选依赖不可用

| 错误场景 | 检测方式 | 降级策略 | 告知用户 |
|----------|---------|---------|---------|
| 生图 skill 未安装 | 检查 skill 是否存在 | 输出完整提示词文本 + 手动生图平台说明 | "未检测到可用的生图 skill，已输出提示词供手动使用" |
| 生图 skill 调用失败 | skill 返回错误 | 重试 1 次，仍失败则输出提示词文本 | "生图失败，已输出提示词供手动使用" |

### 类型 C：运行时异常

| 错误场景 | 降级策略 | 告知用户 |
|----------|---------|---------|
| gacha.py 输出格式异常 | 从 10 类预设方向中随机选择 | "抽卡结果解析失败，已改用内置随机" |
| 任何未预期错误 | 记录错误信息，跳过该步骤，继续主流程 | "遇到了一个问题：[错误简述]。已跳过继续" |

## 错误信息统一格式

```markdown
> [警告] **[步骤名] 已降级**
> 原因：[发生了什么]
> 影响：[什么功能受限]
> 替代：[正在用什么兜底]
> 修复：[怎么恢复完整功能]
```

示例：

```markdown
> [警告] **头像生成已降级**
> 原因：未检测到可用的生图 skill
> 影响：无法自动生成头像图片
> 替代：已输出完整提示词，可复制到 Gemini / ChatGPT 手动生成
> 修复：在当前环境中安装并启用经过审核的生图 skill
```

## 关键原则

1. **文本方案是核心价值，头像是锦上添花**——辅助功能失败永不中断主流程
2. **降级信息要可操作**——不只说"出错了"，要说"怎么修"
3. **一次降级不影响后续步骤**——Step 5 降级了，Step 6 照常输出