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>
85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# 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** —
|