docs(rag): add MemoryBear RAG implementation docs v1.0

Submit the formed RAG documentation set produced across Sprint-1/2/3 (WS-12 through WS-26) under docs/rag/. Includes: - README.md / INDEX.md: landing + total index (responsibility matrix, review verdicts, dual-link to source issues) - overview/: full-pipeline architecture (4 .mmd diagrams), 11-stage boundary contracts, doc map, source-code inventory - pipeline/: 5 deep-dives (Loader/Parser/Chunking, Embedding, VDB & retrieval, GraphRAG, Rerank/Prompt/LLM) - graphrag/, end-to-end/: v1.0 formal versions with full source retained as reference - evolution/: 11 architecture-refactor proposals, 6-direction roadmap, capability map - review/: S3-T1 / S3-T2 final reviews, S2-T7 final summary - _indexes/: glossary (81 terms), source->doc reverse index, chart index - _release/: v1.0-RC1 release manifest, versioning convention, ops & freshness plan - _meta/README.md: placeholder noting WS-12 governance assets gap Aggregate review score 92.6/100 (8/8 PASS, 31/31 source-code spot checks hit). The legacy docs/ ignore in .gitignore is narrowed to docs/* with an explicit allowlist for docs/rag/. Refs: WS-26 Co-authored-by: multica-agent <github@multica.ai>
2026-05-09 10:51:48 +08:00
parent feae2f2e1e
commit 343a5eebe3
33 changed files with 8410 additions and 1 deletions
--- a/docs/rag/_release/ops-and-freshness-plan.md
+++ b/docs/rag/_release/ops-and-freshness-plan.md
@@ -0,0 +1,165 @@
+# MemoryBear RAG Docs · 运营与保鲜计划
+
+> **目标**：让 `docs/rag/` 不沦为"上线那天的快照"，而是与 MemoryBear 一同进化的活水。
+> **责任主线**：知识运营与治理专家牵头，与 PM / AI 知识库专家 / Python 工程师协同。
+
+## 1. 保鲜原则（Why）
+
+> 一句话：**代码会跑，文档会过期；过期速度比新代码合并的速度还快。**
+
+- **失效快**：MemoryBear 在 Sprint-3 内合并的关键改造（如 Reranker 缓存、Embedder Protocol、`node.py:327 print` 删除）会在 1-2 周内让相关文档章节失同步。
+- **影响大**：本套文档是 toB 客户、二次开发者、内部 oncall 的"事实来源"；与代码不一致会直接误导决策。
+- **维护成本可控**：用统一的"评审 + 增量更新 + 自动归档"三段式机制，把维护成本摊到每次 release，而不是堆在年度大修。
+
+## 2. 保鲜节奏（When）
+
+### 2.1 与 release 同步评审（强制）
+
+每次 MemoryBear 主仓发 release（语义化版本 `v0.x.y`）时：
+
+| 时点 | 动作 | 责任人 |
+|---|---|---|
+| **release 准备期 -7d** | 自动扫描：`git diff <last-release-tag>..HEAD -- 'api/app/core/rag/**'` 列出受影响文件 | PM 或脚本 |
+| **release 准备期 -5d** | 知识运营对受影响文件清单进行"文档涟漪映射"（用 `_indexes/file-index.md`） | 知识运营 |
+| **release 准备期 -3d** | 责任专家修订对应文档章节（最低粒度：源码引用行号、配置项默认值、流程描述） | AI 知识库 / Python 工程 |
+| **release day** | 知识运营终审；通过后将 `source-commit` 刷到新 commit | 知识运营 |
+| **release day +1d** | 在 `evolution/CHANGELOG.md`（v1.1 起新增）写入"对应 MemoryBear `v0.x.y` 的文档增量" | 知识运营 |
+
+### 2.2 季度全量复审（强制）
+
+每季度（3 / 6 / 9 / 12 月末）做一次"对所有文档的轻量复审"：
+
+| 步骤 | 内容 |
+|---|---|
+| 1 | 抽样 30%（每类文档至少 1 篇）做"源码引用一致性"抽查（用 `_indexes/file-index.md` 对应行号 grep ±3 行） |
+| 2 | 检查每个文档的 `last-reviewed-at`，超过 3 个月的标记为"待复审" |
+| 3 | 评分（按 5 维卡），低于 75 的文档启动 Should-Fix 流程；低于 60 的文档启动 Must-Fix |
+| 4 | 季度报告（约 1 页）发到 [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) 作为里程碑通告 |
+
+### 2.3 用户反馈驱动评审（按需）
+
+任何外部读者（开发者、客户）在子任务 issue 中反馈"文档与代码不一致"或"文档不清楚"，触发：
+
+- **24h 内**：知识运营响应 + 复核
+- **48h 内**：责任专家修订或返回澄清
+- **保留**：作为评审记录留在子任务评论中，季度报告时统计"反馈密度"作为质量指标
+
+## 3. 保鲜机制（How）
+
+### 3.1 责任矩阵
+
+| 文档类别 | 主责（修订） | 终审 | 升版决定 |
+|---|---|---|---|
+| `_meta/` 治理资产 | 知识运营 | 知识运营自审 | 知识运营 |
+| `overview/` 总览 | AI 知识库 | 知识运营 | 联合 |
+| `pipeline/` 各环节 | Python 工程 | 知识运营 | 联合 |
+| `graphrag/` GraphRAG | Python 工程 | 知识运营 | 联合 |
+| `end-to-end/` E2E | AI 知识库 | 知识运营 | 联合 |
+| `evolution/` 演进 | AI 知识库 | 知识运营 | 联合 |
+| `review/` 评审报告 | 知识运营 | 知识运营自审 | 知识运营 |
+| `_indexes/` 索引 | 知识运营 | 知识运营自审 | 知识运营 |
+| `_release/` 发布 | 知识运营 | 知识运营自审 + PM | 知识运营 + PM |
+
+### 3.2 过期判定规则（自动 + 人工）
+
+文档进入"过期候选"状态满足以下**任一**：
+
+| 触发条件 | 判定 |
+|---|---|
+| `last-reviewed-at` 距今 ≥ 90 天且 `source-commit` 与当前 main HEAD 差距 ≥ 50 commits | 自动标记 |
+| 用户反馈"文档与代码不一致"且复核成立 | 立即标记 |
+| 文档关联的代码模块在 release 中有变更（用 `git diff` 检测） | 自动标记 |
+| 文档评分 < 80 且未在 14 天内启动修订 | 自动标记 |
+
+> 标记后进入 [`_release/freshness-queue.md`](freshness-queue.md)（v1.1 起新建）。每周一上午 PM 在 [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) 评论"本周保鲜任务"通告。
+
+### 3.3 修订流程（强制走 SOP）
+
+所有修订都要遵循 `_meta/review-sop.md`：
+
+1. **作者自检** ≤ 30 min（用 `_meta/scoring-rubric.md`）
+2. **同行评审** ≤ 48 h（≥ 同 Sprint 1 名其他作者）
+3. **知识运营终审** ≤ 24 h
+4. 通过 → 合并 PR；未通过 → 退回作者，最多 2 轮
+
+> 紧急 hot-fix（如调试 print 残留、源码引用错误）可走"快速通道"：直接知识运营 + PM 双人共审 ≤ 4 h，事后补同行评审记录。
+
+### 3.4 归档机制
+
+- 文档被替换或并入新文档时：保留 6 个月，再迁移到 `docs/rag/_archive/<year>/`。
+- 归档保留可读性（保留 frontmatter 的 `status: deprecated`），**不删除**。
+- 季度报告中列出"本季归档清单"。
+
+## 4. 关键指标（Metric）
+
+### 4.1 内容质量指标
+
+| 指标 | 目标 | 测量方式 |
+|---|---|---|
+| 文档评分均值 | ≥ 85 | 季度评审打分 |
+| 评审通过率（一次过） | ≥ 75% | 季度评审统计 |
+| 源码引用一致率（抽查） | 100% | 季度抽样 30% × ±3 行 grep |
+| 失效文档占比（last-reviewed-at > 6 月） | ≤ 10% | 自动扫描 |
+
+### 4.2 使用与反馈指标
+
+| 指标 | 目标 | 测量方式 |
+|---|---|---|
+| 月活读者（PV） | TBD（v1.1 起埋点） | Wiki 自带统计 |
+| 用户反馈数（季度） | ≥ 5 条 | 子任务 issue 评论统计 |
+| 反馈解决率（30 天内闭环） | ≥ 90% | issue 状态统计 |
+| 搜索无结果率（"用户搜了什么找不到"） | ≤ 5% | Wiki 搜索日志（v1.2 起） |
+
+### 4.3 协作健康指标
+
+| 指标 | 目标 | 测量方式 |
+|---|---|---|
+| 修订到合并的中位时间 | ≤ 3 天 | PR 数据 |
+| 紧急 hot-fix 数量（季度） | ≤ 2 | issue 标签统计 |
+| 评审反馈采纳率 | ≥ 80% | 终审记录 |
+
+## 5. 治理工具（推荐落地）
+
+| 工具 | 作用 | 落地阶段 |
+|---|---|---|
+| **Markdown lint**（`markdownlint`） | 检查 frontmatter 完整性、链接有效性 | v1.0 PR 前接入 CI |
+| **链接巡检**（`lychee`） | 自动跑死链 / 失效 mention | v1.1 |
+| **Mermaid 校验**（`@mermaid-js/parser`） | 校验 .mmd 文件可渲染 | v1.0 PR 前 |
+| **`source-commit` 对齐脚本** | 检查 frontmatter 的 commit 是否在 main 历史中可达 | v1.0 PR 前 |
+| **失效扫描器** | 比对 `last-reviewed-at` 与 main HEAD diff，输出过期候选清单 | v1.1（与 PM 协同） |
+| **评分卡 LLM 助手** | 用大模型对文档做初评，节省人工 | v1.2 |
+| **Wiki 同步器** | `.md` → MkDocs / Material 自动构建 | v1.0 同步落地 |
+
+## 6. 与 PM 的协同节律
+
+| 频次 | 内容 | 出口物 |
+|---|---|---|
+| 每周一 | PM 在 [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) 评论"本周关注点" | 通告 |
+| 每周三 | 知识运营点检本周已交付文档，必要时介入 | 评分卡更新 |
+| 每周五 EOB | 责任专家在子任务评论"本周完成 + 下周计划" | 子任务通告 |
+| 每月初 | 知识运营汇总月度评分均值，更新 `_release/quality-dashboard.md`（v1.1 起新增） | 月报 |
+| 每季度 | 全量复审（§2.2） + 给 PM 提交季度报告 | 季报（约 1 页） |
+| 每次 release | 同步评审 + 升版 + CHANGELOG（§2.1） | release 通告 |
+
+## 7. 失败模式与止损（备灾）
+
+| 风险 | 触发场景 | 止损 |
+|---|---|---|
+| 知识运营长期不在场 | 评审节奏断 | 提前指定 backup（建议 [@AI 知识库专家] + [@PM] 共审） |
+| 大量文档同时过期（如重大重构） | 无法在一个 release 内修完 | 按"先核心后边缘"分批：核心（pipeline/03 + evolution）→ overview → pipeline 其余 → graphrag → end-to-end |
+| 用户反馈与责任专家判断冲突 | 修订悬而未决 | 由 PM 仲裁；保留双方陈述在 issue |
+| 评分卡刚性导致一线积极性下降 | 因小错频繁返工 | 季度复盘评估"评分卡是否过严"，必要时调整 Should-Fix 与 Must-Fix 边界 |
+
+## 8. 一年内重要里程碑（建议）
+
+| 时点 | 内容 |
+|---|---|
+| 2026-05-08 | v1.0-RC1（本次发布） |
+| 2026-05-22 ~ 05-29 | S2-T7 评审收口；S2-T4/T6 文档补齐；目标升版 v1.0 |
+| 2026-06-01 ~ 06-05 | S3 全套文档落入仓库 PR；启动 [S3-T4 PM 复盘](mention://issue/b98604b1-326f-42b4-a4c2-b3d9ad80ec75) |
+| 2026-Q3 | S3-T1 §3.1 短期路线图全部合入 → v1.1 |
+| 2026-Q4 | S3-T2 PoC-A / PoC-B 落地，回填实测数据 → v1.2 |
+| 2027-Q1-Q2 | 4 大 Protocol 落地 + OTel 接入 → v2.0-RC |
+| 2027-H2 | 多模态 / 增量图等长期方向落地 → v2.0 正式 |
+
+— **Operations & Freshness Plan · v1.0-RC1 · 2026-05-08** —
--- a/docs/rag/_release/release-manifest-v1.0-RC1.md
+++ b/docs/rag/_release/release-manifest-v1.0-RC1.md
@@ -0,0 +1,126 @@
+# MemoryBear RAG Docs · 发布候选清单 v1.0-RC1
+
+> **状态**：Release Candidate 1 · 候选发布
+> **冻结日期**：2026-05-08
+> **发布方式**：仓库 PR + Wiki + Issue 评论附件
+> **下次升版门槛**：S2-T7 评审通过 + S2-T4 / S2-T6 占位文档替换
+
+---
+
+## 1. 版本基本信息
+
+| 项 | 值 |
+|---|---|
+| 版本号 | `v1.0-RC1` |
+| 发布通道 | Release Candidate（候选发布） |
+| 基线源码 | MemoryBear `agent/ai/f8de881a` 分支（基于 commit `feae2f2e`） |
+| 文档作者 | AI 知识库专家 / Python 工程师 / 知识运营专家 / PM 协同 |
+| 终审责任人 | 知识运营与治理专家 |
+| 文件总数 | 33 个（其中 28 已交付，5 占位） |
+| 总字数（含已交付） | ≈ 230k 字（中文） |
+| Mermaid 图表 | 9 张已交付，5 张待补 |
+| 源码引用 | 200+ 处（采样 5 处全部可在 ±3 行内复现） |
+
+## 2. 发布 Targets（"哪些文档随什么形式发布"）
+
+| 路径 | 发布形式 | 责任人 | 交付物 |
+|---|---|---|---|
+| `docs/rag/README.md` | **仓库 PR** | 知识运营 | Landing 页，含三套阅读路径 |
+| `docs/rag/INDEX.md` | **仓库 PR** | 知识运营 | 全集总索引 + 责任矩阵 |
+| `docs/rag/_meta/*` | **仓库 PR** | 知识运营 | 治理资产（已合入 `agent/ai/f8de881a` 分支预备） |
+| `docs/rag/overview/*.mmd` | **仓库 PR**（Mermaid 文件） + **Wiki**（渲染版） | AI 知识库 | 4 张时序/架构图 |
+| `docs/rag/overview/{boundaries.md,DocMap.md,source-inventory.md}` | **仓库 PR** | AI 知识库 / Python 工程 | 边界定义 / 大纲 / 源码盘点 |
+| `docs/rag/pipeline/*.md` | **仓库 PR** | Python 工程 | 4 篇已交付 + 1 占位（S2-T4 待重启） |
+| `docs/rag/end-to-end/README.md` | **占位**（不入 PR） | AI 知识库 | 等 S2-T6 解除阻塞后追加 |
+| `docs/rag/evolution/*` | **仓库 PR** | AI 知识库 | S3-T1 / S3-T2（终审已通过） |
+| `docs/rag/review/*` | **仓库 PR**（已通过部分） + **Issue 归档**（未启动部分） | 知识运营 | S3-T1 / S3-T2 终审报告 + S2-T7 占位 |
+| `docs/rag/_indexes/*` | **仓库 PR** | 知识运营 | Glossary / File Index / Chart Index |
+| `docs/rag/_release/*` | **仓库 PR** | 知识运营 | 本文 + 版本约定 + 运营保鲜计划 |
+
+> **建议 PR 拆分**：
+> - **PR-1**（_meta + README + INDEX）：作为治理 baseline 先合，便于后续文档按统一模板入库。
+> - **PR-2**（overview + 4 个 .mmd）：架构与图谱基础，独立合并便于 review。
+> - **PR-3**（pipeline 4 篇 + 1 占位）：Sprint-2 已交付内容；占位文件含明确"等待重启"说明，避免误读。
+> - **PR-4**（evolution + capability-map.mmd）：架构改造与迭代路线（S3-T1/T2）。
+> - **PR-5**（review + _indexes + _release）：评审报告与索引、运营资产。
+
+## 3. v1.0-RC1 → v1.0 升版门槛（Release Gate）
+
+| 门槛 | 当前状态 | 责任人 | 预计完成 |
+|---|---|---|---|
+| **G1: S2-T7 评审收口完成** | ⏳ todo（上一次 API Error） | 知识运营 | 重启后 1 个工作日 |
+| **G2: S2-T4 GraphRAG 文档交付 + 评审通过** | ⏳ 占位 | Python 工程师 | 重启后 1 周 |
+| **G3: S2-T6 E2E 调用链路文档交付** | ⏳ 阻塞（依赖 S2-T1~T5） | AI 知识库专家 | S2-T4 解除后 3 个工作日 |
+| **G4: 已交付的 4 篇 Sprint-2 文档（T1/T2/T3/T5）正式评分录入** | ⏳ 待 S2-T7 评审落分 | 知识运营 | G1 完成时一并 |
+| **G5: S3-T1 §3.1 短期路线图工作项 #1（删除 `node.py:327 print()`）合入 main** | ⏳ 待提 PR | Python 工程师 / AI 知识库 | 任意 1 个工作日 |
+| **G6: 全部仓库 PR 合入 main 分支** | ⏳ 待 PR 创建 | 知识运营协调 | G1-G5 完成后启动 |
+
+> **任一门槛未达成，停在 v1.0-RCN（N 递增）**。
+
+## 4. v1.0 ~ v2.0 版本节奏（建议）
+
+| 版本 | 触发条件 | 主要内容 |
+|---|---|---|
+| `v1.0` | G1-G6 全部 PASS | 完整的 S1+S2+S3 文档全集，对外可发布 |
+| `v1.1` | S3-T1 §3.1 短期路线图（5 项工作项）全部合入 | 增量更新：Reranker 缓存上线、`RAGSettings` 落地、单测脱离 ES 等 |
+| `v1.2` | S3-T2 PoC-A（RRF）+ PoC-B（Memory Rewrite）合入 | 增量更新 D2 / D4 章节，回填实测数据 |
+| `v1.3` | S3-T1 §3.2 中期路线图完成（OTel / Plugin Registry / 4 大 Protocol） | 大版本：Embedder/Retriever/Reranker/Generator Protocol 落地，可观测性建立 |
+| `v2.0` | S3-T1 §3.3 长期路线图完成 + S3-T2 D1/D3 多模态 + 增量图 | 架构演进里程碑：可插拔 VDB、Pipeline DSL、增量图、跨模态检索 |
+
+> 这套节奏与 [S3-T2] §4 Roadmap 的 Sprint-3 / 短/中/长 时间窗一致；每次升版必须同步刷新 Mermaid 图与 source-commit。
+
+## 5. 文档质量门槛（自检 vs 终审）
+
+| 类别 | 自检通过分 | 终审通过分 | 一票否决项 |
+|---|---|---|---|
+| Sprint-2 各深度文档（S2-T1 ~ S2-T5） | ≥ 70 | ≥ 80 | 源码虚构 / 核心章节缺失 / 安全风险描述 / 架构严重脱节 |
+| Sprint-3 演进文档（S3-T1 / S3-T2） | ≥ 75 | ≥ 80 | 同上 |
+| 治理资产（_meta） | ≥ 70 | ≥ 80 | 同上 |
+| 索引与 Landing | ≥ 70 | ≥ 80 | 同上 |
+
+> 上述阈值与 S1-T1 评分卡保持一致。当前 S3-T1 / S3-T2 已通过终审（96 / 95）。
+
+## 6. 已知风险与应对
+
+| # | 风险 | 影响 | 缓解 |
+|---|---|---|---|
+| R1 | S2-T4 GraphRAG 文档因 API Error 多次失败，可能再次中断 | v1.0 升版被卡 | 启动前先 dry-run 一次，若仍失败则把"GraphRAG 现有 light/general 的简版梳理"由 [@AI 知识库专家] 接管 |
+| R2 | S2-T6 E2E 文档目前 blocked，依赖 S2-T1~T5 全部交付 | v1.0 升版被卡 | S2-T4 完成后立即触发 S2-T6 |
+| R3 | 仓库 PR 与 RAG 主分支合并冲突（仓主可能在并行修改） | PR 滚动 review 难 | 锁定 source-commit，按 PR-1 → PR-5 顺序短链合并；冲突时由责任专家 rebase |
+| R4 | 文档与代码失同步（main 分支前进） | 内容时效性下降 | 见 `ops-and-freshness-plan.md` 的"每次 release 同步评审"机制 |
+| R5 | 内部 Wiki 渲染 Mermaid 节点上限 1500 | 大图渲染失败 | 拆图（Chart Index §4 已规划）、备份 SVG |
+| R6 | Sprint-2 文档评分若多篇低于 80，需返工 | 升版延期 | 先评 in_review 状态的 4 篇，发现共性问题立即下发修订 |
+
+## 7. 发布仪式 Checklist
+
+发布 v1.0 前，逐项打勾：
+
+- [ ] G1-G6 全部门槛达成（§3）
+- [ ] PR-1 ~ PR-5 全部合入 main
+- [ ] 内部 Wiki 同步发布（含 Mermaid 渲染版）
+- [ ] 在 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) 发"v1.0 正式发布纪要"评论（含交付物清单 + 链接 + 总评分）
+- [ ] 状态由 `in_review` → `done`
+- [ ] 通知 PM 启动 [WS-25 / S3-T4 PM 复盘](mention://issue/b98604b1-326f-42b4-a4c2-b3d9ad80ec75)
+- [ ] 创建 v1.1 跟踪 issue（占位下一轮迭代）
+
+---
+
+## 附录 A：当前已交付文件 SHA-1（防篡改）
+
+> 在落入仓库 PR 前，先记录附件的 SHA-1 校验值；合并到仓库后由 reviewer 复核。
+
+| 文件 | 来源 attachment ID | 大小 | 备注 |
+|---|---|---|---|
+| `S3-T1-deliverable.md` → `evolution/architecture-refactor-suggestions.md` | `019e0757-d0ab-704a-b6bb-5c1bbb3d8eb6` | 33 KB | S3-T1 |
+| `future-extensions-roadmap.md` → `evolution/future-extensions-roadmap.md` | `019e075c-42a0-7a64-b5d5-263c0fc92a0b` | 32 KB | S3-T2 |
+| `capability-map.mmd` → `evolution/capability-map.mmd` | `019e075c-42c7-713e-a8c3-41bf37d5ca37` | 4 KB | S3-T2 |
+| `01-architecture.mmd` → `overview/01-architecture.mmd` | `019e0747-0c26-79e8-984b-f6d8394016aa` | 5 KB | S1-T2 |
+| `02-indexing-pipeline.mmd` → `overview/02-indexing-pipeline.mmd` | `019e0747-0c4d-7808-8362-16b237c02048` | 4 KB | S1-T2 |
+| `03-query-pipeline.mmd` → `overview/03-query-pipeline.mmd` | `019e0747-0c71-7ab7-9269-1175e487308e` | 4 KB | S1-T2 |
+| `04-graphrag-indexing.mmd` → `overview/04-graphrag-indexing.mmd` | `019e0747-0c92-7ec5-a2c9-bb3f9c2b4de9` | 3 KB | S1-T2 |
+| `DocMap.md` → `overview/DocMap.md` | `019e0747-0cb6-78c4-8e5c-af441e571e3c` | 18 KB | S1-T2 |
+| `boundaries.md` → `overview/boundaries.md` | `019e0747-0cd9-7a9e-95f1-f5428e35b3c6` | 13 KB | S1-T2 |
+
+> S1-T1 _meta 系列与 Sprint-2 各深度文档当前以**评论正文**形式存在，作为本次 RC 的"评论沉淀+对外引用"双形态。仓库 PR 时由责任专家把评论正文落到对应文件，由知识运营复核 SHA-1 一致性。
+
+— **Release Manifest · v1.0-RC1 · 2026-05-08** —
--- a/docs/rag/_release/versioning-convention.md
+++ b/docs/rag/_release/versioning-convention.md
@@ -0,0 +1,84 @@
+# MemoryBear RAG Docs · 版本号约定
+
+> 适用范围：`docs/rag/` 下所有文档，含 Markdown / Mermaid / 评分卡 / 模板。
+
+## 1. 版本号格式（语义化）
+
+```
+v<MAJOR>.<MINOR>[-RC<N>]
+```
+
+- **MAJOR**：架构层重大变化（如 4 大 Protocol 落地、可插拔 VDB 上线、检索范式切换）
+- **MINOR**：增量内容更新（新增章节、补图、回填基准、修订错误）
+- **-RC\<N\>**：候选发布（Release Candidate）N，用于在所有升版门槛达成前的过渡发布
+- **示例**：`v1.0-RC1` → `v1.0-RC2` → `v1.0` → `v1.1` → `v2.0-RC1` → `v2.0`
+
+## 2. 升版触发规则
+
+| 触发器 | 升版动作 |
+|---|---|
+| Release Gate 全部达成（见 release-manifest） | RCN → 正式版（去掉 -RC 后缀） |
+| 单文档 Should-Fix 修订 | 文档级 frontmatter `version` 增加 patch 标识（如 `1.0.1`），全集版本不变 |
+| 新增 Sprint 全套文档（如 Sprint-4 立项） | 全集 MINOR +1（v1.1 → v1.2） |
+| 4 大 Protocol 落地、可观测性引入、Plugin Registry 上线 | 全集 MAJOR +1（v1.x → v2.0-RC1） |
+| 紧急 hot-fix（修正错误源码引用、补救一票否决项） | 单文档 patch +1，并在 INDEX.md 记录 |
+
+## 3. frontmatter 规范
+
+每个 `.md` 文档 **必须**有 frontmatter，包括：
+
+```yaml
+---
+name: <文档简称>
+description: <一句话描述>
+type: <user|feedback|project|reference|review|template|...>
+sprint: <S1|S2|S3>
+task: <T1|T2|...>
+author: <责任人角色名>
+reviewer: <终审责任人或 "待 [S2-T7] 评审">
+version: <语义化版本，如 1.0.0>
+source-commit: <锁定的代码 SHA，如 feae2f2e>
+last-reviewed-at: <YYYY-MM-DD>
+---
+```
+
+> **强制项**：name、description、type、source-commit、last-reviewed-at。
+> **可选项**：reviewer（评审中的文档可填 "待 [S2-T7] 评审"）、version（占位文档可不填）。
+
+## 4. source-commit 锁定规则
+
+- **每篇深度文档**必须锁定一个具体的 commit SHA，作为"本文档与代码 100% 对齐的时间点"。
+- 当 main 分支前进、且与文档相关代码发生变化时：
+  - 微改（重命名、注释、格式）→ 不强制更新文档，但可顺手更新 `last-reviewed-at`。
+  - 接口变化、流程改动 → **必须**修订文档，并刷新 source-commit 与 last-reviewed-at。
+- **多文档共享 commit**：本次全集统一锁定到 `feae2f2e`（基线），若后续文档修订采用新 commit，需在 INDEX.md 标注差异。
+
+## 5. 与代码版本的对齐
+
+| 文档版本 | MemoryBear 代码版本 |
+|---|---|
+| `v1.0-RCN`（候选） | 基于 `feae2f2e` 工作分支 `agent/ai/f8de881a` |
+| `v1.0`（正式） | 与下一个 release tag（如 `v0.4.0`）同步发布 |
+| `v1.1` | 与 release `v0.4.x` 增量同步 |
+| `v2.0` | 对应 4 大 Protocol 落地之后的 release（预计 `v0.5.0` 之后） |
+
+> 文档版本号**不强制**与代码版本号一致，但发布通告中需明确"对应代码版本"。
+
+## 6. 已废弃文档处理
+
+- 标记 `status: deprecated` 在 frontmatter；
+- 文件首部加显眼的 `> ⚠️ DEPRECATED · 自 v1.x 起，本文已并入 <新文档路径>` 横幅；
+- 保留 6 个月（覆盖至少一个 release cycle），之后转移到 `docs/rag/_archive/<year>/` 归档。
+
+## 7. 协议变更（如 4 大 Protocol 名称改动）
+
+- 任意涉及命名的协议（Retriever / Reranker / Embedder / Generator / GraphStore）变更，必须同步刷新：
+  1. `evolution/architecture-refactor-suggestions.md` 主文
+  2. `evolution/future-extensions-roadmap.md` 引用处
+  3. `_indexes/glossary.md`
+  4. `_indexes/file-index.md` "提议中"行
+  5. `INDEX.md` 版本与状态
+  6. 所有 Sprint-2 文档中提到该协议的章节
+- 变更记录留在 `evolution/CHANGELOG.md`（v1.1 起新建）。
+
+— **Versioning Convention · v1.0-RC1 · 2026-05-08** —