From f54be0d90969a8f5acaea2eff199e397360d70eb Mon Sep 17 00:00:00 2001
From: Max <shadow.iqka@qq.com>
Date: Fri, 12 Dec 2025 10:12:22 +0800
Subject: [PATCH] Update DESIGN.md to refine reranking options and clarify
 configuration details

- Modified the reranking section to specify "builtin" as the default score-based reranking method, replacing previous terminology.
- Updated the RerankOptions structure to reflect changes in parameter names and types, including the transition from `topK` to `topN`.
- Enhanced documentation to clarify how reranker types are determined in the configuration file, improving overall understanding of the search module's reranking capabilities.
---
 agent/search/DESIGN.md | 34 +++++++++++-----------------------
 1 file changed, 11 insertions(+), 23 deletions(-)

diff --git a/agent/search/DESIGN.md b/agent/search/DESIGN.md
index f68bbbbb..7bf62480 100644
--- a/agent/search/DESIGN.md
+++ b/agent/search/DESIGN.md
@@ -18,7 +18,7 @@ The module follows the **Handler + Registry** pattern consistent with the `conte
 - **Citation System**: Auto-generate citation IDs (`#ref:xxx`) for LLM reference
 - **Real-time Output**: Stream search progress to client
 - **Trace Integration**: Report search operations to user for transparency
-- **Reranking**: Score, Model, Agent, or MCP-based result reranking
+- **Reranking**: Builtin, Agent, or MCP-based result reranking
 - **Graceful Degradation**: Search errors don't block agent flow
 
 ## Quick Start
@@ -133,8 +133,7 @@ agent/search/
 ├── citation.go            # Citation ID generation and tracking
 ├── rerank/                # Result reranking
 │   ├── interfaces.go      # Reranker interface
-│   ├── score.go           # Score-based reranking (default)
-│   ├── model.go           # Model-based reranking (Cohere, etc.)
+│   ├── builtin.go         # Built-in score-based reranking (default)
 │   ├── agent.go           # Agent-based reranking (delegate to another assistant)
 │   └── mcp.go             # MCP-based reranking (call MCP server tool)
 ├── query/                 # Query processing
@@ -225,18 +224,13 @@ const (
 )
 ```
 
-### RerankerType
+### Note on Reranker
 
-```go
-type RerankerType string
+Reranker type is determined by `uses.rerank` in `agent/agent.yml`:
 
-const (
-    RerankerTypeScore RerankerType = "score" // Simple score-based sorting (default)
-    RerankerTypeModel RerankerType = "model" // Model-based reranking (Cohere, BGE, etc.)
-    RerankerTypeAgent RerankerType = "agent" // Agent-based reranking (delegate to assistant)
-    RerankerTypeMCP   RerankerType = "mcp"   // MCP-based reranking (call MCP server tool)
-)
-```
+- `"builtin"` - Simple score-based sorting
+- `"<assistant-id>"` - Delegate to an assistant (Agent)
+- `"mcp:<server-id>"` - Call MCP server tool
 
 ### Request
 
@@ -284,12 +278,9 @@ type QueryOrder struct {
 
 ```go
 // RerankOptions controls result reranking
+// Reranker type is determined by uses.rerank in agent/agent.yml
 type RerankOptions struct {
-    Type  string `json:"type,omitempty"`  // "score", "model", "agent", "mcp"
-    Model string `json:"model,omitempty"` // Model ID (for type="model")
-    Agent string `json:"agent,omitempty"` // Agent ID (for type="agent")
-    MCP   string `json:"mcp,omitempty"`   // MCP server ID (for type="mcp")
-    TopK  int    `json:"top_k,omitempty"` // Return top K after reranking
+    TopN int `json:"top_n,omitempty"` // Return top N after reranking
 }
 ```
 
@@ -496,11 +487,8 @@ interface QueryOrder {
 }
 
 interface RerankOptions {
-  type?: string; // "score", "model", "agent", "mcp"
-  model?: string; // Model ID (for type="model")
-  agent?: string; // Agent ID (for type="agent")
-  mcp?: string; // MCP server ID (for type="mcp")
-  topK?: number; // Return top K
+  topN?: number; // Return top N after reranking
+  // Note: Reranker type is determined by uses.rerank in agent/agent.yml
 }
 ```