feat(api): honor resource_urls=public on hybrid-search

Single-KB retrieval was still returning resource:// handles even when
callers asked for public URLs, unlike knowledge-search.

Author: lyingbug

client/knowledgebase.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"net/url"
 	"time"
 )
 
@@ -407,10 +408,21 @@ type SearchParams struct {
 }
 
 // HybridSearch performs hybrid search.
-func (c *Client) HybridSearch(ctx context.Context, knowledgeBaseID string, params *SearchParams) ([]*SearchResult, error) {
+// Pass ResourceURLOptions to receive public HTTP(S) file URLs in results.
+func (c *Client) HybridSearch(
+	ctx context.Context,
+	knowledgeBaseID string,
+	params *SearchParams,
+	opts ...ResourceURLOptions,
+) ([]*SearchResult, error) {
 	path := fmt.Sprintf("/api/v1/knowledge-bases/%s/hybrid-search", knowledgeBaseID)
 
-	resp, err := c.doRequest(ctx, http.MethodPost, path, params, nil)
+	queryParams := url.Values{}
+	if len(opts) > 0 {
+		applyResourceURLQuery(queryParams, &opts[0])
+	}
+
+	resp, err := c.doRequest(ctx, http.MethodPost, path, params, queryParams)
 	if err != nil {
 		return nil, err
 	}

client/resource_urls.go

@@ -17,7 +17,7 @@ const (
 )
 
 // ResourceURLOptions carries the optional resource_urls query parameter shared
-// by chat, message-history, and knowledge-search endpoints.
+// by chat, message-history, knowledge-search, and hybrid-search endpoints.
 type ResourceURLOptions struct {
 	ResourceURLs ResourceURLMode
 }

docs/api/README.md

@@ -88,8 +88,9 @@ X-Request-ID: unique_request_id
 - `GET /api/v1/sessions/continue-stream/{session_id}`（SSE）
 - `GET /api/v1/messages/{session_id}/load`
 - `POST /api/v1/knowledge-search`
+- `POST /api/v1/knowledge-bases/{id}/hybrid-search`（兼容 GET）
 
-改写覆盖答案正文、`knowledge_references`（含 `image_info`）、Agent 执行步骤与工具结果，以及消息
+改写覆盖答案正文、检索结果 `content` / `image_info`、`knowledge_references`、Agent 执行步骤与工具结果，以及消息
 上的图片附件。流式回答里跨两个 chunk 被截断的引用会先缓冲再改写，客户端拿到的始终是完整链接。
 
 ### 注意事项

docs/api/chat.md

@@ -21,7 +21,7 @@
 |------|------|------|
 | `resource_urls` | `handle`（默认）/ `public` | `public` 让答案与引用里的图片直接返回可加载的 http(s) 链接，省去逐个调用 `/files` 代理。详见[文件与图片引用](./README.md#文件与图片引用resource-与直链) |
 
-同样适用于下面的 `/agent-chat/:session_id`、`/knowledge-search` 与 `/sessions/continue-stream/:session_id`。
+同样适用于下面的 `/agent-chat/:session_id`、`/knowledge-search`、`/knowledge-bases/:id/hybrid-search` 与 `/sessions/continue-stream/:session_id`。
 
 **请求参数**：
 

docs/api/knowledge-base.md

@@ -400,6 +400,10 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0
 | ---- | ------ | --------- |
 | id   | string | 知识库 ID |
 
+**查询参数**:
+
+- `resource_urls`: `handle`（默认）或 `public`。`public` 把检索结果 `content` / `image_info` 里的 `resource://` 引用换成可加载的 http(s) 链接，详见[文件与图片引用](./README.md#文件与图片引用resource-与直链)
+
 **参数说明（请求体）**:
 
 | 字段                     | 类型     | 必填 | 说明                                                             |
@@ -419,7 +423,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0
 **请求**:
 
 ```curl
-curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search' \
+curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search?resource_urls=public' \
 --header 'X-API-Key: sk-xxxxx' \
 --header 'Content-Type: application/json' \
 --data '{

docs/docs.go

@@ -4928,6 +4928,17 @@ const docTemplate = `{
                         "schema": {
                             "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams"
                         }
+                    },
+                    {
+                        "enum": [
+                            "handle",
+                            "public"
+                        ],
+                        "type": "string",
+                        "default": "handle",
+                        "description": "文件引用形式，public 返回可加载直链",
+                        "name": "resource_urls",
+                        "in": "query"
                     }
                 ],
                 "responses": {
@@ -4982,6 +4993,17 @@ const docTemplate = `{
                         "schema": {
                             "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams"
                         }
+                    },
+                    {
+                        "enum": [
+                            "handle",
+                            "public"
+                        ],
+                        "type": "string",
+                        "default": "handle",
+                        "description": "文件引用形式，public 返回可加载直链",
+                        "name": "resource_urls",
+                        "in": "query"
                     }
                 ],
                 "responses": {

docs/swagger.json

@@ -4921,6 +4921,17 @@
                         "schema": {
                             "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams"
                         }
+                    },
+                    {
+                        "enum": [
+                            "handle",
+                            "public"
+                        ],
+                        "type": "string",
+                        "default": "handle",
+                        "description": "文件引用形式，public 返回可加载直链",
+                        "name": "resource_urls",
+                        "in": "query"
                     }
                 ],
                 "responses": {
@@ -4975,6 +4986,17 @@
                         "schema": {
                             "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams"
                         }
+                    },
+                    {
+                        "enum": [
+                            "handle",
+                            "public"
+                        ],
+                        "type": "string",
+                        "default": "handle",
+                        "description": "文件引用形式，public 返回可加载直链",
+                        "name": "resource_urls",
+                        "in": "query"
                     }
                 ],
                 "responses": {

docs/swagger.yaml

@@ -9349,6 +9349,14 @@ paths:
         required: true
         schema:
           $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams'
+      - default: handle
+        description: 文件引用形式，public 返回可加载直链
+        enum:
+        - handle
+        - public
+        in: query
+        name: resource_urls
+        type: string
       produces:
       - application/json
       responses:
@@ -9383,6 +9391,14 @@ paths:
         required: true
         schema:
           $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams'
+      - default: handle
+        description: 文件引用形式，public 返回可加载直链
+        enum:
+        - handle
+        - public
+        in: query
+        name: resource_urls
+        type: string
       produces:
       - application/json
       responses:

internal/handler/knowledgebase.go

@@ -15,6 +15,7 @@ import (
 	"github.com/Tencent/WeKnora/internal/errors"
 	apperrors "github.com/Tencent/WeKnora/internal/errors"
 	"github.com/Tencent/WeKnora/internal/logger"
+	"github.com/Tencent/WeKnora/internal/storageurl"
 	"github.com/Tencent/WeKnora/internal/tracing/langfuse"
 	"github.com/Tencent/WeKnora/internal/types"
 	"github.com/Tencent/WeKnora/internal/types/interfaces"
@@ -35,6 +36,11 @@ type KnowledgeBaseHandler struct {
 	// userService 仅在 list 类接口里用于批量回填 creator_name；
 	// 真正的鉴权由 RBAC 中间件 + Lookup 完成，这里不参与决策。
 	userService interfaces.UserService
+	// fileService and storageResolver back the optional `resource_urls=public`
+	// mode on hybrid-search. Both may be nil in tests, in which case only the
+	// default handle mode is available.
+	fileService     interfaces.FileService
+	storageResolver interfaces.StorageBackendResolver
 }
 
 // NewKnowledgeBaseHandler creates a new knowledge base handler instance
@@ -46,6 +52,8 @@ func NewKnowledgeBaseHandler(
 	asynqClient interfaces.TaskEnqueuer,
 	vectorStoreService interfaces.VectorStoreService,
 	userService interfaces.UserService,
+	fileService interfaces.FileService,
+	storageResolver interfaces.StorageBackendResolver,
 ) *KnowledgeBaseHandler {
 	return &KnowledgeBaseHandler{
 		service:            service,
@@ -55,9 +63,27 @@ func NewKnowledgeBaseHandler(
 		asynqClient:        asynqClient,
 		vectorStoreService: vectorStoreService,
 		userService:        userService,
+		fileService:        fileService,
+		storageResolver:    storageResolver,
 	}
 }
 
+// resolveResourceRewriter builds the storage-reference rewriter for one response
+// from the request's `resource_urls` parameter, falling back to the deployment
+// default. The returned error is already an AppError the caller can hand to
+// c.Error: a rejected scope is a 403, a typo in the parameter is a 400.
+func (h *KnowledgeBaseHandler) resolveResourceRewriter(c *gin.Context) (*storageurl.Rewriter, error) {
+	ctx := c.Request.Context()
+	mode, err := storageurl.ResolveMode(ctx, c.Query(storageurl.QueryParam))
+	if err != nil {
+		if stderrors.Is(err, storageurl.ErrPublicModeForbidden) {
+			return nil, apperrors.NewForbiddenError(err.Error())
+		}
+		return nil, apperrors.NewBadRequestError(err.Error())
+	}
+	return storageurl.NewRequestRewriter(ctx, mode, h.fileService, h.storageResolver), nil
+}
+
 // buildKBResponse turns a knowledge base into a JSON-ready response shape,
 // merging the bound vector store's display metadata and any caller-supplied
 // extras (e.g., my_permission for shared KBs). Returns the kb pointer
@@ -275,10 +301,11 @@ func (h *KnowledgeBaseHandler) resolveKBStoreView(
 // @Tags         知识库
 // @Accept       json
 // @Produce      json
-// @Param        id       path      string             true  "知识库ID"
-// @Param        request  body      types.SearchParams true  "搜索参数"
-// @Success      200      {object}  map[string]interface{}  "搜索结果"
-// @Failure      400      {object}  errors.AppError         "请求参数错误"
+// @Param        id             path      string             true   "知识库ID"
+// @Param        request        body      types.SearchParams true   "搜索参数"
+// @Param        resource_urls  query     string  false  "文件引用形式，public 返回可加载直链"  Enums(handle, public)  default(handle)
+// @Success      200            {object}  map[string]interface{}  "搜索结果"
+// @Failure      400            {object}  errors.AppError         "请求参数错误"
 // @Security     Bearer
 // @Security     ApiKeyAuth
 // @Router       /knowledge-bases/{id}/hybrid-search [post]
@@ -311,6 +338,14 @@ func (h *KnowledgeBaseHandler) HybridSearch(c *gin.Context) {
 	logger.Infof(ctx, "Executing hybrid search, knowledge base ID: %s, query: %s, effectiveTenantID: %d",
 		secutils.SanitizeForLog(id), secutils.SanitizeForLog(req.QueryText), effectiveTenantID)
 
+	// Resolve before retrieving so a typo or a rejected scope costs nothing.
+	rewriter, err := h.resolveResourceRewriter(c)
+	if err != nil {
+		logger.Warnf(ctx, "Rejected resource URL mode: %v", err)
+		_ = c.Error(err)
+		return
+	}
+
 	// Execute hybrid search with default search parameters
 	// Note: For shared KBs, the service uses effectiveTenantID internally via context
 	results, err := h.service.HybridSearch(ctx, id, req)
@@ -333,7 +368,7 @@ func (h *KnowledgeBaseHandler) HybridSearch(c *gin.Context) {
 		secutils.SanitizeForLog(id), len(results))
 	c.JSON(http.StatusOK, gin.H{
 		"success": true,
-		"data":    results,
+		"data":    rewriter.CopyReferences(ctx, results),
 	})
 }
 

internal/handler/knowledgebase_hybrid_search_resource_urls_test.go

@@ -0,0 +1,108 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/Tencent/WeKnora/internal/middleware"
+	"github.com/Tencent/WeKnora/internal/types"
+	"github.com/Tencent/WeKnora/internal/types/interfaces"
+)
+
+func newHybridSearchResourceURLRouter(svc interfaces.KnowledgeBaseService, fileSvc interfaces.FileService) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.Use(middleware.ErrorHandler())
+	router.Use(func(c *gin.Context) {
+		c.Set(types.TenantIDContextKey.String(), uint64(1))
+		c.Set(types.UserIDContextKey.String(), "u-test")
+		c.Next()
+	})
+	h := &KnowledgeBaseHandler{service: svc, fileService: fileSvc}
+	router.POST("/knowledge-bases/:id/hybrid-search", h.HybridSearch)
+	router.GET("/knowledge-bases/:id/hybrid-search", h.HybridSearch)
+	return router
+}
+
+func performHybridSearchResourceURLRequest(
+	svc interfaces.KnowledgeBaseService,
+	fileSvc interfaces.FileService,
+	method, query, body string,
+) *httptest.ResponseRecorder {
+	response := httptest.NewRecorder()
+	request := httptest.NewRequest(
+		method,
+		"/knowledge-bases/kb-1/hybrid-search"+query,
+		bytes.NewBufferString(body),
+	)
+	request.Header.Set("Content-Type", "application/json")
+	newHybridSearchResourceURLRouter(svc, fileSvc).ServeHTTP(response, request)
+	return response
+}
+
+func TestHybridSearch_PublicResourceURLs(t *testing.T) {
+	svc := &hybridSearchTestService{
+		results: []*types.SearchResult{{
+			Content:   "chunk ![c](" + testResourceHandle + ")",
+			ImageInfo: `[{"url":"` + testResourceHandle + `"}]`,
+		}},
+	}
+	fileSvc := &stubResourceFileService{url: "https://cdn.example.com/signed.png"}
+
+	for _, method := range []string{http.MethodPost, http.MethodGet} {
+		t.Run(method, func(t *testing.T) {
+			response := performHybridSearchResourceURLRequest(
+				svc, fileSvc, method, "?resource_urls=public",
+				`{"query_text":"diagram"}`,
+			)
+
+			require.Equal(t, http.StatusOK, response.Code, "body=%s", response.Body.String())
+			assert.NotContains(t, response.Body.String(), testResourceHandle)
+			assert.Contains(t, response.Body.String(), "cdn.example.com")
+		})
+	}
+}
+
+func TestHybridSearch_InvalidResourceURLMode(t *testing.T) {
+	svc := &hybridSearchTestService{}
+	response := performHybridSearchResourceURLRequest(
+		svc, &stubResourceFileService{url: "https://cdn.example.com/signed.png"},
+		http.MethodPost, "?resource_urls=signed",
+		`{"query_text":"diagram"}`,
+	)
+
+	require.Equal(t, http.StatusBadRequest, response.Code, "body=%s", response.Body.String())
+	assert.Contains(t, response.Body.String(), "resource_urls")
+	assert.Equal(t, 0, svc.searchCalls, "invalid mode must not reach HybridSearch")
+}
+
+func TestHybridSearch_DefaultKeepsHandles(t *testing.T) {
+	svc := &hybridSearchTestService{
+		results: []*types.SearchResult{{
+			Content: "chunk ![c](" + testResourceHandle + ")",
+		}},
+	}
+	response := performHybridSearchResourceURLRequest(
+		svc, &stubResourceFileService{url: "https://cdn.example.com/signed.png"},
+		http.MethodPost, "",
+		`{"query_text":"diagram"}`,
+	)
+
+	require.Equal(t, http.StatusOK, response.Code, "body=%s", response.Body.String())
+
+	var resp struct {
+		Data []struct {
+			Content string `json:"content"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(response.Body.Bytes(), &resp))
+	require.Len(t, resp.Data, 1)
+	assert.Contains(t, resp.Data[0].Content, testResourceHandle)
+}