RAG Platform

面向中文知识库的隐私优先 RAG 系统：支持安全的多格式文档导入、向量与 BM25 混合检索、RRF 融合、可选重排序、证据路由、联网补充、带引用回答和有预算上限的研究模式。

仓库提供三个入口：面向普通用户的同源 Web 工作台、适合本地实验的 Gradio 工作台，以及具备租户隔离、鉴权、后台索引任务、持久化目录、限流、指标和安全错误协议的 FastAPI 服务。当前完整增强版位于 main 分支。

它同时是一个可派生的通用基座：产品名称、展示语和运行配置可在不修改 API 契约的前提下调整；行业特有的模型、数据、规则和 UI 应通过明确端口与独立评测集扩展。完整流程见派生项目定制指南。

项目标识与兼容性

• GitHub 仓库与发布名称：rag-platform。
• Python 分发包：rag-platform；稳定的 Python 导入命名空间仍为 rag_system，避免下游项目因品牌调整而破坏。
• 已安装的发行包提供 rag-platform-api 与 rag-platform-workbench 命令；从源码运行时使用等价的 python -m rag_system.server 与 python -m rag_system.workbench。
• v3 起只使用 rag-platform-data 卷、.rag-platform.instance 单节点锁和 rag-platform-* 浏览器会话键。升级前必须按运维手册完成停写、备份和经校验的数据卷复制；v2 入口、锁和会话不会被读取。

准备首个真实领域试点时，请遵循派生项目试点清单：项目提供评测和交付门禁， 但不会用仓库内通用样例伪造领域质量结论。

要在 fork 或副本中创建可同步上游的行业扩展层，可运行 python scripts\init_derivative.py --help；脚手架会在临时环境中通过真实 API 装配回归验证。用法与生成内容见派生项目脚手架。

模型与联网搜索适配器通过受校验的 ProviderFactory 注入；替换默认实现时，请同时遵循提供商适配器一致性，以保持启动失败关闭、引用边界和错误脱敏契约。

Web 工作台覆盖知识库创建、异步索引进度、知识库切换与删除、多轮问答、引用证据、检索路径，以及云端生成和联网搜索的请求级授权。访问密钥只保存在当前浏览器标签会话中，不会写入仓库或持久化到浏览器长期存储。

当前生产形态是 durable single-node，不是多副本高可用集群。SQLite、受限本地向量索引和上传原文必须位于同一个持久卷，API 只能运行一个 Uvicorn worker。能力边界详见部署说明。

核心能力

领域	已实现能力
文档摄取	TXT、Markdown、HTML、DOCX、PDF；大小、页数、字符数、压缩包膨胀和路径安全边界
检索	中文 Embedding、进程内余弦检索、BM25、RRF 融合、来源多样化、可选 CrossEncoder 重排序
回答	本地 / 混合 / 网络 / 拒答路由；请求级云端与联网授权；原子结论—证据结构化契约
研究模式	有界查询拆解、多查询检索融合、多次网络补充；无无限 ReAct 循环
会话	TTL、LRU、轮数与字符数上限；租户、知识库和浏览器会话三重隔离
数据生命周期	原子上传、SHA-256 清单校验、持久索引复用、残缺集合重建、耐久取消意图、显式删除
产品界面	同源 Web 工作台、拖放上传、任务进度、知识库管理、多轮问答、引用证据与隐私开关
服务边界	API Key / Bearer、reader / writer / operator、租户隔离、持久幂等、后台任务、限流
可运维性	liveness/readiness、隐私安全 JSON 事件、Prometheus 指标、Docker Compose、备份恢复手册
质量	检索 Recall/MRR/nDCG、回答事实/拒答/原子性/归因、逐题诊断、冻结质量门禁、Python 3.11/3.12 CI

架构

