rag:
      similarity-threshold: 0.7   # 向量相似度过滤阈值，低于此值的文档被丢弃
      default-top-k: 5            # 最终返回的文档数
      query-rewrite-enabled: true  # 检索前是否用 LLM 改写查询，false 时原样传入

    rag:
      similarity-threshold: 0.7   # 向量相似度过滤阈值，低于此值的文档被丢弃
      default-top-k: 5            # 最终返回的文档数
      query-rewrite-enabled: true  # 检索前是否用 LLM 改写查询，false 时原样传入
      max-calls-per-session: 3    # 每次请求最多 RAG 工具调用次数，独立于 maxSteps

./mvnw validate -q

git add src/main/resources/application.yml
git commit -m "config: add app.ai.rag.max-calls-per-session"

package com.dawn.ai.agent;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;

class StepCollectorTest {

    @BeforeEach
    void setUp() {
        StepCollector.init(10);
    }

    @AfterEach
    void tearDown() {
        StepCollector.clear();
    }

    // ── RETRIEVED_QUERIES 测试 ──────────────────────────────────

    @Test
    @DisplayName("isQueryRetrieved: init 后所有查询均未检索过")
    void isQueryRetrieved_afterInit_returnsFalse() {
        assertThat(StepCollector.isQueryRetrieved("any query")).isFalse();
    }

    @Test
    @DisplayName("markQueryRetrieved + isQueryRetrieved: 标记后应返回 true")
    void markQueryRetrieved_thenIsQueryRetrieved_returnsTrue() {
        StepCollector.markQueryRetrieved("Dawn AI 定价");

        assertThat(StepCollector.isQueryRetrieved("Dawn AI 定价")).isTrue();
    }

    @Test
    @DisplayName("isQueryRetrieved: 未标记的查询应返回 false")
    void isQueryRetrieved_unmarkedQuery_returnsFalse() {
        StepCollector.markQueryRetrieved("query A");

        assertThat(StepCollector.isQueryRetrieved("query B")).isFalse();
    }

    @Test
    @DisplayName("clear: 清理后 isQueryRetrieved 应返回 false")
    void clear_resetsRetrievedQueries() {
        StepCollector.markQueryRetrieved("some query");
        StepCollector.clear();
        StepCollector.init(10); // re-init for afterEach

        assertThat(StepCollector.isQueryRetrieved("some query")).isFalse();
    }

    @Test
    @DisplayName("init: 重新初始化后之前标记的查询应被清除")
    void init_clearsRetrievedQueries() {
        StepCollector.markQueryRetrieved("old query");

        StepCollector.init(10); // re-init

        assertThat(StepCollector.isQueryRetrieved("old query")).isFalse();
    }
}

./mvnw test -Dtest=StepCollectorTest -q 2>&1 | grep -E "ERROR|cannot find" | head -5

git add src/test/java/com/dawn/ai/agent/StepCollectorTest.java
git commit -m "test: add failing StepCollectorTest for RETRIEVED_QUERIES (TDD Red)"

package com.dawn.ai.agent;

import com.dawn.ai.exception.MaxStepsExceededException;
import lombok.extern.slf4j.Slf4j;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.concurrent.atomic.AtomicInteger;

/**
 * ThreadLocal-based request-scoped step collector.
 * Bridges ToolExecutionAspect and AgentOrchestrator without touching tool classes.
 *
 * Lifecycle per request:
 *   AgentOrchestrator.doChat() calls init() → AOP records steps → collect() → clear()
 *
 * RETRIEVED_QUERIES tracks already-searched queries within one request to prevent
 * duplicate RAG calls that would waste tokens.
 */
@Slf4j
public class StepCollector {

    private static final ThreadLocal<List<AgentStep>> STEPS =
            ThreadLocal.withInitial(ArrayList::new);
    private static final ThreadLocal<AtomicInteger> COUNTER =
            ThreadLocal.withInitial(() -> new AtomicInteger(0));
    private static final ThreadLocal<Integer> MAX_STEPS = new ThreadLocal<>();
    /** package-private for test accessibility */
    static final ThreadLocal<Set<String>> RETRIEVED_QUERIES =
            ThreadLocal.withInitial(HashSet::new);

    /** Call at the start of each request to reset state from any previous run. */
    public static void init(Integer maxSteps) {
        STEPS.get().clear();
        COUNTER.get().set(0);
        MAX_STEPS.set(maxSteps);
        RETRIEVED_QUERIES.get().clear();
    }

    /** Called by ToolExecutionAspect after each tool invocation. */
    public static void record(AgentStep step) {
        STEPS.get().add(step);
    }

    /** Returns the next monotonically increasing step number for the current request. */
    public static int getAndIncreaseStepNumber() {
        int next = COUNTER.get().incrementAndGet();
        if (next > MAX_STEPS.get()) {
            log.error("Exceeded Max Steps: {}", next);
            throw new MaxStepsExceededException("Exceeded Max Steps: " + MAX_STEPS.get().toString());
        }
        return next;
    }

