@numa-tech/numa 1.20.3 → 1.20.5

package/src/kb/openapi-contract.json

@@ -0,0 +1,1432 @@
+{
+  "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"
+          },
+          "files": {
+            "items": {
+              "$ref": "#/components/schemas/UploadFileMetadata"
+            },
+            "title": "Files",
+            "type": "array"
+          },
+          "options": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Options"
+          },
+          "request_id": {
+            "title": "Request Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "files",
+          "request_id"
+        ],
+        "title": "Body_begin_direct_upload",
+        "type": "object"
+      },
+      "Body_create_task_knowledge_base": {
+        "properties": {
+          "all_members_role": {
+            "anyOf": [
+              {
+                "enum": [
+                  "viewer",
+                  "contributor",
+                  "manager"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "All Members Role"
+          },
+          "allow_contributor_uploads": {
+            "default": false,
+            "title": "Allow Contributor Uploads",
+            "type": "boolean"
+          },
+          "archive_date": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Archive Date"
+          },
+          "collection_name": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Collection Name"
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Description"
+          },
+          "task_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Task Id"
+          },
+          "task_name": {
+            "title": "Task Name",
+            "type": "string"
+          },
+          "visibility": {
+            "default": "private",
+            "enum": [
+              "private",
+              "shared"
+            ],
+            "title": "Visibility",
+            "type": "string"
+          }
+        },
+        "required": [
+          "task_name"
+        ],
+        "title": "Body_create_task_knowledge_base",
+        "type": "object"
+      },
+      "Body_search_knowledge_base": {
+        "properties": {
+          "agent_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Agent Id"
+          },
+          "collection_id": {
+            "default": "default",
+            "title": "Collection Id",
+            "type": "string"
+          },
+          "collection_ids": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Collection Ids"
+          },
+          "department": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Department"
+          },
+          "document_ids": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Document Ids"
+          },
+          "employee_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Employee Id"
+          },
+          "min_score": {
+            "default": 0.0,
+            "maximum": 1.0,
+            "minimum": 0.0,
+            "title": "Min Score",
+            "type": "number"
+          },
+          "product": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Product"
+          },
+          "query": {
+            "title": "Query",
+            "type": "string"
+          },
+          "region": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Region"
+          },
+          "role": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Role"
+          },
+          "top_k": {
+            "default": 5,
+            "maximum": 10.0,
+            "minimum": 1.0,
+            "title": "Top K",
+            "type": "integer"
+          },
+          "user_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "User Id"
+          }
+        },
+        "required": [
+          "query"
+        ],
+        "title": "Body_search_knowledge_base",
+        "type": "object"
+      },
+      "Body_start_async_archive": {
+        "properties": {
+          "collection_id": {
+            "default": "default",
+            "title": "Collection Id",
+            "type": "string"
+          },
+          "files": {
+            "items": {
+              "$ref": "#/components/schemas/ArchiveFile"
+            },
+            "title": "Files",
+            "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": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Duplicate Resolutions Json"
+          },
+          "files": {
+            "items": {
+              "contentMediaType": "application/octet-stream",
+              "type": "string"
+            },
+            "title": "Files",
+            "type": "array"
+          },
+          "relative_paths_json": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Relative Paths Json"
+          },
+          "request_id": {
+            "title": "Request Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "files",
+          "request_id"
+        ],
+        "title": "Body_upload_external_documents_api_v1_external_documents_batch_upload_post",
+        "type": "object"
+      },
+      "ExternalBatchResolutionBody": {
+        "properties": {
+          "resolutions": {
+            "items": {
+              "$ref": "#/components/schemas/ExternalFileResolution"
+            },
+            "title": "Resolutions",
+            "type": "array"
+          }
+        },
+        "required": [
+          "resolutions"
+        ],
+        "title": "ExternalBatchResolutionBody",
+        "type": "object"
+      },
+      "ExternalFileResolution": {
+        "properties": {
+          "action": {
+            "enum": [
+              "upload",
+              "new_version",
+              "skip"
+            ],
+            "title": "Action",
+            "type": "string"
+          },
+          "confirmation": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Confirmation"
+          },
+          "existing_document_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Existing Document Id"
+          },
+          "file_id": {
+            "title": "File Id",
+            "type": "string"
+          },
+          "reason": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Reason"
+          }
+        },
+        "required": [
+          "file_id",
+          "action"
+        ],
+        "title": "ExternalFileResolution",
+        "type": "object"
+      },
+      "HTTPValidationError": {
+        "properties": {
+          "detail": {
+            "items": {
+              "$ref": "#/components/schemas/ValidationError"
+            },
+            "title": "Detail",
+            "type": "array"
+          }
+        },
+        "title": "HTTPValidationError",
+        "type": "object"
+      },
+      "UploadFileMetadata": {
+        "additionalProperties": false,
+        "properties": {
+          "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"
+          },
+          "sha256": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Sha256",
+            "type": "string"
+          },
+          "size_bytes": {
+            "exclusiveMinimum": 0.0,
+            "maximum": 104857600.0,
+            "title": "Size Bytes",
+            "type": "integer"
+          },
+          "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"
+      },
+      "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": {
+      "post": {
+        "description": "持久化提交异步归档任务，适用于大文件或较多文件。request_id 用于幂等。",
+        "operationId": "start_async_archive",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Body_start_async_archive"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Start Async Archive",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Start Async Archive",
+        "tags": [
+          "agent-tools"
+        ],
+        "x-mcp-annotations": {
+          "destructiveHint": true,
+          "idempotentHint": true,
+          "openWorldHint": true,
+          "readOnlyHint": false
+        }
+      }
+    },
+    "/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/external/documents/batch-upload": {
+      "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",
+        "requestBody": {
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/Body_upload_external_documents_api_v1_external_documents_batch_upload_post"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Upload External Documents Api V1 External Documents Batch Upload Post",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Upload External Documents",
+        "tags": [
+          "external-interfaces"
+        ]
+      }
+    }
+  },
+  "x-numa-contract": {
+    "authentication": "X-Api-Key; deployments may additionally require Bearer application authorization.",
+    "default_upload_limits": {
+      "max_external_files_per_batch": 100,
+      "max_files_per_batch": 50,
+      "max_files_per_batch_environment_override": "KB_MAX_FILES_PER_BATCH",
+      "max_single_file_size_bytes": 104857600,
+      "max_total_batch_size_bytes": 1073741824
+    },
+    "generator": "scripts/export-kb-contract.py",
+    "parse_supported_extensions": [
+      ".bmp",
+      ".csv",
+      ".docx",
+      ".gif",
+      ".jpeg",
+      ".jpg",
+      ".json",
+      ".log",
+      ".md",
+      ".pdf",
+      ".png",
+      ".txt",
+      ".webp",
+      ".xls",
+      ".xlsm",
+      ".xlsx",
+      ".yaml",
+      ".yml"
+    ],
+    "response_validation": "Responses are free-form upstream; validate consumed fields at runtime.",
+    "sources": [
+      "backend/external/agent_routes.py",
+      "backend/external/routes.py"
+    ]
+  }
+}