feat: user chat and external-retrieval

ui/src/api/API_README.md

@@ -732,11 +732,25 @@ Workspace 共享知识库详情由 `resourceScope: 'workspace-shared'` 选择上
 
 ### 资源对话用户授权
 
-`workspace/chat-user.ts` 使用 Admin 请求客户端，通过资源的 `user_group` 查询和保存组自动授权，
-通过 `user_group_id/<groupId>` 查询分页用户及保存逐用户授权，沿用已有接口路径与请求体。
-使用 `ParamsPage`、`ResponsePage`，调用方直接读取已解包数据并管理 loading。
-公共授权类型维护在 `types/chat-user.ts`，经 `@/api/types` 导出。当前由工作空间智能体详情页调用；
-仓库内开源后端尚未注册这组资源授权路径，实际联调依赖提供这些接口的后端环境。
+资源对话用户接口按四种范围维护 `chat-user.ts`，同一范围供智能体、知识库页面选用，不与 System 对话端用户管理接口混用：
+
+- `workspace/chat-user.ts`：`/workspace/{workspaceId}/{resource_type}/{resource_id}`。
+- `workspace/shared/chat-user.ts`：`/system/shared/workspace/{workspaceId}/{resource_type}/{resource_id}`，仅查询。
+- `system/resource-management/chat-user.ts`：`/system/resource/knowledge/{resource_type}/{resource_id}`。
+- `system/shared-resources/chat-user.ts`：`/system/shared/knowledge/{resource_type}/{resource_id}`。
+
+后三套沿用 V2 可核对的接口路径并标注 V3 联调 TODO；Workspace 共享在 V2 只核对到 KNOWLEDGE 查询，不能据此认定共享智能体接口已支持。
+System 前缀中的额外 `knowledge` 段暂按 V2 保留，不能依据普通资源接口自行删减。
+资源类型使用 `RESOURCE_TYPE.APPLICATION / KNOWLEDGE` 的大写值；后台按原值读写授权记录，不会将小写转换为大写。
+仓库中的 `system_manage/urls.py` 已注册普通 Workspace 授权路径，其他范围需在提供对应接口的后端环境联调。
+
+通过 `user_group` 查询和保存组自动授权，通过 `user_group_id/<groupId>` 保存逐用户授权，
+分页查询在其后追加 `/<currentPage>/<pageSize>`；沿用 `ParamsPage`、`ResponsePage` 和原有数组请求体。
+调用方直接读取已解包数据并管理 loading；共享只读 API 不补写方法以凑齐接口集合。
+公共类型维护在 `types/chat-user.ts`，经 `@/api/types` 导出；用户组当前没有已授权人数统计字段，待后台确定字段后补充，不用分页用户数据推算全组人数。
+
+当前智能体、知识库对话用户页仅直接调用普通 `workspace/chat-user.ts`，分别传自己的资源类型和路由 ID，暂不接入详情 context。
+其他三个范围的 API 文件保留，但页面暂不选择调用；页面不判断资源范围，当前请求统一使用 Workspace API，其他入口的 API 切换尚未接入。
 
 ### 智能体对话日志
 
