鲲鹏 / RAG_ · Files

Go to a project
产品研发RAG_模块定义与协同交付说明_v1.md 13.1 KB 
title: 产品研发 RAG：模块定义与协同交付说明（v1）
status: draft
owner: xwk
updated_at: 2026-03-12

本文是 docs/rag/产品研发RAG_规则-用例对齐与入库方案_v1.md 的“协同落地补充件”，用于：

  • 统一模块字典与仲裁规则（让模块作为检索/路由元数据稳定可控）
  • 明确你 vs 黑豆的交付接口（按 app_version 维度可追踪）
  • 给黑豆侧用例蒸馏的 Prompt 模板（从 XML 产出 case_atoms.jsonl）

1. 模块定义（真人标准）

1.1 模块字典（枚举）

当前建议枚举（后续可扩展，但不要轻易改动既有值）：

  • INCOME：收入、提现、银行卡、签约
  • AUTH：认证、备案、完善认证资料
  • INQUIRY：图文/电话/视频问诊、随访
  • CLINIC：门诊/排班/坐诊/加号/预约/挂号等
  • PATIENT：就诊人/患者档案相关、患者列表/分组/拉黑、聊天/提问、添加患者等

模块的作用：不是合并主键，而是用于 检索过滤、路由、预评审输出、责任边界。

1.2 模块边界三件套（建议长期固化）

每个模块建议配 3 类“稳定锚点”，便于 AI 自动标注且可解释：

  • 触点锚点（touchpoints）：页面/入口/端（医生端/患者端/运营端）
  • 业务实体锚点（entities）：提现、银行卡、就诊人、咨询单、排班…
  • 强规则信号（signals）：toast/弹窗/禁用/默认选中/校验提示/错误码文案…

1.3 跨模块仲裁：如何定 primary_module

当同一条规则同时命中多个模块时，按顺序仲裁： 1) 规则最终生效处/校验处 属于哪个模块（更接近“责任边界”） 2) 用户主要操作入口 属于哪个模块（更接近“用户提问落点”） 3) 若仍不确定：选择“更利于检索”的模块为主，同时保留 modules[] 全量

1.4 允许跨模块：modules[] 必须保留

为解决你担心的“你和黑豆分类标准不一致”，落库时建议：

  • 必须有：modules[]（多选，聚合后的全量相关模块）
  • 可选：primary_module（单选，服务于责任边界/路由）

1.5 给 AI 的“模块字典块”（必须写进提示词/系统提示）

这段内容的目的：让模型标注模块时有明确、稳定、可复用的规则，而不是靠常识猜。

你可以把下面整段直接粘到任何一个 LLM 节点/Prompt 的开头（Figma 抽取、XML 蒸馏、合并聚合阶段都可复用）。

模块字典（枚举值必须从以下列表中选择）：
- INCOME：收入、提现、银行卡、签约
- AUTH：认证、备案、完善认证资料
- INQUIRY：图文/电话/视频问诊、随访
- CLINIC：门诊/排班/坐诊/加号/预约/挂号等
- PATIENT：就诊人/患者档案相关、患者列表/分组/拉黑、聊天/提问、添加患者等

模块标注输出字段要求（可选但强烈建议）：
- primary_module: string（可空）
- modules: string[]（可空，但建议至少 1 个）
- module_confidence: 0~1
- module_reason: 用 1~2 句说明为什么这么标（触点/实体/强规则信号）

仲裁规则（确定 primary_module）：
1) 规则最终生效处/校验处 属于哪个模块
2) 用户主要操作入口 属于哪个模块
3) 若仍不确定：选更利于检索的模块为主，同时 modules 保留全量

允许跨模块：同一条规则可以同时属于多个模块（modules 多选）。
注意：模块不是合并主键；合并仍以 app_version + merge_fingerprint 为主。

2. 协同交付接口（按 app_version）

2.1 版本同步记录（必须有）

每个 app_version 一份同步记录文件（建议放仓库，便于自动化）：

  • 模板：docs/rag/version_sync_template.yaml
  • 核心目标：让“该版本 Figma 是否齐、用例是否齐、是否已合并、是否已入库”一眼可追踪。

2.2 黑豆交付物（只做测试用例整理与蒸馏导出）

