Quivr 版本演进全解：从 CHANGELOG 读懂 RAG 平台的演化路线与自动化发布机制

本文以 Quivr 仓库根目录的 CHANGELOG.md 为主体，系统解读这份由 release-please 自动生成的 2810 行版本记录：包括每个版本条目的结构与阅读方法、主仓库（v0.0.43 → v0.0.293）与 quivr-core 包（core-0.0.2 → core-0.0.13）两条版本线的发布机制，以及从变更记录中还原出的 Quivr 从单 Brain 聊天工具演进为多 Brain RAG 平台的关键技术阶段。读完后，你可以掌握如何快速定位某个功能的落地版本、如何核对其对应的源码位置，以及如何复现 Quivr 的自动化 changelog 与发版流程。

这份 CHANGELOG 是什么：release-please 自动生成的版本账本

CHANGELOG.md 位于仓库根目录，全文按版本倒序排列，覆盖从最新的 0.0.293 (2024-07-30) 到最早的 0.0.43 (2023-07-26) 约 250 个版本。它不是人手撰写的，而是由 Google 的 release-please 工具链在每次 push 到 main 分支时自动维护的。理解它的自动生成方式，是正确阅读这份文件的先决条件。

每个版本条目的标准结构

CHANGELOG.md 中每个版本小节都遵循固定的三段式结构：

1. 版本头：## <版本号> (YYYY-MM-DD)，例如 ## 0.0.293 (2024-07-30)；
2. What's Changed：列出该版本内合入 main 的所有 PR，每条格式为 feat/fix(scope): 描述 by @贡献者 in <PR 链接>；
3. Full Changelog：指向两个版本 tag 之间的 compare 页面。

此外还偶见 ## New Contributors 小节，记录首次贡献者，例如 0.0.259 (2024-06-04) 条目中记录了 @AmineDiro made their first contribution。值得注意的是，早期版本（约 0.0.61 之前，2023-08-23 左右）条目形态略有不同：不再列 PR 清单，而是按 ### Features / ### Bug Fixes / ### Performance Improvements 分类列出 conventional commit 及其 commit hash，这正是 release-please 默认 notes 类型与 changelog-notes-type: github 两种输出风格的差异，后文会解释其成因。

自动化发布机制：两个 workflow 与两份配置

Quivr 仓库中存在两条并行的 release-please 流水线，对应 CHANGELOG 中两条版本线：

主线（根目录 CHANGELOG.md）：.github/workflows/release-please.yml 监听 push: branches: [main]，调用 release-please-action@v3 并显式传入：

• release-type: node（按 semver 规则处理版本号）；
• changelog-notes-type: github（以 PR 清单形式生成 What's Changed，即 0.0.293 之后看到的样式）；
• bump-patch-for-minor-pre-major: true（在 0.x 阶段，minor 级别的变更实际递增 patch 位，这解释了为什么版本号始终以 0.0.NNN 形式快速滚动）。

core 线（backend/core/CHANGELOG.md）：.github/workflows/release-please-core.yml 以 path: backend/core 指向 monorepo 内的 Python 包，其 deploy job 在 release_created == 'true' 时自动执行 poetry install && poetry build 并发布包。该线的行为由 release-please-config.json 定义：

{
    "packages": {
        "backend/core": {
            "release-type": "python",
            "package-name": "core",
            "bump-patch-for-minor-pre-major": true,
            "changelog-notes-type": "github",
            "include-v-in-tag": false,
            "tag-separator": "-",
            "component": "core"
        }
    }
}

其中 tag-separator: "-" 与 component: "core"、include-v-in-tag: false 组合，产出了 core 线 core-0.0.13 这种不带 v 前缀的 tag 命名，与主线 v0.0.293 形成对照。这条线的产物 backend/core/CHANGELOG.md 采用 ### Features / ### Bug Fixes 分类格式并附 commit hash（如 ## 0.0.13 (2024-08-01)），与主线的 PR 清单格式不同，是 release-please 默认 notes 风格。

支撑 changelog 质量的两个前置机制

自动生成的 changelog 能否可读，取决于合入 commit 的质量。Quivr 有两道保障：

• Conventional PR 标题校验：.github/workflows/conventional-pr-title.yml 对 PR 标题做 conventional commits 格式检查，因此 CHANGELOG 中 feat(sync): ...、fix(frontend): ... 这类带 scope 前缀的标题才能被 release-please 正确归类；
• 依赖自动更新：renovate.json 配合 CHANGELOG 中可见的 chore(deps): pin dependencies by @renovate、chore: migrate renovate config by @renovate 等条目，让依赖升级也进入版本记录。

版本号的“权威来源”在打包阶段与发布配置一致：例如 backend/core/pyproject.toml 中 version = "0.0.13"，与 backend/core/CHANGELOG.md 最新条目 0.0.13 (2024-08-01) 精确对应，可作为核对版本与 tag 的锚点。

