把 RAG 系统的演进路径，做成可评审、可迁移、可拒绝的方案包。
| 它是什么 | 一个 RAG 演进的方案库与证据库。固定 RAG → GraphRAG / Agentic RAG → Agentic GraphRAG 的能力边界，并把知识准备侧与持续改进侧的两类可选增强，沉淀为可独立采用的方案包 |
| 它不是什么 | 不是 RAGFlow / TrustGraph 的 Fork，不含任何宿主运行时代码或依赖，不是可部署的 RAG 产品。它不执行检索、编译、评测或发布 |
| 你会得到 | 两个方案包（各含四视图、产品决策树、宿主嵌入、契约、治理、评测、D0-D5 工程交付）、一份宿主能力探针、一套共享评测基线、40 条带五维证据坐标的外部主张 |
| 你不会得到 | 可运行的代码、宿主兼容性结论、被实验验证的收益数字 |
| 适合谁 | 正在评估「要不要给现有 RAG 系统加一层能力」的产品负责人、架构师、平台工程与治理团队 |
方案包中出现的接口、字段与伪代码一律标注
Illustrative / Non-normative，是沟通示例而非实现规格。这条纪律贯穿全仓——见凭什么可信。
不从架构出发，从你能观察到的症状出发：
| 你观察到的症状 | 根本缺什么 | 对应方案 |
|---|---|---|
| 同一类知识理解在每次查询时被重复执行；跨来源的关系、版本、冲突语义在检索结果里丢失 | 知识准备阶段没有沉淀结构、来源与版本 | Scheme A |
| RAG 失败反复出现；修复靠人工经验；根因跨数据 / 检索 / Agent / 生成多层；改完没有回归与回滚证据 | 运行反馈到变更发布之间没有受治理的闭环 | Scheme B |
| 两类症状同时存在 | 两侧都缺 | 分别评估，最后再看 Composition |
| 说不清失败样本、业务指标或可比较的 Baseline | 问题本身还没被定义 | 哪个都先别用，先去 共享业务场景 与 指标与评测纪律 |
最后一行不是客套。没有可复现问题和业务结果时，正确动作是先建立 Baseline——本项目的所有采用路径都从这里开始，而不是从选方案开始。
比「它能做什么」更重要的一节。出现以下任一情况，本项目对你的价值很低：
- 你要的是能跑的代码。 这里没有实现，只有可转化为工程计划的设计、契约与验证方法。
- 你要的是「哪个 RAG 框架最好」的答案。 本项目对九个外部项目做固定版本审计，但不做排名，也不给采购建议。
- 你的 RAG 系统还没有稳定的失败样本。 两个方案都以「可复现的问题」为输入前提。
- 你希望方案自动诊断你的现状。 这里提供的是判断框架与探针清单，需要你的团队自己填。
- 你需要现成的收益数字来说服决策层。 所有价值假设尚未被任何实验支持，本项目明确拒绝提供未经验证的数字。
RAG-Evolution-Playbook/
├── README.md 你在这里 —— 唯一的双任务路由器
├── AGENTS.md AI 工具进入仓库的纪律与读取顺序
│
├── foundation/ 6 篇 项目宪章、总体架构、信息架构、边界规则、术语、方案包共同蓝图
├── research/ 12 篇 证据账本（40 条 Claim）、概念图、9 份固定版本项目档案、Host Probe
├── baseline/ 5 篇 两个方案共享的业务场景、语料规范、问题与失败分类、评测纪律
│
├── schemes/ ← 核心交付物
│ ├── compiled-knowledge-for-rag/ 15 篇 Scheme A：知识编译（宿主 RAGFlow）
│ └── governed-rag-improvement/ 16 篇 Scheme B：受治理改进（宿主 TrustGraph）
│
├── composition/ 4 篇 两侧同时采用时的五类契约、编排、冲突与降级（可选）
├── tooling/loop-skill/ Reserved / Incubating —— 不是第三个方案
│
├── project/ 过程证据：路线图、决策、执行、审阅、质量、复盘、模板
├── docs/superpowers/ 已批准的设计规格与分阶段实施计划
└── scripts/check_docs.py 全仓一致性检查（无第三方依赖）
每个方案包内部使用同一套结构，读完一个就会读另一个：
schemes/<scheme>/
├── README.md 四视图导航与角色重点
├── product/ V1 产品决策：何时适用、何时拒绝
├── architecture/ V2 参考架构 + 宿主嵌入责任矩阵
├── contracts/ V3 最小契约（字段为 Illustrative）
├── governance/ V3 自治等级、门禁、安全与信任边界
├── evaluation/ V3 假设、指标、分层报告纪律
├── adoption/ 分阶段迁移路径与退出方法
├── validation/ V4 固定版本宿主深档案 + 未来验证简报
├── delivery/ V4 D0-D5 工程交付与证据包
├── evidence/ 该方案筛选过的外部证据与能力缺口
└── decisions/ 包内 ADR
flowchart LR
RAG["RAG<br/>检索增强生成主流程"]
GRAG["GraphRAG<br/>结构化知识组织"]
ARAG["Agentic RAG<br/>运行时规划与控制"]
AGRAG["Agentic GraphRAG<br/>结构与运行时决策结合"]
CKA["+ Scheme A<br/>Compiled Knowledge for RAG<br/>知识准备与查询输入侧"]
GRI["+ Scheme B<br/>Governed RAG Improvement<br/>Runtime 外围的改进外环"]
COMP["Composition<br/>可选组合规范"]
RAG --> GRAG
RAG --> ARAG
GRAG --> AGRAG
ARAG --> AGRAG
AGRAG -->|"可选增强，可单独采用"| CKA
AGRAG -->|"可选增强，可单独采用"| GRI
CKA -.->|"仅在两侧都需要时"| COMP
GRI -.->|"仅在两侧都需要时"| COMP
这张图表达能力关系，不是所有 RAG 系统都必须依次通关的成熟度阶梯。RAG 的主流程始终是被增强、被治理和被验证的对象；两个方案可以分别采用、分别降级、分别退出。更细的物质化切入位置见总体架构。
每条路径都写明你做什么 / 你得到什么 / 什么时候停。第三项最重要——知道何时停止，才不会把文档读成义务。
| 步骤 | 你做什么 | 你得到什么 |
|---|---|---|
| 1 | 读概念图 | 四种形态各自解决什么、又尚未自动解决什么 |
| 2 | 挑一个感兴趣的项目，读固定版本档案 | 该项目在某个固定 commit 上实际存在什么 |
| 3 | 顺着正文的 Claim ID 进证据账本 | 这句话是谁、在什么版本、什么日期说的 |
| 4 | 读该 Claim 的五维坐标 | 这条证据有多强：Claim Type / Source Strength / Verification Depth / Applicability Scope / Result State |
| 5 | 读配套的 Inference 条目 |
越过这条证据会说错什么 |
什么时候停：当你能对某个项目说出「它有 X，但不能由此推出 Y」时，这条路径的目的已经达到。
一个完整的 walkthrough 例子（TrustGraph）
概念图区分 GraphRAG 与「受治理改进」是两类不同能力 → TrustGraph 项目档案固定 v2.7.8@60529c3b 与代码入口 → 账本 TG-005 记录固定树中 Flow、Agent orchestration、GraphRAG、structured query、provenance 与多层测试入口可定位 → 其坐标为 Fact / Pinned Code-Test / Located / Pinned Project Version / Pass，即「入口存在且已定位」，测试本轮未运行 → TG-006 显式写出不能推出完整受治理闭环，其中 Improvement Case、Checkpoint、Sandbox、Independent Checker、Approval、RAG Release 与 Rollback 为 Missing → 想知道这些责任如何被补齐，进入 Governed RAG Improvement。
这条链上的每一跳都可以点击走通，无需退回本页。
| 步骤 | 你做什么 | 你得到什么 |
|---|---|---|
| 1 | 固定可复现的失败样本、目标业务结果与 Baseline | 一个值得处理的问题，而不是一个想用的新架构 |
| 2 | 读对应方案的产品决策指南，做适用性初筛 | 拒绝 / 阻断 / 继续评估 三选一 |
| 3 | 用 Host Capability Probe 调查 P01-P12 | 你的完整宿主组合（不是单个框架）能承接什么 |
| 4 | 填 Host Profile 与 Adoption Brief | 一份可被独立审阅的采用判断 |
| 5 | 仅当判定为「继续评估」，进入 Engineering Handoff 的 D0-D5 | 可交给工程的验证输入与停止条件 |
什么时候停：任何一步得出「拒绝」就停止并记录理由；得出「阻断」就先关闭 Gap，重新回到第 3 步，而不是硬闯 D0-D5。
这里的「采用方案包」指人使用文档、探针与模板形成采用输入，不是调用已部署的 API。路径走通只表示你能形成工程验证输入，不等于已经采用、适配或验证。
方案内容之外，本仓库的过程设计本身是可复用的：五维证据坐标、Normative / Illustrative 分级、每阶段两道门禁、按缺陷而非按文件派发修复。相关记录在 复盘账本 与 质量控制规则。
什么时候停：这些是针对「多阶段、多来源、易漂移的文档密集型项目」设计的。如果你的项目不具备这些特征，直接套用会让流程成本超过收益——质量控制规则 §5 专门规定了何时必须削减流程。
两个包各自自足：读懂任何一个都不要求先读另一个，也不要求先读 Composition。
Compiled Knowledge for RAG · Scheme A
把重复的知识理解从查询时前移到离线或准离线编译，产出带结构、来源、版本、权限与冲突信息的 Knowledge Artifact，并用结构化 Query 把意图、过滤、证据要求与预算传给现有 RAG Runtime。它增强知识准备与查询输入，不替代 Plan / Retrieve / Reason / Answer。
何时不适用 Scheme A（6 条）
- 没有可复用的任务族、可冻结的评测集或可管理的制品生命周期——编译成本无法摊销。
- 来源无法快照，或许可、ACL、有效期无法固定。
- 宿主既不允许 Query-time Sidecar，也不允许版本化索引投影，且没有明确回退路径。
- 团队无法承担离线编译、制品存储与新鲜度维护成本。
- 真正的问题是「变更没有回归和回滚证据」而不是「知识没有结构」——那属于 Scheme B。
- 期望它自动修复低质量来源，或把制品当成脱离来源的正确答案缓存。
Governed RAG Improvement · Scheme B
在现有 RAG Runtime 外围建立持久、受控的改进外环：从不可信 Trace 发现失败 → 形成可审阅的 Improvement Case → 隔离环境由 Maker 生成候选 → 独立 Checker 评估完整 Sandbox RAG Release → 风险门与人类审批 → 条件发布 → 监控、整组回滚与停止路径。默认自治等级 L1 Assisted，明确不支持无边界自动写回。
何时不适用 Scheme B（5 条）
- Trace 无法关联问题、检索、证据、回答、反馈与完整资产版本——此时只能停在 L0 观察 / 报告。
- 目标资产不可版本化、不能在隔离环境组装，或不能整组回滚。
- Maker、Checker、Approver 的责任与身份无法分离。
- 没有冻结回归、安全与权限硬门、发布监控与人工接管。
- 期望的是模型自动学习、无审批的自动写回，或对基础模型权重的训练与修改——这些是明确非目标。
两个方案共享同一个企业产品与技术支持知识库场景（产品文档、版本兼容信息、FAQ、错误码、工单、过期答案、冲突与权限差异），使未来两个宿主验证项目在检验不同假设时仍使用相同的业务语义与评测纪律。见 baseline/。
Composition 只回答一个问题：当采用方同时需要两侧能力时，两个包如何通过 Artifact / Query / Trace / Change / Release 五类契约连接。它不是第三个方案包，不是成熟度阶梯，也不是理解或采用任一方案的前置。
两个方案共用同一条判定路径。三个分支语义互斥——这是本项目在实施中返工三轮才对齐的地方：
flowchart TD
P["可复现的失败证据<br/>+ 目标业务结果 + 共享 Baseline"] --> F{"方案适用性初筛<br/>V1 产品决策"}
F -->|"已证实不匹配 / 无业务结果 / 无法安全退出"| REJ["拒绝<br/>停止当前提议，保留理由与证据"]
F -->|"通过初筛"| PROBE["Host Capability Probe<br/>P01-P12 · 完整宿主组合"]
PROBE --> PROF["固定 Host Profile"]
PROF --> BRIEF{"Adoption Brief 判定"}
BRIEF -->|"证据不足 / 未知 / 尚未准备好"| BLK["阻断<br/>关闭 Gap 后重新进入 Probe"]
BRIEF -->|"已证实不匹配"| REJ
BRIEF -->|"证据充分且准备度足够"| GO["继续评估"]
GO --> D["Engineering Handoff<br/>D0 → D5"]
BLK -.->|"Gap 关闭且满足重入条件"| PROBE
判定规则一句话：证据不足 → 阻断（可重入）；已证实不匹配 → 拒绝（终止）。只有「继续评估」进入 D0-D5，「阻断」不得绕过 Gap 直接进入交付。
一个方案库最容易犯的错，是把营销材料、技术规格与实际代码混为一谈。本项目用三条机制隔离它们。
一、每条外部主张进账本，带五维坐标。 正文只按 Claim ID 引用，不重复陈述事实。
| 反例（不接受） | 正例（本仓库的实际写法） | |
|---|---|---|
| 陈述 | 「TrustGraph 提供完整的知识治理闭环」 | 「TG-005：固定树 v2.7.8@60529c3b 中 Flow、orchestration、GraphRAG、provenance 与多层测试入口可定位；测试本轮未运行」 |
| 边界 | 无 | 「TG-006：不能由此推出完整受治理闭环——Improvement Case、Checkpoint、Sandbox、Checker、Approval、Release、Rollback 为 Missing」 |
| 可核验 | 否 | 来源 URL + commit SHA + 核验日期 + 具体源码路径 |
二、区分 Normative 与 Illustrative。 责任、权威状态、版本与权限语义、失败行为、门禁、退出语义是规范性的；字段名、Endpoint、JSON 与伪代码一律标注 Illustrative / Non-normative——防止示例被采用方当成必须服从的接口。
三、Unknown 不等于 Missing。 「审计未覆盖」记 Unknown，「已确认不提供」才记 Missing。这条区分在实施中被违反过一次（把未裁定的能力记成了 Missing 并错误归因到某条 Claim），由独立复核发现并修正，过程完整保留。
自动化保障：scripts/check_docs.py 在每次 push 与 PR 上校验链接与锚点、Claim 定义与引用覆盖、Mermaid 与 JSON 结构、固定版本引用、越权措辞与占位符。它不使用任何第三方依赖。
| 层 | 权威真源 | 当前状态 |
|---|---|---|
| 项目整体阶段 | 路线图 | 主干 Foundation、证据库、共享 Baseline、两个方案、Composition 与 Skill 孵化边界已建立并通过 Handoff 验收 |
| 方案包 2.0 增强 | 增强总盘计划 | 六阶段全部 Completed |
| 验收等级 | Evidence Delivery Package 的 G0-G5 表 | G0 文档完整 / G1 证据完整 / G2 方案可交接已由 Phase 5 全仓验收判定通过 |
以下结论当前都不成立，本仓库任何文件都不得声称它们成立：
- G3 宿主适配就绪、G4 实验成立、G5 生产采用。 G2 的允许结论仅为「可进入宿主适配规划」，不含 P01-P12 已在采用方环境通过、可启动实验或价值已被验证。
- RAGFlow 或 TrustGraph 与两个方案宿主兼容，或任一方案的价值假设已被实验支持。
- 存在可部署的编译器、Sidecar、Projection、Adapter、Sandbox、独立 Checker、审批系统、控制面、发布或回滚服务。
- RAGFlow / TrustGraph 独立验证仓库已经创建——它们尚未创建，是否启动仍需确认路线图交接卡列出的宿主版本、数据、预算、凭据、责任人与退出规则。
「Handoff 验收」与「G2」是两把不同的尺子：前者判定主干方案库可交接给后续工程判断，后者是 G0-G5 验收等级中的一级。两者现均已通过，但各自独立——前者通过不蕴含后者成立。
阶段事实分层保存：执行记录证明实际做了什么，审阅记录证明阶段 Gate 是否通过，质量记录保存阻断与允许动作。失败过程与负面结果不删除——包括未收敛的修复轮次与验收脚本自身的误报。
角色最短路径的权威位置是信息架构。每条路径最多五个文件；目标方案 指 Scheme A 或 B 之一，不要求先读另一个方案。
| 角色 | 先回答什么 | 入口 |
|---|---|---|
| 产品 / 业务 | 问题是否值得由该方案处理，价值与代价是什么 | 产品决策路径 |
| 架构 / 技术负责人 | 方案从常规 RAG 的哪个平面切入，责任与信任边界 | 架构决策路径 |
| 工程 / SRE | 状态、版本、并发、权限、幂等、失败与回滚的可测试语义 | 工程执行路径 |
| 安全 / 治理 / 评测 | 身份分离、硬门、保护指标、回滚演练与负面结果留存 | 安全与治理路径 |
| AI 工具 | 进入仓库的信息依赖顺序与纪律 | 先读 AGENTS.md，再看 AI 工具读取顺序 |
| 我要做的事 | 从哪里开始 |
|---|---|
| 理解项目命题、目标与非目标 | 项目宪章 |
| 看两个方案从常规 RAG 的哪里切入 | 总体架构 |
| 找某类信息的权威位置与角色路径 | 信息架构 |
| 核对责任边界、表达等级与禁止交叉 | 边界规则、术语表 |
| 了解一个方案包必须自足回答哪些问题 | 方案包共同蓝图 |
| 追踪外部主张与证据强度 | 证据账本、概念图 |
| 调查自己的完整宿主组合能承接什么 | Host Capability Probe |
| 采用 Scheme A / Scheme B | Scheme A · Scheme B |
| 同时采用两侧并核对跨方案契约 | Composition |
| 准备未来宿主验证 | RAGFlow 验证简报 · TrustGraph 验证简报 |
| 核对项目计划、状态与验收证据 | Project Evidence |
| 查看已批准的设计规格 | 主干规格 · 方案包 2.0 规格 · Walking Skeleton 增补 |
| 作为 AI 工具进入本仓库 | AGENTS.md |
本项目最需要的贡献是证据维护——外部项目在演进，固定版本会过期，来源链接会失效。
- 发现某条 Claim 与实际情况不符：提 证据问题，带 Claim ID、来源 URL 与核验日期。
- 在 Probe / Profile / Adoption Brief 使用中卡住：提 采用问题。
- 提交前请读 CONTRIBUTING.md——本项目的证据纪律与常规文档项目不同，并运行
python scripts/check_docs.py。
另见 行为准则 与 安全披露。变更历史见 CHANGELOG.md。
Apache License 2.0。选择理由、备选方案与回滚条件见 ADR-0002。
本仓库对外部项目（RAGFlow、TrustGraph、Pinecone Nexus 及五个框架）的描述均基于固定版本的公开材料只读审计，不构成对这些项目的评价、推荐或兼容性承诺；各自的许可与商标归其权利人所有。