问津：研发资料 RAG / MCP 检索服务

把有固定来源和版本的技术资料整理成可核对、可重建、可回退的检索证据，并通过 MCP 提供给编程 Agent。项目聚焦资料导入、解析与切分、混合检索、索引版本管理、访问控制和证据交付。

这是个人实现与学习项目，不代表任何公司，也不表示已在公司部署或通过生产验收。当前状态与各类验证证据见开发状态及对应迭代记录。

项目能力

• 核对来源：检索证据保留语料、版本及原文位置等信息，调用方可以回看材料；排序分数不代表答案正确。

• 重建索引：公开语料以 manifest 记录来源、许可、固定版本和文件哈希；原文和派生索引不作为普通源码提交。

• 控制变更：新索引先验证再切换注册表，支持回退；注册表本身是本机运行状态。

• 管理文件：支持上传判重、替换、删除、任务进度查看和失败重试；管理页会话与个人 MCP 凭据用途分开，资料读取权限按请求复核。

• 交付证据：MCP 新旧入口均返回检索证据，由客户端 Agent 生成最终回答；MCP 不替客户端判断证据是否充分。

Related MCP server: linked-docs

主要数据流

公开资料与版本清单
  → 按组织流程摆渡及校验
  → 文档解析 / 切分 / 向量与关键词索引
  → dense + BM25 检索与 RRF 融合
  → 可选本地 reranker
  → 带来源位置的证据
  → MCP 客户端 Agent

RRF 是排名融合，不是模型重排。命令行问答可自行生成回答；MCP 入口主要返回证据。

协议、身份与部署边界

• 项目叙事截止日为 2026-07-15。截至该日的旧 MCP 设计采用 2025-11-25 状态化生命周期：initialize、notifications/initialized、能力协商及可选 MCP-Session-Id。

• 经单独授权整合的 2026-07-28 无状态 MCP 是个人后续迭代，使用 server/discover 和逐请求 _meta，位于独立 mcp-stateless/ uv 环境；不回写为截止日前项目设计或经历。详见新版 MCP 说明。

• 管理界面可使用独立 SQLite 账号身份库，保存登录会话、个人 MCP 凭据哈希、资料库授权及身份审计；凭据原文仅在签发时展示。传统 configs/access/ ACL 和私有索引配置是部署数据，不会因启用账号模式而自动迁移或放权。

• GPU 模型 API 每个服务进程使用单 worker FIFO；当前默认值为最多 8 个等待位（不含正在执行的请求），等待上限 30 秒，均可配置。它限制单次模型 API 调用的排队，不代表整条查询 SLA；配置说明见双部署专题。

• 可选本机完整 Docker 拓扑，或云端轻量 backend 连接私网 TLS 本机 GPU 模型节点。配置模板和隔离验收不等于云资源已购买、公网已部署或生产验收；宿主机、容器及 GPU 环境分别核实。

快速开始：轻量开发环境

主项目使用 Python 3.12 和 uv，依赖由 pyproject.toml 与 uv.lock 管理。以下命令准备锁定的轻量开发环境：

uv python install 3.12
uv sync --locked --no-default-groups --group dev

CI 使用相同的锁定安装命令，随后运行 Ruff 并执行 12 个显式选择的合成测试模块；准确模块清单和步骤以 CI 工作流 为准。

最近一次（2026-10-25）独立回归记录为 175 passed、1 failed；失败是 main 基线中已有的管理员评测授权断言矛盾。新增的 48 项回归单独运行通过，不将这一轮记为全绿。详见开发记录和独立验收记录。

部署与运行专题

• Windows / Linux 环境说明：主环境、运行前提和平台边界。

• 双部署说明：本机完整栈与云端轻量 backend / 私网 GPU 节点配置。

• Windows 交付、备份与恢复：离线资产、隔离恢复和已验证范围。

• Docker 部署专题：现有 compose 与容器入口。

• 文件管理 · 管理界面：受管文件生命周期、账号和授权边界。

• MCP 入口控制：新旧入口配置和运行状态含义。

• 安全边界：凭据、网络与访问控制说明。

文档导航

• 项目目标：目标、教学与长期边界。

• 当前状态与下一步：当前结论、限制和证据链接。

• 项目布局：根目录职责及源码、模型权重和运行数据边界。

• 检索实验：带日期的历史策略与评测结果。

• MVP 验收 · 客户端验收。

• 开发记录索引：各轮变更与原始验收证据。

历史实验数字只说明对应日期、数据和配置下的结果，不证明当前服务、真实资料、目标主机或生产系统状态。

许可

项目自身代码采用 MIT。第三方资料各自遵循上游许可；本仓库通过来源与许可记录标明边界，详见 THIRD_PARTY_NOTICES.md。