flowchart LR
    C["Web app / Gradio / REST client"] --> A["API boundary\nauth · roles · rate limit"]
    A --> P["Application platform\ntenant catalog · jobs · idempotency"]
    C --> S["RAG service"]
    P --> S
    P --> F["Tenant file store"]
    P --> Q["SQLite catalog"]
    S --> I["Ingestion\nsecure loaders · adaptive chunks"]
    S --> R["Hybrid retrieval\ndense · BM25 · RRF · rerank"]
    R --> V["受限本地向量索引"]
    S --> M["Bounded conversation memory"]
    S --> Z["Chat / web providers\nexplicit outbound consent"]

Loading

索引身份包含租户命名空间、文档内容、切分参数和 Embedding 模型。同一知识库在进程重启后可重新挂载已有向量；不同租户上传完全相同的文件也不会共享索引身份。

更完整的数据流、模块边界和非目标见架构文档。

本地向量索引的规模边界

当前密集检索后端是进程内 精确余弦扫描，优先保证单节点部署的 数据边界、可复现性与运维简单性。查询时间会随 chunk 数近似线性增加； 它不是 ANN，也不应被描述成适合任意规模或多副本部署的向量数据库。

在考虑替换后端前，先在目标机器运行下列无模型下载的微基准并保存 JSON：

python scripts\benchmark_local_index.py `
  --sizes 100,1000,5000 `
  --dimension 384 `
  --queries 30 `
  --warmup 5 `
  --require-clean `
  --json-output reports\local-index-boundary.json

该命令只测 LocalVectorIndex.search 的精确扫描与排序，明确排除文档解析、 Embedding、持久化、BM25、重排序、网络与并发。因此它用于判断何时需要通过 现有 IndexRepository / VectorIndex 接口引入新的 ANN 适配器，而不是对外 宣称端到端或生产 SLA。

JSON 报告会同时记录基准参数、Python/平台、可见 CPU 数、源码提交和工作区是否干净；比较不同机器或 不同版本的数值前必须先核对这些字段。用于正式比较的报告应使用 --require-clean，且仍不能将该微基准解释为端到端 SLA。

派生项目如需替换为 ANN 或托管向量库，应在组合根注入既有 IndexRepository 契约，而不是修改 API 或把供应商 SDK 扩散到业务层；约束与验收清单见向量后端扩展契约。

首次可复核的本机边界测量及其环境、命令和限制见 本地精确索引规模记录。

本地工作台

要求 Python 3.11 或 3.12。Windows PowerShell：

git clone https://github.com/XWsight/rag-platform.git
cd rag-platform
git switch main

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
powershell -ExecutionPolicy Bypass -File scripts\bootstrap_dev.ps1
Copy-Item .env.example .env

初始化脚本默认创建 Python 3.11 的 .venv，按哈希锁安装运行时与开发工具，安装当前源码包、 Node 依赖和 Chromium。需要 Python 3.12 时传入 -PythonVersion 3.12；只准备 Python 环境时可传入 -SkipBrowser。脚本不会删除或覆盖已有 .venv。

浏览器端关键流程使用 Playwright 对真实 HTTP API 运行回归，而不是在测试中替换 fetch。首次准备一次浏览器运行时后即可执行：

npm ci
npx playwright install chromium
npm run test:browser

它覆盖访问密钥连接、文档上传和索引完成、问答与引用、资料详情、会话清空、删除，以及云端授权默认关闭与显式确认。scripts/check.ps1 也会运行该套件。 浏览器脚本优先使用 .venv；未创建时 Windows 会尝试已安装的 Python 3.11。也可以通过 $env:PYTHON='C:\path\to\python.exe' 显式指定 Python 3.11/3.12 解释器。缺少 Playwright 依赖时，脚本会提示先执行 npm ci。 Node 工具链固定为 Node 24 与 npm 11；npm ci 会拒绝不匹配的锁文件。 依赖漏洞审计默认最多运行 120 秒；网络受限或 CI 环境可用 python scripts\audit_dependencies.py --timeout-seconds 180 在 30–300 秒内调整，超时仍会失败关闭并回收子进程。

如果需要云端生成或联网搜索，再在 .env 中配置：

