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。