Initial commit: skills library
- 70 skills with code and documentation - Add .gitignore (ignore __pycache__, output/, temp/, venv/) - Clean up test intermediates and caches
This commit is contained in:
hmo
@@ -0,0 +1,443 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user