a

docs/api_expert_generate_3_open.md

@@ -0,0 +1,108 @@
+# 智能提示词优化3号专家 - 对外接口文档
+
+供 Android 等外部应用调用的 REST API。
+
+## 接口地址
+
+```
+POST http://101.43.95.130:5002/api/open/expert-generate-3
+```
+
+## 请求
+
+- **Method**: POST
+- **Content-Type**: application/json
+
+### 请求体参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| input_text | string | 是 | 用户需求描述 |
+| temperature | number | 否 | 生成随机性，0-2，默认 0.7 |
+| max_tokens | int | 否 | 最大生成 token 数，100-4000，默认 1000 |
+| timeout | int | 否 | 超时时间（秒），10-300，默认 60 |
+| uid | int | 否 | 用户ID，用于历史记录归属，不传则使用默认用户 |
+
+### 示例
+
+```json
+{
+  "input_text": "android内存溢出分析",
+  "temperature": 0.7,
+  "max_tokens": 1000,
+  "timeout": 60,
+  "uid": 1
+}
+```
+
+## 响应
+
+### 成功 (code=200)
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "intent_analysis": {
+      "core_intent": "技术",
+      "domain": "xxx",
+      "key_requirements": ["..."],
+      "expected_output": "...",
+      "constraints": ["..."]
+    },
+    "generated_prompt": "生成的完整提示词文本"
+  }
+}
+```
+
+### 失败
+
+```json
+{
+  "code": 400,
+  "message": "错误描述",
+  "data": null
+}
+```
+
+常见 code：400 参数错误，429 重复提交，500 服务器错误。
+
+## Android 调用示例 (Kotlin + Retrofit)
+
+```kotlin
+// 请求体
+data class ExpertGenerate3Request(
+    val input_text: String,
+    val temperature: Float? = 0.7f,
+    val max_tokens: Int? = 1000,
+    val timeout: Int? = 60,
+    val uid: Int? = null
+)
+
+// 响应体
+data class ExpertGenerate3Response(
+    val code: Int,
+    val message: String,
+    val data: Data?
+)
+data class Data(
+    val intent_analysis: IntentAnalysis,
+    val generated_prompt: String
+)
+
+// 使用
+val api = Retrofit.Builder()
+    .baseUrl("http://101.43.95.130:5002/")
+    .addConverterFactory(GsonConverterFactory.create())
+    .build()
+    .create(YourApi::class.java)
+
+api.expertGenerate3(ExpertGenerate3Request(input_text = "android内存溢出分析"))
+```
+
+## 注意事项
+
+- 项目已启用 CORS，支持跨域调用
+- 对外接口不做 8 秒内重复提交校验，由客户端自行控制
+- 建议在客户端增加防重复点击、超时重试等逻辑