skills/agent-vision-awareness/references/failure-handling.md

# Failure Handling and Graceful Degradation

Comprehensive guide for handling visual processing failures.

## Failure Scenarios

### Scenario 1: multimodal-looker Agent Unavailable

**Symptoms:**
- No response from @multimodal-looker
- Error: "Agent not found" or "Service unavailable"
- Timeout after 60+ seconds

**Detection:**
```python
if agent_response.status == "timeout" or "unavailable" in error_message:
    trigger_failure_handling("agent_unavailable")
```

**Response Template:**
```markdown
抱歉，视觉分析服务暂时不可用。

**可能原因**:
- multimodal-looker 服务正在维护
- 网络连接问题
- 服务负载过高

**替代方案**:
1. **稍后重试**: 等待 5-10 分钟后再次尝试
2. **文字描述**: 请用文字描述图片内容，我可以继续帮助你
3. **手动分析**: 如果你能提供图片的关键信息，我可以基于此给出建议

**需要我帮你做什么**:
- [ ] 稍后自动重试
- [ ] 继续其他任务（先跳过图片分析）
- [ ] 你用文字描述，我继续处理
```

**Follow-up Actions:**
- Log the failure for monitoring
- Offer to retry after delay
- Proceed with text-only workflow if possible

---

### Scenario 2: Image Format Not Supported

**Symptoms:**
- Error: "Unsupported image format"
- Error: "Cannot process file type"
- Recognition rate very low

**Supported Formats:**
```
✅ Supported: PNG, JPG/JPEG, GIF, BMP, WebP, SVG (rasterized)
❌ Unsupported: PSD, AI, EPS, RAW, HEIC (without conversion)
⚠️  Limited: PDF (first page only), TIFF (may be slow)
```

**Response Template:**
```markdown
这个图片格式（`.xxx`）可能不被支持。

**当前支持的格式**:
- ✅ PNG, JPG/JPEG, GIF, BMP, WebP
- ⚠️  SVG, TIFF, PDF（有限支持）

**建议操作**:
1. **转换格式**: 
   - 使用在线工具转换为 PNG 或 JPG
   - 推荐工具：[工具名称/链接]
   
2. **截图替代**:
   - 如果是设计文件，可以截图为 PNG
   
3. **文字描述**:
   - 描述图片内容，我继续帮助你

**需要帮助转换吗**？我可以提供具体的转换步骤。
```

**Recovery Options:**
- Provide format conversion tools
- Suggest screenshot as alternative
- Accept text description

---

### Scenario 3: Image File Not Found

**Symptoms:**
- Error: "File not found"
- Error: "Cannot access file"
- Empty response

**Detection:**
```python
if "file not found" in error or "cannot access" in error:
    trigger_failure_handling("file_not_found")
```

**Response Template:**
```markdown
找不到图片文件：`[文件路径]`

**可能原因**:
1. ❌ 文件路径不正确
2. ❌ 文件已被删除或移动
3. ❌ 没有访问权限
4. ❌ 文件正在被其他程序使用

**请检查**:
- [ ] 文件路径是否完整且正确
- [ ] 文件是否确实存在于该位置
- [ ] 是否有读取该文件的权限
- [ ] 文件是否被其他程序锁定

**解决方案**:
1. **重新提供路径**: 请确认正确的文件路径
2. **重新上传**: 如果可以，请重新上传图片
3. **使用绝对路径**: 尝试使用完整的绝对路径

**示例**:
```
错误：./image.png
正确：D:/projects/my-app/assets/image.png
```
```

**Debugging Steps:**
1. Verify file path syntax
2. Check if file exists
3. Verify permissions
4. Try absolute path

---

### Scenario 4: Analysis Timeout

**Symptoms:**
- No response after 60 seconds
- Error: "Request timeout"
- Partial response then silence

**Timeout Thresholds:**
```
Normal image (< 5MB): 10-30 seconds
Large image (5-20MB): 30-60 seconds
Very large (> 20MB): May timeout
Complex diagram: 20-40 seconds
```

**Response Template:**
```markdown
图片分析超时（等待超过 60 秒）。

**可能原因**:
1. 🐌 图片文件过大（超过 20MB）
2. 🌐 网络延迟或不稳定
3. 🔄 服务繁忙，处理队列长
4. 🖼️ 图片内容过于复杂

**建议操作**:
1. **压缩图片**:
   - 目标大小：< 5MB
   - 推荐工具：TinyPNG, Squoosh
   
2. **降低分辨率**:
   - 建议尺寸：1920x1080 或更低
   - 保持清晰度即可
   
3. **简化内容**:
   - 如果是长图，可以分段发送
   - 如果是多页，可以分页发送
   
4. **重试**:
   - 等待几分钟后再次尝试
   - 网络可能暂时不稳定

**需要我帮你压缩图片吗**？或者你可以先描述关键信息，我继续处理。
```

**Optimization Tips:**
- Recommend image compression
- Suggest resolution reduction
- Offer to split large images

---

### Scenario 5: Poor Image Quality

**Symptoms:**
- Low confidence in analysis
- "Cannot read text clearly"
- Missing details in response
- Blurry or distorted recognition

**Quality Issues:**
```
❌ Blurry: Out of focus, motion blur
❌ Dark: Underexposed, low contrast
❌ Small text: Resolution too low
❌ Glare: Reflection, overexposed
❌ Cropped: Important content cut off
```

