flzxsqc-demo 1.4.13 → 1.4.14

package/agent-backend/docs/digital-analysis-global-context-filter-flow.md

@@ -0,0 +1,328 @@
+# globalContext 数据筛选参数处理链路
+
+本文说明前端提交 `globalContext.digitalAnalysis` 后，后端如何把数据筛选条件融入分析任务的工具调用参数中。重点覆盖数据从前端创建任务、后端会话保存、工具执行前预处理，到本地查询兼容层的完整代码路径。
+
+## 1. 入口数据形态
+
+前端创建分析任务时，会把数据筛选信息放入 `globalContext.digitalAnalysis`。当前主要有两类来源：
+
+```json
+{
+  "globalContext": {
+    "digitalAnalysis": {
+      "source": "agent_session_batch",
+      "batchId": "batch-xxx",
+      "queryInstanceId": "query-xxx",
+      "matchedCount": 20,
+      "sessionIds": ["call-1", "call-2"],
+      "filters": {
+        "start_time": "2026-01-01 00:00:00",
+        "end_time": "2026-06-18 23:59:59",
+        "agentId": "A001",
+        "teamId": ["T1", "T2"]
+      }
+    }
+  }
+}
+```
+
+没有批次筛选结果、但填写了固定或动态筛选条件时，前端会提交：
+
+```json
+{
+  "globalContext": {
+    "digitalAnalysis": {
+      "source": "agent_session_filter",
+      "filters": {
+        "channel": "渠道1",
+        "batchCode": "batchId",
+        "queueId": "Q001",
+        "groupId": ["G1"]
+      }
+    }
+  }
+}
+```
+
+相关前端组装代码：
+
+- `want-agent/agent-front-react/src/pages/AnalysisTaskPage.tsx`
+- `want-agent/agent-front-react/src/constants/sessionFilters.ts`
+- `want-agent/agent-front-react/src/pages/analysis-task/SessionBatchPanel.tsx`
+
+## 2. 后端会话创建与保存
+
+创建任务接口接收前端传入的 `globalContext`，并随会话一起保存。
+
+核心代码：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/controller/AgentSessionController.java`
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/AgentTurnRunner.java`
+- `want-agent/agent-backend/src/main/java/com/example/agent/domain/AgentSession.java`
+
+处理要点：
+
+1. `AgentSessionController.createSession(...)` 接收创建任务请求。
+2. 请求中的 `globalContext` 会进入会话创建流程。
+3. `AgentTurnRunner` 创建 `AgentSession` 记录时，把 `globalContext` 挂到 `AgentSession.globalContext`。
+4. 后续工具执行阶段通过当前 `AgentSession` 读取这份上下文。
+
+也就是说，`globalContext.digitalAnalysis` 不是直接作为某个查询接口的 body 传入工具，而是先成为会话级上下文，再在工具调用前被后端预处理器读取并转换。
+
+## 3. 工具执行前的参数处理顺序
+
+分析任务运行时，LLM 会选择工具并生成初始参数。工具真正执行前，会经过后端统一执行管线。
+
+核心代码：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/tool/ToolExecutionPipeline.java`
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/tool/AgentSessionBatchToolContextApplier.java`
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/tool/argument/ToolArgumentResolverRegistry.java`
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/tool/argument/CompanyStructuredQueryToolArgumentResolver.java`
+
+当前关键顺序是：
+
+1. `agentTimeContextService.normalizeArgs(...)`
+2. `AgentSessionBatchToolContextApplier.apply(...)`
+3. `toolInvocationGuard.validateBeforeExecution(...)`
+4. `resolveExecutionArgs(...)`
+5. 进入具体工具实现或 MCP 调用
+
+其中第 2 步和第 4 步都与数据筛选相关，但职责不同。
+
+## 4. AgentSessionBatchToolContextApplier 的作用
+
+`AgentSessionBatchToolContextApplier` 会读取：
+
+```java
+session.getGlobalContext().get("digitalAnalysis")
+```
+
+它的作用是把会话级数据筛选上下文合并到传统工具参数中，主要用于让工具前置校验、执行保护和旧参数路径能看到约束。
+
+相关代码：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/tool/AgentSessionBatchToolContextApplier.java`
+
+典型行为：
+
+- 读取 `digitalAnalysis.filters`
+- 读取 `digitalAnalysis.sessionIds`
+- 合并成规范化筛选条件
+- 注入到工具参数中的 `filters` 或相关字段
+
+这一步保留了对旧式本地查询参数的兼容，但它不是公司 ES 查询参数最终成型的位置。
+
+## 5. request_preprocessor 决定最终工具参数形态
+
+真正把筛选条件组装成公司查询接口参数形态的是 `request_preprocessor`。
+
+工具定义在种子数据里配置：
+
+- `want-agent/agent-backend/src/main/resources/data.sql`
+
+当前两个工具使用公司结构化查询预处理器：
+
+```sql
+query_customer_sessions_structured -> COMPANY_STRUCTURED_DETECT_QUERY
+query_sessions_handle              -> COMPANY_STRUCTURED_HANDLE_QUERY
+```
+
+对应解析器：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/tool/argument/CompanyStructuredQueryToolArgumentResolver.java`
+
+注意：如果本地数据库里已经存在旧的 `tool_definition` 数据，需要重新执行或迁移 `data.sql` 中的 `request_preprocessor` 配置，否则运行时不会进入这个解析器。
+
+## 6. CompanyStructuredQueryToolArgumentResolver 的优先级
+
+`CompanyStructuredQueryToolArgumentResolver` 的核心规则是：只要会话 `globalContext.digitalAnalysis` 里有可识别筛选条件，就优先使用这些条件组装工具参数；否则才使用模型从自然语言问题里解析出的参数。
+
+优先级如下：
+
+1. 有 `globalContext.digitalAnalysis` 筛选条件：使用会话上下文组装公司结构化查询参数。
+2. 没有数据筛选上下文，但模型已经生成 `queryConditions`：保留并补齐默认字段。
+3. 没有 `queryConditions`，但模型生成了旧式 `filters` 或扁平字段：转换成公司结构化查询参数。
+
+这对应用户期望的逻辑：
+
+- 使用了前端数据筛选时，以 `globalContext` 里的条件为准。
+- 没有使用数据筛选时，继续使用原来的客户自然语言问题解析结果。
+
+## 7. 生成的公司查询参数形态
+
+预处理后，`query_customer_sessions_structured` 和 `query_sessions_handle` 的工具参数会被整理为类似下面的形态：
+
+```json
+{
+  "boolOperator": "FILTER",
+  "queryConditions": [
+    {
+      "conditionType": "RANGE",
+      "field": "sessionTime",
+      "fieldType": "DATE",
+      "gte": "2026-01-01 00:00:00",
+      "lte": "2026-06-18 23:59:59"
+    },
+    {
+      "conditionType": "MATCH_PHRASE",
+      "field": "sourceId",
+      "fieldType": "KEYWORD",
+      "value": ["call-1", "call-2"]
+    },
+    {
+      "conditionType": "MATCH_PHRASE",
+      "field": "agentId",
+      "fieldType": "KEYWORD",
+      "value": ["A001"]
+    },
+    {
+      "conditionType": "MATCH_PHRASE",
+      "field": "teamId",
+      "fieldType": "KEYWORD",
+      "value": ["T1", "T2"]
+    }
+  ],
+  "queryPurpose": "DETECT",
+  "sourceTypes": ["VOICE", "TEXT"],
+  "includeFields": ["allText", "queueId", "agentId"],
+  "queryType": "STRUCTURED",
+  "size": 10
+}
+```
+
+`queryPurpose` 会按工具场景设置：
+
+- `COMPANY_STRUCTURED_DETECT_QUERY` -> `DETECT`
+- `COMPANY_STRUCTURED_HANDLE_QUERY` -> `ANALYSE`
+
+## 8. 筛选字段到 queryConditions 的映射
+
+字段映射由 `CompanyStructuredQueryToolArgumentResolver` 完成。
+
+| canonical filter | 公司查询字段 | 条件类型 | 说明 |
+| --- | --- | --- | --- |
+| `start_time` / `end_time` | `sessionTime` | `RANGE` | 时间范围 |
+| `session_ids` / `sessionIds` | `sourceId` | `MATCH_PHRASE` | 会话 ID 列表 |
+| `agentId` | `agentId` | `MATCH_PHRASE` | 坐席 ID |
+| `queueId` | `queueId` | `MATCH_PHRASE` | 队列 |
+| `teamId` | `teamId` | `MATCH_PHRASE` | 团队 ID |
+| `groupId` | `groupId` | `MATCH_PHRASE` | 组 ID |
+| `batchCode` | `batchCode` | `MATCH_PHRASE` | 批次号 |
+| `channel` | `channel` | `MATCH_PHRASE` | 数据渠道 |
+| `dataSource` | `dataSource` | `MATCH_PHRASE` | 数据来源 |
+| `callType` | `callType` | `MATCH_PHRASE` | 会话类型 |
+| `businessLine` | `businessLine` | `MATCH_PHRASE` | 业务线 |
+| `customerId` | `customerId` | `MATCH_PHRASE` | 客户 ID |
+| `keywords` | `allText` | `MATCH_PHRASE` | 文本关键词 |
+| `limit` | `size` | - | 查询条数 |
+
+`source`、`batchId`、`queryInstanceId`、`matchedCount` 等字段是上下文元数据，不直接生成查询条件。真正参与过滤的是 `filters` 和 `sessionIds` 中可识别的字段。
+
+## 9. 本地查询兼容逻辑
+
+本地开发环境并不直接查公司 ES，而是仍然通过本地查询实现或模拟接口执行。因此后端保留了对两种参数形态的兼容：
+
+1. 旧式参数：
+
+```json
+{
+  "filters": {
+    "start_time": "2026-01-01 00:00:00",
+    "end_time": "2026-06-18 23:59:59",
+    "session_ids": ["call-1"]
+  },
+  "limit": 10
+}
+```
+
+2. 公司结构化参数：
+
+```json
+{
+  "queryConditions": [
+    {
+      "conditionType": "MATCH_PHRASE",
+      "field": "sourceId",
+      "fieldType": "KEYWORD",
+      "value": ["call-1"]
+    }
+  ],
+  "size": 10
+}
+```
+
+兼容转换代码：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/filter/AgentSessionFilterMapper.java`
+
+它负责：
+
+- 规范化 `filters`
+- 识别字段别名
+- 把公司结构化 `queryConditions` 反解析成本地 `CustomerSessionQueryRequest` 可用的 canonical filters
+- 把 `size` 兼容为 `limit`
+
+本地工具入口使用该 mapper：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/controller/ToolsController.java`
+- `want-agent/agent-backend/src/main/java/com/example/agent/application/service/localtool/QueryHandleService.java`
+
+最终查询请求对象和 SQL 映射：
+
+- `want-agent/agent-backend/src/main/java/com/example/agent/domain/CustomerSessionQueryRequest.java`
+- `want-agent/agent-backend/src/main/resources/mappers/CustomerSessionMapper.xml`
+
+因此，即使工具参数已经被预处理成公司 ES 风格，本地查询路径也能反解析并继续执行。
+
+## 10. 完整调用链概览
+
+```mermaid
+sequenceDiagram
+    participant FE as 前端 AnalysisTaskPage
+    participant API as AgentSessionController
+    participant Runner as AgentTurnRunner
+    participant Pipeline as ToolExecutionPipeline
+    participant Applier as AgentSessionBatchToolContextApplier
+    participant Resolver as CompanyStructuredQueryToolArgumentResolver
+    participant Tool as query_customer_sessions_structured / query_sessions_handle
+    participant Local as 本地 QueryHandleService / ToolsController
+
+    FE->>API: createSession(question, globalContext.digitalAnalysis)
+    API->>Runner: 创建分析会话
+    Runner->>Runner: 保存 AgentSession.globalContext
+    Runner->>Pipeline: 执行 LLM 选择的工具
+    Pipeline->>Applier: 从 session.globalContext.digitalAnalysis 合并筛选上下文
+    Pipeline->>Resolver: 根据 request_preprocessor 解析最终工具参数
+    Resolver->>Resolver: globalContext 优先；否则使用模型解析参数
+    Resolver->>Tool: 输出公司结构化 queryConditions 参数
+    Tool->>Local: 本地环境执行时进入兼容查询
+    Local->>Local: AgentSessionFilterMapper 反解析 queryConditions
+```
+
+## 11. 关键行为约束
+
+- 前端使用数据筛选时，`globalContext.digitalAnalysis` 的筛选条件优先级高于模型从自然语言中解析出的查询条件。
+- 前端没有使用数据筛选时，后端仍沿用自然语言问题解析出的工具参数。
+- `sample_sessions_by_keywords` 不走公司结构化查询预处理器，避免影响关键字采样类工具的原行为。
+- `query_customer_sessions_structured` 和 `query_sessions_handle` 才走公司结构化查询预处理器。
+- `sampleCount`、采样功能和数据筛选查询是不同链路；采样读取已有分析结果，不重新生成数据筛选查询。
+
+## 12. 相关测试
+
+覆盖该链路的主要测试：
+
+- `want-agent/agent-backend/src/test/java/com/example/agent/application/service/tool/argument/CompanyStructuredQueryToolArgumentResolverTest.java`
+- `want-agent/agent-backend/src/test/java/com/example/agent/application/service/filter/AgentSessionFilterMapperTest.java`
+
+常用验证命令：
+
+```bash
+mvn -Dtest=CompanyStructuredQueryToolArgumentResolverTest,AgentSessionFilterMapperTest test
+```
+
+如果同时验证采样功能相关改动：
+
+```bash
+mvn -Dtest=CompanyStructuredQueryToolArgumentResolverTest,AgentSessionFilterMapperTest,AgentSessionSampleServiceTest test
+```