    /** Returns a snapshot of all recorded steps for the current request. */
    public static List<AgentStep> collect() {
        return new ArrayList<>(STEPS.get());
    }

    /**
     * Returns true if the given rewritten query has already been searched this request.
     * Used by KnowledgeSearchTool to prevent duplicate RAG calls.
     */
    public static boolean isQueryRetrieved(String query) {
        return RETRIEVED_QUERIES.get().contains(query);
    }

    /**
     * Marks a rewritten query as already searched for this request.
     * Call immediately before executing a RAG retrieval.
     */
    public static void markQueryRetrieved(String query) {
        RETRIEVED_QUERIES.get().add(query);
    }

    /** Must be called in a finally block to prevent ThreadLocal memory leaks. */
    public static void clear() {
        STEPS.remove();
        COUNTER.remove();
        MAX_STEPS.remove();
        RETRIEVED_QUERIES.remove();
    }
}

./mvnw test -Dtest=StepCollectorTest -q 2>&1 | tail -10

[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

./mvnw test -q 2>&1 | tail -10

git add src/main/java/com/dawn/ai/agent/StepCollector.java \
        src/test/java/com/dawn/ai/agent/StepCollectorTest.java
git commit -m "feat: extend StepCollector with RETRIEVED_QUERIES for RAG dedup"

import com.dawn.ai.agent.StepCollector;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;

private SimpleMeterRegistry meterRegistry;

@BeforeEach
void setUp() {
    meterRegistry = new SimpleMeterRegistry();
    tool = new KnowledgeSearchTool(queryRewriter, ragService, meterRegistry);
    tool.setDefaultTopK(5);
    tool.initMetrics();
    StepCollector.init(10);
}

@AfterEach
void tearDown() {
    StepCollector.clear();
}

@Test
@DisplayName("apply: 相同改写查询第二次调用时跳过检索并返回提示")
void apply_duplicateQuery_skipsRetrieval() {
    when(queryRewriter.rewrite("月费")).thenReturn("Dawn AI 定价 月费");
    when(ragService.retrieve("Dawn AI 定价 月费", 5)).thenReturn(List.of(new Document("¥99")));

    // 第一次调用 — 正常检索
    tool.apply(new KnowledgeSearchTool.Request("月费"));

    // 第二次相同查询 — 应跳过
    KnowledgeSearchTool.Response secondResponse =
            tool.apply(new KnowledgeSearchTool.Request("月费"));

    assertThat(secondResponse.docsFound()).isEqualTo(0);
    assertThat(secondResponse.context()).contains("已检索过");
    // ragService.retrieve 只被调用了一次（第二次被 dedup 拦截）
    verify(ragService, times(1)).retrieve(anyString(), anyInt());
}

@Test
@DisplayName("apply: 重复查询时 ai.rag.dedup.skipped 计数器 +1")
void apply_duplicateQuery_incrementsDedupCounter() {
    when(queryRewriter.rewrite("test")).thenReturn("test rewritten");
    when(ragService.retrieve("test rewritten", 5)).thenReturn(List.of());

    tool.apply(new KnowledgeSearchTool.Request("test"));
    tool.apply(new KnowledgeSearchTool.Request("test")); // duplicate

    double skipped = meterRegistry.counter("ai.rag.dedup.skipped").count();
    assertThat(skipped).isEqualTo(1.0);
}

import static org.mockito.Mockito.times;
import static org.mockito.ArgumentMatchers.anyInt;
import static org.mockito.ArgumentMatchers.anyString;

./mvnw test -Dtest=KnowledgeSearchToolTest -q 2>&1 | grep -E "FAIL|ERROR" | head -5

package com.dawn.ai.agent.tools;

import com.dawn.ai.agent.StepCollector;
import com.dawn.ai.service.QueryRewriter;
import com.dawn.ai.service.RagService;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.document.Document;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Description;
import org.springframework.stereotype.Component;

import java.util.List;
import java.util.function.Function;

/**
 * Agent tool that searches the internal knowledge base.
 *
 * Placed in the tools package so ToolRegistry auto-discovers it.
 * ToolExecutionAspect intercepts apply() for step tracing and metrics automatically.
 *
 * Deduplication: uses StepCollector.isQueryRetrieved() to skip identical rewritten
 * queries within the same request, preventing wasted LLM + retrieval calls.
 */
@Slf4j
@Component
@Description("搜索内部知识库，获取与问题相关的背景信息。需要查询产品信息、技术文档或领域知识时调用。")
@RequiredArgsConstructor
public class KnowledgeSearchTool implements Function<KnowledgeSearchTool.Request, KnowledgeSearchTool.Response> {

    private final QueryRewriter queryRewriter;
    private final RagService ragService;
    private final MeterRegistry meterRegistry;

    @Setter
    @Value("${app.ai.rag.default-top-k:5}")
    private int defaultTopK;

    private Counter dedupCounter;

    /** package-private for test access */
    void initMetrics() {
        dedupCounter = Counter.builder("ai.rag.dedup.skipped")
                .description("RAG queries skipped due to deduplication within one request")
                .register(meterRegistry);
    }

    @PostConstruct
    void postConstruct() {
        initMetrics();
    }

    public record Request(@JsonProperty(required = true) String query) {}
    public record Response(String context, int docsFound) {}

    @Override
    public Response apply(Request req) {
        String rewrittenQuery = queryRewriter.rewrite(req.query());

        if (StepCollector.isQueryRetrieved(rewrittenQuery)) {
            dedupCounter.increment();
            log.info("[KnowledgeSearchTool] Skipping duplicate query: {}", rewrittenQuery);
            return new Response("（已检索过相同内容，请换个角度或直接生成回答）", 0);
        }
        StepCollector.markQueryRetrieved(rewrittenQuery);

        List<Document> docs = ragService.retrieve(rewrittenQuery, defaultTopK);

        log.info("[KnowledgeSearchTool] query='{}' → rewritten='{}', docsFound={}",
                req.query(), rewrittenQuery, docs.size());

        return new Response(formatContext(docs), docs.size());
    }

    private String formatContext(List<Document> docs) {
        if (docs.isEmpty()) return "未找到相关知识库内容。";
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < docs.size(); i++) {
            sb.append(String.format("[%d] %s\n", i + 1, docs.get(i).getText()));
        }
        return sb.toString();
    }
}

