Knowledge Base

Knowledge Base

1. 目标 & 范围

目标

为 AgentSurvey 的 Agent Harness 提供可配置的知识库（KB）能力：研究人员上传研究材料（产品说明、刺激物、概念文档等），Agent 在访谈中按需检索并引用，输出结果带回文献来源，使 AI 访谈可复现、可审计。

范围（本模块）

• KB 的三级 scope 定义与 CRUD（workspace / project / study）。
• 文档摄取流水线：上传 → 解析 → chunking → embedding → pgvector 索引。
• 检索接口：retrieve_knowledge 工具契约（供 Harness 调用）。
• Citation 机制：检索结果携带来源 metadata，可链回文档与 chunk。
• KB 版本化：study_version 绑定 kb_version_refs，保证历史会话可溯源。
• RAG 触发原则：Agent 不在每轮对话中检索，仅在特定条件下调用。

非本模块范围

• retrieve_knowledge 工具的注册与启用策略见 09_model_tool_config。
• Harness 何时调用工具的决策逻辑见 04_interview_runtime。
• 跨 session 的 Insight 综合不属于本模块。

---

2. 用户故事

作为研究人员（researcher），我希望创建一个 project 级别的知识库并上传产品说明文档，以便 Agent 在访谈中能准确介绍产品概念，而不是凭空生成。

作为研究人员，我希望在 study 配置中选择要关联的 KB 及其版本，以便同一 project 下不同 study 可以使用不同的知识范围，且历史 session 的检索行为可以复现。

作为研究人员，我希望查看 Agent 的每次检索记录（query / 命中 chunk / 相似度分），以便排查 Agent 是否引用了错误来源或产生幻觉。

作为研究人员，我希望更新 KB 中的文档后，已完成的 session 仍能追溯当时检索的版本，以便对比前后差异。

作为 admin / developer，我希望配置 embedding 模型与 chunking 策略，以便在精度与成本之间权衡，不同研究项目可独立调优。

---

3. 功能需求

KB 管理

FR-08-1（P1）：系统支持创建三级 scope 的知识库：workspace（全工作区共享）、project（项目内共享）、study（单次研究专属）。

• 验收要点：knowledge_bases.scope 字段取值限定为 workspace | project | study；workspace-scope KB 需 workspace_id 非空，project-scope KB 需 project_id 非空，study-scope KB 两字段均可非空。

FR-08-2（P1）：研究人员可对 KB 执行 CRUD（创建、读取、更新名称/描述、软删除）；删除前若有 study_version 引用该 KB，系统须警告并阻止硬删除。

• 验收要点：删除引用中的 KB 返回 409 错误，包含引用该 KB 的 study_version_id 列表；软删除后 status 置为 archived，已完成 session 仍可读历史 chunk。

FR-08-3（P1）：study 配置页面可从所属 project 及 workspace 下选择一个或多个 KB 关联，关联关系通过 study_versions.kb_version_refs（JSONB）记录 KB 及其版本快照 ID。

• 验收要点：study_versions.kb_version_refs 存储结构为 [{kb_id, kb_snapshot_id}]；发布 study 时系统自动为当前关联 KB 创建版本快照。

文档摄取流水线

FR-08-4（P1）：系统支持以下文档来源类型（knowledge_documents.source_type）：text（直接输入纯文本）、file（上传 PDF / TXT / DOCX / MD，最大 50 MB）、url（抓取网页正文，单 URL）。

• 验收要点：三种 source_type 各自能成功摄取；file 类型超过 50 MB 返回 413；url 无法访问时状态置为 failed 并记录错误信息。

FR-08-5（P1）：文档上传后进入异步摄取队列，状态机为 processing → ready | failed；研究人员可在 KB 管理页查看每个文档的当前状态和错误原因。

• 验收要点：上传接口立即返回 202 + document_id；轮询或 SSE 可获得状态变更；ready 状态下 chunk 数量 > 0。

FR-08-6（P1）：系统支持三种 chunking 策略（由 KBConfig.chunking_strategy 控制）：fixed（固定 token 窗口，默认 512 token，overlap 64）、semantic（基于句意边界分段）、markdown（按标题层级分段，适用于结构化文档）。

• 验收要点：对同一 Markdown 文档，markdown 策略生成的 chunk 数量与一级标题数量一致（±1）；fixed 策略下每个 chunk 的 token 数不超过 512 + overlap。

FR-08-7（P1）：每个 chunk 使用配置的 EmbeddingConfig 生成向量并写入 knowledge_chunks.embedding（pgvector vector 类型）；支持 text-embedding-3-small（OpenAI）作为默认 embedding 模型，embedding 维度可配。

