flzxsqc-demo 1.4.26 → 1.4.28

package/agent-backend/src/main/java/com/example/agent/application/harness/tool/ToolInvocationGuard.java

@@ -14,6 +14,7 @@ import com.example.agent.domain.model.ToolValidationException;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 
@@ -125,25 +126,57 @@ public class ToolInvocationGuard {
 
     private void validateRequiredArtifact(AgentSession session, ToolDefinition definition, ToolPrecondition precondition) {
         String artifact = trimToNull(precondition.getArtifact());
-        String sourceTool = trimToNull(precondition.getSourceTool());
-        if (artifact == null || sourceTool == null) {
+        List<String> sourceTools = sourceTools(precondition);
+        if (artifact == null || sourceTools.isEmpty()) {
             return;
         }
+        if (hasRequiredArtifact(session, sourceTools, artifact)) {
+            return;
+        }
+        throw validation(
+                "TOOL_PRECONDITION_FAILED",
+                "Tool '" + definition.getToolId() + "' requires artifact '" + artifact
+                        + "' from one of tools " + sourceTools + ".",
+                "Call one of " + sourceTools + " first, then bind artifacts." + artifact + " before retrying."
+        );
+    }
+
+    private List<String> sourceTools(ToolPrecondition precondition) {
+        List<String> result = new ArrayList<String>();
+        addSourceTool(result, precondition.getSourceTool());
+        if (precondition.getSourceTools() != null) {
+            for (String sourceTool : precondition.getSourceTools()) {
+                addSourceTool(result, sourceTool);
+            }
+        }
+        return result;
+    }
+
+    private void addSourceTool(List<String> sourceTools, String sourceTool) {
+        String normalized = trimToNull(sourceTool);
+        if (normalized != null && !sourceTools.contains(normalized)) {
+            sourceTools.add(normalized);
+        }
+    }
+
+    private boolean hasRequiredArtifact(AgentSession session, List<String> sourceTools, String artifact) {
         for (int i = session.getExecutedSteps().size() - 1; i >= 0; i--) {
             AgentExecutedStep step = session.getExecutedSteps().get(i);
-            if (step == null || !"SUCCEEDED".equals(step.getStatus()) || !sourceTool.equals(step.getToolName())) {
+            if (!isSuccessfulSource(step, sourceTools)) {
                 continue;
             }
             Object value = step.getArtifacts().get(artifact);
             if (value != null && trimToNull(String.valueOf(value)) != null) {
-                return;
+                return true;
             }
         }
-        throw validation(
-                "TOOL_PRECONDITION_FAILED",
-                "Tool '" + definition.getToolId() + "' requires artifact '" + artifact + "' from tool '" + sourceTool + "'.",
-                "Call '" + sourceTool + "' first, then bind artifacts." + artifact + " before retrying."
-        );
+        return false;
+    }
+
+    private boolean isSuccessfulSource(AgentExecutedStep step, List<String> sourceTools) {
+        return step != null
+                && "SUCCEEDED".equals(step.getStatus())
+                && sourceTools.contains(step.getToolName());
     }
 
     private void validateRequiredFields(ToolDefinition definition, String root, Map<String, Object> source, List<String> requiredPaths) {

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

@@ -20,6 +20,8 @@ import com.example.agent.domain.model.chat.ChatRole;
 import com.example.agent.domain.port.LlmClient;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import lombok.RequiredArgsConstructor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.core.task.TaskExecutor;
 import org.springframework.stereotype.Service;
@@ -46,6 +48,7 @@ import java.util.UUID;
  */
 public class AgentTurnRunner {
     private static final int MAX_ROUNDS = 16;
+    private static final Logger log = LoggerFactory.getLogger(AgentTurnRunner.class);
 
     private final SkillSelector skillSelector;
     private final SkillRegistry skillRegistry;
@@ -298,13 +301,30 @@ public class AgentTurnRunner {
         planningDetails.put("round", roundNumber);
         harnessWorkflowService.started(session.getSessionId(), turn.getTurnId(), HarnessPhase.PLAN_NEXT_ACTION, planningDetails);
         ToolActionRouter.ToolActionDecision decision;
+        long actionRouterStartedAt = System.currentTimeMillis();
+        log.info("Agent action router started sessionId={} turnId={} round={} allowedToolCount={}",
+                session.getSessionId(), turn.getTurnId(), roundNumber, allowedTools == null ? 0 : allowedTools.size());
         try {
             decision = toolActionRouter.decide(session, skills, allowedTools, roundNumber);
         } catch (RuntimeException e) {
             // 路由模型不可用时退回旧的组合式规划器以维持可用性；错误被写入 Harness 详情，便于后续删除该兼容路径。
+            log.warn("Agent action router failed; combined fallback will start sessionId={} turnId={} round={} elapsedMs={} errorType={} error={}",
+                    session.getSessionId(),
+                    turn.getTurnId(),
+                    roundNumber,
+                    System.currentTimeMillis() - actionRouterStartedAt,
+                    e.getClass().getSimpleName(),
+                    e.getMessage());
             planningDetails.put("action_router_fallback_error", e.getMessage());
             return fallbackCombinedPlannerDecision(session, turn, allowedTools, roundNumber, planningDetails);
         }
+        log.info("Agent action router completed sessionId={} turnId={} round={} elapsedMs={} action={} selectedToolId={}",
+                session.getSessionId(),
+                turn.getTurnId(),
+                roundNumber,
+                System.currentTimeMillis() - actionRouterStartedAt,
+                decision.getActionType(),
+                decision.getToolId());
         planningDetails.put("selected_tool_id", decision.getToolId());
         planningDetails.put("decision_reason", decision.getReason());
         planningDetails.put("candidate_tool_ids", toolIds(allowedTools));
@@ -320,8 +340,30 @@ public class AgentTurnRunner {
         }
         ToolDefinition selectedTool = selectedTool(decision.getToolId(), allowedTools);
         // 动作路由只选择工具；参数规划仅暴露被选中工具的 Schema，避免模型混淆多个工具字段并降低上下文开销。
-        ToolArgumentPlannerService.ArgumentPlanningResult argumentPlanningResult =
-                toolArgumentPlannerService.planToolCall(session, skills, selectedTool, roundNumber);
+        long argumentPlannerStartedAt = System.currentTimeMillis();
+        log.info("Agent argument planner started sessionId={} turnId={} round={} selectedToolId={}",
+                session.getSessionId(), turn.getTurnId(), roundNumber, selectedTool.getToolId());
+        ToolArgumentPlannerService.ArgumentPlanningResult argumentPlanningResult;
+        try {
+            argumentPlanningResult = toolArgumentPlannerService.planToolCall(session, skills, selectedTool, roundNumber);
+        } catch (RuntimeException e) {
+            log.warn("Agent argument planner failed sessionId={} turnId={} round={} selectedToolId={} elapsedMs={} errorType={} error={}",
+                    session.getSessionId(),
+                    turn.getTurnId(),
+                    roundNumber,
+                    selectedTool.getToolId(),
+                    System.currentTimeMillis() - argumentPlannerStartedAt,
+                    e.getClass().getSimpleName(),
+                    e.getMessage());
+            throw e;
+        }
+        log.info("Agent argument planner completed sessionId={} turnId={} round={} selectedToolId={} elapsedMs={} retryCount={}",
+                session.getSessionId(),
+                turn.getTurnId(),
+                roundNumber,
+                selectedTool.getToolId(),
+                System.currentTimeMillis() - argumentPlannerStartedAt,
+                argumentPlanningResult.getRetryCount());
         ChatMessage reply = argumentPlanningResult.getReply();
         runtimeEventBus.publish(session.getSessionId(), turn.getTurnId(), RuntimeEventType.MODEL_DECISION,
                 payload("content", reply.getContent(), "toolCalls", reply.getToolCalls(), "round", roundNumber,
@@ -341,7 +383,33 @@ public class AgentTurnRunner {
                                                         int roundNumber,
                                                         Map<String, Object> planningDetails) {
         List<ChatMessage> messagesForLlm = contextBudgetService.prepareMessagesForToolPlanning(session, allowedTools);
-        ChatMessage reply = LlmRoleContext.call(ModelRole.PLANNER, () -> llmClient.chat(messagesForLlm, allowedTools));
+        long fallbackStartedAt = System.currentTimeMillis();
+        log.info("Agent combined fallback started sessionId={} turnId={} round={} messageCount={} allowedToolCount={}",
+                session.getSessionId(),
+                turn.getTurnId(),
+                roundNumber,
+                messagesForLlm.size(),
+                allowedTools == null ? 0 : allowedTools.size());
+        ChatMessage reply;
+        try {
+            reply = LlmRoleContext.call(ModelRole.PLANNER, () -> llmClient.chat(messagesForLlm, allowedTools));
+        } catch (RuntimeException e) {
+            log.warn("Agent combined fallback failed sessionId={} turnId={} round={} elapsedMs={} errorType={} error={}",
+                    session.getSessionId(),
+                    turn.getTurnId(),
+                    roundNumber,
+                    System.currentTimeMillis() - fallbackStartedAt,
+                    e.getClass().getSimpleName(),
+                    e.getMessage());
+            throw e;
+        }
+        log.info("Agent combined fallback completed sessionId={} turnId={} round={} elapsedMs={} contentChars={} toolCallCount={}",
+                session.getSessionId(),
+                turn.getTurnId(),
+                roundNumber,
+                System.currentTimeMillis() - fallbackStartedAt,
+                reply.getContent() == null ? 0 : reply.getContent().length(),
+                reply.getToolCalls() == null ? 0 : reply.getToolCalls().size());
         runtimeEventBus.publish(session.getSessionId(), turn.getTurnId(), RuntimeEventType.MODEL_DECISION,
                 payload("content", reply.getContent(), "toolCalls", reply.getToolCalls(), "round", roundNumber,
                         "allowed_tool_ids", toolIds(allowedTools), "report_tool_allowed", containsTool(allowedTools, "build_keyword_report"),
@@ -413,13 +481,27 @@ public class AgentTurnRunner {
     }
 
     private List<SkillDefinition> questionRequirementSkills(List<SkillDefinition> selectedSkills) {
-        if (hasEnabledQuestionRequirements(selectedSkills)) {
+        if (hasQuestionRequirementsConfiguration(selectedSkills)) {
             return selectedSkills;
         }
         List<SkillDefinition> allSkills = skillRegistry.allEnabled();
         return hasEnabledQuestionRequirements(allSkills) ? allSkills : selectedSkills;
     }
 
+    private boolean hasQuestionRequirementsConfiguration(List<SkillDefinition> skills) {
+        if (skills == null) {
+            return false;
+        }
+        for (SkillDefinition skill : skills) {
+            if (skill != null
+                    && skill.getQuestionRequirements() != null
+                    && skill.getQuestionRequirements().containsKey("enabled")) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private boolean hasEnabledQuestionRequirements(List<SkillDefinition> skills) {
         if (skills == null) {
             return false;

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

@@ -6,6 +6,8 @@ import com.example.agent.infrastructure.repository.AgentEventRepository;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import lombok.RequiredArgsConstructor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.stereotype.Service;
 import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
 
@@ -30,6 +32,8 @@ import java.util.concurrent.CopyOnWriteArrayList;
  * 但 trace/span/turn/event 等稳定字段由本类统一写入。</p>
  */
 public class RuntimeEventBus {
+    private static final Logger log = LoggerFactory.getLogger(RuntimeEventBus.class);
+
     private final AgentEventRepository repository;
     private final ObjectMapper objectMapper;
     private final Map<String, CopyOnWriteArrayList<SseEmitter>> subscribers = new ConcurrentHashMap<String, CopyOnWriteArrayList<SseEmitter>>();
@@ -62,16 +66,49 @@ public class RuntimeEventBus {
             event.setTurnId((String) row.get("turn_id"));
             event.setEventType(RuntimeEventType.valueOf(String.valueOf(row.get("event_type"))));
             event.setCreatedAt(toInstant(row.get("created_at")));
-            try {
-                event.setPayload(objectMapper.readValue(String.valueOf(row.get("payload_json")), new TypeReference<Map<String, Object>>() {}));
-            } catch (Exception e) {
-                throw new RuntimeException("failed to parse event payload", e);
-            }
+            event.setPayload(readHistoryPayload(row, event));
             events.add(event);
         }
         return events;
     }
 
+    private Map<String, Object> readHistoryPayload(Map<String, Object> row, RuntimeEvent event) {
+        Object rawPayload = row.get("payload_json");
+        if (rawPayload == null) {
+            log.warn("Runtime event payload unavailable eventId={} sessionId={} turnId={} eventType={} payloadRefId={}",
+                    event.getId(), event.getSessionId(), event.getTurnId(), event.getEventType(), row.get("payload_ref_id"));
+            return unavailablePayload(row, "missing");
+        }
+        try {
+            Map<String, Object> payload = objectMapper.readValue(
+                    String.valueOf(rawPayload),
+                    new TypeReference<Map<String, Object>>() {});
+            return payload == null ? unavailablePayload(row, "empty") : payload;
+        } catch (Exception e) {
+            log.warn("Runtime event payload is invalid JSON eventId={} sessionId={} turnId={} eventType={} payloadRefId={} error={}",
+                    event.getId(),
+                    event.getSessionId(),
+                    event.getTurnId(),
+                    event.getEventType(),
+                    row.get("payload_ref_id"),
+                    e.getMessage());
+            return unavailablePayload(row, "invalid_json");
+        }
+    }
+
+    private Map<String, Object> unavailablePayload(Map<String, Object> row, String reason) {
+        Map<String, Object> payload = new HashMap<String, Object>();
+        payload.put("payload_unavailable", true);
+        payload.put("payload_error", reason);
+        if (row.get("payload_ref_id") != null) {
+            payload.put("payload_ref_id", row.get("payload_ref_id"));
+        }
+        if (row.get("payload_preview") != null) {
+            payload.put("payload_preview", row.get("payload_preview"));
+        }
+        return payload;
+    }
+
     public SseEmitter subscribe(String sessionId) {
         SseEmitter emitter = new SseEmitter(0L);
         subscribers.computeIfAbsent(sessionId, ignored -> new CopyOnWriteArrayList<SseEmitter>()).add(emitter);

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

@@ -31,6 +31,7 @@ import java.util.UUID;
  */
 public class ToolArgumentPlannerService {
     private static final int SKILL_PROMPT_LIMIT = 10000;
+    private static final String SKILL_PER_RECORD_ANALYSIS_TOOL_ID = "analyze_sessions_per_record_by_skill_async";
 
     private final LlmClient llmClient;
     private final ContextBudgetService contextBudgetService;
@@ -44,26 +45,26 @@ public class ToolArgumentPlannerService {
         List<ChatMessage> messages = argumentPlanningMessages(session, skills, selectedTool, roundNumber);
         List<ToolDefinition> selectedOnly = Collections.singletonList(selectedTool);
         ChatMessage reply = LlmRoleContext.call(ModelRole.PLANNER, () -> llmClient.chat(messages, selectedOnly));
-        if (hasToolCalls(reply)) {
+        if (hasSelectedToolCall(reply, selectedTool)) {
             return new ArgumentPlanningResult(reply, tokenEstimateService.estimateMessages(messages), 0, false);
         }
-        if (!looksLikeTextToolCall(reply == null ? null : reply.getContent())) {
-            return new ArgumentPlanningResult(reply, tokenEstimateService.estimateMessages(messages), 0, false);
-        }
-        messages.add(message(ChatRole.ASSISTANT, reply.getContent()));
-        messages.add(message(ChatRole.SYSTEM, malformedToolCallRecoveryInstruction(selectedTool)));
+        boolean malformedTextToolCall = looksLikeTextToolCall(reply == null ? null : reply.getContent());
+        addRetryContext(messages, reply, selectedTool, malformedTextToolCall);
         ChatMessage retryReply = LlmRoleContext.call(ModelRole.PLANNER, () -> llmClient.chat(messages, selectedOnly));
-        if (hasToolCalls(retryReply)) {
-            return new ArgumentPlanningResult(retryReply, tokenEstimateService.estimateMessages(messages), 1, true);
+        if (hasSelectedToolCall(retryReply, selectedTool)) {
+            return new ArgumentPlanningResult(
+                    retryReply,
+                    tokenEstimateService.estimateMessages(messages),
+                    1,
+                    malformedTextToolCall
+            );
         }
-        ChatMessage repaired = repairTextToolCall(retryReply == null ? null : retryReply.getContent(), selectedTool);
-        if (!hasToolCalls(repaired)) {
-            repaired = repairTextToolCall(reply.getContent(), selectedTool);
-        }
-        if (hasToolCalls(repaired)) {
+        ChatMessage repaired = repairTextToolCallFromReplies(reply, retryReply, selectedTool);
+        if (hasSelectedToolCall(repaired, selectedTool)) {
             return new ArgumentPlanningResult(repaired, tokenEstimateService.estimateMessages(messages), 1, true);
         }
-        return new ArgumentPlanningResult(retryReply, tokenEstimateService.estimateMessages(messages), 1, true);
+        throw new IllegalStateException("selected tool `" + selectedTool.getToolId()
+                + "` produced no executable function/tool call after one correction");
     }
 
     private List<ChatMessage> argumentPlanningMessages(AgentSession session,
@@ -88,11 +89,28 @@ public class ToolArgumentPlannerService {
         builder.append("Use the selected tool schema supplied by the API. Do not call any other tool.\n");
         builder.append("Use source_ref/source_refs for prior evidence when possible. Do not copy large prior tool outputs into arguments.\n");
         builder.append("Relevant skill details:\n");
+        appendRelevantSkillDetails(builder, skills, selectedTool);
+        return builder.toString();
+    }
+
+    private void appendRelevantSkillDetails(StringBuilder builder,
+                                            List<SkillDefinition> skills,
+                                            ToolDefinition selectedTool) {
+        if (isSkillPerRecordAnalysisTool(selectedTool)) {
+            builder.append("### server-managed-skill-analysis\n");
+            builder.append("The runtime injects the excellent-case analysis prompt and fixed analysis_targets. ");
+            builder.append("Do not generate analysis_prompt or analysis_targets. ");
+            builder.append("Generate the queryId from the prior query handle.\n\n");
+            return;
+        }
         for (SkillDefinition skill : relevantSkills(skills, selectedTool.getToolId())) {
             builder.append("### ").append(skill.getSkillId()).append("\n");
             builder.append(truncate(skill.getPromptMarkdown(), SKILL_PROMPT_LIMIT)).append("\n\n");
         }
-        return builder.toString();
+    }
+
+    private boolean isSkillPerRecordAnalysisTool(ToolDefinition selectedTool) {
+        return selectedTool != null && SKILL_PER_RECORD_ANALYSIS_TOOL_ID.equals(selectedTool.getToolId());
     }
 
     private List<SkillDefinition> relevantSkills(List<SkillDefinition> skills, String toolId) {
@@ -108,10 +126,33 @@ public class ToolArgumentPlannerService {
         return result.isEmpty() ? skills : result;
     }
 
-    private String malformedToolCallRecoveryInstruction(ToolDefinition selectedTool) {
-        return "Runtime correction: the previous response wrote a tool call as assistant text. "
-                + "That is invalid. Call `" + selectedTool.getToolId()
-                + "` using the actual function/tool channel now. Do not include prose or raw tool_call JSON.";
+    private void addRetryContext(List<ChatMessage> messages,
+                                 ChatMessage reply,
+                                 ToolDefinition selectedTool,
+                                 boolean malformedTextToolCall) {
+        if (reply != null && hasText(reply.getContent())) {
+            messages.add(message(ChatRole.ASSISTANT, reply.getContent()));
+        }
+        messages.add(message(ChatRole.SYSTEM, toolCallRecoveryInstruction(selectedTool, malformedTextToolCall)));
+    }
+
+    private String toolCallRecoveryInstruction(ToolDefinition selectedTool, boolean malformedTextToolCall) {
+        String reason = malformedTextToolCall
+                ? "the previous response wrote a tool call as assistant text"
+                : "the previous response did not emit an executable tool call";
+        return "Runtime correction: " + reason + ". "
+                + "Call `" + selectedTool.getToolId()
+                + "` using the actual function/tool channel now. Emit exactly one call and no prose or raw tool_call JSON.";
+    }
+
+    private ChatMessage repairTextToolCallFromReplies(ChatMessage firstReply,
+                                                      ChatMessage retryReply,
+                                                      ToolDefinition selectedTool) {
+        ChatMessage repaired = repairTextToolCall(retryReply == null ? null : retryReply.getContent(), selectedTool);
+        if (hasSelectedToolCall(repaired, selectedTool)) {
+            return repaired;
+        }
+        return repairTextToolCall(firstReply == null ? null : firstReply.getContent(), selectedTool);
     }
 
     private ChatMessage repairTextToolCall(String content, ToolDefinition selectedTool) {
@@ -171,8 +212,14 @@ public class ToolArgumentPlannerService {
                 && payload.containsKey("arguments");
     }
 
-    private boolean hasToolCalls(ChatMessage reply) {
-        return reply != null && reply.getToolCalls() != null && !reply.getToolCalls().isEmpty();
+    private boolean hasSelectedToolCall(ChatMessage reply, ToolDefinition selectedTool) {
+        if (reply == null || reply.getToolCalls() == null || reply.getToolCalls().size() != 1) {
+            return false;
+        }
+        ToolCall toolCall = reply.getToolCalls().get(0);
+        return toolCall != null
+                && toolCall.getFunction() != null
+                && selectedTool.getToolId().equals(toolCall.getFunction().getName());
     }
 
     private ChatMessage message(ChatRole role, String content) {

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

@@ -34,21 +34,43 @@ public class AgentSessionFilter {
     private Map<String, Object> extensions = new LinkedHashMap<String, Object>();
 
     public boolean isEmpty() {
+        return isBasicScopeEmpty()
+                && isRoutingScopeEmpty()
+                && isBusinessScopeEmpty()
+                && isResultControlEmpty();
+    }
+
+    private boolean isBasicScopeEmpty() {
         return sessionIds.isEmpty()
                 && channel == null
                 && batchCode == null
-                && startTime == null
-                && endTime == null
-                && agentId == null
+                && isTimeRangeEmpty();
+    }
+
+    private boolean isTimeRangeEmpty() {
+        return startTime == null && endTime == null;
+    }
+
+    private boolean isRoutingScopeEmpty() {
+        return agentId == null
                 && queueId == null
                 && teamIds.isEmpty()
-                && groupIds.isEmpty()
-                && fullJourney == null
+                && groupIds.isEmpty();
+    }
+
+    private boolean isBusinessScopeEmpty() {
+        return fullJourney == null
                 && dataSource == null
                 && conversationType == null
-                && businessLine == null
-                && customerId == null
-                && keywords.isEmpty()
+                && isBusinessIdentityEmpty();
+    }
+
+    private boolean isBusinessIdentityEmpty() {
+        return businessLine == null && customerId == null;
+    }
+
+    private boolean isResultControlEmpty() {
+        return keywords.isEmpty()
                 && limit == null
                 && extensions.isEmpty();
     }