private SimpleMeterRegistry meterRegistry;

@BeforeEach
void setUp() {
    meterRegistry = new SimpleMeterRegistry();
    tool = new KnowledgeSearchTool(queryRewriter, ragService, meterRegistry);
    tool.setDefaultTopK(5);
    tool.initMetrics();
    StepCollector.init(10);
}

@AfterEach
void tearDown() {
    StepCollector.clear();
}

./mvnw test -Dtest=KnowledgeSearchToolTest -q 2>&1 | tail -10

[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

./mvnw test -q 2>&1 | tail -10

git add src/main/java/com/dawn/ai/agent/tools/KnowledgeSearchTool.java \
        src/test/java/com/dawn/ai/agent/tools/KnowledgeSearchToolTest.java
git commit -m "feat: add RAG dedup and ai.rag.dedup.skipped metric to KnowledgeSearchTool"

@Value("${app.ai.rag.max-calls-per-session:3}")
private int maxRagCalls;

private String buildPlanPrompt(String task,
                               Map<String, String> toolDescriptions,
                               String formatInstructions) {
    String toolList = toolDescriptions.entrySet().stream()
            .map(e -> "- " + e.getKey() + ": " + e.getValue())
            .collect(Collectors.joining("\n"));

    return """
            你是一个任务规划助手。请分析用户的任务，并生成一个 2-5 步的执行计划。

            可用工具：
            %s

            业务约束：
            - action 只能从上方可用工具中选择，最后一步固定为 "finish"
            - reason 使用中文，简短说明为什么要执行该步骤
            - 若单次检索信息不足，可多次调用 knowledgeSearchTool 从不同角度补充，
              直到信息充分再生成最终答案。每次请求最多检索 %d 次。

            用户任务：%s

            %s
            """.formatted(toolList, maxRagCalls, task, formatInstructions);
}

./mvnw test -q 2>&1 | tail -10

git add src/main/java/com/dawn/ai/agent/plan/TaskPlanner.java
git commit -m "feat: inject maxRagCalls guidance into TaskPlanner prompt for iterative retrieval"

private DistributionSummary ragCallsSummary;

import io.micrometer.core.instrument.DistributionSummary;

ragCallsSummary = DistributionSummary.builder("ai.rag.calls_per_session")
        .description("Number of knowledgeSearchTool calls per agent session")
        .register(meterRegistry);

long ragCalls = steps.stream()
        .filter(s -> "KnowledgeSearchTool".equals(s.toolName()))
        .count();
ragCallsSummary.record(ragCalls);

./mvnw test -q 2>&1 | tail -10

git add src/main/java/com/dawn/ai/agent/AgentOrchestrator.java
git commit -m "feat: add ai.rag.calls_per_session metric to AgentOrchestrator"

./mvnw test -q 2>&1 | tail -15

grep -n "isQueryRetrieved\|markQueryRetrieved\|RETRIEVED_QUERIES" \
  src/main/java/com/dawn/ai/agent/StepCollector.java

curl -s http://localhost:8080/actuator/prometheus | grep -E "ai_rag_dedup|ai_rag_calls"

ai_rag_dedup_skipped_total
ai_rag_calls_per_session_count
ai_rag_calls_per_session_sum

git log --oneline -8