概述

import xn.ai.platform.XnAiClient;
import xn.ai.platform.XnAiClientFactory;
import xn.ai.platform.responses.*;

// 应用启动时构造一次（Spring @Bean / ServletContextListener / static 字段）
static final XnAiClient client = XnAiClientFactory.create();

// 业务请求中复用
ResponseRequest req = ResponseRequest.builder()
    .agent("research-assistant")
    .input("用 100 字介绍 RAG")
    .mode("thinking")
    .temperature(0.3)
    .build();

Response r = client.responses().create(req);
System.out.println(r.getOutputText());

try (StreamHandle h = client.responses().createStream(req, new StreamCallback() {
    public void onEvent(ResponseStreamEvent ev) {
        if (ev.type() == ResponseStreamEvent.Type.OUTPUT_TEXT_DELTA) {
            System.out.print(ev.delta());
        }
    }
    public void onComplete(Response r)   { /* 流正常结束 */ }
    public void onError(Throwable t)    { t.printStackTrace(); }
})) {
    // close() 阻塞等待后台流任务自然结束
}

<dependency>
  <groupId>com.xnlink</groupId>
  <artifactId>xnai-platform-sdk</artifactId>
  <version>1.0.0-SNAPSHOT</version>
</dependency>

xn.ai.base-url=http://127.0.0.1:2026
xn.ai.engine=deerflow
xn.ai.timeout-seconds=1800
xn.ai.auth.username=admin
xn.ai.auth.password=***

# 必填（enabled=true 时缺任一项则自动降级为关闭）
xn.ai.platform.langfuse.enabled=true
xn.ai.platform.langfuse.endpoint=http://langfuse.internal:3000
xn.ai.platform.langfuse.public-key=pk-lf-***
xn.ai.platform.langfuse.secret-key=sk-lf-***
# 可选（异步上报队列调优，给出的是默认值）
xn.ai.platform.langfuse.queue-capacity=1000
xn.ai.platform.langfuse.batch-size=20
xn.ai.platform.langfuse.flush-interval-ms=2000
# 可选（运维 / 成本，给出的是默认值）
xn.ai.platform.langfuse.release=               # 版本号 → trace.release，便于按版本过滤
xn.ai.platform.langfuse.environment=           # 环境标签(prod/staging/dev) → trace.environment
xn.ai.platform.langfuse.sample-rate=1.0        # 采样率 0..1；<=0 视为 1.0（全采）。关闭观测用 enabled=false
xn.ai.platform.langfuse.request-timeout-ms=10000 # 上报请求独立超时，不复用业务长超时

// -Dxn.ai.tenantA.baseUrl=... -Dxn.ai.tenantA.engine=deerflow ...
// -Dxn.ai.tenantB.baseUrl=... -Dxn.ai.tenantB.engine=dify     ...

XnAiClient a = XnAiClientFactory.create(XnAiConfig.forTenant("tenantA"));
XnAiClient b = XnAiClientFactory.create(XnAiConfig.forTenant("tenantB"));

// client 在 Spring @Bean 中注入，本类持有引用（不要在方法里 new + close）
@Autowired private XnAiClient client;

