增加与ai大模型对话

huimv-employment/fe-api/src/main/resources/application.yml

@@ -48,6 +48,13 @@ fe:
     port: 9107
     api-key: ${FE_KB_API_KEY:}
     default-model: default
+    default-knowledge-base: default
+    file-url-base: ""
+    upload-path: ${FE_KB_UPLOAD_PATH:}
+    url-rewrite-from-host: ""
+    url-rewrite-to-host: ""
     connect-timeout-ms: 15000
     read-timeout-ms: 120000
     stream-read-timeout-ms: 300000
+    max-retries: 2
+    retry-interval-ms: 500

huimv-employment/fe-common/src/main/java/com/huimv/employment/common/exception/ErrorCode.java

@@ -57,6 +57,12 @@ public enum ErrorCode {
     /** AI：调用上游大模型失败 */
     AI_SERVICE_FAILED(50003, "AI 服务调用失败，请稍后再试"),
 
+    /** 知识库：远程服务已关闭 */
+    KB_SERVICE_DISABLED(50302, "知识库服务未启用"),
+
+    /** 知识库：调用上游失败 */
+    KB_SERVICE_FAILED(50004, "知识库服务调用失败，请稍后再试"),
+
     /** 通用：未预期的系统异常 */
     INTERNAL_ERROR(500, "系统繁忙，请稍后再试");
 

huimv-employment/fe-integration/src/main/java/com/huimv/employment/integration/kb/KbApiProperties.java

@@ -3,7 +3,7 @@ package com.huimv.employment.integration.kb;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 
 /**
- * 大模型网关 HTTP 对接（OpenAI 兼容 {@code /v1/models}、{@code /v1/chat/completions}），绑定 {@code fe.kb.*}。
+ * 大模型网关 HTTP 对接（知识库 {@code /api/v1/kb/**}、对话 {@code /v1/models}、{@code /v1/chat/completions}），绑定 {@code fe.kb.*}。
  */
 @ConfigurationProperties(prefix = "fe.kb")
 public class KbApiProperties {
@@ -22,9 +22,31 @@ public class KbApiProperties {
 
     private String authHeaderName = "Authorization";
 
+    /**
+     * 当业务表 {@code content_file_url} 不是 http(s) 开头时，与其拼接成知识库可拉取的完整 URL。
+     */
+    private String fileUrlBase = "";
+
+    /** 方式一上传默认知识库标识 */
+    private String defaultKnowledgeBase = "default";
+
     /** agent/messages 等非透传场景默认模型 */
     private String defaultModel = "default";
 
+    /**
+     * Markdown 模板与生成文件根目录（对应若依 ruoyi.profile）。
+     * 为空时 {@link KbMarkdownGenerator} 不可用。
+     */
+    private String uploadPath = "";
+
+    /**
+     * 可选：正文 URL 含此外网域名时，改写为 {@link #urlRewriteToHost} 供知识库节点内网拉取。
+     */
+    private String urlRewriteFromHost = "";
+
+    /** 可选：URL 改写目标 host（含端口，如 192.168.1.1:443） */
+    private String urlRewriteToHost = "";
+
     private int connectTimeoutMs = 15000;
 
     private int readTimeoutMs = 120000;
@@ -32,6 +54,12 @@ public class KbApiProperties {
     /** 对话流式 SSE（stream=true）读超时 */
     private int streamReadTimeoutMs = 300000;
 
+    /** 知识库同步/移出失败或超时时的最大重试次数（不含首次请求） */
+    private int maxRetries = 2;
+
+    /** 重试间隔（毫秒） */
+    private int retryIntervalMs = 500;
+
     public boolean isEnabled() {
         return enabled;
     }
@@ -80,6 +108,22 @@ public class KbApiProperties {
         this.authHeaderName = authHeaderName;
     }
 
+    public String getFileUrlBase() {
+        return fileUrlBase;
+    }
+
+    public void setFileUrlBase(String fileUrlBase) {
+        this.fileUrlBase = fileUrlBase;
+    }
+
+    public String getDefaultKnowledgeBase() {
+        return defaultKnowledgeBase;
+    }
+
+    public void setDefaultKnowledgeBase(String defaultKnowledgeBase) {
+        this.defaultKnowledgeBase = defaultKnowledgeBase;
+    }
+
     public String getDefaultModel() {
         return defaultModel;
     }
@@ -88,6 +132,30 @@ public class KbApiProperties {
         this.defaultModel = defaultModel;
     }
 
+    public String getUploadPath() {
+        return uploadPath;
+    }
+
+    public void setUploadPath(String uploadPath) {
+        this.uploadPath = uploadPath;
+    }
+
+    public String getUrlRewriteFromHost() {
+        return urlRewriteFromHost;
+    }
+
+    public void setUrlRewriteFromHost(String urlRewriteFromHost) {
+        this.urlRewriteFromHost = urlRewriteFromHost;
+    }
+
+    public String getUrlRewriteToHost() {
+        return urlRewriteToHost;
+    }
+
+    public void setUrlRewriteToHost(String urlRewriteToHost) {
+        this.urlRewriteToHost = urlRewriteToHost;
+    }
+
     public int getConnectTimeoutMs() {
         return connectTimeoutMs;
     }
@@ -112,6 +180,22 @@ public class KbApiProperties {
         this.streamReadTimeoutMs = streamReadTimeoutMs;
     }
 
+    public int getMaxRetries() {
+        return maxRetries;
+    }
+
+    public void setMaxRetries(int maxRetries) {
+        this.maxRetries = maxRetries;
+    }
+
+    public int getRetryIntervalMs() {
+        return retryIntervalMs;
+    }
+
+    public void setRetryIntervalMs(int retryIntervalMs) {
+        this.retryIntervalMs = retryIntervalMs;
+    }
+
     /** 请求头鉴权值，默认 {@code Bearer {apiKey}}。 */
     public String authHeaderValue() {
         if (apiKey == null || apiKey.isEmpty()) {

huimv-employment/fe-integration/src/main/java/com/huimv/employment/integration/kb/KbFileUrlResolver.java

@@ -0,0 +1,84 @@
+package com.huimv.employment.integration.kb;
+
+import com.huimv.employment.common.exception.BizException;
+import com.huimv.employment.common.exception.ErrorCode;
+import org.springframework.util.StringUtils;
+
+import java.net.URI;
+import java.net.URISyntaxException;
+
+/**
+ * 将业务表中的 {@code content_file_url} 解析为知识库「按 URL 拉取」接口所需的完整地址。
+ */
+public final class KbFileUrlResolver {
+
+    private KbFileUrlResolver() {
+    }
+
+    /**
+     * @param contentFileUrl 表字段 content_file_url
+     * @param properties     {@code fe.kb} 配置（file-url-base、可选 URL 改写）
+     */
+    public static String resolveForKbUpload(String contentFileUrl, KbApiProperties properties) {
+        if (!StringUtils.hasText(contentFileUrl)) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "正文访问地址为空，无法同步知识库");
+        }
+        String fileUrlBase = properties != null ? properties.getFileUrlBase() : "";
+        String p = contentFileUrl.trim();
+        if (startsWithHttp(p)) {
+            return rewriteHostIfConfigured(contentFileUrl, p, properties);
+        }
+        if (!StringUtils.hasText(fileUrlBase)) {
+            throw new BizException(ErrorCode.BAD_REQUEST,
+                    "正文访问地址不是完整 http(s) 地址时，请在配置中设置 fe.kb.file-url-base");
+        }
+        String base = fileUrlBase.trim();
+        while (base.endsWith("/")) {
+            base = base.substring(0, base.length() - 1);
+        }
+        String path = p.startsWith("/") ? p : "/" + p;
+        return rewriteHostIfConfigured(contentFileUrl, base + path, properties);
+    }
+
+    private static boolean startsWithHttp(String url) {
+        return url.regionMatches(true, 0, "http://", 0, 7)
+                || url.regionMatches(true, 0, "https://", 0, 8);
+    }
+
+    /**
+     * 正文 URL 含配置的外网域名时，将解析结果中的域名替换为内网地址，便于知识库节点拉取文件。
+     */
+    static String rewriteHostIfConfigured(String contentFileUrl, String resolvedUrl, KbApiProperties properties) {
+        if (!StringUtils.hasText(contentFileUrl) || !StringUtils.hasText(resolvedUrl) || properties == null) {
+            return resolvedUrl;
+        }
+        String fromHost = properties.getUrlRewriteFromHost();
+        String toHost = properties.getUrlRewriteToHost();
+        if (!StringUtils.hasText(fromHost) || !StringUtils.hasText(toHost)) {
+            return resolvedUrl;
+        }
+        if (!contentFileUrl.contains(fromHost)) {
+            return resolvedUrl;
+        }
+        try {
+            URI uri = new URI(resolvedUrl);
+            if (uri.getHost() == null || !fromHost.equalsIgnoreCase(uri.getHost())) {
+                return resolvedUrl;
+            }
+            StringBuilder sb = new StringBuilder();
+            sb.append(uri.getScheme()).append("://").append(toHost);
+            if (uri.getRawPath() != null) {
+                sb.append(uri.getRawPath());
+            }
+            if (uri.getRawQuery() != null) {
+                sb.append('?').append(uri.getRawQuery());
+            }
+            if (uri.getRawFragment() != null) {
+                sb.append('#').append(uri.getRawFragment());
+            }
+            return sb.toString();
+        } catch (URISyntaxException e) {
+            return resolvedUrl;
+        }
+    }
+}

huimv-employment/fe-integration/src/main/java/com/huimv/employment/integration/kb/KbMarkdownGenerator.java

@@ -0,0 +1,128 @@
+package com.huimv.employment.integration.kb;
+
+import com.huimv.employment.common.exception.BizException;
+import com.huimv.employment.common.exception.ErrorCode;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.stereotype.Component;
+import org.springframework.util.StringUtils;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.StandardCopyOption;
+import java.util.Map;
+
+/**
+ * 基于模板占位符生成 Markdown 文件（输出至 {@code fe.kb.upload-path/template} 目录）。
+ */
+@Component
+public class KbMarkdownGenerator {
+
+    /** 相对 upload-path 的模板目录名 */
+    public static final String TEMPLATE_DIR = "template";
+
+    /** classpath 内置模板目录，部署时可复制到上传目录 */
+    public static final String CLASSPATH_TEMPLATE_PREFIX = "kb-template/";
+
+    private final KbApiProperties properties;
+
+    public KbMarkdownGenerator(KbApiProperties properties) {
+        this.properties = properties;
+    }
+
+    /**
+     * 从模板生成 Markdown 文件。
+     *
+     * @param templateFileName 模板文件名
+     * @param outputFileName   输出文件名
+     * @param placeholders     占位符键名不含花括号，如 {@code drugName} → {@code {drugName}}
+     * @return 生成文件的绝对路径
+     */
+    public Path generateFromTemplate(String templateFileName, String outputFileName, Map<String, String> placeholders) {
+        if (!StringUtils.hasText(templateFileName)) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "Markdown 模板文件名为空");
+        }
+        if (!StringUtils.hasText(outputFileName)) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "Markdown 输出文件名为空");
+        }
+        Path templatePath;
+        try {
+            templatePath = resolveTemplatePath(templateFileName);
+        } catch (IOException e) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED, "准备 Markdown 模板失败：" + e.getMessage());
+        }
+        String content;
+        try {
+            content = new String(Files.readAllBytes(templatePath), StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED,
+                    "读取 Markdown 模板失败：" + templatePath + "，" + e.getMessage());
+        }
+        content = applyPlaceholders(content, placeholders);
+        Path outputDir = templateDirectory();
+        try {
+            Files.createDirectories(outputDir);
+            Path output = outputDir.resolve(outputFileName);
+            Files.write(output, content.getBytes(StandardCharsets.UTF_8));
+            return output;
+        } catch (IOException e) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED, "写入 Markdown 文件失败：" + e.getMessage());
+        }
+    }
+
+    public Path templateDirectory() {
+        String profile = properties.getUploadPath();
+        if (!StringUtils.hasText(profile)) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "未配置 fe.kb.upload-path，无法生成知识库 Markdown 文件");
+        }
+        return Paths.get(profile, TEMPLATE_DIR);
+    }
+
+    /** 删除临时 Markdown（忽略不存在）。 */
+    public void deleteQuietly(Path path) {
+        if (path == null) {
+            return;
+        }
+        try {
+            Files.deleteIfExists(path);
+        } catch (IOException ignored) {
+            // 清理失败不阻断主流程
+        }
+    }
+
+    private Path resolveTemplatePath(String templateFileName) throws IOException {
+        Path inProfile = templateDirectory().resolve(templateFileName);
+        if (Files.isRegularFile(inProfile)) {
+            return inProfile;
+        }
+        ClassPathResource resource = new ClassPathResource(CLASSPATH_TEMPLATE_PREFIX + templateFileName);
+        if (!resource.exists()) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "未找到 Markdown 模板：" + templateFileName
+                    + "（请置于 " + inProfile + " 或 classpath:" + CLASSPATH_TEMPLATE_PREFIX + templateFileName + "）");
+        }
+        Files.createDirectories(templateDirectory());
+        try (InputStream in = resource.getInputStream()) {
+            Files.copy(in, inProfile, StandardCopyOption.REPLACE_EXISTING);
+        }
+        return inProfile;
+    }
+
+    private static String applyPlaceholders(String template, Map<String, String> placeholders) {
+        if (placeholders == null || placeholders.isEmpty()) {
+            return template;
+        }
+        String result = template;
+        for (Map.Entry<String, String> entry : placeholders.entrySet()) {
+            String key = entry.getKey();
+            if (!StringUtils.hasText(key)) {
+                continue;
+            }
+            String value = entry.getValue() != null ? entry.getValue() : "";
+            result = result.replace("{" + key + "}", value);
+        }
+        return result;
+    }
+}

