@numa-tech/numa 1.24.0 → 1.26.0

package/src/kb/openapi-contract.json

@@ -1,106 +1,9 @@
 {
   "components": {
     "schemas": {
-      "ArchiveFile": {
-        "properties": {
-          "archive_category": {
-            "enum": [
-              "final",
-              "intermediate",
-              "task_memory"
-            ],
-            "title": "Archive Category",
-            "type": "string"
-          },
-          "confirm_version_switch": {
-            "title": "Confirm Version Switch",
-            "type": "boolean"
-          },
-          "conflict_action": {
-            "enum": [
-              "reject",
-              "keep_both",
-              "new_version",
-              "skip"
-            ],
-            "title": "Conflict Action",
-            "type": "string"
-          },
-          "content_base64": {
-            "title": "Content Base64",
-            "type": "string"
-          },
-          "existing_document_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Existing Document Id"
-          },
-          "filename": {
-            "title": "Filename",
-            "type": "string"
-          },
-          "rename_to": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Rename To"
-          },
-          "task_id": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Task Id"
-          },
-          "title": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Title"
-          },
-          "version_reason": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Version Reason"
-          }
-        },
-        "required": [
-          "filename",
-          "content_base64"
-        ],
-        "title": "ArchiveFile",
-        "type": "object"
-      },
       "Body_begin_direct_upload": {
         "properties": {
           "collection_id": {
-            "default": "default",
             "title": "Collection Id",
             "type": "string"
           },
@@ -130,7 +33,8 @@
         },
         "required": [
           "files",
-          "request_id"
+          "request_id",
+          "collection_id"
         ],
         "title": "Body_begin_direct_upload",
         "type": "object"
@@ -359,89 +263,117 @@
         "title": "Body_search_knowledge_base",
         "type": "object"
       },
