refactor(terminology): rename user-facing tenant labels to workspace

Align product copy, API docs, Swagger descriptions, and i18n strings
with workspace terminology while keeping internal tenant identifiers
and headers unchanged for API compatibility.
This commit is contained in:
wizardchen
2026-07-14 16:13:49 +08:00
committed by lyingbug
parent e1572b71b9
commit 41975abcc5
161 changed files with 1865 additions and 1770 deletions
+1 -1
View File
@@ -69,7 +69,7 @@ WeKnora API 按功能分为以下几类:
| 分类 | 描述 | 文档链接 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理;OIDC 流程 | [auth.md](./auth.md) · [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
| 租户管理 | 创建和管理租户账户 | [tenant.md](./tenant.md) |
| 空间管理 | 创建和管理空间账户 | [tenant.md](./tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](./knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](./knowledge.md) |
| 模型管理 | 配置和管理各种AI模型 | [model.md](./model.md) |
+4 -4
View File
@@ -111,7 +111,7 @@ curl --location 'http://localhost:8080/api/v1/agents' \
## GET `/agents` - 获取智能体列表
获取当前租户的所有智能体,包括内置智能体和自定义智能体。响应中额外返回 `disabled_own_agent_ids`,指示当前租户在前端对话下拉框中主动隐藏的本租户自有智能体 ID 列表(不影响其他租户)。
获取当前空间的所有智能体,包括内置智能体和自定义智能体。响应中额外返回 `disabled_own_agent_ids`,指示当前空间在前端对话下拉框中主动隐藏的本空间自有智能体 ID 列表(不影响其他空间)。
**请求**:
@@ -164,7 +164,7 @@ curl --location 'http://localhost:8080/api/v1/agents' \
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | ------------------ |
| 401 | 1001 | Unauthorized | 缺少租户上下文 |
| 401 | 1001 | Unauthorized | 缺少空间上下文 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
@@ -470,7 +470,7 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \
|------|------|--------|------|
| `web_search_enabled` | bool | true | 是否启用网络搜索 |
| `web_search_max_results` | int | 5 | 网络搜索最大结果数 |
| `web_search_provider_id` | string | - | 网络搜索提供者 ID,为空使用租户默认提供者 |
| `web_search_provider_id` | string | - | 网络搜索提供者 ID,为空使用空间默认提供者 |
| `web_fetch_enabled` | bool | false | 是否自动获取重排后的搜索结果页面全文 |
| `web_fetch_top_n` | int | 3 | 重排后获取全文的最大页面数 |
@@ -548,6 +548,6 @@ curl --location 'http://localhost:8080/api/v1/agent-chat/session-123' \
## 相关文档
- 智能体的组织共享、跨租户分发与禁用(`/agents/:id/shares`、`/shared-agents` 等):见 [组织管理 API](./organization.md)
- 智能体的组织共享、跨空间分发与禁用(`/agents/:id/shares`、`/shared-agents` 等):见 [组织管理 API](./organization.md)
- 智能体绑定 IM 渠道(`/agents/:id/im-channels`):见组织/IM 渠道相关文档
- 网络搜索提供者配置(被 `web_search_provider_id` 引用):见 [Web Search API](./web-search.md)
+1 -1
View File
@@ -84,7 +84,7 @@ Agent 模式支持更智能的问答,包括工具调用、网络搜索、多
## 回答后推荐问题
回答主消息完成后,服务端会异步生成推荐问题,不阻塞 SSE 的 `complete`/`done` 事件。生成结果按“租户、助手消息、位置、配置快照、语言”持久化并去重。
回答主消息完成后,服务端会异步生成推荐问题,不阻塞 SSE 的 `complete`/`done` 事件。生成结果按“空间、助手消息、位置、配置快照、语言”持久化并去重。
```http
POST /api/v1/sessions/{session_id}/messages/{message_id}/suggestions
+16 -16
View File
@@ -6,9 +6,9 @@
- 知识库类型 `type` 为 `document`(文档)或 `faq`(FAQ),默认 `document`。
- JSON 中对象存储相关字段:**`storage_config`** 为序列化字段名(对应数据库列 `cos_config`,兼容旧数据)。旧客户端若仍发送或接收 `cos_config`,服务端会兼容解析;新集成请使用 **`storage_config`**。
- **`storage_provider_config`** 为新版存储提供者选择(如 `{"provider": "local"}`),与租户级存储引擎凭证配合使用;无配置时可为 `null`。
- **`storage_provider_config`** 为新版存储提供者选择(如 `{"provider": "local"}`),与空间级存储引擎凭证配合使用;无配置时可为 `null`。
- 嵌套配置对象:`chunking_config`、`image_processing_config`、`vlm_config`、`asr_config`、`extract_config`、`faq_config`、`question_generation_config`。其中 `extract_config`、`faq_config`、`question_generation_config` 允许为 `null`。
- **`vector_store_id`** 为知识库绑定的向量存储 ID(参见 [vector-store.md](./vector-store.md))。未指定(或 `null`/`""`)时使用租户级默认的环境变量存储;一旦创建即不可修改。详情接口返回时会附带 `vector_store_name` / `vector_store_source` / `vector_store_engine_type` / `vector_store_status` 四个只读元数据字段,用于前端展示。
- **`vector_store_id`** 为知识库绑定的向量存储 ID(参见 [vector-store.md](./vector-store.md))。未指定(或 `null`/`""`)时使用空间级默认的环境变量存储;一旦创建即不可修改。详情接口返回时会附带 `vector_store_name` / `vector_store_source` / `vector_store_engine_type` / `vector_store_status` 四个只读元数据字段,用于前端展示。
| 方法 | 路径 | 描述 |
| ------ | ----------------------------------------- | ------------------------ |
@@ -46,7 +46,7 @@
| extract_config | object | 否 | 图谱抽取配置;`enabled=true` 时需提供 `text`/`tags`/`nodes`/`relations` |
| faq_config | object | 否 | FAQ 配置(仅 FAQ 类型知识库需要) |
| question_generation_config | object | 否 | 问题生成配置 |
| vector_store_id | string | 否 | 绑定的向量存储 ID。不传或为空字符串等同于 `null`(使用环境变量默认存储)。指定时必须是调用者所在租户拥有的向量存储 UUID;创建后不可修改。无效 UUID / 跨租户 / 未注册到引擎的 ID 会返回 `400` |
| vector_store_id | string | 否 | 绑定的向量存储 ID。不传或为空字符串等同于 `null`(使用环境变量默认存储)。指定时必须是调用者所在空间拥有的向量存储 UUID;创建后不可修改。无效 UUID / 跨空间 / 未注册到引擎的 ID 会返回 `400` |
**请求**:
@@ -193,8 +193,8 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \
| 字段 | 类型 | 说明 |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `vector_store_id` | string | 绑定的向量存储 ID(创建时未指定时为 `null`,从响应中省略) |
| `vector_store_name` | string | 绑定存储的展示名。未绑定时返回 `"System default"`;跨租户共享 KB 视图中被隐藏 |
| `vector_store_source` | string | `"user"`(DB 中创建的存储)/ `"env"`(环境变量虚拟存储)/ `"shared"`(跨租户共享 KB)/ `"unavailable"`(绑定的存储已不可解析) |
| `vector_store_name` | string | 绑定存储的展示名。未绑定时返回 `"System default"`;跨空间共享 KB 视图中被隐藏 |
| `vector_store_source` | string | `"user"`(DB 中创建的存储)/ `"env"`(环境变量虚拟存储)/ `"shared"`(跨空间共享 KB)/ `"unavailable"`(绑定的存储已不可解析) |
| `vector_store_engine_type` | string | 引擎类型(`elasticsearch` / `qdrant` / `milvus` 等)。`shared` / `unavailable` 时为空 |
| `vector_store_status` | string | `"available"` / `"unavailable"`。`unavailable` 表示绑定的存储已被删除或不在内存注册表中,UI 可据此提示用户重新绑定 |
@@ -202,12 +202,12 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \
| HTTP | code | 说明 |
| ---- | ---- | ----------------------------------------------------------------- |
| 400 | 2200 | `vector_store_id` 无效:格式错误、不存在或属于其他租户(统一返回,避免枚举泄漏) |
| 400 | 2200 | `vector_store_id` 无效:格式错误、不存在或属于其他空间(统一返回,避免枚举泄漏) |
| 400 | 2201 | 指定的向量存储当前不可用:存在于数据库但未注册到引擎注册表,请检查 connection_config |
## GET `/knowledge-bases` - 获取知识库列表
返回当前租户拥有的全部知识库。当传入 `agent_id` 时,校验调用者对该共享智能体的访问权限后,返回该智能体配置可见的知识库范围(用于 `@` 提及)。
返回当前空间拥有的全部知识库。当传入 `agent_id` 时,校验调用者对该共享智能体的访问权限后,返回该智能体配置可见的知识库范围(用于 `@` 提及)。
**Query 参数**:
@@ -251,7 +251,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: 字段结构同 `POST /knowledge-bases` 响应(包含 Phase 2 的 `vector_store_*` 元数据字段),并附 `is_pinned` / `pinned_at` / `knowledge_count` / `chunk_count` / `processing_count` 状态字段。通过共享智能体访问时还会附加 `my_permission`;同时 `vector_store_name` / `vector_store_engine_type` 会被隐藏(`vector_store_source` 返回 `"shared"`),避免跨租户泄漏存储展示名。
**响应**: 字段结构同 `POST /knowledge-bases` 响应(包含 Phase 2 的 `vector_store_*` 元数据字段),并附 `is_pinned` / `pinned_at` / `knowledge_count` / `chunk_count` / `processing_count` 状态字段。通过共享智能体访问时还会附加 `my_permission`;同时 `vector_store_name` / `vector_store_engine_type` 会被隐藏(`vector_store_source` 返回 `"shared"`),避免跨空间泄漏存储展示名。
## PUT `/knowledge-bases/:id` - 更新知识库
@@ -315,7 +315,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b582
## DELETE `/knowledge-bases/:id` - 删除知识库
仅知识库 owner(与 owning tenant 匹配的 admin)可调用,删除将级联清理知识库下所有知识与切片。
仅知识库 owner(与所属空间匹配的 admin)可调用,删除将级联清理知识库下所有知识与切片。
**路径参数**:
@@ -431,7 +431,7 @@ curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-
异步拷贝整个知识库(配置 + 全部知识内容)。请求会被入队到 Asynq 后台任务(队列 `default`,最多重试 3 次),并立即返回 `task_id` 供轮询进度。
**约束**:源知识库 `source_id` 必须属于调用者所在租户;若指定 `target_id`,目标知识库同样必须属于调用者租户,否则返回 `403 Forbidden`。
**约束**:源知识库 `source_id` 必须属于调用者所在空间;若指定 `target_id`,目标知识库同样必须属于调用者空间,否则返回 `403 Forbidden`。
**Phase 2 同步预检(当 `target_id` 非空时)**:
@@ -446,9 +446,9 @@ curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | ------------------------------------------------------------- |
| source_id | string | 是 | 源知识库 ID(必须属于当前租户) |
| target_id | string | 否 | 目标知识库 ID(若复用已存在知识库;同样必须属于当前租户) |
| task_id | string | 否 | 自定义任务 ID;不传则由服务端生成(基于租户、源 ID、时间戳) |
| source_id | string | 是 | 源知识库 ID(必须属于当前空间) |
| target_id | string | 否 | 目标知识库 ID(若复用已存在知识库;同样必须属于当前空间) |
| task_id | string | 否 | 自定义任务 ID;不传则由服务端生成(基于空间、源 ID、时间戳) |
**请求**:
@@ -542,7 +542,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/copy/progress/kb_c
| 复制内容 | 仅设置 | 设置 + 全部知识内容 |
| 新 KB ID | 服务端自动生成 UUID | 可指定已有目标库或新建 |
**权限**:需要 `Contributor+`,且对源知识库至少有 `Viewer` 读权限(路由层 `KBAccessRead`)。源知识库必须属于调用者所在租户,否则返回 `403 Forbidden`。
**权限**:需要 `Contributor+`,且对源知识库至少有 `Viewer` 读权限(路由层 `KBAccessRead`)。源知识库必须属于调用者所在空间,否则返回 `403 Forbidden`。
**命名规则**:新 KB 名称在源名称后追加本地化后缀(依据 `Accept-Language` 或 `WEKNORA_LANGUAGE`),例如中文 `原名 副本`、英文 `Original Name Copy`;若同名已存在则递增为 `原名 副本 2`、`Original Name Copy 2` 等。
@@ -598,7 +598,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/duplic
| 场景 | HTTP | 说明 |
| -------------------- | ---- | ---- |
| 源知识库不存在 | 404 | `Source knowledge base not found` |
| 源库属于其他租户 | 403 | `No permission to duplicate this knowledge base` |
| 源库属于其他空间 | 403 | `No permission to duplicate this knowledge base` |
| 向量存储绑定无效 | 400 | 源库绑定的 vector store 不可用 |
## GET `/knowledge-bases/:id/move-targets` - 获取可迁移目标知识库列表
@@ -609,7 +609,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/duplic
- 与源知识库 `embedding_model_id` 相同
- 非临时知识库(`is_temporary = false`)
- 不包含源知识库自身
- 仅同租户的知识库
- 仅同空间的知识库
**路径参数**:
+6 -6
View File
@@ -29,7 +29,7 @@
> **公共说明**:
> - 路径中的 `:id`(知识库路径下)为**知识库 ID**,`/knowledge/:id` 中的 `:id` 为**知识 ID**。
> - 所有写操作(创建、更新、删除、迁移、重新解析、取消解析)需要当前用户在知识库所属组织内具有 `editor` 或 `admin` 权限;清空知识库内容仅 KB **所有者**(admin 且租户匹配)可操作。
> - 所有写操作(创建、更新、删除、迁移、重新解析、取消解析)需要当前用户在知识库所属组织内具有 `editor` 或 `admin` 权限;清空知识库内容仅 KB **所有者**(admin 且空间匹配)可操作。
> - 关键状态字段:`parse_status` 取值 `pending` / `processing` / `finalizing` / `completed` / `failed` / `cancelled`;`enable_status` 取值 `enabled` / `disabled`。
> - `processing` 指 DocReader / 分块 / 向量化阶段;`finalizing` 指主解析已完成、仍在执行摘要 / 问题生成 / 图谱抽取等索引优化任务;只有当全部子任务到达终态后才进入 `completed`。
> - `cancelled` 表示解析被用户主动取消,可通过 `reparse` 重新触发。`pending` / `processing` / `finalizing` 这三种状态都可通过 `cancel-parse` 终止。
@@ -325,7 +325,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowle
## DELETE `/knowledge-bases/:id/knowledge` - 清空知识库下的所有知识
异步提交"清空任务",删除该知识库下的全部知识条目;知识库本身保留。**仅 KB 所有者(admin 且租户匹配)可操作**。
异步提交"清空任务",删除该知识库下的全部知识条目;知识库本身保留。**仅 KB 所有者(admin 且空间匹配)可操作**。
**请求**:
@@ -363,8 +363,8 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/k
| 字段 | 类型 | 必填 | 说明 |
| ----------- | -------- | ---- | --------------------------------------------------------------------- |
| `ids` | string[] | 是 | 知识 ID,重复 `ids=...` 传多个 |
| `kb_id` | string | 否 | 限定知识库范围;共享知识库场景下用于按 KB 校验权限并解析有效租户 |
| `agent_id` | string | 否 | 共享 Agent ID;按 Agent 所属租户拉取,常用于共享场景刷新后的文件回填 |
| `kb_id` | string | 否 | 限定知识库范围;共享知识库场景下用于按 KB 校验权限并解析有效空间 |
| `agent_id` | string | 否 | 共享 Agent ID;按 Agent 所属空间拉取,常用于共享场景刷新后的文件回填 |
**请求**:
@@ -729,7 +729,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge/tags' \
## GET `/knowledge/search` - 跨知识库搜索/过滤知识
按关键词在当前租户(含已共享给当前租户)的知识中检索;可按文件类型过滤;指定 `agent_id` 时按共享 Agent 所配置的知识库范围检索。
按关键词在当前空间(含已共享给当前空间)的知识中检索;可按文件类型过滤;指定 `agent_id` 时按共享 Agent 所配置的知识库范围检索。
**查询参数**:
@@ -827,7 +827,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge/batch-delete' \
将一条或多条**处于 `completed` 状态**的知识从源 KB 迁到目标 KB(异步)。约束:
- 源/目标 KB 必须属于当前租户;
- 源/目标 KB 必须属于当前空间;
- 源/目标必须为同一 KB 类型且**使用相同的 Embedding 模型**;
- 源 KB ≠ 目标 KB;
- 仅 `parse_status=completed` 的知识可迁移。
+4 -4
View File
@@ -7,7 +7,7 @@ MCP(Model Context Protocol)服务管理接口,提供 MCP 服务的 CRUD、
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------------------- | --------------------------------------------- |
| POST | `/mcp-services` | 创建 MCP 服务 |
| GET | `/mcp-services` | 获取当前租户的 MCP 服务列表 |
| GET | `/mcp-services` | 获取当前空间的 MCP 服务列表 |
| GET | `/mcp-services/:id` | 获取 MCP 服务详情 |
| PUT | `/mcp-services/:id` | 更新 MCP 服务(部分字段更新) |
| DELETE | `/mcp-services/:id` | 删除 MCP 服务 |
@@ -113,7 +113,7 @@ curl --location 'http://localhost:8080/api/v1/mcp-services' \
## GET `/mcp-services` - 获取 MCP 服务列表
返回当前租户已配置的所有 MCP 服务。
返回当前空间已配置的所有 MCP 服务。
**请求**:
@@ -497,7 +497,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/mcp-services/mcp-000
用于 Agent 在执行过程中阻塞等待人工审批的场景:当 Agent 命中一个 `require_approval = true` 的工具时会生成一条 `pending_id`,前端拿到这个 ID 后调用此接口将审批结果回传给 Agent,Agent 才会继续执行(或终止)。
**鉴权要求**:请求上下文中必须有已认证用户(`user_id`),且该用户必须是当前 pending 会话的所有者;租户与用户两层都会做 fail-close 校验。
**鉴权要求**:请求上下文中必须有已认证用户(`user_id`),且该用户必须是当前 pending 会话的所有者;空间与用户两层都会做 fail-close 校验。
**路径参数**:
@@ -552,6 +552,6 @@ curl --location --request POST 'http://localhost:8080/api/v1/agent/tool-approval
| HTTP | 触发条件 |
| ---- | --------------------------------------------------------------------------------------- |
| 400 | `decision` 不是 `approve`/`reject`;或 `modified_args` 是 `null`/非对象;或租户/用户错配 |
| 400 | `decision` 不是 `approve`/`reject`;或 `modified_args` 是 `null`/非对象;或空间/用户错配 |
| 401 | 上下文缺失认证用户(中间件未注入 `user_id`) |
| 404 | `pending_id` 不存在或已完成(超时/取消已先一步消费) |
+1 -1
View File
@@ -239,7 +239,7 @@ curl --location 'http://localhost:8080/api/v1/messages/search' \
## GET `/messages/chat-history-stats` - 获取聊天历史知识库统计
获取当前租户的聊天历史知识库索引统计信息。
获取当前空间的聊天历史知识库索引统计信息。
**请求**:
+4 -4
View File
@@ -2,7 +2,7 @@
[返回目录](./README.md)
模型管理接口用于维护当前租户下可用的 LLM / Embedding / Rerank / VLLM / ASR 模型配置。
模型管理接口用于维护当前空间下可用的 LLM / Embedding / Rerank / VLLM / ASR 模型配置。
| 方法 | 路径 | 描述 |
| ------ | ------------------- | --------------------- |
@@ -46,7 +46,7 @@ WeKnora 支持多种主流 AI 模型服务商,在创建模型时可通过 `par
## GET `/models/providers` - 获取模型服务商列表
根据模型类型获取支持的服务商列表及配置信息(系统级元数据,与租户无关)。
根据模型类型获取支持的服务商列表及配置信息(系统级元数据,与空间无关)。
**查询参数**:
@@ -100,7 +100,7 @@ curl --location 'http://localhost:8080/api/v1/models/providers?model_type=embedd
## POST `/models` - 创建模型
为当前租户创建一个新的模型配置。
为当前空间创建一个新的模型配置。
**参数说明(请求体)**:
@@ -314,7 +314,7 @@ curl --location 'http://localhost:8080/api/v1/models' \
## GET `/models` - 获取模型列表
返回当前租户下的所有模型。内置模型(`is_builtin = true`)的 `base_url` 与 `api_key` 会被清空以隐藏敏感信息。
返回当前空间下的所有模型。内置模型(`is_builtin = true`)的 `base_url` 与 `api_key` 会被清空以隐藏敏感信息。
**请求**:
+2 -2
View File
@@ -2,7 +2,7 @@
[返回目录](./README.md)
组织(Organization,又称"空间")是 WeKnora 的多租户协作单元。一个用户可以创建/加入多个组织,并以 owner / admin / editor / viewer 的角色参与;知识库与智能体可以共享到组织内,组织成员根据角色获得相应的访问权限。
组织(Organization,又称"空间")是 WeKnora 的多空间协作单元。一个用户可以创建/加入多个组织,并以 owner / admin / editor / viewer 的角色参与;知识库与智能体可以共享到组织内,组织成员根据角色获得相应的访问权限。
本页文档覆盖以下六类接口:
@@ -1183,7 +1183,7 @@ curl --location 'http://localhost:8080/api/v1/shared-knowledge-bases' \
### GET `/shared-agents` - 获取共享给我的智能体(跨组织)
返回当前用户通过所有组织共享获得的智能体列表,供"全部智能体"视图使用。`disabled_by_me: true` 表示当前租户已在对话下拉中隐藏该智能体。
返回当前用户通过所有组织共享获得的智能体列表,供"全部智能体"视图使用。`disabled_by_me: true` 表示当前空间已在对话下拉中隐藏该智能体。
**请求**:
+6 -6
View File
@@ -9,7 +9,7 @@
| POST | `/sessions` | 创建会话 |
| DELETE | `/sessions/batch` | 批量删除会话 |
| GET | `/sessions/:id` | 获取会话详情 |
| GET | `/sessions` | 获取当前租户的会话列表 |
| GET | `/sessions` | 获取当前空间的会话列表 |
| PUT | `/sessions/:id` | 更新会话 |
| DELETE | `/sessions/:id` | 删除会话 |
| DELETE | `/sessions/:id/messages` | 清空会话消息 |
@@ -61,11 +61,11 @@ curl --location 'http://localhost:8080/api/v1/sessions' \
}
```
> 通过 API-Key 调用时 `user_id` 可能为空,此时会话以租户级可见。
> 通过 API-Key 调用时 `user_id` 可能为空,此时会话以空间级可见。
## DELETE `/sessions/batch` - 批量删除会话
支持两种模式:按 ID 列表批量删除,或删除当前租户的所有会话。
支持两种模式:按 ID 列表批量删除,或删除当前空间的所有会话。
**请求 - 按 ID 列表删除**:
@@ -97,7 +97,7 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/batch' \
| 字段 | 类型 | 必填 | 描述 |
| ------------ | -------- | ---- | ---------------------------------------------------------- |
| `ids` | string[] | 否 | 要删除的会话 ID 列表(`delete_all` 为 `false` 时必填) |
| `delete_all` | bool | 否 | 设为 `true` 时删除当前租户的所有会话,忽略 `ids` 字段 |
| `delete_all` | bool | 否 | 设为 `true` 时删除当前空间的所有会话,忽略 `ids` 字段 |
**响应**:
@@ -148,9 +148,9 @@ curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-f
会话不存在时返回 `404`。
## GET `/sessions` - 获取当前租户的会话列表
## GET `/sessions` - 获取当前空间的会话列表
获取当前租户的会话列表,支持分页、关键字搜索、按来源 / Agent 过滤。
获取当前空间的会话列表,支持分页、关键字搜索、按来源 / Agent 过滤。
**请求**:
+60 -60
View File
@@ -1,32 +1,32 @@
# 租户管理 API
# 空间管理 API
[返回目录](./README.md)
包含两组接口:
- 租户 CRUD(`/tenants`、`/tenants/:id`):当前认证用户对自己所属租户进行管理;跨租户访问需要管理员权限。
- 跨租户接口(`/tenants/all`、`/tenants/search`):**需要服务端启用 `EnableCrossTenantAccess` 且当前用户具备 `CanAccessAllTenants` 权限**,否则返回 403。
- 租户 KV 配置(`/tenants/kv/:key`):当前租户级别的通用配置项,**`tenant_id` 从认证上下文中获取,不在 URL 中传入**。
- 空间 CRUD(`/tenants`、`/tenants/:id`):当前认证用户对自己所属空间进行管理;跨空间访问需要管理员权限。
- 跨空间接口(`/tenants/all`、`/tenants/search`):**需要服务端启用 `EnableCrossTenantAccess` 且当前用户具备 `CanAccessAllTenants` 权限**,否则返回 403。
- 空间 KV 配置(`/tenants/kv/:key`):当前空间级别的通用配置项,**`tenant_id` 从认证上下文中获取,不在 URL 中传入**。
| 方法 | 路径 | 描述 |
| ------ | -------------------------- | ------------------------------------------------- |
| GET | `/tenants/all` | 获取所有租户列表(需跨租户权限) |
| GET | `/tenants/search` | 分页搜索租户(需跨租户权限) |
| POST | `/tenants` | 创建新租户 |
| GET | `/tenants/:id` | 获取指定租户信息 |
| PUT | `/tenants/:id` | 更新租户信息 |
| DELETE | `/tenants/:id` | 删除租户 |
| GET | `/tenants/:id/api-keys` | 列出租户 API Key(Owner) |
| GET | `/tenants/all` | 获取所有空间列表(需跨空间权限) |
| GET | `/tenants/search` | 分页搜索空间(需跨空间权限) |
| POST | `/tenants` | 创建新空间 |
| GET | `/tenants/:id` | 获取指定空间信息 |
| PUT | `/tenants/:id` | 更新空间信息 |
| DELETE | `/tenants/:id` | 删除空间 |
| GET | `/tenants/:id/api-keys` | 列出空间 API Key(Owner) |
| POST | `/tenants/:id/api-keys` | 创建带角色的 API Key(Owner) |
| DELETE | `/tenants/:id/api-keys/:key_id` | 吊销指定 API Key(Owner) |
| GET | `/tenants/:id/api-principal-config` | 获取 API Key 用户身份配置(Owner) |
| PUT | `/tenants/:id/api-principal-config` | 更新 API Key 用户身份配置(Owner) |
| GET | `/tenants` | 获取当前用户可见的租户列表 |
| GET | `/tenants/kv/:key` | 获取当前租户的 KV 配置(tenant 由认证上下文确定) |
| PUT | `/tenants/kv/:key` | 更新当前租户的 KV 配置(tenant 由认证上下文确定) |
| GET | `/tenants` | 获取当前用户可见的空间列表 |
| GET | `/tenants/kv/:key` | 获取当前空间的 KV 配置(空间由认证上下文确定) |
| PUT | `/tenants/kv/:key` | 更新当前空间的 KV 配置(空间由认证上下文确定) |
## GET `/tenants/all` - 获取所有租户列表
## GET `/tenants/all` - 获取所有空间列表
获取系统中所有租户列表,需要跨租户权限。
获取系统中所有空间列表,需要跨空间权限。
**请求**:
@@ -45,7 +45,7 @@ curl --location 'http://localhost:8080/api/v1/tenants/all' \
{
"id": 10001,
"name": "weknora-1",
"description": "weknora tenants 1",
"description": "weknora workspaces 1",
"status": "active",
"business": "wechat",
"created_at": "2025-08-11T20:37:28.39698+08:00",
@@ -54,7 +54,7 @@ curl --location 'http://localhost:8080/api/v1/tenants/all' \
{
"id": 10002,
"name": "weknora-2",
"description": "weknora tenants 2",
"description": "weknora workspaces 2",
"status": "active",
"business": "wechat",
"created_at": "2025-08-11T20:52:58.05679+08:00",
@@ -66,13 +66,13 @@ curl --location 'http://localhost:8080/api/v1/tenants/all' \
}
```
## GET `/tenants/search` - 搜索租户
## GET `/tenants/search` - 搜索空间
按关键词搜索租户,需要跨租户权限。
按关键词搜索空间,需要跨空间权限。
**查询参数**:
- `keyword`: 搜索关键词(可选)
- `tenant_id`: 按租户ID筛选(可选)
- `tenant_id`: 按空间ID筛选(可选)
- `page`: 页码(默认 1)
- `page_size`: 每页条数(默认 20)
@@ -93,7 +93,7 @@ curl --location 'http://localhost:8080/api/v1/tenants/search?keyword=weknora&pag
{
"id": 10002,
"name": "weknora",
"description": "weknora tenants",
"description": "weknora workspaces",
"status": "active",
"business": "wechat",
"created_at": "2025-08-11T20:52:58.05679+08:00",
@@ -108,18 +108,18 @@ curl --location 'http://localhost:8080/api/v1/tenants/search?keyword=weknora&pag
}
```
## POST `/tenants` - 创建新租户
## POST `/tenants` - 创建新空间
创建一个新的租户。**默认不会**自动发放 API Key;请在创建后通过 `POST /tenants/:id/api-keys` 创建密钥。从旧版本升级时,原有 `tenants.api_key` 会迁移到 `tenant_api_keys` 表并继续可用,直至被吊销。
创建一个新的空间。**默认不会**自动发放 API Key;请在创建后通过 `POST /tenants/:id/api-keys` 创建密钥。从旧版本升级时,原有 `tenants.api_key` 会迁移到 `tenant_api_keys` 表并继续可用,直至被吊销。
> **兼容旧行为(可选)**:如需恢复旧版「创建租户即下发默认 API Key」的行为,可将系统设置 `tenant.auto_create_api_key` 置为 `true`(或设置环境变量 `WEKNORA_TENANT_AUTO_CREATE_API_KEY=true`)。开启后,创建租户会自动生成一个 `full_access` 权限的 API Key,并在响应体 `data.api_key` 中返回其明文 token(仅本次创建响应返回,请妥善保存)。默认 `false`。
> **兼容旧行为(可选)**:如需恢复旧版「创建空间即下发默认 API Key」的行为,可将系统设置 `tenant.auto_create_api_key` 置为 `true`(或设置环境变量 `WEKNORA_TENANT_AUTO_CREATE_API_KEY=true`)。开启后,创建空间会自动生成一个 `full_access` 权限的 API Key,并在响应体 `data.api_key` 中返回其明文 token(仅本次创建响应返回,请妥善保存)。默认 `false`。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------------------------------------------------ |
| name | string | 是 | 租户名称 |
| description | string | 否 | 租户描述 |
| name | string | 是 | 空间名称 |
| description | string | 否 | 空间描述 |
| business | string | 否 | 业务标识(如 `wechat`) |
| retriever_engines | object | 否 | 检索引擎组合配置(`engines` 数组:每项含 `retriever_type` 与 `retriever_engine_type`) |
| storage_quota | int | 否 | 存储配额(字节) |
@@ -131,7 +131,7 @@ curl --location 'http://localhost:8080/api/v1/tenants' \
--header 'Content-Type: application/json' \
--data '{
"name": "weknora",
"description": "weknora tenants",
"description": "weknora workspaces",
"business": "wechat",
"retriever_engines": {
"engines": [
@@ -155,7 +155,7 @@ curl --location 'http://localhost:8080/api/v1/tenants' \
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora tenants",
"description": "weknora workspaces",
"status": "active",
"retriever_engines": {
"engines": [
@@ -187,7 +187,7 @@ curl --location 'http://localhost:8080/api/v1/tenants' \
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora tenants",
"description": "weknora workspaces",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"business": "wechat",
@@ -201,15 +201,15 @@ curl --location 'http://localhost:8080/api/v1/tenants' \
}
```
## GET `/tenants/:id` - 获取指定租户信息
## GET `/tenants/:id` - 获取指定空间信息
获取指定 ID 的租户详情。只能访问自己所属租户;访问其他租户需要跨租户权限,否则返回 403。
获取指定 ID 的空间详情。只能访问自己所属空间;访问其他空间需要跨空间权限,否则返回 403。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ------- |
| id | int | 租户 ID |
| id | int | 空间 ID |
**请求**:
@@ -226,7 +226,7 @@ curl --location 'http://localhost:8080/api/v1/tenants/10000' \
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora tenants",
"description": "weknora workspaces",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"retriever_engines": {
@@ -252,15 +252,15 @@ curl --location 'http://localhost:8080/api/v1/tenants/10000' \
}
```
## PUT `/tenants/:id` - 更新租户信息
## PUT `/tenants/:id` - 更新空间信息
更新指定租户的基础信息。访问规则同 `GET /tenants/:id`。
更新指定空间的基础信息。访问规则同 `GET /tenants/:id`。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ------- |
| id | int | 租户 ID |
| id | int | 空间 ID |
**参数说明(请求体)**: 与 `POST /tenants` 相同字段;未传字段保持原值。
@@ -272,7 +272,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \
--header 'Content-Type: application/json' \
--data '{
"name": "weknora new",
"description": "weknora tenants new",
"description": "weknora workspaces new",
"status": "active",
"retriever_engines": {
"engines": [
@@ -298,7 +298,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \
"data": {
"id": 10000,
"name": "weknora new",
"description": "weknora tenants new",
"description": "weknora workspaces new",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"retriever_engines": {
@@ -324,15 +324,15 @@ curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \
}
```
## DELETE `/tenants/:id` - 删除租户
## DELETE `/tenants/:id` - 删除空间
删除指定租户。访问规则同 `GET /tenants/:id`。
删除指定空间。访问规则同 `GET /tenants/:id`。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ------- |
| id | int | 租户 ID |
| id | int | 空间 ID |
**请求**:
@@ -346,21 +346,21 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \
```json
{
"message": "Tenant deleted successfully",
"message": "Workspace deleted successfully",
"success": true
}
```
## 租户 API Key 管理(`tenant_api_keys`)
## 空间 API Key 管理(`tenant_api_keys`)
自 scoped API Key 改造后,密钥以独立记录存储,支持:
- **role**:`viewer`(只读 + 语义检索 POST)、`contributor`(知识库写入)、`admin`(租户级管理,不含 `/api-keys` 管理面)
- **role**:`viewer`(只读 + 语义检索 POST)、`contributor`(知识库写入)、`admin`(空间级管理,不含 `/api-keys` 管理面)
- **knowledge_base_ids**:可选,将 Key 限制在指定知识库
- **吊销**:`DELETE /tenants/:id/api-keys/:key_id`
- **过期**:创建时可选 `expires_at_unix`
认证上下文中的租户角色与 Key 的 `role` 一致(`viewer` / `contributor` / `admin`)。路由级 API Key 鉴权与 KB 访问守卫在 `X-API-Key` 认证后强制执行。
认证上下文中的空间角色与 Key 的 `role` 一致(`viewer` / `contributor` / `admin`)。路由级 API Key 鉴权与 KB 访问守卫在 `X-API-Key` 认证后强制执行。
## API Key Principal:隔离边界与安全说明
@@ -370,25 +370,25 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \
Principal **仅**用于按终端用户隔离以下能力:
- **对话 Session**(创建、列表、读取按外部用户分开;`仅租户` 模式仍共用租户级 Session)
- **MCP OAuth** 访问令牌(同一租户下不同外部用户各自授权,token 互不共用)
- **对话 Session**(创建、列表、读取按外部用户分开;`仅空间` 模式仍共用空间级 Session)
- **MCP OAuth** 访问令牌(同一空间下不同外部用户各自授权,token 互不共用)
- 对话内 MCP OAuth 提示、MCP 工具审批等与终端用户绑定的流程
Principal **不会**缩小 API Key 的 HTTP 路由权限:路由访问由 Key 的 `role` 控制;租户内 RBAC 角色与 `role` 一致。知识库、Agent 等资源的细粒度访问另受 KB 守卫约束。
Principal **不会**缩小 API Key 的 HTTP 路由权限:路由访问由 Key 的 `role` 控制;空间内 RBAC 角色与 `role` 一致。知识库、Agent 等资源的细粒度访问另受 KB 守卫约束。
### 模式与安全假设
| mode | 适用场景 | 安全假设 |
| ---- | -------- | -------- |
| `tenant` | 无 per-user MCP 需求 | 全租户共用一个 MCP OAuth 身份 |
| `tenant` | 无 per-user MCP 需求 | 全空间共用一个 MCP OAuth 身份 |
| `direct_header` | 仅可信服务端到服务端 | 用户 ID 来自调用方请求头,**可被持有 API Key 的任意调用方伪造**(冒充其他外部用户并共用/劫持其 MCP OAuth 授权)。面向终端用户或不可信客户端时**禁止**使用;若必须使用,请开启 `require_direct_header` 并确保 API Key 仅保存在可信后端 |
| `signed_token` | 面向终端用户的集成(**推荐**) | 由业务后端使用 `hmac_secret` 为外部用户签发短期 HS256 JWT;无效或缺失 token 返回 401,**不回退**为租户级 Principal |
| `signed_token` | 面向终端用户的集成(**推荐**) | 由业务后端使用 `hmac_secret` 为外部用户签发短期 HS256 JWT;无效或缺失 token 返回 401,**不回退**为空间级 Principal |
`direct_header` 模式下,若未携带用户 ID 请求头:`require_direct_header=false` 时回退为租户级 Principal;`require_direct_header=true` 时返回 401。
`direct_header` 模式下,若未携带用户 ID 请求头:`require_direct_header=false` 时回退为空间级 Principal;`require_direct_header=true` 时返回 401。
## GET `/tenants/:id/api-principal-config` - 获取 API Key 用户身份配置
返回租户级 API Key 请求如何映射为终端 Principal 的配置。**需要 Owner 权限**。
返回空间级 API Key 请求如何映射为终端 Principal 的配置。**需要 Owner 权限**。
**响应字段**:
@@ -453,9 +453,9 @@ curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000/api-pr
}'
```
## GET `/tenants` - 获取租户列表
## GET `/tenants` - 获取空间列表
返回当前认证上下文对应的租户(普通用户为单条;管理员仍只返回自身租户)。
返回当前认证上下文对应的空间(普通用户为单条;管理员仍只返回自身空间)。
**请求**:
@@ -474,7 +474,7 @@ curl --location 'http://localhost:8080/api/v1/tenants' \
{
"id": 10002,
"name": "weknora",
"description": "weknora tenants",
"description": "weknora workspaces",
"api_key": "sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA",
"status": "active",
"retriever_engines": {
@@ -502,9 +502,9 @@ curl --location 'http://localhost:8080/api/v1/tenants' \
}
```
## GET `/tenants/kv/:key` - 获取租户 KV 配置
## GET `/tenants/kv/:key` - 获取空间 KV 配置
获取当前租户的 KV 配置项。**租户 ID 从认证上下文中获取**(即由 `X-API-Key` / Bearer Token 对应的租户决定),URL 中不需要也不接受 tenant_id。
获取当前空间的 KV 配置项。**空间 ID 从认证上下文中获取**(即由 `X-API-Key` / Bearer Token 对应的空间决定),URL 中不需要也不接受 tenant_id。
**路径参数**:
@@ -560,9 +560,9 @@ curl --location 'http://localhost:8080/api/v1/tenants/kv/agent-config' \
{ "success": false, "error": "unsupported key" }
```
## PUT `/tenants/kv/:key` - 更新租户 KV 配置
## PUT `/tenants/kv/:key` - 更新空间 KV 配置
更新当前租户的 KV 配置项。**租户 ID 从认证上下文中获取**,请求体结构按 `key` 不同而异。`prompt-templates` 为只读,不支持 PUT。
更新当前空间的 KV 配置项。**空间 ID 从认证上下文中获取**,请求体结构按 `key` 不同而异。`prompt-templates` 为只读,不支持 PUT。
**路径参数**:
+8 -8
View File
@@ -2,7 +2,7 @@
[返回目录](./README.md)
向量存储(VectorStore)API 用于管理租户的向量数据库连接配置,支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、Tencent VectorDB、SQLite 等引擎。接口同时管理用户在 DB 中创建的配置(`source: "user"`)以及通过 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`,只读)。
向量存储(VectorStore)API 用于管理空间的向量数据库连接配置,支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、Tencent VectorDB、SQLite 等引擎。接口同时管理用户在 DB 中创建的配置(`source: "user"`)以及通过 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`,只读)。
| 方法 | 路径 | 描述 |
| ------ | ---------------------------- | -------------------------------- |
@@ -109,13 +109,13 @@ curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/test'
## POST `/vector-stores` - 创建向量存储
为当前租户创建一个新的向量存储配置。同一 endpoint + index 组合在租户内不允许重复(与环境变量配置的存储也会冲突)。
为当前空间创建一个新的向量存储配置。同一 endpoint + index 组合在空间内不允许重复(与环境变量配置的存储也会冲突)。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 是 | 存储显示名(租户内友好名) |
| name | string | 是 | 存储显示名(空间内友好名) |
| engine_type | string | 是 | 引擎类型,取自 `/vector-stores/types` |
| connection_config | object | 是 | 连接配置(与所选引擎的 `connection_fields` 对应) |
| index_config | object | 否 | 索引配置(与所选引擎的 `index_fields` 对应) |
@@ -193,7 +193,7 @@ curl --location 'http://localhost:8080/api/v1/vector-stores' \
## GET `/vector-stores` - 获取向量存储列表
返回当前租户的所有向量存储,包含 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`、`readonly: true`)和用户在 DB 中创建的存储(`source: "user"`、`readonly: false`)。环境变量存储排列在前。
返回当前空间的所有向量存储,包含 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`、`readonly: true`)和用户在 DB 中创建的存储(`source: "user"`、`readonly: false`)。环境变量存储排列在前。
**请求**:
@@ -335,7 +335,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e84
**Phase 2 — 绑定保护**:
删除请求在事务中执行,并按 `(tenant_id, vector_store_id)` 复合索引统计当前租户中仍绑定到该存储的活跃知识库数量。**只要存在任意绑定的知识库(已软删除的 KB 不计入),删除即被拒绝**,调用者必须先解绑或删除这些知识库才能继续。在 PostgreSQL 上,事务期间会对 `vector_stores` 行加 `SELECT … FOR UPDATE` 行锁,阻止并发的知识库创建请求悄悄落到正在被删除的存储上(SQLite 上则依赖 WAL + 单写入序列化达成同样语义)。
删除请求在事务中执行,并按 `(tenant_id, vector_store_id)` 复合索引统计当前空间中仍绑定到该存储的活跃知识库数量。**只要存在任意绑定的知识库(已软删除的 KB 不计入),删除即被拒绝**,调用者必须先解绑或删除这些知识库才能继续。在 PostgreSQL 上,事务期间会对 `vector_stores` 行加 `SELECT … FOR UPDATE` 行锁,阻止并发的知识库创建请求悄悄落到正在被删除的存储上(SQLite 上则依赖 WAL + 单写入序列化达成同样语义)。
**路径参数**:
@@ -370,7 +370,7 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550
}
```
HTTP `400`。错误消息中包含具体的知识库数量(便于运营定位),但不包含任何 KB 的 ID/名称,以避免跨租户信息泄漏。删除被拒绝时,DB 中的存储行保持原状,进程内引擎注册表也不会被清除。
HTTP `400`。错误消息中包含具体的知识库数量(便于运营定位),但不包含任何 KB 的 ID/名称,以避免跨空间信息泄漏。删除被拒绝时,DB 中的存储行保持原状,进程内引擎注册表也不会被清除。
## POST `/vector-stores/:id/test` - 测试已保存或环境变量存储的连接
@@ -427,9 +427,9 @@ Tencent VectorDB 环境变量存储可通过 `TENCENT_VECTORDB_REPLICA_NUMBER`
| HTTP 状态码 | code | 含义 |
| ----------- | ---- | --------------------------------------------------- |
| 400 | 1000 | 请求参数错误、校验失败、尝试修改环境变量存储、删除时仍有知识库绑定 |
| 400 | 2200 | 知识库创建时引用的 `vector_store_id` 无效(不存在或属于其他租户) |
| 400 | 2200 | 知识库创建时引用的 `vector_store_id` 无效(不存在或属于其他空间) |
| 400 | 2201 | 知识库创建时引用的存储当前不可用(DB 中存在但未注册到引擎) |
| 401 | 1001 | 未认证(缺少租户上下文或 API Key) |
| 401 | 1001 | 未认证(缺少空间上下文或 API Key) |
| 404 | 1003 | 向量存储不存在 |
| 409 | 1005 | 同一 endpoint + index 组合已存在 |
| 500 | 1007 | 内部服务器错误 |
+7 -7
View File
@@ -4,15 +4,15 @@
包含两组接口:
- `/web-search/providers`:返回**可用的 provider 类型**(只读元数据)
- `/web-search-providers/*`:当前租户**自定义保存**的 provider CRUD 与连通性测试
- `/web-search-providers/*`:当前空间**自定义保存**的 provider CRUD 与连通性测试
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------- | ----------------------------------- |
| GET | `/web-search/providers` | 获取网络搜索服务商类型列表 |
| GET | `/web-search-providers/types` | 获取 Provider 类型元数据(含参数定义) |
| POST | `/web-search-providers/test` | 使用原始凭证测试连通性(不落库) |
| POST | `/web-search-providers` | 创建租户级 Provider 配置 |
| GET | `/web-search-providers` | 获取当前租户已保存的 Provider 列表 |
| POST | `/web-search-providers` | 创建空间级 Provider 配置 |
| GET | `/web-search-providers` | 获取当前空间已保存的 Provider 列表 |
| GET | `/web-search-providers/:id` | 获取指定 Provider 详情 |
| PUT | `/web-search-providers/:id` | 更新 Provider |
| DELETE | `/web-search-providers/:id` | 删除 Provider |
@@ -20,7 +20,7 @@
## GET `/web-search/providers` - 获取网络搜索服务商类型列表
获取系统中可用的网络搜索服务商列表(系统级元数据,与租户无关)。
获取系统中可用的网络搜索服务商列表(系统级元数据,与空间无关)。
**请求**:
@@ -132,11 +132,11 @@ curl --location --request POST 'http://localhost:8080/api/v1/web-search-provider
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------- | ---- | ------------------------------------------ |
| name | string | 是 | Provider 显示名(在租户内唯一友好名) |
| name | string | 是 | Provider 显示名(在空间内唯一友好名) |
| provider | string | 是 | Provider 类型(来自 `/web-search-providers/types`) |
| description | string | 否 | 备注 |
| parameters | object | 否 | 凭证与参数 |
| is_default | boolean | 否 | 是否设为当前租户默认 Provider |
| is_default | boolean | 否 | 是否设为当前空间默认 Provider |
**请求**:
@@ -174,7 +174,7 @@ curl --location 'http://localhost:8080/api/v1/web-search-providers' \
## GET `/web-search-providers` - 获取 Provider 列表
返回当前租户已保存的所有 Provider。
返回当前空间已保存的所有 Provider。
**请求**: