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:

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

Response Template:

抱歉，视觉分析服务暂时不可用。

**可能原因**:
- 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:

这个图片格式（`.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:

if "file not found" in error or "cannot access" in error:
    trigger_failure_handling("file_not_found")

Response Template:

找不到图片文件：`[文件路径]`

**可能原因**:
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:

图片分析超时（等待超过 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:

图片分析完成，但质量不高，可能影响准确性。

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

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

**建议改进**:
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:

图片分析似乎不完整，只获取了部分结果。

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

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

**建议操作**:
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

既然图片分析不可用，我们可以用文字方式继续：

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

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

Strategy 2: Incremental Processing

我们可以分步处理：

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

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

Strategy 3: External Tool Assistance

如果内置工具不可用，可以尝试外部工具：

**推荐工具**:
- 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

{
  "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