fix: harden API principal config after review

Add require_direct_header toggle, external user ID validation, JWT TTL
limits, SaveToken error handling, ru-RU i18n, API docs, and Go SDK methods.
This commit is contained in:
wizardchen
2026-06-30 10:54:00 +08:00
committed by lyingbug
parent cb99736d72
commit 97bca74a31
17 changed files with 1212 additions and 14 deletions
+69
View File
@@ -16,6 +16,8 @@
| PUT | `/tenants/:id` | 更新租户信息 |
| DELETE | `/tenants/:id` | 删除租户 |
| POST | `/tenants/:id/api-key` | 重置租户 API Key |
| 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 由认证上下文确定) |
@@ -354,6 +356,73 @@ curl --location --request POST 'http://localhost:8080/api/v1/tenants/10000/api-k
}
```
## GET `/tenants/:id/api-principal-config` - 获取 API Key 用户身份配置
返回租户级 API Key 请求如何映射为终端 Principal 的配置。**需要 Owner 权限**。
**响应字段**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| mode | string | `tenant` / `direct_header` / `signed_token` |
| direct_header_name | string | 直接传用户 ID 时的请求头名,默认 `X-External-User-ID` |
| signed_token_header_name | string | 签名 token 模式请求头名,默认 `X-External-User-Token` |
| require_direct_header | bool | `direct_header` 模式下是否强制要求用户 ID 请求头 |
| has_hmac_secret | bool | 是否已配置 HMAC secret(不返回明文) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants/10000/api-principal-config' \
--header 'Authorization: Bearer <token>'
```
**响应**:
```json
{
"success": true,
"data": {
"mode": "signed_token",
"direct_header_name": "X-External-User-ID",
"signed_token_header_name": "X-External-User-Token",
"require_direct_header": false,
"has_hmac_secret": true
}
}
```
## PUT `/tenants/:id/api-principal-config` - 更新 API Key 用户身份配置
更新 API Key 请求的 Principal 映射方式。**需要 Owner 权限**。
**请求体**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| mode | string | 必填,`tenant` / `direct_header` / `signed_token` |
| direct_header_name | string | 可选 |
| signed_token_header_name | string | 可选 |
| require_direct_header | bool | 可选,`direct_header` 模式下缺 header 是否 401 |
| hmac_secret | string | 可选,`signed_token` 模式 HMAC 密钥;省略则保留现有值 |
`signed_token` 模式首次启用时必须提供 `hmac_secret`。
外部用户 JWT 要求:HS256 签名、`aud=weknora`、包含 `sub` 与 `tenant_id`、有效期不超过 24 小时。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000/api-principal-config' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"mode": "direct_header",
"direct_header_name": "X-External-User-ID",
"require_direct_header": true
}'
```
## GET `/tenants` - 获取租户列表
返回当前认证上下文对应的租户(普通用户为单条;管理员仍只返回自身租户)。
+324 -2
View File
@@ -19,6 +19,107 @@ const docTemplate = `{
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/agent/mcp-oauth-resolutions/{pending_id}": {
"post": {
"security": [
{
"Bearer": []
}
],
"description": "用户在对话中完成 OAuth 授权后调用,校验令牌存在后恢复被暂停的 Agent 工具调用",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"MCP服务"
],
"summary": "完成对话内 MCP OAuth 授权",
"parameters": [
{
"type": "string",
"description": "待授权 ID",
"name": "pending_id",
"in": "path",
"required": true
},
{
"description": "{service_id: string}",
"name": "request",
"in": "body",
"required": true,
"schema": {
"type": "object",
"additionalProperties": true
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"409": {
"description": "用户尚未完成授权",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/agent/mcp-oauth-resolutions/{pending_id}/cancel": {
"post": {
"security": [
{
"Bearer": []
}
],
"description": "用户主动跳过 OAuth 授权,解除 Agent 阻塞",
"produces": [
"application/json"
],
"tags": [
"MCP服务"
],
"summary": "跳过对话内 MCP OAuth 授权",
"parameters": [
{
"type": "string",
"description": "待授权 ID",
"name": "pending_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/agent/tool-approvals/{pending_id}": {
"post": {
"security": [
@@ -11906,6 +12007,113 @@ const docTemplate = `{
}
}
},
"/tenants/{id}/api-principal-config": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "返回 X-API-Key 请求如何映射为终端 Principal 的配置(Owner)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"租户管理"
],
"summary": "获取租户 API Key 用户身份配置",
"parameters": [
{
"type": "integer",
"description": "租户ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "API principal 配置",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "请求参数错误",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"403": {
"description": "权限不足",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
},
"put": {
"security": [
{
"Bearer": []
}
],
"description": "配置 X-API-Key 请求如何映射为终端 Principal(Owner)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"租户管理"
],
"summary": "更新租户 API Key 用户身份配置",
"parameters": [
{
"type": "integer",
"description": "租户ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "API principal 配置",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/internal_handler.apiPrincipalConfigRequest"
}
}
],
"responses": {
"200": {
"description": "更新后的配置",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "请求参数错误",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"403": {
"description": "权限不足",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/tenants/{id}/audit-log": {
"get": {
"security": [
@@ -13604,6 +13812,19 @@ const docTemplate = `{
}
}
},
"github_com_Tencent_WeKnora_internal_types.APIPrincipalMode": {
"type": "string",
"enum": [
"tenant",
"direct_header",
"signed_token"
],
"x-enum-varnames": [
"APIPrincipalModeTenant",
"APIPrincipalModeDirect",
"APIPrincipalModeSignedToken"
]
},
"github_com_Tencent_WeKnora_internal_types.ASRConfig": {
"type": "object",
"properties": {
@@ -15474,6 +15695,10 @@ const docTemplate = `{
"api_key": {
"type": "string"
},
"api_key_header": {
"description": "APIKeyHeader is the header name that carries APIKey when AuthType is\napi_key. Empty defaults to \"X-API-Key\". This is non-secret structural\nconfig (the secret is APIKey), so it is not encrypted and is safe to echo\nback in responses. It lets services that expect the key in a different\nheader (e.g. the raw token directly in \"Authorization\") work without\nresorting to plaintext custom headers.",
"type": "string"
},
"auth_server_metadata_url": {
"description": "AuthServerMetadataURL optionally pins the OAuth authorization server\nmetadata URL. When empty, the server is discovered automatically from\nthe MCP URL (RFC 9728 / RFC 8414).",
"type": "string"
@@ -15727,6 +15952,14 @@ const docTemplate = `{
"id": {
"type": "string"
},
"kb_id": {
"description": "Parent knowledge base for file/tag mentions",
"type": "string"
},
"kb_name": {
"description": "Display name for parent KB",
"type": "string"
},
"kb_type": {
"description": "\"document\" or \"faq\" (only for kb type)",
"type": "string"
@@ -15734,8 +15967,16 @@ const docTemplate = `{
"name": {
"type": "string"
},
"service_id": {
"description": "Parent MCP service for MCP tool mentions",
"type": "string"
},
"skill_name": {
"description": "Preloaded agent skill name",
"type": "string"
},
"type": {
"description": "\"kb\" for knowledge base, \"file\" for file",
"description": "\"kb\", \"file\", \"tag\", \"mcp\", \"skill\"",
"type": "string"
}
}
@@ -16932,9 +17173,33 @@ const docTemplate = `{
"type": "string"
}
},
"mcp_service_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"mentioned_items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.MentionedItem"
}
},
"model_id": {
"type": "string"
},
"skill_names": {
"type": "array",
"items": {
"type": "string"
}
},
"tag_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"web_search_enabled": {
"type": "boolean"
}
@@ -19632,6 +19897,26 @@ const docTemplate = `{
}
}
},
"internal_handler.apiPrincipalConfigRequest": {
"type": "object",
"properties": {
"direct_header_name": {
"type": "string"
},
"hmac_secret": {
"type": "string"
},
"mode": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.APIPrincipalMode"
},
"require_direct_header": {
"type": "boolean"
},
"signed_token_header_name": {
"type": "string"
}
}
},
"internal_handler.auditLogListResponse": {
"type": "object",
"properties": {
@@ -19891,6 +20176,13 @@ const docTemplate = `{
"type": "string"
}
},
"mcp_service_ids": {
"description": "Per-request MCP services selected via @mention",
"type": "array",
"items": {
"type": "string"
}
},
"mentioned_items": {
"description": "@mentioned knowledge bases and files",
"type": "array",
@@ -19902,10 +20194,24 @@ const docTemplate = `{
"description": "Query text for knowledge base search",
"type": "string"
},
"skill_names": {
"description": "Per-request Skills selected via @mention",
"type": "array",
"items": {
"type": "string"
}
},
"summary_model_id": {
"description": "Optional summary model ID for this request (overrides session default)",
"type": "string"
},
"tag_ids": {
"description": "@mentioned tag IDs (display/debug; scoped via MentionedItems)",
"type": "array",
"items": {
"type": "string"
}
},
"web_search_enabled": {
"description": "Whether web search is enabled for this request",
"type": "boolean"
@@ -19963,6 +20269,14 @@ const docTemplate = `{
"id": {
"type": "string"
},
"kb_id": {
"description": "Parent knowledge base for file/tag mentions",
"type": "string"
},
"kb_name": {
"description": "Display name for parent KB",
"type": "string"
},
"kb_type": {
"description": "\"document\" or \"faq\" (only for kb type)",
"type": "string"
@@ -19970,8 +20284,16 @@ const docTemplate = `{
"name": {
"type": "string"
},
"service_id": {
"description": "Parent MCP service for MCP tool mentions",
"type": "string"
},
"skill_name": {
"description": "Preloaded agent skill name",
"type": "string"
},
"type": {
"description": "\"kb\" for knowledge base, \"file\" for file",
"description": "\"kb\", \"file\", \"tag\", \"mcp\", \"skill\"",
"type": "string"
}
}
+324 -2
View File
@@ -12,6 +12,107 @@
},
"basePath": "/api/v1",
"paths": {
"/agent/mcp-oauth-resolutions/{pending_id}": {
"post": {
"security": [
{
"Bearer": []
}
],
"description": "用户在对话中完成 OAuth 授权后调用,校验令牌存在后恢复被暂停的 Agent 工具调用",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"MCP服务"
],
"summary": "完成对话内 MCP OAuth 授权",
"parameters": [
{
"type": "string",
"description": "待授权 ID",
"name": "pending_id",
"in": "path",
"required": true
},
{
"description": "{service_id: string}",
"name": "request",
"in": "body",
"required": true,
"schema": {
"type": "object",
"additionalProperties": true
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"409": {
"description": "用户尚未完成授权",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/agent/mcp-oauth-resolutions/{pending_id}/cancel": {
"post": {
"security": [
{
"Bearer": []
}
],
"description": "用户主动跳过 OAuth 授权,解除 Agent 阻塞",
"produces": [
"application/json"
],
"tags": [
"MCP服务"
],
"summary": "跳过对话内 MCP OAuth 授权",
"parameters": [
{
"type": "string",
"description": "待授权 ID",
"name": "pending_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/agent/tool-approvals/{pending_id}": {
"post": {
"security": [
@@ -11899,6 +12000,113 @@
}
}
},
"/tenants/{id}/api-principal-config": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "返回 X-API-Key 请求如何映射为终端 Principal 的配置(Owner)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"租户管理"
],
"summary": "获取租户 API Key 用户身份配置",
"parameters": [
{
"type": "integer",
"description": "租户ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "API principal 配置",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "请求参数错误",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"403": {
"description": "权限不足",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
},
"put": {
"security": [
{
"Bearer": []
}
],
"description": "配置 X-API-Key 请求如何映射为终端 Principal(Owner)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"租户管理"
],
"summary": "更新租户 API Key 用户身份配置",
"parameters": [
{
"type": "integer",
"description": "租户ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "API principal 配置",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/internal_handler.apiPrincipalConfigRequest"
}
}
],
"responses": {
"200": {
"description": "更新后的配置",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "请求参数错误",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"403": {
"description": "权限不足",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/tenants/{id}/audit-log": {
"get": {
"security": [
@@ -13597,6 +13805,19 @@
}
}
},
"github_com_Tencent_WeKnora_internal_types.APIPrincipalMode": {
"type": "string",
"enum": [
"tenant",
"direct_header",
"signed_token"
],
"x-enum-varnames": [
"APIPrincipalModeTenant",
"APIPrincipalModeDirect",
"APIPrincipalModeSignedToken"
]
},
"github_com_Tencent_WeKnora_internal_types.ASRConfig": {
"type": "object",
"properties": {
@@ -15467,6 +15688,10 @@
"api_key": {
"type": "string"
},
"api_key_header": {
"description": "APIKeyHeader is the header name that carries APIKey when AuthType is\napi_key. Empty defaults to \"X-API-Key\". This is non-secret structural\nconfig (the secret is APIKey), so it is not encrypted and is safe to echo\nback in responses. It lets services that expect the key in a different\nheader (e.g. the raw token directly in \"Authorization\") work without\nresorting to plaintext custom headers.",
"type": "string"
},
"auth_server_metadata_url": {
"description": "AuthServerMetadataURL optionally pins the OAuth authorization server\nmetadata URL. When empty, the server is discovered automatically from\nthe MCP URL (RFC 9728 / RFC 8414).",
"type": "string"
@@ -15720,6 +15945,14 @@
"id": {
"type": "string"
},
"kb_id": {
"description": "Parent knowledge base for file/tag mentions",
"type": "string"
},
"kb_name": {
"description": "Display name for parent KB",
"type": "string"
},
"kb_type": {
"description": "\"document\" or \"faq\" (only for kb type)",
"type": "string"
@@ -15727,8 +15960,16 @@
"name": {
"type": "string"
},
"service_id": {
"description": "Parent MCP service for MCP tool mentions",
"type": "string"
},
"skill_name": {
"description": "Preloaded agent skill name",
"type": "string"
},
"type": {
"description": "\"kb\" for knowledge base, \"file\" for file",
"description": "\"kb\", \"file\", \"tag\", \"mcp\", \"skill\"",
"type": "string"
}
}
@@ -16925,9 +17166,33 @@
"type": "string"
}
},
"mcp_service_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"mentioned_items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.MentionedItem"
}
},
"model_id": {
"type": "string"
},
"skill_names": {
"type": "array",
"items": {
"type": "string"
}
},
"tag_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"web_search_enabled": {
"type": "boolean"
}
@@ -19625,6 +19890,26 @@
}
}
},
"internal_handler.apiPrincipalConfigRequest": {
"type": "object",
"properties": {
"direct_header_name": {
"type": "string"
},
"hmac_secret": {
"type": "string"
},
"mode": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.APIPrincipalMode"
},
"require_direct_header": {
"type": "boolean"
},
"signed_token_header_name": {
"type": "string"
}
}
},
"internal_handler.auditLogListResponse": {
"type": "object",
"properties": {
@@ -19884,6 +20169,13 @@
"type": "string"
}
},
"mcp_service_ids": {
"description": "Per-request MCP services selected via @mention",
"type": "array",
"items": {
"type": "string"
}
},
"mentioned_items": {
"description": "@mentioned knowledge bases and files",
"type": "array",
@@ -19895,10 +20187,24 @@
"description": "Query text for knowledge base search",
"type": "string"
},
"skill_names": {
"description": "Per-request Skills selected via @mention",
"type": "array",
"items": {
"type": "string"
}
},
"summary_model_id": {
"description": "Optional summary model ID for this request (overrides session default)",
"type": "string"
},
"tag_ids": {
"description": "@mentioned tag IDs (display/debug; scoped via MentionedItems)",
"type": "array",
"items": {
"type": "string"
}
},
"web_search_enabled": {
"description": "Whether web search is enabled for this request",
"type": "boolean"
@@ -19956,6 +20262,14 @@
"id": {
"type": "string"
},
"kb_id": {
"description": "Parent knowledge base for file/tag mentions",
"type": "string"
},
"kb_name": {
"description": "Display name for parent KB",
"type": "string"
},
"kb_type": {
"description": "\"document\" or \"faq\" (only for kb type)",
"type": "string"
@@ -19963,8 +20277,16 @@
"name": {
"type": "string"
},
"service_id": {
"description": "Parent MCP service for MCP tool mentions",
"type": "string"
},
"skill_name": {
"description": "Preloaded agent skill name",
"type": "string"
},
"type": {
"description": "\"kb\" for knowledge base, \"file\" for file",
"description": "\"kb\", \"file\", \"tag\", \"mcp\", \"skill\"",
"type": "string"
}
}
+223 -2
View File
@@ -205,6 +205,16 @@ definitions:
tier:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_infrastructure_chunker.StrategyTier'
type: object
github_com_Tencent_WeKnora_internal_types.APIPrincipalMode:
enum:
- tenant
- direct_header
- signed_token
type: string
x-enum-varnames:
- APIPrincipalModeTenant
- APIPrincipalModeDirect
- APIPrincipalModeSignedToken
github_com_Tencent_WeKnora_internal_types.ASRConfig:
properties:
enabled:
@@ -1674,6 +1684,15 @@ definitions:
properties:
api_key:
type: string
api_key_header:
description: |-
APIKeyHeader is the header name that carries APIKey when AuthType is
api_key. Empty defaults to "X-API-Key". This is non-secret structural
config (the secret is APIKey), so it is not encrypted and is safe to echo
back in responses. It lets services that expect the key in a different
header (e.g. the raw token directly in "Authorization") work without
resorting to plaintext custom headers.
type: string
auth_server_metadata_url:
description: |-
AuthServerMetadataURL optionally pins the OAuth authorization server
@@ -1859,13 +1878,25 @@ definitions:
properties:
id:
type: string
kb_id:
description: Parent knowledge base for file/tag mentions
type: string
kb_name:
description: Display name for parent KB
type: string
kb_type:
description: '"document" or "faq" (only for kb type)'
type: string
name:
type: string
service_id:
description: Parent MCP service for MCP tool mentions
type: string
skill_name:
description: Preloaded agent skill name
type: string
type:
description: '"kb" for knowledge base, "file" for file'
description: '"kb", "file", "tag", "mcp", "skill"'
type: string
type: object
github_com_Tencent_WeKnora_internal_types.Message:
@@ -2774,8 +2805,24 @@ definitions:
items:
type: string
type: array
mcp_service_ids:
items:
type: string
type: array
mentioned_items:
items:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.MentionedItem'
type: array
model_id:
type: string
skill_names:
items:
type: string
type: array
tag_ids:
items:
type: string
type: array
web_search_enabled:
type: boolean
type: object
@@ -4746,6 +4793,19 @@ definitions:
required:
- similar_questions
type: object
internal_handler.apiPrincipalConfigRequest:
properties:
direct_header_name:
type: string
hmac_secret:
type: string
mode:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.APIPrincipalMode'
require_direct_header:
type: boolean
signed_token_header_name:
type: string
type: object
internal_handler.auditLogListResponse:
properties:
data:
@@ -4937,6 +4997,11 @@ definitions:
items:
type: string
type: array
mcp_service_ids:
description: Per-request MCP services selected via @mention
items:
type: string
type: array
mentioned_items:
description: '@mentioned knowledge bases and files'
items:
@@ -4945,10 +5010,20 @@ definitions:
query:
description: Query text for knowledge base search
type: string
skill_names:
description: Per-request Skills selected via @mention
items:
type: string
type: array
summary_model_id:
description: Optional summary model ID for this request (overrides session
default)
type: string
tag_ids:
description: '@mentioned tag IDs (display/debug; scoped via MentionedItems)'
items:
type: string
type: array
web_search_enabled:
description: Whether web search is enabled for this request
type: boolean
@@ -4990,13 +5065,25 @@ definitions:
properties:
id:
type: string
kb_id:
description: Parent knowledge base for file/tag mentions
type: string
kb_name:
description: Display name for parent KB
type: string
kb_type:
description: '"document" or "faq" (only for kb type)'
type: string
name:
type: string
service_id:
description: Parent MCP service for MCP tool mentions
type: string
skill_name:
description: Preloaded agent skill name
type: string
type:
description: '"kb" for knowledge base, "file" for file'
description: '"kb", "file", "tag", "mcp", "skill"'
type: string
type: object
internal_handler_session.SearchKnowledgeRequest:
@@ -5045,6 +5132,71 @@ info:
title: WeKnora API
version: "1.0"
paths:
/agent/mcp-oauth-resolutions/{pending_id}:
post:
consumes:
- application/json
description: 用户在对话中完成 OAuth 授权后调用,校验令牌存在后恢复被暂停的 Agent 工具调用
parameters:
- description: 待授权 ID
in: path
name: pending_id
required: true
type: string
- description: '{service_id: string}'
in: body
name: request
required: true
schema:
additionalProperties: true
type: object
produces:
- application/json
responses:
"200":
description: OK
schema:
additionalProperties: true
type: object
"400":
description: Bad Request
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
"409":
description: 用户尚未完成授权
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
security:
- Bearer: []
summary: 完成对话内 MCP OAuth 授权
tags:
- MCP服务
/agent/mcp-oauth-resolutions/{pending_id}/cancel:
post:
description: 用户主动跳过 OAuth 授权,解除 Agent 阻塞
parameters:
- description: 待授权 ID
in: path
name: pending_id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
additionalProperties: true
type: object
"404":
description: Not Found
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
security:
- Bearer: []
summary: 跳过对话内 MCP OAuth 授权
tags:
- MCP服务
/agent/tool-approvals/{pending_id}:
post:
consumes:
@@ -12465,6 +12617,75 @@ paths:
summary: 重置租户 API Key
tags:
- 租户管理
/tenants/{id}/api-principal-config:
get:
consumes:
- application/json
description: 返回 X-API-Key 请求如何映射为终端 Principal 的配置(Owner)
parameters:
- description: 租户ID
in: path
name: id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: API principal 配置
schema:
additionalProperties: true
type: object
"400":
description: 请求参数错误
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
"403":
description: 权限不足
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
security:
- Bearer: []
summary: 获取租户 API Key 用户身份配置
tags:
- 租户管理
put:
consumes:
- application/json
description: 配置 X-API-Key 请求如何映射为终端 Principal(Owner)
parameters:
- description: 租户ID
in: path
name: id
required: true
type: integer
- description: API principal 配置
in: body
name: request
required: true
schema:
$ref: '#/definitions/internal_handler.apiPrincipalConfigRequest'
produces:
- application/json
responses:
"200":
description: 更新后的配置
schema:
additionalProperties: true
type: object
"400":
description: 请求参数错误
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
"403":
description: 权限不足
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
security:
- Bearer: []
summary: 更新租户 API Key 用户身份配置
tags:
- 租户管理
/tenants/{id}/audit-log:
get:
description: 返回该租户最近的审计事件,按 id 倒序。游标分页:将上次响应的 next_cursor 作为下一次请求的 after_id。