ZHIPU_API_KEY=你的智谱密钥
ZHIPU_MODEL=glm-5.2

不配置密钥也能使用本地检索模式。RAG_ALLOW_CLOUD_DEFAULT 与 RAG_ALLOW_WEB_DEFAULT 只控制 Gradio 开发工作台的初始勾选状态；正式产品界面为同源 Web 工作台 /app，REST API 始终要求每次请求显式授权。关闭时，问题与文档证据不会被发送到相应外部服务。

开发调试工作台（Gradio，不作为正式产品 UI）：

$env:NO_PROXY = "127.0.0.1,localhost"
$env:no_proxy = "127.0.0.1,localhost"
python -m rag_system.workbench

访问 http://127.0.0.1:7860。首次使用默认 Embedding 模型时需要下载模型文件。正式部署统一使用下方 FastAPI 的 /app Web 工作台；新功能应优先进入该界面，避免双 UI 行为分叉。

持久化 API

在 .env 中使用高熵 API Key 配置租户主体，并启用持久化：

RAG_PERSIST_DATA=true
RAG_STORAGE_ROOT=.rag_data
RAG_API_KEYS_JSON={"替换为至少16字符的随机密钥":{"subject":"local-admin","tenant_id":"local","roles":["reader","writer","operator"]}}

启动单 worker 服务：

python -m rag_system.server --host 127.0.0.1 --port 8000

主要端点：

方法	路径	角色	用途
GET	/health/live, /health/ready	公开	存活与就绪检查
POST	/v1/knowledge-bases	writer	上传并异步建立知识库，需要 Idempotency-Key
GET	/v1/knowledge-bases	reader	列出本租户知识库
GET/DELETE	/v1/knowledge-bases/{id}	reader / writer	查询或完整删除资源
GET/DELETE	/v1/jobs/{id}	reader / writer	查询或取消后台任务
POST	/v1/answers	reader	检索、路由并回答
DELETE	/v1/knowledge-bases/{id}/sessions/{session}	writer	清除一段对话记忆
GET	/metrics	operator	Prometheus 文本指标

每个受保护请求只能提供一种认证方式：X-API-Key 或 Authorization: Bearer。Idempotency-Key 必须是 8–128 个可打印 ASCII 字符；在 24 小时有效窗口内，相同键与相同请求会返回原资源，同一键绑定不同请求会安全地返回冲突。窗口过期后，该键会被视为新的创建请求。

索引取消采用两层状态：平台会先把可取消知识库的 Catalog 状态从 PENDING/INDEXING 耐久写为 CANCELLING，成功后才向进程内 worker 发出取消信号。意图写入失败时 API 返回 503、worker 不会收到信号，调用方应使用同一 job ID 重试。排队 job 可能立即变为 cancelled；运行中 job 先变为 cancelling，只有 worker 实际退出后才释放任务容量。知识库通常收敛为 FAILED/index_cancelled；若终态写入中断，启动恢复或同一创建请求的幂等重放会完成收敛。旧 worker 不会恢复执行，但其快照在有界保留期内仍可查询；必要时重放会轮换并绑定一个新的可轮询 job。

如果知识库已经耐久提交为 READY，取消请求已经太迟：Catalog 保持 READY，job 可能短暂显示 cancelling，但已完成的任务最终记为 succeeded。Catalog 当前使用 schema v4：上传先进入 PREPARING，绑定一次性不可变清单，全部文件落盘核验后才进入 PENDING。启动时会事务化迁移 schema v2/v3；升级前仍须停写备份，旧程序不能直接读取迁移后的 v4 Catalog。

ready 验证文档存储根、Catalog、向量目录、任务执行器和耐久 job 快照库；它不加载可选模型、不执行向量查询，也不探测外部供应商。调用方仍需处理单次检索、模型下载或上游服务失败。

正式 Web 工作台位于 http://127.0.0.1:8000/app，根路径会自动跳转到该页面。OpenAPI 位于 http://127.0.0.1:8000/docs；生产环境可设置 RAG_API_DOCS_ENABLED=false。

