quivr

机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

Quivr V2

一个将连续内容流转化为搜索和监控的开源引擎。

Quivr V2 持久化地摄取内容，使其在几秒钟内可搜索，在后台进行丰富处理，并允许你随时间跟踪某个主题。核心保持通用：格式、AI 模型和业务规则属于插件，因此你可以在不分叉平台的情况下将 Quivr 适应你的领域。

状态：评估阶段。 API 是 v0，可能会随时更改。尚不建议在生产环境中运行。

为什么选择 Quivr V2

• 以持久为先，而非速度优先。 写入仅在提交后被确认；故障会延迟处理，但绝不会丢失或悄无声息地失败。
• 处处幂等。 每次写入都带有幂等性键。重放返回相同结果，修改后的重放产生冲突，更正则创建新的不可变版本，而不是覆盖历史。
• 早期就有用，后期更丰富。 文本一经分段即可按词汇搜索；嵌入和其他丰富处理随后到达，不会阻塞。混合搜索在向量重建时保留关键词结果，并报告受影响的语料库。
• 可重建索引。 PostgreSQL 和 S3 保存规范数据；搜索索引是可从持久化工件重建的投影。
• 真实搜索。 每个命中都从规范存储中重构并重新授权。依赖故障时返回错误，而不会返回空的“成功”。
• 通用核心，可扩展边缘。 连接器、标准化器、丰富器、检索器和交付通道是插件功能，而非核心代码。

架构一览

flowchart LR
    client[Client / connector] -->|REST v0| api[Go API]
    api -->|commit receipt + intent| pg[(PostgreSQL<br/>catalog, receipts, changes)]
    api --> temporal[Temporal]
    temporal --> worker[Go worker]
    worker -->|canonical bytes, artifacts| s3[(S3-compatible storage)]
    worker -->|segments| weaviate[(Weaviate<br/>lexical + vector)]
    worker -->|text parts| ingest[core.ingest plugin]
    ingest -->|passages| tei[TEI · E5 embeddings]
    api -->|search, rehydrate, recheck| weaviate
    api -->|changes: polling / SSE| client

单个 quivr 二进制文件提供 api、worker 和 migrate 命令。

快速开始

要求（Linux x86_64，或苹果硅的 macOS 用于 make dev）：Go 1.27.2，带 Compose v2 的 Docker，带 venv 的 Python 3，Node.js 22 和 jq。第一次运行会下载固定镜像和 E5 模型（约 1 GB）。

make dev      # start dependencies, run migrations, launch API + worker
make check    # docs, contracts, vet and unit tests without Docker (about 2 min); run before pushing
make verify   # make check, then end-to-end journeys on an isolated stack
make down     # stop everything, keep data (make reset also deletes volumes)

make verify 运行每个功能的验收测试套件以及在隔离堆栈上的一次完整监控流程。它只删除自己的项目，即使在失败或按下 Ctrl C 后也是如此。然后，它会打印一个 report.md 的路径，该路径标明任何失败步骤、固定的版本以及依赖清单。它仅在 Linux x86_64 上运行，如同在 CI 中；请参阅 剩余限制。

make dev 打印 API 地址以及生成的、包含临时本地密钥的 config.json 路径；eval "$(make -s env)" 导出地址、一个密钥和一个 webhook 目的地。然后按照 快速入门 ：创建一个语料库，添加一篇文章，搜索它并获取提醒，make verify 会针对真实堆栈重放这些命令。

对于同一 API 的浏览器 UI，运行 make demo 并打开 http://127.0.0.1:5183（见 quivr-search/）。

当前可用功能

• 在一台机器上运行 Quivr，使用发布镜像和一个 Compose 文件，CPU 嵌入、持久存储以及可选的演示界面。

• 在专用主机上运行向量索引，支持经过身份验证的 HTTPS、持久数据盘，以及幂等的 Azure CLI 部署示例。

• 重置并重新加载安装，使用私有 JSON 声明，带预览和幂等的公共 API 重放。