@PostMapping(value = "/chat/stream", produces = "text/event-stream;charset=UTF-8")
public void chatStream(@RequestBody ChatRequest body,
                       HttpServletResponse response) throws IOException {

    response.setHeader("Cache-Control", "no-cache");
    response.setHeader("X-Accel-Buffering", "no");
    response.flushBuffer();   // 先把响应头刷出，再开始流式写入

    ResponseRequest req = ResponseRequest.builder()
        .agent(body.getAgent())
        .input(body.hasMessages() ? body.getMessages() : body.getInputText())
        .mode(body.getMode())
        .previousResponseId(body.getPrevId())
        .temperature(body.getTemperature())
        .maxOutputTokens(body.getMaxTokens())
        .store(body.getStore())
        .putMetadata("tenantCode", tenantCode)
        .putMetadata("traceId", traceId)
        .build();

    // ✅ 必须 try-with-resources：close() 阻塞等待后台流任务自然结束
    // 若不阻塞，方法立即返回 → Servlet 容器关闭 response → 后台写流时拿到 IOException
    try (StreamHandle h = client.responses().createStreamAsSse(req, response.getOutputStream())) {
        // getResponseId() 同步返回，与后台 SSE 流并发执行，不阻塞输出
        String responseId = h.getResponseId();
        conversationDao.save(body.getUserId(), responseId);  // 落库，供下轮 previousResponseId
    } catch (AuthenticationException e) {
        response.sendError(401, "AI 平台认证失败，请检查凭证");
    } catch (AuthorizationException e) {
        response.sendError(403, "无权访问该 Agent");
    } catch (RateLimitException e) {
        response.setHeader("Retry-After", String.valueOf(e.getRetryAfterSeconds()));
        response.sendError(429, "请求过于频繁，请稍后重试");
    } catch (NetworkException e) {
        response.sendError(504, "AI 平台连接超时");
    } catch (ValidationException e) {
        response.sendError(400, "请求参数有误: " + e.getMessage());
    } catch (AiPlatformException e) {
        response.sendError(502, "AI 平台异常");
    }
}

// ChatRequest DTO，前端可传 inputText 或 messages
static class ChatRequest {
    String agent;
    String inputText;          // 简单文本：.input(String)
    List<Message> messages;    // 多轮/多模态：.input(List<Message>)
    String mode;
    String prevId;
    Double temperature;
    Integer maxTokens;
    Boolean store;
    boolean hasMessages() { return messages != null && !messages.isEmpty(); }
    // getters/setters ...
}

import xn.ai.platform.responses.Message;

// 脚本场景下用 try-with-resources（用完即关）；Web 服务请用单例 client
try (XnAiClient client = XnAiClientFactory.create()) {

    // ① String 输入 — 单轮
    Response r1 = client.responses().create(
        ResponseRequest.builder()
            .agent("pig-farm-agent")
            .input("帮我分析最近一周的养殖数据")   // String
            .mode("thinking")
            .temperature(0.3)
            .topP(0.9)
            .maxOutputTokens(2000)
            .reasoning(Reasoning.of("medium", null))
            .text(TextConfig.of(null, "medium"))
            .parallelToolCalls(true)
            .truncation("auto")
            .store(true)
            .putMetadata("traceId", traceId)
            .build()
    );

    // ② List<Message> 输入 — 多轮自构造
    List<Message> messages = Arrays.asList(
        Message.user("第一个问题"),
        Message.assistant("上一轮的回复..."),
        Message.user("追问：能详细展开第二点吗？")
    );
    Response r2 = client.responses().create(
        ResponseRequest.builder()
            .agent("pig-farm-agent")
            .input(messages)                     // List<Message>
            .mode("pro")
            .build()
    );

} catch (AuthenticationException e) {
    // 通知管理员更新凭证
} catch (RateLimitException e) {
    // 延迟 e.getRetryAfterSeconds() 秒后重试
} catch (NetworkException e) {
    // 重试或降级
} catch (AiPlatformException e) {
    // e.getProviderName(), e.getRequestId(), e.getHttpStatus()
}

// client 为应用级单例（Spring @Bean / static 字段），不要在方法里新建

// ① String 输入 — 必须 try-with-resources 等流自然结束
try (StreamHandle h = client.responses().createStream(
        ResponseRequest.builder()
            .agent("pig-farm-agent")
            .input("帮我分析最近一周的养殖数据")  // String
            .mode("ultra")
            .build(),
        event -> {
            switch (event.type()) {
                case OUTPUT_TEXT_DELTA:
                    sendToFrontend(event.delta());
                    break;
                case RESPONSE_COMPLETED:
                    closeFrontend();
                    break;
                case RESPONSE_FAILED:
                    log.error("流异常: {}", event.response().getError().getMessage());
                    break;
                default:
                    break;
            }
        })) {
    // close() 阻塞等待流任务结束
} catch (AiPlatformException e) {
    log.error("连接失败", e);
}