• 验收要点：chunk 插入后 knowledge_chunks.embedding 字段非空；可对该列执行 cosine_similarity 查询并返回有序结果。

FR-08-8（P1）：同一文档重复上传时（基于 content_hash 判断），系统跳过摄取并返回已有 document_id，避免重复计算 embedding。

• 验收要点：相同内容第二次上传返回 200 + 原始 document_id，不新增 chunk。

检索与引用

FR-08-9（P1）：Harness 通过 retrieve_knowledge 工具检索 KB，工具输入为 { query: string, top_k: number, filters?: { kb_ids?: string[], scope?: KnowledgeBaseScope } }，输出符合 RetrievalResult 类型（query + chunks[]），每个 chunk 包含 chunk_id、document_id、title、content、score、metadata。

• 验收要点：给定合法 study_id 与 query，返回的 chunks 按 score 降序排列；top_k 边界值（1、20）均可正常返回；返回 chunk 数不超过 top_k。

FR-08-10（P1）：检索支持 score_threshold 过滤（KBConfig.score_threshold）：低于阈值的 chunk 不进入结果；score_threshold 未配置时返回全部 top_k 结果。

• 验收要点：设置 score_threshold=0.8 后，返回结果中所有 score >= 0.8；若无 chunk 超过阈值，返回空数组而非报错。

FR-08-11（P1）：当 KBConfig.citation_required = true 时，Harness 引用 KB 内容给受访者时须在 tool_call 的 output 中携带来源 metadata（chunk_id、document_id、title、原文 content 片段）；该 tool_call 记录入 tool_calls 表，便于事后审计引用来源。

• 验收要点：citation_required=true 的 KB 触发检索后，对应 tool_calls.tool_output 包含 citations 数组且每项有 chunk_id 与 document_id。

FR-08-12（P1）：检索操作记录完整日志（query、命中 chunk IDs、每个 chunk 的 score、使用的 kb_version_refs），用于调试 hallucination 与检索质量分析。

• 验收要点：每次 retrieve_knowledge 调用后，tool_calls 表存在对应记录，tool_input 含 query 与 filters，tool_output 含完整 RetrievalResult。

KB 版本化

FR-08-13（P1）：发布 study（POST /api/studies/{study_id}/publish）时，系统自动为当前关联的每个 KB 记录一次版本快照（snapshot），记录快照时的文档列表与 chunk 版本；study_versions.kb_version_refs 绑定该快照 ID。

• 验收要点：study 发布后 kb_version_refs 非空；同一 session 在快照之后即使 KB 文档更新，其检索范围仍限定于快照版本的 chunk 集合。

FR-08-14（P1）：研究人员可在管理界面查看某个 study_version 关联的 KB 快照内容（文档列表、chunk 数量、embedding 模型），以便复现历史检索行为。

• 验收要点：通过 GET /api/knowledge-bases/{kb_id}/snapshots/{snapshot_id} 返回快照文档列表与配置；对应 session 的 study_version_id.kb_version_refs 可关联到该快照。

RAG 触发原则

FR-08-15（P1）：Agent Harness 不在每轮对话中自动检索 KB；仅在以下条件之一满足时，Harness 才调用 retrieve_knowledge：（a）受访者询问产品/概念细节；（b）Agent 需要解释研究刺激物；（c）Agent 需引用项目背景支撑追问；（d）需根据受访者 segment 使用不同说明；（e）Agent 需核实回答是否与 KB 事实冲突。

• 验收要点：在无需 KB 的普通对话轮次中，tool_calls 表不存在 tool_name='retrieve_knowledge' 记录；触发条件满足时检索被正确调用（可通过 agent decision log 验证）。

FR-08-16（P1）：若 study 未关联任何 KB 或 retrieval_enabled=false，retrieve_knowledge 工具不在该 study 的 enabled tools 列表中出现，Harness 无法调用（防止空检索报错）。

• 验收要点：retrieval_enabled=false 的 study，Harness 的 tool schema 中不包含 retrieve_knowledge；Agent 调用该工具时后端返回 403。

---

4. 关键流程

4.1 文档摄取流水线

researcher 上传文档
  → POST /api/knowledge-bases/{kb_id}/documents
  → API 校验 source_type、文件格式/大小
  → 计算 content_hash，检查重复
  → 写入 knowledge_documents（status=processing）
  → 推入异步队列（Arq worker）
        ├── 解析文档（PDF/DOCX 转文本）
        ├── 按 chunking_strategy 分段
        ├── 调用 EmbeddingConfig 指定模型生成向量
        ├── 写入 knowledge_chunks（含 embedding）
        └── 更新 knowledge_documents.status = ready | failed
  → 研究人员可轮询/订阅状态