• 选择嵌入模型 用于本地推理、自己的模型服务器或托管 API，带重建要求和仅执行调优。运行大规模导入 涵盖批量工作器、提供商容量、数据库大小及队列监控。

• 搜索报告查询模型故障为可重试 503 model_unavailable ，与超载和其他搜索依赖故障分开。参见 搜索错误。

• 工作器自动扩缩 按批量或实时队列积压情况进行，使用 KEDA、 quivr-autoscaler 二进制文件（Kubernetes 或 Railway）或手动操作。实时工作器保持独立容量。

• 滚动应用升级使用增量模式扩展；破坏性清理仅在 quivr migrate --contract 下运行。API 和工作器在后台构建重试性能索引，因此它们繁忙的索引构建不会延迟启动。旧的二进制索引构建仍可持有迁移锁，直到完成或被停止。CI 检查 merge-base 二进制是否与扩展匹配。参见 升级 Quivr。

• 发布镜像和构建标识。 Release-please 管理 alpha 发布 PR、版本和更新日志。发布版本会在 GHCR 上构建签名的引擎和第一方插件镜像，附带签名 SPDX 清单和漏洞扫描。 quivr --version 、 GET /v0/version 、启动日志和进程指标报告构建情况。参见 部署和配置 Quivr 和 发布安全。

• 声明式一致性案例：贡献通用要求并用 make conformance 在本地测量；案例格式和报告。CI 从不执行案例。

• 身份验证向量索引：可选的 weaviate_api_key 在每个索引请求中发送承载密钥；对外部索引使用 HTTPS。参见 配置。

• 外发 TLS 用于 Temporal、Weaviate、PostgreSQL、S3 和插件，支持已验证证书和可配置信任。传入 HTTPS 在您的平台终止；请参阅 在 TLS 后运行 Quivr。

• 语料库，每个组织、操作和语料库具有作用域 API 密钥。

• 语料库生命周期控制：使用 POST /v0/corpora/{corpus_id}/archive 和 /unarchive （ corpora:archive ）归档和恢复语料库。归档的语料库仍然存储，但会从默认列表、搜索和目录作用域以及变更流中消失；显式搜索或目录访问返回 409 corpus_archived，而连接器轮询会停止，但不改变其启用状态。GET /v0/corpora?include_archived=true 列出归档条目，GET /v0/corpora/{corpus_id} 显示其归档状态。PATCH /v0/corpora/{corpus_id} 使用 corpora:rename 重命名它。这些命令会被审计。归档的直接记录、版本和浏览时间线读取在恢复前返回 not_found。

• 持久、幂等的摄取：内联文本、每条记录结果的有限批次、已验证上传（预签名 PUT+校验和确认）、结构化清单、扩展和关系。

• 更正和撤回，带有不可变版本和受限撤回记录。

• 搜索：词汇、语义和混合搜索，每次命中时进行规范重构和访问重新检查，跨源共享元数据和类型化语料库过滤器，可在选择的源命名空间内（在排名前进行过滤）。新建或重建索引支持可配置条目字段提升、语言中立或法语关键词副本、范围索引日期和身份过滤器；默认检索插件一次返回记录及其最佳段落。

• 元数据面：在语料库间精确计算文档数、限制的顶值及 UTC 日、月或年直方图，在相同元数据过滤下。

• 变更流 通过轮询和可恢复 SSE，另加光标过期后的 目录重新同步。按最新版本接受时间列出语料库记录，按时间范围过滤，并通过 API 或 CLI 读取精确区间计数。使用单次语料库统计请求读取运行中文档总数、UTC 小时或日直方图以及连接器总数。元数据相等性和日期范围页面使用作用域索引和有限读取；过滤过于宽泛将返回不可重试的缩小错误。

• 已保存查询和订阅，可固定和版本化；已启用订阅将新可搜索版本转为唯一 匹配（ /v0/matches ），当配置目的地时，每个匹配附带一次传送。省略 destination_id 可通过 API 阅读匹配和所有变更流通知，无需 webhook 传送。匹配由固定告警规则插件（ subscription 贡献）决定，每篇文章批量处理。两者均可重命名而无需新版本。