Docker 部署

cp .env.example .env
# 编辑 .env 后：
docker compose config --quiet
docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/health/ready

容器健康后，浏览器访问 http://127.0.0.1:8000/app。首次进入时粘贴 .env 中配置的租户 API Key；密钥仅在当前标签会话中保存。

Compose 默认仅发布到 127.0.0.1，使用非 root 用户、只读容器根文件系统、最小权限、资源上限、日志轮转和 /data 持久卷。公网访问必须由可信反向代理终止 TLS。备份、恢复、升级、回滚、密钥轮换和删除要求见部署说明与运维手册；Prometheus 抓取与告警的受控部署方式见监控说明。

本地开发可使用 .env；生产容器应优先使用只读文件挂载的 RAG_API_KEYS_JSON_FILE 与 ZHIPU_API_KEY_FILE，避免原始密钥留在容器环境变量中。Docker Compose 覆盖示例、文件安全 边界与轮换步骤见密钥来源说明。

运行时直接依赖保存在易审查的 requirements.txt，其完整传递闭包与 SHA-256 哈希按受支持 Python 小版本固定在 requirements-py311.lock 和 requirements-py312.lock。requirements-lock.in 在这份通用审计输入之外，明确 CPU-only 部署所需的 torch wheel 选择。安装生产依赖时选择当前解释器对应的锁文件，例如 Python 3.11 使用 python -m pip install --find-links https://download.pytorch.org/whl/cpu/torch/ --require-hashes -r requirements-py311.lock；修改直接依赖后，分别以 uv pip compile requirements-lock.in --generate-hashes --python-version 3.11 --python-platform linux --index https://download.pytorch.org/whl/cpu --default-index https://pypi.org/simple --index-strategy unsafe-best-match --output-file requirements-py311.lock 和对应的 3.12 命令有意更新锁文件，并在相应解释器中运行 python scripts\verify_dependency_lock.py。这里的专用 torch 索引与 PyPI 一起参与解析，且锁文件必须保留每个候选制品的哈希。准备发布时可运行 python scripts\release_manifest.py --require-clean --json-output reports\release-manifest.json，记录源码提交、包版本和 Docker/Compose/依赖清单的 SHA-256。CI 还会从干净的锁定运行时环境生成 SPDX 2.3 SBOM 工件；稳定发行还会附上不可变 OCI image@sha256:... 引用、BuildKit provenance、镜像 SBOM 与 Sigstore keyless 签名。验证者应始终针对 digest（而非 latest）验证签名和 provenance；它们不会读取 .env，也不等同于运行时密钥管理。

验证与评测

python -m unittest discover -s tests -v
python -m compileall -q rag_system tests scripts
python scripts\benchmark_sparse.py evals\retrieval_cases.jsonl `
  evals\corpus\rag.md evals\corpus\retrieval.md `
  evals\corpus\safety.md evals\corpus\storage.md `
  --top-k 5 `
  --quality-gate evals\gates\bm25-smoke.json `
  --json-output reports\bm25-smoke.json `
  --markdown-output reports\bm25-smoke.md

当前 ground truth 摘要 74fe19194ca06876 的 18 题开发集上，依赖无关 BM25 冒烟基线为 Recall@5 1.0000、MRR@5 0.9583、nDCG@5 0.9692、路由准确率 0.8333。这个小型、仓库内开发集只用于回归，不能外推为真实业务效果，引用指标也不适用于该检索集。

报告同时列出每题的缺失相关来源、期望/实际路由、首个相关排名、置信度和延迟，并汇总 P50/P95/P99。冻结门禁会校验数据集摘要、top-k 和最低指标；依赖无关的 BM25 门禁由本地检查与 GitHub CI 自动执行。延迟受硬件和缓存影响，当前只报告、不作为跨机器硬门槛。

