知识库 RAG
路由源文件：app/server/routers/kdb.py，业务实现位于 common/services 下与 KDB 相关的服务（名称可能含 kdb / knowledge）。主参考中的路径均以 /api/knowledge-base 为前缀。
与其他模块的关系
- Agent 侧：在
AgentConfigDTO的availableKnowledgeBases（或兼容字段名）中列出kdb_id后，运行时才允许该 Agent 的检索/对话管线访问这些库（具体 enforcement 在 chat/Agent 装配层）。 - 工具侧：产品也可能通过工具封装间接调用
POST .../retrieve；与直接 HTTP 调用的区别主要在鉴权、审计和计费边界。
推荐集成顺序
POST /api/knowledge-base/add建库，记下返回的kdb_id。- 用
POST /api/knowledge-base/doc/add_by_files上传文档，拿到taskId。 - 用
GET /api/knowledge-base/doc/task_process或文档列表/状态接口观察解析与索引是否完成；必要时.../redo*. POST /api/knowledge-base/retrieve做联调检索；top_k等参数见主参考「知识库常用模型」。- 将
kdb_id配入 Agent 或上层应用配置。
易错点
- 删除与清空：
delete/{kdb_id}与clear语义不同，后者是清空内容、保留库元数据，集成自动化前确认业务要哪一种。 - 文档任务 ID：
task_id在列表、进度、重跑类接口中多次出现，不要与 [计划任务/tasks](/Sage/zh/api/HTTP_API_TASKS.html)或 [Agent 异步任务GET /api/agent/tasks/...](/Sage/zh/api/HTTP_API_AGENT.html)混读。 - 分页与过滤：
doc/list的query_status、page_no等见主参考「知识库文档查询字段」表。