// ② List<Message> 输入 — 多轮
List<Message> messages = Arrays.asList(
    Message.user("上轮数据有异常波动，帮我分析原因"),
    Message.assistant("波动来自供给端，需求侧平稳。"),
    Message.user("那供给端具体是哪个环节？")
);
try (StreamHandle h = client.responses().createStream(
        ResponseRequest.builder()
            .agent("pig-farm-agent")
            .input(messages)                     // List<Message>
            .mode("pro")
            .build(),
        event -> log.info("{}: {}", event.type(), event.delta()))) {
    // 阻塞至流结束
}

@PostMapping(value = "/chat", produces = "text/event-stream")
public void chat(HttpServletResponse resp, @RequestBody ChatDTO dto) throws IOException {
    resp.setHeader("Cache-Control", "no-cache");
    resp.setHeader("Connection", "keep-alive");
    resp.setHeader("X-Accel-Buffering", "no");   // 关掉 Nginx 缓冲

    ResponseRequest req = ResponseRequest.builder()
        .agent(dto.getAgent())
        .input(dto.getInput())
        .mode(dto.getMode())                 // "flash" / "thinking" / "pro" / "ultra"
        .previousResponseId(dto.getPrevId())
        .build();

    try (StreamHandle h = client.responses().createStreamAsSse(req, resp.getOutputStream())) {
        // 阻塞至流结束 / 取消
    }
}

try (StreamHandle h = client.responses().createStreamAsSse(req, resp.getOutputStream())) {
    String responseId = h.getResponseId();          // 立即返回（含 threadId），与 SSE 流并发
    conversationDao.save(userId, responseId);   // 落库，供下轮 previousResponseId
}

// 对话端点：拿含 runId 的 id 落库
try (StreamHandle h = client.responses().createStreamAsSse(req, resp.getOutputStream())) {
    String responseId = h.awaitResponseId(3000);   // 阻塞至 run_id 就绪，含 runId
    sessionDao.save(sessionId, responseId);     // 供「停止」端点使用
}

// 停止端点（另一个请求）：凭 responseId 服务端取消，跨实例可靠
public void stop(String sessionId) {
    String responseId = sessionDao.get(sessionId);
    client.responses().cancel(responseId);
}

List<Message> msgs = Arrays.asList(
    Message.system("你是一名审计师"),
    Message.user(
        new TextContent("分析这张报表"),
        new InputImageContent("file_abc", null)
    )
);

ResponseRequest req = ResponseRequest.builder()
    .agent("audit")
    .input(msgs)
    .build();

FileObject f = client.files().upload(FileUploadRequest.builder()
    .file(Paths.get("/tmp/report.pdf"))
    .purpose("assistants")
    .agent("doc-qa")
    .build());

System.out.println(f.getId());     // 不透明 ID
System.out.println(f.getBytes());

// 业务后端：取字节转存（大文件流式，避免全载内存）
try (FileDownload dl = client.files().download(fileId)) {
    String name = dl.getFilename();
    String mime = dl.getContentType();      // 可空
    boolean inline = dl.isInline();        // 预览提示：活动内容(html/svg)为 false
    try (InputStream in = dl.getStream()) {
        // 拷贝到本地/对象存储，或直接写入 HTTP 响应回吐前端
    }
}

// 创建热词表
String vocabId = client.audio().createVocabulary(
    VocabularyRequest.builder()
        .name("pig-farm-terms")
        .model("fun-asr")
        .hotwords(Arrays.asList(
            new Hotword("后备母猪", 5),
            new Hotword("死淘率", 4)
        ))
        .build());

// 转写时引用
AudioResponse resp = client.audio().transcribe(
    AudioRequest.builder()
        .fileUrl("https://oss.example.com/audio/query.wav")
        .vocabularyId(vocabId)
        .build());

