Files

Multica PM Agent 343a5eebe3

Sync to Gitee / sync (push) Has been cancelled

Details

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

3.8 KiB

Raw Blame History

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，包括：

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

3.8 KiB Raw Blame History Unescape Escape