ragtop-agent Skill

本 Skill 允许 AI 通过 curl 调用 RAGTOP 后端接口。AI 必须根据用户请求的性质，在“简单指令”与“深度调研”两种模式间切换。

Configuration

The following environment variables are required:

• RAGTOP_API_URL: RAGTOP API base URL. Defaults to http://10.71.10.71:9380 if not set.
• RAGTOP_API_TOKEN: Your RAGTOP API access token. Can be configured via the OpenClaw Web UI.

1. 核心工具构建指南 (How to build curl)

在调用以下接口前，请确保已获取环境变量 ${RAGTOP_API_URL} 和 ${RAGTOP_API_TOKEN}。如果 ${RAGTOP_API_URL} 为空，请使用默认值 http://10.71.10.71:9380。

A. 列出知识库 (list_kb)

用于获取所有可用的 knowledge_id。

curl -L -X POST "${RAGTOP_API_URL}/api/v1/ragtop/tool/list_kb" \
     -H "Authorization: Bearer ${RAGTOP_API_TOKEN}" \
     -H "Content-Type: application/json"

B. 列出文档 (list_doc)

用于获取特定知识库内的 doc_id 列表，以便缩小检索范围。

• Payload: {"knowledge_id": "string"}

curl -L -X POST "${RAGTOP_API_URL}/api/v1/ragtop/tool/list_doc" \
     -H "Authorization: Bearer ${RAGTOP_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"knowledge_id": "YOUR_KB_ID"}'

C. 内容检索 (retrieval)

用于执行语义搜索。支持单查询或多查询。

• Payload 关键参数:
  • knowledge_id: 必填。
  • query: 字符串（单查询）。
  • queries: 字符串数组（多查询，推荐用于复杂任务）。
  • doc_ids: 数组（可选，限定文件范围）。
  • retrieval_setting: {"top_k": 16, "score_threshold": 0.3}

curl -L -X POST "${RAGTOP_API_URL}/api/v1/ragtop/tool/retrieval" \
     -H "Authorization: Bearer ${RAGTOP_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "knowledge_id": "YOUR_KB_ID",
       "queries": ["查询1", "查询2"],
       "retrieval_setting": {"top_k": 5}
     }'

2. 任务分类处理逻辑

情况 A：简单指令 (Simple Instructions)

适用场景: 用户询问“有哪些知识库？”、“这个库里有哪些文件？”等管理类问题。 执行逻辑:

1. 直接根据需求构建 list_kb 或 list_doc 的 curl 命令。
2. 将返回的 JSON 结果整理成易读的表格或列表告知用户。

情况 B：深度调研 (Deep Investigation / Agentic RAG)

适用场景: 用户提出具体业务问题、对比分析或需要跨文档总结。 执行逻辑:

1. 参考 references/workflow.md 执行“分析-分解-检索-综合”流程。
2. 多步编排:
   • 第一步：调用 list_kb 确定相关的知识库 ID。
   • 第二步（可选）：调用 list_doc 锁定相关文件。
   • 第三步：构建包含多个改写问题的 retrieval 请求，利用多路召回提高准确率。
   • 第四步：根据检索到的多个 chunks 进行逻辑推理和引用标注。

3. 运行规范

• 严禁提及 ragflow，统一使用 ragtop。
• 引用必填: 所有深度调研的回答必须注明引用的文档名称。
• 错误处理: 如果 curl 返回非 SUCCESS，应检查 Token 有效性并告知用户。