CampusClaw 第四课：可追溯知识库检索

本仓库完成作业 0923-课后任务：为限定班级范围的知识库增加正文切分、关键字/向量/混合检索、原文溯源和基于依据的简短回答。OpenSpec 变更名为 add-traceable-vector-retrieval，规约和实现放在同一仓库。

本项目使用自编示例材料，不复制教师课件正文。课程网页.txt 仅保留课程入口链接。

作业要求对应关系

要求	实现位置 / 行为
第四次课 OpenSpec 变更描述	`openspec/changes/add-traceable-vector-retrieval/` 四件套
限定班级范围	`class_id` 只取自服务端会话；关键字、向量和回表三处过滤
正文切分	auto（800/80）、custom（100–2000，0–50%）、Markdown 标题分章
三种检索	keyword、vector、hybrid；混合模式使用 RRF，`k=60`
内容溯源	标题、切片序号、Unicode 字符区间、摘录、完整原文定位
无依据处理	固定返回“资料中未找到相关内容”，不调用生成模型
向量数据库	默认 SQLite 便携演示；配置后使用 Qdrant，正文仍只在关系库

直接运行（无需安装依赖）

需要 Python 3.10 或更高版本，且 Python 自带的 SQLite 启用了 FTS5。Windows PowerShell：

Copy-Item .env.example .env
python run.py

打开 http://127.0.0.1:8080。预置账号：

班级	教师	学生	初始密码
A	`teacher_a`	`student_a1`	`Demo123!`
B	`teacher_b`	`student_b1`	`Demo123!`

教师可上传 UTF-8 编码的 .txt / .md 材料并选择切分策略；学生可检索和查看本班原文。A 班账号无法读取 B 班专用材料 BLUE-ORCA-927。

检索模式说明

默认 .env.example 使用零依赖的本地词法向量。它用确定性的特征哈希产生向量，适合验证向量存取、余弦阈值、RRF 和回表逻辑，但不具备大模型的同义改写理解能力。界面会明确显示“离线演示”。

要验收真正的语义检索，将 .env 中以下项目改为课程网关提供的实际值：

EMBEDDING_PROVIDER=remote
EMBEDDING_MODEL=实际嵌入模型名
EMBEDDING_DIM=实际维度
MODEL_BASE_URL=https://实际网关/v1
MODEL_API_KEY=实际密钥

配置改变后应使用新的 DATA_DIR，由系统重新生成与模型匹配的索引。密钥只在服务端使用，切勿提交 .env。

如需 Qdrant，再设置：

VECTOR_BACKEND=qdrant
QDRANT_URL=http://qdrant:6333

随后执行 docker compose --profile qdrant up --build。Compose 不将 Qdrant 的 6333 端口暴露给浏览器，向量 payload 也不保存正文。

基于依据的回答

默认 CHAT_PROVIDER=extractive，问答区域直接整理最多四条原文摘录，并标注 [1]、[2]；它不会伪装成模型生成内容。接入兼容 OpenAI 的对话模型时设置：

CHAT_PROVIDER=remote
CHAT_MODEL=实际对话模型名

服务端只把本班检索到的标题、切片序号和正文交给模型；客户端构造的 system 消息不会被转发。没有命中时整个模型调用路径不会发生。

接口

POST /api/login、POST /api/logout、GET /api/me
GET /api/materials、POST /api/materials
GET /api/materials/{id}、GET /api/materials/{id}/download
POST /api/materials/{id}/reindex
POST /api/search：query、mode、limit
POST /api/ask：使用混合检索取前 4 条
GET /health：无需登录

任何请求中的 class_id 都不会覆盖登录会话中的班级。跨班检索表现为无命中，跨班材料详情与不存在的材料一样返回 404。

验证

python -m compileall app run.py
python -m unittest discover -s tests -v
python scripts/http_smoke.py

http_smoke.py 会临时启动服务，检查健康状态、登录、关键字检索、请求体篡改班级无效、跨班详情 404，以及无依据问答固定文案。测试数据写入临时目录，不污染仓库。

若已安装 OpenSpec CLI，还可执行：

openspec validate add-traceable-vector-retrieval --strict

OpenSpec CLI 的官方安装与验证命令见 https://github.com/Fission-AI/OpenSpec。

项目结构

app/                 服务端、切分、检索和模型/向量适配
static/              登录、检索、教师上传和原文溯源页面
examples/            自编 A/B 班验收材料
openspec/changes/    第四课 OpenSpec 四件套
scripts/http_smoke.py HTTP 端到端验收
tests/               单元与集成测试
compose.yaml         应用与可选 Qdrant

提交到 GitLink

请先在 GitLink 新建一个公开空仓库，不要勾选自动创建 README。然后在本目录执行：

git init
git add .
git commit -m "feat: add traceable classroom knowledge retrieval"
git branch -M main
git remote add origin 你的GitLink仓库地址
git push -u origin main

提交作业时粘贴 GitLink 仓库首页地址。推送前用 git status 确认 .env、data/ 和密钥没有被纳入版本控制。

设计边界

课程课件参考 MySQL FULLTEXT ... WITH PARSER ngram 与 Qdrant。本仓库为了让阅卷者无需安装服务即可运行，默认使用 SQLite FTS5 与本地向量；通过配置可以切换到 Qdrant 和真实模型。两种模式都保持同样的班级隔离、阈值、RRF、回表和溯源行为。