v0.2.1-beta.3

v0.2.1-beta 发布说明（标签 v0.2.1-beta.3）

发布日期：2026-08-26
发布类型：Beta 补丁版本

v0.2.1-beta 聚焦发布链路、离线可靠性和依赖安全，不改变主要 API 或数据格式。现有 v0.2.0-beta 部署可直接升级，但升级前仍建议备份 backend/data/ 和外部 Qdrant 数据。

实际发布标签为 v0.2.1-beta.3。v0.2.1-beta、v0.2.1-beta.1 与 v0.2.1-beta.2 是保留用于审计的失败候选标签，未创建 GitHub Release；.3 仅表示发布门禁与评测 provenance 修订，不改变应用 API 或数据版本。

主要变化

• Token 计数器改为延迟初始化；tiktoken 缓存不可用时使用保守的 UTF-8 字节计数，离线启动和测试收集不再依赖网络；
• 流式回答结束时对“事实正确但个别声明缺少紧邻引用”的情况执行确定性补引；该步骤不调用模型、不改事实文本，且只接受质量指标不退化的结果；
• 引用验证器会先分离回答正文与尾部来源展示区，兼容中英文、标题与链接同行、来源 ID 位于 Markdown 链接目标等格式，以及不依赖“文档/文件”等固定结尾的指代性来源归属句；只有在前文存在已引用事实且展示内容位于回答尾部时才忽略该区域，独立的文件来源回答及其后的实质文本仍会正常校验；
• 中英文会话式礼貌收尾不再被误判为知识库事实；规则仅接受完整匹配的提问或帮助邀请，带时限、政策、数字及其他实质内容的条件句仍必须接受引用与证据校验；
• 补齐 MAX_LOOP_HARD_ITERATIONS 环境变量示例，恢复配置同步检查；
• 后端生产代码覆盖率门禁提高到 70%，并统一仓库根目录与 backend/ 目录下的覆盖率统计；
• CI 增加 npm 生产依赖高危漏洞门禁，修复 nanoid 已知漏洞，并更新 undici；
• Node.js 最低版本提高到 22.22.0，CI 和 Docker 构建使用明确的 Node 22 版本；
• Dependabot 对 minor/patch 更新分组并限制并发 PR，减少维护噪声；
• Docker E2E 显式覆盖开发端口，并在构建前检查最终 Compose 配置，避免 8000/5173 端口冲突；
• 评测 provenance 的文本哈希统一换行符，发布报告可在 Windows 与 Linux 之间稳定复核；E2E 未启动时不再产生误导性的空 artifact 错误；
• 发布 Docker E2E 改为本地持有密钥、提交脱敏且绑定源码树的 12 阶段证据，GitHub 标签门禁不再保存或读取模型 API 密钥；
• Grounding 校验新增受限的定义、结构化请求和比较证据摘录，避免无证据补全以及低收益 LLM 修复；
• Grounding 修复超时由 4 秒收紧到 3 秒，评测调用的输出 token 上限与生产配置保持一致；
• README、贡献指南、项目介绍、项目参考、来源说明和变更日志同步更新。

发布验证

门禁	结果
GitHub Actions 首轮 CI	通过（run #86）
后端离线回归	1,026 passed / 11 skipped / 9 deselected
后端生产代码覆盖率	73.13%
Agent 专项测试	426 passed
前端 Vitest	70 / 70 passed
Ruff / MyPy / Oxlint / TypeScript build	通过
Python 运行时与开发依赖审计	0 个已知漏洞
npm 生产依赖审计	0 个已知漏洞
Docker E2E	12 / 12 阶段通过
Docker 严格冒烟测试	5 / 5 通过
回答忠实度 / 引用精确率	100.00% / 99.62%
拒答准确率 / 预期事实召回	100.00% / 85.21%
总延迟 P95 / P99	4,759.69 / 5,812.07 ms
Grounded-answer Release Gate	质量与性能门禁均通过

Docker 验收覆盖镜像构建、健康检查、鉴权、文档上传与双索引一致性、两条真实 SSE 引用问答、重启持久化、备份恢复、Qdrant 降级与恢复。验收使用仓库外部配置的模型服务，不在报告或镜像中保存密钥。