演进时间线：约 370 天、250 个版本的技术脉络

CHANGELOG 的价值在于它完整记录了 Quivr 的决策与迭代顺序。下面按阶段归纳主版本线（每个阶段均标注 CHANGELOG 中的代表性版本与仓库中可核实的源码位置）。

阶段一（2023-07 ~ 2023-08）：基础设施、流式聊天与模型解耦

0.0.43 (2023-07-26) 至 0.0.68 (2023-09-06) 期间，CHANGELOG 显示了三条主线：

• 微服务化与部署：0.0.59 条目中出现 microservices: split into 4 quivr to better handle long services、aws: all in microservices、健康检查 endpoint 等，对应仓库中拆分出的 API / Celery 结构（backend/api/quivr_api/main.py、backend/api/quivr_api/celery_worker.py）；
• 聊天体验：0.0.47 加入 chat: added streaming，0.0.63 加入 # 触发 prompt，0.0.60 加入 mention 选择 Brain；
• 模型层解耦：0.0.68 的 feat(liteLLM): Add support for Azure OpenAI, Palm, Claude-2, Llama2, CodeLlama (100+LLMs) 标志着 LLM 接入统一到 LiteLLM，为“Any LLM”的产品主张打下基础，模型端点抽象在 backend/core/quivr_core/llm/llm_endpoint.py。

同期还有 repository pattern 引入（0.0.50：Introduce repository pattern to prepare adding other database providers），对应 backend/api/quivr_api/modules/base_repository.py，为后来切换到 SQLAlchemy 预留了接口。

阶段二（2023-08 ~ 2024-01）：Brain 概念确立与多租户

这一阶段的分水岭是 0.0.171 (2024-01-22) 的 feat: 🎸 brains：Quivr 从“一个知识库”重构为“多 Brain”模型，随后 0.0.169 支持多 Brain 组合提问。配套能力在 CHANGELOG 中依次出现：

• 0.0.161 (2024-01-07) feat: 🎸 policies——数据库行级安全策略，对应 backend/supabase/migrations/20240107231636_policies.sql 与 20240514080520_rls_optim.sql；
• 0.0.153 ~ 0.0.157 连续多条 feat: 🎸 posthog / feat: 🎸 usage / feat: 🎸 pricing——产品分析、用量计量与计费能力，对应 frontend/services/june 与 backend/api/quivr_api/routes/subscription_routes.py；
• 0.0.166 (2024-01-20) feat(search): new way to interact with Quivr——搜索页交互，对应 frontend/app/search/page.tsx。

阶段三（2024-02 ~ 2024-03）：自定义 Brain、集成与反馈闭环

• 自定义 Brain 上线：0.0.208 (2024-02-21) feat(frontend): first custom brain live 与 feat: implement elasticache（缓存层落地，Redis 配置见 backend/api/quivr_api/celery_config.py）；
• RAG 管道现代化：0.0.203 的 feat(lcel): migrated to lcel and pydantic 与 feat: 🎸 ocr，提示词模板重构后位于 backend/api/quivr_api/modules/brain；
• 检索排序改进：0.0.237 (2024-04-24) 之前的 feat(reranker): Add flashrank and contextual compression retriever、feat: Update chunk overlap to 200 等条目，与 docs/configuring/reranking.mdx 文档互为印证；
• 用户反馈闭环：0.0.226 (2024-03-21) 加入 thumbs for message feedback 与 Mistral 模型接入（前端模型清单见 frontend/helpers/defineMaxTokens.ts）、feat(frontend): dark mode。

阶段四（2024-04 ~ 2024-05）：Assistants、引用溯源与 RAG 评估

这个阶段 CHANGELOG 出现了明显的“能力扩张”：

• Ingestion → Assistants 重构：0.0.228 先加入 feat(ingestion): Add ingestion module and routes，0.0.229 (2024-04-12) 随即 feat: Add assistant module and remove ingestion module，最终模块落在 backend/api/quivr_api/modules/assistant，前端对应 frontend/app/assistants；
• RAG 评估：0.0.230 的 feat(backend): add RAG evaluation using Ragas，对应 backend/api/tests/ragas_evaluation/run_evaluation.py；
• 引用溯源：0.0.239 feat(citations): system added、0.0.241 feat(frontend): citations & sources，让回答可标注来源，是 RAG 产品可信度的关键一步；
• 文档解析升级：0.0.241 加入 LlamaParse 复杂文档解析、0.0.249 加入 Playwright 网页抓取、0.0.252 支持 gpt-4o；
• 工具化：0.0.250 加入 WebSearchTool（Brave 搜索）、图片生成，0.0.251 加入 URLReaderTool 与邮件工具，对应 backend/api/quivr_api/modules/tools。

