docs(rag): add comments on knowledge retrieval pipeline

Document the lookup_knowledge flow from L0 hints through L1 retrieval,
post-processing, packing, and Agent projection so the boundaries and
current limitations are easier to follow.

src/main/java/com/superbiz/agent/service/KnowledgeQueryTransformer.java

@@ -6,7 +6,17 @@ import org.springframework.stereotype.Service;
 import java.util.List;
 
 /**
- * Converts a raw Agent query into retrieval-control hints.
+ * 检索前的 query 理解层（L0 出口）。
+ *
+ * <p>输入是 Agent 的原始检索句，输出 {@link KnowledgeQuery}，供后续 L1 过滤与 rerank 使用。</p>
+ *
+ * <h3>当前能力边界</h3>
+ * <ul>
+ *   <li>会做：关键词匹配、domain/entity/title hint、唯一 domain 时生成 categoryFilter</li>
+ *   <li>不会做：真正的 query rewrite / 同义词扩展 / 多 query 改写
+ *       （{@code rewrittenQuery} 目前等于 {@code originalQuery}）</li>
+ *   <li>L0 命中文档正文不会直接当作 evidence；证据只来自 L1 向量召回</li>
+ * </ul>
  */
 @Service
 public class KnowledgeQueryTransformer {
@@ -17,15 +27,23 @@ public class KnowledgeQueryTransformer {
         this.knowledgeIndexService = knowledgeIndexService;
     }
 
+    /**
+     * 将原始 query 转为检索控制结构。
+     *
+     * <p>{@code categoryFilter} 仅在 L0 恰好命中一个 domain 时非空；
+     * 多 domain 或零 domain 时为 null，避免错误收窄召回。</p>
+     */
     public KnowledgeQuery transform(String rawQuery) {
         String normalized = rawQuery == null ? "" : rawQuery.trim();
         KnowledgeIndexService.L0Hint hint = knowledgeIndexService.analyzeQuery(normalized);
         return KnowledgeQuery.builder()
                 .originalQuery(normalized)
+                // 预留改写字段；当前未实现 rewrite，保持与 original 一致
                 .rewrittenQuery(normalized)
                 .domainHints(safeList(hint.domains()))
                 .matchedKeywords(safeList(hint.matchedKeywords()))
                 .entities(safeList(hint.entities()))
+                // 只有唯一 domain 才作为向量 metadata 的 category 过滤条件
                 .categoryFilter(hint.singleDomainOrNull())
                 .l0Titles(safeList(hint.titles()))
                 .l0MatchCount(hint.matches() == null ? 0 : hint.matches().size())