flzxsqc-demo 1.4.13 → 1.4.15

package/agent-backend/docs/digital-analysis-current-implementation-design.md

@@ -60,6 +60,7 @@
 7. 多目标分析底层链路
    - `analyze_sessions_per_record_async` 支持 `analysis_targets`。
    - prompt 编译要求每条结构化 item 带 `target`。
+   - `aggregate_analysis_results` 要求传 `targets`，按 `items[].target` 输出 `primary_counts_by_target` 和 `category_sample_rows_by_target`。
    - `cluster_analysis_results` 支持按 target 输出 `clusters_by_target` 和 `assignment_trace_sample_by_target`。
    - 长耗时分析确认文案支持把多个分析目标拆成编号列表，例如“客户意图”和“客户要求转人工的原因”会分别展示，避免用户只能看到一段合并后的目标描述。
 
@@ -509,19 +510,56 @@ agent-backend/src/main/java/com/example/agent/application/harness/analysis/Analy
 agent-backend/src/main/java/com/example/agent/application/service/localtool/AnalysisResultAggregationService.java
 ```
 
+`aggregate_analysis_results` 负责确定性计数聚合，适用于 TopN 统计、按会话数降序、分类计数等需求。新链路要求所有调用都传 `targets`，单目标也传一个元素；不要在 `aggregation_spec` 中传 `target`。
+
+固定入参形态：
+
+```json
+{
+  "analysis_result_id": "result-xxx",
+  "targets": ["customer_intent", "handoff_reason"],
+  "top_n": 5,
+  "aggregation_spec": {
+    "item_path": "items",
+    "value_path": "label",
+    "output_key": "label",
+    "description_path": "description",
+    "evidence_path": "evidence",
+    "category_path": "category"
+  }
+}
+```
+
+多目标聚合输出：
+
+- `primary_items_by_target`
+- `primary_counts_by_target`
+- `category_sample_rows_by_target`
+- `available_targets`
+- `target_item_counts`
+- `target_record_counts`
+- `empty_targets`
+
+报告引用聚合结果时使用：
+
+- `aggregate_analysis_results:exports.primary_counts_by_target.<target>`
+- `aggregate_analysis_results:exports.category_sample_rows_by_target.<target>`
+
 语义聚类：
 
 ```text
 agent-backend/src/main/java/com/example/agent/application/service/localtool/AnalysisResultClusteringService.java
 ```
 
+`cluster_analysis_results` 负责无监督语义聚类，适用于未知类型发现、相似语义归纳、负面情绪类别发现等需求；不要用 cluster 替代明确的 TopN 计数聚合。
+
 多目标聚类输出：
 
 - `clusters_by_target`
 - `cluster_run_ids_by_target`
 - `assignment_trace_sample_by_target`
 
-其中 `assignment_trace_sample` / representative cases 带 `session_code`，用于会话溯源。
+其中 `assignment_trace_sample` / representative cases 带 `session_code`，用于会话溯源。报告引用聚类结果时使用 `cluster_analysis_results:exports.clusters_by_target.<target>.clusters` 和 `cluster_analysis_results:exports.clusters_by_target.<target>.category_sample_rows`。
 
 ### 7.4 多目标用户确认展示
 
@@ -548,7 +586,7 @@ agent-backend/src/main/java/com/example/agent/application/harness/requirements/S
 - 输出形式：Top5聚类
 ```
 
-该确认只负责让用户判断“目标识别是否正确”。真正执行逐条分析时，仍由 `analyze_sessions_per_record_async.analysis_targets` 传入稳定目标 key，并由 prompt 编译要求每个 item 写入 `target`。
+该确认只负责让用户判断“目标识别是否正确”。真正执行逐条分析时，仍由 `analyze_sessions_per_record_async.analysis_targets` 传入稳定目标 key，并由 prompt 编译要求每个 item 写入 `target`；下游 aggregate/cluster 的 `targets` 必须与这组 key 保持一致。
 
 ### 7.5 异步逐条结果解析容错
 
@@ -623,7 +661,7 @@ build_keyword_report -> ReportAssemblyService -> latestAnswer -> AnalysisTaskPag
 - 报告按分类值采样。
 - 从报告跳转会话详情。
 
