{"openapi":"3.1.0","info":{"title":"Prompt Optimizer REST API","version":"1.0.0","description":"### 🚀 AI 提示词结构化优化服务 (Prompt Optimizer API)\n\nPrompt Optimizer API 为开发者提供高可用、多模型的企业级提示词工程与自动化优化能力：\n\n- 🎯 **用户提示词优化 (User Prompt Optimization)**：重构日常需求、提炼核心意图、补充关键上下文与约束。\n- ⚙️ **系统提示词优化 (System Prompt Optimization)**：生成标准角色设定、专业领域规则、工作流结构与行为准则。\n- 🔄 **迭代优化 (Iterative Optimization)**：针对已有提示词，结合反馈需求进行多轮增量演化。\n- ⚡ **测试推理 (Prompt Test)**：在线测试系统提示词与用户提示词的综合表现。\n- 🌊 **全流式支持 (Server-Sent Events / SSE)**：所有优化接口均支持 `stream: true`，实时打字机效果输出。\n- 🔑 **自带 Key (BYOK) 支持**：支持在 HTTP Header 中传递 `X-Api-Key` 或 `Authorization: Bearer <key>`，动态调用任意大模型。\n\n---\n"},"servers":[{"url":"/","description":"当前 API 服务实例"}],"paths":{"/healthz":{"get":{"tags":["系统状态"],"summary":"健康检查","description":"检查 API 服务以及底层的 Core 核心模块与模型就绪状态。","responses":{"200":{"description":"服务正常运行","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/optimize/user":{"post":{"tags":["提示词优化"],"summary":"优化用户提示词 (User Prompt)","description":"对日常提问、代码编写、文本创作或专业任务的用户提示词进行增强，提高清晰度、增加约束并补全缺失背景。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeUserRequest"},"example":{"prompt":"帮我写一篇关于微服务架构演进的技术博客，重点讲讲服务网格和服务治理","template":"user-prompt-professional","stream":false}}}},"responses":{"200":{"description":"优化成功（根据 stream 参数返回 JSON 对象或 text/event-stream 流式事件）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeResponse"}},"text/event-stream":{"schema":{"type":"string","description":"SSE 流式事件，包含 { type: 'chunk', chunk: '...' } 以及 { type: 'done', fullText: '...' }"}}}},"400":{"description":"参数验证失败或未配置模型","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/optimize/system":{"post":{"tags":["提示词优化"],"summary":"优化系统角色提示词 (System Prompt)","description":"针对 AI 助手、专家 Agent、结构化输出等系统角色设定进行专业化设计，提升规范性与抗指令攻击能力。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeSystemRequest"},"example":{"prompt":"你是一个资深前端架构师，精通 Vue3、TypeScript 和前端工程化","template":"general-optimize","stream":false}}}},"responses":{"200":{"description":"优化成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"}}}},"/api/v1/optimize/iterate":{"post":{"tags":["提示词优化"],"summary":"多轮迭代优化提示词 (Iterative Refinement)","description":"在已有提示词的基础上，根据用户的新增补充要求或反馈进行定向修改与优化迭代。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IterateRequest"},"example":{"prompt":"你是一个专业的技术写作助手，请帮我审核和润色技术文档。","requirements":"增加输出结构规范，要求必须包含【修改摘要】、【改进后内容】和【改进理由说明】三个部分，并使用 Markdown 格式。","template":"iterate","stream":false}}}},"responses":{"200":{"description":"迭代优化成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"}}}},"/api/v1/prompt/test":{"post":{"tags":["调试与测试"],"summary":"测试运行提示词 (Test Run)","description":"使用当前配置的 LLM 模型直接测试提示词的实际推理效果。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestPromptRequest"},"example":{"systemPrompt":"You are a concise code reviewer.","userPrompt":"Review this function: function add(a, b) { return a + b; }","stream":false}}}},"responses":{"200":{"description":"运行成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestPromptResponse"}},"text/event-stream":{"schema":{"type":"string"}}}}}}},"/api/v1/templates":{"get":{"tags":["模板资源"],"summary":"获取提示词优化模板列表","description":"查询所有内置及自定义的提示词优化模板，可按类别筛选。","parameters":[{"name":"type","in":"query","required":false,"description":"按模板分类筛选","schema":{"type":"string","enum":["user","system","iterate"]}}],"responses":{"200":{"description":"模板列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateItem"}}}}}}}}}},"/api/v1/models":{"get":{"tags":["模型配置"],"summary":"获取已配置的模型列表","description":"查询服务端当前注册的大模型信息、提供商与默认模型标记。","responses":{"200":{"description":"模型列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ModelItem"}}}}}}}}}}},"components":{"responses":{"ErrorResponse":{"description":"错误响应","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"OptimizeUserRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"待优化的用户提示词","example":"如何使用 Docker 部署一个 Node.js 全栈应用？"},"template":{"type":"string","description":"指定优化模板 ID（可选，参考 /api/v1/templates）","example":"user-prompt-professional"},"stream":{"type":"boolean","description":"是否启用 SSE 流式输出（默认为 false）","default":false},"model":{"type":"string","description":"指定模型 Key（可选）"}}},"OptimizeSystemRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"待优化的系统角色提示词","example":"你是一个专业的 Python 数据分析师，擅长使用 Pandas 和可视化工具。"},"template":{"type":"string","description":"指定优化模板 ID（可选，参考 /api/v1/templates）","example":"general-optimize"},"stream":{"type":"boolean","description":"是否启用 SSE 流式输出","default":false},"model":{"type":"string","description":"指定模型 Key（可选）"}}},"IterateRequest":{"type":"object","required":["prompt","requirements"],"properties":{"prompt":{"type":"string","description":"原始或已有的提示词"},"requirements":{"type":"string","description":"本次迭代的修改意见或具体要求"},"lastOptimizedPrompt":{"type":"string","description":"上一轮优化生成的提示词（如果未提供，默认使用 prompt 字段）"},"template":{"type":"string","description":"指定迭代模板 ID（可选，参考 /api/v1/templates）","example":"iterate"},"stream":{"type":"boolean","description":"是否启用流式输出","default":false},"model":{"type":"string","description":"指定模型 Key（可选）"}}},"TestPromptRequest":{"type":"object","required":["userPrompt"],"properties":{"userPrompt":{"type":"string","description":"用户提示词"},"systemPrompt":{"type":"string","description":"可选的系统提示词"},"stream":{"type":"boolean","default":false},"model":{"type":"string"}}},"OptimizeResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"optimizedPrompt":{"type":"string","description":"优化后的提示词完整内容"},"originalPrompt":{"type":"string","description":"提交的原始提示词"},"templateId":{"type":"string","description":"所使用的模板 ID"},"modelKey":{"type":"string","description":"执行优化的模型 Key"}}}}},"TestPromptResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"response":{"type":"string","description":"模型输出的回复内容"},"modelKey":{"type":"string"}}}}},"TemplateItem":{"type":"object","properties":{"id":{"type":"string","example":"user-clarity-enhancer"},"name":{"type":"string","example":"日常提问清晰度增强"},"category":{"type":"string","enum":["user","system","iterate"],"example":"user"},"description":{"type":"string"},"isBuiltin":{"type":"boolean","example":true}}},"ModelItem":{"type":"object","properties":{"key":{"type":"string","example":"api-default"},"name":{"type":"string","example":"OpenAI GPT-4o"},"provider":{"type":"string","example":"openai"},"modelId":{"type":"string","example":"gpt-4o"},"enabled":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","example":"2026-10-30T02:45:00.000Z"},"service":{"type":"string","example":"prompt-optimizer-api"},"version":{"type":"string","example":"1.0.0"},"hasDefaultModel":{"type":"boolean","example":true}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_PARAMETER"},"message":{"type":"string","example":"Field 'prompt' is required."}}}}}}}}