鲲鹏 / RAG_ · Files

Go to a project
产品研发RAG_总体方案与实施手册.md 21.6 KB 
title: 产品研发 RAG 总体方案与实施手册
status: active
owner: xwk
updated_at: 2026-03-19

1. 文档目标

本文是当前项目的唯一主方案文档，用于统一回答下面几件事：

  1. 这个 RAG 项目要解决什么问题
  2. 现有数据资产有哪些，质量如何
  3. 技术架构和数据流怎么设计
  4. 当前仓库里的脚本和产物分别做什么
  5. 如何重新生成知识库、如何导入、如何日常维护
  6. 后续如何扩展到需求预评审和代码知识库

不再建议继续维护多份平行方案文档。

2. 项目目标

2.1 业务目标

这个项目最终要服务三类能力：

能力一：产品逻辑问答（已完成）

用户通过对话直接询问：

  • 某个功能现在怎么做
  • 哪些场景会报错
  • 某个按钮/弹窗/校验规则是什么
  • 某个功能从哪个版本开始变化

能力二：需求 AI 预评审（待完善）

当新增需求时，AI 应能基于现有知识库输出：

  • 影响模块
  • 影响触点
  • 已有相似规则
  • 潜在冲突
  • 建议补充的测试场景

能力三：代码知识库底座（待实现）

后续把接口、服务、前后端代码说明接到同一套知识骨架上，形成：

  • 产品规则
  • 版本演进
  • 技术实现

三层联动的知识体系。

2.2 当前阶段目标

当前阶段不追求“一步到位的完美智能体”，而是先把以下基础能力稳定下来：

  1. 统一知识生产链
  2. 统一知识索引层
  3. 最终可导入的合成知识库
  4. 可复跑、可迭代、可增量更新

3. 当前资产现状

3.1 已有原始资产

项目当前已经具备四类核心输入：

培训文档

  • 来源：飞书文档导出 PDF
  • 目录：pdf/
  • 特点：
    • 相对接近产品官方描述
    • 有版本信息
    • 但 PDF 导出后会有断行、标题丢失、版式噪声

测试用例

  • 来源：迭代测试 XML
  • 目录：testCase/
  • 特点：
    • 行为和回归场景丰富
    • 对异常、边界、校验类问题很有价值
    • 但大量步骤是枚举式表达，语义不稳定

