{"openapi":"3.1.0","info":{"title":"Kefuma Public Manual API","version":"3.0.0","description":"机器可读的产品说明书 API。每份已发布的说明书提供五种形态：Markdown 全文（GET /m/{slug}.md）、结构化 JSON、语义检索、RAG 上下文包、RAG 问答。另有 MCP server（POST /api/mcp，Streamable HTTP 2025-06-18，读工具 list_manuals/get_manual/search_manual/ask_manual + 写工具 submit_ticket/check_warranty/register_product/request_human，可替用户办理售后）。接入指南见 /developers。无需鉴权；按 IP 限流（429 带 Retry-After）；内容端点支持 ETag/If-None-Match。站点索引见 /llms.txt。"},"servers":[{"url":"https://kefuma.com"}],"paths":{"/api/v2/{slug}/manual":{"get":{"operationId":"getManual","summary":"结构化说明书 JSON（章节 + FAQ 全文）","parameters":[{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"说明书结构化内容","content":{"application/json":{"schema":{"type":"object","properties":{"productName":{"type":"string"},"oneLiner":{"type":"string"},"brand":{"type":"string"},"version":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"body":{"type":"string","description":"HTML"}}}},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}}}}}}},"403":{"description":"说明书设有访问密码，不对机器开放"},"404":{"description":"不存在或未发布"}}}},"/api/v2/{slug}/markdown":{"get":{"operationId":"getManualMarkdown","summary":"说明书 Markdown 全文（等价公开地址 /m/{slug}.md）","parameters":[{"$ref":"#/components/parameters/slug"},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"翻译语言码（如 en、ja）；缺省为原文"}],"responses":{"200":{"description":"Markdown 文档","content":{"text/markdown":{"schema":{"type":"string"}}}},"403":{"description":"说明书设有访问密码，不对机器开放"},"404":{"description":"不存在或未发布"}}}},"/api/v2/{slug}/search":{"get":{"operationId":"searchManual","summary":"语义检索：按问题返回最相关章节/FAQ 片段（带溯源，无 LLM）","parameters":[{"$ref":"#/components/parameters/slug"},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200},"description":"查询问题"},{"name":"topK","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5}}],"responses":{"200":{"description":"排序后的片段，score 越高越相关；mode=semantic 为向量检索，keyword 为退化匹配","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"string"},"query":{"type":"string"},"mode":{"type":"string","enum":["semantic","keyword"]},"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["section","faq"]},"id":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"score":{"type":"number"},"url":{"type":"string","description":"可引用的权威来源地址"}}}}}}}}},"400":{"description":"q 缺失或超长"},"403":{"description":"说明书设有访问密码"},"404":{"description":"不存在或未发布"},"429":{"description":"限流：30 次/60 秒/IP"}}}},"/api/v2/{slug}/context":{"get":{"operationId":"getManualContext","summary":"RAG 上下文包：预切块的完整客服语料（安全警示/章节/FAQ/故障排查/知识库），带 token 估算与溯源 URL","parameters":[{"$ref":"#/components/parameters/slug"},{"name":"maxTokens","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"token 预算；按 安全警示→章节→FAQ→故障排查→知识库 的顺序贪心装入"},{"name":"types","in":"query","required":false,"schema":{"type":"string"},"description":"逗号分隔的块类型过滤: safety,section,faq,troubleshoot,knowledge,kb-article"}],"responses":{"200":{"description":"上下文块列表","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"string"},"canonical":{"type":"string"},"totalChunks":{"type":"integer"},"totalApproxTokens":{"type":"integer"},"truncated":{"type":"boolean"},"chunks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["safety","section","faq","troubleshoot","knowledge","kb-article"]},"title":{"type":"string"},"text":{"type":"string"},"url":{"type":"string"},"approxTokens":{"type":"integer"}}}}}}}}},"304":{"description":"内容未变化（If-None-Match 命中 ETag）"},"403":{"description":"说明书设有访问密码"},"404":{"description":"不存在或未发布"}}}},"/api/v2/{slug}/chat":{"post":{"operationId":"askManual","summary":"RAG 问答：基于说明书内容回答问题，附引用与置信度","parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":500},"history":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"回答 + 章节引用 + 置信度","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string"},"references":{"type":"array","items":{"type":"string"}},"confidence":{"type":"string"}}}}}},"429":{"description":"限流（30 次/60 秒/IP）或说明书方月度配额用尽"}}}}},"components":{"parameters":{"slug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"说明书标识；全部已发布说明书见 /llms.txt 或 /sitemap.xml"}}}}