• 关键词提醒 通过第一方插件 plugins/alerts，在本地堆栈中默认固定：

  • 查询例如 "Acme" AND (grève OR strike) NOT sport，带有精确短语，
    “任意”、“无一”及分组;
  • 格、重音和标点被忽略，单词整体匹配;
  • 元数据过滤器，如 source:wire 或 author:"Jane Doe"（名称在插件配置中映射），仅使用过滤器本身就是一个有效的警报；
  • 每个匹配的证据都会列出匹配的术语以及它们匹配的部分（指南）。
  • 浏览器演示的 Alertes 标签会记录这些警报，并实时显示每个警报捕获了什么 (quivr-search/)。

• **通过同一插件描述警报：如“港口和港口的劳工罢工”等通俗语言描述，由TypeSafe的Jev分类器判断，因此对文章的重新表述和翻译也同样具有警示效果：

  • 插件每批批次对每个不同描述进行一次检查和询问;
  • 警报可以限制给选定的来源，其其他文章从未被发送;
  • 匹配证据带有分类器的分数;
  • 没有 TypeSafe 密钥它们无法使用，因为文章内容会发送到 TypeSafe (指南);
  • 浏览器演示的 Alertes 标签在部署有分类器时，会在关键字提醒旁提供它们，并显示每篇捕获文章的评分 (quivr-search/)。

• 本地含义提醒 通过同一个插件：meaning 类型与 meaning_check: vectors 比较描述与存储的嵌入，以捕捉改写或翻译的文章，而无需外部分类器（文本仅在本地使用本地嵌入提供者）。keywords_or_meaning 和 keywords_and_meaning 结合关键词与含义检查 (指南)。

• 订阅预览 (POST /v0/subscription-previews)：在保存警报之前，查看它会捕获最近哪些文章，由同一个插件按照相同规则进行判断。预览不会保存任何内容，也不会发送任何内容，并且最多评估50篇文章；演示的警报表单会在你输入时显示预览。

• 订阅所有者：一个应用可以为其终端用户（一个不透明的 owner，例如 user-123）或全局用户创建订阅，可以在订阅上查看所有者、其匹配项、Webhook 和变更订阅源以路由每个警报，并使用 GET /v0/subscriptions?owner=… 列出用户的活动订阅。

• 修正和撤回通知：对于被警告的记录：仍然匹配的修正会获得一个关联的后续匹配（match.corrected），不再匹配的修正会标记为 match.no_longer_matches，但不会生成新的匹配，撤回则标记为 match.withdrawn。早期的匹配仍然可读。

• 签名的 webhook 发送（标准 Webhooks）到部署配置的目标，具有仅追加的尝试历史记录，边界内的抖动指数重试，重试耗尽后不再尝试，如果订阅被禁用则不会有新的尝试。工作进程在其探针监听器（/metrics）上暴露发送指标。

• 从持久化工件进行投影重建，作为可恢复的操作，可取消和重新运行。重新嵌入并发运行，可配置 rebuild.concurrency（默认 8），在慢文档仍在处理时跨页面填充值槽。安全检查点在恢复时保留未完成的工作；重建活动拥有独立的工作容量。导入仍可通过嵌入配方更改进行词汇搜索；不兼容的增强会标记 rebuild_required，直到重建向量被提供。进度报告分别覆盖版本和段落/向量空间条目，即 versions_covered 和 passages_covered。

• 文档步骤时间：每个版本报告其被接受、物化、切分为段落、可搜索、赋予向量、由警报评估、隔离或撤回的时间（steps）。具有 observability:read 的密钥列出最新文档及其步骤（GET /v0/admin/documents），并读取单个文档的时间线及每个步骤的持续时间和插件。

• 每个语料库的类型化检索映射（PUT /v0/corpora/{id}/retrieval）：指向源数据的逻辑字段仅在其重建生成被验证并激活后生效。