Figma 规则

  • 来源：Figma 链接和已产出的 rule atoms
  • 目录：inputs/figma/、build/*/rule_atoms.jsonl
  • 特点：
    • 对页面交互、弹窗、toast、按钮态最强
    • 但业务背景往往不完整

后台代码仓库

  • 来源：后台 Java 多模块仓库
  • 当前接入路径：/Users/xwk/Downloads/studio-server2
  • 特点：
    • 对接口路径、鉴权、枚举、状态机、异常约束最强
    • 适合补“系统实际上怎么实现、受什么条件限制”
    • 不直接定义产品主事实

高优先参考文档

  • 来源：测试同学或产品同学人工整理的专项说明
  • 目录：inputs/priority_refs/
  • 特点：
    • 通常聚焦单一主题
    • 比普通测试补充更干净
    • 适合在培训文档未覆盖专项细节时，作为强参考

3.2 现状判断

当前项目不是“没有数据”，而是“数据已经够用，但知识层还不够稳定”。

主要问题：

  • 老的 case_atoms.jsonl 中仍有 [截图]、满足预期、枚举步骤等噪声
  • 老的 doc_atoms.jsonl 有 PDF 切分断裂问题
  • 历史产物按版本分散存放，缺少统一知识索引
  • 版本演进和需求预评审能力没有被组织成独立知识层

所以当前正确定位是：

  • 原始资产层：可用
  • 候选原子层：可用但不稳定
  • 统一知识索引层：已补齐
  • 最终合成知识库：已可用

4. 总体架构

4.1 分层架构图

flowchart TB
    A[培训文档 PDF 主事实源] --> B[结构化抽取]
    C[Figma 链接与规则 交互细节补充源] --> B
    D[测试用例 XML 行为验证与边界补充源] --> B
    X[后台代码仓库 实现补充源] --> Y[代码扫描与蒸馏]

    B --> E[候选层 Candidate]
    E --> F[语义蒸馏 / 合成原子]
    F --> G[质量校验]
    G --> H[统一知识索引层 主轴: feature_scope + app_version + 来源优先级]
    H --> I[最终合成知识库 培训文档主事实层与补充层]
    Y --> I

    H --> M[模块标签 辅助过滤与路由]
    I --> J[产品逻辑问答]
    I --> K[需求 AI 预评审]
    I --> L[代码影响分析与实现约束问答]

4.2 四层说明

第一层：Raw 原始资产层

保存原始输入，不做知识承诺。

包括：

  • pdf/*.pdf
  • testCase/*.xml
  • inputs/figma/*
  • inputs/priority_refs/*

第二层：Candidate 候选层

把原始资产解析成更适合模型和脚本处理的结构化中间层。

包括：

  • build/<version>/case_candidates.jsonl
  • build/<version>/doc_segments.jsonl

第三层：Atom 层

分成两类：

  • 历史原子：case_atoms.jsonl、doc_atoms.jsonl、rule_atoms.jsonl
  • 增强原子：case_atoms_model.jsonl、doc_atoms_model.jsonl

增强原子带有：

  • confidence
  • qa_status

用于在统一索引中优先覆盖旧原子。

第四层：Knowledge 层

统一索引与最终知识库：

  • dist/rag/
  • dist/final_kb/
  • dist/backend_code/
  • dist/usable_kb/
  • dist/dify_import/

这是实际对接 Dify / Bot 的主输出层。

4.5 事实源优先级与冲突裁决

这套体系里，三类原始资产不是平级关系，必须明确主次。

固定优先级：

  1. 培训文档
  2. Figma
  3. 测试用例

说明：

  • 这条优先级只用于“产品事实裁决”
  • 后台代码不参与主事实抢占
  • 后台代码只作为“实现补充层”

事实源裁决图

flowchart TD
    A[同一功能出现多来源信息] --> B{培训文档是否存在}
    B -->|是| C[以培训文档为主事实]
    B -->|否| D{Figma 是否存在}
    D -->|是| E[以 Figma 补充事实]
    D -->|否| F[以测试用例作为候选补充事实]
    C --> G[补充 Figma 交互细节]
    G --> H[补充测试用例边界/异常]
    E --> H
    F --> I[标记为候选事实或待确认]

为什么这样定

培训文档

培训文档是主事实源。

原因：

  • 内容覆盖最全
  • 最接近产品口径
  • 不仅有预定义模块内容，也有大量跨模块、非标准模块、背景性产品逻辑

因此原则是：

  • 培训文档必须完整保留
  • 不能因为模块体系而过滤
  • 不能因为不是 INCOME / INQUIRY / ... 这些预定义模块就丢弃

Figma

Figma 是交互细节补充源。

主要补：

  • toast
  • 弹窗
  • 按钮状态
  • 默认值
  • 页面交互和流程表现

当培训文档未覆盖这些细节时，Figma 用来补足。

测试用例

测试用例是行为验证与边界补充源。

主要补：

  • 异常场景
  • 边界条件
  • 回归行为
  • 历史遗留逻辑

测试用例不应直接定义“产品主事实”，而应作为：

  • 培训文档规则的验证证据
  • 培训文档缺失时的候选补充事实

冲突裁决规则

培训文档 vs Figma

  • 默认培训文档优先
  • 如果培训文档明显是旧版本，而 Figma 是更高版本，则以更高版本为准，并保留演进说明

培训文档 vs 测试用例

  • 默认培训文档优先
  • 测试用例作为验证层证据，不抢主事实定义权

Figma vs 测试用例

  • 交互表现、文案、按钮态：优先 Figma
  • 边界场景、异常路径、回归验证：优先测试用例

多版本冲突

  • 最新版本优先
  • 同时保留版本演进
  • 不允许直接覆盖掉历史变化线索

最终落地原则

在最终知识库里，事实源角色应固定为：

  • 培训文档：规则主事实源
  • Figma：交互细节事实源
  • 测试用例：行为验证与边界补充源
  • 后台代码：接口契约、枚举状态、实现约束补充源

5. 数据流与流程图

5.1 知识生产主流程

flowchart LR
    A[培训文档 PDF] --> B[提取结构]
    C[Figma 规则] --> B
    D[测试用例 XML] --> B

    B --> E[Candidate 层]
    E --> F[模型蒸馏 / 启发式合成]
    F --> G[*_model.jsonl]
    G --> H[质量校验]
    H --> I[来源优先级合并]
    I --> J[统一索引 dist/rag]
    J --> K[最终知识库 dist/final_kb]

    L[模块标签] -.辅助元数据.-> J

5.2 问答流程

flowchart TD
    Q[用户提问] --> A{问题类型}
    A -->|产品逻辑| B[先查培训文档主事实 再补 Figma 与测试细节]
    A -->|版本变化| C[版本演进文档 与 功能主题索引]
    A -->|需求预评审| D[预评审文档 与 功能主题索引]
    B --> E[生成回答]
    C --> E
    D --> E

5.3 需求预评审流程

flowchart TD
    A[输入新需求] --> B[识别模块]
    B --> C[召回相似功能主题]
    C --> D[优先检查培训文档主事实]
    D --> E[补查 Figma 交互细节]
    E --> F[补查测试用例边界与异常]
    F --> G[检查历史版本变化]
    G --> H[检查跨模块触点]
    H --> I[输出影响范围 / 风险 / 建议]

6. 目录与核心产物说明

6.1 docs

当前保留的文档职责：

  • docs/产品研发RAG_总体方案与实施手册.md
    • 主方案文档
  • docs/Figma链接索引_来自历史对话_v1.md
    • Figma 历史链接索引
  • docs/version_sync_template.yaml
    • 新版本同步模板
  • docs/version_sync_v4.57.3.yaml
    • 已有版本同步样例

6.2 build

按版本存储中间层与候选层产物：

  • rule_atoms.jsonl
  • case_atoms.jsonl
  • doc_atoms.jsonl
  • case_candidates.jsonl
  • doc_segments.jsonl
  • case_atoms_model.jsonl
  • doc_atoms_model.jsonl

6.3 dist/rag

统一知识索引层：

  • master_atoms.jsonl
  • feature_catalog.jsonl
  • review_index.jsonl
  • knowledge_v2/*.md

6.4 dist/final_kb

最终可导入知识库：

  • 00_导入说明.md
  • 01_知识库设计原则.md
  • 02_培训文档主事实库.md
  • 03_培训文档保留项.md
  • 04_Figma与测试补充库.md
  • 05_版本演进.md
  • 06_需求预评审.md
  • 07_模块辅助索引.md
  • 08_后台代码实现补充库.md

6.5 dist/backend_code

后台实现补充知识：

  • code_atoms.jsonl
  • 01_接口契约.md
  • 02_枚举与状态.md
  • 03_实现约束.md
  • 04_模块映射.md
  • 05_业务实现主题.md

6.6 dist/usable_kb

面向日常问答和预评审的可用知识库包：

  • 00_导入说明.md
  • 01_知识库使用规则.md
  • 02_版本变更总览.md
  • 03_需求预评审执行指南.md
  • 04_后台实现导读.md
  • 10_AUTH_认证.md
  • 11_INCOME_收入提现.md
  • 12_INQUIRY_问诊.md
  • 13_CLINIC_门诊.md
  • 14_PATIENT_患者.md
  • 15_NOTIFICATION_通知.md
  • 16_BACKSTAGE_后台.md
  • 17_GENERAL_通用.md

6.7 dist/dify_import

面向 Dify / 通用 RAG 平台的中颗粒度导入包：

  • 00_导入说明.md
  • 01_使用规则.md
  • 02_版本变更总览.md
  • 03_需求预评审执行指南.md
  • 04_后台实现导读.md
  • 09_AUTH_高优先参考_医师认证流程.md
  • 10_AUTH_主知识库.md
  • 11_INCOME_主知识库.md
  • 12_INQUIRY_主知识库.md
  • 13_CLINIC_主知识库.md
  • 14_PATIENT_主知识库.md
  • 15_NOTIFICATION_主知识库.md
  • 16_BACKSTAGE_主知识库.md
  • 17_GENERAL_主知识库.md

7. 关键脚本说明

7.1 抽取层

scripts/extract_testcase_candidates.py

作用：

  • 把 XML 解析成结构化 testcase candidates

输出：

  • build/<version>/case_candidates.jsonl

scripts/extract_pdf_segments.py

作用：

  • 把 PDF 解析成结构化 doc segments

输出：

  • build/<version>/doc_segments.jsonl

7.2 原子层

scripts/build_synthesized_atoms.py

作用：

  • 在没有外部模型时，基于 candidates/segments 批量合成更干净的 atoms

输出：

  • build/<version>/case_atoms_model.jsonl
  • build/<version>/doc_atoms_model.jsonl

scripts/normalize_model_atoms.py

作用：

  • 当你接入外部模型后，把模型输出规范化回仓库

7.3 校验与索引层

scripts/validate_atoms.py

作用：

  • 检查 atoms 质量问题

输出：

  • dist/quality/atom_quality_summary.md
  • dist/quality/atom_issues.jsonl

scripts/build_rag_assets.py

作用：

  • 聚合所有 atoms
  • 生成统一知识索引

输出：

  • dist/rag/*

scripts/build_final_knowledge_base.py

作用：

  • 从统一索引生成最终可导入知识库

输出：

  • dist/final_kb/*

scripts/build_backend_code_knowledge.py

作用：

  • 扫描后台代码仓库
  • 生成接口契约、枚举状态、实现约束三类实现补充知识

输出：

  • dist/backend_code/*
  • dist/final_kb/08_后台代码实现补充库.md

scripts/build_usable_knowledge_pack.py

作用：

  • 把主事实、补充事实、后台实现信息整理成一套更适合直接使用的知识库包

输出：

  • dist/usable_kb/*

scripts/build_dify_import_pack.py

作用：

  • 把 dist/usable_kb/ 整理成中颗粒度导入包
  • 保留公共文件和模块主文件
  • 自动吸收 inputs/priority_refs/*.md 这类高优先参考文件
  • 交给 Dify 在导入时继续做内部切分

输出：

  • dist/dify_import/*

8. 当前推荐运行手册

8.1 全量重建

按顺序执行：

python3 scripts/extract_testcase_candidates.py
python3 scripts/extract_pdf_segments.py
python3 scripts/build_synthesized_atoms.py
python3 scripts/validate_atoms.py
python3 scripts/build_rag_assets.py
python3 scripts/build_final_knowledge_base.py
python3 scripts/build_usable_knowledge_pack.py
python3 scripts/build_dify_import_pack.py

如需同时接入后台代码仓库，再执行：

python3 scripts/build_backend_code_knowledge.py --repo /Users/xwk/Downloads/studio-server2
python3 scripts/build_final_knowledge_base.py
python3 scripts/build_usable_knowledge_pack.py
python3 scripts/build_dify_import_pack.py

8.2 指定版本重建

python3 scripts/extract_testcase_candidates.py 4.57.3
python3 scripts/extract_pdf_segments.py 4.57.3
python3 scripts/build_synthesized_atoms.py 4.57.3
python3 scripts/build_rag_assets.py
python3 scripts/build_final_knowledge_base.py
python3 scripts/build_usable_knowledge_pack.py
python3 scripts/build_dify_import_pack.py

8.3 接入外部模型时

如果后续用 OpenAI / Claude / Dify 工作流做更高质量蒸馏，推荐流程：

python3 scripts/extract_testcase_candidates.py
python3 scripts/extract_pdf_segments.py
# 使用 prompts/*.md 驱动模型批量生成 atoms
python3 scripts/normalize_model_atoms.py model_output_case.jsonl case
python3 scripts/normalize_model_atoms.py model_output_doc.jsonl doc
python3 scripts/validate_atoms.py
python3 scripts/build_rag_assets.py
python3 scripts/build_final_knowledge_base.py

8.4 增量更新推荐做法

如果只是新版本上线，优先跑增量链路，而不是每次手动拼命令：

bash scripts/rebuild_version_kb.sh 4.57.3 /Users/xwk/Downloads/studio-server2

如果是脚本逻辑、知识结构、历史规则做了明显调整，再跑全量：

bash scripts/rebuild_all_kb.sh /Users/xwk/Downloads/studio-server2

8.5 新专项文档接入

如果拿到类似“医师认证流程”这种人工整理后的专项文档：

  1. 原始文件放到 inputs/priority_refs/
  2. 整理出一份清晰 Markdown，也放到 inputs/priority_refs/
  3. 执行：
python3 scripts/build_dify_import_pack.py
  1. 把新生成的高优先参考文件上传到 Dify 的“产品主知识库”

9. 当前输出结果说明

截至当前仓库状态，项目已经生成了最终合成知识库：

  • 目录：dist/final_kb/

它已经具备以下特性：

  • 按模块组织
  • 包含当前规则
  • 包含版本演进
  • 包含预评审线索
  • 能直接导入知识库系统

当前索引层和最终库已经优先使用增强原子。

但从设计原则上，最终库后续应继续朝下面这条方向收敛：

  • 以培训文档为主事实层
  • 以功能主题和版本演进为主组织方式
  • 以模块作为辅助索引，而不是主切分维度
  • 用 Figma 和测试用例补足培训文档未覆盖的细节与边界

也就是说，最终库的目标不是“把所有内容先塞进模块”，而是“先保住主事实，再提供模块化检索能力”。

10. 质量控制策略

10.1 目前的主要噪声

历史数据里仍然存在：

  • [截图]
  • 满足预期
  • 纯枚举动作
  • PDF 断句碎片

10.2 当前处理策略

已经采取的策略：

  1. 最终知识库层做过滤
  2. 候选层和增强原子分开存放
  3. 统一索引优先使用：
    • 同源更高质量
    • validated
    • 更高 confidence

10.3 后续最优解

当前的 build_synthesized_atoms.py 是“无外部模型时的替代方案”，它比旧 atoms 干净，但还不等于真正的高质量语义蒸馏。

最佳做法仍然是：

  • 用模型重做 case_atoms
  • 用模型重做 doc_atoms
  • 再用 normalize_model_atoms.py 回写

10.5 模块体系的定位

模块最初是为了帮助 AI 分类，但在当前项目目标下，模块不应该成为知识组织的主轴。

为什么不能把模块当主轴

原因有三点：

  1. 培训文档里存在大量非预定义模块的产品逻辑
  2. 同一条规则可能天然跨模块
  3. 如果以模块作为硬边界，会误伤培训文档的完整性

因此模块不适合承担：

  • 知识切分主键
  • 合并主键
  • 培训文档是否保留的过滤条件

模块应该承担什么角色

模块建议保留，但降级为辅助元数据。

适合承担：

  • 检索过滤
  • 路由提示
  • 需求预评审时的影响范围提示
  • 未来代码知识库的粗粒度归属

这套体系真正的主轴是什么

建议以三件事作为主轴：

  1. feature_scope
  2. app_version
  3. 事实源优先级

也就是说：

  • 知识按功能主题组织
  • 变化按版本组织
  • 冲突按来源优先级裁决
  • 模块只作为辅助标签存在

对最终知识库的要求

最终知识库应该满足：

  • 培训文档内容完整保留
  • 非预定义模块内容允许存在
  • 能标模块则标，不能标不强行归类
  • GENERAL 只作为兜底，不代表低价值内容

11. 知识库导入手册

11.1 推荐导入内容

如果你要保留“完整知识骨架”，优先导入：

  1. dist/final_kb/00_导入说明.md
  2. dist/final_kb/01_知识库设计原则.md
  3. dist/final_kb/02_培训文档主事实库.md
  4. dist/final_kb/03_培训文档保留项.md
  5. dist/final_kb/04_Figma与测试补充库.md
  6. dist/final_kb/05_版本演进.md
  7. dist/final_kb/06_需求预评审.md
  8. dist/final_kb/07_模块辅助索引.md
  9. dist/final_kb/08_后台代码实现补充库.md

如果你要直接接 Dify / 通用 RAG 平台，优先导入：

  1. dist/dify_import/00_导入说明.md
  2. dist/dify_import/01_使用规则.md
  3. dist/dify_import/02_版本变更总览.md
  4. dist/dify_import/03_需求预评审执行指南.md
  5. dist/dify_import/04_后台实现导读.md
  6. dist/dify_import/10_AUTH_主知识库.md
  7. dist/dify_import/11_INCOME_主知识库.md
  8. dist/dify_import/12_INQUIRY_主知识库.md
  9. dist/dify_import/13_CLINIC_主知识库.md
  10. dist/dify_import/14_PATIENT_主知识库.md
  11. dist/dify_import/15_NOTIFICATION_主知识库.md
  12. dist/dify_import/16_BACKSTAGE_主知识库.md
  13. dist/dify_import/17_GENERAL_主知识库.md
  14. dist/dify_import/*高优先参考*.md

11.2 推荐使用方式

产品问答

主要使用：

  • 培训文档主事实库
  • 培训文档保留项
  • Figma 与测试补充库
  • 后台代码实现补充库

版本查询

主要使用：

  • 版本演进文档
  • 培训文档主事实库

需求预评审

主要使用：

  • 需求预评审文档
  • 模块辅助索引
  • 版本演进文档
  • Figma 与测试补充库
  • 后台代码实现补充库

11.3 当前 Dify 实施经验

当前实测有效的参数是：

  • 分段标识符：\n\n
  • 分段最大长度：1200
  • 分段重叠长度：100
  • 索引方式：高质量
  • 检索方式：混合检索
  • Top K：5
  • Score 阈值：先不开
  • Rerank：能开就开
  • Embedding：text-embedding-v4

当前实测更稳的 Dify 结构是三库：

  1. 产品主知识库
  2. 版本与预评审知识库
  3. 后台实现补充知识库

原因：

  • 底层知识资产是一套
  • 但 Dify 里的知识库同时承担检索域职责
  • 按用途拆分后，普通问答、版本追溯、后台实现约束的召回更稳

11.4 未来 AI 的接手入口

为了避免上下文丢失后无法继续维护，仓库里保留了三类持续化资产：

  • docs/产品研发RAG_增量更新与Dify维护手册.md
  • docs/产品研发RAG_接手说明.md
  • skills/product-rag-maintainer/SKILL.md

新 AI 或新同学接手时，优先阅读这三份资产。

12. 未来扩展方案

12.1 接入需求文档 / 评审记录

建议新增：

  • PRD atoms
  • 评审决策 atoms

这样可以补齐“为什么这样设计”。

12.2 接入代码知识

当前已经完成第一版代码接入：

  • controller 接口契约
  • enum / constant 枚举与状态
  • Assert / BusinessException / RequestLock 实现约束

后续继续补强：

  • service 级规则归纳
  • mapper / repository / SQL 约束
  • 数据表与字段语义
  • 关键调用链路

推荐沿用同样的元数据：

  • app_version
  • primary_module
  • feature_scope
  • touchpoints

12.3 接入真实模型生产链

建议最终演进为：

flowchart LR
    A[候选层] --> B[外部模型蒸馏]
    B --> C[规范化]
    C --> D[质量校验]
    D --> E[统一索引]
    E --> F[最终知识库]

13. 最终结论

这个项目目前已经完成了从“散落的原始资产”到“可导入的合成知识库”的关键一步。

当前最重要的不是再改大方向，而是持续做两件事：

  1. 新版本按这套流程稳定增量入库
  2. 用真实模型逐步替换历史低质量 atoms

这份文档就是当前项目的统一思路、统一架构和统一手册。