Ragie.ai RAG 技能（OpenClaw 优化版）

该技能通过 Ragie.ai 作为 RAG 后端，实现基于事实依据的问答能力。

Ragie 负责以下任务：

• 文档分块（Document chunking）
• 向量化嵌入（Embedding）
• 向量索引构建（Vector indexing）
• 语义检索（Retrieval）
• 可选重排序（Optional reranking）

智能体（Agent）负责以下任务：

• 判断何时执行文档摄入（ingest）
• 触发检索流程
• 构造基于检索结果的提示词（grounded prompts）
• 生成最终回答

核心原则

1. 绝不未经检索直接作答。
2. 绝不编造检索结果中未出现的信息（即杜绝幻觉）。
3. 引用具体事实时，必须注明 document_name。
4. 若检索返回零个相关文本块，则明确回应：

   “我当前的知识库中没有该信息。”

5. 最终回答中不得暴露 API 密钥或原始 API 请求/响应载荷。

确定性工作流

场景 A — 用户提供文件或 URL

若用户提供了以下任一内容：

• 一个文件
• 一个文档路径
• 一个待摄入的 PDF 或 URL

则执行以下步骤：

1. 执行摄入操作：

   python `skills/scripts/ingest.py` --file  --name ""
   

   或

   python `skills/scripts/ingest.py` --url "" --name ""
   

2. 捕获返回的 document_id。

3. 轮询文档状态：

   python `skills/scripts/manage.py` status --id 
   

   持续轮询，直至状态变为 ready。

4. 进入“检索”阶段（见场景 C）。

场景 B — 用户请求文档管理

列出全部文档

python `skills/scripts/manage.py` list

查询文档状态

python `skills/scripts/manage.py` status --id 

删除指定文档

python `skills/scripts/manage.py` delete --id 

向用户返回结构化结果。

场景 C — 检索（基于事实依据的问答）

执行以下命令：

python `skills/scripts/retrieve.py` 
  --query "" 
  --top-k 6 
  --rerank

可选参数：

• --partition
• --filter '{"key":"value"}'

检索输出格式

预期输出格式如下：

[
  {
    "text": "...",
    "score": 0.87,
    "document_name": "Policy Handbook",
    "document_id": "doc_abc123"
  }
]

基于事实依据的提示词构造

完成检索后：

1. 提取所有文本块的 text 字段内容。
2. 使用分隔符（如 ---）拼接各文本块。
3. 构造如下系统提示词：

SYSTEM:
You are a helpful assistant.
Answer using ONLY the context provided below.
If the context does not contain the answer, say:
"I don't have that information in the current knowledge base."

CONTEXT:
[chunk 1 text]
---
[chunk 2 text]
---
...

USER QUESTION:
{original user question}

4. 生成最终回答。
5. 引用信息时须标注其来源的 document_name。

输出契约

最终响应必须满足以下要求：

• 仅基于检索所得文本块作答
• 对所有事实性陈述标注对应 document_name
• 杜绝幻觉（hallucination）
• 不提及内部执行步骤（如脚本调用、轮询等）
• 不暴露 API 密钥或原始响应内容
• 当信息缺失时，需清晰声明

若未返回任何文本块，则输出：

I don't have that information in the current knowledge base.

API 参考

基础 URL：

https://api.ragie.ai

错误处理

若摄入失败：

• 需清晰报告失败原因。
• 禁止继续执行后续检索流程。

若检索失败：

• 最多重试一次。
• 若仍失败，应明确告知用户。

决策规则汇总

1. 用户上传内容 → 执行摄入 → 等待状态就绪 → 执行检索。
2. 用户提出问题 → 立即执行检索。
3. 检索返回零个文本块 → 明确声明知识缺口。
4. 默认启用重排序（reranking），除非显式禁用。
5. 绝不未经检索直接作答。

高级用法

• 使用元数据 filter 参数缩小检索范围。
• 使用 partition 实现租户级数据隔离。
• 仅在时间相关性至关重要的场景下启用 recency_bias。
• 根据查询复杂度动态调整 top_k 值。

安全性

• API 密钥必须从环境变量中加载。
• .env 文件严禁提交至代码仓库。
• 禁止记录敏感请求头信息。

总结

本技能提供以下能力：

• 确定性的文档摄入流程
• 确定性的语义检索流程
• 严格基于事实依据的回答机制
• 完整的 Ragie 生命周期管理能力
• 安全、抗幻觉的 RAG 执行保障

技能说明结束。