• 连接器实例：计划将数据拉取到语料库中，使用仅写入的凭据和健康状态，通过与推送内容相同的摄取路径。通过 object_storage_archive 导入归档：不可变的兼容 S3 的 .tar.gz 和 ZIP 源，有限的批次和并发，可恢复的成员检查点，光标前进时立即继续，摄取队列的回压，以及配置的数字修订顺序（指南）。提供的类型：rss（RSS 和 Atom 订阅源）、m365_mail（Microsoft 365 邮箱）和 x_list（第一方插件 plugins/x-list），可轮询 X 列表：编辑变为更正，已删除或受保护的帖子被撤回，健康状态显示每日阅读量（指南）。在 webhook 模式下，X 帖子通过核心转发到插件的过滤流 webhooks 实时到达，轮询作为回退（指南）。部署 credential_key 可选。没有它，凭据存放将被拒绝并返回 503 credentials_unavailable，其余功能正常。GET /v0/connector-kinds 发布每个启用类型的配置和凭据 JSON 模式，PUT /v0/connectors/{id}/schedule 更改轮询间隔，POST /v0/connectors/{id}/runs 立即再次检查源。使用 POST /v0/connectors/{id}/pause 和 …/resume 暂停和恢复计划采集，包括继续导入；保留上次保存的位置。验证错误会以 JSON Pointer 的形式标明出错字段。

• 安全源 API 路由（插件 API 0.12）：连接器插件在 /v0/connectors/{id}/api/<path> 声明 POST 推送和 GET 挑战路由。引擎检查集合范围的 connector:push 密钥、实例范围的承载令牌或提供方签名策略，并对签名推送进行时间戳和重放保护；接受的推送返回 202 并附摄取收据。作者指南

• Web 应用中的来源页面（quivr-search，Sources 标签）：粘贴网站或订阅源地址，Web 应用会查找其 RSS 或 Atom 订阅源（拒绝私人地址），或从 DEMO_FEED_SUGGESTIONS 一键添加推荐订阅源。每个来源显示其健康状态和最新文章，并可暂停、恢复或移除；失败的来源可立即重新检查 (Réessayer)。其他类型保留从其模式生成的表单，因此新增类型无需更改 UI（指南）。

• 网页应用中的实时信息流页面（Veille 标签页）：显示所有进入演示语料库的内容，按最新顺序排列，包含来源、时间、标题和摘要。新条目通过 SSE 到达，由应用服务器从变更源转发，并可按来源过滤（指南）。

• 各进程私有探针监听器上的操作指标及相关日志（/metrics，Prometheus 文本，有限标签）：

  • API：接受的命令、待摄取积压，以及搜索准入容量、占用和拒绝情况；
  • 工作线程：处理结果，从接受到可搜索的时间，以及交付尝试次数和持续时间。
  • 两者：按注册路由、方法和状态类别统计的 HTTP 请求次数；
    按路由和方法统计的持续时间和进行中请求；本地 PostgreSQL 连接池的占用和饱和度。

  实时/批量积压观察默认每 15 秒刷新一次，可配置间隔，并根据进度计数器估算重建/补充情况（队列配置）。

  实时和批量工作线程在每个接收批次内，将就绪文档提交分组，每个组织最多 16 个不同记录。仅段摄取提供者可以同时发布新内容和关键词准备情况；向量处理保持为单独步骤。桥接初始保留旧有日志模式。显式并行激活会移除组织范围的接收锁定，保持每条记录稳定的源顺序和安全发布范围；并发记录无需严格遵循提交顺序（部署指南）。

  JSON 日志关联调用者请求 ID、跟踪/跨度 ID、收据、记录和版本。可选择的 OpenTelemetry 将跟踪和指标导出到 OTLP 收集器，将一次跟踪通过持久化摄取、Temporal、插件调用和 Webhook 传递（配置）。

• 本地负载测量（make load），采用确定性免费提供者、版本化场景、摄取突发和副本故障。报告包括延迟、错误、吞吐量及直到文档可搜索和触发警报的延迟；详见 运行本地负载测试。

• 检索测量使用冻结工作负载（make measure），以及搜索质量在公共法语和英语评测集或私人评测集上，每晚进行（make eval，指南）。通过 MLflow 使用离线发件箱共享测量结果，进行配对比较和帕累托排行榜（结果指南）。