正式检索回归套件使用严格 manifest 管理 54 个语义家族、216 个问题、10 篇来源和 12 个类别。开发/验证/test 分段分别为 88/68/60 题，相关来源文档禁止跨分段复用；本地、拒答和联网路由分别为 160/36/20 题。新增普通世界知识、无关理工/生活问题和不支持的外部动作，防止阈值只对隐私及时效负例过拟合。校验器会拒绝规范化重复问题、缺失或越界来源、错误路由标签、来源泄漏和覆盖不足：

python scripts\validate_retrieval_suite.py evals\retrieval_suite.json `
  --contract evals\gates\retrieval-suite.json
python scripts\benchmark_sparse.py evals\retrieval_suite.json `
  --top-k 5 `
  --quality-gate evals\gates\bm25-foundation.json `
  --json-output reports\bm25-foundation.json `
  --markdown-output reports\bm25-foundation.md

当前 suite/corpus bundle 摘要为 e75fb276b6a2a227，题目 ground truth 摘要为 2f40b11e574096d0。全语料 BM25 下限为 Recall@5 0.9844、MRR@5 0.9568、nDCG@5 0.9592、总体路由准确率 0.9722、拒答路由准确率 0.8611。--split development|validation|test 可以只运行一个来源隔离分段；同义问法用于鲁棒性覆盖，因此 216 题应同时报告为 54 个独立语义家族，不能包装成 216 个独立知识点。

受治理的检索运行会额外输出期望/实际路由混淆矩阵，以及 split、category、difficulty、expected route 四个维度的质量切片。每条预测还包含不含问题或文档正文的路由信号：首名/次名分数、分差、稠密与稀疏排名一致性、词法支撑度和最终置信度。这些信号用于定位阈值与特征问题，不得记录检索正文，也不能通过只展示高分切片掩盖失败。

真实混合检索需要安装运行依赖后执行：

python scripts\benchmark_retrieval.py evals\retrieval_cases.jsonl `
  evals\corpus\rag.md evals\corpus\retrieval.md `
  evals\corpus\safety.md evals\corpus\storage.md `
  --top-k 5 `
  --quality-gate evals\gates\hybrid-development.json

在当前本地模型标识与默认配置下，当前 18 题 Hybrid 开发基线的 Recall@5、MRR@5、nDCG@5 和路由准确率均为 1.0000。该门禁需要下载并运行 Embedding 模型，因此是发布前手动门禁，不在默认 CI 中执行。该集合专门加入了语义改写、本地越界和必须联网的对抗题，仍然只是开发回归证据，不是生产质量或真实业务泛化证明。

216 题套件的真实 Hybrid 全语料基线为 Recall@5 0.9844、MRR@5 0.9536、nDCG@5 0.9537、总体路由准确率 0.9907、拒答路由准确率 0.9722，冻结在 evals/gates/hybrid-foundation.json。查询能力意图与证据置信度已经分层：实时信息、未授权外部动作和受限请求先经过确定性能力边界，普通知识问题才使用校准到 0.59 的检索置信度。该门禁只手动运行，不因结果较大就替代 18 题秒级回归。

按来源隔离的本地实测中，development 88 题为 Recall@5 1.0000、MRR@5 0.9818、nDCG@5 0.9766、路由 1.0000；validation 68 题为 1.0000、0.9792、0.9812、1.0000。首次冻结后的 test 得到 Recall@5 1.0000、MRR@5 0.9896、nDCG@5 0.9923、路由 0.9167，暴露医疗诊断和密钥提取能力边界后，该公开 test 已被消费并降级为回归集；后续改进不得继续把它称为无偏盲测。

检索消融运行器在同一个索引上比较 Dense、BM25、融合、来源多样化和可选重排，并以轮转顺序重复执行，拒绝同一变体在重复运行中产生不同预测。报告绑定 suite、ground truth 和无敏感配置摘要，列出质量差值、相对延迟以及新增/修复的 case ID：

python scripts\ablate_retrieval.py evals\retrieval_suite.json `
  --split development `
  --repetitions 3 `
  --json-output reports\ablation-development.json `
  --markdown-output reports\ablation-development.md

融合权重实验必须给四个归一化分量 dense:sparse:lexical:rrf，先在 development 筛选，再把唯一候选带到 validation：

python scripts\ablate_retrieval.py evals\retrieval_suite.json `
  --split development `
  --profiles fusion-diverse `
  --fusion-weight bm25-05:0.50:0.05:0.25:0.20