huimv-employment/fe-integration/src/main/java/com/huimv/employment/integration/kb/KnowledgeBaseClient.java

@@ -0,0 +1,37 @@
+package com.huimv.employment.integration.kb;
+
+import java.io.File;
+
+/**
+ * 与大模型知识库后台的 HTTP 交互（上传文档、删除文档等），供各业务模块复用。
+ */
+public interface KnowledgeBaseClient {
+
+    /**
+     * 方式一：multipart/form-data 上传本地文件入库。
+     *
+     * @param file           本地文件
+     * @param uploadFilename multipart 中 file 部分的文件名
+     * @param knowledgeBase  知识库标识，默认 {@code default}
+     * @param category       分类
+     * @return 知识库返回的 file_id
+     */
+    String uploadFile(File file, String uploadFilename, String knowledgeBase, String category);
+
+    /**
+     * 方式二：multipart/form-data 提交 url、category、description 上传文件入库。
+     *
+     * @param fileUrl     知识库可 HTTP 拉取的正文地址
+     * @param category    分类
+     * @param description 描述
+     * @return 知识库返回的 file_id
+     */
+    String uploadFileByUrl(String fileUrl, String category, String description);
+
+    /**
+     * 按知识库文档 id 移出条目。
+     *
+     * @param kbDocId {@code /api/v1/kb/files/{id}} 中的 id
+     */
+    void deleteFile(String kbDocId);
+}

