fix: 修复知识库索引并发与向量化边界

- 复用 Lucene 和 Elasticsearch 客户端并支持有界批量写入与删除

- 记录脱敏后的 Embedding 失败请求与完整响应

- 为 BGE-M3 分块统一增加上下文硬上限

easy-agents-search-engine/easy-agents-search-engine-service/src/main/java/com/easyagents/search/engine/service/DocumentSearcher.java

@@ -17,23 +17,106 @@ package com.easyagents.search.engine.service;
 
 import com.easyagents.core.document.Document;
 
+import java.util.Collection;
 import java.util.List;
 
+/**
+ * 关键词搜索引擎统一接口。
+ */
 public interface DocumentSearcher {
 
+    /**
+     * 写入单个文档。
+     *
+     * @param document 待写入文档
+     * @return 写入成功时返回 {@code true}
+     */
     boolean addDocument(Document document);
 
+    /**
+     * 批量写入文档。
+     *
+     * <p>默认实现保持现有搜索引擎兼容性；支持原生批量写入的实现应覆盖该方法。</p>
+     *
+     * @param documents 待写入文档
+     * @return 全部文档写入成功时返回 {@code true}
+     */
+    default boolean addDocuments(List<Document> documents) {
+        if (documents == null || documents.isEmpty()) {
+            return false;
+        }
+        for (Document document : documents) {
+            if (!addDocument(document)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * 删除指定文档。
+     *
+     * @param id 文档 ID
+     * @return 删除成功时返回 {@code true}
+     */
     boolean deleteDocument(Object id);
 
+    /**
+     * 批量删除指定文档。
+     *
+     * <p>默认实现保持现有搜索引擎兼容性，并确保所有文档都会尝试删除；
+     * 支持原生批量删除的实现应覆盖该方法。</p>
+     *
+     * @param ids 文档 ID 集合
+     * @return 全部文档删除成功时返回 {@code true}
+     */
+    default boolean deleteDocuments(Collection<?> ids) {
+        if (ids == null || ids.isEmpty()) {
+            return false;
+        }
+        boolean success = true;
+        for (Object id : ids) {
+            if (!deleteDocument(id)) {
+                success = false;
+            }
+        }
+        return success;
+    }
+
+    /**
+     * 更新指定文档。
+     *
+     * @param document 待更新文档
+     * @return 更新成功时返回 {@code true}
+     */
     boolean updateDocument(Document document);
 
+    /**
+     * 使用默认返回数量搜索文档。
+     *
+     * @param keyword 搜索关键词
+     * @return 命中文档
+     */
     default List<Document> searchDocuments(String keyword) {
         return searchDocuments(KeywordSearchRequest.of(keyword, 10));
     }
 
+    /**
+     * 搜索指定数量的文档。
+     *
+     * @param keyword 搜索关键词
+     * @param count 最大返回数量
+     * @return 命中文档
+     */
     default List<Document> searchDocuments(String keyword, int count) {
         return searchDocuments(KeywordSearchRequest.of(keyword, count));
     }
 
+    /**
+     * 按请求条件搜索文档。
+     *
+     * @param request 搜索请求
+     * @return 命中文档
+     */
     List<Document> searchDocuments(KeywordSearchRequest request);
 }