当前实验中，5% BM25 强度候选在 development 保持 Recall/路由不变并把 MRR 从 0.9818 提升到 0.9844，但在 validation 的四项质量指标均与默认方案相同。由于没有独立盲测增益证据，生产默认权重仍保持 0.55 dense + 0.00 sparse + 0.25 lexical + 0.20 RRF；不能把“验证集无退化”包装成“新方案已证明更优”。实验延迟只用于同机相对比较，不是 SLA。

云端生成不再把引用关系藏在自由文本中。模型必须返回由原子 claims、每条结论的 citation_ids 和明确的 insufficient 状态组成的 JSON；供应商适配器与应用服务会分别校验同一证据契约，API 同时返回可直接审计的 claims 映射和兼容展示用文本。该机制保证引用 ID 存在且每条生成结论都有归因，但不等于语义蕴含或事实正确性已经被证明。

结构化回答另有独立的真实模型基准，不复用检索成绩：

python scripts\validate_answer_suite.py evals\answer_suite.json `
  --contract evals\gates\answer-suite.json

受治理的回答套件包含 50 个独立问题、70 个原子事实、35 个可回答样例和 15 个拒答样例，覆盖 13 个类别与 15 个风险标签；development/validation/test 为 20/15/15。套件摘要 89e99234c8b10102 会冻结完整证据、事实标注和覆盖矩阵，默认 CI 只做确定性校验，不调用云端模型。真实运行报告除总体指标外，还会自动生成 split、类别、难度和风险标签四个维度的质量切片、严格通过数与失败 case ID，避免平均分掩盖局部退化。

python scripts\benchmark_answers.py evals\answer_cases.jsonl `
  --dotenv .env `
  --quality-gate evals\gates\answer-live.json `
  --json-output reports\answers-live.json `
  --markdown-output reports\answers-live.md

修改生成协议或提示后，可以先在 development 分段运行完整套件；这会产生真实 API 调用与费用，因此保持手动触发：

python scripts\benchmark_answers.py evals\answer_suite.json `
  --split development `
  --dotenv .env `
  --json-output reports\answers-development.json `
  --markdown-output reports\answers-development.md

2026-08-11 的一次 4 题/8 原子事实开发运行中，结构契约、拒答、事实召回、原子结论和归因五项均为 1.0000。这是会受模型版本与随机性影响的手动发布冒烟结果；门禁最低值为 0.75，不在默认 CI 中执行，也不能外推为生产准确率。

评测协议、数据泄漏防范与阈值校准见评测文档，数据标注与 split 治理见评测数据说明。仓库中的 evals/sample_dataset.jsonl 是评测格式夹具，不是系统性能证明。

项目结构

rag_system/
  application.py      # 与 HTTP/CLI/Agent 无关的应用用例端口和稳定错误
  api.py              # REST 路由、鉴权、角色、限流和安全响应策略
  api_contract.py     # 版本化 HTTP schema 与领域到 wire 的投影
  api_errors.py       # 应用失败到公共 HTTP 错误的集中映射
  web_ui.py           # 同源产品界面的安全挂载与响应头
  web_ui/             # 知识库管理、任务进度、问答和引用展示前端
  rag_platform.py     # 应用门面：多租户用例、幂等与恢复编排
  runtime_bootstrap.py # 默认 Profile 的受控组合根与启动恢复
  knowledge_base_lifecycle.py # 建库、删除、取消、幂等重放与恢复编排
  answer_workflow.py  # 问答容量控制、索引恢复与会话隔离
  submission.py       # 上传物化、大小策略、请求摘要和文档 ID
  coordination.py     # 有界分片锁与双向 resource-job 登记
  knowledge_base_assets.py # 文档清单、存储结果、路径和内容一致性边界
  indexing.py         # 耐久索引状态机、取消语义和失败补偿
  catalog.py          # SQLite 知识库目录与状态机
  idempotency.py      # 持久化幂等 reservation
  file_store.py       # 租户隔离、原子且有界的上传存储
  ingestion.py        # 安全文档加载与确定性切分
  retrieval.py        # 受限本地向量索引、混合检索和索引持久化
  routing.py          # 查询能力意图、证据置信度和可审计路由决策
  benchmark.py        # 检索指标、逐题诊断与延迟分位数
  benchmark_suite.py  # 评测家族、覆盖矩阵、来源隔离和泄漏校验
  retrieval_analysis.py # 检索切片、路由混淆矩阵和置信信号诊断
  retrieval_experiments.py # 多变体轮转消融、确定性检查和逐题增益/退化报告
  evaluation_suite.py # 检索/回答套件共享的严格 schema、摘要与冻结契约
  answer_suite.py     # 结构化回答证据、事实、split 和风险覆盖治理
  answer_analysis.py  # 回答质量切片、失败定位和可审计报告
  quality_gate.py     # 绑定数据集的严格回归门禁
  answer_benchmark.py # 结构化回答事实、拒答、原子性与归因评测
  answer_quality_gate.py # 绑定回答数据集的手动发布门禁
  answer_protocol.py  # 可替换的提示、证据边界与严格输出解码协议
  provider_errors.py  # 应用层与外部服务适配器共享的稳定失败契约
  json_contract.py    # 拒绝重复键和非有限值的严格 JSON 边界
  rag_service.py      # 检索、联网、研究模式、引用和会话编排
  grounding.py        # 原子结论、证据归因校验与稳定渲染
  metrics.py          # 有界 Prometheus 指标
  observability.py    # 不记录问题/文档正文的结构化事件
evals/                # 标注检索集、离线评测夹具与冻结质量门禁
scripts/              # 基准、校准和质量检查入口
tests/                # 单元、隔离、并发、故障与 API 契约测试

安全与边界

• 上传内容、网络摘要和检索片段全部视为不可信数据；系统提示明确禁止执行证据中的指令。
• API 不回显供应商响应体、内部路径、租户 ID、内部索引 ID、问题正文或文档正文到日志。
• 网络搜索会发送问题，云端生成会发送问题与选中证据；两条出站路径分别授权。
• 会话、可执行任务队列和限流状态仍为进程内状态；job 快照/ID 已有租户隔离的 SQLite 有界归档。重启不会继续执行旧 worker，而会把其中断快照安全终态化，先核验或回滚 PREPARING，再按 Catalog 重新提交 PENDING/INDEXING，并把耐久 CANCELLING 收敛为 FAILED/index_cancelled。这仍不是分布式任务系统。
• “删除”是应用层逻辑删除与文件删除，不等于 SSD、快照和离线备份的介质级不可恢复擦除。

威胁模型、残余风险和安全报告流程见安全设计与安全策略。

向量存储边界：本项目不再依赖或暴露 ChromaDB。当前后端是带清单校验和原子写入的受限本地 JSON 向量索引，执行精确余弦搜索；它适合受控单进程部署，不是 ANN 或多节点向量服务。

当前非目标

• 多副本写入、跨可用区容灾和零停机滚动升级
• 任意代码执行、自动训练或无边界自主工具循环
• 未经人工评审的自动科研结论或自动投稿
• 用代码行数、测试数量或开发集得分代替真实负载与领域验收

下一阶段的规模化路径是把目录、向量服务、任务队列、会话和限流依次迁移到外置共享基础设施，并先补齐迁移工具、故障演练和多租户负载测试。

贡献与许可

版本变化见 CHANGELOG.md，稳定发布与兼容性政策见 RELEASE.md，贡献流程见 CONTRIBUTING.md。本项目使用 MIT 许可证。