• 有界搜索活动 探索公共开发或加密的私人工作集设置，具有持续的帕累托前沿、每日/总量上限、可恢复清理和每日摘要。线索提交有界提案和准确的使用收据（指南）。配置的活动在开启设置 PR 前确认完整堆栈上的最终候选。

• 私人新闻评估构建器：可插拔生成，带可配置目标和尝试预算，汇总判断、加密工作集/保留集以及人工审查（贡献者指南）；实际提供者运行由操作员控制。

• 插件协议 v0 合约（contracts/plugins/v0/）和 quivr plugin inspect，用于验证 quivr-plugin.yaml 并报告其兼容性、贡献、模式、密钥和限制。

• 签名引擎调用（插件 API 0.14）：每个插件的 HS256 令牌绑定操作和内容，60 秒内过期，并支持重叠密钥轮换。两个 SDK 在分发前拒绝无效调用。较旧声明的 API 保持未签名，并显示启动警告。协议参考。

• 无需重启的插件注册和激活：启动时固定的插件会记录在数据库中，活动的流水线计划指明每个插件承担的角色（媒体类型、警报规则、连接器类型、摄取、检索）。拥有 plugins:admin 的操作员密钥（组织密钥无法获取）注册在某地址运行的插件版本；Quivr 通过合约运行器进行检查，再通过一次调用激活为新计划，API 和 worker 按此计划运行而无需重启（无需重启切换插件）。已启动的工作（收据处理、连接器运行、重建）在其开始计划上完成，即使跨 worker 重启。被替换的版本显示 draining，附带仍固定在其上的工作数量，然后显示 inactive。固定插件消失的工作会被隔离，并使用诊断命名计划和插件，从不移动到新版本。Quivr 从不启动插件进程。一次调用可回滚到先前计划。夜间运行（make measure-upgrade）在持续摄取下进行升级、排空、回滚和回填，并检查无文章丢失且 API 保持响应（无停机升级插件）。

• 回填和向量空间提升：操作员在对文档量、持续时间和成本进行干运行后，为语料库的历史文章（全部或窗口范围）填充新嵌入模型的评估空间（POST /v0/admin/backfills）。回填运行速度低于实时摄取，可以暂停、恢复或取消，并在重启后从检查点继续。一次调用即可使搜索使用该空间，对前一个空间的相同调用可回退 (为历史文章填充新向量空间)。

• 插件和搜索计数器：每个进程统计每次插件调用、搜索、处理步骤、接收的文档（按源命名空间）及匹配次数，包括错误和延迟，并每隔几秒写入 PostgreSQL（observability.flush_interval，默认 5 秒，这是崩溃最多丢失的时间）。具有 observability:read 的密钥可从 GET /v0/admin/stats/plugins、searches、steps、received、matches 及 top-queries 中读取其组织的过去一小时、一天或一周的数据；数据超过 7 天不保留。Top queries 需要 observability.record_query_text，默认关闭，因为它会存储查询文本。相同的计数器也出现在 /metrics 上。

• 外部归一化器：启动配置固定一个插件，并将 Blob 媒体类型路由到其归一化器。通过引用摄取的路由类型 Blob，通过插件的 Parts 可被搜索，其 Version 显示 provenance.normalization。不可用的插件会重试，但从不阻塞 API 或其他摄取。插件错误、输出无效或重试耗尽会将 Version 隔离，并提供结构化诊断，而 optional 文本路径会回退到内置文本路径 (指南)。

• 重新处理隔离的版本：在插件修复或回滚后，操作员列出隔离的 Versions，进行干运行，然后使用活动计划重新处理它们，可选择从存储的源通过归一化重新启动。操作是有节奏的、可恢复的，并保持每个 Version 的身份 (指南)。

• 插件拥有的扩展命名空间：固定插件声明的命名空间在启动时与内置命名空间一起注册。其归一化器的扩展会根据其 schema 进行验证并发布在 Version 上，客户端无法写入 (422 extension_namespace_owned)，检索映射可以将它们映射到搜索中。