**Response Template:**
```markdown
图片分析完成，但质量不高，可能影响准确性。

**识别到的问题**:
- ⚠️ 图片模糊，文字识别困难
- ⚠️ 光线不足，部分细节不清
- ⚠️ 分辨率低，小字无法辨认

**当前分析结果**（仅供参考）:
[分析结果，标注置信度]

**建议改进**:
1. **重新拍摄**:
   - 确保光线充足
   - 保持相机稳定
   - 对焦清晰
   
2. **提高分辨率**:
   - 使用更高 DPI 扫描
   - 截图而非拍照
   
3. **调整角度**:
   - 避免反光和阴影
   - 正面拍摄，不要倾斜

**或者**:
- 你可以直接告诉我图片中的关键信息
- 或者指出你关心的具体部分，我尽力分析
```

**Workarounds:**
- Provide best-effort analysis with confidence disclaimer
- Ask user to clarify specific areas
- Accept text input for critical information

---

### Scenario 6: Partial Analysis (Incomplete Results)

**Symptoms:**
- Response cuts off mid-sentence
- Only partial image analyzed
- Missing requested information

**Response Template:**
```markdown
图片分析似乎不完整，只获取了部分结果。

**已获取的信息**:
- [列出已分析的内容]

**缺失的信息**:
- [列出未分析的部分]

**建议操作**:
1. **请求补充分析**:
   @multimodal-looker 请补充分析图片的 [具体部分]
   
2. **分段处理**:
   如果是长图或复杂图片，可以分段发送分析
   
3. **手动补充**:
   你可以补充缺失部分的信息，我整合分析

**需要我请求补充分析吗**？或者你提供额外信息？
```

**Recovery:**
- Request targeted re-analysis
- Ask user to provide missing context
- Combine partial results with text input

---

## Escalation Protocol

### Level 1: Automatic Retry
```
First failure → Wait 10 seconds → Retry once
```

### Level 2: Alternative Approach
```
Second failure → Suggest alternative (compression, format conversion, text description)
```

### Level 3: Human Intervention
```
Third failure → Acknowledge limitation → Request manual input
```

### Level 4: Task Redesign
```
Persistent failure → Propose alternative workflow → Bypass visual processing
```

---

## Recovery Strategies

### Strategy 1: Text-Based Alternative
```markdown
既然图片分析不可用，我们可以用文字方式继续：

**请你描述**:
1. 图片的主要内容是什么？
2. 你关心图片中的哪些部分？
3. 你希望基于图片完成什么任务？

**我会根据描述**:
- 提供针对性建议
- 继续后续工作
- 必要时再尝试图片分析
```

### Strategy 2: Incremental Processing
```markdown
我们可以分步处理：

**步骤 1**: 你先描述图片概要
**步骤 2**: 我基于概要提供初步建议
**步骤 3**: 针对关键点，我们再尝试图片分析
**步骤 4**: 整合结果，完成整体任务

这样即使某一步失败，也能继续推进。
```

### Strategy 3: External Tool Assistance
```markdown
如果内置工具不可用，可以尝试外部工具：

**推荐工具**:
- OCR: 白描、ABBYY FineReader
- 图表分析：ChartExpo、Plotly
- 架构图：Draw.io、Lucidchart

**流程**:
1. 使用外部工具分析
2. 导出分析结果（文字/数据）
3. 我基于结果继续处理
```

---

## Monitoring and Logging

### Failure Metrics to Track
```
- Total visual requests
- Success rate
- Average response time
- Failure reasons distribution
- Retry success rate
```

### Log Format
```json
{
  "timestamp": "2026-02-26T10:30:00Z",
  "task_id": "vision-12345",
  "failure_type": "timeout",
  "image_size": "15MB",
  "retry_count": 2,
  "resolution": "text_description",
  "user_satisfaction": "pending"
}
```

---

## User Communication Best Practices

### DO:
1. ✅ Acknowledge the failure promptly
2. ✅ Explain the reason clearly (without technical jargon)
3. ✅ Provide concrete alternatives
4. ✅ Offer specific next steps
5. ✅ Maintain positive, helpful tone

### DON'T:
1. ❌ Blame the user ("你的图片有问题")
2. ❌ Make excuses without solutions
3. ❌ Give up without alternatives
4. ❌ Use vague language ("可能", "也许")
5. ❌ Repeat the same failed approach

### Example Phrases

**Good**:
- "抱歉，图片分析遇到了问题。我们可以试试这样的替代方案..."
- "虽然无法分析图片，但如果你能描述 [关键信息]，我可以继续帮助你..."
- "这个格式暂时不支持，建议转换为 PNG。需要我提供转换工具吗？"

**Bad**:
- "这个图片不行" (太模糊)
- "我处理不了" (放弃态度)
- "你换个图片" (推卸责任)

---

## Testing Checklist

Test failure handling for:

- [ ] Agent timeout (simulate delay)
- [ ] Unsupported format (send .psd file)
- [ ] File not found (invalid path)
- [ ] Large file timeout (> 20MB)
- [ ] Blurry image (low quality)
- [ ] Partial response (cut off mid-analysis)
- [ ] Network error (disconnect)
- [ ] Service error (mock 500 response)

For each test:
- [ ] Appropriate error message shown
- [ ] Alternatives provided
- [ ] User can continue task
- [ ] No crash or hang
- [ ] Logs recorded

---

## Continuous Improvement

After each failure:
1. Record failure type and context
2. Analyze root cause
3. Update detection/prevention logic
4. Improve response templates
5. Test with similar scenarios

Share learnings with:
- Skill maintainers
- OMO development team
- multimodal-looker operators