-因此当前报告是否按目标分组、是否每条问题举例都带会话 ID，取决于 LLM 生成的 report blueprint 是否引用了 `clusters_by_target`、`assignment_trace_sample_by_target` 或其他带 `session_code` 的工具输出，不是后端结构化强约束。
+因此当前报告是否按目标分组、是否每条问题举例都带会话 ID，取决于 LLM 生成的 report blueprint 是否引用了对应 by-target 证据路径。计数聚合报告应引用 `aggregate_analysis_results:exports.primary_counts_by_target.<target>` 和 `aggregate_analysis_results:exports.category_sample_rows_by_target.<target>`；语义聚类报告应引用 `clusters_by_target`、`assignment_trace_sample_by_target` 或其他带 `session_code` 的工具输出。
 
 ## 10. DSL 重放关联优化
 

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/analysis/AnalysisPromptCompiler.java

@@ -51,7 +51,7 @@ public class AnalysisPromptCompiler {
                 "- items：array，只放当前会话中可用于后续聚合的结构化条目，最多 " + limit + " 个；没有命中返回 []。",
                 "- summary：string，用一句话概括当前会话的分析结论；没有命中也要说明未发现目标现象。",
                 "- items 中每个对象的字段必须与固定输出 JSON 结构中的 items 声明保持一致。",
-                "- items[].target：必须填写当前条目所属分析目标 key；单目标任务使用 default，多目标任务只能使用 analysis_targets 中的 key。",
+                "- items[].target：必须填写当前条目所属分析目标 key；必须使用 analysis_targets 中的 key。",
                 "- 所有结论必须能从当前会话原文找到依据。"
         );
     }

package/agent-backend/src/main/java/com/example/agent/application/harness/prompt/RuntimeInstructionFactory.java