@@ -759,6 +773,27 @@ Web 知识库详情及更新响应的顶层 `doc_strategy` 使用 `DocumentStrat
 `KnowledgeItem` 声明；非 Web 类型返回 null。文档处理策略设置通过 `putKnowledge` 仅提交
 `{ doc_strategy }`，服务端合并到知识库 meta，保留其他来源配置，保存不立即发起同步。
 
+### 知识库外部检索服务
+
+四个知识库范围分别在自己的 `external-retrieval.ts` 中维护相同的查询与保存方法，仅资源前缀不同：
+
+- Workspace：`/workspace/<workspaceId>/knowledge/<knowledgeId>`。
+- Workspace 共享：`/system/shared/workspace/<workspaceId>/knowledge/<knowledgeId>`。
+- System 资源管理：`/system/resource/knowledge/<knowledgeId>`。
+- System 共享资源：`/system/shared/knowledge/<knowledgeId>`。
+
+`getKnowledgeExternalRetrieval(knowledgeId)` 通过 GET `<资源前缀>/external_service` 查询配置；
+`putKnowledgeExternalRetrieval(knowledgeId, payload)` 通过 PUT 同一路径保存开关。
+工作空间 ID 在调用时由 API 内读取，四套均使用 Admin 请求封装，不返回占位 null 或回退其他范围。
+
+联调 TODO 统一保留在两个方法处：查询返回 `enabled`、`authentication`、`api_url`、`api_example`、`mcp_url`、`mcp_config`；
+`api_example` 为后台生成的完整 API 调用示例文本（string），前端仅展示和复制，不拼接请求内容。
+保存只更新 payload 传入的 `enabled` 或 `authentication`，保留未提交字段，并返回包含最新 `api_example` 的完整配置。
+响应与提交类型共用 `types/knowledge-external-retrieval.ts`，通过 `@/api/types` 导入；请求层统一解包 `data`。
+页面已实现加载、开关保存、回显与只读内容复制；接口字段有差异时在各自 API 模块适配，不要求联调人员补写页面交互。
+当前页面仅直接调用普通 `workspace/knowledge/external-retrieval.ts`，暂不接入详情 context；
+其他三个范围的 API 文件保留，页面暂不请求并禁用开关、显示待接入提示，不回退普通 Workspace。
+
 ### 知识库定时同步
 
 `setting/scheduled-sync/` 页面调用设置查询、保存和日志分页接口；保存返回的规范化配置用于回填。

ui/src/api/admin/system/resource-management/chat-user.ts

@@ -0,0 +1,30 @@
+import { get, put } from '../../core/request'
+import type { ParamsPage, ResponsePage } from '../../core/types'
+import type {
+  ChatUserAuthorization,
+  ChatUserAuthorizationGroup,
+  ChatUserAuthorizationResource,
+  ChatUserGroupAuthorizationPayload,
+  ChatUserAuthorizationPayload,
+  Dict,
+} from '@/api/types'
+
+// TODO：V3 联调确认授权前缀；当前沿用 V2 的 /system/resource/knowledge/{resource_type}。
+const getPrefix = (resource: ChatUserAuthorizationResource) => `/system/resource/knowledge/${resource.resource_type}/${resource.resource_id}`
+
+/** 获取资源的对话用户组及自动授权状态。 */
+const getUserGroupList = (resource: ChatUserAuthorizationResource) => get<ChatUserAuthorizationGroup[]>(`${getPrefix(resource)}/user_group`)
+
+/** 保存资源的用户组自动授权设置。 */
+const putUserGroupAuthorization = (resource: ChatUserAuthorizationResource, data: ChatUserGroupAuthorizationPayload[]) =>
+  put<ChatUserGroupAuthorizationPayload[], boolean>(`${getPrefix(resource)}/user_group`, data)
+
+/** 分页查询用户组内的对话用户及资源授权状态。 */
+const getUserGroupUserList = (resource: ChatUserAuthorizationResource, userGroupId: string, page: ParamsPage, query?: Dict<unknown>) =>
+  get<ResponsePage<ChatUserAuthorization>>(`${getPrefix(resource)}/user_group_id/${userGroupId}/${page.currentPage}/${page.pageSize}`, query)
+
+/** 保存用户组内的对话用户资源授权。 */
+const putUserGroupUser = (resource: ChatUserAuthorizationResource, userGroupId: string, data: ChatUserAuthorizationPayload[]) =>
+  put<ChatUserAuthorizationPayload[], boolean>(`${getPrefix(resource)}/user_group_id/${userGroupId}`, data)
+
+export default { getUserGroupList, putUserGroupAuthorization, getUserGroupUserList, putUserGroupUser }

ui/src/api/admin/system/resource-management/knowledge/external-retrieval.ts

@@ -0,0 +1,16 @@
+import { get, put } from '@/api/admin/core/request'
+import type { KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting } from '@/api/types'
+
+const getPrefix = (knowledgeId: string) => `/system/resource/knowledge/${knowledgeId}`
+
+/** 获取知识库外部检索服务配置。 */
+// TODO：联调确认响应包含 enabled、authentication、api_url、api_example、mcp_url、mcp_config。
+// api_example 为后台生成的完整示例文本（string），前端直接展示和复制，不拼接请求内容。
+const getKnowledgeExternalRetrieval = (knowledgeId: string) => get<KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`)
+
+/** 保存知识库外部检索服务开关。 */
+// TODO：只更新 payload 中的开关，保留未提交字段，并返回包含最新 api_example 的完整配置。
+const putKnowledgeExternalRetrieval = (knowledgeId: string, payload: KnowledgeExternalRetrievalPayload) =>
+  put<KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`, payload)
+
+export default { getKnowledgeExternalRetrieval, putKnowledgeExternalRetrieval }

ui/src/api/admin/system/shared-resources/chat-user.ts

@@ -0,0 +1,30 @@
+import { get, put } from '../../core/request'
+import type { ParamsPage, ResponsePage } from '../../core/types'
+import type {
+  ChatUserAuthorization,
+  ChatUserAuthorizationGroup,
+  ChatUserAuthorizationResource,
+  ChatUserGroupAuthorizationPayload,
+  ChatUserAuthorizationPayload,
+  Dict,
+} from '@/api/types'
+
+// TODO：V3 联调确认授权前缀；当前沿用 V2 的 /system/shared/knowledge/{resource_type}。
+const getPrefix = (resource: ChatUserAuthorizationResource) => `/system/shared/knowledge/${resource.resource_type}/${resource.resource_id}`
+
+/** 获取资源的对话用户组及自动授权状态。 */
+const getUserGroupList = (resource: ChatUserAuthorizationResource) => get<ChatUserAuthorizationGroup[]>(`${getPrefix(resource)}/user_group`)
+
+/** 保存资源的用户组自动授权设置。 */
+const putUserGroupAuthorization = (resource: ChatUserAuthorizationResource, data: ChatUserGroupAuthorizationPayload[]) =>
+  put<ChatUserGroupAuthorizationPayload[], boolean>(`${getPrefix(resource)}/user_group`, data)
+
+/** 分页查询用户组内的对话用户及资源授权状态。 */
+const getUserGroupUserList = (resource: ChatUserAuthorizationResource, userGroupId: string, page: ParamsPage, query?: Dict<unknown>) =>
+  get<ResponsePage<ChatUserAuthorization>>(`${getPrefix(resource)}/user_group_id/${userGroupId}/${page.currentPage}/${page.pageSize}`, query)
+
+/** 保存用户组内的对话用户资源授权。 */
+const putUserGroupUser = (resource: ChatUserAuthorizationResource, userGroupId: string, data: ChatUserAuthorizationPayload[]) =>
+  put<ChatUserAuthorizationPayload[], boolean>(`${getPrefix(resource)}/user_group_id/${userGroupId}`, data)
+
+export default { getUserGroupList, putUserGroupAuthorization, getUserGroupUserList, putUserGroupUser }

ui/src/api/admin/system/shared-resources/knowledge/external-retrieval.ts

@@ -0,0 +1,16 @@
+import { get, put } from '@/api/admin/core/request'
+import type { KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting } from '@/api/types'
+
+const getPrefix = (knowledgeId: string) => `/system/shared/knowledge/${knowledgeId}`
+
+/** 获取知识库外部检索服务配置。 */
+// TODO：联调确认响应包含 enabled、authentication、api_url、api_example、mcp_url、mcp_config。
+// api_example 为后台生成的完整示例文本（string），前端直接展示和复制，不拼接请求内容。
+const getKnowledgeExternalRetrieval = (knowledgeId: string) => get<KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`)
+
+/** 保存知识库外部检索服务开关。 */
+// TODO：只更新 payload 中的开关，保留未提交字段，并返回包含最新 api_example 的完整配置。
+const putKnowledgeExternalRetrieval = (knowledgeId: string, payload: KnowledgeExternalRetrievalPayload) =>
+  put<KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`, payload)
+
+export default { getKnowledgeExternalRetrieval, putKnowledgeExternalRetrieval }

ui/src/api/admin/workspace/knowledge/external-retrieval.ts

@@ -0,0 +1,17 @@
+import { get, put } from '../../core/request'
+import type { KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting } from '@/api/types'
+import { getWorkspaceId } from '@/utils/resource-context'
+
+const getPrefix = (knowledgeId: string) => `/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}`
+
+/** 获取知识库外部检索服务配置。 */
+// TODO：联调确认响应包含 enabled、authentication、api_url、api_example、mcp_url、mcp_config。
+// api_example 为后台生成的完整示例文本（string），前端直接展示和复制，不拼接请求内容。
+const getKnowledgeExternalRetrieval = (knowledgeId: string) => get<KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`)
+
+/** 保存知识库外部检索服务开关。 */
+// TODO：只更新 payload 中的开关，保留未提交字段，并返回包含最新 api_example 的完整配置。
+const putKnowledgeExternalRetrieval = (knowledgeId: string, payload: KnowledgeExternalRetrievalPayload) =>
+  put<KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`, payload)
+
+export default { getKnowledgeExternalRetrieval, putKnowledgeExternalRetrieval }

ui/src/api/admin/workspace/shared/chat-user.ts

@@ -0,0 +1,17 @@
+import { get } from '../../core/request'
+import type { ParamsPage, ResponsePage } from '../../core/types'
+import type { ChatUserAuthorization, ChatUserAuthorizationGroup, ChatUserAuthorizationResource, Dict } from '@/api/types'
+import { getWorkspaceId } from '@/utils/resource-context'
+
+// TODO：V3 联调确认共享授权路径；当前沿用 V2 的大写资源类型，已核对 KNOWLEDGE 查询。
+const getPrefix = (resource: ChatUserAuthorizationResource) =>
+  `/system/shared/workspace/${getWorkspaceId()}/${resource.resource_type}/${resource.resource_id}`
+
+/** 查询工作空间共享资源的用户组授权状态。 */
+const getUserGroupList = (resource: ChatUserAuthorizationResource) => get<ChatUserAuthorizationGroup[]>(`${getPrefix(resource)}/user_group`)
+
+/** 分页查询共享资源的组内用户授权；共享范围不提供写接口。 */
+const getUserGroupUserList = (resource: ChatUserAuthorizationResource, userGroupId: string, page: ParamsPage, query?: Dict<unknown>) =>
+  get<ResponsePage<ChatUserAuthorization>>(`${getPrefix(resource)}/user_group_id/${userGroupId}/${page.currentPage}/${page.pageSize}`, query)
+
+export default { getUserGroupList, getUserGroupUserList }

ui/src/api/admin/workspace/shared/knowledge/external-retrieval.ts

@@ -0,0 +1,17 @@
+import { get, put } from '../../../core/request'
+import type { KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting } from '@/api/types'
+import { getWorkspaceId } from '@/utils/resource-context'
+
+const getPrefix = (knowledgeId: string) => `/system/shared/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}`
+
+/** 获取知识库外部检索服务配置。 */
+// TODO：联调确认响应包含 enabled、authentication、api_url、api_example、mcp_url、mcp_config。
+// api_example 为后台生成的完整示例文本（string），前端直接展示和复制，不拼接请求内容。
+const getKnowledgeExternalRetrieval = (knowledgeId: string) => get<KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`)
+
+/** 保存知识库外部检索服务开关。 */
+// TODO：只更新 payload 中的开关，保留未提交字段，并返回包含最新 api_example 的完整配置。
+const putKnowledgeExternalRetrieval = (knowledgeId: string, payload: KnowledgeExternalRetrievalPayload) =>
+  put<KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetting>(`${getPrefix(knowledgeId)}/external_service`, payload)
+
+export default { getKnowledgeExternalRetrieval, putKnowledgeExternalRetrieval }

