知识库

概述

wesgine 的知识库（Knowledge）是 Cell 内的文档存储与检索系统。通过将文档上传到知识库，Agent 可以在对话中通过语义搜索检索相关信息。知识库是 Cell 级资源，不区分 Actor。

核心概念

数据源（Source）

数据源是知识库的组织单元，用于对文件进行分组管理。每个数据源可以包含多个文件：

Knowledge
├── 数据源：合同模板
│   ├── 劳动合同模板.docx
│   └── 采购合同模板.pdf
├── 数据源：政策文件
│   ├── 员工手册.md
│   └── 安全规范.txt

自动分块与索引

文件上传后，引擎自动执行：

1. 解析：提取文档文本内容
2. 分块：将长文档切分为语义片段
3. 索引：为每个片段建立向量索引和全文索引

文件状态

文件操作

上传文件

POST /cells/{id}/knowledge/ingest          # 上传文件（raw body）
POST /cells/{id}/knowledge/ingest-local    # 导入本地路径

管理数据源

GET    /cells/{id}/knowledge/sources           # 数据源列表
POST   /cells/{id}/knowledge/sources           # 添加数据源
PATCH  /cells/{id}/knowledge/sources/{id}      # 更新数据源
DELETE /cells/{id}/knowledge/sources/{id}      # 删除数据源

管理文件

GET    /cells/{id}/knowledge/files             # 文件列表（支持按 source/agent/status 过滤）
GET    /cells/{id}/knowledge/files/{id}        # 文件详情
DELETE /cells/{id}/knowledge/files/{id}        # 删除文件
GET    /cells/{id}/knowledge/files/{id}/content # 原始内容

语义搜索

知识库提供语义搜索能力，Agent 在对话中可通过工具调用进行检索：

POST /cells/{id}/knowledge/search

{
    "query": "劳动合同解除的条件",
    "limit": 10,
    "source_ids": ["src-001"],
    "agent_id": "agent-legal"
}

搜索使用向量相似度 + 关键词匹配的混合检索策略，返回最相关的文档片段。

Agent 绑定

知识库文件可以与特定 Agent 绑定，控制哪些 Agent 可以访问哪些知识：

POST   /cells/{id}/knowledge/files/{id}/agents            # 绑定 Agent
DELETE /cells/{id}/knowledge/files/{id}/agents/{agent_id}  # 解绑 Agent
GET    /cells/{id}/knowledge/agents/{agent_id}/files       # 某 Agent 绑定的文件列表

未绑定任何 Agent 的文件对 Cell 内所有 Agent 可见。

索引管理

重建索引

当索引损坏或需要更新时，可以重建：

POST /cells/{id}/knowledge/files/{id}/reindex     # 重建单个文件索引
POST /cells/{id}/knowledge/sources/{id}/reindex   # 重建数据源下全部文件索引
POST /cells/{id}/knowledge/reindex-quarantined    # 批量重建被隔离文件索引

解除隔离

被安全扫描误报隔离的文件可以手动解除：

POST /cells/{id}/knowledge/files/{id}/unquarantine    # 解除隔离并重建索引

安全扫描

知识库使用独立扫描器（ScanKBChunk），仅检测私钥材料（PEM 头）。这与记忆系统的威胁扫描（5 条正则 + invisible unicode）不同——文档中的 DSN 示例、配置模板等不会触发误报。

扫描粒度为 per-chunk：仅跳过含私钥的片段，其余正常索引。

统计信息

GET /cells/{id}/knowledge/stats                     # 全局统计
GET /cells/{id}/knowledge/sources/{id}/stats        # 数据源统计

返回文件数、总大小、索引状态分布等信息。