4.2 检索流程（访谈中）

Harness 判断需检索（满足 FR-08-15 条件之一）
  → 调用 retrieve_knowledge(query, top_k, filters)
  → Knowledge Base Service 执行 pgvector cosine_similarity 查询
  → 过滤 score < score_threshold 的 chunk
  → 返回 RetrievalResult（chunks + citations + source metadata）
  → Harness 将 chunk 内容注入上下文并生成回复
  → tool_call 记录入 tool_calls 表（含完整 input/output）

4.3 KB 版本化（study 发布）

researcher 发布 study
  → POST /api/studies/{study_id}/publish
  → 系统为每个关联 KB 当前状态创建 snapshot
      （记录文档 IDs、chunk 版本、EmbeddingConfig）
  → study_versions.kb_version_refs = [{kb_id, snapshot_id}, ...]
  → 该 study_version 下的所有 session 检索范围锁定于 snapshot

---

5. 数据

涉及表（详见 03_data_model）：

表	关键字段	说明
knowledge_bases	id, project_id, workspace_id, scope, status	KB 实体，三级 scope
knowledge_documents	id, knowledge_base_id, source_type, source_uri, content_hash, status, metadata	文档记录，status 为状态机
knowledge_chunks	id, document_id, chunk_index, content, embedding（vector）, metadata	chunk 与向量，pgvector 索引
study_versions	kb_version_refs（JSONB）	绑定 KB 快照，格式 [{kb_id, snapshot_id}]
tool_calls	tool_name='retrieve_knowledge', tool_input, tool_output	检索日志，含完整 RetrievalResult

knowledge_bases.scope 约束：workspace scope 时 workspace_id 非空；project / study scope 时 project_id 非空。

knowledge_chunks.embedding 使用 pgvector vector 类型，维度与 EmbeddingConfig.dimensions 一致（默认 1536，对应 text-embedding-3-small）；需在该列创建 IVFFlat 或 HNSW 索引以加速检索。

---

6. 接口

涉及 REST 端点（详见 02_api_contracts）：

KB CRUD

POST   /api/projects/{project_id}/knowledge-bases          # 创建 KB（project scope）
POST   /api/workspaces/{workspace_id}/knowledge-bases      # 创建 KB（workspace scope）
GET    /api/knowledge-bases/{kb_id}                        # 读取 KB 详情与 KBConfig
PATCH  /api/knowledge-bases/{kb_id}                        # 更新名称/描述/配置
DELETE /api/knowledge-bases/{kb_id}                        # 软删除（检查引用）

文档管理

POST /api/knowledge-bases/{kb_id}/documents               # 上传/添加文档（202 异步）
GET  /api/knowledge-bases/{kb_id}/documents               # 列出文档与状态
GET  /api/knowledge-bases/{kb_id}/documents/{doc_id}      # 文档详情（chunk 数量、status）
DELETE /api/knowledge-bases/{kb_id}/documents/{doc_id}    # 删除文档及 chunk

KB 快照

GET /api/knowledge-bases/{kb_id}/snapshots/{snapshot_id}  # 读取快照内容

工具检索接口（内部，供 Harness 调用）

POST /api/tools/retrieve-knowledge

Request 示例：

{
  "study_id": "study_123",
  "query": "AgentSurvey 的核心能力是什么？",
  "top_k": 5,
  "filters": {
    "kb_ids": ["kb_abc"],
    "scope": "project"
  }
}

Response 符合 RetrievalResult：

{
  "query": "AgentSurvey 的核心能力是什么？",
  "chunks": [
    {
      "chunk_id": "chunk_001",
      "document_id": "doc_xyz",
      "title": "产品概念说明",
      "content": "AgentSurvey 是一个开源 agentic 用户调研平台...",
      "score": 0.91,
      "metadata": { "chunk_index": 2, "source_type": "file" }
    }
  ]
}

retrieve_knowledge 工具定义（ToolDefinition 摘要）：

id:              retrieve_knowledge
tool_type:       retrieval
execution_mode:  backend
risk_level:      low
input_schema:    { query, top_k, filters? }
output_schema:   RetrievalResult（query + chunks[]）

工具注册与 study 级启用策略见 09_model_tool_config。

---

7. 验收标准

AC-08-1：可成功创建 workspace / project / study 三种 scope 的 KB，各 scope 的权限隔离符合：workspace-scope 对工作区所有成员可见，project-scope 仅对 project 成员可见，study-scope 仅在该 study 配置中引用。

AC-08-2：上传 source_type=file 的 PDF（< 50 MB），在 60 秒内文档状态由 processing 变为 ready，knowledge_chunks 表中 chunk 数量 > 0，每个 chunk 的 embedding 字段为有效向量。