// 管理热词表
client.audio().listVocabularies();        // 查询全部
client.audio().deleteVocabulary(vocabId);  // 删除

// 在自定义 WebApi/服务的 doService(req, resp) 中（苍穹提供 javax.servlet 风格 req/resp）
public void doChat(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 1) 解析 multipart：文本 + 可选文件（苍穹/Commons-FileUpload 均可，这里示意）
    String message = req.getParameter("message");
    String prevRespId = req.getParameter("previousResponseId"); // 续话可空
    Part filePart = req.getPart("file");                       // 可空

    // 2) 组装对话内容：有文件则内联上传（SDK 自动同 thread）
    List<Content> contents = new ArrayList<>();
    if (filePart != null) {
        contents.add(Content.inputFile(filePart.getInputStream(), filePart.getSubmittedFileName()));
    }
    contents.add(Content.text(message));

    ResponseRequest aiReq = ResponseRequest.builder()
            .agent("doc-qa")
            .input(Arrays.asList(Message.user(contents)))
            .previousResponseId(prevRespId)   // null=新会话
            .mode("pro")
            .build();

    // 3) SSE 直通：SDK 把符合 OpenAI 规范的 SSE 字节写进 resp.getOutputStream()
    resp.setContentType("text/event-stream;charset=UTF-8");
    resp.setHeader("Cache-Control", "no-cache");
    resp.setHeader("X-Accel-Buffering", "no");  // 关闭代理缓冲，保证实时
    client.responses().createStreamAsSse(aiReq, resp.getOutputStream());
}

public void doFile(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    String fileId = req.getParameter("fileId");
    boolean wantPreview = "preview".equals(req.getParameter("mode"));

    try (FileDownload dl = client.files().download(fileId)) {
        // Content-Type
        resp.setContentType(dl.getContentType() != null
                ? dl.getContentType() : "application/octet-stream");
        if (dl.getContentLength() >= 0) {
            resp.setHeader("Content-Length", String.valueOf(dl.getContentLength()));
        }
        // 预览仅对可内联类型生效；活动内容(html/svg)isInline()=false，强制下载防 XSS
        boolean inline = wantPreview && dl.isInline();
        String disposition = (inline ? "inline" : "attachment");
        // 中文文件名用 RFC 5987 filename*，避免乱码
        String enc = URLEncoder.encode(dl.getFilename(), "UTF-8").replace("+", "%20");
        resp.setHeader("Content-Disposition",
                disposition + "; filename*=UTF-8''" + enc);

        // 流式拷贝（不全载内存）
        byte[] buf = new byte[8192];
        int n;
        InputStream in = dl.getStream();
        OutputStream out = resp.getOutputStream();
        while ((n = in.read(buf)) > 0) out.write(buf, 0, n);
        out.flush();
    } catch (ResourceNotFoundException e) {
        resp.sendError(404, "file not found");   // 文件不存在
    }
    // try-with-resources 自动 close FileDownload，释放底层连接
}

FileObject f = client.files().upload(FileUploadRequest.builder()
        .stream(filePart.getInputStream(), filePart.getSubmittedFileName())
        .agent("doc-qa").build());
String fileId = f.getId();  // 可下载、可在后续对话用 Content.inputFile(fileId)+previousResponseId 引用

Assistant a = client.assistants().create(
    AssistantRequest.builder()
        .name("my-agent")
        .instructions("You are a helpful assistant.")
        .build());
// → POST /api/agents  body: {name, soul}
// → 返回 Assistant: id="asst_my-agent", instructions="You are..."

Assistant a = client.assistants().create(
    AssistantRequest.builder()
        .name("pig-farm-expert")
        .description("猪场成本分析专家")
        .instructions("你是资深猪场成本分析专家，基于数据驱动决策。")
        .putMetadata("skills", "pig-farm-cost-analysis,data-analysis,deep-research")
        .build());
// config.yaml 结果:
//   name: pig-farm-expert
//   description: 猪场成本分析专家
//   skills:
//     - pig-farm-cost-analysis
//     - data-analysis
//     - deep-research

