@dxpos/knowledge 0.11.0 → 0.12.0

package/dist/generated/sdk.gen.js

@@ -21,6 +21,8 @@ export const deleteApiFiles = (options) => (options.client ?? client).delete({
 });
 /**
  * 列出文件
+ *
+ * 按创建时间倒序分页返回。q 分词后匹配文件名，命中词在 filenameSnippet 中高亮。
  */
 export const getApiFiles = (options) => (options?.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -34,7 +36,7 @@ export const getApiFiles = (options) => (options?.client ?? client).get({
 /**
  * 服务端直传文件
  *
- * 需编辑者及以上。
+ * 需编辑者及以上。multipart 上传一个或多个文件，逐个返回结果，部分失败不影响其余文件。
  */
 export const postApiFiles = (options) => (options.client ?? client).post({
     ...formDataBodySerializer,
@@ -53,7 +55,7 @@ export const postApiFiles = (options) => (options.client ?? client).post({
 /**
  * 预签名直传
  *
- * 需编辑者及以上。返回对象存储 PUT 地址。
+ * 需编辑者及以上。为每个文件创建 pending 记录并返回对象存储 PUT 地址；客户端上传完成后需调用 /api/files/complete 确认。
  */
 export const postApiFilesPresign = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -71,7 +73,7 @@ export const postApiFilesPresign = (options) => (options.client ?? client).post(
 /**
  * 确认预签名上传完成
  *
- * 需编辑者及以上。
+ * 需编辑者及以上。检查对象是否已上传，存在则标记为 ready，否则标记为 failed。
  */
 export const postApiFilesComplete = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -107,7 +109,7 @@ export const postApiFilesCleanup = (options) => (options.client ?? client).post(
 /**
  * 删除文件
  *
- * 需管理员及以上。force=true 时坚持删除被引用文件。
+ * 需管理员及以上。未传 force 时若仍被引用则返回 409 与引用列表；force=true 时坚持删除被引用文件。
  */
 export const deleteApiFilesById = (options) => (options.client ?? client).delete({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -120,6 +122,8 @@ export const deleteApiFilesById = (options) => (options.client ?? client).delete
 });
 /**
  * 获取文件元数据
+ *
+ * 不存在时返回 404。
  */
 export const getApiFilesById = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -132,6 +136,8 @@ export const getApiFilesById = (options) => (options.client ?? client).get({
 });
 /**
  * 读取文件原始内容
+ *
+ * 以文件 MIME 返回二进制流，可长期缓存。文件不存在返回 404，尚未就绪返回 400。
  */
 export const getApiFilesByIdRaw = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -144,6 +150,8 @@ export const getApiFilesByIdRaw = (options) => (options.client ?? client).get({
 });
 /**
  * 获取文件下载地址
+ *
+ * 知识库文档图片（scope=knowledge）返回长期有效的公开地址，其余返回带有效期的预签名地址。文件不存在返回 404，尚未就绪返回 400。
  */
 export const getApiFilesByIdUrl = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -155,9 +163,9 @@ export const getApiFilesByIdUrl = (options) => (options.client ?? client).get({
     ...options
 });
 /**
- * RAG 问答
+ * 问答
  *
- * stream 默认 true，返回 NDJSON 事件流：token / node / references / done / error。stream=false 时返回 JSON 信封，data 为完整回答与引用。attachments 为已上传的对话图片 fileId，实际上限由配置决定，默认 4。content 与 attachments 至少传一项。排队已满或等待超时时返回 429，响应头带 Retry-After。
+ * stream 默认 true，返回 NDJSON 事件流：route / token / node / references / done / error。stream=false 时返回 JSON 信封，data 为完整回答与引用。会话绑定智能路由且尚未绑定助手时，首问会先分析意图并绑定助手，流式返回 route 事件（ragId / ragName），非流式在 data.route 返回；其余情况 data.route 为 null。attachments 为已上传的对话图片 fileId，实际上限由配置决定，默认 4。content 与 attachments 至少传一项。排队已满或等待超时时返回 429，响应头带 Retry-After。
  */
 export const postApiChat = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -173,9 +181,9 @@ export const postApiChat = (options) => (options.client ?? client).post({
     }
 });
 /**
- * 读取会话生效的图片限制与欢迎语
+ * 获取会话配置
  *
- * 按 RAG 配置 > 全局 > 代码默认合并图片数量上限与压缩最长边；并返回生效的欢迎语与推荐问题（RAG > 全局）。
+ * 返回会话生效的图片限制、欢迎语与推荐问题，优先级为问答助手 > 全局 > 默认值。
  */
 export const getApiChatLimits = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -189,7 +197,7 @@ export const getApiChatLimits = (options) => (options.client ?? client).get({
 /**
  * 列出会话
  *
- * 管理员可传 userId 查看指定用户会话；ragId 可按 RAG 过滤。
+ * 按创建时间倒序返回。编辑者及以下仅返回自己的会话；管理员及以上默认返回全部会话，可传 userId 查看指定用户会话。ragId 可按问答助手过滤，routerId 可按智能路由过滤。
  */
 export const getApiChatConversations = (options) => (options?.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -202,6 +210,8 @@ export const getApiChatConversations = (options) => (options?.client ?? client).
 });
 /**
  * 创建会话
+ *
+ * ragId / mark 直接绑定问答助手；routerId / routerMark 绑定智能路由，ragId 暂为 null，首次问答时按意图自动绑定问答助手，之后固定使用该助手。两组参数必须且只能传一组。
  */
 export const postApiChatConversations = (options) => (options?.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -218,6 +228,8 @@ export const postApiChatConversations = (options) => (options?.client ?? client)
 });
 /**
  * 删除会话
+ *
+ * 连同消息一并删除。编辑者及以下仅能删除自己的会话，否则返回 404。
  */
 export const deleteApiChatConversationsById = (options) => (options.client ?? client).delete({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -230,6 +242,8 @@ export const deleteApiChatConversationsById = (options) => (options.client ?? cl
 });
 /**
  * 获取会话与消息
+ *
+ * 返回会话及其全部消息，消息图片会回填当前有效的下载地址。编辑者及以下仅能访问自己的会话，否则返回 404。
  */
 export const getApiChatConversationsById = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -243,7 +257,7 @@ export const getApiChatConversationsById = (options) => (options.client ?? clien
 /**
  * 更新会话
  *
- * 需编辑者及以上。
+ * 需编辑者及以上。仅支持修改标题，title 为空时保持原标题。
  */
 export const patchApiChatConversationsById = (options) => (options.client ?? client).patch({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -258,6 +272,84 @@ export const patchApiChatConversationsById = (options) => (options.client ?? cli
         ...options.headers
     }
 });
+/**
+ * 列出智能路由
+ *
+ * 返回全部智能路由及其候选问答助手配置。
+ */
+export const getApiChatRouters = (options) => (options?.client ?? client).get({
+    security: [{ scheme: 'bearer', type: 'http' }, {
+            in: 'cookie',
+            name: 'authjs.session-token',
+            type: 'apiKey'
+        }],
+    url: '/api/chat/routers',
+    ...options
+});
+/**
+ * 创建智能路由
+ *
+ * 需编辑者及以上。routes 为候选问答助手，不能重复，intent 为空时取问答助手描述作为意图描述；未命中任何候选时路由到 fallbackRagId。intentPrompt 为空使用默认提示词，自定义时必须包含 {{assistants}} 变量，模型需只输出命中助手的 id。textProviderId 与 textModel 需同时填写，为空使用全局文本模型。mark 重复时返回 400。
+ */
+export const postApiChatRouters = (options) => (options.client ?? client).post({
+    security: [{ scheme: 'bearer', type: 'http' }, {
+            in: 'cookie',
+            name: 'authjs.session-token',
+            type: 'apiKey'
+        }],
+    url: '/api/chat/routers',
+    ...options,
+    headers: {
+        'Content-Type': 'application/json',
+        ...options.headers
+    }
+});
+/**
+ * 删除智能路由
+ *
+ * 需编辑者及以上。已绑定问答助手的会话保留助手，routerId 置空。
+ */
+export const deleteApiChatRoutersById = (options) => (options.client ?? client).delete({
+    security: [{ scheme: 'bearer', type: 'http' }, {
+            in: 'cookie',
+            name: 'authjs.session-token',
+            type: 'apiKey'
+        }],
+    url: '/api/chat/routers/{id}',
+    ...options
+});
+/**
+ * 获取智能路由
+ *
+ * 不存在时返回 404。
+ */
+export const getApiChatRoutersById = (options) => (options.client ?? client).get({
+    security: [{ scheme: 'bearer', type: 'http' }, {
+            in: 'cookie',
+            name: 'authjs.session-token',
+            type: 'apiKey'
+        }],
+    url: '/api/chat/routers/{id}',
+    ...options
+});
+/**
+ * 更新智能路由
+ *
+ * 需编辑者及以上。仅更新传入字段，校验规则同创建。已绑定问答助手的会话不受影响。
+ */
+export const patchApiChatRoutersById = (options) => (options.client ?? client).patch({
+    security: [{ scheme: 'bearer', type: 'http' }, {
+            in: 'cookie',
+            name: 'authjs.session-token',
+            type: 'apiKey'
+        }],
+    url: '/api/chat/routers/{id}',
+    ...options,
+    headers: {
+        'Content-Type': 'application/json',
+        ...options.headers
+    }
+});
 /**
  * 关键词检索文档
  *
@@ -274,6 +366,8 @@ export const getApiSearch = (options) => (options.client ?? client).get({
 });
 /**
  * 上报检索结果点击
+ *
+ * 记录检索词与被点击文档，用于检索效果统计。
  */
 export const postApiSearchClick = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -305,7 +399,7 @@ export const getApiKnowledgeBases = (options) => (options?.client ?? client).get
 /**
  * 创建知识库
  *
- * 需编辑者及以上。mark 为知识库唯一标识，不可包含逗号。
+ * 需编辑者及以上。mark 为知识库唯一标识，不可包含逗号。分块参数为空时继承全局默认。
  */
 export const postApiKnowledgeBases = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -336,6 +430,8 @@ export const deleteApiKnowledgeBasesById = (options) => (options.client ?? clien
 });
 /**
  * 获取知识库
+ *
+ * 不存在时返回 404。
  */
 export const getApiKnowledgeBasesById = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -349,7 +445,7 @@ export const getApiKnowledgeBasesById = (options) => (options.client ?? client).
 /**
  * 更新知识库
  *
- * 需编辑者及以上。
+ * 需编辑者及以上。仅更新传入字段。mark 不可包含逗号，重复时返回 400。
  */
 export const patchApiKnowledgeBasesById = (options) => (options.client ?? client).patch({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -365,7 +461,23 @@ export const patchApiKnowledgeBasesById = (options) => (options.client ?? client
     }
 });
 /**
- * 列出 RAG 配置
+ * 导出知识库
+ *
+ * 将当前角色可见的文档导出为 Zip：Markdown 按文件夹树存放，根目录 manifest.json 记录各文档的路径、可见性与排序（结构见 KnowledgeBaseManifest）。阅览者仅导出公开且所在文件夹链路均公开的文档。导出包可通过 POST /api/documents 的 archive 字段导入。
+ */
+export const getApiKnowledgeBasesByIdExport = (options) => (options.client ?? client).get({
+    security: [{ scheme: 'bearer', type: 'http' }, {
+            in: 'cookie',
+            name: 'authjs.session-token',
+            type: 'apiKey'
+        }],
+    url: '/api/knowledge-bases/{id}/export',
+    ...options
+});
+/**
+ * 列出问答助手
+ *
+ * 返回全部问答助手的完整配置，欢迎语图片会回填当前有效的下载地址。
  */
 export const getApiRags = (options) => (options?.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -377,9 +489,9 @@ export const getApiRags = (options) => (options?.client ?? client).get({
     ...options
 });
 /**
- * 创建 RAG 配置
+ * 创建问答助手
  *
- * 绑定知识库与对话模块配置。mark 不可包含逗号。
+ * 需编辑者及以上。绑定知识库与对话参数，对话参数为空时继承全局默认。textProviderId 与 textModel 需同时填写。mark 不可包含逗号且全局唯一，重复时返回 400。
  */
 export const postApiRags = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -395,7 +507,9 @@ export const postApiRags = (options) => (options.client ?? client).post({
     }
 });
 /**
- * 删除 RAG 配置
+ * 删除问答助手
+ *
+ * 需编辑者及以上。被智能路由设为兜底助手时返回 400；已绑定该助手的会话保留，ragId 置空。
  */
 export const deleteApiRagsById = (options) => (options.client ?? client).delete({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -407,7 +521,9 @@ export const deleteApiRagsById = (options) => (options.client ?? client).delete(
     ...options
 });
 /**
- * 获取 RAG 配置
+ * 获取问答助手
+ *
+ * 返回问答助手完整配置，欢迎语图片会回填当前有效的下载地址。不存在时返回 404。
  */
 export const getApiRagsById = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -419,9 +535,9 @@ export const getApiRagsById = (options) => (options.client ?? client).get({
     ...options
 });
 /**
- * 更新 RAG 配置
+ * 更新问答助手
  *
- * 空字段表示继承全局默认。
+ * 需编辑者及以上。除 name / kbId 外，未传字段会被置为 null（对话参数为 null 即继承全局默认），请提交完整配置。textProviderId 与 textModel 需同时填写。mark 重复时返回 400。
  */
 export const patchApiRagsById = (options) => (options.client ?? client).patch({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -437,7 +553,7 @@ export const patchApiRagsById = (options) => (options.client ?? client).patch({
     }
 });
 /**
- * 按 id / mark 获取 RAG 配置摘要
+ * 按 id / mark 获取问答助手摘要
  *
  * id 与 mark 不能同时为空，同时传入按 AND 匹配。返回 id/name/mark/welcome/recommendedQuestions。
  */
@@ -466,6 +582,8 @@ export const deleteApiDocuments = (options) => (options.client ?? client).delete
 });
 /**
  * 列出知识库文档
+ *
+ * 返回文档摘要（不含正文）。阅览者仅能看到公开文档，且所在文件夹链路均需公开。
  */
 export const getApiDocuments = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -479,7 +597,7 @@ export const getApiDocuments = (options) => (options.client ?? client).get({
 /**
  * 创建空白文档或上传 Markdown
  *
- * Content-Type 为 application/json 时创建空白文档（kbId 由 query 传入）；为 multipart/form-data 时上传 Markdown 文件，返回 NDJSON 进度事件流。需编辑者及以上。
+ * Content-Type 为 application/json 时创建空白文档（kbId 由 query 传入）；为 multipart/form-data 时上传 Markdown 文件（files）或知识库导出 Zip（archive），返回 NDJSON 进度事件流。同级重名的文档记为失败并跳过。需编辑者及以上。
  */
 export const postApiDocuments = (options) => (options.client ?? client).post({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -529,7 +647,7 @@ export const patchApiDocumentsByPath = (options) => (options.client ?? client).p
 /**
  * 删除文档
  *
- * 需编辑者及以上。
+ * 需编辑者及以上。同时删除文档分块。
  */
 export const deleteApiDocumentsById = (options) => (options.client ?? client).delete({
     security: [{ scheme: 'bearer', type: 'http' }, {
@@ -542,6 +660,8 @@ export const deleteApiDocumentsById = (options) => (options.client ?? client).de
 });
 /**
  * 获取文档
+ *
+ * 返回文档完整内容并记录一次访问。阅览者仅能访问公开且所在文件夹链路均公开的文档，否则返回 403；文档不存在返回 404。
  */
 export const getApiDocumentsById = (options) => (options.client ?? client).get({
     security: [{ scheme: 'bearer', type: 'http' }, {