Grounded-answer 正式报告来自最后一次完整在线运行，并保留真实 draft、TTFT 与模型调用记录。两个 LLM 修复在超时前没有产生替换文本，因此仅对其本地后处理阶段按当前确定性策略进行了显式标记的 replay；范围和记录均保存在报告 provenance 中。

升级方式

使用源码构建：

git fetch --tags
git checkout v0.2.1-beta.3
docker compose --env-file backend/.env up -d --build

使用 GHCR 镜像：

docker compose --env-file backend/.env -f docker-compose.ghcr.yml pull
docker compose --env-file backend/.env -f docker-compose.ghcr.yml up -d

升级后检查：

GET /api/health
GET /api/health/dependencies

兼容性与已知限制

• 推荐 Python 3.12；前端开发和源码构建要求 Node.js 22.22.0 或更高版本；
• 当前仍定位为单租户、单实例 SQLite 写入，不承诺多实例并发写入或高可用；
• OCR、Reranker 和 Web Search 为可选能力，需单独安装依赖或配置外部服务；
• 公开质量结果基于合成评测集，不等同于所有真实业务文档和模型供应商组合均已验证。

完整变更见 CHANGELOG.md，安全报告流程见 SECURITY.md。

v0.2.0-beta — Agent 自主推理重构

v0.2.0-beta: Agent 自主推理重构

首个 Beta 候选版本，Agent 从规则驱动转向模型自主 ReAct 推理。

重大变更

• Agent 放权：删除意图分类规则层，工具选择交由模型 ReAct 自主决策
• 系统提示词重写：从"规则手册"改为"角色+能力+原则"
• 联网搜索升级：KB 不足时 Agent 可自主升级到 web_search
• Safety guard 放权：从正则替换答案改为通知式

新增

• JWT Access Token + HttpOnly Refresh Cookie 登录
• 用户自行修改密码，旧 Refresh Token 自动失效
• 会话持久化、上下文压缩
• Docker Compose 冒烟测试 + E2E 验收脚本

CI 状态

Job	状态
secret-scan	✅
backend-static (ruff+mypy)	✅
backend-tests (921 tests)	✅
security	✅
frontend-quality	✅
docker-smoke	✅
compose-smoke	✅
docker-push	✅

验证结果

指标	结果
回答忠实度	98.48%
引用精确率	97.73%
引用召回率	98.18%
拒答准确率	100.00%

已知限制

• 单租户/小团队场景，非企业级多租户
• SQLite + 本地存储，不适合水平扩展
• 依赖外部 LLM 和 Embedding API

---

🐳 Docker 镜像: ghcr.io/momom101/rag-reactagent/backend:latest

v0.1.0-beta — 首个公开候选版本

v0.1.0-beta — 首个公开候选版本

RAG-ReActAgent 的首个公开 Beta 版本：基于 ReAct（推理+行动）Agent 循环的检索增强生成系统，支持多跳推理和智能问答。

核心特性

• ReAct Agent 循环：迭代式推理-行动框架，规划→检索→综合→评估，跨多步自主完成问答
• RAG 流水线：完整的检索管道——文档加载、语义分块、嵌入生成、Qdrant 向量检索
• 混合检索与重排序：语义 + BM25 关键词（SQLite FTS5）RRF 融合，Cross-Encoder 重排序
• 意图分类：自动查询类型检测，选择最优检索策略
• 有据回答生成：每个事实引用具体来源 [S数字]，支持 Markdown 格式化输出
• 会话与记忆：多轮对话上下文管理，用户个人信息自动提取与持久化
• JWT 认证：Access Token + HttpOnly Refresh Cookie，基于角色的访问控制，刷新令牌轮换
• 多格式文档：PDF、DOCX、TXT、Markdown、CSV、XLSX 入库，图像 OCR（DocTR）
• REST API：FastAPI 后端，聊天、文档管理、用户管理、备份恢复等完整端点
• 前端界面：React + TypeScript SPA，支持实时 SSE 流式回答
• CI/CD：GitHub Actions 全流程（lint、test、docker-smoke、compose-smoke、docker-push）

技术栈

Python FastAPI Qdrant SQLite FTS5 React TypeScript JWT SQLAlchemy Alembic Docker

注意事项

这是 Beta 版本，API 和数据结构可能在 v1.0 之前发生变化。欢迎反馈和贡献。