mcpField
D
denser-retriever

denser-retriever

github.com/denser-org文档处理656 次安装36 周前更新
代码仓库

关于 denser-retriever

denser-retriever 是用于调用 Denser Retriever REST API 的技能，可管理知识库并对文档进行语义搜索。它通过 curl 指导文件与文本导入、处理状态检查和查询。

主要功能

  1. 01创建和管理知识库
  2. 02上传并导入支持的文件
  3. 03直接导入纯文本
  4. 04检查文档处理状态
  5. 05语义搜索文档

适用场景

  1. 01从文件建立可搜索的知识库
  2. 02无需上传文件即可添加文本
  3. 03搜索指定或全部知识库

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/denser-org/claude-skills --skill denser-retriever

安装后在 Claude Code 中输入/denser-retriever确认已加载。

附带文件references/api_reference.md

详细介绍

Denser Retriever API

通过 Denser Retriever REST API 管理知识库，并对文档执行语义搜索。所有操作均使用 curl 命令。

设置

API 密钥：从 DENSER_API_KEY 环境变量读取。如果未设置，请向用户索取 API 密钥。

基础 URL：https://retriever.denser.ai/api/open/v1

检查密钥是否可用：

echo $DENSER_API_KEY

如果为空，请向用户询问：“请提供您的 Denser Retriever API 密钥（可在组织设置中找到）。”

快速参考

操作方法端点
获取用量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。

常见工作流

1. 根据文件构建知识库

这是一个多步骤流程：创建知识库、上传每个文件、等待处理完成，然后进行搜索。

步骤 1：创建知识库

curl -s -X POST "https://retriever.denser.ai/api/open/v1/createKnowledgeBase" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My KB", "description": "Optional description"}' | python3 -m json.tool

保存返回的 id，以供后续操作使用。

步骤 2：对每个文件执行 3 步上传操作

a) 获取预签名上传 URL：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/presignUploadUrl" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId": "KB_ID", "fileName": "document.pdf", "size": FILE_SIZE_BYTES}' | python3 -m json.tool

b) 将文件上传到预签名 URL（原始字节，使用 PUT 请求）：

curl -s -X PUT "PRESIGNED_UPLOAD_URL" --data-binary @/path/to/document.pdf

c) 触发导入处理：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/importFile" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "FILE_ID"}' | python3 -m json.tool

步骤 3：轮询，直到处理完成

curl -s -X GET "https://retriever.denser.ai/api/open/v1/getDocumentStatus?documentId=DOC_ID" \
  -H "x-api-key: $DENSER_API_KEY" | python3 -m json.tool

每隔 2-3 秒重复一次，直到 status 为 "processed"。如果状态为 "failed" 或 "timeout"，请报告错误。

步骤 4：搜索

curl -s -X POST "https://retriever.denser.ai/api/open/v1/query" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query", "knowledgeBaseIds": ["KB_ID"], "limit": 10}' | python3 -m json.tool
2. 直接导入文本内容

适用于无需上传文件的纯文本：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/importTextContent" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId": "KB_ID", "title": "My Document", "content": "Full text content here..."}' | python3 -m json.tool
3. 搜索所有知识库

省略 knowledgeBaseIds 即可搜索所有内容：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/query" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query", "limit": 10}' | python3 -m json.tool

自动化模式

批量上传多个文件

用户提供文件目录时，循环处理其中的文件：

KB_ID="your-kb-id"
for file in /path/to/files/*; do
  FILE_NAME=$(basename "$file")
  FILE_SIZE=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)

  # Get presigned URL
  PRESIGN=$(curl -s -X POST "https://retriever.denser.ai/api/open/v1/presignUploadUrl" \
    -H "x-api-key: $DENSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"knowledgeBaseId\": \"$KB_ID\", \"fileName\": \"$FILE_NAME\", \"size\": $FILE_SIZE}")

  UPLOAD_URL=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['uploadUrl'])")
  FILE_ID=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['fileId'])")

  # Upload file
  curl -s -X PUT "$UPLOAD_URL" --data-binary @"$file"

  # Trigger import
  curl -s -X POST "https://retriever.denser.ai/api/open/v1/importFile" \
    -H "x-api-key: $DENSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"fileId\": \"$FILE_ID\"}"

  echo "Uploaded: $FILE_NAME (fileId: $FILE_ID)"
done
轮询文档状态，直到就绪
DOC_ID="your-document-id"
while true; do
  STATUS=$(curl -s -X GET "https://retriever.denser.ai/api/open/v1/getDocumentStatus?documentId=$DOC_ID" \
    -H "x-api-key: $DENSER_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
  echo "Status: $STATUS"
  if [ "$STATUS" = "processed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "timeout" ]; then
    break
  fi
  sleep 3
done

响应格式

所有响应均遵循以下结构：

成功： {"success": true, "data": { ... }}

错误： {"success": false, "message": "Error details", "errorCode": "ERROR_CODE"}

常见错误代码：STORAGE_LIMIT_EXCEEDED、KNOWLEDGE_BASE_LIMIT_EXCEEDED、INSUFFICIENT_CREDITS、INPUT_VALIDATION_FAILED

支持的文件类型

PDF、DOCX、PPTX、XLS、XLSX、HTML、TXT、CSV、XML、Markdown。文件大小上限：512MB。

重要说明

  • 每次搜索查询消耗 1 个积分。批量搜索前，请使用 getBalance 检查余额。
  • 文档处理是异步的——搜索前务必轮询 getDocumentStatus。
  • 上传文件必须遵循 presignUploadUrl -> PUT 上传 -> importFile 流程。
  • 搜索结果包含 score、content、title、document_id 和 metadata。

评论

支持 Markdown