阶段五（2024-06）：同步集成、monorepo 与 quivr-core 诞生

0.0.260 (2024-06-11) 至 0.0.275 (2024-06-27) 是全 changelog 中工程变化最密集的窗口：

• 云盘同步：Google Drive 与 SharePoint 授权链路（fix(google): auth is now in state、feat: Add force_sync option to SyncsActiveUpdateInput）、0.0.284 加入 Dropbox，前端入口在 frontend/lib/api/sync/sync.ts；
• 数据访问层切换：0.0.240 feat(backend): use SQLAlchemy instead od supabase API，仓库层落在 backend/api/quivr_api/models/sqlalchemy_repository.py；
• Monorepo 与 core 包：0.0.275 的 feat(backend): quivr-monorepo and quivr-core package 是架构级节点——RAG 核心被抽成独立可发布包 backend/core/quivr_core（含 brain、processor、storage 等子模块），从此 core 线开始独立发版；
• 异步任务与通知：0.0.242 的 RLS + realtime 通知（迁移脚本 backend/supabase/migrations/20240501180719_notifications.sql）、Celery 配置与重试逻辑（0.0.284：feat(celery): add retry logic for dcos）。

阶段六（2024-07）：quivr-core 版本线成熟与最新变更

主线 0.0.281 (2024-07-11) 起，CHANGELOG 中开始成对出现 chore(main): release core 0.0.N 条目，即 core 线发版（chore: Add release-please-core workflow and configuration files，见 0.0.281）。core 线 backend/core/CHANGELOG.md 的完整轨迹为 core-0.0.2 (2024-07-09) → core-0.0.13 (2024-08-01)，其中里程碑包括：

• 0.0.2：quivr-monorepo and quivr-core package 与 quivr core minimal chat；
• 0.0.5 ~ 0.0.8：chat history、ask streaming、Quivr chatbot 示例（backend/core/examples/chatbot/main.py）；
• 0.0.9：quivr api use quivr core——主仓库 API 开始依赖 core 包，验证了抽取的正确方向；
• 0.0.10 ~ 0.0.13：move parsers quivr core、processors registry（注册表实现见 backend/core/quivr_core/processor/registry.py）、tox 测试与解析器测试（测试集见 backend/core/tests/processor）。

主线最后几个版本则继续打磨产品：0.0.291 支持 Azure Drive Sites、0.0.292 处理 Azure 站点同步、0.0.293 (2024-07-30) 上线 brain carousel 及其反馈修复。

版本核对：如何验证某个功能落在哪个版本

基于 CHANGELOG 的记录规则，可以形成一套可操作的核对方法：

1. 按关键词定位版本：在 CHANGELOG.md 中检索功能关键词（如 citations、dropbox、lcel），第一个命中的版本头即为落地版本，日期在版本头括号内；
2. 交叉验证 tag 与包版本：core 线功能以 backend/core/CHANGELOG.md 为准，tag 形如 core-0.0.N（由 release-please-config.json 的 tag-separator + component 规则决定），且 backend/core/pyproject.toml 中的 version 字段应等于或高于最新已发布版本；
3. 注意格式分界：2023-08-23（约 0.0.61）之后的条目是 PR 清单式（changelog-notes-type: github），之前的条目是 commit 分类式，两种格式检索关键词的方式略有不同（前者含 PR 作者与标题，后者含 commit message 与 hash）；
4. 区分 Revert：changelog 中成对出现的 feat: ... 与 Revert "feat: ..."（如 0.0.255 中的 Google Drive 同步加入后立即 Revert）说明该功能在该版本实际未生效，引用时以后一条为准。

工程实践要点

从 CHANGELOG 与其配套配置中，可以提炼出几条对维护自身项目有参考价值的实践：

• changelog 零人工成本：release-please 以 PR 合入为唯一输入，版本说明、tag、Release 三件事在同一次 push 上完成（.github/workflows/release-please.yml），作者只需保证 PR 标题规范；
• PR 标题规范是 changelog 可读性的前提：scope 前缀（feat(sync)、fix(frontend)、chore(main)）让 250 个版本、数千条记录仍可按功能域快速过滤；
• monorepo 多包独立发版：通过 release-please-config.json 的 packages 字段为 backend/core 定义独立组件，主线与 core 线互不干扰地各自递增、各自发布（Python 包经 poetry build 发布）；
• 高频小版本优于低频大版本：0.0.43 → 0.0.293 约 370 天 250 个版本，意味着每个版本 diff 很小，定位回归（bisect）成本低。

需要说明的是：CHANGELOG 本身是机器生成的事实记录，其中每条 PR 标题、版本号与日期均可以直接采信；而本文对各阶段的归纳属于对变更记录的整理，具体实现细节以仓库中对应源码为准（上文各小节均已给出可核实的文件路径）。