ui/src/api/types/chat-user.ts

@@ -1,6 +1,6 @@
 /** 对话用户 API 与管理页面共用的业务类型。 */
 
-import { PERIOD_TYPE, QUOTA_TYPE } from '@/api/enums'
+import { PERIOD_TYPE, QUOTA_TYPE, RESOURCE_TYPE } from '@/api/enums'
 
 export interface ChatUserBase {
   id: string
@@ -104,7 +104,7 @@ export interface BatchSetChatUserQuotaResult {
 /** 对话用户授权所属的资源。 */
 export interface ChatUserAuthorizationResource {
   resource_id: string
-  resource_type: string
+  resource_type: (typeof RESOURCE_TYPE)['APPLICATION' | 'KNOWLEDGE']
 }
 
 /** 资源内的对话用户组自动授权状态。 */

ui/src/api/types/index.ts

@@ -19,6 +19,7 @@ export type * from './folder'
 export type * from './tool'
 export type * from './knowledge'
 export type * from './knowledge-sync'
+export type * from './knowledge-external-retrieval'
 export type * from './trigger'
 export type * from './related-resources'
 export type * from './workflow-version'

ui/src/api/types/knowledge-external-retrieval.ts

@@ -0,0 +1,17 @@
+import type { Dict } from './common'
+
+/** 知识库外部检索服务配置。 */
+export interface KnowledgeExternalRetrievalSetting {
+  enabled: boolean
+  authentication: boolean
+  api_url: string
+  api_example: string
+  mcp_url: string
+  mcp_config: Dict<unknown>
+}
+
+/** 每次只提交发生变化的开关，保留其他配置。 */
+export interface KnowledgeExternalRetrievalPayload {
+  enabled?: boolean
+  authentication?: boolean
+}