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

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

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

## 项目能力

- **核对来源**：检索证据保留语料、版本及原文位置等信息，调用方可以回看材料；排序分数不代表答案正确。
- **重建索引**：公开语料以 manifest 记录来源、许可、固定版本和文件哈希；原文和派生索引不作为普通源码提交。
- **控制变更**：新索引先验证再切换注册表，支持回退；注册表本身是本机运行状态。
- **管理文件**：支持上传判重、替换、删除、任务进度查看和失败重试；管理页会话与个人 MCP 凭据用途分开，资料读取权限按请求复核。
- **交付证据**：MCP 新旧入口均返回检索证据，由客户端 Agent 生成最终回答；MCP 不替客户端判断证据是否充分。

## 主要数据流

```text
公开资料与版本清单
  → 按组织流程摆渡及校验
  → 文档解析 / 切分 / 向量与关键词索引
  → 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 说明](docs/mcp-stateless.md)。
- 管理界面可使用独立 SQLite 账号身份库，保存登录会话、个人 MCP 凭据哈希、资料库授权及身份审计；凭据原文仅在签发时展示。传统 `configs/access/` ACL 和私有索引配置是部署数据，不会因启用账号模式而自动迁移或放权。
- GPU 模型 API 每个服务进程使用单 worker FIFO；当前默认值为最多 8 个等待位（不含正在执行的请求），等待上限 30 秒，均可配置。它限制单次模型 API 调用的排队，不代表整条查询 SLA；配置说明见[双部署专题](docs/dual-deployment.md)。
- 可选本机完整 Docker 拓扑，或云端轻量 backend 连接私网 TLS 本机 GPU 模型节点。配置模板和隔离验收不等于云资源已购买、公网已部署或生产验收；宿主机、容器及 GPU 环境分别核实。

## 快速开始：轻量开发环境

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

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

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

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

## 部署与运行专题

- [Windows / Linux 环境说明](docs/environment.md)：主环境、运行前提和平台边界。
- [双部署说明](docs/dual-deployment.md)：本机完整栈与云端轻量 backend / 私网 GPU 节点配置。
- [Windows 交付、备份与恢复](docs/team-delivery-windows.md)：离线资产、隔离恢复和已验证范围。
- [Docker 部署专题](docs/docker-deployment.md)：现有 compose 与容器入口。
- [文件管理](docs/file-management.md) · [管理界面](docs/admin-frontend.md)：受管文件生命周期、账号和授权边界。
- [MCP 入口控制](docs/mcp-entry-control.md)：新旧入口配置和运行状态含义。
- [安全边界](SECURITY.md)：凭据、网络与访问控制说明。

## 文档导航

- [项目目标](PROJECT.md)：目标、教学与长期边界。
- [当前状态与下一步](code.md)：当前结论、限制和证据链接。
- [项目布局](docs/project-layout.md)：根目录职责及源码、模型权重和运行数据边界。
- [检索实验](docs/retrieval-experiments.md)：带日期的历史策略与评测结果。
- [MVP 验收](docs/acceptance.md) · [客户端验收](docs/claude-code-acceptance.md)。
- [开发记录索引](docs/development-log.md)：各轮变更与原始验收证据。

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

## 许可

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