# 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** —