package/agent-backend/src/main/java/com/example/agent/application/harness/state/DefaultAsyncCallbackPayloadBuilder.java

@@ -32,6 +32,9 @@ public class DefaultAsyncCallbackPayloadBuilder implements AsyncCallbackPayloadB
             return;
         }
         for (Map.Entry<String, Object> entry : source.entrySet()) {
+            if (isExecutionIdentity(entry.getKey()) && target.containsKey(entry.getKey())) {
+                continue;
+            }
             Object targetValue = target.get(entry.getKey());
             Object sourceValue = entry.getValue();
             if (targetValue instanceof Map && sourceValue instanceof Map) {
@@ -42,6 +45,10 @@ public class DefaultAsyncCallbackPayloadBuilder implements AsyncCallbackPayloadB
         }
     }
 
+    private boolean isExecutionIdentity(String key) {
+        return "tool".equals(key) || "args".equals(key);
+    }
+
     private Map<String, Object> readJsonMap(Object raw) {
         if (raw == null) {
             return new LinkedHashMap<String, Object>();

package/agent-backend/src/main/java/com/example/agent/application/service/ToolExecutionPipeline.java

@@ -99,7 +99,11 @@ public class ToolExecutionPipeline {
 
             // 5. 异步工具需要登记等待任务；同步工具直接发布完成事件。
             if (executionResult.isWaitingAsync()) {
-                String payloadJson = objectMapper.writeValueAsString(executionResult.getNormalizedPayload());
+                String payloadJson = objectMapper.writeValueAsString(asyncPendingPayload(
+                        request.toolName(),
+                        executorArgs,
+                        executionResult.getNormalizedPayload()
+                ));
                 asyncJobRepository.insertPendingAgentJob(new AsyncJobRepository.AgentAsyncJobInsert(
                         request.session().getSessionId(),
                         request.turnId(),
@@ -237,6 +241,15 @@ public class ToolExecutionPipeline {
         return payload;
     }
 
+    private Map<String, Object> asyncPendingPayload(String toolName, Map<String, Object> args, Map<String, Object> result) {
+        Map<String, Object> payload = result == null
+                ? new LinkedHashMap<String, Object>()
+                : new LinkedHashMap<String, Object>(result);
+        payload.put("tool", toolName);
+        payload.put("args", args == null ? new LinkedHashMap<String, Object>() : new LinkedHashMap<String, Object>(args));
+        return payload;
+    }
+
     private Map<String, Object> timedPayload(String toolName, Map<String, Object> args, Object result, long startedAt) {
         Map<String, Object> payload = payload(toolName, args, result);
         payload.put("latency_ms", System.currentTimeMillis() - startedAt);

package/agent-backend/src/main/java/com/example/agent/application/service/localtool/AgentSessionBatchService.java

@@ -40,15 +40,14 @@ public class AgentSessionBatchService {
         List<String> rawSessionIds = new ArrayList<String>();
         rawSessionIds.addAll(parseSessionIds(safeRequest.getManualIds(), MANUAL_SESSION_ID_SPLITTER));
         rawSessionIds.addAll(parseSessionIds(safeRequest.getFileContent(), FILE_SESSION_ID_SPLITTER));
-        if (rawSessionIds.isEmpty()) {
-            throw new IllegalArgumentException("session ids must not be empty");
-        }
 
         LinkedHashSet<String> uniqueSessionIds = new LinkedHashSet<String>(rawSessionIds);
-        Map<String, CustomerSessionRecord> existingRecords = existingRecordMap(uniqueSessionIds);
+        Map<String, CustomerSessionRecord> existingRecords = uniqueSessionIds.isEmpty()
+                ? new LinkedHashMap<String, CustomerSessionRecord>()
+                : existingRecordMap(uniqueSessionIds);
         String batchId = "batch-" + UUID.randomUUID().toString();
         List<AgentSessionBatchItemPo> items = buildItems(batchId, uniqueSessionIds, existingRecords);
-        AgentSessionBatchPo batch = buildBatch(batchId, safeRequest, items.size());
+        AgentSessionBatchPo batch = buildBatch(batchId, safeRequest, items.size(), uniqueSessionIds.isEmpty());
         batchRepository.insert(batch, items);
         return toBatchResponse(batch, items);
     }
@@ -56,9 +55,6 @@ public class AgentSessionBatchService {
     public AgentSessionBatchDtos.FilterResponse filter(String batchId, AgentSessionBatchDtos.FilterRequest request) {
         AgentSessionBatchPo batch = requireBatch(batchId);
         List<AgentSessionBatchItemPo> validItems = batchRepository.findValidItems(batch.getBatchId());
-        if (validItems.isEmpty()) {
-            throw new IllegalArgumentException("batch has no valid session ids: " + batchId);
-        }
 
         AgentSessionBatchDtos.FilterRequest safeRequest = request == null ? new AgentSessionBatchDtos.FilterRequest() : request;
         CustomerSessionQueryRequest queryRequest = buildQueryRequest(validItems, safeRequest);
@@ -161,12 +157,13 @@ public class AgentSessionBatchService {
 
     private AgentSessionBatchPo buildBatch(String batchId,
                                            AgentSessionBatchDtos.ParseRequest request,
-                                           int validCount) {
+                                           int validCount,
+                                           boolean filterOnly) {
         AgentSessionBatchPo batch = new AgentSessionBatchPo();
         batch.setBatchId(batchId);
-        batch.setSourceType(defaultText(request.getSourceType(), "MANUAL"));
+        batch.setSourceType(defaultText(request.getSourceType(), filterOnly ? "FILTER_ONLY" : "MANUAL"));
         batch.setValidCount(validCount);
-        batch.setStatus(validCount > 0 ? "READY" : "INVALID");
+        batch.setStatus(validCount > 0 || filterOnly ? "READY" : "INVALID");
         batch.setCreator(defaultText(request.getCreator(), "system"));
         return batch;
     }
@@ -174,13 +171,20 @@ public class AgentSessionBatchService {
     private CustomerSessionQueryRequest buildQueryRequest(List<AgentSessionBatchItemPo> validItems,
                                                           AgentSessionBatchDtos.FilterRequest request) {
         Map<String, Object> filters = AgentSessionFilterMapper.normalizeBatchFilterRequest(request);
-        filters.put(AgentSessionFilterField.SESSION_IDS.key(), validSessionIds(validItems));
+        putSessionIdsIfPresent(filters, validItems);
         CustomerSessionQueryRequest queryRequest = new CustomerSessionQueryRequest();
         AgentSessionFilterMapper.applyToQueryRequest(queryRequest, filters);
         queryRequest.setLimit(normalizeLimit(queryRequest.getLimit()));
         return queryRequest;
     }
 
+    private void putSessionIdsIfPresent(Map<String, Object> filters, List<AgentSessionBatchItemPo> validItems) {
+        List<String> sessionIds = validSessionIds(validItems);
+        if (!sessionIds.isEmpty()) {
+            filters.put(AgentSessionFilterField.SESSION_IDS.key(), sessionIds);
+        }
+    }
+
     private List<String> validSessionIds(List<AgentSessionBatchItemPo> validItems) {
         LinkedHashSet<String> sessionIds = new LinkedHashSet<String>();
         for (AgentSessionBatchItemPo item : validItems) {

package/agent-backend/src/test/java/com/example/agent/application/harness/state/DefaultAsyncCallbackPayloadBuilderTest.java

@@ -14,10 +14,16 @@ class DefaultAsyncCallbackPayloadBuilderTest {
         DefaultAsyncCallbackPayloadBuilder builder = new DefaultAsyncCallbackPayloadBuilder(new ObjectMapper());
 
         Map<String, Object> asyncJob = new LinkedHashMap<String, Object>();
-        asyncJob.put("payload_json", "{\"status\":\"WAITING_ASYNC_CALLBACK\",\"artifacts\":{\"batchId\":\"batch-123\",\"analysis_job_id\":\"job-1\"},\"exports\":{\"analysis_result_id\":\"batch-123\"}}");
+        asyncJob.put("payload_json", "{\"tool\":\"query_sessions_handle\",\"args\":{\"queryConditions\":[{\"field\":\"sourceId\",\"value\":[\"call-1\"]}]},\"status\":\"WAITING_ASYNC_CALLBACK\",\"artifacts\":{\"batchId\":\"batch-123\",\"analysis_job_id\":\"job-1\"},\"exports\":{\"analysis_result_id\":\"batch-123\"}}");
 
         Map<String, Object> callbackPayload = new LinkedHashMap<String, Object>();
         callbackPayload.put("status", "SUCCEEDED");
+        callbackPayload.put("tool", "query_sessions_handle");
+        callbackPayload.put("args", new LinkedHashMap<String, Object>() {{
+            put("filters", new LinkedHashMap<String, Object>() {{
+                put("session_ids", "llm-call");
+            }});
+        }});
         callbackPayload.put("artifacts", new LinkedHashMap<String, Object>() {{
             put("sample_count", 80);
         }});
@@ -29,5 +35,8 @@ class DefaultAsyncCallbackPayloadBuilderTest {
         Assertions.assertEquals("batch-123", artifacts.get("batchId"));
         Assertions.assertEquals(80, artifacts.get("sample_count"));
         Assertions.assertEquals("job-1", artifacts.get("analysis_job_id"));
+        Map<String, Object> args = (Map<String, Object>) merged.get("args");
+        Assertions.assertEquals("sourceId", ((Map<?, ?>) ((java.util.List<?>) args.get("queryConditions")).get(0)).get("field"));
+        Assertions.assertFalse(args.containsKey("filters"));
     }
 }

package/agent-backend/src/test/java/com/example/agent/application/service/ToolExecutionPipelineTest.java

@@ -19,6 +19,7 @@ import com.example.agent.domain.model.ToolResultType;
 import com.example.agent.domain.model.ToolValidationException;
 import com.example.agent.domain.port.ToolExecutor;
 import com.example.agent.infrastructure.repository.AsyncJobRepository;
+import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
@@ -228,6 +229,72 @@ class ToolExecutionPipelineTest {
         Assertions.assertFalse(executedArgs.containsKey("analysis_prompt"));
     }
 
+    @Test
+    void persistsResolvedArgsForAsyncFinishEvents() throws Exception {
+        ToolExecutor executor = Mockito.mock(ToolExecutor.class);
+        ToolResult toolResult = new ToolResult();
+        toolResult.setType(ToolResultType.ASYNC_JOB);
+        toolResult.setAsyncJobId("async-1");
+        toolResult.setCallbackTopic("agent.tool.analysis.completed");
+        toolResult.setArtifacts(new LinkedHashMap<String, Object>() {{
+            put("analysis_job_id", "async-1");
+        }});
+        Mockito.when(executor.execute(Mockito.any(ToolCommand.class))).thenReturn(toolResult);
+        AsyncJobRepository asyncJobRepository = Mockito.mock(AsyncJobRepository.class);
+        ToolArgumentResolver resolver = new ToolArgumentResolver() {
+            @Override
+            public String key() {
+                return "TEST_STRUCTURED_QUERY";
+            }
+
+            @Override
+            public Map<String, Object> resolve(AgentSession session, ToolDefinition definition, Map<String, Object> args) {
+                Map<String, Object> resolved = new LinkedHashMap<String, Object>();
+                resolved.put("queryConditions", Collections.singletonList(new LinkedHashMap<String, Object>() {{
+                    put("field", "sourceId");
+                    put("value", Collections.singletonList("call-1"));
+                }}));
+                return resolved;
+            }
+        };
+        ToolExecutionPipeline pipeline = pipeline(
+                executor,
+                Mockito.mock(HarnessMemoryService.class),
+                Arrays.asList(new DefaultToolArgumentResolver(), resolver),
+                asyncJobRepository,
+                Mockito.mock(RuntimeEventBus.class)
+        );
+
+        AgentSession session = new AgentSession();
+        session.setSessionId("session-1");
+        session.setQuery("分析筛选数据");
+        ToolDefinition definition = tool("query_sessions_handle");
+        definition.setResultType(ToolResultType.ASYNC_JOB);
+        definition.setRequestPreprocessor("TEST_STRUCTURED_QUERY");
+
+        pipeline.execute(new ToolExecutionPipeline.ToolExecutionRequest(
+                session,
+                "turn-1",
+                "call-1",
+                "query_sessions_handle",
+                new LinkedHashMap<String, Object>() {{
+                    put("filters", Collections.singletonMap("session_ids", Collections.singletonList("llm-call")));
+                }},
+                Collections.singletonList(definition)
+        ));
+
+        ArgumentCaptor<AsyncJobRepository.AgentAsyncJobInsert> insertCaptor = ArgumentCaptor.forClass(AsyncJobRepository.AgentAsyncJobInsert.class);
+        Mockito.verify(asyncJobRepository).insertPendingAgentJob(insertCaptor.capture());
+        Map<String, Object> payload = new ObjectMapper().readValue(
+                insertCaptor.getValue().payloadJson(),
+                new TypeReference<Map<String, Object>>() {}
+        );
+        Map<String, Object> args = (Map<String, Object>) payload.get("args");
+        Assertions.assertEquals("query_sessions_handle", payload.get("tool"));
+        Assertions.assertEquals("sourceId", ((Map<?, ?>) ((List<?>) args.get("queryConditions")).get(0)).get("field"));
+        Assertions.assertFalse(args.containsKey("filters"));
+    }
+
     private ToolExecutionPipeline pipeline(ToolExecutor executor, HarnessMemoryService memoryService) {
         return pipeline(executor, memoryService, Collections.singletonList(new DefaultToolArgumentResolver()));
     }
@@ -235,11 +302,25 @@ class ToolExecutionPipelineTest {
     private ToolExecutionPipeline pipeline(ToolExecutor executor,
                                            HarnessMemoryService memoryService,
                                            List<ToolArgumentResolver> resolvers) {
+        return pipeline(
+                executor,
+                memoryService,
+                resolvers,
+                Mockito.mock(AsyncJobRepository.class),
+                Mockito.mock(RuntimeEventBus.class)
+        );
+    }
+
+    private ToolExecutionPipeline pipeline(ToolExecutor executor,
+                                           HarnessMemoryService memoryService,
+                                           List<ToolArgumentResolver> resolvers,
+                                           AsyncJobRepository asyncJobRepository,
+                                           RuntimeEventBus runtimeEventBus) {
         return new ToolExecutionPipeline(
                 Mockito.mock(ToolRegistry.class),
                 executor,
-                Mockito.mock(RuntimeEventBus.class),
-                Mockito.mock(AsyncJobRepository.class),
+                runtimeEventBus,
+                asyncJobRepository,
                 new ObjectMapper(),
                 new AgentTimeContextService("Asia/Shanghai"),
                 new ToolArgumentResolverRegistry(resolvers),

package/agent-backend/src/test/java/com/example/agent/application/service/localtool/AgentSessionBatchServiceTest.java

@@ -0,0 +1,85 @@
+package com.example.agent.application.service.localtool;
+
+import com.example.agent.domain.model.CustomerSessionRecord;
+import com.example.agent.infrastructure.persistence.po.localtool.AgentSessionBatchPo;
+import com.example.agent.infrastructure.repository.localtool.AgentSessionBatchRepository;
+import com.example.agent.infrastructure.repository.localtool.CustomerSessionMysqlRepository;
+import com.example.agent.interfaces.rest.dto.AgentSessionBatchDtos;
+import com.example.agent.interfaces.rest.dto.CustomerSessionQueryRequest;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mockito;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+class AgentSessionBatchServiceTest {
+
+    @Test
+    void parseAllowsFilterOnlyBatchWithoutSessionIds() {
+        AgentSessionBatchRepository batchRepository = Mockito.mock(AgentSessionBatchRepository.class);
+        AgentSessionBatchService service = service(batchRepository, Mockito.mock(CustomerSessionMysqlRepository.class), Mockito.mock(QueryHandleService.class));
+
+        AgentSessionBatchDtos.BatchResponse response = service.parse(new AgentSessionBatchDtos.ParseRequest());
+
+        ArgumentCaptor<AgentSessionBatchPo> batchCaptor = ArgumentCaptor.forClass(AgentSessionBatchPo.class);
+        Mockito.verify(batchRepository).insert(batchCaptor.capture(), Mockito.eq(Collections.emptyList()));
+        Assertions.assertEquals("READY", response.getStatus());
+        Assertions.assertEquals("FILTER_ONLY", response.getSourceType());
+        Assertions.assertEquals(Integer.valueOf(0), response.getValidCount());
+        Assertions.assertEquals("READY", batchCaptor.getValue().getStatus());
+        Assertions.assertEquals("FILTER_ONLY", batchCaptor.getValue().getSourceType());
+    }
+
+    @Test
+    void filterWithoutValidSessionIdsUsesOnlyFilterFields() {
+        AgentSessionBatchRepository batchRepository = Mockito.mock(AgentSessionBatchRepository.class);
+        CustomerSessionMysqlRepository customerSessionMysqlRepository = Mockito.mock(CustomerSessionMysqlRepository.class);
+        QueryHandleService queryHandleService = Mockito.mock(QueryHandleService.class);
+        AgentSessionBatchPo batch = new AgentSessionBatchPo();
+        batch.setBatchId("batch-filter-only");
+        batch.setStatus("READY");
+        batch.setValidCount(0);
+        Mockito.when(batchRepository.findBatch("batch-filter-only")).thenReturn(batch);
+        Mockito.when(batchRepository.findValidItems("batch-filter-only")).thenReturn(Collections.emptyList());
+        CustomerSessionRecord record = new CustomerSessionRecord();
+        record.setCallId("call-1");
+        Mockito.when(customerSessionMysqlRepository.queryForHandle(Mockito.any(CustomerSessionQueryRequest.class), Mockito.anyInt()))
+                .thenReturn(Collections.singletonList(record));
+        Mockito.when(queryHandleService.createHandle(Mockito.anyMap())).thenReturn(handleArtifacts());
+        AgentSessionBatchService service = service(batchRepository, customerSessionMysqlRepository, queryHandleService);
+
+        AgentSessionBatchDtos.FilterRequest request = new AgentSessionBatchDtos.FilterRequest();
+        request.setBatchCode("personal-batch-1");
+        request.setChannel("VOICE");
+        AgentSessionBatchDtos.FilterResponse response = service.filter("batch-filter-only", request);
+
+        ArgumentCaptor<CustomerSessionQueryRequest> queryCaptor = ArgumentCaptor.forClass(CustomerSessionQueryRequest.class);
+        Mockito.verify(customerSessionMysqlRepository).queryForHandle(queryCaptor.capture(), Mockito.anyInt());
+        Assertions.assertTrue(queryCaptor.getValue().getSessionIds().isEmpty());
+        Assertions.assertEquals("VOICE", queryCaptor.getValue().getChannel());
+        Assertions.assertEquals("personal-batch-1", queryCaptor.getValue().getExtraFilters().get("batchCode"));
+        ArgumentCaptor<Map<String, Object>> handleCaptor = ArgumentCaptor.forClass(Map.class);
+        Mockito.verify(queryHandleService).createHandle(handleCaptor.capture());
+        Map<?, ?> filters = (Map<?, ?>) handleCaptor.getValue().get("filters");
+        Assertions.assertFalse(filters.containsKey("session_ids"));
+        Assertions.assertEquals("personal-batch-1", filters.get("batchCode"));
+        Assertions.assertEquals(Integer.valueOf(1), response.getMatchedCount());
+        Assertions.assertEquals(Collections.singletonList("call-1"), response.getSessionIds());
+    }
+
+    private AgentSessionBatchService service(AgentSessionBatchRepository batchRepository,
+                                             CustomerSessionMysqlRepository customerSessionMysqlRepository,
+                                             QueryHandleService queryHandleService) {
+        return new AgentSessionBatchService(batchRepository, customerSessionMysqlRepository, queryHandleService);
+    }
+
+    private Map<String, Object> handleArtifacts() {
+        Map<String, Object> artifacts = new LinkedHashMap<String, Object>();
+        artifacts.put("query_instance_id", "query-1");
+        return artifacts;
+    }
+}