feat: 支持工作流多知识库向量检索

- 统一单选多选输出与结构化暂停参数

- 增加严格恢复校验及并发状态保护

- 补充确认节点契约与恢复测试

easy-agents-core/src/main/java/com/easyagents/core/store/StoreOptions.java

@@ -43,6 +43,11 @@ public class StoreOptions extends Metadata {
         public void setEmbeddingOptions(EmbeddingOptions embeddingOptions) {
             throw new IllegalStateException("Can not set embeddingOptions to the default instance.");
         }
+
+        @Override
+        public void setTimeoutMillis(Long timeoutMillis) {
+            throw new IllegalStateException("Can not set timeoutMillis to the default instance.");
+        }
     };
 
     /**
@@ -65,6 +70,11 @@ public class StoreOptions extends Metadata {
      */
     private EmbeddingOptions embeddingOptions = EmbeddingOptions.DEFAULT;
 
+    /**
+     * Optional upper bound for one store operation.
+     */
+    private Long timeoutMillis;
+
 
     public String getCollectionName() {
         return collectionName;
@@ -111,6 +121,17 @@ public class StoreOptions extends Metadata {
         this.embeddingOptions = embeddingOptions;
     }
 
+    public Long getTimeoutMillis() {
+        return timeoutMillis;
+    }
+
+    public void setTimeoutMillis(Long timeoutMillis) {
+        if (timeoutMillis != null && timeoutMillis <= 0L) {
+            throw new IllegalArgumentException("timeoutMillis must be greater than zero");
+        }
+        this.timeoutMillis = timeoutMillis;
+    }
+
 
     public static StoreOptions ofCollectionName(String collectionName) {
         StoreOptions storeOptions = new StoreOptions();

easy-agents-core/src/main/java/com/easyagents/core/store/StoreTimeoutException.java

@@ -0,0 +1,21 @@
+/*
+ *  Copyright (c) 2023-2026, Easy-Agents (fuhai999@gmail.com).
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ */
+package com.easyagents.core.store;
+
+/**
+ * Indicates that a store operation exhausted its caller-provided time budget.
+ */
+public class StoreTimeoutException extends RuntimeException {
+
+    public StoreTimeoutException(String message) {
+        super(message);
+    }
+
+    public StoreTimeoutException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

easy-agents-document/easy-agents-document-core/src/main/java/com/easyagents/document/core/async/DocumentAsyncTaskManager.java

@@ -2,6 +2,7 @@ package com.easyagents.document.core.async;
 
 import com.easyagents.core.util.StringUtil;
 import com.easyagents.document.core.exception.DocumentParseException;
+import com.easyagents.document.core.exception.DocumentAsyncTaskNotFoundException;
 import com.easyagents.document.core.entity.ParseResponse;
 import com.easyagents.document.core.entity.ParseTaskInfo;
 import com.easyagents.document.core.entity.ParseTaskStatus;
@@ -135,7 +136,7 @@ public class DocumentAsyncTaskManager {
         }
         DocumentAsyncTaskRecord record = repository.find(taskId);
         if (record == null) {
-            throw new DocumentParseException("Document async task not found: " + taskId);
+            throw new DocumentAsyncTaskNotFoundException(taskId);
         }
         return record;
     }

easy-agents-document/easy-agents-document-core/src/main/java/com/easyagents/document/core/exception/DocumentAsyncTaskNotFoundException.java

@@ -0,0 +1,29 @@
+package com.easyagents.document.core.exception;
+
+/**
+ * 进程内异步文档任务不存在。
+ *
+ * <p>本地 Office 解析任务允许使用内存仓库；进程重启后，调用方可以
+ * 通过该异常识别执行实例已经丢失，并从持久化业务任务重新提交。</p>
+ *
+ * @author Codex
+ * @since 2026-09-02
+ */
+public class DocumentAsyncTaskNotFoundException extends DocumentParseException {
+
+    private final String taskId;
+
+    public DocumentAsyncTaskNotFoundException(String taskId) {
+        super("Document async task not found: " + taskId);
+        this.taskId = taskId;
+    }
+
+    /**
+     * 获取已丢失的任务 ID。
+     *
+     * @return 任务 ID
+     */
+    public String getTaskId() {
+        return taskId;
+    }
+}

easy-agents-document/easy-agents-document-core/src/test/java/com/easyagents/document/core/async/DocumentAsyncTaskManagerTest.java

@@ -4,6 +4,7 @@ import com.easyagents.document.core.entity.ParseResponse;
 import com.easyagents.document.core.entity.ParseResult;
 import com.easyagents.document.core.entity.ParseTaskInfo;
 import com.easyagents.document.core.entity.ParseTaskStatus;
+import com.easyagents.document.core.exception.DocumentAsyncTaskNotFoundException;
 import org.junit.Assert;
 import org.junit.Test;
 
@@ -18,6 +19,21 @@ import java.util.concurrent.Executor;
  */
 public class DocumentAsyncTaskManagerTest {
 
+    @Test
+    public void shouldExposeMissingInMemoryTaskAsRecoverableSignal() {
+        DocumentAsyncTaskManager manager = new DocumentAsyncTaskManager(
+            new InMemoryDocumentAsyncTaskRepository(),
+            Runnable::run
+        );
+
+        try {
+            manager.queryTaskInfo("lost-task");
+            Assert.fail("expected DocumentAsyncTaskNotFoundException");
+        } catch (DocumentAsyncTaskNotFoundException error) {
+            Assert.assertEquals("lost-task", error.getTaskId());
+        }
+    }
+
     @Test
     public void shouldTrackTaskLifecycleAndResult() {
         Executor directExecutor = new Executor() {

easy-agents-document/easy-agents-document-xlsx/src/main/java/com/easyagents/document/xlsx/mineru/MineruXlsxDocumentParseService.java

@@ -14,6 +14,7 @@ import com.easyagents.document.core.entity.ParseRequest;
 import com.easyagents.document.core.entity.ParseResponse;
 import com.easyagents.document.core.entity.ParseResult;
 import com.easyagents.document.core.entity.XlsxParseRequest;
+import com.easyagents.document.core.exception.DocumentParseException;
 import com.easyagents.document.core.support.AbstractAsyncDocumentParseService;
 import com.easyagents.document.xlsx.XlsxDocumentProvider;
 import com.easyagents.document.xlsx.model.XlsxCellArtifact;
@@ -52,6 +53,10 @@ import java.util.concurrent.Executors;
 public class MineruXlsxDocumentParseService extends AbstractAsyncDocumentParseService<XlsxParseRequest> implements XlsxDocumentProvider {
 
     public static final String PROVIDER_NAME = "mineru";
+    private static final byte[] OLE2_SIGNATURE = new byte[] {
+        (byte) 0xd0, (byte) 0xcf, 0x11, (byte) 0xe0,
+        (byte) 0xa1, (byte) 0xb1, 0x1a, (byte) 0xe1
+    };
 
     private final MineruProperties properties;
     private final MineruClient client;
@@ -145,6 +150,9 @@ public class MineruXlsxDocumentParseService extends AbstractAsyncDocumentParseSe
 
     @Override
     protected ParseResponse doParse(XlsxParseRequest request, DocumentAsyncTaskUpdater updater) {
+        for (ParseFile file : request.getFiles()) {
+            validateXlsxContent(file);
+        }
         ParseResponse response = new ParseResponse();
         List<ParseResult> results = new ArrayList<ParseResult>();
         String backend = null;
@@ -211,6 +219,50 @@ public class MineruXlsxDocumentParseService extends AbstractAsyncDocumentParseSe
         return aggregate;
     }
 
+    /**
+     * 在 POI 打开工作簿前校验 XLSX 容器签名，避免向用户暴露底层格式异常。
+     *
+     * @param file 待解析文件
+     */
+    private void validateXlsxContent(ParseFile file) {
+        byte[] content = file == null ? null : file.getContent();
+        if (hasZipSignature(content)) {
+            return;
+        }
+        String fileName = file == null || !StringUtil.hasText(file.getFileName())
+            ? "当前文件"
+            : "文件“" + file.getFileName() + "”";
+        String reason = startsWith(content, OLE2_SIGNATURE)
+            ? "可能是旧版 XLS 或已加密文件"
+            : "文件内容与 .xlsx 扩展名不一致或文件已损坏";
+        throw new DocumentParseException(
+            fileName + "不是标准 XLSX，" + reason
+                + "。请解除保护后用 Excel/WPS 另存为 XLSX（修改文件后缀无效）"
+        );
+    }
+
+    private boolean hasZipSignature(byte[] content) {
+        return content != null
+            && content.length >= 4
+            && content[0] == 'P'
+            && content[1] == 'K'
+            && ((content[2] == 3 && content[3] == 4)
+                || (content[2] == 5 && content[3] == 6)
+                || (content[2] == 7 && content[3] == 8));
+    }
+
+    private boolean startsWith(byte[] content, byte[] signature) {
+        if (content == null || content.length < signature.length) {
+            return false;
+        }
+        for (int index = 0; index < signature.length; index++) {
+            if (content[index] != signature[index]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     private SheetExtraction extractSheet(XSSFSheet sheet,
                                          int sheetIndex,
                                          DataFormatter formatter,

easy-agents-document/easy-agents-document-xlsx/src/test/java/com/easyagents/document/xlsx/mineru/MineruXlsxDocumentParseServiceTest.java

@@ -16,6 +16,7 @@ import com.easyagents.document.core.entity.ParseTaskStatus;
 import com.easyagents.document.core.entity.XlsxParseRequest;
 import com.easyagents.document.core.exception.DocumentParseException;
 import com.easyagents.document.xlsx.model.XlsxParseArtifact;
+import org.apache.poi.hssf.usermodel.HSSFWorkbook;
 import org.apache.poi.ss.usermodel.ClientAnchor;
 import org.apache.poi.xssf.usermodel.XSSFDrawing;
 import org.apache.poi.xssf.usermodel.XSSFSheet;
@@ -119,6 +120,31 @@ public class MineruXlsxDocumentParseServiceTest {
         Assert.assertEquals("image/jpeg", result.getImages().get(0).getMimeType());
     }
 
+    @Test
+    public void shouldRejectLegacyXlsContentWithActionableMessage() throws Exception {
+        RecordingClient client = new RecordingClient(defaultProperties());
+        MineruMapper mapper = new MineruMapper(defaultProperties());
+        MineruXlsxDocumentParseService service = new MineruXlsxDocumentParseService(
+            defaultProperties(),
+            client,
+            mapper,
+            new DocumentAsyncTaskManager(new InMemoryDocumentAsyncTaskRepository(), directExecutor())
+        );
+        XlsxParseRequest request = new XlsxParseRequest();
+        request.addFile(ParseFile.of("legacy.xlsx", buildLegacyWorkbookBytes()));
+
+        DocumentParseException error = Assert.assertThrows(
+            DocumentParseException.class,
+            () -> service.parse(request)
+        );
+
+        Assert.assertEquals(
+            "文件“legacy.xlsx”不是标准 XLSX，可能是旧版 XLS 或已加密文件。"
+                + "请解除保护后用 Excel/WPS 另存为 XLSX（修改文件后缀无效）",
+            error.getMessage()
+        );
+    }
+
     @Test
     public void shouldAppendImageReferenceForImageOnlySheet() throws Exception {
         RecordingClient client = new RecordingClient(defaultProperties());
@@ -255,6 +281,15 @@ public class MineruXlsxDocumentParseServiceTest {
         return writeWorkbook(workbook);
     }
 
+    private byte[] buildLegacyWorkbookBytes() throws Exception {
+        try (HSSFWorkbook workbook = new HSSFWorkbook();
+             ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
+            workbook.createSheet("Sheet1").createRow(0).createCell(0).setCellValue("旧版表格");
+            workbook.write(outputStream);
+            return outputStream.toByteArray();
+        }
+    }
+
     private void addPicture(XSSFWorkbook workbook,
                             XSSFSheet sheet,
                             int rowIndex,

easy-agents-flow/src/main/java/com/easyagents/flow/core/chain/Chain.java

@@ -1751,16 +1751,91 @@ public class Chain {
                 stateInstanceId,
                 10L,
                 TimeUnit.SECONDS,
-                () -> {
+                () -> resumeSuspended(variables));
-                    ChainState current =
+    }
-                            chainStateRepository.load(stateInstanceId);
+
-                    if (current == null
+    private void validateResumeVariables(
-                            || current.getStatus() != ChainStatus.SUSPEND) {
+            ChainState state, Map<String, Object> variables) {
-                        return false;
+        List<Parameter> parameters = state.getSuspendForParameters();
-                    }
+        if (parameters == null || parameters.isEmpty()) {
-                    resumeSuspended(variables);
+            return;
-                    return true;
+        }
-                });
+        Map<String, Object> submitted = variables == null
+                ? Collections.emptyMap()
+                : variables;
+        Set<String> expectedKeys = parameters.stream()
+                .map(Parameter::getName)
+                .filter(Objects::nonNull)
+                .collect(java.util.stream.Collectors.toCollection(
+                        LinkedHashSet::new));
+        Set<String> extraKeys = new LinkedHashSet<>(submitted.keySet());
+        extraKeys.removeAll(expectedKeys);
+        if (!extraKeys.isEmpty()) {
+            throw new ChainResumeException(
+                    "确认参数包含未声明字段");
+        }
+        for (Parameter parameter : parameters) {
+            String name = parameter.getName();
+            Object value = submitted.get(name);
+            String label = StringUtil.getFirstWithText(
+                    parameter.getFormLabel(), name);
+            if (!submitted.containsKey(name) || isBlankResumeValue(value)) {
+                throw new ChainResumeException(
+                        "确认参数[" + label + "]不能为空");
+            }
+            validateResumeOption(parameter, value, label);
+        }
+    }
+
+    private void validateResumeOption(
+            Parameter parameter, Object value, String label) {
+        List<ParameterOption> options = parameter.getOptions();
+        if (options == null || options.isEmpty()) {
+            return;
+        }
+        Set<String> allowedValues = options.stream()
+                .map(ParameterOption::getValue)
+                .filter(Objects::nonNull)
+                .collect(java.util.stream.Collectors.toCollection(
+                        LinkedHashSet::new));
+        if ("checkbox".equals(parameter.getFormType())) {
+            if (!(value instanceof Collection<?> selected)) {
+                throw new ChainResumeException(
+                        "确认参数[" + label + "]必须提交字符串数组");
+            }
+            Set<String> unique = new LinkedHashSet<>();
+            for (Object item : selected) {
+                if (!(item instanceof String selectedValue)
+                        || !allowedValues.contains(selectedValue)) {
+                    throw new ChainResumeException(
+                            "确认参数[" + label + "]包含未配置选项");
+                }
+                if (!unique.add(selectedValue)) {
+                    throw new ChainResumeException(
+                            "确认参数[" + label + "]不能重复选择同一选项");
+                }
+            }
+            return;
+        }
+        if (!(value instanceof String selectedValue)) {
+            throw new ChainResumeException(
+                    "确认参数[" + label + "]必须提交单个字符串值");
+        }
+        if (!allowedValues.contains(selectedValue)) {
+            throw new ChainResumeException(
+                    "确认参数[" + label + "]包含未配置选项");
+        }
+    }
+
+    private boolean isBlankResumeValue(Object value) {
+        if (value == null) {
+            return true;
+        }
+        if (value instanceof String text) {
+            return text.trim().isEmpty();
+        }
+        return value instanceof Collection<?> collection
+                && collection.isEmpty();
     }
 
     /**
@@ -1777,36 +1852,51 @@ public class Chain {
      *
      * @param variables 恢复时注入的变量
      */
-    private void resumeSuspended(Map<String, Object> variables) {
+    private boolean resumeSuspended(Map<String, Object> variables) {
-        ChainState newState = updateStateSafely(state -> {
+        AtomicBoolean resumed = new AtomicBoolean(false);
-            if (variables != null) {
+        AtomicReference<Set<String>> suspendedNodeIds =
-                state.getMemory().putAll(variables);
+                new AtomicReference<>(Collections.emptySet());
-                return EnumSet.of(ChainStateField.MEMORY);
+        updateStateSafely(state -> {
-            } else {
+            resumed.set(false);
+            suspendedNodeIds.set(Collections.emptySet());
+            if (state.getStatus() != ChainStatus.SUSPEND) {
                 return null;
             }
+            validateResumeVariables(state, variables);
+            if (state.getSuspendNodeIds() != null) {
+                suspendedNodeIds.set(
+                        new LinkedHashSet<>(state.getSuspendNodeIds()));
+            }
+            EnumSet<ChainStateField> updatedFields = EnumSet.of(
+                    ChainStateField.STATUS,
+                    ChainStateField.SUSPEND_NODE_IDS,
+                    ChainStateField.SUSPEND_FOR_PARAMETERS);
+            if (variables != null && !variables.isEmpty()) {
+                state.getMemory().putAll(variables);
+                updatedFields.add(ChainStateField.MEMORY);
+            }
+            state.setStatus(ChainStatus.RUNNING);
+            state.setSuspendNodeIds(null);
+            state.setSuspendForParameters(null);
+            resumed.set(true);
+            return updatedFields;
         });
+        if (!resumed.get()) {
+            return false;
+        }
 
         notifyEvent(new ChainResumeEvent(this, variables));
-        setStatusAndNotifyEvent(ChainStatus.RUNNING);
+        notifyEvent(new ChainStatusChangeEvent(
+                this, ChainStatus.RUNNING, ChainStatus.SUSPEND));
 
-        Set<String> suspendNodeIds = newState.getSuspendNodeIds();
+        for (String id : suspendedNodeIds.get()) {
-        if (suspendNodeIds != null && !suspendNodeIds.isEmpty()) {
+            Node node = definition.getNodeById(id);
-            // 移除 suspend 状态，方便二次 suspend 时，不带有旧数据
+            if (node == null) {
-             updateStateSafely(state -> {
+                throw new ChainException("Node not found: " + id);
-                state.setSuspendNodeIds(null);
-                state.setSuspendForParameters(null);
-                return EnumSet.of(ChainStateField.SUSPEND_NODE_IDS, ChainStateField.SUSPEND_FOR_PARAMETERS);
-            });
-
-            for (String id : suspendNodeIds) {
-                Node node = definition.getNodeById(id);
-                if (node == null) {
-                    throw new ChainException("Node not found: " + id);
-                }
-                scheduleNode(node, null, TriggerType.RESUME, 0L);
             }
+            scheduleNode(node, null, TriggerType.RESUME, 0L);
         }
+        return true;
     }
 
     public void resume() {

easy-agents-flow/src/main/java/com/easyagents/flow/core/chain/ChainResumeException.java

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025-2026, Michael Yang 杨福海 (fuhai999@gmail.com).
+ * <p>
+ * Licensed under the GNU Lesser General Public License (LGPL) ,Version 3.0.
+ */
+package com.easyagents.flow.core.chain;
+
+/**
+ * 工作流挂起参数不满足当前恢复请求时抛出的异常。
+ */
+public class ChainResumeException extends ChainException {
+
+    public ChainResumeException(String message) {
+        super(message);
+    }
+}

easy-agents-flow/src/main/java/com/easyagents/flow/core/chain/Parameter.java

@@ -49,6 +49,11 @@ public class Parameter implements Serializable, Cloneable {
      */
     protected List<Object> enums;
 
+    /**
+     * 显示文案与实际值分离的结构化选项。
+     */
+    protected List<ParameterOption> options;
+
     /**
      * 用户输入的表单类型，例如："input"  "textarea"  "select"  "radio"  "checkbox"  等等
      */
@@ -242,6 +247,14 @@ public class Parameter implements Serializable, Cloneable {
         }
     }
 
+    public List<ParameterOption> getOptions() {
+        return options;
+    }
+
+    public void setOptions(List<ParameterOption> options) {
+        this.options = options;
+    }
+
     public String getFormType() {
         return formType;
     }
@@ -298,6 +311,7 @@ public class Parameter implements Serializable, Cloneable {
             ", flattenAggregation=" + flattenAggregation +
             ", children=" + children +
             ", enums=" + enums +
+            ", options=" + options +
             ", formType='" + formType + '\'' +
             ", formLabel='" + formLabel + '\'' +
             ", formPlaceholder='" + formPlaceholder + '\'' +
@@ -320,6 +334,13 @@ public class Parameter implements Serializable, Cloneable {
                 clone.enums = new ArrayList<>(this.enums.size());
                 clone.enums.addAll(this.enums);
             }
+            if (this.options != null) {
+                clone.options = new ArrayList<>(this.options.size());
+                for (ParameterOption option : this.options) {
+                    clone.options.add(new ParameterOption(
+                            option.getLabel(), option.getValue()));
+                }
+            }
             return clone;
         } catch (CloneNotSupportedException e) {
             throw new AssertionError();

easy-agents-flow/src/main/java/com/easyagents/flow/core/chain/ParameterOption.java

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2025-2026, Michael Yang 杨福海 (fuhai999@gmail.com).
+ * <p>
+ * Licensed under the GNU Lesser General Public License (LGPL) ,Version 3.0.
+ */
+package com.easyagents.flow.core.chain;
+
+import java.io.Serializable;
+
+/**
+ * 用户输入参数的结构化选项。
+ */
+public class ParameterOption implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    private String label;
+    private String value;
+
+    public ParameterOption() {
+    }
+
+    public ParameterOption(String label, String value) {
+        setLabel(label);
+        setValue(value);
+    }
+
+    public String getLabel() {
+        return label;
+    }
+
+    public void setLabel(String label) {
+        this.label = trim(label);
+    }
+
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue(String value) {
+        this.value = trim(value);
+    }
+
+    private static String trim(String value) {
+        return value == null ? null : value.trim();
+    }
+
+    @Override
+    public String toString() {
+        return "ParameterOption{" +
+                "label='" + label + '\'' +
+                ", value='" + value + '\'' +
+                '}';
+    }
+}

easy-agents-flow/src/main/java/com/easyagents/flow/core/knowledge/KnowledgeManager.java

@@ -18,6 +18,7 @@ package com.easyagents.flow.core.knowledge;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 
 public class KnowledgeManager {
 
@@ -51,4 +52,20 @@ public class KnowledgeManager {
         }
         return null;
     }
+
+    /**
+     * 将完整知识检索请求交给首个能够处理它的 Provider。
+     *
+     * @param request 检索请求
+     * @return 节点输出；没有 Provider 能处理时返回 null
+     */
+    public Map<String, Object> search(KnowledgeSearchRequest request) {
+        for (KnowledgeProvider provider : providers) {
+            Map<String, Object> result = provider.search(request);
+            if (result != null) {
+                return result;
+            }
+        }
+        return null;
+    }
 }

easy-agents-flow/src/main/java/com/easyagents/flow/core/knowledge/KnowledgeProvider.java

@@ -15,6 +15,37 @@
  */
 package com.easyagents.flow.core.knowledge;
 
+import com.easyagents.flow.core.util.Maps;
+
+import java.util.List;
+import java.util.Map;
+
 public interface KnowledgeProvider {
     Knowledge getKnowledge(Object id);
+
+    /**
+     * 执行完整的知识库节点检索请求。
+     *
+     * <p>默认实现保留单知识库兼容。需要跨知识库汇总的业务 Provider
+     * 应覆盖本方法并返回完整节点输出。</p>
+     *
+     * @param request 检索请求
+     * @return 节点输出；当前 Provider 不支持该请求时返回 null
+     */
+    default Map<String, Object> search(KnowledgeSearchRequest request) {
+        if (request == null || request.getKnowledgeIds().size() != 1) {
+            return null;
+        }
+        Object knowledgeId = request.getKnowledgeIds().get(0);
+        Knowledge knowledge = getKnowledge(knowledgeId);
+        if (knowledge == null) {
+            return null;
+        }
+        List<Map<String, Object>> documents = knowledge.search(
+                request.getKeyword(),
+                request.getLimit(),
+                request.getKnowledgeNode(),
+                request.getChain());
+        return Maps.of("documents", documents);
+    }
 }

easy-agents-flow/src/main/java/com/easyagents/flow/core/knowledge/KnowledgeSearchRequest.java

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2025-2026, Michael Yang 杨福海 (fuhai999@gmail.com).
+ * <p>
+ * Licensed under the GNU Lesser General Public License (LGPL) ,Version 3.0.
+ */
+package com.easyagents.flow.core.knowledge;
+
+import com.easyagents.flow.core.chain.Chain;
+import com.easyagents.flow.core.node.KnowledgeNode;
+
+import java.util.Collections;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 工作流知识库节点的完整检索请求。
+ */
+public class KnowledgeSearchRequest {
+
+    private final List<Object> knowledgeIds;
+    private final String keyword;
+    private final int limit;
+    private final String retrievalMode;
+    private final KnowledgeNode knowledgeNode;
+    private final Chain chain;
+
+    public KnowledgeSearchRequest(
+            List<Object> knowledgeIds,
+            String keyword,
+            int limit,
+            String retrievalMode,
+            KnowledgeNode knowledgeNode,
+            Chain chain) {
+        this.knowledgeIds = knowledgeIds == null
+                ? Collections.emptyList()
+                : Collections.unmodifiableList(new ArrayList<>(knowledgeIds));
+        this.keyword = keyword;
+        this.limit = limit;
+        this.retrievalMode = retrievalMode;
+        this.knowledgeNode = knowledgeNode;
+        this.chain = chain;
+    }
+
+    public List<Object> getKnowledgeIds() {
+        return knowledgeIds;
+    }
+
+    public String getKeyword() {
+        return keyword;
+    }
+
+    public int getLimit() {
+        return limit;
+    }
+
+    public String getRetrievalMode() {
+        return retrievalMode;
+    }
+
+    public KnowledgeNode getKnowledgeNode() {
+        return knowledgeNode;
+    }
+
+    public Chain getChain() {
+        return chain;
+    }
+}

easy-agents-flow/src/main/java/com/easyagents/flow/core/node/ConfirmNode.java

@@ -15,21 +15,55 @@
  */
 package com.easyagents.flow.core.node;
 
-
 import com.easyagents.flow.core.chain.Chain;
 import com.easyagents.flow.core.chain.ChainSuspendException;
+import com.easyagents.flow.core.chain.DataType;
 import com.easyagents.flow.core.chain.Parameter;
+import com.easyagents.flow.core.chain.ParameterOption;
 import com.easyagents.flow.core.chain.RefType;
 import com.easyagents.flow.core.chain.repository.ChainStateField;
+import com.easyagents.flow.core.chain.runtime.Trigger;
+import com.easyagents.flow.core.chain.runtime.TriggerContext;
+import com.easyagents.flow.core.chain.runtime.TriggerType;
 
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 
 public class ConfirmNode extends BaseNode {
     private static final long serialVersionUID = 1L;
 
+    public static final String DEFAULT_OUTPUT_NAME = "selection";
+    public static final int MAX_OPTIONS = 100;
+    public static final int MAX_MESSAGE_LENGTH = 2000;
+    public static final int MAX_OPTION_LENGTH = 200;
+    public static final Set<String> SUPPORTED_CONFIGURATION_KEYS = Set.of(
+            "condition",
+            "description",
+            "expand",
+            "joinMode",
+            "loopBreakCondition",
+            "loopEnable",
+            "loopIntervalMs",
+            "maxLoopCount",
+            "maxRetryCount",
+            "message",
+            "multiple",
+            "options",
+            "outputDefs",
+            "resetRetryCountAfterNormal",
+            "retryEnable",
+            "retryIntervalMs",
+            "title");
 
     private String message;
-    private List<Parameter> confirms;
+    private boolean multiple;
+    private List<String> options;
 
     public String getMessage() {
         return message;
@@ -39,115 +73,152 @@ public class ConfirmNode extends BaseNode {
         this.message = message;
     }
 
-    public List<Parameter> getConfirms() {
+    public boolean isMultiple() {
-        return confirms;
+        return multiple;
     }
 
-    public void setConfirms(List<Parameter> confirms) {
+    public void setMultiple(boolean multiple) {
-        if (confirms != null) {
+        this.multiple = multiple;
-            for (Parameter confirm : confirms) {
-                confirm.setRefType(RefType.INPUT);
-                confirm.setRequired(true); // 必填，才能正确通过 getParameterValuesOnly 获取参数值
-                confirm.setName(confirm.getName());
-            }
-        }
-        this.confirms = confirms;
     }
 
+    public List<String> getOptions() {
+        return options;
+    }
+
+    public void setOptions(List<String> options) {
+        this.options = options;
+    }
 
     @Override
     public Map<String, Object> execute(Chain chain) {
+        validateConfiguration();
+        String outputName = resolveOutputName();
+        Parameter parameter = buildParameter();
 
-        List<Parameter> confirmParameters = new ArrayList<>();
+        // 确认值只能来自经过 Chain.resumeIfSuspended 校验后创建的恢复触发器。
-        addConfirmParameter(confirmParameters);
+        // 启动参数与普通节点内存中的同名值均不能绕过人工确认。
-
+        if (!isValidatedResumeTrigger(chain)) {
-        if (confirms != null) {
+            chain.updateStateSafely(state -> {
-            for (Parameter confirm : confirms) {
+                if (state.getMemory().remove(parameter.getName()) == null) {
-                Parameter clone = confirm.clone();
+                    return null;
-                clone.setName(confirm.getName() + "__" + getId());
+                }
-                clone.setRefType(RefType.INPUT);
+                return EnumSet.of(ChainStateField.MEMORY);
-                confirmParameters.add(clone);
+            });
-            }
         }
 
         Map<String, Object> values;
         try {
             values = chain.getExecutionState()
-                    .resolveParameters(this, confirmParameters);
+                    .resolveParameters(this, Collections.singletonList(parameter));
-            // 移除 confirm 参数，方便在其他节点二次确认，或者在 for 循环中第二次获取
             chain.updateStateSafely(state -> {
-                for (Parameter confirmParameter : confirmParameters) {
+                if (!state.getMemory().containsKey(parameter.getName())) {
-                    state.getMemory().remove(confirmParameter.getName());
+                    return null;
                 }
+                state.getMemory().remove(parameter.getName());
                 return EnumSet.of(ChainStateField.MEMORY);
             });
-        } catch (ChainSuspendException e) {
+        } catch (ChainSuspendException exception) {
             chain.updateStateSafely(state -> {
                 state.setMessage(message);
                 return EnumSet.of(ChainStateField.MESSAGE);
             });
-
+            throw exception;
-            if (confirms != null) {
-                List<Parameter> newParameters = new ArrayList<>();
-                for (Parameter confirm : confirms) {
-                    Parameter clone = confirm.clone();
-                    clone.setName(confirm.getName() + "__" + getId());
-                    clone.setRefType(RefType.REF); // 固定为 REF
-                    newParameters.add(clone);
-                }
-
-                // 获取参数值，不会触发 ChainSuspendException 错误
-                Map<String, Object> parameterValues =
-                        chain.getExecutionState().resolveParameters(
-                                this,
-                                newParameters,
-                                null,
-                                true);
-
-                // 设置 enums，方便前端给用户进行选择
-                for (Parameter confirmParameter : confirmParameters) {
-                    if (confirmParameter.getEnums() == null) {
-                        Object enumsObject = parameterValues.get(confirmParameter.getName());
-                        confirmParameter.setEnumsObject(enumsObject);
-                    }
-                }
-            }
-
-            throw e;
         }
 
+        return Collections.singletonMap(
+                outputName,
+                values.get(parameter.getName()));
+    }
 
-        Map<String, Object> results = new HashMap<>(values.size());
+    /**
-        values.forEach((key, value) -> {
+     * 获取并校验当前节点配置的唯一输出名称。
-            int index = key.lastIndexOf("__");
+     *
-            if (index >= 0) {
+     * @return 用户配置的输出名称
-                results.put(key.substring(0, index), value);
+     */
-            } else {
+    public String resolveOutputName() {
-                results.put(key, value);
+        if (outputDefs == null || outputDefs.size() != 1
+                || outputDefs.get(0) == null) {
+            throw new IllegalArgumentException(
+                    "用户确认节点必须配置一个输出参数");
+        }
+        Parameter output = outputDefs.get(0);
+        String outputName = output.getName();
+        if (outputName == null || outputName.trim().isEmpty()) {
+            throw new IllegalArgumentException(
+                    "用户确认节点输出参数名称不能为空");
+        }
+        DataType expectedType = multiple
+                ? DataType.Array_String
+                : DataType.String;
+        if (output.getDataType() != expectedType) {
+            throw new IllegalArgumentException(
+                    "用户确认节点输出参数类型必须与选择方式一致");
+        }
+        return outputName;
+    }
+
+    private boolean isValidatedResumeTrigger(Chain chain) {
+        Trigger trigger = TriggerContext.getCurrentTrigger();
+        return trigger != null
+                && trigger.getType() == TriggerType.RESUME
+                && Objects.equals(
+                        chain.getStateInstanceId(),
+                        trigger.getStateInstanceId())
+                && Objects.equals(getId(), trigger.getNodeId());
+    }
+
+    public void validateConfiguration() {
+        requireText(message, MAX_MESSAGE_LENGTH, "确认提示内容");
+        if (options == null || options.isEmpty()) {
+            throw new IllegalArgumentException("用户确认节点至少需要一个选项");
+        }
+        if (options.size() > MAX_OPTIONS) {
+            throw new IllegalArgumentException(
+                    "用户确认节点最多支持 " + MAX_OPTIONS + " 个选项");
+        }
+
+        Set<String> normalizedOptions = new HashSet<>();
+        for (String option : options) {
+            String normalized = requireText(option, MAX_OPTION_LENGTH, "选项内容");
+            if (!normalizedOptions.add(normalized)) {
+                throw new IllegalArgumentException("用户确认节点选项内容重复: " + normalized);
             }
-        });
+        }
-
-        return results;
     }
 
-
+    private Parameter buildParameter() {
-    private void addConfirmParameter(List<Parameter> parameters) {
-        // “确认 和 取消” 的参数
         Parameter parameter = new Parameter();
+        parameter.setId(DEFAULT_OUTPUT_NAME);
+        parameter.setName(DEFAULT_OUTPUT_NAME + "__" + getId());
+        parameter.setDataType(multiple ? DataType.Array_String : DataType.String);
         parameter.setRefType(RefType.INPUT);
-        parameter.setId("confirm");
-        parameter.setName("confirm__" + getId());
         parameter.setRequired(true);
-
-        List<Object> selectionData = new ArrayList<>();
-        selectionData.add("yes");
-        selectionData.add("no");
-
-        parameter.setEnums(selectionData);
         parameter.setContentType("text");
-        parameter.setFormType("confirm");
+        parameter.setFormType(multiple ? "checkbox" : "radio");
-        parameters.add(parameter);
+        parameter.setFormLabel("选择内容");
+        parameter.setOptions(buildRuntimeOptions());
+        return parameter;
     }
 
+    private List<ParameterOption> buildRuntimeOptions() {
+        List<ParameterOption> runtimeOptions = new ArrayList<>(options.size());
+        for (String option : options) {
+            String normalized = option.trim();
+            runtimeOptions.add(new ParameterOption(normalized, normalized));
+        }
+        return runtimeOptions;
+    }
 
+    private static String requireText(
+            String value, int maxLength, String fieldName) {
+        String normalized = value == null ? "" : value.trim();
+        if (normalized.isEmpty()) {
+            throw new IllegalArgumentException(fieldName + "不能为空");
+        }
+        if (normalized.length() > maxLength) {
+            throw new IllegalArgumentException(
+                    fieldName + "不能超过 " + maxLength + " 个字符");
+        }
+        return normalized;
+    }
 }

easy-agents-flow/src/main/java/com/easyagents/flow/core/node/KnowledgeNode.java

@@ -17,15 +17,15 @@ package com.easyagents.flow.core.node;
 
 import com.easyagents.flow.core.chain.Chain;
 import com.easyagents.flow.core.chain.ChainState;
-import com.easyagents.flow.core.knowledge.Knowledge;
 import com.easyagents.flow.core.knowledge.KnowledgeManager;
-import com.easyagents.flow.core.util.Maps;
+import com.easyagents.flow.core.knowledge.KnowledgeSearchRequest;
 import com.easyagents.flow.core.util.StringUtil;
 import com.easyagents.flow.core.util.TextTemplate;
 import org.slf4j.Logger;
 
-import java.util.Arrays;
+import java.util.ArrayList;
 import java.util.Collections;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 
@@ -36,6 +36,7 @@ public class KnowledgeNode extends BaseNode {
     private static final Logger logger = org.slf4j.LoggerFactory.getLogger(KnowledgeNode.class);
 
     private Object knowledgeId;
+    private List<Object> knowledgeIds = new ArrayList<>();
     private String keyword;
     private String limit;
     private String retrievalMode = "HYBRID";
@@ -48,6 +49,32 @@ public class KnowledgeNode extends BaseNode {
         this.knowledgeId = knowledgeId;
     }
 
+    /**
+     * 获取规范化的知识库集合，兼容历史单值字段。
+     *
+     * @return 去重后的知识库 ID
+     */
+    public List<Object> getKnowledgeIds() {
+        if (knowledgeIds != null && !knowledgeIds.isEmpty()) {
+            return Collections.unmodifiableList(knowledgeIds);
+        }
+        return knowledgeId == null
+                ? Collections.emptyList()
+                : Collections.singletonList(knowledgeId);
+    }
+
+    public void setKnowledgeIds(List<?> knowledgeIds) {
+        LinkedHashSet<Object> normalized = new LinkedHashSet<>();
+        if (knowledgeIds != null) {
+            for (Object id : knowledgeIds) {
+                if (id != null && StringUtil.hasText(String.valueOf(id))) {
+                    normalized.add(id);
+                }
+            }
+        }
+        this.knowledgeIds = new ArrayList<>(normalized);
+    }
+
     public String getKeyword() {
         return keyword;
     }
@@ -88,25 +115,44 @@ public class KnowledgeNode extends BaseNode {
         if (StringUtil.hasText(realLimitString)) {
             try {
                 realLimit = Integer.parseInt(realLimitString);
-            } catch (Exception e) {
+            } catch (NumberFormatException exception) {
-                logger.error(e.toString(), e);
+                throw new IllegalArgumentException(
+                        "知识库节点最终返回条数必须为正整数", exception);
             }
         }
-
+        if (realLimit <= 0) {
-        Knowledge knowledge = KnowledgeManager.getInstance().getKnowledge(knowledgeId);
+            throw new IllegalArgumentException(
-
+                    "知识库节点最终返回条数必须为正整数");
-        if (knowledge == null) {
-            return Collections.emptyMap();
         }
 
-        List<Map<String, Object>> result = knowledge.search(realKeyword, realLimit, this, chain);
+        List<Object> resolvedKnowledgeIds = getKnowledgeIds();
-        return Maps.of("documents", result);
+        if (resolvedKnowledgeIds.isEmpty()) {
+            throw new IllegalArgumentException("知识库节点至少需要选择一个知识库");
+        }
+        if (resolvedKnowledgeIds.size() > 1
+                && !"VECTOR".equalsIgnoreCase(retrievalMode)) {
+            throw new IllegalArgumentException("多知识库检索仅支持 VECTOR 模式");
+        }
+
+        Map<String, Object> result = KnowledgeManager.getInstance().search(
+                new KnowledgeSearchRequest(
+                        resolvedKnowledgeIds,
+                        realKeyword,
+                        realLimit,
+                        retrievalMode,
+                        this,
+                        chain));
+        if (result == null) {
+            throw new IllegalStateException("没有可用的知识库 Provider");
+        }
+        return result;
     }
 
     @Override
     public String toString() {
         return "KnowledgeNode{" +
                 "knowledgeId=" + knowledgeId +
+                ", knowledgeIds=" + knowledgeIds +
                 ", keyword='" + keyword + '\'' +
                 ", limit='" + limit + '\'' +
                 ", retrievalMode='" + retrievalMode + '\'' +

easy-agents-flow/src/main/java/com/easyagents/flow/core/parser/impl/ConfirmNodeParser.java

@@ -15,11 +15,12 @@
  */
 package com.easyagents.flow.core.parser.impl;
 
+import com.alibaba.fastjson.JSONArray;
 import com.alibaba.fastjson.JSONObject;
-import com.easyagents.flow.core.chain.Parameter;
 import com.easyagents.flow.core.node.ConfirmNode;
 import com.easyagents.flow.core.parser.BaseNodeParser;
 
+import java.util.ArrayList;
 import java.util.List;
 
 public class ConfirmNodeParser extends BaseNodeParser<ConfirmNode> {
@@ -28,12 +29,36 @@ public class ConfirmNodeParser extends BaseNodeParser<ConfirmNode> {
     public ConfirmNode doParse(JSONObject root, JSONObject data, JSONObject chainJSONObject) {
 
         ConfirmNode confirmNode = new ConfirmNode();
-        confirmNode.setMessage(data.getString("message"));
+        for (String key : data.keySet()) {
-
+            if (!ConfirmNode.SUPPORTED_CONFIGURATION_KEYS.contains(key)) {
-        List<Parameter> confirms = getParameters(data, "confirms");
+                throw new IllegalArgumentException(
-        if (confirms != null && !confirms.isEmpty()) {
+                        "用户确认节点包含无效配置字段: " + key);
-            confirmNode.setConfirms(confirms);
+            }
         }
+        Object message = data.get("message");
+        if (!(message instanceof String)) {
+            throw new IllegalArgumentException("用户确认节点提示内容必须为字符串");
+        }
+        confirmNode.setMessage((String) message);
+
+        Object multiple = data.get("multiple");
+        if (!(multiple instanceof Boolean)) {
+            throw new IllegalArgumentException("用户确认节点选择方式必须为布尔值");
+        }
+        confirmNode.setMultiple((Boolean) multiple);
+
+        Object optionsValue = data.get("options");
+        if (!(optionsValue instanceof JSONArray options)) {
+            throw new IllegalArgumentException("用户确认节点选项必须为数组");
+        }
+        List<String> confirmOptions = new ArrayList<>(options.size());
+        for (Object option : options) {
+            if (!(option instanceof String)) {
+                throw new IllegalArgumentException("用户确认节点选项内容必须为字符串");
+            }
+            confirmOptions.add((String) option);
+        }
+        confirmNode.setOptions(confirmOptions);
 
         return confirmNode;
     }

easy-agents-flow/src/main/java/com/easyagents/flow/core/parser/impl/KnowledgeNodeParser.java

@@ -16,15 +16,41 @@
 package com.easyagents.flow.core.parser.impl;
 
 import com.alibaba.fastjson.JSONObject;
+import com.alibaba.fastjson.JSONArray;
 import com.easyagents.flow.core.node.KnowledgeNode;
 import com.easyagents.flow.core.parser.BaseNodeParser;
 
+import java.util.ArrayList;
+
 public class KnowledgeNodeParser extends BaseNodeParser<KnowledgeNode> {
 
     @Override
     public KnowledgeNode doParse(JSONObject root, JSONObject data, JSONObject chainJSONObject) {
         KnowledgeNode knowledgeNode = new KnowledgeNode();
-        knowledgeNode.setKnowledgeId(data.get("knowledgeId"));
+        if (data.containsKey("knowledgeIds")) {
+            Object rawIds = data.get("knowledgeIds");
+            if (!(rawIds instanceof JSONArray)) {
+                throw new IllegalArgumentException("knowledgeIds 必须为数组");
+            }
+            JSONArray ids = (JSONArray) rawIds;
+            if (ids.isEmpty()) {
+                throw new IllegalArgumentException("knowledgeIds 不能为空");
+            }
+            java.util.LinkedHashSet<String> normalized =
+                    new java.util.LinkedHashSet<>();
+            for (Object id : ids) {
+                String value = id == null ? null : String.valueOf(id).trim();
+                if (!com.easyagents.flow.core.util.StringUtil.hasText(value)) {
+                    throw new IllegalArgumentException("knowledgeIds 不能包含空值");
+                }
+                if (!normalized.add(value)) {
+                    throw new IllegalArgumentException("knowledgeIds 不能包含重复值");
+                }
+            }
+            knowledgeNode.setKnowledgeIds(new ArrayList<>(normalized));
+        } else {
+            knowledgeNode.setKnowledgeId(data.get("knowledgeId"));
+        }
         knowledgeNode.setLimit(data.getString("limit"));
         knowledgeNode.setKeyword(data.getString("keyword"));
         knowledgeNode.setRetrievalMode(data.getString("retrievalMode"));

easy-agents-flow/src/test/java/com/easyagents/flow/core/test/ChainExecutorConcurrencyTest.java

@@ -15,10 +15,15 @@
  */
 package com.easyagents.flow.core.test;
 
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONObject;
 import com.easyagents.flow.core.chain.Chain;
 import com.easyagents.flow.core.chain.ChainDefinition;
 import com.easyagents.flow.core.chain.ChainStatus;
+import com.easyagents.flow.core.chain.DataType;
 import com.easyagents.flow.core.chain.Edge;
+import com.easyagents.flow.core.chain.Parameter;
+import com.easyagents.flow.core.chain.RefType;
 import com.easyagents.flow.core.chain.ChainState;
 import com.easyagents.flow.core.chain.event.ChainEndEvent;
 import com.easyagents.flow.core.chain.repository.ChainDefinitionSnapshotRepository;
@@ -35,6 +40,7 @@ import com.easyagents.flow.core.node.EndNode;
 import com.easyagents.flow.core.node.BaseNode;
 import com.easyagents.flow.core.node.ConfirmNode;
 import com.easyagents.flow.core.node.StartNode;
+import com.easyagents.flow.core.parser.ChainParser;
 import org.junit.Assert;
 import org.junit.Test;
 
@@ -61,6 +67,127 @@ import java.util.concurrent.atomic.AtomicReference;
  */
 public class ChainExecutorConcurrencyTest {
 
+    /**
+     * 验证启动变量不能伪造确认节点的恢复参数并绕过人工确认。
+     */
+    @Test
+    public void shouldSuspendConfirmNodeDespitePrefilledStartVariable()
+            throws Exception {
+        ScheduledExecutorService schedulerPool =
+                Executors.newSingleThreadScheduledExecutor();
+        ExecutorService workerPool = Executors.newFixedThreadPool(2);
+        TriggerScheduler triggerScheduler = new TriggerScheduler(
+                new InMemoryTriggerStore(), schedulerPool, workerPool, 10L);
+        ChainDefinition definition = createConfirmDefinition();
+        InMemoryChainStateRepository stateRepository =
+                new InMemoryChainStateRepository();
+        ChainExecutor executor = new ChainExecutor(
+                ignored -> definition,
+                stateRepository,
+                new InMemoryNodeStateRepository(),
+                triggerScheduler);
+
+        try {
+            String instanceId = executor.executeAsync(
+                    definition.getId(),
+                    Map.of("selection__confirm", "未配置值"));
+
+            ChainState state = awaitStatus(
+                    stateRepository, instanceId, ChainStatus.SUSPEND);
+            Assert.assertFalse(
+                    state.getMemory().containsKey("selection__confirm"));
+            Assert.assertEquals(
+                    "selection__confirm",
+                    state.getSuspendForParameters().get(0).getName());
+        } finally {
+            triggerScheduler.shutdown();
+        }
+    }
+
+    /**
+     * 验证设计器最终契约可解析、挂起、恢复，并把用户选择按配置名称交给结束节点。
+     */
+    @Test
+    public void shouldFlowConfiguredConfirmOutputToEndNode()
+            throws Exception {
+        ScheduledExecutorService schedulerPool =
+                Executors.newSingleThreadScheduledExecutor();
+        ExecutorService workerPool = Executors.newFixedThreadPool(2);
+        TriggerScheduler triggerScheduler = new TriggerScheduler(
+                new InMemoryTriggerStore(), schedulerPool, workerPool, 10L);
+        ChainDefinition definition = createParsedConfirmDefinition();
+        InMemoryChainStateRepository stateRepository =
+                new InMemoryChainStateRepository();
+        ChainExecutor executor = new ChainExecutor(
+                ignored -> definition,
+                stateRepository,
+                new InMemoryNodeStateRepository(),
+                triggerScheduler);
+
+        try {
+            String instanceId = executor.executeAsync(
+                    definition.getId(), Collections.emptyMap());
+            ChainState suspended = awaitStatus(
+                    stateRepository, instanceId, ChainStatus.SUSPEND);
+
+            Assert.assertEquals(
+                    "selection__confirm",
+                    suspended.getSuspendForParameters().get(0).getName());
+            Assert.assertTrue(executor.resumeAsyncIfSuspended(
+                    instanceId,
+                    Map.of("selection__confirm", "继续")));
+
+            ChainState completed = awaitStatus(
+                    stateRepository, instanceId, ChainStatus.SUCCEEDED);
+            Assert.assertEquals("继续", completed.getExecuteResult().get("result"));
+        } finally {
+            triggerScheduler.shutdown();
+        }
+    }
+
+    /**
+     * 验证多选确认结果以字符串数组形式流转到结束节点。
+     */
+    @Test
+    public void shouldFlowMultipleConfirmOutputToEndNode()
+            throws Exception {
+        ScheduledExecutorService schedulerPool =
+                Executors.newSingleThreadScheduledExecutor();
+        ExecutorService workerPool = Executors.newFixedThreadPool(2);
+        TriggerScheduler triggerScheduler = new TriggerScheduler(
+                new InMemoryTriggerStore(), schedulerPool, workerPool, 10L);
+        ChainDefinition definition = createParsedConfirmDefinition(true);
+        InMemoryChainStateRepository stateRepository =
+                new InMemoryChainStateRepository();
+        ChainExecutor executor = new ChainExecutor(
+                ignored -> definition,
+                stateRepository,
+                new InMemoryNodeStateRepository(),
+                triggerScheduler);
+
+        try {
+            String instanceId = executor.executeAsync(
+                    definition.getId(), Collections.emptyMap());
+            ChainState suspended = awaitStatus(
+                    stateRepository, instanceId, ChainStatus.SUSPEND);
+
+            Assert.assertEquals(
+                    DataType.Array_String,
+                    suspended.getSuspendForParameters().get(0).getDataType());
+            List<String> selection = List.of("继续", "停止");
+            Assert.assertTrue(executor.resumeAsyncIfSuspended(
+                    instanceId,
+                    Map.of("selection__confirm", selection)));
+
+            ChainState completed = awaitStatus(
+                    stateRepository, instanceId, ChainStatus.SUCCEEDED);
+            Assert.assertEquals(
+                    selection, completed.getExecuteResult().get("result"));
+        } finally {
+            triggerScheduler.shutdown();
+        }
+    }
+
     /**
      * 验证同步 Tool 入口遇到人工挂起会快速失败，不会无限占用调用线程。
      *
@@ -563,6 +690,12 @@ public class ChainExecutorConcurrencyTest {
         start.setId("start");
         ConfirmNode confirm = new ConfirmNode();
         confirm.setId("confirm");
+        confirm.setMessage("请选择是否继续");
+        confirm.setOptions(List.of("继续", "停止"));
+        confirm.setOutputDefs(Collections.singletonList(
+                new Parameter(
+                        ConfirmNode.DEFAULT_OUTPUT_NAME,
+                        DataType.String)));
         EndNode end = new EndNode();
         end.setId("end");
         Edge first = new Edge();
@@ -581,6 +714,91 @@ public class ChainExecutorConcurrencyTest {
         return definition;
     }
 
+    private ChainDefinition createParsedConfirmDefinition() {
+        return createParsedConfirmDefinition(false);
+    }
+
+    private ChainDefinition createParsedConfirmDefinition(boolean multiple) {
+        JSONArray nodes = new JSONArray();
+        nodes.add(nodeJson("start", "startNode", new JSONObject()));
+
+        JSONObject confirmData = new JSONObject();
+        confirmData.put("message", "请选择是否继续");
+        confirmData.put("multiple", multiple);
+        confirmData.put("options", new JSONArray(List.of("继续", "停止")));
+        String outputType = multiple ? "Array<String>" : "String";
+        confirmData.put("outputDefs", new JSONArray(List.of(
+                parameterJson("templateType", outputType, null))));
+        nodes.add(nodeJson("confirm", "confirmNode", confirmData));
+
+        JSONObject endData = new JSONObject();
+        endData.put("outputDefs", new JSONArray(List.of(
+                parameterJson(
+                        "result", outputType, "confirm.templateType"))));
+        nodes.add(nodeJson("end", "endNode", endData));
+
+        JSONArray edges = new JSONArray();
+        edges.add(edgeJson("start-to-confirm", "start", "confirm"));
+        edges.add(edgeJson("confirm-to-end", "confirm", "end"));
+        JSONObject flow = new JSONObject();
+        flow.put("nodes", nodes);
+        flow.put("edges", edges);
+
+        ChainDefinition definition = ChainParser.builder()
+                .withDefaultParsers(true)
+                .build()
+                .parse(flow.toJSONString());
+        definition.setId("confirm-output-flow-test");
+        return definition;
+    }
+
+    private JSONObject nodeJson(
+            String id, String type, JSONObject data) {
+        JSONObject node = new JSONObject();
+        node.put("id", id);
+        node.put("type", type);
+        node.put("data", data);
+        return node;
+    }
+
+    private JSONObject edgeJson(
+            String id, String source, String target) {
+        JSONObject edge = new JSONObject();
+        edge.put("id", id);
+        edge.put("source", source);
+        edge.put("target", target);
+        return edge;
+    }
+
+    private JSONObject parameterJson(
+            String name, String dataType, String ref) {
+        JSONObject parameter = new JSONObject();
+        parameter.put("name", name);
+        parameter.put("dataType", dataType);
+        if (ref != null) {
+            parameter.put("ref", ref);
+            parameter.put("refType", RefType.REF.toString());
+        }
+        return parameter;
+    }
+
+    private ChainState awaitStatus(
+            InMemoryChainStateRepository repository,
+            String instanceId,
+            ChainStatus expected) throws InterruptedException {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(3);
+        ChainState state;
+        do {
+            state = repository.load(instanceId);
+            if (state != null && state.getStatus() == expected) {
+                return state;
+            }
+            Thread.sleep(10L);
+        } while (System.nanoTime() < deadline);
+        Assert.fail("workflow did not reach status " + expected);
+        return state;
+    }
+
     /**
      * 创建用于取消传播验证的工作流。
      *

easy-agents-flow/src/test/java/com/easyagents/flow/core/test/ChainResumeGuardTest.java

@@ -2,15 +2,29 @@ package com.easyagents.flow.core.test;
 
 import com.easyagents.flow.core.chain.Chain;
 import com.easyagents.flow.core.chain.ChainDefinition;
+import com.easyagents.flow.core.chain.ChainResumeException;
+import com.easyagents.flow.core.chain.ChainState;
 import com.easyagents.flow.core.chain.ChainStatus;
 import com.easyagents.flow.core.chain.EventManager;
+import com.easyagents.flow.core.chain.Parameter;
+import com.easyagents.flow.core.chain.ParameterOption;
+import com.easyagents.flow.core.chain.repository.ChainStateField;
 import com.easyagents.flow.core.chain.repository.InMemoryChainStateRepository;
 import com.easyagents.flow.core.chain.repository.InMemoryNodeStateRepository;
 import org.junit.Assert;
 import org.junit.Test;
 
+import java.util.Arrays;
 import java.util.Collections;
+import java.util.EnumSet;
+import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
 
 /**
  * {@link Chain} 暂停恢复状态守卫测试。
@@ -72,6 +86,167 @@ public class ChainResumeGuardTest {
                         .containsKey("unexpected"));
     }
 
+    /**
+     * 验证确认选项只能按挂起时声明的字段和值恢复。
+     */
+    @Test
+    public void shouldValidateDeclaredResumeOptionsBeforeStateTransition() {
+        InMemoryChainStateRepository stateRepository =
+                new InMemoryChainStateRepository();
+        Chain chain = createChain(stateRepository, "resume-options");
+        Parameter single = optionParameter(
+                "templateType__confirm", "会议类型", "radio");
+        Parameter multiple = optionParameter(
+                "participants__confirm", "参会人员", "checkbox");
+        chain.getExecutionState().setSuspendForParameters(
+                Arrays.asList(single, multiple));
+        chain.suspend();
+
+        ChainResumeException invalidOption = assertRejected(
+                chain,
+                Map.of(
+                        "templateType__confirm", "UNKNOWN",
+                        "participants__confirm", List.of("REVIEW")));
+        ChainResumeException extraField = assertRejected(
+                chain,
+                Map.of(
+                        "templateType__confirm", "AGENDA",
+                        "participants__confirm", List.of("REVIEW", "REVIEW")));
+        assertRejected(
+                chain,
+                Map.of(
+                        "templateType__confirm", "AGENDA",
+                        "participants__confirm", List.of("REVIEW"),
+                        "extra", "value"));
+        Assert.assertFalse(invalidOption.getMessage().contains("UNKNOWN"));
+        Assert.assertFalse(extraField.getMessage().contains("extra"));
+
+        Assert.assertEquals(
+                ChainStatus.SUSPEND,
+                stateRepository.load("resume-options").getStatus());
+        Assert.assertTrue(
+                stateRepository.load("resume-options").getMemory().isEmpty());
+
+        boolean resumed = chain.resumeIfSuspended(Map.of(
+                "templateType__confirm", "AGENDA",
+                "participants__confirm", List.of("REVIEW", "BRIEFING")));
+
+        Assert.assertTrue(resumed);
+        Assert.assertEquals(
+                "AGENDA",
+                stateRepository.load("resume-options")
+                        .getMemory()
+                        .get("templateType__confirm"));
+        Assert.assertEquals(
+                List.of("REVIEW", "BRIEFING"),
+                stateRepository.load("resume-options")
+                        .getMemory()
+                        .get("participants__confirm"));
+    }
+
+    /**
+     * 验证并发恢复同一暂停实例时，只有一个请求可以完成状态转换。
+     */
+    @Test
+    public void shouldAllowOnlyOneConcurrentResume() throws Exception {
+        InMemoryChainStateRepository stateRepository =
+                new InMemoryChainStateRepository();
+        Chain first = createChain(stateRepository, "resume-concurrent");
+        Chain second = createChain(stateRepository, "resume-concurrent");
+        Parameter parameter = optionParameter(
+                "templateType__confirm", "会议类型", "radio");
+        first.getExecutionState().setSuspendForParameters(
+                List.of(parameter));
+        first.suspend();
+
+        CountDownLatch ready = new CountDownLatch(2);
+        CountDownLatch start = new CountDownLatch(1);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<Boolean> firstResult = executor.submit(() -> {
+                ready.countDown();
+                start.await();
+                return first.resumeIfSuspended(
+                        Map.of("templateType__confirm", "AGENDA"));
+            });
+            Future<Boolean> secondResult = executor.submit(() -> {
+                ready.countDown();
+                start.await();
+                return second.resumeIfSuspended(
+                        Map.of("templateType__confirm", "REVIEW"));
+            });
+
+            Assert.assertTrue(ready.await(5, TimeUnit.SECONDS));
+            start.countDown();
+            int resumedCount = (firstResult.get(5, TimeUnit.SECONDS) ? 1 : 0)
+                    + (secondResult.get(5, TimeUnit.SECONDS) ? 1 : 0);
+
+            Assert.assertEquals(1, resumedCount);
+            Assert.assertEquals(
+                    ChainStatus.RUNNING,
+                    stateRepository.load("resume-concurrent").getStatus());
+            Object selected = stateRepository.load("resume-concurrent")
+                    .getMemory()
+                    .get("templateType__confirm");
+            Assert.assertTrue(
+                    "AGENDA".equals(selected) || "REVIEW".equals(selected));
+        } finally {
+            executor.shutdownNow();
+        }
+    }
+
+    /**
+     * 验证恢复变量、状态和暂停上下文通过一次原子更新完成。
+     */
+    @Test
+    public void shouldCommitResumeTransitionInSingleStateUpdate() {
+        CountingChainStateRepository stateRepository =
+                new CountingChainStateRepository();
+        Chain chain = createChain(stateRepository, "resume-single-update");
+        chain.getExecutionState().setSuspendForParameters(List.of(
+                optionParameter("templateType__confirm", "会议类型", "radio")));
+        chain.suspend();
+        stateRepository.resetUpdateCount();
+
+        boolean resumed = chain.resumeIfSuspended(
+                Map.of("templateType__confirm", "AGENDA"));
+
+        ChainState state = stateRepository.load("resume-single-update");
+        Assert.assertTrue(resumed);
+        Assert.assertEquals(1, stateRepository.getUpdateCount());
+        Assert.assertEquals(ChainStatus.RUNNING, state.getStatus());
+        Assert.assertNull(state.getSuspendNodeIds());
+        Assert.assertNull(state.getSuspendForParameters());
+        Assert.assertEquals("AGENDA", state.getMemory().get(
+                "templateType__confirm"));
+    }
+
+    private ChainResumeException assertRejected(
+            Chain chain, Map<String, Object> variables) {
+        try {
+            chain.resumeIfSuspended(variables);
+            Assert.fail("invalid resume variables must be rejected");
+            return null;
+        } catch (ChainResumeException expected) {
+            Assert.assertNotNull(expected.getMessage());
+            return expected;
+        }
+    }
+
+    private Parameter optionParameter(
+            String name, String label, String formType) {
+        Parameter parameter = new Parameter();
+        parameter.setName(name);
+        parameter.setFormLabel(label);
+        parameter.setFormType(formType);
+        parameter.setRequired(true);
+        parameter.setOptions(List.of(
+                new ParameterOption("第一议题", "AGENDA"),
+                new ParameterOption("审议类", "REVIEW"),
+                new ParameterOption("听取类", "BRIEFING")));
+        return parameter;
+    }
+
     /**
      * 创建使用进程内状态仓储的最小工作流。
      *
@@ -93,4 +268,25 @@ public class ChainResumeGuardTest {
         chain.setEventManager(new EventManager());
         return chain;
     }
+
+    private static class CountingChainStateRepository
+            extends InMemoryChainStateRepository {
+        private final AtomicInteger updateCount = new AtomicInteger();
+
+        @Override
+        public boolean tryUpdate(
+                ChainState chainState,
+                EnumSet<ChainStateField> fields) {
+            updateCount.incrementAndGet();
+            return super.tryUpdate(chainState, fields);
+        }
+
+        private int getUpdateCount() {
+            return updateCount.get();
+        }
+
+        private void resetUpdateCount() {
+            updateCount.set(0);
+        }
+    }
 }

easy-agents-flow/src/test/java/com/easyagents/flow/core/test/ConfirmNodeTest.java

@@ -0,0 +1,235 @@
+/**
+ * Copyright (c) 2025-2026, Michael Yang 杨福海 (fuhai999@gmail.com).
+ * <p>
+ * Licensed under the GNU Lesser General Public License (LGPL) ,Version 3.0.
+ */
+package com.easyagents.flow.core.test;
+
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONObject;
+import com.easyagents.flow.core.chain.Chain;
+import com.easyagents.flow.core.chain.ChainDefinition;
+import com.easyagents.flow.core.chain.ChainSuspendException;
+import com.easyagents.flow.core.chain.DataType;
+import com.easyagents.flow.core.chain.EventManager;
+import com.easyagents.flow.core.chain.Parameter;
+import com.easyagents.flow.core.chain.repository.InMemoryChainStateRepository;
+import com.easyagents.flow.core.chain.repository.InMemoryNodeStateRepository;
+import com.easyagents.flow.core.chain.runtime.Trigger;
+import com.easyagents.flow.core.chain.runtime.TriggerContext;
+import com.easyagents.flow.core.chain.runtime.TriggerType;
+import com.easyagents.flow.core.node.ConfirmNode;
+import com.easyagents.flow.core.parser.impl.ConfirmNodeParser;
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 用户确认节点选择与输出契约测试。
+ */
+public class ConfirmNodeTest {
+
+    @Test
+    public void shouldBuildSingleChoiceAndReturnSelectedContent() {
+        ConfirmNode node = parse(false);
+        node.setId("confirm-1");
+        Chain chain = createChain();
+
+        Parameter parameter = suspend(node, chain);
+        Assert.assertEquals("selection__confirm-1", parameter.getName());
+        Assert.assertEquals("radio", parameter.getFormType());
+        Assert.assertEquals("选择内容", parameter.getFormLabel());
+        Assert.assertEquals(DataType.String, parameter.getDataType());
+        Assert.assertEquals("第一议题", parameter.getOptions().get(0).getLabel());
+        Assert.assertEquals("第一议题", parameter.getOptions().get(0).getValue());
+
+        chain.getExecutionState().getMemory().put(parameter.getName(), "审议类");
+        Map<String, Object> result = executeAsResume(node, chain);
+
+        Assert.assertEquals(Collections.singletonMap("selection", "审议类"), result);
+        Assert.assertFalse(chain.getExecutionState().getMemory()
+                .containsKey(parameter.getName()));
+    }
+
+    @Test
+    public void shouldBuildMultipleChoiceAndReturnSelectedContents() {
+        ConfirmNode node = parse(true);
+        node.setId("confirm-1");
+        Chain chain = createChain();
+
+        Parameter parameter = suspend(node, chain);
+        Assert.assertEquals("checkbox", parameter.getFormType());
+        Assert.assertEquals(DataType.Array_String, parameter.getDataType());
+
+        List<String> selected = List.of("第一议题", "听取类");
+        chain.getExecutionState().getMemory().put(parameter.getName(), selected);
+
+        Assert.assertEquals(selected, executeAsResume(node, chain).get("selection"));
+    }
+
+    @Test
+    public void shouldUseConfiguredOutputNameWithoutChangingSuspendParameter() {
+        ConfirmNode node = parse(false, "templateChoice");
+        node.setId("confirm-1");
+        Chain chain = createChain();
+
+        Parameter parameter = suspend(node, chain);
+        Assert.assertEquals("selection__confirm-1", parameter.getName());
+
+        chain.getExecutionState().getMemory().put(
+                parameter.getName(), "第一议题");
+        Assert.assertEquals(
+                Collections.singletonMap("templateChoice", "第一议题"),
+                executeAsResume(node, chain));
+    }
+
+    @Test
+    public void shouldIgnorePrefilledValueWithoutResumeTrigger() {
+        ConfirmNode node = parse(false);
+        node.setId("confirm-1");
+        Chain chain = createChain();
+        chain.getExecutionState().getMemory().put(
+                "selection__confirm-1", "未配置值");
+
+        Parameter parameter = suspend(node, chain);
+
+        Assert.assertEquals("selection__confirm-1", parameter.getName());
+        Assert.assertFalse(chain.getExecutionState().getMemory()
+                .containsKey(parameter.getName()));
+    }
+
+    @Test
+    public void shouldRejectDuplicateNormalizedOptionContents() {
+        ConfirmNode node = parse(false);
+        node.setOptions(List.of("审议类", " 审议类 "));
+
+        try {
+            node.validateConfiguration();
+            Assert.fail("duplicate option contents must be rejected");
+        } catch (IllegalArgumentException expected) {
+            Assert.assertTrue(expected.getMessage().contains("选项内容重复"));
+        }
+    }
+
+    @Test
+    public void shouldRejectNonStringOptionDuringParsing() {
+        JSONObject data = data(false);
+        data.getJSONArray("options").add(1);
+
+        try {
+            new ConfirmNodeParser().doParse(
+                    new JSONObject(), data, new JSONObject());
+            Assert.fail("non-string option must be rejected");
+        } catch (IllegalArgumentException expected) {
+            Assert.assertTrue(expected.getMessage().contains("必须为字符串"));
+        }
+    }
+
+    @Test
+    public void shouldRejectStringEncodedOptionsDuringParsing() {
+        JSONObject data = data(false);
+        data.put("options", "[\"第一议题\"]");
+
+        try {
+            new ConfirmNodeParser().doParse(
+                    new JSONObject(), data, new JSONObject());
+            Assert.fail("string encoded options must be rejected");
+        } catch (IllegalArgumentException expected) {
+            Assert.assertTrue(expected.getMessage().contains("必须为数组"));
+        }
+    }
+
+    @Test
+    public void shouldRejectImplicitModeConversionDuringParsing() {
+        JSONObject data = data(false);
+        data.put("multiple", "false");
+
+        try {
+            new ConfirmNodeParser().doParse(
+                    new JSONObject(), data, new JSONObject());
+            Assert.fail("non-boolean mode must be rejected");
+        } catch (IllegalArgumentException expected) {
+            Assert.assertTrue(expected.getMessage().contains("必须为布尔值"));
+        }
+    }
+
+    @Test
+    public void shouldRejectUnknownConfigurationFieldDuringParsing() {
+        JSONObject data = data(false);
+        data.put("async", true);
+
+        try {
+            new ConfirmNodeParser().doParse(
+                    new JSONObject(), data, new JSONObject());
+            Assert.fail("unknown confirm configuration must be rejected");
+        } catch (IllegalArgumentException expected) {
+            Assert.assertTrue(expected.getMessage().contains("无效配置字段"));
+        }
+    }
+
+    private static ConfirmNode parse(boolean multiple) {
+        return parse(multiple, ConfirmNode.DEFAULT_OUTPUT_NAME);
+    }
+
+    private static ConfirmNode parse(boolean multiple, String outputName) {
+        ConfirmNode node = new ConfirmNodeParser().doParse(
+                new JSONObject(), data(multiple), new JSONObject());
+        Parameter output = new Parameter();
+        output.setName(outputName);
+        output.setDataType(multiple
+                ? DataType.Array_String
+                : DataType.String);
+        node.setOutputDefs(Collections.singletonList(output));
+        node.validateConfiguration();
+        return node;
+    }
+
+    private static JSONObject data(boolean multiple) {
+        JSONObject data = new JSONObject();
+        data.put("message", "请选择会议纪要模板");
+        data.put("multiple", multiple);
+        JSONArray options = new JSONArray();
+        options.addAll(List.of("第一议题", "审议类", "听取类"));
+        data.put("options", options);
+        return data;
+    }
+
+    private static Parameter suspend(ConfirmNode node, Chain chain) {
+        try {
+            node.execute(chain);
+            throw new AssertionError("confirm node must suspend");
+        } catch (ChainSuspendException expected) {
+            Assert.assertEquals(1, expected.getSuspendParameters().size());
+            return expected.getSuspendParameters().get(0);
+        }
+    }
+
+    private static Map<String, Object> executeAsResume(
+            ConfirmNode node, Chain chain) {
+        Trigger trigger = new Trigger();
+        trigger.setType(TriggerType.RESUME);
+        trigger.setStateInstanceId(chain.getStateInstanceId());
+        trigger.setNodeId(node.getId());
+        TriggerContext.setCurrentTrigger(trigger);
+        try {
+            return node.execute(chain);
+        } finally {
+            TriggerContext.clearCurrentTrigger();
+        }
+    }
+
+    private static Chain createChain() {
+        ChainDefinition definition = new ChainDefinition();
+        definition.setId("confirm-node-test");
+        definition.setNodes(Collections.emptyList());
+        definition.setEdges(Collections.emptyList());
+        Chain chain = new Chain(definition, "confirm-node-instance");
+        chain.setChainStateRepository(new InMemoryChainStateRepository());
+        chain.setNodeStateRepository(new InMemoryNodeStateRepository());
+        chain.setEventManager(new EventManager());
+        return chain;
+    }
+}

easy-agents-flow/src/test/java/com/easyagents/flow/core/test/KnowledgeNodeTest.java

@@ -0,0 +1,217 @@
+/**
+ * Copyright (c) 2025-2026, Michael Yang 杨福海 (fuhai999@gmail.com).
+ * <p>
+ * Licensed under the GNU Lesser General Public License (LGPL) ,Version 3.0.
+ */
+package com.easyagents.flow.core.test;
+
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONObject;
+import com.easyagents.flow.core.chain.Chain;
+import com.easyagents.flow.core.chain.ChainDefinition;
+import com.easyagents.flow.core.chain.ChainState;
+import com.easyagents.flow.core.knowledge.Knowledge;
+import com.easyagents.flow.core.knowledge.KnowledgeManager;
+import com.easyagents.flow.core.knowledge.KnowledgeProvider;
+import com.easyagents.flow.core.knowledge.KnowledgeSearchRequest;
+import com.easyagents.flow.core.node.KnowledgeNode;
+import com.easyagents.flow.core.parser.impl.KnowledgeNodeParser;
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * 知识库节点多来源契约测试。
+ */
+public class KnowledgeNodeTest {
+
+    @Test
+    public void shouldParseLegacyKnowledgeId() {
+        JSONObject data = baseData();
+        data.put("knowledgeId", "101");
+
+        KnowledgeNode node = parse(data);
+
+        Assert.assertEquals(List.of("101"), node.getKnowledgeIds());
+    }
+
+    @Test
+    public void shouldPreferKnowledgeIdsAndKeepOrder() {
+        JSONObject data = baseData();
+        data.put("knowledgeId", "legacy");
+        JSONArray ids = new JSONArray();
+        ids.addAll(List.of("201", "202"));
+        data.put("knowledgeIds", ids);
+
+        KnowledgeNode node = parse(data);
+
+        Assert.assertEquals(List.of("201", "202"), node.getKnowledgeIds());
+    }
+
+    @Test
+    public void shouldNormalizeKnowledgeIdsBeforeStoringThem() {
+        JSONObject data = baseData();
+        JSONArray ids = new JSONArray();
+        ids.addAll(List.of(" 201 ", "202"));
+        data.put("knowledgeIds", ids);
+
+        KnowledgeNode node = parse(data);
+
+        Assert.assertEquals(List.of("201", "202"), node.getKnowledgeIds());
+    }
+
+    @Test
+    public void shouldRejectInvalidKnowledgeIds() {
+        JSONObject data = baseData();
+        data.put("knowledgeIds", "[201,202]");
+        assertParseFailure(data, "必须为数组");
+
+        JSONArray duplicateIds = new JSONArray();
+        duplicateIds.addAll(List.of("201", "201"));
+        data.put("knowledgeIds", duplicateIds);
+        assertParseFailure(data, "重复值");
+    }
+
+    @Test
+    public void defaultProviderShouldKeepSingleKnowledgeCompatibility() {
+        KnowledgeProvider provider = id ->
+                (keyword, limit, node, chain) -> List.of(Map.of(
+                        "knowledgeId", id,
+                        "content", keyword));
+        KnowledgeNode node = new KnowledgeNode();
+        node.setKnowledgeId("301");
+
+        Map<String, Object> output = provider.search(
+                new KnowledgeSearchRequest(
+                        node.getKnowledgeIds(),
+                        "问题",
+                        3,
+                        "HYBRID",
+                        node,
+                        null));
+
+        Assert.assertNotNull(output);
+        Assert.assertEquals(1, ((List<?>) output.get("documents")).size());
+    }
+
+    @Test
+    public void defaultProviderShouldDeclineMultiKnowledgeRequest() {
+        KnowledgeProvider provider = id -> null;
+        KnowledgeNode node = new KnowledgeNode();
+        node.setKnowledgeIds(List.of("401", "402"));
+
+        Assert.assertNull(provider.search(new KnowledgeSearchRequest(
+                node.getKnowledgeIds(),
+                "问题",
+                3,
+                "VECTOR",
+                node,
+                null)));
+    }
+
+    @Test
+    public void shouldResolveVariableLimitAndDefaultBlankValueAtRuntime() {
+        Assert.assertEquals(7, executeAndCaptureLimit("{{start.limit}}", "7"));
+        Assert.assertEquals(10, executeAndCaptureLimit("{{start.limit}}", "   "));
+        Assert.assertEquals(10, executeAndCaptureLimit("{{start.limit ?? }}", null));
+    }
+
+    @Test
+    public void shouldRejectInvalidResolvedVariableLimitAtRuntime() {
+        assertRuntimeLimitFailure("abc");
+        assertRuntimeLimitFailure("0");
+        assertRuntimeLimitFailure("-2");
+    }
+
+    private static KnowledgeNode parse(JSONObject data) {
+        return new KnowledgeNodeParser().doParse(
+                new JSONObject(), data, new JSONObject());
+    }
+
+    private static JSONObject baseData() {
+        JSONObject data = new JSONObject();
+        data.put("keyword", "问题");
+        data.put("limit", "5");
+        data.put("retrievalMode", "VECTOR");
+        return data;
+    }
+
+    private static void assertParseFailure(
+            JSONObject data, String expectedMessage) {
+        try {
+            parse(data);
+            Assert.fail("invalid knowledgeIds must be rejected");
+        } catch (IllegalArgumentException expected) {
+            Assert.assertTrue(expected.getMessage().contains(expectedMessage));
+        }
+    }
+
+    private static int executeAndCaptureLimit(
+            String limitTemplate,
+            String runtimeValue) {
+        AtomicInteger capturedLimit = new AtomicInteger(-1);
+        KnowledgeProvider provider = new KnowledgeProvider() {
+            @Override
+            public Knowledge getKnowledge(Object id) {
+                return null;
+            }
+
+            @Override
+            public Map<String, Object> search(KnowledgeSearchRequest request) {
+                capturedLimit.set(request.getLimit());
+                return Map.of("documents", List.of());
+            }
+        };
+        KnowledgeManager.getInstance().registerProvider(provider);
+        try {
+            KnowledgeNode node = runtimeNode(limitTemplate);
+            ChainState state = new ChainState();
+            if (runtimeValue != null) {
+                state.getMemory().put("start.limit", runtimeValue);
+            }
+            node.execute(new FixedStateChain(state));
+            return capturedLimit.get();
+        } finally {
+            KnowledgeManager.getInstance().removeProvider(provider);
+        }
+    }
+
+    private static void assertRuntimeLimitFailure(String runtimeValue) {
+        KnowledgeNode node = runtimeNode("{{start.limit}}");
+        ChainState state = new ChainState();
+        state.getMemory().put("start.limit", runtimeValue);
+
+        IllegalArgumentException exception = Assert.assertThrows(
+                IllegalArgumentException.class,
+                () -> node.execute(new FixedStateChain(state)));
+
+        Assert.assertTrue(exception.getMessage().contains("必须为正整数"));
+    }
+
+    private static KnowledgeNode runtimeNode(String limitTemplate) {
+        KnowledgeNode node = new KnowledgeNode();
+        node.setKnowledgeIds(List.of("501", "502"));
+        node.setKeyword("问题");
+        node.setLimit(limitTemplate);
+        node.setRetrievalMode("VECTOR");
+        return node;
+    }
+
+    private static final class FixedStateChain extends Chain {
+
+        private final ChainState state;
+
+        private FixedStateChain(ChainState state) {
+            super(new ChainDefinition(), "knowledge-node-limit-test");
+            this.state = state;
+        }
+
+        @Override
+        public ChainState getExecutionState() {
+            return state;
+        }
+    }
+}

easy-agents-search-engine/easy-agents-search-engine-lucene/src/main/java/com/easyagents/search/engine/lucene/LuceneSearcher.java

@@ -199,10 +199,13 @@ public class LuceneSearcher implements DocumentSearcher, AutoCloseable {
     @Override
     public List<Document> searchDocuments(KeywordSearchRequest request) {
         List<Document> results = new ArrayList<>();
+        if (request == null || request.getKeyword() == null || request.getKeyword().trim().isEmpty()) {
+            return results;
+        }
         try (IndexReader reader = DirectoryReader.open(directory)) {
             IndexSearcher searcher = new IndexSearcher(reader);
             Query query = buildQuery(request);
-            TopDocs topDocs = searcher.search(query, request == null ? 10 : request.getCount());
+            TopDocs topDocs = searcher.search(query, request.getCount());
             for (ScoreDoc scoreDoc : topDocs.scoreDocs) {
                 org.apache.lucene.document.Document doc = searcher.doc(scoreDoc.doc);
                 Document resultDoc = new Document();
@@ -224,29 +227,24 @@ public class LuceneSearcher implements DocumentSearcher, AutoCloseable {
         return results;
     }
 
-    Query buildQuery(KeywordSearchRequest request) {
+    Query buildQuery(KeywordSearchRequest request) throws ParseException {
-        try {
+        String escapedKeyword = QueryParser.escape(request.getKeyword());
-            String keyword = request == null ? null : request.getKeyword();
 
-            QueryParser titleQueryParser = new QueryParser("title", analyzer);
+        QueryParser titleQueryParser = new QueryParser("title", analyzer);
-            Query titleQuery = titleQueryParser.parse(keyword);
+        Query titleQuery = titleQueryParser.parse(escapedKeyword);
-            BooleanClause titleBooleanClause = new BooleanClause(titleQuery, BooleanClause.Occur.SHOULD);
+        BooleanClause titleBooleanClause = new BooleanClause(titleQuery, BooleanClause.Occur.SHOULD);
 
-            QueryParser contentQueryParser = new QueryParser("content", analyzer);
+        QueryParser contentQueryParser = new QueryParser("content", analyzer);
-            Query contentQuery = contentQueryParser.parse(keyword);
+        Query contentQuery = contentQueryParser.parse(escapedKeyword);
-            BooleanClause contentBooleanClause = new BooleanClause(contentQuery, BooleanClause.Occur.SHOULD);
+        BooleanClause contentBooleanClause = new BooleanClause(contentQuery, BooleanClause.Occur.SHOULD);
 
-            BooleanQuery.Builder builder = new BooleanQuery.Builder();
+        BooleanQuery.Builder builder = new BooleanQuery.Builder();
-            builder.add(titleBooleanClause)
+        builder.add(titleBooleanClause)
-                .add(contentBooleanClause);
+            .add(contentBooleanClause);
-            if (request != null && request.getKnowledgeId() != null && !request.getKnowledgeId().trim().isEmpty()) {
+        if (request.getKnowledgeId() != null && !request.getKnowledgeId().trim().isEmpty()) {
-                builder.add(new TermQuery(new Term(KeywordSearchMetadataKeys.KNOWLEDGE_ID, request.getKnowledgeId().trim())), BooleanClause.Occur.MUST);
+            builder.add(new TermQuery(new Term(KeywordSearchMetadataKeys.KNOWLEDGE_ID, request.getKnowledgeId().trim())), BooleanClause.Occur.MUST);
-            }
-            return builder.build();
-        } catch (ParseException e) {
-            LOG.error(e.toString(), e);
         }
-        return null;
+        return builder.build();
     }
 
     private static Analyzer createAnalyzer() {

easy-agents-search-engine/easy-agents-search-engine-lucene/src/test/java/com/easyagents/search/engine/lucene/LuceneSearcherTest.java

@@ -57,6 +57,45 @@ public class LuceneSearcherTest {
         }
     }
 
+    /**
+     * 验证用户输入中的 Lucene 特殊字符按普通文本检索。
+     *
+     * @throws Exception 临时目录或 Lucene 资源操作失败时抛出
+     */
+    @Test
+    public void shouldTreatLuceneSpecialCharactersAsPlainText() throws Exception {
+        Path tempDir = Files.createTempDirectory("lucene-searcher-special-character-test");
+        LuceneConfig config = new LuceneConfig();
+        config.setIndexDirPath(tempDir.toString());
+        try (LuceneSearcher searcher = new LuceneSearcher(config)) {
+            Document document = new Document();
+            document.setId("special-character");
+            document.setContent("A/C.\\nPLEASE");
+            Assert.assertTrue(searcher.addDocument(document));
+
+            List<Document> results = searcher.searchDocuments("A/C.\\nPLEASE", 10);
+
+            Assert.assertEquals(1, results.size());
+            Assert.assertEquals("special-character", String.valueOf(results.get(0).getId()));
+        }
+    }
+
+    /**
+     * 验证空查询直接返回空结果。
+     *
+     * @throws Exception 临时目录或 Lucene 资源操作失败时抛出
+     */
+    @Test
+    public void shouldReturnEmptyForMissingKeyword() throws Exception {
+        Path tempDir = Files.createTempDirectory("lucene-searcher-empty-keyword-test");
+        LuceneConfig config = new LuceneConfig();
+        config.setIndexDirPath(tempDir.toString());
+        try (LuceneSearcher searcher = new LuceneSearcher(config)) {
+            Assert.assertTrue(searcher.searchDocuments((KeywordSearchRequest) null).isEmpty());
+            Assert.assertTrue(searcher.searchDocuments("   ", 10).isEmpty());
+        }
+    }
+
     /**
      * 验证多个导入线程可共享同一个 IndexWriter 完成批量写入。
      *

easy-agents-store/easy-agents-store-milvus/pom.xml

@@ -25,7 +25,6 @@
         <dependency>
             <groupId>io.milvus</groupId>
             <artifactId>milvus-sdk-java</artifactId>
-            <version>2.4.1</version>
         </dependency>
         <dependency>
             <groupId>junit</groupId>

easy-agents-store/easy-agents-store-milvus/src/main/java/com/easyagents/store/milvus/MilvusClientManager.java

@@ -0,0 +1,617 @@
+/*
+ *  Copyright (c) 2023-2026, Easy-Agents (fuhai999@gmail.com).
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ */
+package com.easyagents.store.milvus;
+
+import com.easyagents.core.util.StringUtil;
+import io.grpc.Context;
+import io.milvus.pool.MilvusClientV2Pool;
+import io.milvus.pool.PoolConfig;
+import io.milvus.v2.client.ConnectConfig;
+import io.milvus.v2.client.MilvusClientV2;
+import io.milvus.v2.client.RetryConfig;
+
+import java.net.URI;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.time.Duration;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.concurrent.Callable;
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+import java.util.function.Function;
+
+/**
+ * Shared Milvus client pool and collection state.
+ */
+public class MilvusClientManager implements AutoCloseable {
+
+    private static final String POOL_KEY = "default";
+    private static final RetryConfig SINGLE_ATTEMPT_RETRY_CONFIG = RetryConfig.builder()
+        .maxRetryTimes(1)
+        .retryOnRateLimit(false)
+        .maxRetryTimeoutMs(0L)
+        .build();
+
+    private final ReentrantReadWriteLock lifecycleLock = new ReentrantReadWriteLock();
+    private final Set<String> initializedCollections =
+        Collections.synchronizedSet(new HashSet<String>());
+    private final Set<String> loadedCollections =
+        Collections.synchronizedSet(new HashSet<String>());
+    private final ConcurrentMap<String, CollectionLoadTicket> collectionLoads =
+        new ConcurrentHashMap<String, CollectionLoadTicket>();
+    private final Set<Context.CancellableContext> activeContexts =
+        ConcurrentHashMap.newKeySet();
+    private final ConcurrentMap<Thread, Integer> activeOperations =
+        new ConcurrentHashMap<Thread, Integer>();
+    private volatile ManagedMilvusClientV2Pool pool;
+    private volatile String poolFingerprint;
+    private volatile long poolGeneration;
+    private volatile boolean acceptingOperations = true;
+    private volatile boolean closed;
+
+    public MilvusClientManager(MilvusVectorStoreConfig config) {
+        PoolSettings settings = PoolSettings.from(config);
+        this.pool = createPool(settings);
+        this.poolFingerprint = fingerprint(settings);
+    }
+
+    private static ManagedMilvusClientV2Pool createPool(PoolSettings settings) {
+        ConnectConfig connectConfig = buildConnectConfig(settings);
+        PoolConfig poolConfig = PoolConfig.builder()
+            .maxTotal(settings.poolMaxTotal())
+            .maxTotalPerKey(settings.poolMaxTotalPerKey())
+            .maxIdlePerKey(settings.poolMaxIdlePerKey())
+            .minIdlePerKey(settings.poolMinIdlePerKey())
+            .blockWhenExhausted(true)
+            .maxBlockWaitDuration(Duration.ofMillis(settings.poolMaxWaitMillis()))
+            .evictionPollingInterval(Duration.ofMillis(settings.poolEvictionIntervalMillis()))
+            .minEvictableIdleDuration(Duration.ofMillis(settings.poolMinEvictableIdleMillis()))
+            .testOnBorrow(true)
+            .testOnReturn(false)
+            .build();
+        try {
+            return new ManagedMilvusClientV2Pool(poolConfig, connectConfig);
+        } catch (ReflectiveOperationException exception) {
+            throw new IllegalStateException("Unable to initialize Milvus client pool", exception);
+        }
+    }
+
+    public <T> T withClient(Function<MilvusClientV2, T> operation) {
+        return withClient(null, operation);
+    }
+
+    public <T> T withClient(
+        Duration maxWait,
+        Function<MilvusClientV2, T> operation
+    ) {
+        Thread operationThread = registerActiveOperation();
+        lifecycleLock.readLock().lock();
+        try {
+            ManagedMilvusClientV2Pool currentPool = requireOpenPool();
+            MilvusClientV2 client = maxWait == null
+                ? currentPool.getClient(POOL_KEY)
+                : currentPool.getClient(POOL_KEY, maxWait);
+            if (client == null) {
+                throw new IllegalStateException(
+                    "Milvus client pool is exhausted or unavailable"
+                );
+            }
+            Throwable operationFailure = null;
+            try {
+                client.retryConfig(SINGLE_ATTEMPT_RETRY_CONFIG);
+                Context.CancellableContext operationContext =
+                    Context.current().withCancellation();
+                try {
+                    return withRequestContext(operationContext,
+                        () -> operation.apply(client));
+                } catch (RuntimeException | Error exception) {
+                    throw exception;
+                } catch (Exception exception) {
+                    throw new IllegalStateException(
+                        "Milvus client operation failed", exception);
+                } finally {
+                    operationContext.cancel(null);
+                }
+            } catch (RuntimeException | Error exception) {
+                operationFailure = exception;
+                throw exception;
+            } finally {
+                RuntimeException cleanupFailure = null;
+                try {
+                    releaseClient(currentPool, client);
+                } catch (RuntimeException exception) {
+                    cleanupFailure = exception;
+                }
+                if (cleanupFailure != null) {
+                    if (operationFailure == null) {
+                        throw cleanupFailure;
+                    }
+                    operationFailure.addSuppressed(cleanupFailure);
+                }
+            }
+        } finally {
+            unregisterActiveOperation(operationThread);
+            lifecycleLock.readLock().unlock();
+        }
+    }
+
+    private Thread registerActiveOperation() {
+        ensureAcceptingOperations();
+        Thread currentThread = Thread.currentThread();
+        activeOperations.merge(currentThread, 1, Integer::sum);
+        if (!acceptingOperations) {
+            unregisterActiveOperation(currentThread);
+            ensureAcceptingOperations();
+        }
+        return currentThread;
+    }
+
+    private void unregisterActiveOperation(Thread operationThread) {
+        activeOperations.computeIfPresent(operationThread,
+            (thread, depth) -> depth <= 1 ? null : depth - 1);
+    }
+
+    private void releaseClient(
+        ManagedMilvusClientV2Pool currentPool,
+        MilvusClientV2 client
+    ) {
+        RuntimeException readinessFailure = null;
+        boolean reusable = false;
+        try {
+            reusable = client.clientIsReady();
+        } catch (RuntimeException exception) {
+            readinessFailure = exception;
+        }
+        try {
+            if (reusable) {
+                currentPool.returnClient(POOL_KEY, client);
+            } else {
+                discardFailedClient(currentPool, client);
+            }
+        } catch (RuntimeException cleanupFailure) {
+            if (readinessFailure == null) {
+                throw cleanupFailure;
+            }
+            readinessFailure.addSuppressed(cleanupFailure);
+        }
+        if (readinessFailure != null) {
+            throw readinessFailure;
+        }
+    }
+
+    <T> T withRequestContext(
+        Context.CancellableContext context,
+        Callable<T> operation
+    ) throws Exception {
+        ensureAcceptingOperations();
+        activeContexts.add(context);
+        if (!acceptingOperations) {
+            activeContexts.remove(context);
+            context.cancel(new CancellationException(
+                "Milvus client pool is unavailable"));
+            ensureAcceptingOperations();
+        }
+        try {
+            return context.call(operation);
+        } finally {
+            activeContexts.remove(context);
+        }
+    }
+
+    private void discardFailedClient(
+        ManagedMilvusClientV2Pool currentPool,
+        MilvusClientV2 client
+    ) {
+        RuntimeException cleanupFailure = null;
+        try {
+            currentPool.invalidateClient(POOL_KEY, client);
+        } catch (RuntimeException exception) {
+            cleanupFailure = exception;
+        }
+        if (cleanupFailure != null) {
+            throw cleanupFailure;
+        }
+    }
+
+    /**
+     * Rebuilds the pool when connection or pool settings change.
+     * Active operations are cancelled before the old pool is closed.
+     *
+     * @return true when a new pool was installed
+     */
+    public synchronized boolean reconfigureIfNeeded(MilvusVectorStoreConfig config) {
+        PoolSettings nextSettings = PoolSettings.from(config);
+        String nextFingerprint = fingerprint(nextSettings);
+        if (nextFingerprint.equals(poolFingerprint)) {
+            return false;
+        }
+        acceptingOperations = false;
+        cancelActiveContexts("Milvus client pool is reconfiguring");
+        interruptActiveOperations();
+        lifecycleLock.writeLock().lock();
+        try {
+            if (closed) {
+                throw new IllegalStateException("Milvus client pool is closed");
+            }
+            if (nextFingerprint.equals(poolFingerprint)) {
+                return false;
+            }
+            ManagedMilvusClientV2Pool replacement = createPool(nextSettings);
+            ManagedMilvusClientV2Pool previous = pool;
+            pool = replacement;
+            poolFingerprint = nextFingerprint;
+            poolGeneration++;
+            initializedCollections.clear();
+            loadedCollections.clear();
+            failCollectionLoads("Milvus client pool was reconfigured");
+            if (previous != null) {
+                previous.close();
+            }
+            return true;
+        } finally {
+            lifecycleLock.writeLock().unlock();
+            if (!closed) {
+                acceptingOperations = true;
+            }
+        }
+    }
+
+    boolean isCollectionInitialized(String collectionName) {
+        return initializedCollections.contains(collectionName);
+    }
+
+    Object initializedCollectionsLock() {
+        return initializedCollections;
+    }
+
+    void markCollectionInitialized(String collectionName) {
+        initializedCollections.add(collectionName);
+    }
+
+    boolean isCollectionLoaded(String collectionName) {
+        return loadedCollections.contains(collectionName);
+    }
+
+    void markCollectionLoaded(String collectionName) {
+        loadedCollections.add(collectionName);
+    }
+
+    void markCollectionUnloaded(String collectionName) {
+        loadedCollections.remove(collectionName);
+    }
+
+    CollectionLoadTicket beginCollectionLoad(String collectionName) {
+        ensureAcceptingOperations();
+        lifecycleLock.readLock().lock();
+        try {
+            requireOpenPool();
+            CollectionLoadTicket candidate = new CollectionLoadTicket(
+                collectionName,
+                poolGeneration,
+                new CompletableFuture<Void>(),
+                true
+            );
+            CollectionLoadTicket existing = collectionLoads.putIfAbsent(
+                collectionName, candidate);
+            return existing == null ? candidate : existing.asFollower();
+        } finally {
+            lifecycleLock.readLock().unlock();
+        }
+    }
+
+    void completeCollectionLoad(CollectionLoadTicket ticket) {
+        lifecycleLock.readLock().lock();
+        try {
+            requireOpenPool();
+            if (ticket.generation != poolGeneration) {
+                throw new IllegalStateException(
+                    "Milvus client pool changed while loading collection: "
+                        + ticket.collectionName
+                );
+            }
+            loadedCollections.add(ticket.collectionName);
+            ticket.completion.complete(null);
+        } finally {
+            lifecycleLock.readLock().unlock();
+        }
+    }
+
+    void failCollectionLoad(
+        CollectionLoadTicket ticket,
+        Throwable failure,
+        boolean retryableForFollowers
+    ) {
+        if (retryableForFollowers && ticket.leader) {
+            collectionLoads.remove(ticket.collectionName, ticket);
+        }
+        Throwable sharedFailure = retryableForFollowers
+            ? new RetryableCollectionLoadException(failure)
+            : failure;
+        ticket.completion.completeExceptionally(sharedFailure);
+    }
+
+    void endCollectionLoad(CollectionLoadTicket ticket) {
+        if (ticket.leader) {
+            collectionLoads.remove(ticket.collectionName, ticket);
+        }
+    }
+
+    public int getActiveClientCount() {
+        lifecycleLock.readLock().lock();
+        try {
+            return requireOpenPool().getTotalActiveClientNumber();
+        } finally {
+            lifecycleLock.readLock().unlock();
+        }
+    }
+
+    public int getIdleClientCount() {
+        lifecycleLock.readLock().lock();
+        try {
+            return requireOpenPool().getTotalIdleClientNumber();
+        } finally {
+            lifecycleLock.readLock().unlock();
+        }
+    }
+
+    @Override
+    public synchronized void close() {
+        if (closed) {
+            return;
+        }
+        acceptingOperations = false;
+        closed = true;
+        cancelActiveContexts("Milvus client pool is closing");
+        interruptActiveOperations();
+        lifecycleLock.writeLock().lock();
+        try {
+            initializedCollections.clear();
+            loadedCollections.clear();
+            poolGeneration++;
+            failCollectionLoads("Milvus client pool was closed");
+            ManagedMilvusClientV2Pool currentPool = pool;
+            pool = null;
+            poolFingerprint = null;
+            if (currentPool != null) {
+                currentPool.close();
+            }
+        } finally {
+            lifecycleLock.writeLock().unlock();
+        }
+    }
+
+    private ManagedMilvusClientV2Pool requireOpenPool() {
+        ManagedMilvusClientV2Pool currentPool = pool;
+        if (closed || currentPool == null) {
+            throw new IllegalStateException("Milvus client pool is closed");
+        }
+        return currentPool;
+    }
+
+    boolean isClosed() {
+        return closed;
+    }
+
+    private void ensureAcceptingOperations() {
+        if (!acceptingOperations) {
+            throw new IllegalStateException(closed
+                ? "Milvus client pool is closed"
+                : "Milvus client pool is reconfiguring");
+        }
+    }
+
+    private void failCollectionLoads(String message) {
+        IllegalStateException failure = new IllegalStateException(message);
+        for (CollectionLoadTicket ticket : collectionLoads.values()) {
+            ticket.completion.completeExceptionally(failure);
+        }
+        collectionLoads.clear();
+    }
+
+    private void cancelActiveContexts(String message) {
+        for (Context.CancellableContext context : activeContexts) {
+            context.cancel(new CancellationException(message));
+        }
+    }
+
+    private void interruptActiveOperations() {
+        Thread currentThread = Thread.currentThread();
+        for (Thread operationThread : activeOperations.keySet()) {
+            if (operationThread != currentThread) {
+                operationThread.interrupt();
+            }
+        }
+    }
+
+    private static String fingerprint(PoolSettings settings) {
+        String value = String.join("\u0000",
+            String.valueOf(settings.uri()),
+            String.valueOf(settings.databaseName()),
+            String.valueOf(settings.token()),
+            String.valueOf(settings.username()),
+            String.valueOf(settings.password()),
+            String.valueOf(settings.poolMaxTotal()),
+            String.valueOf(settings.poolMaxTotalPerKey()),
+            String.valueOf(settings.poolMaxIdlePerKey()),
+            String.valueOf(settings.poolMinIdlePerKey()),
+            String.valueOf(settings.poolMaxWaitMillis()),
+            String.valueOf(settings.poolEvictionIntervalMillis()),
+            String.valueOf(settings.poolMinEvictableIdleMillis())
+        );
+        try {
+            byte[] digest = MessageDigest.getInstance("SHA-256")
+                .digest(value.getBytes(StandardCharsets.UTF_8));
+            StringBuilder result = new StringBuilder(digest.length * 2);
+            for (byte item : digest) {
+                result.append(String.format("%02x", item & 0xff));
+            }
+            return result.toString();
+        } catch (NoSuchAlgorithmException exception) {
+            throw new IllegalStateException("SHA-256 is unavailable", exception);
+        }
+    }
+
+    static ConnectConfig buildConnectConfig(MilvusVectorStoreConfig config) {
+        return buildConnectConfig(PoolSettings.from(config));
+    }
+
+    private static ConnectConfig buildConnectConfig(PoolSettings settings) {
+        String uri = normalizeAndValidateUri(settings.uri());
+        String databaseName = StringUtil.hasText(settings.databaseName())
+            ? settings.databaseName().trim()
+            : "default";
+        ConnectConfig.ConnectConfigBuilder<?, ?> builder = ConnectConfig.builder()
+            .uri(uri)
+            .dbName(databaseName);
+        if (StringUtil.hasText(settings.token())) {
+            builder.token(settings.token().trim());
+        }
+        if (StringUtil.hasText(settings.username()) && StringUtil.hasText(settings.password())) {
+            builder.username(settings.username().trim());
+            builder.password(settings.password().trim());
+        }
+        return builder.build();
+    }
+
+    private record PoolSettings(
+        String uri,
+        String databaseName,
+        String token,
+        String username,
+        String password,
+        int poolMaxTotal,
+        int poolMaxTotalPerKey,
+        int poolMaxIdlePerKey,
+        int poolMinIdlePerKey,
+        long poolMaxWaitMillis,
+        long poolEvictionIntervalMillis,
+        long poolMinEvictableIdleMillis
+    ) {
+        private static PoolSettings from(MilvusVectorStoreConfig config) {
+            return new PoolSettings(
+                config.getUri(),
+                config.getDatabaseName(),
+                config.getToken(),
+                config.getUsername(),
+                config.getPassword(),
+                config.getPoolMaxTotal(),
+                config.getPoolMaxTotalPerKey(),
+                config.getPoolMaxIdlePerKey(),
+                config.getPoolMinIdlePerKey(),
+                config.getPoolMaxWaitMillis(),
+                config.getPoolEvictionIntervalMillis(),
+                config.getPoolMinEvictableIdleMillis()
+            );
+        }
+    }
+
+    private static final class ManagedMilvusClientV2Pool extends MilvusClientV2Pool {
+
+        private ManagedMilvusClientV2Pool(
+            PoolConfig poolConfig,
+            ConnectConfig connectConfig
+        ) throws ClassNotFoundException, NoSuchMethodException {
+            super(poolConfig, connectConfig);
+        }
+
+        private void invalidateClient(String key, MilvusClientV2 client) {
+            try {
+                clientPool.invalidateObject(key, client);
+            } catch (Exception exception) {
+                throw new IllegalStateException("Unable to invalidate Milvus client", exception);
+            }
+        }
+
+        private MilvusClientV2 getClient(String key, Duration maxWait) {
+            if (maxWait == null || maxWait.isZero() || maxWait.isNegative()) {
+                throw new IllegalArgumentException("maxWait must be greater than zero");
+            }
+            try {
+                long waitMillis = Math.max(1L, maxWait.toMillis());
+                return clientPool.borrowObject(key, waitMillis);
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+                throw new IllegalStateException(
+                    "Interrupted while waiting for a Milvus client", exception);
+            } catch (Exception exception) {
+                throw new IllegalStateException(
+                    "Unable to borrow a Milvus client", exception);
+            }
+        }
+    }
+
+    static final class CollectionLoadTicket {
+
+        private final String collectionName;
+        private final long generation;
+        private final CompletableFuture<Void> completion;
+        private final boolean leader;
+
+        private CollectionLoadTicket(
+            String collectionName,
+            long generation,
+            CompletableFuture<Void> completion,
+            boolean leader
+        ) {
+            this.collectionName = collectionName;
+            this.generation = generation;
+            this.completion = completion;
+            this.leader = leader;
+        }
+
+        boolean isLeader() {
+            return leader;
+        }
+
+        CompletableFuture<Void> completion() {
+            return completion;
+        }
+
+        private CollectionLoadTicket asFollower() {
+            return new CollectionLoadTicket(
+                collectionName, generation, completion, false);
+        }
+    }
+
+    static final class RetryableCollectionLoadException
+        extends RuntimeException {
+
+        private RetryableCollectionLoadException(Throwable cause) {
+            super("The collection load leader exhausted its local budget", cause);
+        }
+    }
+
+    static String normalizeAndValidateUri(String uri) {
+        if (StringUtil.noText(uri)) {
+            throw new IllegalArgumentException(
+                "Milvus uri is required. Example: http://127.0.0.1:19530"
+            );
+        }
+        String normalized = uri.trim();
+        if (!normalized.contains("://")) {
+            normalized = "http://" + normalized;
+        }
+        try {
+            URI parsed = URI.create(normalized);
+            if (StringUtil.noText(parsed.getHost()) || parsed.getPort() <= 0) {
+                throw new IllegalArgumentException("Invalid Milvus uri: " + uri);
+            }
+        } catch (IllegalArgumentException exception) {
+            throw new IllegalArgumentException(
+                "Invalid Milvus uri: " + uri + ". Example: http://127.0.0.1:19530",
+                exception
+            );
+        }
+        return normalized;
+    }
+}

easy-agents-store/easy-agents-store-milvus/src/main/java/com/easyagents/store/milvus/MilvusVectorStore.java

@@ -15,34 +15,45 @@
  */
 package com.easyagents.store.milvus;
 
-import com.alibaba.fastjson.JSON;
+import com.google.gson.Gson;
-import com.alibaba.fastjson.JSONObject;
+import com.google.gson.JsonObject;
 import com.easyagents.core.document.Document;
 import com.easyagents.core.store.DocumentStore;
 import com.easyagents.core.store.SearchWrapper;
 import com.easyagents.core.store.StoreOptions;
 import com.easyagents.core.store.StoreResult;
+import com.easyagents.core.store.StoreTimeoutException;
 import com.easyagents.core.util.CollectionUtil;
 import com.easyagents.core.util.Maps;
 import com.easyagents.core.util.StringUtil;
-import io.milvus.v2.client.ConnectConfig;
+import io.grpc.Context;
+import io.grpc.Status;
 import io.milvus.v2.client.MilvusClientV2;
 import io.milvus.v2.common.ConsistencyLevel;
 import io.milvus.v2.common.DataType;
 import io.milvus.v2.common.IndexParam;
-import io.milvus.v2.exception.MilvusClientException;
 import io.milvus.v2.service.collection.request.CreateCollectionReq;
 import io.milvus.v2.service.collection.request.GetLoadStateReq;
 import io.milvus.v2.service.collection.request.HasCollectionReq;
 import io.milvus.v2.service.collection.request.LoadCollectionReq;
 import io.milvus.v2.service.vector.request.*;
+import io.milvus.v2.service.vector.request.data.FloatVec;
 import io.milvus.v2.service.vector.response.QueryResp;
 import io.milvus.v2.service.vector.response.SearchResp;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import java.net.URI;
+import java.time.Duration;
 import java.util.*;
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.function.Function;
 
 /**
  * Milvus vector store based on Milvus Java SDK v2.
@@ -52,63 +63,74 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
     private static final Logger LOG = LoggerFactory.getLogger(MilvusVectorStore.class);
     private static final long LOAD_TIMEOUT_MS = 30_000L;
     private static final long LOAD_POLL_INTERVAL_MS = 200L;
+    private static final long DEADLINE_SAFETY_MARGIN_MS = 200L;
+    private static final ScheduledExecutorService DEADLINE_SCHEDULER =
+        Executors.newSingleThreadScheduledExecutor(new ThreadFactory() {
+            @Override
+            public Thread newThread(Runnable runnable) {
+                Thread thread = new Thread(runnable, "milvus-deadline");
+                thread.setDaemon(true);
+                return thread;
+            }
+        });
 
     private static final String FIELD_ID = "id";
     private static final String FIELD_CONTENT = "content";
     private static final String FIELD_METADATA = "metadata";
     private static final String FIELD_VECTOR = "vector";
 
-    private final MilvusClientV2 client;
+    private static final Gson GSON = new Gson();
+
+    private final MilvusClientManager clientManager;
     private final MilvusVectorStoreConfig config;
     private final String defaultCollectionName;
-    private final Set<String> initializedCollections = Collections.synchronizedSet(new HashSet<String>());
+    private final boolean ownsClientManager;
-    private final Set<String> loadedCollections = Collections.synchronizedSet(new HashSet<String>());
+    private volatile MilvusClientV2 compatibilityClient;
+    private volatile boolean closed;
 
     public MilvusVectorStore(MilvusVectorStoreConfig config) {
-        this.config = config;
+        this(config, createOwnedClientManager(config), true);
-        this.defaultCollectionName = config.getDefaultCollectionName();
-        String uri = normalizeAndValidateUri(config.getUri());
-        String dbName = StringUtil.hasText(config.getDatabaseName()) ? config.getDatabaseName().trim() : "default";
-
-        ConnectConfig.ConnectConfigBuilder<?, ?> builder = ConnectConfig.builder()
-            .uri(uri)
-            .dbName(dbName);
-
-        if (StringUtil.hasText(config.getToken())) {
-            builder.token(config.getToken().trim());
-        }
-
-        if (StringUtil.hasText(config.getUsername()) && StringUtil.hasText(config.getPassword())) {
-            builder.username(config.getUsername().trim());
-            builder.password(config.getPassword().trim());
-        }
-
-        ConnectConfig connectConfig = builder.build();
-        this.client = new MilvusClientV2(connectConfig);
     }
 
-    private String normalizeAndValidateUri(String uri) {
+    public MilvusVectorStore(
-        if (StringUtil.noText(uri)) {
+        MilvusVectorStoreConfig config,
-            throw new IllegalArgumentException("Milvus uri is required. Example: http://127.0.0.1:19530");
+        MilvusClientManager clientManager
-        }
+    ) {
+        this(config, clientManager, false);
+    }
 
-        String normalized = uri.trim();
+    private MilvusVectorStore(
-        if (!normalized.contains("://")) {
+        MilvusVectorStoreConfig config,
-            normalized = "http://" + normalized;
+        MilvusClientManager clientManager,
-        }
+        boolean ownsClientManager
+    ) {
+        validateConfig(config);
+        this.config = config;
+        this.defaultCollectionName = config.getDefaultCollectionName();
+        this.clientManager = Objects.requireNonNull(clientManager, "clientManager");
+        this.ownsClientManager = ownsClientManager;
+    }
 
-        URI parsed;
+    private static MilvusClientManager createOwnedClientManager(
-        try {
+        MilvusVectorStoreConfig config
-            parsed = URI.create(normalized);
+    ) {
-        } catch (Exception e) {
+        validateConfig(config);
-            throw new IllegalArgumentException("Invalid Milvus uri: " + uri + ". Example: http://127.0.0.1:19530", e);
+        return new MilvusClientManager(config);
-        }
+    }
 
-        if (StringUtil.noText(parsed.getHost()) || parsed.getPort() <= 0) {
+    private static void validateConfig(MilvusVectorStoreConfig config) {
-            throw new IllegalArgumentException("Invalid Milvus uri: " + uri + ". Example: http://127.0.0.1:19530");
+        Objects.requireNonNull(config, "config");
+        if (config.getSearchTimeoutMillis() <= DEADLINE_SAFETY_MARGIN_MS) {
+            throw new IllegalArgumentException(
+                "Milvus searchTimeoutMillis must be greater than "
+                    + DEADLINE_SAFETY_MARGIN_MS
+            );
+        }
+        if (config.getPoolMaxWaitMillis() <= 0L) {
+            throw new IllegalArgumentException(
+                "Milvus poolMaxWaitMillis must be greater than zero"
+            );
         }
-
-        return normalized;
     }
 
     @Override
@@ -121,22 +143,25 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
             throw new IllegalStateException("CollectionName is null or blank. please config the \"defaultCollectionName\" or store with designative collectionName.");
         }
 
-        int dimension = getDimension(documents);
-        ensureCollectionExists(collectionName, dimension);
-
         try {
-            InsertReq.InsertReqBuilder<?, ?> builder = InsertReq.builder();
+            int dimension = getDimension(documents);
-            if (StringUtil.hasText(options.getPartitionName())) {
+            clientManager.withClient(client -> {
-                builder.partitionName(options.getPartitionName());
+                ensureCollectionExists(client, collectionName, dimension);
-            }
+                InsertReq.InsertReqBuilder<?, ?> builder = InsertReq.builder();
-            InsertReq insertReq = builder
+                if (StringUtil.hasText(options.getPartitionName())) {
-                .collectionName(collectionName)
+                    builder.partitionName(options.getPartitionName());
-                .data(toMilvusDocuments(documents))
+                }
-                .build();
+                client.insert(builder
-            client.insert(insertReq);
+                    .collectionName(collectionName)
+                    .data(toMilvusDocuments(documents))
+                    .build());
+                return null;
+            });
             return StoreResult.successWithIds(documents);
-        } catch (MilvusClientException e) {
+        } catch (RuntimeException e) {
-            return StoreResult.fail();
+            LOG.error("Milvus insert failed. collection={}, message={}",
+                collectionName, e.getMessage(), e);
+            return StoreResult.fail(e.getMessage());
         }
     }
 
@@ -159,7 +184,10 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
                 .collectionName(collectionName)
                 .ids(MilvusPrimaryKeySupport.normalize(ids))
                 .build();
-            client.delete(deleteReq);
+            clientManager.withClient(client -> {
+                client.delete(deleteReq);
+                return null;
+            });
             return StoreResult.success();
         } catch (Exception e) {
             LOG.error("Milvus delete failed. collection={}, message={}",
@@ -178,19 +206,22 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
             throw new IllegalStateException("CollectionName is null or blank. please config the \"defaultCollectionName\" or store with designative collectionName.");
         }
 
-        int dimension = getDimension(documents);
-        ensureCollectionExists(collectionName, dimension);
-
         try {
-            UpsertReq upsertReq = UpsertReq.builder()
+            int dimension = getDimension(documents);
-                .collectionName(collectionName)
+            clientManager.withClient(client -> {
-                .partitionName(options.getPartitionName())
+                ensureCollectionExists(client, collectionName, dimension);
-                .data(toMilvusDocuments(documents))
+                client.upsert(UpsertReq.builder()
-                .build();
+                    .collectionName(collectionName)
-            client.upsert(upsertReq);
+                    .partitionName(options.getPartitionName())
+                    .data(toMilvusDocuments(documents))
+                    .build());
+                return null;
+            });
             return StoreResult.successWithIds(documents);
         } catch (Exception e) {
-            return StoreResult.fail();
+            LOG.error("Milvus upsert failed. collection={}, message={}",
+                collectionName, e.getMessage(), e);
+            return StoreResult.fail(e.getMessage());
         }
     }
 
@@ -200,56 +231,104 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
         if (StringUtil.noText(collectionName)) {
             throw new IllegalStateException("CollectionName is null or blank. please config the \"defaultCollectionName\" or store with designative collectionName.");
         }
-        ensureCollectionLoaded(collectionName);
+        long timeoutMillis = resolveSearchTimeoutMillis(options);
+        long rpcBudgetMillis = timeoutMillis - DEADLINE_SAFETY_MARGIN_MS;
+        long deadlineNanos = deadlineAfterMillis(rpcBudgetMillis);
+        Context.CancellableContext context = Context.current().withDeadlineAfter(
+            rpcBudgetMillis, TimeUnit.MILLISECONDS, DEADLINE_SCHEDULER);
+        try {
+            return clientManager.withRequestContext(context, () ->
+                searchWithinDeadline(
+                    wrapper, options, collectionName, deadlineNanos));
+        } catch (RuntimeException exception) {
+            if (!(exception instanceof StoreTimeoutException)
+                && deadlineExpired(deadlineNanos, exception)) {
+                throw timeoutException(collectionName, exception);
+            }
+            throw exception;
+        } catch (Exception exception) {
+            throw new IllegalStateException("Milvus search failed", exception);
+        } finally {
+            context.cancel(null);
+        }
+    }
 
+    private List<Document> searchWithinDeadline(
+        SearchWrapper wrapper,
+        StoreOptions options,
+        String collectionName,
+        long deadlineNanos
+    ) {
+        String operation = wrapper.getVector() == null
+            || wrapper.getVector().length == 0
+            ? "query"
+            : "search";
+        ensureCollectionLoaded(collectionName, deadlineNanos);
+        try {
+            return searchOnce(wrapper, options, collectionName, deadlineNanos);
+        } catch (RuntimeException exception) {
+            if (!isCollectionNotLoaded(exception)) {
+                throw propagateSearchFailure(
+                    operation, collectionName, exception);
+            }
+            clientManager.markCollectionUnloaded(collectionName);
+            try {
+                ensureCollectionLoaded(collectionName, deadlineNanos);
+                return searchOnce(
+                    wrapper, options, collectionName, deadlineNanos);
+            } catch (RuntimeException retryException) {
+                retryException.addSuppressed(exception);
+                throw propagateSearchFailure(
+                    operation, collectionName, retryException);
+            }
+        }
+    }
+
+    private List<Document> searchOnce(
+        SearchWrapper wrapper,
+        StoreOptions options,
+        String collectionName,
+        long deadlineNanos
+    ) {
         if (wrapper.getVector() == null || wrapper.getVector().length == 0) {
-            return queryByCondition(wrapper, options, collectionName);
+            return queryByCondition(
+                wrapper, options, collectionName, deadlineNanos);
         }
-        return searchByVector(wrapper, options, collectionName);
+        return searchByVector(wrapper, options, collectionName, deadlineNanos);
     }
 
-    private List<Document> searchByVector(SearchWrapper wrapper, StoreOptions options, String collectionName) {
+    private List<Document> searchByVector(
+        SearchWrapper wrapper,
+        StoreOptions options,
+        String collectionName,
+        long deadlineNanos
+    ) {
         SearchReq searchReq = buildSearchReq(wrapper, options, collectionName);
-        try {
+        SearchResp resp = withClientBeforeDeadline(
-            SearchResp resp = client.search(searchReq);
+            deadlineNanos, client -> client.search(searchReq));
-            return parseSearchResults(resp, wrapper.getMinScore());
+        return parseSearchResults(resp, wrapper.getMinScore());
-        } catch (Exception e) {
-            if (isCollectionNotLoaded(e)) {
-                loadedCollections.remove(collectionName);
-                try {
-                    ensureCollectionLoaded(collectionName);
-                    SearchResp retryResp = client.search(searchReq);
-                    return parseSearchResults(retryResp, wrapper.getMinScore());
-                } catch (Exception retryException) {
-                    LOG.warn("Milvus search retry failed after load. collection={}, message={}", collectionName, retryException.getMessage());
-                    return Collections.emptyList();
-                }
-            }
-            LOG.warn("Milvus search failed. collection={}, message={}", collectionName, e.getMessage());
-            return Collections.emptyList();
-        }
     }
 
-    private List<Document> queryByCondition(SearchWrapper wrapper, StoreOptions options, String collectionName) {
+    private List<Document> queryByCondition(
+        SearchWrapper wrapper,
+        StoreOptions options,
+        String collectionName,
+        long deadlineNanos
+    ) {
         QueryReq queryReq = buildQueryReq(wrapper, options, collectionName);
-        try {
+        QueryResp resp = withClientBeforeDeadline(
-            QueryResp resp = client.query(queryReq);
+            deadlineNanos, client -> client.query(queryReq));
-            return parseQueryResults(resp);
+        return parseQueryResults(resp);
-        } catch (Exception e) {
+    }
-            if (isCollectionNotLoaded(e)) {
+
-                loadedCollections.remove(collectionName);
+    private RuntimeException propagateSearchFailure(
-                try {
+        String operation,
-                    ensureCollectionLoaded(collectionName);
+        String collectionName,
-                    QueryResp retryResp = client.query(queryReq);
+        RuntimeException exception
-                    return parseQueryResults(retryResp);
+    ) {
-                } catch (Exception retryException) {
+        LOG.error("Milvus {} failed. collection={}, message={}",
-                    LOG.warn("Milvus query retry failed after load. collection={}, message={}", collectionName, retryException.getMessage());
+            operation, collectionName, exception.getMessage(), exception);
-                    return Collections.emptyList();
+        return exception;
-                }
-            }
-            LOG.warn("Milvus query failed. collection={}, message={}", collectionName, e.getMessage());
-            return Collections.emptyList();
-        }
     }
 
     private SearchReq buildSearchReq(SearchWrapper wrapper, StoreOptions options, String collectionName) {
@@ -259,7 +338,7 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
             .outputFields(getOutputFields(wrapper))
             .topK(wrapper.getMaxResults())
             .annsField(FIELD_VECTOR)
-            .data(Collections.singletonList(toFloatList(wrapper.getVector())))
+            .data(Collections.singletonList(new FloatVec(wrapper.getVector())))
             .searchParams(Maps.of("ef", 64));
 
         if (CollectionUtil.hasItems(options.getPartitionNamesOrEmpty())) {
@@ -305,11 +384,7 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
                     continue;
                 }
                 document.setId(result.getId());
-                Float distance = result.getDistance();
+                document.setScore(normalizeScore(result.getScore()));
-                if (distance != null) {
-                    double score = (distance + 1.0d) / 2.0d;
-                    document.setScore(score);
-                }
                 if (minScore == null || document.getScore() == null || document.getScore() >= minScore) {
                     documents.add(document);
                 }
@@ -318,6 +393,10 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
         return documents;
     }
 
+    static Double normalizeScore(Float rawScore) {
+        return rawScore == null ? null : (rawScore + 1.0d) / 2.0d;
+    }
+
     private List<Document> parseQueryResults(QueryResp resp) {
         List<QueryResp.QueryResult> results = resp.getQueryResults();
         if (CollectionUtil.noItems(results)) {
@@ -360,22 +439,28 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
             document.addMetadata(metadata);
         } else if (metadataObj != null) {
             @SuppressWarnings("unchecked")
-            Map<String, Object> metadata = JSON.parseObject(JSON.toJSONString(metadataObj), Map.class);
+            Map<String, Object> metadata = GSON.fromJson(
+                GSON.toJsonTree(metadataObj),
+                Map.class
+            );
             document.addMetadata(metadata);
         }
 
         return document;
     }
 
-    private List<JSONObject> toMilvusDocuments(List<Document> documents) {
+    List<JsonObject> toMilvusDocuments(List<Document> documents) {
-        List<JSONObject> rows = new ArrayList<JSONObject>(documents.size());
+        List<JsonObject> rows = new ArrayList<JsonObject>(documents.size());
         for (Document doc : documents) {
-            JSONObject row = new JSONObject();
+            JsonObject row = new JsonObject();
-            row.put(FIELD_ID, String.valueOf(doc.getId()));
+            row.addProperty(FIELD_ID, String.valueOf(doc.getId()));
-            row.put(FIELD_CONTENT, doc.getContent());
+            row.addProperty(FIELD_CONTENT, doc.getContent());
-            row.put(FIELD_VECTOR, toFloatList(doc.getVector()));
+            row.add(FIELD_VECTOR, GSON.toJsonTree(toFloatList(doc.getVector())));
             Map<String, Object> metadatas = doc.getMetadataMap();
-            row.put(FIELD_METADATA, metadatas == null ? new JSONObject() : new JSONObject(metadatas));
+            row.add(
+                FIELD_METADATA,
+                metadatas == null ? new JsonObject() : GSON.toJsonTree(metadatas)
+            );
             rows.add(row);
         }
         return rows;
@@ -413,67 +498,175 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
         throw new IllegalStateException("Unable to determine vector dimension for Milvus collection.");
     }
 
-    private void ensureCollectionExists(String collectionName, int dimension) {
+    private void ensureCollectionExists(
-        if (initializedCollections.contains(collectionName)) {
+        MilvusClientV2 client,
+        String collectionName,
+        int dimension
+    ) {
+        if (clientManager.isCollectionInitialized(collectionName)) {
             return;
         }
-        synchronized (initializedCollections) {
+        synchronized (clientManager.initializedCollectionsLock()) {
-            if (initializedCollections.contains(collectionName)) {
+            if (clientManager.isCollectionInitialized(collectionName)) {
                 return;
             }
             Boolean exists = client.hasCollection(HasCollectionReq.builder().collectionName(collectionName).build());
             if (Boolean.TRUE.equals(exists)) {
-                initializedCollections.add(collectionName);
+                clientManager.markCollectionInitialized(collectionName);
                 return;
             }
             if (!config.isAutoCreateCollection()) {
                 throw new IllegalStateException("Milvus collection not found and autoCreateCollection is disabled: " + collectionName);
             }
-            createCollection(collectionName, dimension);
+            createCollection(client, collectionName, dimension);
-            initializedCollections.add(collectionName);
+            clientManager.markCollectionInitialized(collectionName);
         }
     }
 
-    private void ensureCollectionLoaded(String collectionName) {
+    private void ensureCollectionLoaded(
-        if (loadedCollections.contains(collectionName)) {
+        String collectionName,
-            return;
+        long deadlineNanos
-        }
+    ) {
-        synchronized (loadedCollections) {
+        while (!clientManager.isCollectionLoaded(collectionName)) {
-            if (loadedCollections.contains(collectionName)) {
+            MilvusClientManager.CollectionLoadTicket ticket =
-                return;
+                clientManager.beginCollectionLoad(collectionName);
+            if (!ticket.isLeader()) {
+                if (awaitCollectionLoad(
+                    ticket, collectionName, deadlineNanos)) {
+                    return;
+                }
+                continue;
             }
-            boolean loaded = false;
             try {
-                loaded = Boolean.TRUE.equals(client.getLoadState(GetLoadStateReq.builder().collectionName(collectionName).build()));
+                if (clientManager.isCollectionLoaded(collectionName)) {
-            } catch (Exception e) {
+                    clientManager.completeCollectionLoad(ticket);
-                LOG.warn("Milvus getLoadState failed. collection={}, message={}", collectionName, e.getMessage());
+                    return;
+                }
+                withClientBeforeDeadline(deadlineNanos, client -> {
+                    boolean loaded = Boolean.TRUE.equals(client.getLoadState(
+                        GetLoadStateReq.builder()
+                            .collectionName(collectionName)
+                            .build()
+                    ));
+                    if (!loaded) {
+                        client.loadCollection(LoadCollectionReq.builder()
+                            .collectionName(collectionName)
+                            .async(false)
+                            .build());
+                        waitForCollectionLoaded(
+                            client, collectionName, deadlineNanos);
+                    }
+                    return null;
+                });
+                clientManager.completeCollectionLoad(ticket);
+                return;
+            } catch (RuntimeException | Error failure) {
+                clientManager.failCollectionLoad(
+                    ticket, failure, isLeaderLocalAbort(failure));
+                throw failure;
+            } finally {
+                clientManager.endCollectionLoad(ticket);
             }
-
-            if (!loaded) {
-                client.loadCollection(LoadCollectionReq.builder().collectionName(collectionName).build());
-                waitForCollectionLoaded(collectionName);
-            }
-            loadedCollections.add(collectionName);
         }
     }
 
-    private void waitForCollectionLoaded(String collectionName) {
+    private boolean isLeaderLocalAbort(Throwable failure) {
-        long deadline = System.currentTimeMillis() + LOAD_TIMEOUT_MS;
+        if (clientManager.isClosed()) {
-        while (System.currentTimeMillis() < deadline) {
+            return false;
+        }
+        if (failure instanceof StoreTimeoutException
+            || Thread.currentThread().isInterrupted()
+            || Context.current().isCancelled()) {
+            return true;
+        }
+        Throwable current = failure;
+        while (current != null) {
+            if (current instanceof InterruptedException) {
+                return true;
+            }
+            current = current.getCause();
+        }
+        return false;
+    }
+
+    private boolean awaitCollectionLoad(
+        MilvusClientManager.CollectionLoadTicket ticket,
+        String collectionName,
+        long deadlineNanos
+    ) {
+        Context currentContext = Context.current();
+        CompletableFuture<Void> cancelled = new CompletableFuture<Void>();
+        Context.CancellationListener cancellationListener = context ->
+            cancelled.completeExceptionally(new CancellationException(
+                "Milvus search was cancelled"));
+        currentContext.addListener(cancellationListener, Runnable::run);
+        try {
+            CompletableFuture.anyOf(ticket.completion(), cancelled).get(
+                remainingNanos(deadlineNanos, collectionName),
+                TimeUnit.NANOSECONDS
+            );
+            return true;
+        } catch (InterruptedException exception) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException(
+                "Interrupted while loading Milvus collection: "
+                    + collectionName,
+                exception
+            );
+        } catch (TimeoutException exception) {
+            throw timeoutException(collectionName, exception);
+        } catch (ExecutionException exception) {
+            Throwable cause = exception.getCause();
+            if (cause instanceof MilvusClientManager
+                .RetryableCollectionLoadException) {
+                remainingNanos(deadlineNanos, collectionName);
+                return false;
+            }
+            if (cause instanceof RuntimeException runtimeException) {
+                throw runtimeException;
+            }
+            if (cause instanceof Error error) {
+                throw error;
+            }
+            throw new IllegalStateException(
+                "Unable to load Milvus collection: " + collectionName,
+                cause
+            );
+        } catch (CancellationException exception) {
+            throw new IllegalStateException(
+                "Milvus collection load was cancelled: " + collectionName,
+                exception
+            );
+        } finally {
+            currentContext.removeListener(cancellationListener);
+        }
+    }
+
+    private void waitForCollectionLoaded(
+        MilvusClientV2 client,
+        String collectionName,
+        long deadlineNanos
+    ) {
+        while (true) {
+            long remainingNanos = remainingNanos(
+                deadlineNanos, collectionName);
             if (Boolean.TRUE.equals(client.getLoadState(GetLoadStateReq.builder().collectionName(collectionName).build()))) {
                 return;
             }
             try {
-                Thread.sleep(LOAD_POLL_INTERVAL_MS);
+                long sleepMillis = Math.min(
+                    LOAD_POLL_INTERVAL_MS,
+                    Math.max(1L, TimeUnit.NANOSECONDS.toMillis(remainingNanos))
+                );
+                Thread.sleep(sleepMillis);
             } catch (InterruptedException e) {
                 Thread.currentThread().interrupt();
                 throw new IllegalStateException("Interrupted while loading Milvus collection: " + collectionName, e);
             }
         }
-        throw new IllegalStateException("Timeout waiting for Milvus collection loaded: " + collectionName);
     }
 
-    private boolean isCollectionNotLoaded(Exception e) {
+    private boolean isCollectionNotLoaded(Throwable e) {
         Throwable current = e;
         while (current != null) {
             String message = current.getMessage();
@@ -485,7 +678,91 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
         return false;
     }
 
-    private void createCollection(String collectionName, int dimension) {
+    private <T> T withClientBeforeDeadline(
+        long deadlineNanos,
+        Function<MilvusClientV2, T> operation
+    ) {
+        long remainingNanos = remainingNanos(deadlineNanos, null);
+        long poolWaitNanos = TimeUnit.MILLISECONDS.toNanos(
+            config.getPoolMaxWaitMillis());
+        try {
+            return clientManager.withClient(
+                Duration.ofNanos(Math.min(remainingNanos, poolWaitNanos)),
+                operation
+            );
+        } catch (RuntimeException exception) {
+            if (deadlineExpired(deadlineNanos, exception)) {
+                throw timeoutException(null, exception);
+            }
+            throw exception;
+        }
+    }
+
+    private long resolveSearchTimeoutMillis(StoreOptions options) {
+        long timeoutMillis = config.getSearchTimeoutMillis();
+        Long requestedTimeoutMillis = options.getTimeoutMillis();
+        if (requestedTimeoutMillis != null) {
+            timeoutMillis = Math.min(timeoutMillis, requestedTimeoutMillis);
+        }
+        if (timeoutMillis <= DEADLINE_SAFETY_MARGIN_MS) {
+            throw new StoreTimeoutException(
+                "Insufficient time remaining for Milvus search"
+            );
+        }
+        return timeoutMillis;
+    }
+
+    private static long deadlineAfterMillis(long timeoutMillis) {
+        long now = System.nanoTime();
+        long timeoutNanos = TimeUnit.MILLISECONDS.toNanos(timeoutMillis);
+        if (now > Long.MAX_VALUE - timeoutNanos) {
+            return Long.MAX_VALUE;
+        }
+        return now + timeoutNanos;
+    }
+
+    private static long remainingNanos(
+        long deadlineNanos,
+        String collectionName
+    ) {
+        if (deadlineNanos == Long.MAX_VALUE) {
+            return Long.MAX_VALUE;
+        }
+        long remaining = deadlineNanos - System.nanoTime();
+        if (remaining <= 0L) {
+            throw timeoutException(collectionName, null);
+        }
+        return remaining;
+    }
+
+    private static boolean deadlineExpired(
+        long deadlineNanos,
+        Throwable failure
+    ) {
+        if (deadlineNanos != Long.MAX_VALUE
+            && System.nanoTime() >= deadlineNanos) {
+            return true;
+        }
+        Throwable cancellationCause = Context.current().cancellationCause();
+        return cancellationCause instanceof TimeoutException
+            || Status.fromThrowable(failure).getCode()
+                == Status.Code.DEADLINE_EXCEEDED;
+    }
+
+    private static StoreTimeoutException timeoutException(
+        String collectionName,
+        Throwable cause
+    ) {
+        String suffix = StringUtil.hasText(collectionName)
+            ? ": " + collectionName
+            : "";
+        return new StoreTimeoutException(
+            "Timeout waiting for Milvus search" + suffix,
+            cause
+        );
+    }
+
+    private void createCollection(MilvusClientV2 client, String collectionName, int dimension) {
         List<CreateCollectionReq.FieldSchema> fieldSchemaList = new ArrayList<CreateCollectionReq.FieldSchema>();
         fieldSchemaList.add(CreateCollectionReq.FieldSchema.builder()
             .name(FIELD_ID)
@@ -531,31 +808,83 @@ public class MilvusVectorStore extends DocumentStore implements AutoCloseable {
             .indexParams(indexParams)
             .build();
         client.createCollection(createCollectionReq);
-        ensureCollectionLoaded(collectionName);
+        ensureCollectionLoadedForWrite(client, collectionName);
     }
 
-    public MilvusClientV2 getClient() {
+    private void ensureCollectionLoadedForWrite(
-        return client;
+        MilvusClientV2 client,
+        String collectionName
+    ) {
+        if (clientManager.isCollectionLoaded(collectionName)) {
+            return;
+        }
+        boolean loaded = Boolean.TRUE.equals(client.getLoadState(
+            GetLoadStateReq.builder().collectionName(collectionName).build()));
+        if (!loaded) {
+            client.loadCollection(LoadCollectionReq.builder()
+                .collectionName(collectionName)
+                .async(false)
+                .build());
+            waitForCollectionLoaded(
+                client,
+                collectionName,
+                deadlineAfterMillis(LOAD_TIMEOUT_MS)
+            );
+        }
+        clientManager.markCollectionLoaded(collectionName);
     }
 
     public boolean checkAvailable() {
         try {
-            return client.hasCollection(HasCollectionReq.builder()
+            return clientManager.withClient(client -> client.hasCollection(
-                .collectionName("__milvus_boot_probe__")
+                HasCollectionReq.builder()
-                .build()) != null;
+                    .collectionName("__milvus_boot_probe__")
+                    .build()
+            )) != null;
         } catch (Exception e) {
             LOG.warn("Milvus availability check failed. message={}", e.getMessage());
             return false;
         }
     }
 
+    /**
+     * Returns a compatibility client for integrations that used the pre-pool API.
+     * Prefer store operations so pooled lifecycle management remains automatic.
+     */
+    @Deprecated
+    public synchronized MilvusClientV2 getClient() {
+        if (closed) {
+            throw new IllegalStateException("Milvus vector store is closed");
+        }
+        if (compatibilityClient == null) {
+            compatibilityClient = new MilvusClientV2(
+                MilvusClientManager.buildConnectConfig(config)
+            );
+        }
+        return compatibilityClient;
+    }
+
     @Override
     public void close() {
-        try {
+        MilvusClientV2 legacyClient;
-            client.close(1L);
+        synchronized (this) {
-        } catch (InterruptedException e) {
+            if (closed) {
-            Thread.currentThread().interrupt();
+                return;
-            LOG.warn("Interrupted while closing Milvus client. uri={}", config.getUri(), e);
+            }
+            closed = true;
+            legacyClient = compatibilityClient;
+            compatibilityClient = null;
+        }
+        if (legacyClient != null) {
+            try {
+                legacyClient.close(1L);
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+                LOG.warn("Interrupted while closing compatibility Milvus client", exception);
+            }
+        }
+        if (ownsClientManager) {
+            clientManager.close();
         }
     }
 }

easy-agents-store/easy-agents-store-milvus/src/main/java/com/easyagents/store/milvus/MilvusVectorStoreConfig.java

@@ -30,6 +30,14 @@ public class MilvusVectorStoreConfig implements DocumentStoreConfig {
     private String password;
     private String defaultCollectionName;
     private boolean autoCreateCollection = true;
+    private int poolMaxTotal = 8;
+    private int poolMaxTotalPerKey = 8;
+    private int poolMaxIdlePerKey = 4;
+    private int poolMinIdlePerKey = 1;
+    private long poolMaxWaitMillis = 3_000L;
+    private long poolEvictionIntervalMillis = 60_000L;
+    private long poolMinEvictableIdleMillis = 300_000L;
+    private long searchTimeoutMillis = 10_000L;
 
     public String getUri() {
         return uri;
@@ -87,6 +95,70 @@ public class MilvusVectorStoreConfig implements DocumentStoreConfig {
         this.autoCreateCollection = autoCreateCollection;
     }
 
+    public int getPoolMaxTotal() {
+        return poolMaxTotal;
+    }
+
+    public void setPoolMaxTotal(int poolMaxTotal) {
+        this.poolMaxTotal = poolMaxTotal;
+    }
+
+    public int getPoolMaxTotalPerKey() {
+        return poolMaxTotalPerKey;
+    }
+
+    public void setPoolMaxTotalPerKey(int poolMaxTotalPerKey) {
+        this.poolMaxTotalPerKey = poolMaxTotalPerKey;
+    }
+
+    public int getPoolMaxIdlePerKey() {
+        return poolMaxIdlePerKey;
+    }
+
+    public void setPoolMaxIdlePerKey(int poolMaxIdlePerKey) {
+        this.poolMaxIdlePerKey = poolMaxIdlePerKey;
+    }
+
+    public int getPoolMinIdlePerKey() {
+        return poolMinIdlePerKey;
+    }
+
+    public void setPoolMinIdlePerKey(int poolMinIdlePerKey) {
+        this.poolMinIdlePerKey = poolMinIdlePerKey;
+    }
+
+    public long getPoolMaxWaitMillis() {
+        return poolMaxWaitMillis;
+    }
+
+    public void setPoolMaxWaitMillis(long poolMaxWaitMillis) {
+        this.poolMaxWaitMillis = poolMaxWaitMillis;
+    }
+
+    public long getPoolEvictionIntervalMillis() {
+        return poolEvictionIntervalMillis;
+    }
+
+    public void setPoolEvictionIntervalMillis(long poolEvictionIntervalMillis) {
+        this.poolEvictionIntervalMillis = poolEvictionIntervalMillis;
+    }
+
+    public long getPoolMinEvictableIdleMillis() {
+        return poolMinEvictableIdleMillis;
+    }
+
+    public void setPoolMinEvictableIdleMillis(long poolMinEvictableIdleMillis) {
+        this.poolMinEvictableIdleMillis = poolMinEvictableIdleMillis;
+    }
+
+    public long getSearchTimeoutMillis() {
+        return searchTimeoutMillis;
+    }
+
+    public void setSearchTimeoutMillis(long searchTimeoutMillis) {
+        this.searchTimeoutMillis = searchTimeoutMillis;
+    }
+
     @Override
     public boolean checkAvailable() {
         return StringUtil.hasText(this.uri);

easy-agents-store/easy-agents-store-milvus/src/test/java/com/easyagents/store/milvus/MilvusVectorStoreCompatibilityTest.java

@@ -0,0 +1,92 @@
+package com.easyagents.store.milvus;
+
+import com.easyagents.core.document.Document;
+import com.google.gson.JsonObject;
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Milvus SDK 2.3.11 数据适配回归测试。
+ */
+public class MilvusVectorStoreCompatibilityTest {
+
+    @Test
+    public void shouldConvertRowsToGsonWithoutLosingMetadata() {
+        MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+        config.setUri("http://127.0.0.1:19530");
+        config.setDefaultCollectionName("test");
+        MilvusVectorStore store = new MilvusVectorStore(config);
+        try {
+            Document document = Document.of("正文");
+            document.setId("chunk-1");
+            document.setVector(new float[] { 0.25F, 0.75F });
+            document.addMetadata(Map.of("knowledgeId", "knowledge-1"));
+
+            List<JsonObject> rows = store.toMilvusDocuments(List.of(document));
+
+            Assert.assertEquals(1, rows.size());
+            Assert.assertEquals("chunk-1", rows.get(0).get("id").getAsString());
+            Assert.assertEquals("正文", rows.get(0).get("content").getAsString());
+            Assert.assertEquals(2, rows.get(0).getAsJsonArray("vector").size());
+            Assert.assertEquals(
+                "knowledge-1",
+                rows.get(0).getAsJsonObject("metadata").get("knowledgeId").getAsString()
+            );
+        } finally {
+            store.close();
+        }
+    }
+
+    @Test
+    public void shouldNormalizeUriWithoutExposingCredentialsInPoolKey() {
+        Assert.assertEquals(
+            "http://127.0.0.1:19530",
+            MilvusClientManager.normalizeAndValidateUri("127.0.0.1:19530")
+        );
+    }
+
+    @Test
+    public void shouldRebuildPoolOnlyWhenConnectionSettingsChange() {
+        MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+        config.setUri("http://127.0.0.1:19530");
+        MilvusClientManager manager = new MilvusClientManager(config);
+        try {
+            Assert.assertFalse(manager.reconfigureIfNeeded(config));
+
+            config.setPoolMaxTotal(9);
+
+            Assert.assertTrue(manager.reconfigureIfNeeded(config));
+            Assert.assertFalse(manager.reconfigureIfNeeded(config));
+        } finally {
+            manager.close();
+        }
+    }
+
+    @Test
+    public void shouldPreserveCosineScoreNormalization() {
+        Assert.assertEquals(Double.valueOf(1.0D), MilvusVectorStore.normalizeScore(1.0F));
+        Assert.assertEquals(Double.valueOf(0.5D), MilvusVectorStore.normalizeScore(0.0F));
+        Assert.assertEquals(Double.valueOf(0.0D), MilvusVectorStore.normalizeScore(-1.0F));
+        Assert.assertNull(MilvusVectorStore.normalizeScore(null));
+    }
+
+    @Test
+    public void shouldRejectCompatibilityClientAfterStoreCloses() {
+        MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+        config.setUri("http://127.0.0.1:19530");
+        MilvusVectorStore store = new MilvusVectorStore(config);
+
+        store.close();
+
+        try {
+            store.getClient();
+            Assert.fail("A closed store must not recreate a compatibility client");
+        } catch (IllegalStateException expected) {
+            Assert.assertEquals(
+                "Milvus vector store is closed", expected.getMessage());
+        }
+    }
+}

easy-agents-store/easy-agents-store-milvus/src/test/java/com/easyagents/store/milvus/MilvusVectorStoreConfigTest.java

@@ -34,4 +34,24 @@ public class MilvusVectorStoreConfigTest {
         config.setPassword("Milvus");
         Assert.assertTrue(config.checkAvailable());
     }
+
+    @Test
+    public void testPoolDefaultsAreBounded() {
+        MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+        Assert.assertEquals(8, config.getPoolMaxTotal());
+        Assert.assertEquals(8, config.getPoolMaxTotalPerKey());
+        Assert.assertEquals(4, config.getPoolMaxIdlePerKey());
+        Assert.assertEquals(1, config.getPoolMinIdlePerKey());
+        Assert.assertEquals(3_000L, config.getPoolMaxWaitMillis());
+        Assert.assertEquals(300_000L, config.getPoolMinEvictableIdleMillis());
+        Assert.assertEquals(10_000L, config.getSearchTimeoutMillis());
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testSearchTimeoutMustLeaveCleanupMargin() {
+        MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+        config.setUri("http://127.0.0.1:19530");
+        config.setSearchTimeoutMillis(200L);
+        new MilvusVectorStore(config);
+    }
 }

easy-agents-store/easy-agents-store-milvus/src/test/java/com/easyagents/store/milvus/MilvusVectorStoreGrpcTest.java

@@ -0,0 +1,935 @@
+package com.easyagents.store.milvus;
+
+import com.easyagents.core.document.Document;
+import com.easyagents.core.store.SearchWrapper;
+import com.easyagents.core.store.StoreOptions;
+import com.easyagents.core.store.StoreTimeoutException;
+import io.grpc.Context;
+import io.grpc.Server;
+import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
+import io.grpc.stub.ServerCallStreamObserver;
+import io.grpc.stub.StreamObserver;
+import io.milvus.grpc.CheckHealthRequest;
+import io.milvus.grpc.CheckHealthResponse;
+import io.milvus.grpc.ConnectRequest;
+import io.milvus.grpc.ConnectResponse;
+import io.milvus.grpc.CollectionSchema;
+import io.milvus.grpc.DataType;
+import io.milvus.grpc.DescribeCollectionRequest;
+import io.milvus.grpc.DescribeCollectionResponse;
+import io.milvus.grpc.ErrorCode;
+import io.milvus.grpc.FieldSchema;
+import io.milvus.grpc.GetLoadStateRequest;
+import io.milvus.grpc.GetLoadStateResponse;
+import io.milvus.grpc.ListDatabasesRequest;
+import io.milvus.grpc.ListDatabasesResponse;
+import io.milvus.grpc.LoadCollectionRequest;
+import io.milvus.grpc.LoadState;
+import io.milvus.grpc.MilvusServiceGrpc;
+import io.milvus.grpc.QueryRequest;
+import io.milvus.grpc.QueryResults;
+import io.milvus.v2.client.MilvusClientV2;
+import io.milvus.v2.service.vector.request.QueryReq;
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BooleanSupplier;
+
+public class MilvusVectorStoreGrpcTest {
+
+    private static final long AWAIT_SECONDS = 5L;
+
+    @Test(timeout = 10_000L)
+    public void shouldUseOneSdkAttemptAndKeepClientReusable() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 2_000L)) {
+            fixture.manager.markCollectionLoaded("docs");
+            Assert.assertEquals(
+                0L,
+                MilvusClientManager.buildConnectConfig(fixture.config).getRpcDeadlineMs()
+            );
+
+            server.failQueriesWithUnavailable();
+            assertSearchFails(fixture.store, "docs");
+
+            Assert.assertEquals(1, server.queryCalls.get());
+            Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+            Assert.assertEquals(1, fixture.manager.getIdleClientCount());
+
+            server.succeedQueries();
+            Assert.assertTrue(search(fixture.store, "docs").isEmpty());
+            Assert.assertEquals(2, server.queryCalls.get());
+            Assert.assertEquals(1, server.connectCalls.get());
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldReleaseAndReuseClientAfterContextDeadline() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 1_000L)) {
+            fixture.manager.markCollectionLoaded("docs");
+            fixture.manager.withClient(client -> client);
+            QueryBlock block = server.blockQueries();
+            ExecutorService executor = Executors.newSingleThreadExecutor();
+            try {
+                Future<List<Document>> search = executor.submit(() ->
+                    search(fixture.store, "docs"));
+
+                block.awaitEntered();
+                block.awaitCancelled();
+                Throwable failure = futureFailure(search);
+                Assert.assertTrue(failure.toString(),
+                    failure instanceof StoreTimeoutException);
+
+                Assert.assertTrue(server.querySawDeadline.get());
+                Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+                Assert.assertEquals(1, fixture.manager.getIdleClientCount());
+
+                server.succeedQueries();
+                Assert.assertTrue(search(fixture.store, "docs").isEmpty());
+                Assert.assertEquals(1, server.connectCalls.get());
+            } finally {
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldReleaseAndReuseClientAfterThreadInterrupt() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 5_000L)) {
+            fixture.manager.markCollectionLoaded("docs");
+            fixture.manager.withClient(client -> client);
+            QueryBlock block = server.blockQueries();
+            CountDownLatch finished = new CountDownLatch(1);
+            AtomicReference<Throwable> failure = new AtomicReference<>();
+            AtomicBoolean interrupted = new AtomicBoolean();
+            Thread searchThread = new Thread(() -> {
+                try {
+                    search(fixture.store, "docs");
+                } catch (Throwable exception) {
+                    failure.set(exception);
+                } finally {
+                    interrupted.set(Thread.currentThread().isInterrupted());
+                    finished.countDown();
+                }
+            }, "milvus-interrupt-test");
+            searchThread.start();
+
+            block.awaitEntered();
+            searchThread.interrupt();
+            Assert.assertTrue(finished.await(AWAIT_SECONDS, TimeUnit.SECONDS));
+            block.awaitCancelled();
+
+            Assert.assertNotNull(failure.get());
+            Assert.assertTrue(interrupted.get());
+            Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+            Assert.assertEquals(1, fixture.manager.getIdleClientCount());
+
+            server.succeedQueries();
+            Assert.assertTrue(search(fixture.store, "docs").isEmpty());
+            Assert.assertEquals(1, server.connectCalls.get());
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldKeepPoolAfterOrdinaryBusinessFailure() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 2_000L)) {
+            MilvusClientV2 first = fixture.manager.withClient(client -> client);
+
+            try {
+                fixture.manager.withClient(client -> {
+                    throw new IllegalArgumentException("synthetic business failure");
+                });
+                Assert.fail("The business failure must be propagated");
+            } catch (IllegalArgumentException expected) {
+                Assert.assertEquals("synthetic business failure", expected.getMessage());
+            }
+
+            MilvusClientV2 second = fixture.manager.withClient(client -> client);
+            Assert.assertSame(first, second);
+            Assert.assertEquals(1, server.connectCalls.get());
+            Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+            Assert.assertEquals(1, fixture.manager.getIdleClientCount());
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldAttachContextToEveryClientOperation() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 2_000L)) {
+            Context callerContext = Context.current();
+            Context operationContext = fixture.manager.withClient(client ->
+                Context.current());
+
+            Assert.assertNotSame(callerContext, operationContext);
+            Assert.assertTrue(operationContext.isCancelled());
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldCapPoolWaitByRemainingSearchDeadline() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 5_000L)) {
+            fixture.manager.markCollectionLoaded("docs");
+            ExecutorService executor = Executors.newSingleThreadExecutor();
+            CountDownLatch borrowed = new CountDownLatch(1);
+            CountDownLatch release = new CountDownLatch(1);
+            try {
+                Future<?> holder = executor.submit(() ->
+                    fixture.manager.withClient(client -> {
+                        borrowed.countDown();
+                        try {
+                            Assert.assertTrue(release.await(
+                                AWAIT_SECONDS, TimeUnit.SECONDS));
+                        } catch (InterruptedException exception) {
+                            Thread.currentThread().interrupt();
+                            throw new IllegalStateException(exception);
+                        }
+                        return null;
+                    }));
+                Assert.assertTrue(borrowed.await(
+                    AWAIT_SECONDS, TimeUnit.SECONDS));
+
+                StoreOptions options = StoreOptions.ofCollectionName("docs");
+                options.setTimeoutMillis(500L);
+                long startedAt = System.nanoTime();
+                try {
+                    search(fixture.store, options);
+                    Assert.fail("Pool wait must respect the remaining deadline");
+                } catch (RuntimeException expected) {
+                    Assert.assertTrue(expected.toString(),
+                        expected instanceof StoreTimeoutException);
+                    long elapsedMillis = TimeUnit.NANOSECONDS.toMillis(
+                        System.nanoTime() - startedAt);
+                    Assert.assertTrue("elapsedMillis=" + elapsedMillis,
+                        elapsedMillis < 800L);
+                }
+
+                release.countDown();
+                holder.get(AWAIT_SECONDS, TimeUnit.SECONDS);
+                Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+            } finally {
+                release.countDown();
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldInvalidateOnlyClosedClient() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 2, 2_000L)) {
+            ExecutorService executor = Executors.newSingleThreadExecutor();
+            CountDownLatch firstBorrowed = new CountDownLatch(1);
+            CountDownLatch releaseFirst = new CountDownLatch(1);
+            try {
+                Future<?> holder = executor.submit(() ->
+                    fixture.manager.withClient(client -> {
+                        firstBorrowed.countDown();
+                        try {
+                            Assert.assertTrue(releaseFirst.await(
+                                AWAIT_SECONDS, TimeUnit.SECONDS));
+                        } catch (InterruptedException exception) {
+                            Thread.currentThread().interrupt();
+                            throw new IllegalStateException(exception);
+                        }
+                        return null;
+                    }));
+                Assert.assertTrue(firstBorrowed.await(
+                    AWAIT_SECONDS, TimeUnit.SECONDS));
+                fixture.manager.withClient(client -> client);
+                releaseFirst.countDown();
+                holder.get(AWAIT_SECONDS, TimeUnit.SECONDS);
+                Assert.assertEquals(2, fixture.manager.getIdleClientCount());
+
+                AtomicReference<MilvusClientV2> closed = new AtomicReference<>();
+                try {
+                    fixture.manager.withClient(client -> {
+                        closed.set(client);
+                        client.close();
+                        throw new IllegalStateException("synthetic closed client");
+                    });
+                    Assert.fail("The closed-client failure must be propagated");
+                } catch (IllegalStateException expected) {
+                    Assert.assertEquals(
+                        "synthetic closed client", expected.getMessage());
+                }
+
+                Assert.assertEquals(1, fixture.manager.getIdleClientCount());
+                MilvusClientV2 remaining = fixture.manager.withClient(
+                    client -> client);
+                Assert.assertNotSame(closed.get(), remaining);
+                Assert.assertEquals(2, server.connectCalls.get());
+            } finally {
+                releaseFirst.countDown();
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldLoadSameCollectionOnlyOnce() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 2, 3_000L)) {
+            LoadGate gate = server.blockLoad("shared");
+            ExecutorService executor = Executors.newFixedThreadPool(2);
+            try {
+                Future<List<Document>> first = executor.submit(() ->
+                    search(fixture.store, "shared"));
+                gate.awaitEntered();
+
+                Future<List<Document>> second = executor.submit(() ->
+                    search(fixture.store, "shared"));
+                MilvusClientManager.CollectionLoadTicket follower =
+                    fixture.manager.beginCollectionLoad("shared");
+                Assert.assertFalse(follower.isLeader());
+                awaitCondition(() -> follower.completion().getNumberOfDependents() > 0);
+
+                Assert.assertEquals(1, server.loadCalls("shared"));
+                Assert.assertEquals(1, fixture.manager.getActiveClientCount());
+                gate.release();
+
+                Assert.assertTrue(first.get(AWAIT_SECONDS, TimeUnit.SECONDS).isEmpty());
+                Assert.assertTrue(second.get(AWAIT_SECONDS, TimeUnit.SECONDS).isEmpty());
+                Assert.assertEquals(1, server.loadCalls("shared"));
+                Assert.assertTrue(fixture.manager.isCollectionLoaded("shared"));
+            } finally {
+                gate.release();
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldRemoveLeaderTicketAfterLateCacheHit() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer()) {
+            MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+            config.setUri(server.uri());
+            config.setDefaultCollectionName("docs");
+            config.setPoolMinIdlePerKey(0);
+            config.setSearchTimeoutMillis(2_000L);
+            RacingMilvusClientManager manager =
+                new RacingMilvusClientManager(config, "late-hit");
+            MilvusVectorStore store = new MilvusVectorStore(config, manager);
+            try {
+                Assert.assertTrue(search(store, "late-hit").isEmpty());
+                manager.markCollectionUnloaded("late-hit");
+
+                Assert.assertTrue(search(store, "late-hit").isEmpty());
+
+                Assert.assertEquals(1, server.loadCalls("late-hit"));
+                Assert.assertTrue(manager.isCollectionLoaded("late-hit"));
+            } finally {
+                store.close();
+                manager.close();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldLoadDifferentCollectionsInParallel() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 2, 3_000L)) {
+            LoadGate firstGate = server.blockLoad("first");
+            LoadGate secondGate = server.blockLoad("second");
+            ExecutorService executor = Executors.newFixedThreadPool(2);
+            try {
+                Future<List<Document>> first = executor.submit(() ->
+                    search(fixture.store, "first"));
+                Future<List<Document>> second = executor.submit(() ->
+                    search(fixture.store, "second"));
+
+                firstGate.awaitEntered();
+                secondGate.awaitEntered();
+                Assert.assertEquals(2, server.activeLoads.get());
+                Assert.assertEquals(2, server.maxConcurrentLoads.get());
+                Assert.assertEquals(2, fixture.manager.getActiveClientCount());
+
+                firstGate.release();
+                secondGate.release();
+                Assert.assertTrue(first.get(AWAIT_SECONDS, TimeUnit.SECONDS).isEmpty());
+                Assert.assertTrue(second.get(AWAIT_SECONDS, TimeUnit.SECONDS).isEmpty());
+            } finally {
+                firstGate.release();
+                secondGate.release();
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldReelectFollowerAfterLoadLeaderTimesOut() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 3_000L)) {
+            LoadGate gate = server.blockLoad("reelect");
+            ExecutorService executor = Executors.newFixedThreadPool(2);
+            try {
+                StoreOptions shortBudget =
+                    StoreOptions.ofCollectionName("reelect");
+                shortBudget.setTimeoutMillis(500L);
+                Future<List<Document>> first = executor.submit(() ->
+                    search(fixture.store, shortBudget));
+                gate.awaitEntered();
+
+                Future<List<Document>> second = executor.submit(() ->
+                    search(fixture.store, "reelect"));
+                awaitCondition(() -> server.loadCalls("reelect") == 2);
+                gate.release();
+
+                Throwable firstFailure = futureFailure(first);
+                Assert.assertTrue(firstFailure.toString(),
+                    firstFailure instanceof StoreTimeoutException);
+                Assert.assertTrue(second.get(
+                    AWAIT_SECONDS, TimeUnit.SECONDS).isEmpty());
+                Assert.assertEquals(2, server.loadCalls("reelect"));
+                Assert.assertTrue(
+                    fixture.manager.isCollectionLoaded("reelect"));
+            } finally {
+                gate.release();
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldCancelWaitingFollowerWithoutBorrowingClient() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 5_000L)) {
+            MilvusClientManager.CollectionLoadTicket leader =
+                fixture.manager.beginCollectionLoad("waiting");
+            CountDownLatch finished = new CountDownLatch(1);
+            AtomicReference<Throwable> failure = new AtomicReference<>();
+            Thread follower = new Thread(() -> {
+                try {
+                    search(fixture.store, "waiting");
+                } catch (Throwable exception) {
+                    failure.set(exception);
+                } finally {
+                    finished.countDown();
+                }
+            }, "milvus-load-follower-test");
+            try {
+                follower.start();
+                awaitCondition(() -> leader.completion().getNumberOfDependents() > 0);
+
+                Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+                Assert.assertEquals(0, server.connectCalls.get());
+                follower.interrupt();
+                Assert.assertTrue(finished.await(AWAIT_SECONDS, TimeUnit.SECONDS));
+
+                Assert.assertNotNull(failure.get());
+                Assert.assertFalse(leader.completion().isDone());
+                Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+                Assert.assertEquals(0, server.connectCalls.get());
+            } finally {
+                follower.interrupt();
+                fixture.manager.failCollectionLoad(
+                    leader, new IllegalStateException("test cleanup"), false);
+                fixture.manager.endCollectionLoad(leader);
+            }
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldRecoverAfterCollectionLoadFailure() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 2_000L)) {
+            server.failNextLoad("recoverable");
+            LoadGate gate = server.blockLoad("recoverable");
+            ExecutorService executor = Executors.newFixedThreadPool(2);
+            try {
+                Future<List<Document>> first = executor.submit(() ->
+                    search(fixture.store, "recoverable"));
+                gate.awaitEntered();
+                Future<List<Document>> second = executor.submit(() ->
+                    search(fixture.store, "recoverable"));
+                MilvusClientManager.CollectionLoadTicket follower =
+                    fixture.manager.beginCollectionLoad("recoverable");
+                Assert.assertFalse(follower.isLeader());
+                awaitCondition(() ->
+                    follower.completion().getNumberOfDependents() > 0);
+                gate.release();
+
+                assertFutureFails(first);
+                assertFutureFails(second);
+            } finally {
+                gate.release();
+                executor.shutdownNow();
+            }
+
+            Assert.assertEquals(1, server.loadCalls("recoverable"));
+            Assert.assertFalse(fixture.manager.isCollectionLoaded("recoverable"));
+            Assert.assertEquals(0, fixture.manager.getActiveClientCount());
+            Assert.assertEquals(1, fixture.manager.getIdleClientCount());
+
+            Assert.assertTrue(search(fixture.store, "recoverable").isEmpty());
+            Assert.assertEquals(2, server.loadCalls("recoverable"));
+            Assert.assertTrue(fixture.manager.isCollectionLoaded("recoverable"));
+            Assert.assertEquals(1, server.connectCalls.get());
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldCancelActiveRpcWhenManagerCloses() throws Exception {
+        FakeMilvusServer server = new FakeMilvusServer();
+        Fixture fixture = new Fixture(server, 1, 5_000L);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            fixture.manager.markCollectionLoaded("docs");
+            QueryBlock block = server.blockQueries();
+            Future<?> operation = executor.submit(() ->
+                query(fixture.manager));
+            block.awaitEntered();
+
+            Future<?> close = executor.submit(fixture.manager::close);
+            block.awaitCancelled();
+            close.get(AWAIT_SECONDS, TimeUnit.SECONDS);
+            assertFutureFails(operation);
+
+            try {
+                fixture.manager.withClient(client -> null);
+                Assert.fail("A closed manager must reject client borrows");
+            } catch (IllegalStateException expected) {
+                Assert.assertEquals("Milvus client pool is closed", expected.getMessage());
+            }
+        } finally {
+            executor.shutdownNow();
+            fixture.close();
+            server.close();
+        }
+    }
+
+    @Test(timeout = 10_000L)
+    public void shouldCancelActiveRpcWhenManagerReconfigures() throws Exception {
+        try (FakeMilvusServer server = new FakeMilvusServer();
+             Fixture fixture = new Fixture(server, 1, 5_000L)) {
+            ExecutorService executor = Executors.newFixedThreadPool(2);
+            try {
+                QueryBlock block = server.blockQueries();
+                Future<?> operation = executor.submit(() ->
+                    query(fixture.manager));
+                block.awaitEntered();
+
+                fixture.config.setPoolMaxTotal(2);
+                Future<Boolean> reconfigure = executor.submit(() ->
+                    fixture.manager.reconfigureIfNeeded(fixture.config));
+                block.awaitCancelled();
+
+                Assert.assertTrue(reconfigure.get(
+                    AWAIT_SECONDS, TimeUnit.SECONDS));
+                assertFutureFails(operation);
+
+                server.succeedQueries();
+                query(fixture.manager);
+            } finally {
+                executor.shutdownNow();
+            }
+        }
+    }
+
+    private static Object query(MilvusClientManager manager) {
+        return manager.withClient(client -> client.query(
+            QueryReq.builder()
+                .collectionName("docs")
+                .filter("id == \"synthetic-id\"")
+                .outputFields(List.of("id"))
+                .build()
+        ));
+    }
+
+    private static List<Document> search(MilvusVectorStore store, String collection) {
+        return search(store, StoreOptions.ofCollectionName(collection));
+    }
+
+    private static List<Document> search(
+        MilvusVectorStore store,
+        StoreOptions options
+    ) {
+        SearchWrapper wrapper = new SearchWrapper();
+        wrapper.setWithVector(false);
+        wrapper.eq("id", "synthetic-id");
+        return store.search(wrapper, options);
+    }
+
+    private static void assertSearchFails(MilvusVectorStore store, String collection) {
+        try {
+            search(store, collection);
+            Assert.fail("The synthetic Milvus failure must be propagated");
+        } catch (RuntimeException expected) {
+            Assert.assertNotNull(expected);
+        }
+    }
+
+    private static void assertFutureFails(Future<?> future)
+        throws InterruptedException, TimeoutException {
+        futureFailure(future);
+    }
+
+    private static Throwable futureFailure(Future<?> future)
+        throws InterruptedException, TimeoutException {
+        try {
+            future.get(AWAIT_SECONDS, TimeUnit.SECONDS);
+            Assert.fail("The synthetic Milvus failure must be propagated");
+        } catch (ExecutionException expected) {
+            Assert.assertNotNull(expected.getCause());
+            return expected.getCause();
+        }
+        throw new AssertionError("Expected future to fail");
+    }
+
+    private static void awaitCondition(BooleanSupplier condition)
+        throws InterruptedException, TimeoutException {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(AWAIT_SECONDS);
+        while (!condition.getAsBoolean()) {
+            if (System.nanoTime() >= deadline) {
+                throw new TimeoutException("Timed out waiting for test condition");
+            }
+            if (Thread.interrupted()) {
+                throw new InterruptedException();
+            }
+            Thread.onSpinWait();
+        }
+    }
+
+    private static final class Fixture implements AutoCloseable {
+
+        private final MilvusVectorStoreConfig config;
+        private final MilvusClientManager manager;
+        private final MilvusVectorStore store;
+
+        private Fixture(FakeMilvusServer server, int poolSize, long searchTimeoutMillis) {
+            config = new MilvusVectorStoreConfig();
+            config.setUri(server.uri());
+            config.setDefaultCollectionName("docs");
+            config.setPoolMaxTotal(poolSize);
+            config.setPoolMaxTotalPerKey(poolSize);
+            config.setPoolMaxIdlePerKey(poolSize);
+            config.setPoolMinIdlePerKey(0);
+            config.setPoolMaxWaitMillis(1_000L);
+            config.setSearchTimeoutMillis(searchTimeoutMillis);
+            manager = new MilvusClientManager(config);
+            store = new MilvusVectorStore(config, manager);
+        }
+
+        @Override
+        public void close() {
+            store.close();
+            manager.close();
+        }
+    }
+
+    private static final class RacingMilvusClientManager
+        extends MilvusClientManager {
+
+        private final String collectionName;
+        private final AtomicInteger observations = new AtomicInteger();
+
+        private RacingMilvusClientManager(
+            MilvusVectorStoreConfig config,
+            String collectionName
+        ) {
+            super(config);
+            this.collectionName = collectionName;
+        }
+
+        @Override
+        boolean isCollectionLoaded(String requestedCollectionName) {
+            if (collectionName.equals(requestedCollectionName)) {
+                int observation = observations.getAndIncrement();
+                if (observation == 0) {
+                    return false;
+                }
+                if (observation == 1) {
+                    return true;
+                }
+            }
+            return super.isCollectionLoaded(requestedCollectionName);
+        }
+    }
+
+    private static final class QueryBlock {
+
+        private final CountDownLatch entered = new CountDownLatch(1);
+        private final CountDownLatch cancelled = new CountDownLatch(1);
+
+        private void awaitEntered() throws InterruptedException {
+            Assert.assertTrue(entered.await(AWAIT_SECONDS, TimeUnit.SECONDS));
+        }
+
+        private void awaitCancelled() throws InterruptedException {
+            Assert.assertTrue(cancelled.await(AWAIT_SECONDS, TimeUnit.SECONDS));
+        }
+    }
+
+    private static final class LoadGate {
+
+        private final CountDownLatch entered = new CountDownLatch(1);
+        private final CountDownLatch release = new CountDownLatch(1);
+
+        private void awaitEntered() throws InterruptedException {
+            Assert.assertTrue(entered.await(AWAIT_SECONDS, TimeUnit.SECONDS));
+        }
+
+        private void release() {
+            release.countDown();
+        }
+    }
+
+    private static final class FakeMilvusServer implements AutoCloseable {
+
+        private static final io.milvus.grpc.Status SUCCESS =
+            io.milvus.grpc.Status.newBuilder()
+                .setErrorCode(ErrorCode.Success)
+                .setCode(0)
+                .build();
+
+        private final AtomicInteger connectCalls = new AtomicInteger();
+        private final AtomicInteger queryCalls = new AtomicInteger();
+        private final AtomicInteger activeLoads = new AtomicInteger();
+        private final AtomicInteger maxConcurrentLoads = new AtomicInteger();
+        private final AtomicBoolean querySawDeadline = new AtomicBoolean();
+        private final ConcurrentHashMap<String, AtomicInteger> loadCalls =
+            new ConcurrentHashMap<>();
+        private final ConcurrentHashMap<String, LoadGate> loadGates =
+            new ConcurrentHashMap<>();
+        private final Set<String> loadedCollections = ConcurrentHashMap.newKeySet();
+        private final Set<String> failNextLoads = ConcurrentHashMap.newKeySet();
+        private final ExecutorService rpcExecutor = Executors.newCachedThreadPool();
+        private final Server server;
+        private volatile QueryAction queryAction = QueryAction.SUCCESS;
+        private volatile QueryBlock queryBlock;
+
+        private FakeMilvusServer() throws IOException {
+            server = NettyServerBuilder.forPort(0)
+                .executor(rpcExecutor)
+                .addService(new Service())
+                .build()
+                .start();
+        }
+
+        private String uri() {
+            return "http://127.0.0.1:" + server.getPort();
+        }
+
+        private void succeedQueries() {
+            queryAction = QueryAction.SUCCESS;
+            queryBlock = null;
+        }
+
+        private void failQueriesWithUnavailable() {
+            queryAction = QueryAction.UNAVAILABLE;
+            queryBlock = null;
+        }
+
+        private QueryBlock blockQueries() {
+            QueryBlock block = new QueryBlock();
+            queryBlock = block;
+            queryAction = QueryAction.BLOCK;
+            return block;
+        }
+
+        private LoadGate blockLoad(String collectionName) {
+            LoadGate gate = new LoadGate();
+            loadGates.put(collectionName, gate);
+            return gate;
+        }
+
+        private void failNextLoad(String collectionName) {
+            failNextLoads.add(collectionName);
+        }
+
+        private int loadCalls(String collectionName) {
+            AtomicInteger calls = loadCalls.get(collectionName);
+            return calls == null ? 0 : calls.get();
+        }
+
+        @Override
+        public void close() {
+            for (LoadGate gate : new ArrayList<>(loadGates.values())) {
+                gate.release();
+            }
+            server.shutdownNow();
+            try {
+                server.awaitTermination(AWAIT_SECONDS, TimeUnit.SECONDS);
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+            } finally {
+                rpcExecutor.shutdownNow();
+            }
+        }
+
+        private enum QueryAction {
+            SUCCESS,
+            UNAVAILABLE,
+            BLOCK
+        }
+
+        private final class Service extends MilvusServiceGrpc.MilvusServiceImplBase {
+
+            @Override
+            public void connect(
+                ConnectRequest request,
+                StreamObserver<ConnectResponse> observer
+            ) {
+                connectCalls.incrementAndGet();
+                observer.onNext(ConnectResponse.newBuilder()
+                    .setStatus(SUCCESS)
+                    .setIdentifier(1L)
+                    .build());
+                observer.onCompleted();
+            }
+
+            @Override
+            public void listDatabases(
+                ListDatabasesRequest request,
+                StreamObserver<ListDatabasesResponse> observer
+            ) {
+                observer.onNext(ListDatabasesResponse.newBuilder()
+                    .setStatus(SUCCESS)
+                    .addDbNames("default")
+                    .build());
+                observer.onCompleted();
+            }
+
+            @Override
+            public void checkHealth(
+                CheckHealthRequest request,
+                StreamObserver<CheckHealthResponse> observer
+            ) {
+                observer.onNext(CheckHealthResponse.newBuilder()
+                    .setStatus(SUCCESS)
+                    .setIsHealthy(true)
+                    .build());
+                observer.onCompleted();
+            }
+
+            @Override
+            public void getLoadState(
+                GetLoadStateRequest request,
+                StreamObserver<GetLoadStateResponse> observer
+            ) {
+                LoadState state = loadedCollections.contains(request.getCollectionName())
+                    ? LoadState.LoadStateLoaded
+                    : LoadState.LoadStateNotLoad;
+                observer.onNext(GetLoadStateResponse.newBuilder()
+                    .setStatus(SUCCESS)
+                    .setState(state)
+                    .build());
+                observer.onCompleted();
+            }
+
+            @Override
+            public void describeCollection(
+                DescribeCollectionRequest request,
+                StreamObserver<DescribeCollectionResponse> observer
+            ) {
+                CollectionSchema schema = CollectionSchema.newBuilder()
+                    .setName(request.getCollectionName())
+                    .addFields(FieldSchema.newBuilder()
+                        .setName("id")
+                        .setIsPrimaryKey(true)
+                        .setDataType(DataType.VarChar)
+                        .build())
+                    .build();
+                observer.onNext(DescribeCollectionResponse.newBuilder()
+                    .setStatus(SUCCESS)
+                    .setCollectionName(request.getCollectionName())
+                    .setSchema(schema)
+                    .build());
+                observer.onCompleted();
+            }
+
+            @Override
+            public void loadCollection(
+                LoadCollectionRequest request,
+                StreamObserver<io.milvus.grpc.Status> observer
+            ) {
+                String collectionName = request.getCollectionName();
+                loadCalls.computeIfAbsent(
+                    collectionName, ignored -> new AtomicInteger()).incrementAndGet();
+                LoadGate gate = loadGates.get(collectionName);
+                if (gate != null) {
+                    int active = activeLoads.incrementAndGet();
+                    maxConcurrentLoads.accumulateAndGet(active, Math::max);
+                    gate.entered.countDown();
+                    try {
+                        if (!gate.release.await(AWAIT_SECONDS, TimeUnit.SECONDS)) {
+                            observer.onError(io.grpc.Status.DEADLINE_EXCEEDED
+                                .withDescription("test load gate timed out")
+                                .asRuntimeException());
+                            return;
+                        }
+                    } catch (InterruptedException exception) {
+                        Thread.currentThread().interrupt();
+                        observer.onError(io.grpc.Status.CANCELLED
+                            .withCause(exception)
+                            .asRuntimeException());
+                        return;
+                    } finally {
+                        activeLoads.decrementAndGet();
+                    }
+                }
+                if (failNextLoads.remove(collectionName)) {
+                    observer.onNext(io.milvus.grpc.Status.newBuilder()
+                        .setErrorCode(ErrorCode.UnexpectedError)
+                        .setCode(1)
+                        .setReason("synthetic load failure")
+                        .build());
+                    observer.onCompleted();
+                    return;
+                }
+                loadedCollections.add(collectionName);
+                observer.onNext(SUCCESS);
+                observer.onCompleted();
+            }
+
+            @Override
+            public void query(
+                QueryRequest request,
+                StreamObserver<QueryResults> observer
+            ) {
+                queryCalls.incrementAndGet();
+                querySawDeadline.compareAndSet(
+                    false, Context.current().getDeadline() != null);
+                QueryAction action = queryAction;
+                if (action == QueryAction.UNAVAILABLE) {
+                    observer.onError(io.grpc.Status.UNAVAILABLE
+                        .withDescription("synthetic query failure")
+                        .asRuntimeException());
+                    return;
+                }
+                if (action == QueryAction.BLOCK) {
+                    QueryBlock block = queryBlock;
+                    @SuppressWarnings("unchecked")
+                    ServerCallStreamObserver<QueryResults> serverObserver =
+                        (ServerCallStreamObserver<QueryResults>) observer;
+                    serverObserver.setOnCancelHandler(block.cancelled::countDown);
+                    block.entered.countDown();
+                    return;
+                }
+                observer.onNext(QueryResults.newBuilder()
+                    .setStatus(SUCCESS)
+                    .setCollectionName(request.getCollectionName())
+                    .build());
+                observer.onCompleted();
+            }
+        }
+    }
+}

easy-agents-store/easy-agents-store-milvus/src/test/java/com/easyagents/store/milvus/MilvusVectorStoreIntegrationTest.java

@@ -0,0 +1,190 @@
+package com.easyagents.store.milvus;
+
+import com.easyagents.core.document.Document;
+import com.easyagents.core.store.SearchWrapper;
+import com.easyagents.core.store.StoreOptions;
+import io.milvus.v2.service.collection.request.DropCollectionReq;
+import org.junit.Assert;
+import org.junit.Assume;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Opt-in compatibility smoke tests for a real Milvus instance.
+ */
+public class MilvusVectorStoreIntegrationTest {
+
+    @Test
+    public void shouldCrudAgainstRealMilvusAndRecoverPooledClients() throws Exception {
+        String uri = System.getenv("MILVUS_TEST_URI");
+        Assume.assumeTrue("MILVUS_TEST_URI is not configured", uri != null && !uri.isBlank());
+        String collectionName = "easy_agents_sdk_2311_" + UUID.randomUUID().toString().replace("-", "");
+        MilvusVectorStoreConfig config = new MilvusVectorStoreConfig();
+        config.setUri(uri);
+        config.setDefaultCollectionName(collectionName);
+        config.setPoolMaxTotal(1);
+        config.setPoolMaxTotalPerKey(1);
+        config.setPoolMaxIdlePerKey(1);
+        config.setPoolMinIdlePerKey(0);
+        config.setPoolMaxWaitMillis(250L);
+        MilvusClientManager manager = new MilvusClientManager(config);
+        MilvusVectorStore store = new MilvusVectorStore(config, manager);
+        StoreOptions options = StoreOptions.ofCollectionName(collectionName);
+        try {
+            Document first = document("chunk-1", "first", 1.0F, 0.0F);
+            Document second = document("chunk-2", "second", 0.0F, 1.0F);
+            Assert.assertTrue(store.store(List.of(first, second), options).isSuccess());
+
+            SearchWrapper nearest = new SearchWrapper();
+            nearest.setVector(new float[] { 1.0F, 0.0F });
+            nearest.setMaxResults(1);
+            List<Document> initial = store.search(nearest, options);
+            Assert.assertEquals(1, initial.size());
+            Assert.assertEquals("chunk-1", String.valueOf(initial.get(0).getId()));
+
+            Document updated = document("chunk-1", "updated", 1.0F, 0.0F);
+            Assert.assertTrue(store.update(List.of(updated), options).isSuccess());
+            Assert.assertEquals("updated", store.search(nearest, options).get(0).getContent());
+
+            Assert.assertTrue(store.delete(List.of("chunk-2"), options).isSuccess());
+            SearchWrapper deleted = new SearchWrapper();
+            deleted.setWithVector(false);
+            deleted.eq("id", "chunk-2");
+            Assert.assertTrue(store.search(deleted, options).isEmpty());
+
+            assertQueryFailureIsNotReportedAsEmpty(store, options);
+            assertPoolExhaustionIsBounded(manager);
+            assertBusinessFailurePreservesClient(manager);
+            Assert.assertTrue(store.checkAvailable());
+        } finally {
+            try {
+                manager.withClient(client -> {
+                    client.dropCollection(DropCollectionReq.builder()
+                        .collectionName(collectionName)
+                        .build());
+                    return null;
+                });
+            } finally {
+                store.close();
+                manager.close();
+            }
+        }
+        try {
+            manager.getActiveClientCount();
+            Assert.fail("A closed pool must reject further use");
+        } catch (IllegalStateException expected) {
+            Assert.assertEquals("Milvus client pool is closed", expected.getMessage());
+        }
+    }
+
+    private static void assertQueryFailureIsNotReportedAsEmpty(
+        MilvusVectorStore store,
+        StoreOptions options
+    ) {
+        SearchWrapper invalid = new SearchWrapper();
+        invalid.setWithVector(false);
+        invalid.eq("id", "chunk-1");
+        StoreOptions invalidOptions = StoreOptions.ofCollectionName(
+            options.getCollectionName()
+        ).partitionName("__missing_partition__");
+        try {
+            store.search(invalid, invalidOptions);
+            Assert.fail("A Milvus query failure must not be reported as an empty result");
+        } catch (RuntimeException expected) {
+            Assert.assertNotNull(expected.getMessage());
+        }
+    }
+
+    private static void assertBusinessFailurePreservesClient(MilvusClientManager manager)
+        throws InterruptedException, ExecutionException {
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        CountDownLatch borrowed = new CountDownLatch(1);
+        CountDownLatch waiterStarted = new CountDownLatch(1);
+        CountDownLatch fail = new CountDownLatch(1);
+        AtomicReference<Object> failedClient = new AtomicReference<>();
+        try {
+            Future<?> failing = executor.submit(() -> {
+                try {
+                    manager.withClient(client -> {
+                        failedClient.set(client);
+                        borrowed.countDown();
+                        try {
+                            if (!fail.await(2, TimeUnit.SECONDS)) {
+                                throw new IllegalStateException("Timed out waiting to fail client");
+                            }
+                        } catch (InterruptedException exception) {
+                            Thread.currentThread().interrupt();
+                            throw new IllegalStateException(exception);
+                        }
+                        throw new IllegalStateException("synthetic RPC failure");
+                    });
+                    Assert.fail("The synthetic client failure must be propagated");
+                } catch (IllegalStateException expected) {
+                    Assert.assertEquals("synthetic RPC failure", expected.getMessage());
+                }
+            });
+            Assert.assertTrue(borrowed.await(2, TimeUnit.SECONDS));
+            Future<Object> waiting = executor.submit(() -> {
+                waiterStarted.countDown();
+                return manager.withClient(client -> client);
+            });
+            Assert.assertTrue(waiterStarted.await(2, TimeUnit.SECONDS));
+            fail.countDown();
+            failing.get();
+            Assert.assertSame(failedClient.get(), waiting.get());
+        } finally {
+            fail.countDown();
+            executor.shutdownNow();
+        }
+    }
+
+    private static void assertPoolExhaustionIsBounded(MilvusClientManager manager)
+        throws InterruptedException, ExecutionException {
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        CountDownLatch borrowed = new CountDownLatch(1);
+        CountDownLatch release = new CountDownLatch(1);
+        try {
+            Future<?> holder = executor.submit(() -> manager.withClient(client -> {
+                borrowed.countDown();
+                try {
+                    if (!release.await(2, TimeUnit.SECONDS)) {
+                        throw new IllegalStateException("Timed out waiting to release pooled client");
+                    }
+                } catch (InterruptedException exception) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(exception);
+                }
+                return null;
+            }));
+            Assert.assertTrue(borrowed.await(2, TimeUnit.SECONDS));
+            Future<?> waiter = executor.submit(() -> manager.withClient(client -> null));
+            try {
+                waiter.get();
+                Assert.fail("Pool exhaustion must fail after the configured wait");
+            } catch (ExecutionException expected) {
+                Assert.assertNotNull(expected.getCause());
+            }
+            release.countDown();
+            holder.get();
+        } finally {
+            release.countDown();
+            executor.shutdownNow();
+        }
+    }
+
+    private static Document document(String id, String content, float first, float second) {
+        Document document = Document.of(content);
+        document.setId(id);
+        document.setVector(new float[] { first, second });
+        return document;
+    }
+}

pom.xml

@@ -49,6 +49,7 @@
         <agentscope.version>1.0.12</agentscope.version>
         <snakeyaml.version>2.6</snakeyaml.version>
         <commons-compress.version>1.28.0</commons-compress.version>
+        <milvus.version>2.3.11</milvus.version>
     </properties>
 
 
@@ -129,6 +130,12 @@
                 <version>${commons-compress.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>io.milvus</groupId>
+                <artifactId>milvus-sdk-java</artifactId>
+                <version>${milvus.version}</version>
+            </dependency>
+
             <!--easy-agents dependency management-->
             <dependency>
                 <groupId>com.easyagents</groupId>