• Go 和 Python 插件 SDK 支持所有五种贡献，具有命名的源路由处理程序和离线 push-source 示例。两个工具包都支持推送路由和附件。quivr plugin init 用于生成规范器、警报规则以及拉取或推送源，quivr plugin dev 可在本地运行，检查其发现摘要并通过引擎的 Manifest 验证回放一个固定装置，而无需 Quivr 堆栈 (SDK 指南)。

• 插件合同运行器 (quivr plugin test)，用于根据公共协议认证规范器，可从其清单启动或在 --endpoint <url> 上运行。它运行健康检查、发现、规范和插件固定装置、确定性回放、声明的截止时间、无效请求的终端错误以及兼容性范围。它使用引擎自身的验证来判断输出：Manifest 规则、响应大小、仅输入 Blob 的 Blob 部分以及声明的命名空间。它通过 --report 写入 JSON 报告，CI 会为 quivr plugin init 模板发布报告。

• 可搜索的 NewsML-G2 文本 通过 plugins/newsml-g2：标题、短标题和段落保留其语言和方向，编辑元数据保持命名空间，原始 XML 仍可作为源 Blob 获取。支持项目和单项目消息媒体类型。

• 可搜索的 PDF 通过参考插件 plugins/pdf-text（pypdf, BSD-3-Clause）。一个 application/pdf Blob 转换为每页一个带文本的 body 部分，短语可在其页面的部分中被找到。空白或扫描页会给出警告；加密或损坏的 PDF 会被隔离，并带有指明插件的诊断信息。默认情况下，make dev 会固定它；没有 OCR (指南)。

• 从命令行使用 quivr search：设置 QUIVR_API_URL 和 QUIVR_API_KEY，然后 quivr search --corpus <corpus_id> "query" 会打印带有摘要和记录 / 版本 / 部分来源的排序命中，或者用 --json 输出未更改的 API 响应。失败时，每类错误返回不同的退出码（被拒绝的密钥或作用域、无效请求、无法访问的服务器）。它使用从合同生成的 Go 客户端（包 client），且从不触碰堆栈的存储 (指南)。

• AI代理通过MCP搜索并引用Quivr：quivr mcp --profile read 在stdio上为代理提供三个只读工具。代理可以列出其密钥可访问的文集，搜索它们，并读取命中的记录版本和清单，同时保存记录、版本、部分及精确摘录的偏移以进行引用。--profile ingest 将文本添加到文集中并跟踪其摄取回执直到可搜索；重试不会重复，且没有工具会删除。仅API密钥决定访问权限（连接AI代理）。

• 编写标准化器的指南：搭建、运行、认证、固定、摄取并观察你自己的插件（编写标准化器）。

• 作为插件的源收集器，用Go语言（插件API 0.3）：连接器契约（在不透明检查点后fetch页面、check_credential、分类错误）、Go插件SDK（sdks/go）可屏蔽凭证，以及quivr plugin test 检查页面是否从检查点继续且无凭证泄漏。核心调用这些插件进行计划和按需收集。

• 受保护的源推送：每实例令牌桶、Idempotency-Key答案的TTL重放、可选的CIDR白名单与可信代理解析，以及接收/拒绝的审核事件和每实例管理员统计。

• 作为插件的分段和嵌入（插件 API 0.6，ingestion 贡献）：一个固定插件声明其拥有的向量空间，一个用于服务，其他用于评估，将每篇文章切分为各个段，每个空间对应一个向量和可选的关键词文本，并为其空间编码查询。当语料库重建时会使用它；GET /v0/corpora/{id}/vector-spaces 显示每个空间的拥有者、角色和覆盖范围（编写一个 ingestion 插件）。第一方 core.ingest 插件（token 窗口，E5）默认被固定；引擎本身不进行分段和嵌入。可选的 hosted.embed 将连续的正文部分捆绑在一起以形成有界项目，并为大型项目和大小超限保留全文分页。在打包配置更改后，受影响的语料库需重建。它通过配置选择托管模型或兼容 OpenAI 的服务器，支持 OpenAI 和 Cohere v2 格式。模板为显式设置；认证的供应商使用 EMBED_API_KEY。为任何托管模型准备校验和固定的 tokenizer；发布的插件镜像从只读挂载中运行，以确保精确的 token 预算。EmbeddingGemma 2 是一个示例配置。更改空间 ID 需要重新摄取或重建。可选的固定 CPU 文本编码器 在文档继续使用远程提供者的同时，可回答 API 查询。

