Denser Retriever 是一套通过 REST API 管理知识库并进行语义搜索的能力，所有操作使用 curl 命令完成。
配置：API 密钥从环境变量 DENSER_API_KEY 读取，可用 echo $DENSER_API_KEY 检查；若为空需向用户索取。基础地址为 https://retriever.denser.ai/api/open/v1。
主要操作：获取用量（GET /v1/getUsage）、获取余额（GET /v1/getBalance）、创建知识库（POST /v1/createKnowledgeBase）、列出知识库（GET /v1/listKnowledgeBases）、更新知识库（POST /v1/updateKnowledgeBase）、删除知识库（POST /v1/deleteKnowledgeBase）、预签名上传（POST /v1/presignUploadUrl）、导入文件（POST /v1/importFile）、导入文本（POST /v1/importTextContent）、列出文档（GET /v1/listDocuments）、删除文档（POST /v1/deleteDocument）、查询文档状态（GET /v1/getDocumentStatus）、搜索（POST /v1/query）。完整请求与响应结构见 references/api_reference.md。
典型流程：先用 createKnowledgeBase 创建知识库并保存返回 id；上传文件需三步：presignUploadUrl 获取预签名 URL 与 fileId，再以 PUT 将原始字节上传到该 URL，最后调用 importFile 触发处理。之后每 2-3 秒轮询 getDocumentStatus，直到状态为 processed；若为 failed 或 timeout 则报告错误。搜索调用 query，可传 knowledgeBaseIds 限定知识库，省略则搜索全部，limit 控制条数。纯文本可用 importTextContent 直接导入。
响应格式：成功为 {"success": true, "data": {...}}，错误为 {"success": false, "message": "...", "errorCode": "..."}。常见错误码包括 STORAGE_LIMIT_EXCEEDED、KNOWLEDGE_BASE_LIMIT_EXCEEDED、INSUFFICIENT_CREDITS、INPUT_VALIDATION_FAILED。
支持文件类型：PDF、DOCX、PPTX、XLS、XLSX、HTML、TXT、CSV、XML、Markdown，单文件最大 512MB。
限制与注意：每次搜索消耗 1 个 credit，批量搜索前先用 getBalance 检查余额；文档处理是异步的，搜索前必须轮询状态；文件上传必须走 presignUploadUrl → PUT → importFile 流程。搜索结果包含 score、content、title、document_id 和 metadata。