{
  "openapi": "3.0.3",
  "info": {
    "title": "箱熵具身智能知识库与方案生成 API (Entropy Box Embodied AI API)",
    "description": "面向机器人与具身智能领域的知识图谱、技术调研证据检索、实体档案直查与 LLM 自动化工程方案装配接口。支持通过 WorkBuddy、Trae、ChatGPT Custom Actions、Claude 及任何 HTTP/MCP 客户端接入。所有接口原生支持中文与英文输入，查询语言自动识别（无需额外参数）；Consult 默认返回 hybrid search 的图谱结构化结果（快、接地），请求体置 integrate=true 时启用 LLM 生成式技术链装配（响应较慢，调用方请将客户端超时 timeout 设为 180 秒以上）。",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://xiangshang.ngrok.app",
      "description": "公网生产环境"
    },
    {
      "url": "http://127.0.0.1:8001",
      "description": "本地开发环境"
    }
  ],
  "paths": {
    "/api/consult": {
      "post": {
        "operationId": "consultRoboticsSolution",
        "summary": "工程咨询与自动化方案生成 (Consult)",
        "description": "输入具体机器人工程规划/落地问题（支持中文或英文），自动进行多步意图拆解、跨领域混合检索（向量+BM25+图扩展+精排）相关 Topic/Capability/Asset 候选池，并**默认返回图谱结构化结果**（results + task_steps + chains，带 graph_via 归因边）。LLM 技术链装配（/integrate）为**可选**能力：仅当请求体 integrate=true 时额外由 LLM 装配可落地的多阶段执行技术链（含分支/合并决策与算法选型），图谱结果仍一并返回。仅取图谱时响应明显更快；启用 integrate 时单次响应通常需 30–180 秒，调用方须将客户端超时（timeout）设置为 180 秒以上。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsultRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功返回方案链路与候选池",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsultResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/lookup": {
      "get": {
        "operationId": "lookupEntityGet",
        "summary": "单实体/能力资料直查 (Lookup - GET)",
        "description": "按能力 ID (CAP_xxx)、资产 ID (AST_xxx) 或话题关键词直查技术档案。注意：为保护知识产权及防止批量拖库，话题（Topic）仅返回摘要元数据与概览；查询具体 CAP_/AST_ 实体将返回详细定义与规范。",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "查询词（如 stair_navigation / CAP_90e22fca / AST_43b86326 / 楼梯感知；支持中文或英文）",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "可选限定实体类型：topic | cap | asset",
            "schema": {
              "type": "string",
              "enum": [
                "topic",
                "cap",
                "asset"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "返回格式：json 或 md（默认 json）",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "md"
              ],
              "default": "json"
            }
          },
          {
            "name": "list",
            "in": "query",
            "required": false,
            "description": "是否返回候选列表模式（模糊匹配多个实体）",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "first",
            "in": "query",
            "required": false,
            "description": "候选列表模式下仅取首个匹配实体并渲染",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "查询结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "lookupEntityPost",
        "summary": "单实体/能力资料直查 (Lookup - POST)",
        "description": "通过 POST 请求查询具体能力/资产档案。注意：为保护知识产权及防止批量拖库，话题（Topic）仅返回摘要元数据与概览；查询具体 CAP_/AST_ 实体将返回详细定义与规范。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "查询结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/evidence/search": {
      "post": {
        "operationId": "searchEvidence",
        "summary": "调研证据与开源选型依据检索 (Evidence Search)",
        "description": "检索机器人/具身智能领域工程范式、开源选型依据、算法对比笔记等脱敏片段。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvidenceSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "检索命中文档片段",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvidenceSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "post": {
        "operationId": "searchKnowledgeBase",
        "summary": "知识库多路混合召回 (Knowledge Search)",
        "description": "支持 topics / caps / assets 多维度的向量 + BM25 + CrossEncoder 混合召回。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "知识库检索结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ConsultRequest": {
        "type": "object",
        "required": [
          "question"
        ],
        "properties": {
          "question": {
            "type": "string",
            "description": "具体的机器人工程问题（如：PyBullet 里机械臂如何稳定抓取并实时避障；支持中文或英文输入）"
          },
          "top_k": {
            "type": "integer",
            "default": 30,
            "description": "召回候选条数（10-100）"
          },
          "rerank": {
            "type": "boolean",
            "default": true,
            "description": "是否启用 CrossEncoder 精排"
          },
          "prev_context": {
            "type": "string",
            "description": "前序多轮会话的方案结论（用于上下文衔接）"
          },
          "brief": {
            "type": "boolean",
            "default": false,
            "description": "是否仅返回简要链路骨架"
          },
          "integrate": {
            "type": "boolean",
            "default": false,
            "description": "是否额外启用 LLM 技术链装配。默认 false——仅返回 hybrid search 的图谱结构化结果（results+task_steps+chains）；true 时叠加 LLM 装配，图谱仍一并返回。"
          }
        }
      },
      "ConsultResponse": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string"
          },
          "pool": {
            "type": "object",
            "description": "候选池规模计数（topics/caps/assets）"
          },
          "results": {
            "type": "object",
            "description": "hybrid search 的图谱结构化结果（topics/caps/assets 完整实体记录 + graph_via 归因边），始终返回"
          },
          "task_steps": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "LLM 对问题的多步意图拆解"
          },
          "chains": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "搜索期发现的关联子图，始终返回"
          },
          "synthesis": {
            "type": "object",
            "nullable": true,
            "description": "LLM 技术链装配结果；仅当请求 integrate=true 时非 null，否则为 null（图谱结果已含全部接地内容）"
          },
          "latency_ms": {
            "type": "number"
          }
        }
      },
      "LookupRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "查询词（keyword / CAP_xxx / AST_xxx / 中文名；支持中文或英文）"
          },
          "type": {
            "type": "string",
            "enum": [
              "topic",
              "cap",
              "asset"
            ],
            "description": "可选限定实体类型"
          },
          "format": {
            "type": "string",
            "enum": [
              "json",
              "md"
            ],
            "default": "json"
          },
          "list": {
            "type": "boolean",
            "default": false
          },
          "first": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "LookupResponse": {
        "type": "object",
        "properties": {
          "found": {
            "type": "boolean"
          },
          "query": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "record": {
            "type": "object"
          },
          "markdown": {
            "type": "string"
          },
          "candidates": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "EvidenceSearchRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "检索查询（自然语言问题或技术概念；支持中文或英文）"
          },
          "topic": {
            "type": "string",
            "nullable": true
          },
          "top_k": {
            "type": "integer",
            "default": 10
          },
          "mode": {
            "type": "string",
            "default": "hybrid"
          },
          "rerank": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "EvidenceSearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "latency_ms": {
            "type": "number"
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "检索关键词或自然语言需求（支持中文或英文）"
          },
          "scope": {
            "type": "string",
            "default": "all"
          },
          "top_k": {
            "type": "integer",
            "default": 20
          },
          "mode": {
            "type": "string",
            "default": "hybrid"
          },
          "rerank": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "results": {
            "type": "object"
          }
        }
      }
    }
  }
}