AssistantListResponse list = client.assistants().list();
// → GET /api/agents
// → {"object":"list","data":[...],"first_id":"asst_...","last_id":"asst_...","has_more":false}

System.out.println("共 " + list.getData().size() + " 个 Agent");
for (Assistant a : list.getData()) {
    System.out.println(a.getId() + " | " + a.getName()
        + " | instructions="
        + (a.getInstructions() != null
            ? a.getInstructions().substring(0, Math.min(40, a.getInstructions().length()))
            : "null"));
    // skills 透传在 metadata 中
    String skills = a.getMetadata().get("skills");
    if (skills != null) System.out.println("  skills: " + skills);
}

Assistant a = client.assistants().retrieve("asst_my-agent");
// → GET /api/agents/my-agent

System.out.println(a.getId());            // "asst_my-agent"
System.out.println(a.getName());          // "my-agent"
System.out.println(a.getDescription());   // "猪场成本分析专家"
System.out.println(a.getInstructions());  // SOUL.md 内容
System.out.println(a.getMetadata().get("skills")); // "skill-a,skill-b"

// 只改系统提示词，其他不动
Assistant updated = client.assistants().modify(
    "asst_my-agent",
    AssistantRequest.builder()
        .instructions("你是养猪专家，用通俗易懂的中文回答所有问题。")
        .build());
// → PUT /api/agents/my-agent  body: {soul: "你是养猪专家..."}

Assistant updated = client.assistants().modify(
    "asst_my-agent",
    AssistantRequest.builder()
        .description("更新后的描述")
        .instructions("新的系统提示词")
        .build());
// → PUT /api/agents/my-agent  body: {description, soul}

// 安全删除：先尝试删，不存在也不报错
client.assistants().delete("asst_my-agent");
// → DELETE /api/agents/my-agent

// 完整流程：创建 → 使用 → 清理
String testId = "asst_demo-test";
try { client.assistants().delete(testId); } catch (Exception e) {}
Assistant a = client.assistants().create(...);
// ... 测试 ...
client.assistants().delete(testId);

Assistant a = client.assistants().create(
    AssistantRequest.builder()
        .name("cost-analyst")
        .instructions("你是成本分析专家。")
        .putMetadata("skills", "pig-farm-cost-analysis,data-analysis,deep-research")
        .build());
// config.yaml:
//   skills:
//     - pig-farm-cost-analysis
//     - data-analysis
//     - deep-research

// 更新 skills 列表
client.assistants().modify("asst_cost-analyst",
    AssistantRequest.builder()
        .putMetadata("skills", "xn-api,pig-farm-metrics")
        .build());

// 清空 skills
client.assistants().modify("asst_cost-analyst",
    AssistantRequest.builder()
        .putMetadata("skills", "")
        .build());

Assistant a = client.assistants().retrieve("asst_cost-analyst");
String skills = a.getMetadata().get("skills");
// → "xn-api,pig-farm-metrics"（或 null 表示后端未返回）

RESPONSE_CREATED
RESPONSE_IN_PROGRESS
OUTPUT_ITEM_ADDED                  ← 工具调用 item 开始
FUNCTION_CALL_ARGUMENTS_DELTA × N
FUNCTION_CALL_ARGUMENTS_DONE       ← 在此执行实际工具
OUTPUT_ITEM_DONE
OUTPUT_ITEM_ADDED                  ← 文本 item 开始
CONTENT_PART_ADDED
OUTPUT_TEXT_DELTA × N
OUTPUT_TEXT_DONE
CONTENT_PART_DONE
OUTPUT_ITEM_DONE
RESPONSE_COMPLETED

try {
    Response r = client.responses().create(req);
} catch (RateLimitException e) {
    Thread.sleep(e.getRetryAfterSeconds() * 1000L);
} catch (AuthenticationException e) {
    client.refreshAuth();
} catch (AiPlatformException e) {
    log.error("AI 调用失败 code={}", e.getCode(), e);
}