每个 app_version 建议交付：

  • 必交
    • tests/<app_version>/*.testsuite-deep.xml：原始导出 XML（不要求修改 XML 内容）
  • 强烈推荐
    • tests/<app_version>/case_atoms.jsonl：从 XML 蒸馏得到的“用例原子”

2.2.1 case_atoms.jsonl 字段要求（最小可执行）

每行 1 个 JSON 对象（JSONL），必填字段：

  • app_version：外部补齐（来自版本同步表，不从 XML 推断）
  • suite_name
  • external_id（如果有）
  • internal_id（如果有）
  • case_revision_version（来自 XML <version>，注意不是 app_version）
  • C / A / R
  • canon_text：固定格式 C=<...>|A=<...>|R=<...>
  • merge_fingerprint：sha1(canon_text) 取前 12 位
  • evidence：建议包含 xml_file + xpath_or_path + raw_text（用于审计回溯）

可选字段（但很有价值）：

  • module_hint：黑豆基于测试集目录给的模块候选（不做强约束）
  • touchpoints[]：若能从用例标题/前置中识别到端与页面，可先给候选

2.3 你交付物（Figma/合并/入库/报表/词表）

每个 app_version 建议交付：

  • figma/<app_version>/links.txt：该版本所有需求 Figma 链接
  • build/<app_version>/rule_atoms.jsonl：Figma 规则原子（含 Figma evidence）
  • build/<app_version>/case_atoms.jsonl：黑豆交付（或你代跑得到）
  • build/<app_version>/rule_clusters.jsonl：合并后的规则簇
  • build/<app_version>/rule_view.md：规则视图入库文档（给 Dify）
  • build/<app_version>/case_view.md：用例视图入库文档（给 Dify）
  • build/<app_version>/merge_report.csv：命中/未命中报表（便于协作迭代）
  • docs/rag/synonyms.yaml（或同等位置）：同义词/占位符表（你主导迭代）

2.3.1 你侧批量交付口径（15 个 Figma 链接 → 1 个版本归一 rule_atoms.jsonl）

以 v4.57.3 为例，你可能收集到 15 个需求/页面的 Figma 链接。交付时不需要 15 份规则文件，而是：

  • 保留 1 份链接清单：figma/v4.57.3/links.txt（15 行即可）
  • 额外生成 1 个版本归一文件：build/v4.57.3/rule_atoms.jsonl

推荐跑法：

  • 跑法 A（推荐）：逐个链接/节点解析 → 产出规则原子 JSONL → 汇总拼接为 1 个 rule_atoms.jsonl
    • 每行都写入 app_version=v4.57.3
    • evidence.figma_url（或 file_key + node_id）必须保留，便于追溯
    • 如需去重：以 canon_text 作为去重键（同版本内去重即可）

2.3.2 rule_atoms.jsonl 字段要求（最小可执行）

每行 1 个 JSON 对象（JSONL），必填字段：

  • app_version
  • C / A / R
  • canon_text：固定格式 C=<...>|A=<...>|R=<...>
  • merge_fingerprint：sha1(canon_text) 取前 12 位
  • modules[]：可先为空数组，但建议给出候选（用于检索/路由/预评审）
  • evidence：至少包含 figma_url（或 file_key/node_id）+ raw_text（用于审计回溯）

可选字段（建议尽量有）：

  • primary_module
  • touchpoints[]
  • feature_scope
  • ui_states[]（例如：按钮禁用/默认选中/错误态/空态等）

2.3.3 你侧过滤规则（Figma 文本去噪）

以下内容不要进入 C/A/R，也尽量不要进入 evidence.raw_text：

  • base64、data:image、长随机串（截图/附件/编码内容）
  • 纯占位符/无业务语义文本（如“按钮/标题/请输入/示例”且无规则信号）
  • 重复出现的装饰性文案（同一页面多处重复、无差异）

保留优先级（强规则信号）：

  • toast/弹窗文案
  • 校验/错误提示
  • 按钮可用/禁用、默认选中、缺省值
  • 条件触发提示（“未选择xx点击提交 -> 提示xx”）

3. 黑豆侧 Prompt 建议（从 XML 生成 case_atoms.jsonl）

目标：让用例蒸馏“稳定可对齐”。核心不是写得漂亮，而是：

  • C/A/R 可复用、可归一化
  • 能产出稳定的 canon_text 与 merge_fingerprint
  • 能回溯到 XML 原文（evidence）

3.0 批量交付口径（10 个 XML → 1 个版本归一 JSONL）

以 v4.57.3 为例，黑豆可能会导出 10 个 .testsuite-deep.xml。交付时不需要 10 份 JSONL，而是：

  • 保留 10 个原始 XML（用于审计与复跑）
  • 额外生成 1 个版本归一文件：tests/v4.57.3/case_atoms.jsonl

推荐跑法（两种都可以）：

  • 跑法 A（更稳，推荐）：逐个 XML 跑 Prompt → 得到 10 段 JSONL → 直接拼接为 1 个 case_atoms.jsonl
    • 每行都写入 app_version=v4.57.3
    • evidence.xml_file 写真实来源文件路径，便于追溯
    • 如需去重：以 canon_text（或 external_id + canon_text）作为去重键
  • 跑法 B（一次喂多文件）：把 10 个 XML 一次性作为输入让模型输出 1 份 JSONL
    • 仅在“模型上下文足够大”的情况下可用；否则容易截断/漏用例

3.1 Prompt 模板（直接可用）

把下面整段给到 LLM（或 Dify 工作流/脚本内的 LLM 节点），输入是一份 XML 文本（或解析后的结构化 JSON）。

你是资深测试分析师。请将给定的 testsuite XML 解析为 case_atoms.jsonl（JSON Lines）。

目标：将每个 testcase 拆解为 1~N 个“用例原子 case_atom”，每个 atom 只表达一个核心动作(A)与期望(R)，并保留必要前置(C)。

强约束（必须遵守）：
1) 输出格式：JSONL，每行一个 JSON 对象，不要输出数组，不要输出多余解释。
2) 每个 JSON 对象必须包含字段：
   - app_version: 使用外部传入的版本号（不要从 XML 推断）
   - suite_name
   - external_id（若 XML 有则填，否则置空字符串）
   - internal_id（若 XML 有则填，否则置空字符串）
   - case_revision_version（来自 XML 的 <version>，若无置空）
   - C, A, R（字符串；允许 C 为空，但 A/R 至少一个非空）
   - canon_text: "C=<C>|A=<A>|R=<R>"
   - merge_fingerprint: sha1(canon_text) 前12位（小写 hex）
   - evidence: { xml_file, xpath_or_path, raw_text } 其中 raw_text 为你用于抽取本 atom 的原始片段（尽量短，能定位）
3) （可选）模块提示字段：
   - module_hint: 从模块字典中选择 0~1 个最可能的模块；如果无法判断，输出空字符串
   - 注意：module_hint 仅用于检索/路由辅助，不作为合并主键
4) 拆分规则：
   - 若一个 testcase 含多个步骤与多条期望，请按“一个 A 对应一个 R”为单位拆多个 atom。
   - 避免把多个 toast/弹窗期望合并在同一个 atom。
5) 归一化规则（写入 C/A/R 前先处理）：
   - 金额归一为 <MONEY>，数字归一为 <NUM>，日期时间归一为 <DATETIME>，卡号/订单号归一为 <ID>
   - 同义词归一：弹窗提示/提示语/Toast -> toast提示；不可点击/置灰 -> 禁用
6) 过滤规则（必须做，尤其是截图 base64）：
   - 任何 base64、data:image、看起来像长随机串的内容都不要进入 C/A/R，也不要放进 evidence.raw_text
   - 如果 expectedresults 里只有截图/图片（无文字期望），则该步骤不要产 atom（或 atom 的 R 置空，但必须标记 evidence.raw_text="only_image_ignored"）
   - raw_text 要尽量短：优先保留能定位的 1~2 句提示文案；超过 200 字请截断
7) 质量要求：
   - A 以“动作动词+对象”开头（点击/输入/选择/提交/发送等）
   - R 明确可观察结果（toast提示xx/弹窗显示xx/按钮禁用/页面跳转/列表刷新等）

输入：
- app_version = {APP_VERSION}
- xml_file = {XML_FILE_PATH}
- testsuite_xml = {XML_TEXT}

现在开始输出 JSONL。

实操建议：如果模型对 “sha1(canon_text)” 计算不稳定，可以改成先输出 canon_text，merge_fingerprint 由脚本统一后处理计算（更可靠，也便于你们对齐算法版本）。

3.2 例子（便于黑豆对齐输出风格）

下面只是示例结构，不要求与业务完全一致。

{"app_version":"v4.57.3","suite_name":"患者加号","external_id":"24256","internal_id":"","case_revision_version":"1","C":"患者加号弹窗已选择日期且未选择坐诊时间段","A":"点击发送给患者","R":"toast提示请选择坐诊时间段","canon_text":"C=患者加号弹窗已选择日期且未选择坐诊时间段|A=点击发送给患者|R=toast提示请选择坐诊时间段","merge_fingerprint":"<sha1前12位>","evidence":{"xml_file":"/path/患者加号.testsuite-deep.xml","xpath_or_path":"testsuite/testcase[externalid='24256']/expectedresults","raw_text":"请选择坐诊时间段"}}

3.3 黑豆侧自检清单（交付前 2 分钟检查）

  • XML 可解析、suite_name 可取到
  • case_atoms.jsonl 每行都是合法 JSON
  • 100% 的 atom 都有 canon_text 与 merge_fingerprint
  • 大多数 atom 的 R 都包含“强规则信号”（toast/弹窗/禁用/默认值/校验提示）
  • evidence 能定位回 XML（最少 xml_file + 一段 raw_text）

4. 你侧验收（收到黑豆交付后怎么验）

  • 结构验收：字段齐全、fingerprint 生成规则一致、JSONL 可读
  • 命中率验收：跑一次合并得到 merge_report.csv
    • 未命中优先看：是否没拆 atom / canon_text 不稳定 / 缺少 R 或 R 太泛
  • 迭代入口：把“未命中 Top 原因”沉淀进 synonyms.yaml 与占位符策略