API 参考: 知识库 (Knowledge)

知识库管理端点。创建知识库、上传文档、语义搜索 (RAG)。

创建知识库

POST /v1/knowledge

权限要求： write

请求体

字段	类型	必填	说明
name	string	是	知识库名称
description	string	否	描述
type	string	否	类型：general（默认）、faq、manual

请求示例

curl -X POST https://api.invoratec.cn/v1/knowledge \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "运维知识库",
    "description": "设备运维文档集合",
    "type": "general"
  }'

响应 (201 Created)

{
  "_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "developerId": "user_123",
  "name": "运维知识库",
  "description": "设备运维文档集合",
  "type": "general",
  "documentCount": 0,
  "createdAt": "2026-04-12T08:00:00.000Z",
  "updatedAt": "2026-04-12T08:00:00.000Z"
}

错误

状态码	说明
400	name 缺失
403	缺少 write 权限

---

列出知识库

GET /v1/knowledge

请求示例

curl https://api.invoratec.cn/v1/knowledge \
  -H "X-API-Key: claw_xxxx"

响应

{
  "knowledgeBases": [
    {
      "_id": "665f...",
      "name": "运维知识库",
      "description": "设备运维文档集合",
      "type": "general",
      "documentCount": 15,
      "updatedAt": "2026-04-12T08:00:00.000Z"
    }
  ]
}

---

上传文档

将文本内容上传到知识库，系统自动分块并向量化，供语义搜索使用。

POST /v1/knowledge/{id}/documents

权限要求： write

路径参数

参数	类型	说明
id	string	知识库 _id

请求体

字段	类型	必填	说明
content	string	是	文档文本内容
title	string	否	文档标题，默认 "Untitled"
metadata	object	否	自定义元数据键值对

请求示例

curl -X POST https://api.invoratec.cn/v1/knowledge/665f.../documents \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "冷水机故障排查手册",
    "content": "## 高压报警\n原因：冷凝器散热不良...",
    "metadata": {
      "category": "maintenance",
      "equipment": "chiller"
    }
  }'

响应 (201 Created)

{
  "id": "665f1a2b3c4d5e6f7a8b9c0e",
  "title": "冷水机故障排查手册"
}

上传成功后，知识库的 documentCount 自动加 1。

错误

状态码	说明
400	content 缺失
403	缺少 write 权限

---

列出知识库文档

列出指定知识库下的所有文档。返回结果不包含 content 字段（避免大量数据传输）。

GET /v1/knowledge/{id}/documents

路径参数

参数	类型	说明
id	string	知识库 _id

请求示例

curl https://api.invoratec.cn/v1/knowledge/665f.../documents \
  -H "X-API-Key: claw_xxxx"

响应

{
  "documents": [
    {
      "_id": "665f...",
      "title": "冷水机故障排查手册",
      "metadata": { "category": "maintenance" },
      "createdAt": "2026-04-12T08:00:00.000Z"
    }
  ]
}

---

语义查询 (RAG)

对知识库进行语义搜索，返回与查询最相关的文档片段。

POST /v1/knowledge/{id}/query

路径参数

参数	类型	说明
id	string	知识库 _id

请求体

字段	类型	必填	说明
query	string	是	搜索查询文本
limit	integer	否	返回结果数量上限，默认 5

请求示例

curl -X POST https://api.invoratec.cn/v1/knowledge/665f.../query \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "冷水机高压报警怎么处理？",
    "limit": 5
  }'

响应

{
  "results": [
    {
      "text": "## 高压报警\n原因：冷凝器散热不良，通常由冷却水温度过高引起...",
      "source": "冷水机故障排查手册",
      "metadata": { "category": "maintenance", "equipment": "chiller" }
    },
    {
      "text": "当冷水机出现高压报警时，应首先检查冷却塔风机...",
      "source": "应急处理流程",
      "metadata": { "category": "emergency" }
    }
  ]
}

响应字段

字段	类型	说明
results[].text	string	匹配的文档内容片段
results[].source	string	来源文档标题
results[].metadata	object	文档元数据

如果 RAG 向量搜索不可用，系统自动降级为文本正则匹配，结果中 text 为内容前 500 字符。

错误

状态码	说明
400	query 缺失

---

直接写入内容

向知识库直接写入内容，无需指定标题（标题从 metadata 中获取）。

POST /v1/knowledge/{id}/content

权限要求： write

路径参数

参数	类型	说明
id	string	知识库 _id

请求体

字段	类型	必填	说明
content	string	是	文本内容
metadata	object	否	元数据，可包含 title 字段

请求示例

curl -X POST https://api.invoratec.cn/v1/knowledge/665f.../content \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "2026年新规定...",
    "metadata": { "title": "2026运维规范", "version": "v2" }
  }'

响应 (201 Created)

{ "success": true }

错误

状态码	说明
400	content 缺失
403	缺少 write 权限