• 由插件排名的搜索（插件 API 0.7，retrieval 贡献）：选定的插件在最多三轮中回答每次搜索，向引擎请求其已授权的关键词、向量或混合候选，然后对每个命中提供解释，并按照命名的配置文件在延迟和成本预算下进行排名（GET /v0/search/profiles）。多个检索插件可以一起固定：搜索接受完整的 plugin/profile 名称或在 retrieval.profiles 中配置的短名称，包括 default（编写一个检索插件）。第一方 core.retrieve 插件（关键词、向量或两者）默认被固定；可选设置可选择向量权重、候选深度和相对分数或 RRF 融合（默认：alpha 0.5，搜索上限，相对分数）。引擎本身不进行排名。

文档

文档网站 docs.quivr.thevibecompany.co 是为使用 Quivr 并编写插件的人而写的：包括介绍、快速入门、核心概念、插件指南、任务指南和参考资料。其源码位于 docs-site/；那里 HTTP、CLI、MCP 和插件参考是从合约生成的。

该仓库存储了贡献者的文档，根据 docs/inventory.toml 生成的起始页为不同读者列出内容：

• 使用 Quivr：合约的 README、演示和部署，以及生成的参考资料。
• 编写插件：SDK 的 README、插件合约以及第一方插件。
• 为 Quivr 做贡献：以个人或编码代理身份更改此仓库。

仓库布局

cmd/quivr/          single binary: API, worker, migrations
internal/           domain modules (content, corpus, retrieval, changes, monitoring…)
contracts/http/v0/  OpenAPI contract, examples and checks
contracts/plugins/v0/ Plugin Protocol v0 schemas and normative fixtures
sdks/go/            Go Plugin SDK for every Contribution
sdks/python/        Python Plugin SDK
plugins/pdf-text/   reference normalizer: PDF text, one Part per page
migrations/         expand/contract PostgreSQL migrations (UTC-stamped; legacy 0xx_ first)
scripts/            local stack, verification and measurement tooling
quivr-search/       demo web UI
deploy/             Docker Compose and Railway deployment
docs-site/          the public documentation site (Mintlify): authored MDX pages and generated references
docs/               contributor documentation, ADRs (docs/adr/) and dated documents (docs/dated/)
multimodal-rag/     earlier exploration (submodule), not the target architecture

贡献

• 首先阅读 AGENTS.md 和 CONTEXT.md；在代码和文档中使用领域词汇。
• 修改 contracts/http/v0/openapi.yaml 中的合同，然后运行 make generate。
• 在推送之前运行 make check 并保持 make verify 通过；每次行为变更时添加测试。
• 在 docs/inventory.toml 中声明每个新的动态文档页面，一行说明其受众和类型（文件头中解释了两者），然后运行 make start-pages；如果存在未声明页面、过期启动页面、损坏的相对链接或缺失的仓库路径，make docs 会失败，并指明修复方法。
• 在站点 docs-site/ 中在同一拉取请求中记录面向用户的行为；合同更改后运行 make docs-site。将 API 请求展示为 可运行块，make verify 会重新执行这些块。
• 绝不编辑已接受的 ADR 或 docs/dated/ 下的有日期文档：应通过新的文档取代它们（ADR 0004）；make docs 会将它们与您分支从 origin/main 分叉的位置进行比较。
• 拉取请求标题遵循 Commitizen 约定，例如 feat(ingestion): accept record versions。
• 保持客户特定格式和规则不进入核心；它们应属于插件。

许可

MIT — 参见 许可证。