343a5eebe3
Some checks failed
Sync to Gitee / sync (push) Has been cancelled
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>
8.7 KiB
8.7 KiB
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 作为里程碑通告 |
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（v1.1 起新建）。每周一上午 PM 在 WS-11 评论"本周保鲜任务"通告。
3.3 修订流程（强制走 SOP）
所有修订都要遵循 _meta/review-sop.md：
- 作者自检 ≤ 30 min（用
_meta/scoring-rubric.md） - 同行评审 ≤ 48 h（≥ 同 Sprint 1 名其他作者）
- 知识运营终审 ≤ 24 h
- 通过 → 合并 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 评论"本周关注点" | 通告 |
| 每周三 | 知识运营点检本周已交付文档，必要时介入 | 评分卡更新 |
| 每周五 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 复盘 |
| 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 —