Agent/knowledge_batch_20260411_toolhub_error_recovery.json

{
  "upload_batch": "ToolHub 错误恢复与图像评估局限性",
  "upload_date": "2026-04-11",
  "source_type": "execution",
  "knowledge_count": 2,
  "knowledge": [
    {
      "id": "knowledge-20260411-exec-001",
      "task": "在 ToolHub 搜索接口返回 500 错误时直接调用工具",
      "content": "当 toolhub_search 返回 500 Internal Server Error 但 toolhub_health 检查通过时，可以直接尝试调用 toolhub_call 执行工具。健康检查通过说明服务核心功能可用，搜索接口可能是临时故障。\n\n## 错误恢复策略\n1. **健康检查优先**：遇到 toolhub_search 失败时，先用 toolhub_health 确认服务状态\n2. **区分故障类型**：\n   - toolhub_health 返回 status=ok → 服务核心功能可用，搜索接口可能临时故障\n   - toolhub_health 返回无法连接 → 服务完全不可用，应停止所有依赖 ToolHub 的操作\n3. **绕过搜索直接调用**：健康检查通过时，可直接使用 toolhub_call(tool_id=xxx, params={...}) 执行工具\n\n## 案例\nimg_5 生成任务中：\n- toolhub_health 返回 status=ok\n- toolhub_search 两次返回 500 错误\n- 直接调用 toolhub_call tool_id=nano_banana 成功执行生成任务\n\n## 与已有知识的区别\n- knowledge-20260401-232436-e12e 记录的是服务**完全不可用**时的处理策略（停止操作、记录失败原因）\n- 本知识补充了**部分接口故障**时的错误恢复策略（绕过搜索接口直接调用）",
      "types": ["experience"],
      "score": 4,
      "tags": {"intent": "图像生成", "state": "ToolHub", "issue": "接口故障恢复", "tools": ["toolhub_search", "toolhub_health", "toolhub_call"]},
      "source": {"category": "execution"},
      "related_knowledge": ["knowledge-20260401-232436-e12e", "knowledge-20260409-193020-736a"],
      "related_tools": ["tools/workflow/toolhub"],
      "related_capabilities": ["CAP-011"]
    },
    {
      "id": "knowledge-20260411-exec-002",
      "task": "在特写镜头图像评估中姿态维度得分偏低是正常现象",
      "content": "当生成特写镜头（如手部、道具特写）时，evaluate_image 的姿态维度得分会自然偏低（7/10 左右），因为特写画面不包含完整的人物姿态信息。这是评估工具的局限性，不应视为生成失败。\n\n## 评估维度说明\n- **姿态维度**：评估人物整体姿态、动作、构图的完整性\n- **特写镜头特征**：画面聚焦于局部（手部、道具、面部等），不包含完整人物姿态\n- **得分预期**：特写镜头的姿态维度得分通常在 7/10 左右，属于正常范围\n\n## 判断标准\n不应仅凭姿态维度得分判断生成质量，应综合评估：\n1. **核心目标达成度**：如材质质感、细节清晰度等关键指标\n2. **其他维度得分**：材质、构图、色彩等维度可能得分很高\n3. **整体评分**：整体 8.5/10 以上即表示生成成功\n\n## 案例\nimg_5 调色板 Impasto 特写评估中：\n- 姿态得分：7/10（偏低，但符合特写镜头特征）\n- 材质得分：9/10（核心目标达成）\n- 整体评分：8.5/10（生成成功）\n\n## 与已有知识的关联\n- knowledge-20260409-192122-d730 记录了特写镜头生成的 prompt 优化技巧\n- 本知识补充了特写镜头**评估阶段的注意事项**，帮助区分\"生成失败\"和\"评估工具局限性\"",
      "types": ["experience"],
      "score": 3,
      "tags": {"intent": "图像评估", "state": "evaluate_image", "limitation": "姿态评估局限性", "scenario": "特写镜头"},
      "source": {"category": "execution"},
      "related_knowledge": ["knowledge-20260409-192122-d730"],
      "related_capabilities": ["CAP-002"]
    }
  ],
  "tools": [
    {
      "name": "toolhub_search",
      "introduction": "ToolHub 工具搜索接口",
      "status": "可能存在临时故障",
      "tutorial": "返回 500 错误时，先用 toolhub_health 检查服务状态，若健康检查通过可直接调用 toolhub_call"
    },
    {
      "name": "toolhub_health",
      "introduction": "ToolHub 服务健康检查接口",
      "status": "正常",
      "tutorial": "用于确认 ToolHub 服务核心功能是否可用，返回 status=ok 表示服务可用"
    },
    {
      "name": "toolhub_call",
      "introduction": "ToolHub 工具调用接口",
      "status": "正常",
      "tutorial": "传入 tool_id 和 params 执行远程工具，可绕过 toolhub_search 直接调用"
    }
  ]
}