docs(api): clarify knowledge-search scope union of knowledge_base_ids and knowledge_ids (#4191)

website-docs/04-api/01-api-overview.md

@@ -239,7 +239,7 @@ X-Accel-Buffering: no
 | --- | --- | --- |
 | 给自己的 RAG / 智能体拿检索结果，排序和页面问答一致 | `knowledge-search` | `query` + `knowledge_base_ids`，其余不填 |
 | 同时搜多个知识库，且它们用的 embedding 模型不同 | `knowledge-search` | `knowledge_base_ids` |
-| 只在某几个文档或标签里搜 | `knowledge-search` | `knowledge_ids` / `tag_ids` |
+| 只在某几个文档或标签里搜 | `knowledge-search` | `knowledge_ids` / `tag_ids`；只搜指定文档时不要再传它们所在的 `knowledge_base_ids`，两者取并集 |
 | 调整返回条数或召回阈值，但仍然要 rerank | `knowledge-search` | `match_count`、`vector_threshold`、`keyword_threshold` |
 | 换一个 rerank 模型，或改 rerank 阈值 | `knowledge-search` | `rerank.model_id`、`rerank.threshold` |
 | 不要 rerank，直接拿召回结果 | `knowledge-search` 或 `hybrid-search` | 前者传 `"rerank":{"enabled":false}`；后者不传 `rerank` |

website-docs/04-api/02-api-chat.md

@@ -424,7 +424,7 @@ curl -N -X POST $BASE/api/v1/agent-chat/s-1 -H "Authorization: Bearer $TOKEN" \
 | `query` | string | 是（`binding:"required"`） | 查询 |
 | `knowledge_base_id` | string | 否 | 单 KB（兼容旧版） |
 | `knowledge_base_ids` | []string | 否 | 多 KB |
-| `knowledge_ids` | []string | 否 | 限定文件 |
+| `knowledge_ids` | []string | 否 | 指定文件，与 `knowledge_base_id(s)` 取并集（见下方说明） |
 | `tag_ids` | []string | 否 | 标签过滤 |
 | `mentioned_items` | []object | 否 | 带 KB 范围的标签提及 |
 | `vector_threshold` / `keyword_threshold` | float | 否 | 召回阈值；省略时用空间检索配置（默认 0.15 / 0.3） |
@@ -434,6 +434,8 @@ curl -N -X POST $BASE/api/v1/agent-chat/s-1 -H "Authorization: Bearer $TOKEN" \
 
 省略的字段都沿用空间的检索配置（`GET /tenants/kv/retrieval-config`），不传任何新字段时行为和以前一样。
 
+检索范围是 `knowledge_base_id(s)` 与 `knowledge_ids` 的并集，与产品内 @ 提及的语义一致：每个知识库整库检索，`knowledge_ids` 中属于这些知识库的文件已被覆盖，不再单独限定；属于其他知识库的文件会额外加入检索。**只想在指定文件里搜时，只传 `knowledge_ids`，不要同时传它们所在的知识库**，否则会检索整个知识库。
+
 响应：200 `{"success":true,"data":[SearchResult],"meta":{"rerank":{...}}}`。`SearchResult` 含 `id,content,knowledge_id,knowledge_title,score,chunk_type,knowledge_base_id,...`；经过 rerank 的结果 `metadata` 带 `model_score` 和 `base_score`。`data` 为空时看 `meta.rerank.outcome` 判断原因，见 [meta.rerank 诊断](./01-api-overview.md#retrieval-api)。
 
 ```bash
@@ -444,6 +446,10 @@ curl -X POST $BASE/api/v1/knowledge-search -H "X-API-Key: $API_KEY" \
 curl -X POST $BASE/api/v1/knowledge-search -H "X-API-Key: $API_KEY" \
   -H 'Content-Type: application/json' \
   -d '{"query":"部署要求","knowledge_base_ids":["kb-1"],"disable_keywords_match":true,"match_count":5,"rerank":{"enabled":false}}'
+
+# 只在指定文件里搜（不传 knowledge_base_ids）
+curl -X POST $BASE/api/v1/knowledge-search -H "X-API-Key: $API_KEY" \
+  -H 'Content-Type: application/json' -d '{"query":"部署要求","knowledge_ids":["k-1","k-2"]}'
 ```
 
 ## 消息（/api/v1/messages）