huimv-employment/fe-integration/src/main/java/com/huimv/employment/integration/kb/KnowledgeBaseClientImpl.java

@@ -0,0 +1,331 @@
+package com.huimv.employment.integration.kb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.huimv.employment.common.exception.BizException;
+import com.huimv.employment.common.exception.ErrorCode;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.core.io.FileSystemResource;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Service;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+import org.springframework.util.StringUtils;
+import org.springframework.web.client.HttpStatusCodeException;
+import org.springframework.web.client.ResourceAccessException;
+import org.springframework.web.client.RestTemplate;
+
+import java.io.File;
+import java.io.UnsupportedEncodingException;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.function.Supplier;
+
+/**
+ * 调用大模型知识库开放 API（multipart 上传 / 删除文件等）。
+ */
+@Service
+public class KnowledgeBaseClientImpl implements KnowledgeBaseClient {
+
+    private static final Logger log = LoggerFactory.getLogger(KnowledgeBaseClientImpl.class);
+
+    private static final String[] FILE_ID_KEYS = { "file_id", "fileId", "kbDocId", "kb_doc_id", "docId", "id" };
+
+    private final KbApiProperties properties;
+    private final RestTemplate restTemplate;
+    private final ObjectMapper objectMapper;
+
+    public KnowledgeBaseClientImpl(KbApiProperties properties,
+                                   @Qualifier("kbRestTemplate") RestTemplate restTemplate,
+                                   ObjectMapper objectMapper) {
+        this.properties = properties;
+        this.restTemplate = restTemplate;
+        this.objectMapper = objectMapper;
+    }
+
+    @Override
+    public String uploadFile(File file, String uploadFilename, String knowledgeBase, String category) {
+        ensureReady();
+        if (file == null || !file.isFile()) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "上传文件无效或不存在");
+        }
+        String kb = StringUtils.hasText(knowledgeBase) ? knowledgeBase.trim() : properties.getDefaultKnowledgeBase();
+        if (!StringUtils.hasText(kb)) {
+            kb = "default";
+        }
+        String name = StringUtils.hasText(uploadFilename) ? uploadFilename.trim() : file.getName();
+
+        MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
+        body.add("knowledge_base", kb);
+        body.add("category", category);
+        body.add("file", multipartFileResource(file, name));
+
+        return postMultipart(body);
+    }
+
+    @Override
+    public String uploadFileByUrl(String fileUrl, String category, String description) {
+        ensureReady();
+        MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
+        body.add("url", fileUrl);
+        body.add("category", category);
+        body.add("description", description);
+        return postMultipart(body);
+    }
+
+    private String postMultipart(MultiValueMap<String, Object> body) {
+        String url = properties.baseUrl() + "/api/v1/kb/files";
+        HttpHeaders headers = new HttpHeaders();
+        headers.add(properties.getAuthHeaderName(), properties.authHeaderValue());
+        HttpEntity<MultiValueMap<String, Object>> entity = new HttpEntity<>(body, headers);
+        String raw = executeWithRetry("知识库上传", () -> {
+            try {
+                ResponseEntity<String> resp = restTemplate.exchange(URI.create(url), HttpMethod.POST, entity, String.class);
+                return resp.getBody();
+            } catch (HttpStatusCodeException e) {
+                String b = e.getResponseBodyAsString(StandardCharsets.UTF_8);
+                throw new BizException(ErrorCode.KB_SERVICE_FAILED,
+                        "知识库上传失败 HTTP " + e.getRawStatusCode() + "：" + abbreviate(b));
+            }
+        });
+        return parseUploadResponse(raw);
+    }
+
+    private static FileSystemResource multipartFileResource(File file, String uploadName) {
+        return new FileSystemResource(file) {
+            @Override
+            public String getFilename() {
+                return uploadName;
+            }
+        };
+    }
+
+    @Override
+    public void deleteFile(String kbDocId) {
+        ensureReady();
+        if (!StringUtils.hasText(kbDocId)) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "知识库文档 id 为空");
+        }
+        String url = properties.baseUrl() + "/api/v1/kb/files/" + encodePathSegment(kbDocId);
+        HttpHeaders headers = new HttpHeaders();
+        headers.add(properties.getAuthHeaderName(), properties.authHeaderValue());
+        HttpEntity<Void> entity = new HttpEntity<>(headers);
+        executeWithRetry("知识库删除", () -> {
+            try {
+                ResponseEntity<String> resp = restTemplate.exchange(URI.create(url), HttpMethod.DELETE, entity, String.class);
+                if (!resp.getStatusCode().is2xxSuccessful()) {
+                    throw new BizException(ErrorCode.KB_SERVICE_FAILED,
+                            "知识库删除失败 HTTP " + resp.getStatusCode().value());
+                }
+                return null;
+            } catch (HttpStatusCodeException e) {
+                if (e.getRawStatusCode() == 404) {
+                    return null;
+                }
+                String b = e.getResponseBodyAsString(StandardCharsets.UTF_8);
+                throw new BizException(ErrorCode.KB_SERVICE_FAILED,
+                        "知识库删除失败 HTTP " + e.getRawStatusCode() + "：" + abbreviate(b));
+            }
+        });
+    }
+
+    private <T> T executeWithRetry(String operation, Supplier<T> action) {
+        int maxRetries = Math.max(0, properties.getMaxRetries());
+        BizException last = null;
+        for (int attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return action.get();
+            } catch (BizException e) {
+                if (attempt >= maxRetries || !isRetryable(e)) {
+                    throw e;
+                }
+                last = e;
+                log.warn("{}失败，第 {}/{} 次重试：{}", operation, attempt + 1, maxRetries, e.getMessage());
+                sleepBeforeRetry();
+            } catch (Exception e) {
+                BizException wrapped = wrapUnexpected(operation, e);
+                if (attempt >= maxRetries || !isRetryable(wrapped, e)) {
+                    throw wrapped;
+                }
+                last = wrapped;
+                log.warn("{}异常，第 {}/{} 次重试：{}", operation, attempt + 1, maxRetries, e.getMessage());
+                sleepBeforeRetry();
+            }
+        }
+        if (last != null) {
+            throw last;
+        }
+        throw new BizException(ErrorCode.KB_SERVICE_FAILED, operation + "失败");
+    }
+
+    private static boolean isRetryable(BizException e) {
+        String msg = e.getMessage();
+        if (msg == null) {
+            return false;
+        }
+        if (msg.contains("HTTP 404")) {
+            return false;
+        }
+        if (msg.contains("HTTP 408") || msg.contains("HTTP 429")) {
+            return true;
+        }
+        if (msg.matches(".*HTTP [45]\\d\\d.*")) {
+            int code = extractHttpStatus(msg);
+            return code >= 500 || code == 408 || code == 429;
+        }
+        return false;
+    }
+
+    private static boolean isRetryable(BizException wrapped, Exception cause) {
+        if (cause instanceof ResourceAccessException) {
+            return true;
+        }
+        return isRetryable(wrapped);
+    }
+
+    private static int extractHttpStatus(String msg) {
+        int idx = msg.indexOf("HTTP ");
+        if (idx < 0) {
+            return 0;
+        }
+        int start = idx + 5;
+        int end = start;
+        while (end < msg.length() && Character.isDigit(msg.charAt(end))) {
+            end++;
+        }
+        if (end == start) {
+            return 0;
+        }
+        try {
+            return Integer.parseInt(msg.substring(start, end));
+        } catch (NumberFormatException e) {
+            return 0;
+        }
+    }
+
+    private void sleepBeforeRetry() {
+        int interval = Math.max(0, properties.getRetryIntervalMs());
+        if (interval <= 0) {
+            return;
+        }
+        try {
+            Thread.sleep(interval);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    }
+
+    private static BizException wrapUnexpected(String operation, Exception e) {
+        if (e instanceof BizException) {
+            return (BizException) e;
+        }
+        return new BizException(ErrorCode.KB_SERVICE_FAILED, operation + "异常：" + e.getMessage());
+    }
+
+    private static String encodePathSegment(String id) {
+        try {
+            return URLEncoder.encode(id, StandardCharsets.UTF_8.name()).replace("+", "%20");
+        } catch (UnsupportedEncodingException e) {
+            return id;
+        }
+    }
+
+    private String parseUploadResponse(String raw) {
+        if (!StringUtils.hasText(raw)) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED, "知识库上传返回空响应");
+        }
+        JsonNode root;
+        try {
+            root = objectMapper.readTree(raw);
+        } catch (Exception e) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED, "知识库上传响应非 JSON：" + abbreviate(raw));
+        }
+        assertBusinessOk(root);
+        String fileId = extractFileId(root);
+        if (!StringUtils.hasText(fileId)) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED,
+                    "知识库上传成功但未解析到 file_id，响应：" + abbreviate(raw));
+        }
+        return fileId;
+    }
+
+    private void assertBusinessOk(JsonNode root) {
+        if (root == null || !root.has("code")) {
+            return;
+        }
+        JsonNode c = root.get("code");
+        boolean ok = false;
+        if (c.isNumber()) {
+            int v = c.intValue();
+            ok = (v == 0 || v == 200);
+        } else if (c.isTextual()) {
+            String s = c.asText();
+            ok = "0".equals(s) || "200".equals(s) || "success".equalsIgnoreCase(s);
+        }
+        if (!ok) {
+            String msg = root.has("message") ? root.get("message").asText(null) : null;
+            if (!StringUtils.hasText(msg) && root.has("msg")) {
+                msg = root.get("msg").asText(null);
+            }
+            if (!StringUtils.hasText(msg)) {
+                msg = "知识库接口返回失败";
+            }
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED, msg);
+        }
+    }
+
+    private static String extractFileId(JsonNode root) {
+        JsonNode data = root.get("data");
+        if (data != null && data.isTextual()) {
+            String t = data.asText(null);
+            if (StringUtils.hasText(t)) {
+                return t;
+            }
+        }
+        if (data != null && data.isObject()) {
+            for (String key : FILE_ID_KEYS) {
+                if (data.has(key) && !data.get(key).isNull()) {
+                    String v = data.get(key).asText(null);
+                    if (StringUtils.hasText(v)) {
+                        return v;
+                    }
+                }
+            }
+        }
+        for (String key : FILE_ID_KEYS) {
+            if (root.has(key) && !root.get(key).isNull()) {
+                String v = root.get(key).asText(null);
+                if (StringUtils.hasText(v)) {
+                    return v;
+                }
+            }
+        }
+        return null;
+    }
+
+    private static String abbreviate(String s) {
+        if (s == null) {
+            return "";
+        }
+        String t = s.trim();
+        if (t.length() > 500) {
+            return t.substring(0, 500) + "...";
+        }
+        return t;
+    }
+
+    private void ensureReady() {
+        if (!properties.isEnabled()) {
+            throw new BizException(ErrorCode.KB_SERVICE_DISABLED);
+        }
+        if (!StringUtils.hasText(properties.getApiKey())) {
+            throw new BizException(ErrorCode.KB_SERVICE_FAILED, "未配置知识库访问密钥 fe.kb.api-key");
+        }
+    }
+}