-      "Body_start_async_archive": {
+      "ChatRequest": {
+        "description": "Request body for the streaming RAG chat endpoint.",
         "properties": {
-          "collection_id": {
-            "default": "default",
-            "title": "Collection Id",
-            "type": "string"
-          },
-          "files": {
+          "collection_ids": {
             "items": {
-              "$ref": "#/components/schemas/ArchiveFile"
+              "type": "string"
             },
-            "title": "Files",
+            "maxItems": 20,
+            "minItems": 1,
+            "title": "Collection Ids",
             "type": "array"
           },
-          "request_id": {
-            "title": "Request Id",
-            "type": "string"
-          }
-        },
-        "required": [
-          "files",
-          "request_id"
-        ],
-        "title": "Body_start_async_archive",
-        "type": "object"
-      },
-      "Body_upload_external_documents_api_v1_external_documents_batch_upload_post": {
-        "properties": {
-          "collection_id": {
-            "default": "default",
-            "title": "Collection Id",
-            "type": "string"
-          },
-          "conflict_policy": {
-            "default": "detect",
-            "enum": [
-              "detect",
-              "reject",
-              "force_upload"
-            ],
-            "title": "Conflict Policy",
-            "type": "string"
-          },
-          "duplicate_resolutions_json": {
+          "history": {
             "anyOf": [
               {
-                "type": "string"
+                "items": {
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "type": "object"
+                },
+                "maxItems": 50,
+                "type": "array"
               },
               {
                 "type": "null"
               }
             ],
-            "title": "Duplicate Resolutions Json"
+            "title": "History"
           },
-          "files": {
-            "items": {
-              "contentMediaType": "application/octet-stream",
-              "type": "string"
-            },
-            "title": "Files",
-            "type": "array"
+          "message": {
+            "maxLength": 8000,
+            "minLength": 1,
+            "title": "Message",
+            "type": "string"
           },
-          "relative_paths_json": {
+          "session_id": {
             "anyOf": [
               {
+                "maxLength": 80,
                 "type": "string"
               },
               {
                 "type": "null"
               }
             ],
-            "title": "Relative Paths Json"
+            "title": "Session Id"
           },
-          "request_id": {
-            "title": "Request Id",
+          "top_k": {
+            "default": 5,
+            "maximum": 30.0,
+            "minimum": 1.0,
+            "title": "Top K",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "message",
+          "collection_ids"
+        ],
+        "title": "ChatRequest",
+        "type": "object"
+      },
+      "ChatSessionCreateBody": {
+        "description": "Create a persistent RAG chat session.",
+        "properties": {
+          "collection_ids": {
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 20,
+            "minItems": 1,
+            "title": "Collection Ids",
+            "type": "array"
+          },
+          "title": {
+            "default": "新对话",
+            "maxLength": 80,
+            "title": "Title",
             "type": "string"
           }
         },
         "required": [
-          "files",
-          "request_id"
+          "collection_ids"
+        ],
+        "title": "ChatSessionCreateBody",
+        "type": "object"
+      },
+      "CollectionMemberBody": {
+        "properties": {
+          "global_uid": {
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Global Uid",
+            "type": "string"
+          },
+          "role": {
+            "enum": [
+              "viewer",
+              "contributor",
+              "manager"
+            ],
+            "title": "Role",
+            "type": "string"
+          }
+        },
+        "required": [
+          "global_uid",
+          "role"
         ],
-        "title": "Body_upload_external_documents_api_v1_external_documents_batch_upload_post",
+        "title": "CollectionMemberBody",
         "type": "object"
       },
       "ExternalBatchResolutionBody": {
@@ -529,147 +461,1703 @@
         "title": "HTTPValidationError",
         "type": "object"
       },
-      "UploadFileMetadata": {
-        "additionalProperties": false,
+      "ResolveConflictBody": {
         "properties": {
-          "content_md5": {
-            "title": "Content Md5",
-            "type": "string"
-          },
-          "content_type": {
-            "default": "application/octet-stream",
-            "maxLength": 200,
-            "title": "Content Type",
-            "type": "string"
-          },
-          "duplicate_action": {
-            "default": "",
+          "action": {
             "enum": [
-              "",
-              "upload",
-              "new_version"
+              "keep_both",
+              "supersede_existing",
+              "archive_existing",
+              "mark_superseded",
+              "mark_coexisting_scope",
+              "ingest_without_relation"
             ],
-            "title": "Duplicate Action",
+            "title": "Action",
             "type": "string"
           },
-          "existing_document_id": {
+          "scope": {
             "anyOf": [
               {
-                "type": "string"
+                "additionalProperties": true,
+                "type": "object"
               },
               {
                 "type": "null"
               }
             ],
-            "title": "Existing Document Id"
+            "title": "Scope"
+          }
+        },
+        "required": [
+          "action"
+        ],
+        "title": "ResolveConflictBody",
+        "type": "object"
+      },
+      "SwitchDocumentVersionBody": {
+        "properties": {
+          "confirmation": {
+            "const": "SWITCH_CURRENT_VERSION",
+            "title": "Confirmation",
+            "type": "string"
           },
-          "filename": {
-            "maxLength": 255,
+          "expected_current_version_id": {
+            "maxLength": 200,
             "minLength": 1,
-            "title": "Filename",
+            "title": "Expected Current Version Id",
             "type": "string"
           },
-          "sha256": {
-            "pattern": "^[0-9a-f]{64}$",
-            "title": "Sha256",
+          "reason": {
+            "maxLength": 500,
+            "minLength": 1,
+            "title": "Reason",
             "type": "string"
           },
-          "size_bytes": {
-            "exclusiveMinimum": 0.0,
-            "maximum": 104857600.0,
-            "title": "Size Bytes",
-            "type": "integer"
-          },
-          "version_confirmation": {
+          "target_version_id": {
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Target Version Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "target_version_id",
+          "expected_current_version_id",
+          "reason",
+          "confirmation"
+        ],
+        "title": "SwitchDocumentVersionBody",
+        "type": "object"
+      },
+      "TransferCollectionBody": {
+        "properties": {
+          "target_owner_id": {
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Target Owner Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "target_owner_id"
+        ],
+        "title": "TransferCollectionBody",
+        "type": "object"
+      },
+      "UpdateCollectionBody": {
+        "additionalProperties": false,
+        "properties": {
+          "description": {
             "anyOf": [
               {
-                "const": "SWITCH_CURRENT_VERSION",
+                "maxLength": 200,
                 "type": "string"
               },
               {
                 "type": "null"
               }
             ],
-            "title": "Version Confirmation"
+            "title": "Description"
           },
-          "version_reason": {
+          "name": {
             "anyOf": [
               {
+                "maxLength": 50,
+                "minLength": 1,
                 "type": "string"
               },
               {
                 "type": "null"
               }
             ],
-            "title": "Version Reason"
+            "title": "Name"
           }
         },
-        "required": [
-          "filename",
-          "size_bytes",
-          "sha256",
-          "content_md5"
-        ],
-        "title": "UploadFileMetadata",
+        "title": "UpdateCollectionBody",
         "type": "object"
       },
-      "ValidationError": {
+      "UpdateDocumentBody": {
         "properties": {
-          "ctx": {
-            "title": "Context",
-            "type": "object"
-          },
-          "input": {
-            "title": "Input"
-          },
-          "loc": {
-            "items": {
-              "anyOf": [
-                {
+          "doc_version": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Doc Version"
+          },
+          "document_key": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Document Key"
+          },
+          "effective_date": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Effective Date"
+          },
+          "expiry_date": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Expiry Date"
+          },
+          "lifecycle_status": {
+            "anyOf": [
+              {
+                "enum": [
+                  "active",
+                  "superseded",
+                  "draft",
+                  "archived"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Lifecycle Status"
+          },
+          "metadata": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Metadata"
+          },
+          "permission_scope": {
+            "anyOf": [
+              {
+                "items": {
                   "type": "string"
                 },
-                {
-                  "type": "integer"
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Permission Scope"
+          },
+          "published_date": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Published Date"
+          },
+          "scope": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Scope"
+          },
+          "source_type": {
+            "anyOf": [
+              {
+                "enum": [
+                  "official_policy",
+                  "department_rule",
+                  "contract",
+                  "faq",
+                  "note",
+                  "unknown"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Source Type"
+          },
+          "title": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Title"
+          },
+          "version_sequence": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Version Sequence"
+          }
+        },
+        "title": "UpdateDocumentBody",
+        "type": "object"
+      },
+      "UploadFileMetadata": {
+        "additionalProperties": false,
+        "properties": {
+          "archive_category": {
+            "anyOf": [
+              {
+                "enum": [
+                  "final",
+                  "intermediate",
+                  "task_memory"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Archive Category"
+          },
+          "content_md5": {
+            "title": "Content Md5",
+            "type": "string"
+          },
+          "content_type": {
+            "default": "application/octet-stream",
+            "maxLength": 200,
+            "title": "Content Type",
+            "type": "string"
+          },
+          "duplicate_action": {
+            "default": "",
+            "enum": [
+              "",
+              "upload",
+              "new_version"
+            ],
+            "title": "Duplicate Action",
+            "type": "string"
+          },
+          "existing_document_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Existing Document Id"
+          },
+          "filename": {
+            "maxLength": 255,
+            "minLength": 1,
+            "title": "Filename",
+            "type": "string"
+          },
+          "relative_path": {
+            "anyOf": [
+              {
+                "maxLength": 1500,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Relative Path"
+          },
+          "sha256": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Sha256",
+            "type": "string"
+          },
+          "size_bytes": {
+            "exclusiveMinimum": 0.0,
+            "maximum": 104857600.0,
+            "title": "Size Bytes",
+            "type": "integer"
+          },
+          "task_id": {
+            "anyOf": [
+              {
+                "maxLength": 200,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Task Id"
+          },
+          "title": {
+            "anyOf": [
+              {
+                "maxLength": 500,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Title"
+          },
+          "version_confirmation": {
+            "anyOf": [
+              {
+                "const": "SWITCH_CURRENT_VERSION",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Version Confirmation"
+          },
+          "version_reason": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Version Reason"
+          }
+        },
+        "required": [
+          "filename",
+          "size_bytes",
+          "sha256",
+          "content_md5"
+        ],
+        "title": "UploadFileMetadata",
+        "type": "object"
+      },
+      "UploadPreflightBody": {
+        "additionalProperties": false,
+        "properties": {
+          "collection_id": {
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Collection Id",
+            "type": "string"
+          },
+          "files": {
+            "items": {
+              "$ref": "#/components/schemas/UploadFileMetadata"
+            },
+            "maxItems": 50,
+            "minItems": 1,
+            "title": "Files",
+            "type": "array"
+          }
+        },
+        "required": [
+          "collection_id",
+          "files"
+        ],
+        "title": "UploadPreflightBody",
+        "type": "object"
+      },
+      "ValidationError": {
+        "properties": {
+          "ctx": {
+            "title": "Context",
+            "type": "object"
+          },
+          "input": {
+            "title": "Input"
+          },
+          "loc": {
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "integer"
+                }
+              ]
+            },
+            "title": "Location",
+            "type": "array"
+          },
+          "msg": {
+            "title": "Message",
+            "type": "string"
+          },
+          "type": {
+            "title": "Error Type",
+            "type": "string"
+          }
+        },
+        "required": [
+          "loc",
+          "msg",
+          "type"
+        ],
+        "title": "ValidationError",
+        "type": "object"
+      }
+    }
+  },
+  "info": {
+    "title": "Knowledge Base Agent API",
+    "version": "0.1.0"
+  },
+  "openapi": "3.1.0",
+  "paths": {
+    "/api/v1/external/agent/archives/{archive_id}": {
+      "get": {
+        "description": "查询异步归档进度及完整归档回执。",
+        "operationId": "get_archive_status",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "archive_id",
+            "required": true,
+            "schema": {
+              "title": "Archive Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Get Archive Status",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Archive Status",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": true
+        }
+      }
+    },
+    "/api/v1/external/agent/archives/{archive_id}/retry": {
+      "post": {
+        "description": "重试异步归档任务中保留了源文件的失败项。",
+        "operationId": "retry_archive",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "archive_id",
+            "required": true,
+            "schema": {
+              "title": "Archive Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Retry Archive",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Retry Archive",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": true,
+          "idempotentHint": false,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      }
+    },
+    "/api/v1/external/agent/collections": {
+      "get": {
+        "description": "列出当前平台可用的知识库。\n\n返回知识库列表，包含 collection_id、名称、描述、文档数量等信息。\n建议在首次检索前先调用此工具，了解有哪些知识库可用。\n权限按知识库所有者、指定成员和“全体成员”授权实时计算。\n\nReturns:\n    JSON 对象，包含 collections 列表和 total 总数",
+        "operationId": "list_knowledge_bases",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response List Knowledge Bases",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "List Knowledge Bases",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": true
+        }
+      }
+    },
+    "/api/v1/external/agent/documents/{document_id}/download-ticket": {
+      "get": {
+        "description": "获取当前有权读取原件的短期下载链接。直连 OSS 时不要附加 KB 登录头。\n\nURL 是短期能力凭证，不应写入日志或长期保存；过期后重新调用本工具。",
+        "operationId": "get_document_download",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "document_id",
+            "required": true,
+            "schema": {
+              "title": "Document Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Get Document Download",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Document Download",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": true
+        }
+      }
+    },
+    "/api/v1/external/agent/search": {
+      "post": {
+        "description": "在企业知识库中检索文档片段。\n\n返回压缩后的 snippets / context / sources，可直接作为 LLM 上下文。\n普通问题优先使用 effective_date 最新、status=active 的片段；\n历史/旧版问题会自动包含 superseded 文档。\n\nArgs:\n    query: 检索关键词或自然语言问题（必填）\n    collection_id: 知识库 ID，默认 default\n    collection_ids: 多知识库检索列表（优先级高于 collection_id）\n    document_ids: 限定检索的文档 ID 列表\n    top_k: 返回片段数量，默认 5，最大 10\n    min_score: 最低相似度阈值 0-1，默认 0\n    role: 业务检索提示，不参与权限判断\n    employee_id: 业务检索提示，不参与权限判断\n    user_id: 业务检索提示，不参与权限判断\n    agent_id: 调用 Agent 标识，不参与权限判断\n    region: 业务范围 - 地区\n    product: 业务范围 - 产品\n    department: 业务范围 - 部门\n\nReturns:\n    JSON 对象，包含 query / snippets / context / sources / total / retrieval_mode；\n    sources 中包含可直接打开的短时 download_url",
+        "operationId": "search_knowledge_base",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Body_search_knowledge_base"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Search Knowledge Base",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Search Knowledge Base",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": true
+        }
+      }
+    },
+    "/api/v1/external/agent/task-collections": {
+      "post": {
+        "description": "为当前 WorkBuddy 任务创建一个独立知识空间。\n\n默认名称为“任务名-YYYYMMDD”，默认仅当前 API Key 所属用户可见。\n创建成功后，将返回的 collection_id 传给文件上传工具即可归档文件。\n\nArgs:\n    task_name: 当前任务名称，用于默认命名和归档追踪\n    visibility: 兼容旧客户端；private 或 shared，建议改用 all_members_role\n    archive_date: 归档日期，支持 YYYYMMDD 或 YYYY-MM-DD，默认当天\n    collection_name: 可选的自定义知识库名称，最长 50 字符\n    description: 可选描述，最长 200 字符\n    task_id: WorkBuddy 当前任务 ID，用于后续追踪和幂等治理\n    allow_contributor_uploads: 兼容旧客户端；建议改用 all_members_role\n    all_members_role: 全体成员角色，支持 viewer、contributor、manager；留空为私有\n\nReturns:\n    JSON 对象，包含 collection_id、名称、可见性和任务归档信息。",
+        "operationId": "create_task_knowledge_base",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Body_create_task_knowledge_base"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Create Task Knowledge Base",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Create Task Knowledge Base",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      }
+    },
+    "/api/v1/external/agent/upload-sessions": {
+      "post": {
+        "description": "创建可恢复的 OSS 直传会话。files 仅含文件名、大小、SHA256、Base64 MD5 等元数据。\n\n客户端使用返回 files[].upload 链接直接 PUT 文件，严格使用 required headers；\n不传 KB API Key，不把文件正文或 Base64 内容放入 MCP。上传后 complete_direct_upload。\n同一 request_id 必须对应相同文件内容及选项。链接不得日志输出或长期保存。",
+        "operationId": "begin_direct_upload",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Body_begin_direct_upload"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Begin Direct Upload",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Begin Direct Upload",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      }
+    },
+    "/api/v1/external/agent/upload-sessions/{session_id}": {
+      "delete": {
+        "description": "取消尚未提交的直传会话，服务端保留状态并安排无引用对象清理。",
+        "operationId": "cancel_direct_upload",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "session_id",
+            "required": true,
+            "schema": {
+              "title": "Session Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Cancel Direct Upload",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Cancel Direct Upload",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": true,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      },
+      "get": {
+        "description": "查询服务端保存的直传进度；renew=true 为尚未上传的对象重新签发短期链接。",
+        "operationId": "get_direct_upload",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "session_id",
+            "required": true,
+            "schema": {
+              "title": "Session Id",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "renew",
+            "required": false,
+            "schema": {
+              "default": false,
+              "title": "Renew",
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Get Direct Upload",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Direct Upload",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      }
+    },
+    "/api/v1/external/agent/upload-sessions/{session_id}/complete": {
+      "post": {
+        "description": "让服务端核对 OSS 对象并提交持久解析任务。可幂等重试，后台仍将核验完整 SHA256。",
+        "operationId": "complete_direct_upload",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "session_id",
+            "required": true,
+            "schema": {
+              "title": "Session Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Complete Direct Upload",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Complete Direct Upload",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": true,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      }
+    },
+    "/api/v1/external/batches/{batch_id}": {
+      "get": {
+        "operationId": "get_external_batch_api_v1_external_batches__batch_id__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "batch_id",
+            "required": true,
+            "schema": {
+              "title": "Batch Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Get External Batch Api V1 External Batches  Batch Id  Get",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get External Batch",
+        "tags": [
+          "external-interfaces"
+        ]
+      }
+    },
+    "/api/v1/external/batches/{batch_id}/resolve": {
+      "post": {
+        "description": "Resolve selected per-file conflicts and resume ready files.",
+        "operationId": "resolve_external_batch_conflicts_api_v1_external_batches__batch_id__resolve_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "batch_id",
+            "required": true,
+            "schema": {
+              "title": "Batch Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalBatchResolutionBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Resolve External Batch Conflicts Api V1 External Batches  Batch Id  Resolve Post",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Resolve External Batch Conflicts",
+        "tags": [
+          "external-interfaces"
+        ]
+      }
+    },
+    "/api/v1/external/batches/{batch_id}/retry": {
+      "post": {
+        "operationId": "retry_external_batch_api_v1_external_batches__batch_id__retry_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "batch_id",
+            "required": true,
+            "schema": {
+              "title": "Batch Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Retry External Batch Api V1 External Batches  Batch Id  Retry Post",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Retry External Batch",
+        "tags": [
+          "external-interfaces"
+        ]
+      }
+    },
+    "/api/v1/kb/batch/{batch_id}/cancel": {
+      "post": {
+        "operationId": "cancel_batch_api_v1_kb_batch__batch_id__cancel_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "batch_id",
+            "required": true,
+            "schema": {
+              "title": "Batch Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Cancel Batch",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/batches": {
+      "get": {
+        "description": "列出最近的批量上传任务。",
+        "operationId": "list_batches_api_v1_kb_batches_get",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 20,
+              "maximum": 100,
+              "minimum": 1,
+              "title": "Limit",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "offset",
+            "required": false,
+            "schema": {
+              "default": 0,
+              "minimum": 0,
+              "title": "Offset",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "collection_id",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Collection Id"
+            }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Status"
+            }
+          },
+          {
+            "in": "query",
+            "name": "include_files",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Include Files",
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "List Batches",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/chat/sessions": {
+      "get": {
+        "operationId": "get_chat_sessions_api_v1_kb_chat_sessions_get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Get Chat Sessions",
+        "tags": [
+          "knowledge-base"
+        ]
+      },
+      "post": {
+        "operationId": "create_rag_chat_session_api_v1_kb_chat_sessions_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChatSessionCreateBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Create Rag Chat Session",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/chat/sessions/{session_id}": {
+      "delete": {
+        "operationId": "delete_rag_chat_session_api_v1_kb_chat_sessions__session_id__delete",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "session_id",
+            "required": true,
+            "schema": {
+              "title": "Session Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Delete Rag Chat Session",
+        "tags": [
+          "knowledge-base"
+        ]
+      },
+      "get": {
+        "operationId": "get_rag_chat_session_api_v1_kb_chat_sessions__session_id__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "session_id",
+            "required": true,
+            "schema": {
+              "title": "Session Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Rag Chat Session",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/chat/stream": {
+      "post": {
+        "description": "RAG 知识库对话（流式 SSE）。\n\n    The first SSE event is: ``data: [META] <json with chunks & sources>\n\n``\n    Subsequent events are plain text chunks: ``data: <text>\n\n``",
+        "operationId": "chat_rag_stream_api_v1_kb_chat_stream_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChatRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Chat Rag Stream",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/collections/{collection_id}": {
+      "delete": {
+        "operationId": "delete_collection_api_v1_kb_collections__collection_id__delete",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Delete Collection",
+        "tags": [
+          "knowledge-base"
+        ]
+      },
+      "get": {
+        "operationId": "get_collection_api_v1_kb_collections__collection_id__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Collection",
+        "tags": [
+          "knowledge-base"
+        ]
+      },
+      "put": {
+        "operationId": "update_collection_api_v1_kb_collections__collection_id__put",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateCollectionBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Update Collection",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/collections/{collection_id}/members": {
+      "get": {
+        "operationId": "get_collection_members_api_v1_kb_collections__collection_id__members_get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Collection Members",
+        "tags": [
+          "knowledge-base"
+        ]
+      },
+      "put": {
+        "operationId": "save_collection_member_api_v1_kb_collections__collection_id__members_put",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CollectionMemberBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
                 }
-              ]
+              }
             },
-            "title": "Location",
-            "type": "array"
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Save Collection Member",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/collections/{collection_id}/members/{global_uid}": {
+      "delete": {
+        "operationId": "revoke_collection_member_api_v1_kb_collections__collection_id__members__global_uid__delete",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
           },
-          "msg": {
-            "title": "Message",
-            "type": "string"
+          {
+            "in": "path",
+            "name": "global_uid",
+            "required": true,
+            "schema": {
+              "title": "Global Uid",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Successful Response"
           },
-          "type": {
-            "title": "Error Type",
-            "type": "string"
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
           }
         },
-        "required": [
-          "loc",
-          "msg",
-          "type"
-        ],
-        "title": "ValidationError",
-        "type": "object"
+        "summary": "Revoke Collection Member",
+        "tags": [
+          "knowledge-base"
+        ]
       }
-    }
-  },
-  "info": {
-    "title": "Knowledge Base Agent API",
-    "version": "0.1.0"
-  },
-  "openapi": "3.1.0",
-  "paths": {
-    "/api/v1/external/agent/archives": {
+    },
+    "/api/v1/kb/collections/{collection_id}/transfer": {
       "post": {
-        "description": "持久化提交异步归档任务，适用于大文件或较多文件。request_id 用于幂等。",
-        "operationId": "start_async_archive",
+        "operationId": "transfer_collection_api_v1_kb_collections__collection_id__transfer_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "collection_id",
+            "required": true,
+            "schema": {
+              "title": "Collection Id",
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/Body_start_async_archive"
+                "$ref": "#/components/schemas/TransferCollectionBody"
               }
             }
           },
@@ -677,13 +2165,72 @@
         },
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
             "content": {
               "application/json": {
                 "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Start Async Archive",
-                  "type": "object"
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Transfer Collection",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/conflict-reviews": {
+      "get": {
+        "operationId": "list_conflict_reviews_api_v1_kb_conflict_reviews_get",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "collection_id",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Collection Id"
+            }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
                 }
+              ],
+              "title": "Status"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -699,42 +2246,159 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Start Async Archive",
+        "summary": "List Conflict Reviews",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": true,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
+          "knowledge-base"
+        ]
       }
     },
-    "/api/v1/external/agent/archives/{archive_id}": {
-      "get": {
-        "description": "查询异步归档进度及完整归档回执。",
-        "operationId": "get_archive_status",
+    "/api/v1/kb/conflict-reviews/{conflict_id}/resolve": {
+      "post": {
+        "operationId": "resolve_conflict_api_v1_kb_conflict_reviews__conflict_id__resolve_post",
         "parameters": [
           {
             "in": "path",
-            "name": "archive_id",
+            "name": "conflict_id",
             "required": true,
             "schema": {
-              "title": "Archive Id",
+              "title": "Conflict Id",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResolveConflictBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Resolve Conflict",
+        "tags": [
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/documents": {
+      "get": {
+        "operationId": "list_documents_api_v1_kb_documents_get",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "collection_id",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Collection Id"
+            }
+          },
+          {
+            "in": "query",
+            "name": "q",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Q"
+            }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Status"
+            }
+          },
+          {
+            "in": "query",
+            "name": "lifecycle_status",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Lifecycle Status"
+            }
+          },
+          {
+            "in": "query",
+            "name": "offset",
+            "required": false,
+            "schema": {
+              "default": 0,
+              "minimum": 0,
+              "title": "Offset",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 100,
+              "maximum": 500,
+              "minimum": 1,
+              "title": "Limit",
+              "type": "integer"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Get Archive Status",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -750,44 +2414,28 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Get Archive Status",
+        "summary": "List Documents",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": true
-        }
+          "knowledge-base"
+        ]
       }
     },
-    "/api/v1/external/agent/archives/{archive_id}/retry": {
-      "post": {
-        "description": "重试异步归档任务中保留了源文件的失败项。",
-        "operationId": "retry_archive",
+    "/api/v1/kb/documents/{document_id}": {
+      "delete": {
+        "operationId": "delete_document_api_v1_kb_documents__document_id__delete",
         "parameters": [
           {
             "in": "path",
-            "name": "archive_id",
+            "name": "document_id",
             "required": true,
             "schema": {
-              "title": "Archive Id",
+              "title": "Document Id",
               "type": "string"
             }
           }
         ],
         "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Retry Archive",
-                  "type": "object"
-                }
-              }
-            },
+          "204": {
             "description": "Successful Response"
           },
           "422": {
@@ -801,52 +2449,13 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Retry Archive",
-        "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": true,
-          "idempotentHint": false,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
-      }
-    },
-    "/api/v1/external/agent/collections": {
-      "get": {
-        "description": "列出当前平台可用的知识库。\n\n返回知识库列表，包含 collection_id、名称、描述、文档数量等信息。\n建议在首次检索前先调用此工具，了解有哪些知识库可用。\n权限按知识库所有者、指定成员和“全体成员”授权实时计算。\n\nReturns:\n    JSON 对象，包含 collections 列表和 total 总数",
-        "operationId": "list_knowledge_bases",
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response List Knowledge Bases",
-                  "type": "object"
-                }
-              }
-            },
-            "description": "Successful Response"
-          }
-        },
-        "summary": "List Knowledge Bases",
+        "summary": "Delete Document",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": true
-        }
-      }
-    },
-    "/api/v1/external/agent/documents/{document_id}/download-ticket": {
+          "knowledge-base"
+        ]
+      },
       "get": {
-        "description": "获取当前有权读取原件的短期下载链接。直连 OSS 时不要附加 KB 登录头。\n\nURL 是短期能力凭证，不应写入日志或长期保存；过期后重新调用本工具。",
-        "operationId": "get_document_download",
+        "operationId": "get_document_api_v1_kb_documents__document_id__get",
         "parameters": [
           {
             "in": "path",
@@ -856,17 +2465,89 @@
               "title": "Document Id",
               "type": "string"
             }
+          },
+          {
+            "in": "query",
+            "name": "include_content",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Include Content",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "include_chunks",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Include Chunks",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "include_assets",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Include Assets",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "chunk_offset",
+            "required": false,
+            "schema": {
+              "default": 0,
+              "minimum": 0,
+              "title": "Chunk Offset",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "chunk_limit",
+            "required": false,
+            "schema": {
+              "default": 100,
+              "maximum": 500,
+              "minimum": 1,
+              "title": "Chunk Limit",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "asset_offset",
+            "required": false,
+            "schema": {
+              "default": 0,
+              "minimum": 0,
+              "title": "Asset Offset",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "asset_limit",
+            "required": false,
+            "schema": {
+              "default": 100,
+              "maximum": 500,
+              "minimum": 1,
+              "title": "Asset Limit",
+              "type": "integer"
+            }
           }
         ],
         "responses": {
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Get Document Download",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -882,27 +2563,29 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Get Document Download",
+        "summary": "Get Document",
         "tags": [
-          "agent-tools"
+          "knowledge-base"
+        ]
+      },
+      "put": {
+        "operationId": "update_document_api_v1_kb_documents__document_id__put",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "document_id",
+            "required": true,
+            "schema": {
+              "title": "Document Id",
+              "type": "string"
+            }
+          }
         ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": true
-        }
-      }
-    },
-    "/api/v1/external/agent/search": {
-      "post": {
-        "description": "在企业知识库中检索文档片段。\n\n返回压缩后的 snippets / context / sources，可直接作为 LLM 上下文。\n普通问题优先使用 effective_date 最新、status=active 的片段；\n历史/旧版问题会自动包含 superseded 文档。\n\nArgs:\n    query: 检索关键词或自然语言问题（必填）\n    collection_id: 知识库 ID，默认 default\n    collection_ids: 多知识库检索列表（优先级高于 collection_id）\n    document_ids: 限定检索的文档 ID 列表\n    top_k: 返回片段数量，默认 5，最大 10\n    min_score: 最低相似度阈值 0-1，默认 0\n    role: 业务检索提示，不参与权限判断\n    employee_id: 业务检索提示，不参与权限判断\n    user_id: 业务检索提示，不参与权限判断\n    agent_id: 调用 Agent 标识，不参与权限判断\n    region: 业务范围 - 地区\n    product: 业务范围 - 产品\n    department: 业务范围 - 部门\n\nReturns:\n    JSON 对象，包含 query / snippets / context / sources / total / retrieval_mode；\n    sources 中包含可直接打开的短时 download_url",
-        "operationId": "search_knowledge_base",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/Body_search_knowledge_base"
+                "$ref": "#/components/schemas/UpdateDocumentBody"
               }
             }
           },
@@ -912,11 +2595,7 @@
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Search Knowledge Base",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -932,91 +2611,54 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Search Knowledge Base",
+        "summary": "Update Document",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": true
-        }
+          "knowledge-base"
+        ]
       }
     },
-    "/api/v1/external/agent/task-collections": {
-      "post": {
-        "description": "为当前 WorkBuddy 任务创建一个独立知识空间。\n\n默认名称为“任务名-YYYYMMDD”，默认仅当前 API Key 所属用户可见。\n创建成功后，将返回的 collection_id 传给文件上传工具即可归档文件。\n\nArgs:\n    task_name: 当前任务名称，用于默认命名和归档追踪\n    visibility: 兼容旧客户端；private 或 shared，建议改用 all_members_role\n    archive_date: 归档日期，支持 YYYYMMDD 或 YYYY-MM-DD，默认当天\n    collection_name: 可选的自定义知识库名称，最长 50 字符\n    description: 可选描述，最长 200 字符\n    task_id: WorkBuddy 当前任务 ID，用于后续追踪和幂等治理\n    allow_contributor_uploads: 兼容旧客户端；建议改用 all_members_role\n    all_members_role: 全体成员角色，支持 viewer、contributor、manager；留空为私有\n\nReturns:\n    JSON 对象，包含 collection_id、名称、可见性和任务归档信息。",
-        "operationId": "create_task_knowledge_base",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/Body_create_task_knowledge_base"
-              }
+    "/api/v1/kb/documents/{document_id}/assets": {
+      "get": {
+        "operationId": "list_document_assets_api_v1_kb_documents__document_id__assets_get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "document_id",
+            "required": true,
+            "schema": {
+              "title": "Document Id",
+              "type": "string"
             }
           },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Create Task Knowledge Base",
-                  "type": "object"
-                }
-              }
-            },
-            "description": "Successful Response"
+          {
+            "in": "query",
+            "name": "offset",
+            "required": false,
+            "schema": {
+              "default": 0,
+              "minimum": 0,
+              "title": "Offset",
+              "type": "integer"
+            }
           },
-          "422": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/HTTPValidationError"
-                }
-              }
-            },
-            "description": "Validation Error"
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 24,
+              "maximum": 200,
+              "minimum": 1,
+              "title": "Limit",
+              "type": "integer"
+            }
           }
-        },
-        "summary": "Create Task Knowledge Base",
-        "tags": [
-          "agent-tools"
         ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": false,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
-      }
-    },
-    "/api/v1/external/agent/upload-sessions": {
-      "post": {
-        "description": "创建可恢复的 OSS 直传会话。files 仅含文件名、大小、SHA256、Base64 MD5 等元数据。\n\n客户端使用返回 files[].upload 链接直接 PUT 文件，严格使用 required headers；\n不传 KB API Key，不把文件正文或 Base64 内容放入 MCP。上传后 complete_direct_upload。\n同一 request_id 必须对应相同文件内容及选项。链接不得日志输出或长期保存。",
-        "operationId": "begin_direct_upload",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/Body_begin_direct_upload"
-              }
-            }
-          },
-          "required": true
-        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Begin Direct Upload",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1032,29 +2674,22 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Begin Direct Upload",
+        "summary": "List Document Assets",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
+          "knowledge-base"
+        ]
       }
     },
-    "/api/v1/external/agent/upload-sessions/{session_id}": {
-      "delete": {
-        "description": "取消尚未提交的直传会话，服务端保留状态并安排无引用对象清理。",
-        "operationId": "cancel_direct_upload",
+    "/api/v1/kb/documents/{document_id}/change-history": {
+      "get": {
+        "operationId": "get_document_change_history_api_v1_kb_documents__document_id__change_history_get",
         "parameters": [
           {
             "in": "path",
-            "name": "session_id",
+            "name": "document_id",
             "required": true,
             "schema": {
-              "title": "Session Id",
+              "title": "Document Id",
               "type": "string"
             }
           }
@@ -1063,11 +2698,7 @@
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Cancel Direct Upload",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1083,38 +2714,46 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Cancel Direct Upload",
+        "summary": "Get Document Change History",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": true,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
-      },
+          "knowledge-base"
+        ]
+      }
+    },
+    "/api/v1/kb/documents/{document_id}/chunks": {
       "get": {
-        "description": "查询服务端保存的直传进度；renew=true 为尚未上传的对象重新签发短期链接。",
-        "operationId": "get_direct_upload",
+        "operationId": "list_document_chunks_api_v1_kb_documents__document_id__chunks_get",
         "parameters": [
           {
             "in": "path",
-            "name": "session_id",
+            "name": "document_id",
             "required": true,
             "schema": {
-              "title": "Session Id",
+              "title": "Document Id",
               "type": "string"
             }
           },
           {
             "in": "query",
-            "name": "renew",
+            "name": "offset",
             "required": false,
             "schema": {
-              "default": false,
-              "title": "Renew",
-              "type": "boolean"
+              "default": 0,
+              "minimum": 0,
+              "title": "Offset",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 50,
+              "maximum": 500,
+              "minimum": 1,
+              "title": "Limit",
+              "type": "integer"
             }
           }
         ],
@@ -1122,11 +2761,7 @@
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Get Direct Upload",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1142,29 +2777,22 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Get Direct Upload",
+        "summary": "List Document Chunks",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": false,
-          "idempotentHint": false,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
+          "knowledge-base"
+        ]
       }
     },
-    "/api/v1/external/agent/upload-sessions/{session_id}/complete": {
+    "/api/v1/kb/documents/{document_id}/reindex": {
       "post": {
-        "description": "让服务端核对 OSS 对象并提交持久解析任务。可幂等重试，后台仍将核验完整 SHA256。",
-        "operationId": "complete_direct_upload",
+        "operationId": "reindex_document_api_v1_kb_documents__document_id__reindex_post",
         "parameters": [
           {
             "in": "path",
-            "name": "session_id",
+            "name": "document_id",
             "required": true,
             "schema": {
-              "title": "Session Id",
+              "title": "Document Id",
               "type": "string"
             }
           }
@@ -1173,11 +2801,7 @@
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Complete Direct Upload",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1193,41 +2817,41 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Complete Direct Upload",
+        "summary": "Reindex Document",
         "tags": [
-          "agent-tools"
-        ],
-        "x-mcp-annotations": {
-          "destructiveHint": true,
-          "idempotentHint": true,
-          "openWorldHint": true,
-          "readOnlyHint": false
-        }
+          "knowledge-base"
+        ]
       }
     },
-    "/api/v1/external/batches/{batch_id}": {
-      "get": {
-        "operationId": "get_external_batch_api_v1_external_batches__batch_id__get",
+    "/api/v1/kb/documents/{document_id}/switch-version": {
+      "post": {
+        "operationId": "switch_document_version_api_v1_kb_documents__document_id__switch_version_post",
         "parameters": [
           {
             "in": "path",
-            "name": "batch_id",
+            "name": "document_id",
             "required": true,
             "schema": {
-              "title": "Batch Id",
+              "title": "Document Id",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SwitchDocumentVersionBody"
+              }
+            }
+          },
+          "required": true
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Get External Batch Api V1 External Batches  Batch Id  Get",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1243,46 +2867,31 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Get External Batch",
+        "summary": "Switch Document Version",
         "tags": [
-          "external-interfaces"
+          "knowledge-base"
         ]
       }
     },
-    "/api/v1/external/batches/{batch_id}/resolve": {
-      "post": {
-        "description": "Resolve selected per-file conflicts and resume ready files.",
-        "operationId": "resolve_external_batch_conflicts_api_v1_external_batches__batch_id__resolve_post",
+    "/api/v1/kb/documents/{document_id}/versions": {
+      "get": {
+        "operationId": "get_document_versions_api_v1_kb_documents__document_id__versions_get",
         "parameters": [
           {
             "in": "path",
-            "name": "batch_id",
+            "name": "document_id",
             "required": true,
             "schema": {
-              "title": "Batch Id",
+              "title": "Document Id",
               "type": "string"
             }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/ExternalBatchResolutionBody"
-              }
-            }
-          },
-          "required": true
-        },
         "responses": {
-          "202": {
+          "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Resolve External Batch Conflicts Api V1 External Batches  Batch Id  Resolve Post",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1298,35 +2907,76 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Resolve External Batch Conflicts",
+        "summary": "Get Document Versions",
         "tags": [
-          "external-interfaces"
+          "knowledge-base"
         ]
       }
     },
-    "/api/v1/external/batches/{batch_id}/retry": {
-      "post": {
-        "operationId": "retry_external_batch_api_v1_external_batches__batch_id__retry_post",
+    "/api/v1/kb/ingest-jobs": {
+      "get": {
+        "operationId": "list_ingest_jobs_api_v1_kb_ingest_jobs_get",
         "parameters": [
           {
-            "in": "path",
-            "name": "batch_id",
-            "required": true,
+            "in": "query",
+            "name": "document_id",
+            "required": false,
             "schema": {
-              "title": "Batch Id",
-              "type": "string"
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Document Id"
+            }
+          },
+          {
+            "in": "query",
+            "name": "collection_id",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Collection Id"
+            }
+          },
+          {
+            "in": "query",
+            "name": "include_completed",
+            "required": false,
+            "schema": {
+              "default": false,
+              "title": "Include Completed",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 20,
+              "maximum": 200,
+              "minimum": 1,
+              "title": "Limit",
+              "type": "integer"
             }
           }
         ],
         "responses": {
-          "202": {
+          "200": {
             "content": {
               "application/json": {
-                "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Retry External Batch Api V1 External Batches  Batch Id  Retry Post",
-                  "type": "object"
-                }
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1342,35 +2992,114 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Retry External Batch",
+        "summary": "List Ingest Jobs",
         "tags": [
-          "external-interfaces"
+          "knowledge-base"
         ]
       }
     },
-    "/api/v1/external/documents/batch-upload": {
+    "/api/v1/kb/upload-sessions/preflight": {
       "post": {
-        "description": "Submit binary files for asynchronous ingestion using API-Key auth.\n\n``detect`` resolves exact duplicate content as reuse, treats an exact\nfilename with changed content as a new version when safe, and holds only\nambiguous files for per-file resolution. ``reject`` refuses the entire batch\nwhen filename preflight requires confirmation, without reusing or replacing\nexisting documents; it is the conservative direct-upload fallback policy.\n``force_upload`` deliberately\nskips those checks and is restricted to a collection owner/manager.\nRequest IDs are scoped to the API-Key owner and make retries idempotent.",
-        "operationId": "upload_external_documents_api_v1_external_documents_batch_upload_post",
+        "operationId": "upload_preflight_api_v1_kb_upload_sessions_preflight_post",
         "requestBody": {
           "content": {
-            "multipart/form-data": {
+            "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/Body_upload_external_documents_api_v1_external_documents_batch_upload_post"
+                "$ref": "#/components/schemas/UploadPreflightBody"
               }
             }
           },
           "required": true
         },
         "responses": {
-          "202": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
             "content": {
               "application/json": {
                 "schema": {
-                  "additionalProperties": true,
-                  "title": "Response Upload External Documents Api V1 External Documents Batch Upload Post",
-                  "type": "object"
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Upload Preflight",
+        "tags": [
+          "file-transfers"
+        ]
+      }
+    },
+    "/api/v1/kb/users/search": {
+      "get": {
+        "description": "Search the upstream directory without exposing its full PII payload.",
+        "operationId": "search_permission_users_api_v1_kb_users_search_get",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "collection_id",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                {
+                  "type": "null"
                 }
+              ],
+              "title": "Collection Id"
+            }
+          },
+          {
+            "in": "query",
+            "name": "q",
+            "required": false,
+            "schema": {
+              "default": "",
+              "maxLength": 100,
+              "title": "Q",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "offset",
+            "required": false,
+            "schema": {
+              "default": 0,
+              "minimum": 0,
+              "title": "Offset",
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 20,
+              "maximum": 50,
+              "minimum": 1,
+              "title": "Limit",
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
               }
             },
             "description": "Successful Response"
@@ -1386,15 +3115,15 @@
             "description": "Validation Error"
           }
         },
-        "summary": "Upload External Documents",
+        "summary": "Search Permission Users",
         "tags": [
-          "external-interfaces"
+          "knowledge-base"
         ]
       }
     }
   },
   "x-numa-contract": {
-    "authentication": "X-Api-Key; deployments may additionally require Bearer application authorization.",
+    "authentication": "Keycloak Bearer JWT for native KB routes; legacy Agent API deployments may also support X-Api-Key.",
     "default_upload_limits": {
       "max_external_files_per_batch": 100,
       "max_files_per_batch": 50,
@@ -1426,7 +3155,9 @@
     "response_validation": "Responses are free-form upstream; validate consumed fields at runtime.",
     "sources": [
       "backend/external/agent_routes.py",
-      "backend/external/routes.py"
+      "backend/external/routes.py",
+      "backend/routes/knowledge_base.py",
+      "backend/routes/direct_uploads.py"
     ]
   }
 }