@@ -12,6 +12,7 @@ import java.util.Map;
 
 @Service
 public class RuntimeInstructionFactory {
+    private static final int SOURCE_REF_LIMIT = 80;
     private final ObjectMapper objectMapper;
 
     public RuntimeInstructionFactory(ObjectMapper objectMapper) {
@@ -131,11 +132,18 @@ public class RuntimeInstructionFactory {
     }
 
     private void addRefs(List<String> refs, String toolName, String namespace, Object value) {
-        if (!(value instanceof Map)) {
+        if (!(value instanceof Map) || refs.size() >= SOURCE_REF_LIMIT) {
             return;
         }
-        for (Object key : ((Map<?, ?>) value).keySet()) {
-            refs.add(toolName + ":" + namespace + "." + String.valueOf(key));
+        for (Map.Entry<?, ?> entry : ((Map<?, ?>) value).entrySet()) {
+            String path = namespace + "." + String.valueOf(entry.getKey());
+            refs.add(toolName + ":" + path);
+            if (entry.getValue() instanceof Map) {
+                addRefs(refs, toolName, path, entry.getValue());
+            }
+            if (refs.size() >= SOURCE_REF_LIMIT) {
+                return;
+            }
         }
     }
 

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/DslCompilerService.java

@@ -218,7 +218,10 @@ public class DslCompilerService {
         template.put("report_blueprint", sanitizedBlueprint);
         Object rawReportInputs = executedStep.getArgs().get("report_inputs");
         if (rawReportInputs instanceof Map) {
-            template.put("report_inputs", buildReportInputTemplate("report_inputs", rawReportInputs, priorSteps, step));
+            Object reportInputTemplate = buildReportInputTemplate("report_inputs", rawReportInputs, priorSteps, step);
+            template.put("report_inputs", reportInputTemplate instanceof Map
+                    ? reportInputTemplate
+                    : new LinkedHashMap<String, Object>());
         } else {
             template.put("report_inputs", new LinkedHashMap<String, Object>());
         }
@@ -333,6 +336,22 @@ public class DslCompilerService {
                                             List<CompiledStepContext> priorSteps,
                                             ExecutableDslStep step) {
         ToolScopedPath scopedPath = findToolScopedPath(targetPath, priorSteps);
+        if (rawValue instanceof Map) {
+            Map<String, Object> source = objectMapper.convertValue(rawValue, Map.class);
+            if (isSourceDescriptor(source)) {
+                return source;
+            }
+            if (isResolvedToolScopedMap(scopedPath, priorSteps)) {
+                Map<String, Object> nestedTemplate = new LinkedHashMap<String, Object>();
+                for (Map.Entry<String, Object> entry : source.entrySet()) {
+                    Object nestedValue = buildReportInputTemplate(targetPath + "." + entry.getKey(), entry.getValue(), priorSteps, step);
+                    if (nestedValue != null) {
+                        nestedTemplate.put(entry.getKey(), nestedValue);
+                    }
+                }
+                return nestedTemplate.isEmpty() ? null : nestedTemplate;
+            }
+        }
         if (scopedPath != null) {
             ExecutableDslInputBinding scopedBinding = inferToolScopedBinding(targetPath, scopedPath, rawValue, priorSteps);
             if (scopedBinding != null) {
@@ -357,7 +376,7 @@ public class DslCompilerService {
                     nestedTemplate.put(entry.getKey(), nestedValue);
                 }
             }
-            return nestedTemplate;
+            return nestedTemplate.isEmpty() ? null : nestedTemplate;
         }
         if (rawValue instanceof List && scopedPath != null) {
             return null;
@@ -365,6 +384,15 @@ public class DslCompilerService {
         return rawValue;
     }
 
+    private boolean isResolvedToolScopedMap(ToolScopedPath scopedPath, List<CompiledStepContext> priorSteps) {
+        if (scopedPath == null) {
+            return false;
+        }
+        CompiledStepContext priorStep = findPriorStepByToolName(scopedPath.toolName, priorSteps);
+        String sourcePath = resolveToolScopedSourcePath(priorStep, scopedPath.remainder);
+        return resolveSourceValue(priorStep, sourcePath) instanceof Map;
+    }
+
     private void attachBlueprintSourceBindings(Map<String, Object> sanitizedBlueprint,
                                                List<CompiledStepContext> priorSteps,
                                                ExecutableDslStep step) {
@@ -574,15 +602,25 @@ public class DslCompilerService {
         if (priorStep.exports.containsKey(remainder)) {
             return "exports." + remainder;
         }
+        if (resolveNestedValue(priorStep.exports, remainder) != null) {
+            return "exports." + remainder;
+        }
         if ("records".equals(remainder) && resolveSourceValue(priorStep, "data.records") != null) {
             return "data.records";
         }
         if (priorStep.artifacts.containsKey(remainder)) {
             return "artifacts." + remainder;
         }
+        if (resolveNestedValue(priorStep.artifacts, remainder) != null) {
+            return "artifacts." + remainder;
+        }
         if (priorStep.outputData instanceof Map && ((Map<?, ?>) priorStep.outputData).containsKey(remainder)) {
             return "data." + remainder;
         }
+        if (priorStep.outputData instanceof Map
+                && resolveNestedValue((Map<String, Object>) priorStep.outputData, remainder) != null) {
+            return "data." + remainder;
+        }
         return null;
     }
 

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

@@ -24,7 +24,7 @@ import java.util.regex.Pattern;
 public class ReportAssemblyService {
     private static final Pattern TEMPLATE_VARIABLE = Pattern.compile("\\{\\{\\s*([a-zA-Z0-9_\\.]+)\\s*}}");
     private static final Pattern SIMPLE_TEMPLATE_VARIABLE = Pattern.compile("(?<!\\{)\\{\\s*([a-zA-Z0-9_\\.]+)\\s*}(?!})");
-    private static final String AGGREGATE_CATEGORY_SAMPLE_ROWS = "aggregate_analysis_results:exports.category_sample_rows";
+    private static final String AGGREGATE_CATEGORY_SAMPLE_ROWS_BY_TARGET = "aggregate_analysis_results:exports.category_sample_rows_by_target";
     private static final String CLUSTER_CATEGORY_SAMPLE_ROWS = "cluster_analysis_results:exports.category_sample_rows";
     private final ObjectMapper objectMapper;
     private final BindingResolver bindingResolver;
@@ -81,7 +81,7 @@ public class ReportAssemblyService {
     private String renderMissingCategorySampleTables(ReportBlueprint blueprint, Map<String, Object> inputs) {
         List<String> tables = new ArrayList<String>();
         List<String> referencedSourceLabels = referencedSourceLabels(blueprint);
-        appendCategorySampleTable(tables, inputs, referencedSourceLabels, AGGREGATE_CATEGORY_SAMPLE_ROWS, "聚合分类样本");
+        appendAggregateCategorySampleTablesByTarget(tables, inputs, referencedSourceLabels);
         appendCategorySampleTable(tables, inputs, referencedSourceLabels, CLUSTER_CATEGORY_SAMPLE_ROWS, "聚类分类样本");
         if (tables.isEmpty()) {
             return "";
@@ -89,6 +89,33 @@ public class ReportAssemblyService {
         return "## 分类样本明细\n\n" + String.join("\n\n", tables);
     }
 
+    @SuppressWarnings("unchecked")
+    private void appendAggregateCategorySampleTablesByTarget(List<String> tables,
+                                                             Map<String, Object> inputs,
+                                                             List<String> referencedSourceLabels) {
+        if (isCategorySampleSourceReferenced(referencedSourceLabels, AGGREGATE_CATEGORY_SAMPLE_ROWS_BY_TARGET)) {
+            return;
+        }
+        Object rawRowsByTarget = inputs.get(AGGREGATE_CATEGORY_SAMPLE_ROWS_BY_TARGET);
+        if (!(rawRowsByTarget instanceof Map)) {
+            return;
+        }
+        Map<String, Object> rowsByTarget = objectMapper.convertValue(rawRowsByTarget, new TypeReference<Map<String, Object>>() {});
+        for (Map.Entry<String, Object> entry : rowsByTarget.entrySet()) {
+            String target = entry.getKey();
+            Object rows = entry.getValue();
+            if (normalizeTableRows(rows).isEmpty()) {
+                continue;
+            }
+            String instruction = "聚合分类样本 - " + target;
+            ReportBlockBlueprint block = categorySampleTableBlock(AGGREGATE_CATEGORY_SAMPLE_ROWS_BY_TARGET + "." + target, instruction, false);
+            String table = renderStructuredTable(instruction, rows, block);
+            if (hasText(table)) {
+                tables.add(table);
+            }
+        }
+    }
+
     private void appendCategorySampleTable(List<String> tables,
                                            Map<String, Object> inputs,
                                            List<String> referencedSourceLabels,
@@ -101,23 +128,25 @@ public class ReportAssemblyService {
         if (normalizeTableRows(rows).isEmpty()) {
             return;
         }
-        ReportBlockBlueprint block = categorySampleTableBlock(sourceRef, instruction);
+        ReportBlockBlueprint block = categorySampleTableBlock(sourceRef, instruction, true);
         String table = renderStructuredTable(instruction, rows, block);
         if (hasText(table)) {
             tables.add(table);
         }
     }
 
-    private ReportBlockBlueprint categorySampleTableBlock(String sourceRef, String instruction) {
+    private ReportBlockBlueprint categorySampleTableBlock(String sourceRef, String instruction, boolean includeDescription) {
         ReportBlockBlueprint block = new ReportBlockBlueprint();
         block.setBlockType("table");
         block.setInstruction(instruction);
         block.setSourceRef(ReportSourceRef.fromString(sourceRef));
         List<ReportTableColumnBlueprint> columns = new ArrayList<ReportTableColumnBlueprint>();
         columns.add(column("分类", "category"));
-        columns.add(column("描述", "description"));
-        columns.add(column("样本关键会话", "sample_key_sessions"));
-        columns.add(column("样本会话ID", "sample_session_ids"));
+        if (includeDescription) {
+            columns.add(column("描述", "description"));
+        }
+        columns.add(column("抽样原文依据", "sample_key_sessions"));
+        columns.add(column("对应会话ID", "sample_session_ids"));
         block.setColumns(columns);
         return block;
     }
@@ -175,8 +204,16 @@ public class ReportAssemblyService {
             if (!hasText(label)) {
                 continue;
             }
-            if (sourceRef.equals(label) || "category_sample_rows".equals(label)
-                    || "exports.category_sample_rows".equals(label)) {
+            if (sourceRef.equals(label)
+                    || "category_sample_rows".equals(label)
+                    || "category_sample_rows_by_target".equals(label)
+                    || "exports.category_sample_rows".equals(label)
+                    || "exports.category_sample_rows_by_target".equals(label)) {
+                return true;
+            }
+            if (sourceRef.startsWith("aggregate_analysis_results:")
+                    && label.startsWith("aggregate_analysis_results:")
+                    && label.contains("category_sample_rows_by_target")) {
                 return true;
             }
             if (sourceRef.startsWith("cluster_analysis_results:")