AC-08-3：同一文档内容第二次上传，系统返回已有 document_id，knowledge_chunks 中无重复 chunk，knowledge_documents 中无新增记录。

AC-08-4：调用 POST /api/tools/retrieve-knowledge，指定合法 study_id 与 query，返回 chunks 按 score 降序排列，结果数量不超过 top_k。

AC-08-5：设置 score_threshold=0.8，检索结果中所有 chunk 的 score >= 0.8；无满足条件 chunk 时返回 { "query": "...", "chunks": [] } 而非 4xx 错误。

AC-08-6：citation_required=true 的 KB，检索后对应 tool_calls.tool_output.citations 数组非空，每项包含 chunk_id 与 document_id，可关联回 knowledge_chunks 与 knowledge_documents。

AC-08-7：发布 study 后，study_versions.kb_version_refs 非空；更新 KB 文档后重新检索，已完成 session（旧 study_version）的检索范围不受影响（仍使用快照 chunk 集合）。

AC-08-8：retrieval_enabled=false 的 study 中，Harness 的 tool schema 不含 retrieve_knowledge；强制调用该工具时后端返回 403。

AC-08-9：在无 RAG 触发条件的普通对话轮次中，tool_calls 表内不产生 tool_name='retrieve_knowledge' 记录（可通过 agent decision log 核查）。

AC-08-10：删除被 study_version 引用的 KB 时，API 返回 409 并在响应体中包含引用该 KB 的 study_version_id 列表，不执行删除。

AC-08-11：markdown chunking 策略下，对含 4 个一级标题的 Markdown 文档，生成 chunk 数量在 3 ~ 5 之间；fixed 策略下每个 chunk token 数不超过 576（512 + 64 overlap）。

AC-08-12：GET /api/knowledge-bases/{kb_id}/snapshots/{snapshot_id} 返回该快照的文档列表、chunk 数量与 EmbeddingConfig，与发布时刻的 KB 状态一致。

---

8. 边界 & 非目标

• 非目标（本模块）：工具注册与 study 级启用/禁用策略（见 09_model_tool_config）。
• 非目标（本模块）：Harness 的 RAG 决策逻辑实现细节（见 04_interview_runtime）。
• 非目标（P1 内）：KB 跨 workspace 共享、公开 KB 市场。
• 非目标（P1 内）：图像、音频、视频文件的摄取；URL 批量抓取（单 URL 支持）。
• 非目标（P1 内）：重排序（re-ranking）模型；混合检索（BM25 + 向量）。
• 边界：retrieve_knowledge 是 backend 执行工具，不通过 AG-UI 发送到前端；前端不感知检索过程，仅看到 Agent 的最终回复。
• 边界：embedding 维度一旦为 KB 配置后不可修改；需换 embedding 模型时须重新建库并重新摄取所有文档。
• 边界：KB 软删除后，status=archived 的 KB 不出现在新 study 配置的选择列表中，但历史 session 的引用保持有效。

---

9. 依赖 & 风险

依赖

依赖项	说明
pgvector	PostgreSQL 扩展，必须在 DB 实例上启用；向量索引（IVFFlat / HNSW）须在 chunk 数量增长后手动创建或调优
Arq（异步队列）	文档摄取、embedding 计算为异步任务，依赖 Arq worker 正常运行
EmbeddingConfig	与 09_model_tool_config 中的 EmbeddingConfig 复用，需先完成模型配置模块
Object Storage	source_type=file 的原始文件存储于 S3-compatible 对象存储，需配置存储 bucket
04_interview_runtime	Harness 决定调用 retrieve_knowledge 的时机；KB 模块提供工具实现，不控制触发策略
09_model_tool_config	retrieve_knowledge 的 ToolDefinition 注册与 study 级启用在此模块管理

风险

风险	可能性	缓解措施
embedding 维度与模型不匹配导致查询报错	中	建库时锁定维度，换模型前强制重建；API 校验 embedding 维度一致性
大文档（> 10 MB PDF）摄取超时	中	异步队列 + 超时重试（最多 3 次）；任务状态可查；超过单文件上限（50 MB）直接拒绝
pgvector 在高并发检索下性能下降	低（MVP 阶段）	MVP 单实例部署可承受；规模化时加 HNSW 索引 + 连接池；必要时引入专用向量数据库
Chunk 质量差导致检索相关性低	中	提供三种 chunking 策略供研究人员选择；记录检索分数日志，便于研究人员调优
Agent 过度检索影响访谈流畅性	中	RAG 触发原则（FR-08-15）由 Harness 控制；本模块仅保证工具实现正确；验收通过 agent decision log 核查