鲲鹏 / RAG_ · Files

title: 产品研发 RAG：规则-用例对齐与入库方案（v1）
status: draft
owner: xwk
updated_at: 2026-03-12

0. 最终目标（来自“实施方案最终版”）

0.1 项目愿景

构建产品研发的 “数字大脑”，实现两类核心能力：

• 飞书即时业务问答
  例：医生提现失败的原因有哪些？
  AI 可回答（示例）：未完成签约 / 账户余额不足 / 提现金额超过限制

• 需求 AI 预评审
  例：产品提需求：新增提现手续费
  AI 自动提示（示例）：影响模块 INCOME；涉及规则（提现金额校验 / 提现流程规则）

0.2 核心理念（知识来源于真实资产）

• 测试用例 → 业务规则
• Figma 设计稿 → 交互规则
• 代码 → 技术参数

AI 负责把这些资产 自动整理为产品知识规则，最终形成：

• 模块规则文档（例如 income_rules.md）→ 进入 RAG 知识库（Dify）

0.3 终态架构（数字大脑数据流）

graph TD; A["测试用例"] --> B["AI 规则蒸馏（业务规则）"]; C["Figma 设计稿"] --> D["Figma 解析（插件/API）"]; D --> E["AI 提取交互规则"]; J["代码/接口"] --> K["AI 提取技术参数"]; B --> F["规则合并/对齐"]; E --> F; K --> F; F --> G["模块规则文档 income_rules.md"]; G --> H["Dify 知识库"]; H --> I["飞书 AI 助手（业务问答/需求预评审）"]; note1["系统核心：自动知识生产"] --> F;

0.4 当前试点范围（第一阶段）

• 只做模块：INCOME（可扩展到 AUTH / INQUIRY / CLINIC / PATIENT）
• 输入资产：测试用例（已蒸馏/或可蒸馏）+ Figma 历史版本链接（+ 可选代码/接口）
• 输出：income_rules.md
• 目标：让 AI 可以回答 INCOME 业务问题，并支撑 INCOME 需求预评审

---

1. 背景与目标

1.1 背景

• Figma 视觉稿能提供强规则信号（弹窗/Toast/校验/按钮文案/流程说明），但天然“碎片化”
• 测试用例 XML能提供“可验证”的步骤与期望，但与产品侧的模块分类可能不一致，且缺少 Figma node_id

1.2 目标

• 按 app 版本维度将 Figma 规则与测试用例对齐，形成可入库的“规则簇（Rule Cluster）”
• 支持两种检索视图（你明确需要 C：两者都要）：
  • 规则视图：每条规则挂载证据（Figma 原文）+ 覆盖用例（XML）
  • 用例视图：每条用例挂载对应规则 + 设计证据
• 解决协同问题：黑豆只负责测试用例整理/蒸馏导出，你负责其他所有内容；通过“版本同步表”实现可追踪、可回溯的交付与合并。

1.3 核心原则（关键）

1) 合并不以模块为主键（PATIENT/INQUIRY/CLINIC…都可能不一致） 2) 合并主键 = app_version + 内容指纹（merge_fingerprint） 3) Figma node_id只做证据追溯与规则侧去重，不参与跨源主对齐

---

2. 总体架构（含设计图）

2.1 端到端架构图（数据流）

graph LR; Figma["Figma 节点/页面（fileKey,nodeId）"] --> FigmaFetch["拉取 Figma 结构树"] --> AtomizeFigma["规则原子化（rule_atoms）"]; XML["TestSuite XML（概述/前置/步骤/期望/字段）"] --> XmlParse["解析 XML 用例结构"] --> AtomizeCase["用例原子化（case_atoms）"]; Code["（可选）代码/接口/日志"] --> Cluster["规则簇（rule_clusters）"]; AtomizeFigma --> Norm["文本归一化（占位符/同义词/去噪）"] --> Fingerprint["merge_fingerprint = sha1(canon_text) 前12位"] --> Strong["强合并（app_version + fingerprint）"] --> Cluster; AtomizeCase --> Norm --> Fingerprint --> Strong; Norm --> Embed["（可选）Embedding"] --> Weak["弱合并（语义相似 + 约束）"] --> Cluster; Cluster --> MD1["规则视图 Markdown"] --> KB["Dify Knowledge Base"]; Cluster --> MD2["用例视图 Markdown"] --> KB; Cluster --> Audit["审计/对齐报表"];

2.2 数据模型（ER 简图）

graph TD; RC["RULE_CLUSTER"] --> RA["RULE_ATOM"]; RC --> CA["CASE_ATOM"]; RA --> FE["FIGMA_EVIDENCE"]; CA --> CE["CASE_EVIDENCE"];

注：飞书对 Mermaid 的 erDiagram 支持不稳定，因此这里用「关系简图 + 字段表」替代 ER 图。

实体	关键字段（示例）
RULE_CLUSTER	cluster_id, app_version, merge_fingerprint, canon_text, modules[], feature_scope, touchpoints[], confidence, created_at
RULE_ATOM	atom_id, app_version, canon_text, merge_fingerprint, C, A, R, primary_module, secondary_modules[]
CASE_ATOM	atom_id, app_version, canon_text, merge_fingerprint, C, A, R, suite_name, external_id, internal_id, case_revision_version
FIGMA_EVIDENCE	file_key, node_id, figma_url, raw_text
CASE_EVIDENCE	xml_file, xpath_or_path, raw_text

---

3. 关键算法：原子化、归一化、内容指纹

3.1 原子化（Atomization）

3.1.1 Figma → rule_atoms

• 输入：fileKey + node-id 获取结构树（文本节点、控件层级）
• 输出：按“强规则信号”切分的 rule_atom：
  • Toast/弹窗文案
  • 校验提示
  • 按钮可用/不可用、默认选中
  • 条件触发提示（例如“未选择时间段点击发送”）

3.1.2 XML → case_atoms（黑豆负责的输出之一）

• 输入：测试用例 XML（概述/前置/步骤/期望）
• 输出：将一条用例拆成若干 case_atom（一条 atom 只表达一个核心 A+R）
  • C：来自 preconditions + steps 中的前置描述（可为空）
  • A：关键操作（点击/输入/选择/提交/发送）
  • R：期望（Toast/页面变化/按钮状态）

说明：同一 test case 常覆盖多个规则，不拆就会对齐困难；拆分是命中率的关键。

3.2 canon_text（可对齐文本）

统一固定格式（两侧必须一致）：

C=<...>|A=<...>|R=<...>

3.3 文本归一化（Normalization）

3.3.1 去噪

• 删除无语义的时间戳、重复 UI 列表项、纯装饰文本
• 图片/截图 base64 不入 canon_text，仅作为 evidence 附件引用（可选）

3.3.2 占位符（强烈建议两侧统一）

• 金额 → <MONEY>
• 数字（次数/天数/序号）→ <NUM>
• 日期时间 → <DATETIME>
• 手机/身份证/卡号/订单号 → <ID>/<ORDER_ID>
• 姓名/机构/医生 → <NAME>

3.3.3 同义词归一（最小表，持续迭代）

• Toast/弹窗提示/提示语 → toast提示
• 禁用/置灰/不可点击 → 禁用
• 撤销/撤回 → 撤回
• 到账/入账 → 到账 -（问诊域词表：后续按你们业务补全）

3.4 merge_fingerprint（主对齐键）

merge_fingerprint = sha1(canon_text) 取前 12 位
merge_key = app_version + ":" + merge_fingerprint

3.4.1 强合并（主路径）

• 只要 merge_key 一致，即认为是同一条规则（跨模块也合）

3.4.2 弱合并（可选增强）

当 fingerprint 不一致但语义高度相似时：

• embedding 相似度 ≥ 阈值
• 且满足约束之一：同 app_version / 同触点 / 关键实体一致（提现/就诊人/加号/坐诊…）

---

4. Dify 工作流设计（可落地）

4.1 工作流划分

建议按“版本”为单位跑批：

• Workflow A：figma_nodes_to_rule_atoms
• Workflow B：xml_to_case_atoms（黑豆侧也可在本地/脚本完成，再交付 JSONL）
• Workflow C：merge_atoms_to_clusters_and_render_md

4.2 Workflow C（合并 + 双视图渲染）示意图

graph TB; Start["Start：app_version + rule_atoms + case_atoms"] --> Validate["校验：app_version 必填 + 字段完整性/去重"] --> Strong["强合并：merge_key"] --> Cluster["生成 rule_clusters（含 sources, coverage）"]; Validate --> Weak["弱合并：embedding + 约束（可选）"] --> Cluster; Cluster --> RenderRule["渲染：规则视图 MD"] --> End["End"]; Cluster --> RenderCase["渲染：用例视图 MD"] --> End; Cluster --> Report["输出：命中/未命中报表"] --> End;

---

5. 协同与交付（你 vs 黑豆）

5.1 分工边界

黑豆（仅测试用例整理与蒸馏导出）

交付物（每个 app_version 一份）：

• testsuite_raw.xml：原始导出 XML（不要求修改）
• case_atoms.jsonl：蒸馏后的用例原子（推荐，命中率更稳定）
  • 必填字段：external_id/internal_id/suite_name/C/A/R/canon_text/merge_fingerprint
  • case_revision_version：取 XML <version>（注意：不是 app_version）

你（其他所有：Figma、合并、入库、检索、报表、迭代词表）

交付物（每个 app_version 一份）：

• figma_links.txt：该版本所有需求 Figma 链接
• rule_atoms.jsonl：规则原子（含 evidence：fileKey/node-id/raw_text）
• rule_clusters.md：规则视图入库文档
• case_view.md：用例视图入库文档
• merge_report.csv/md：命中率与未命中原因（缺少文案/缺少期望/语义不一致）
• synonyms.yaml：同义词表（共同维护也可，但建议你主导）

5.2 是否需要“基于版本号的同步表”？结论：需要

原因：

• XML 不包含 app_version；必须用外部元数据补齐
• 需要可追踪每个版本的“Figma/用例”是否齐备、是否已合并、是否已入库

5.3 模块定义与标注治理（真人标准 + AI 标注 + 人工兜底）

目标：模块不再作为“合并主键”，但仍是 检索/路由/预评审输出/责任边界 的核心元数据，因此必须治理一致性。

5.3.1 谁来定义模块？

• 真人定义（强约束、长期稳定）
  • 模块字典（枚举）：INCOME / AUTH / INQUIRY / CLINIC / PATIENT ...
  • 模块边界与仲裁原则（见 5.3.4）
  • 模块 Owner（便于治理与验收）
• AI 只做“自动标注/候选推荐”，并输出置信度与理由；最终以人工修正为准

5.3.2 模块标注需要哪些字段（落库字段）

建议每条 atom/cluster 都带下面字段（用于过滤/排序/报表）：

• primary_module：主模块（可空，可人工改）
• modules[]：相关模块多选（合并后聚合；允许跨模块）
• module_confidence：0~1
• module_reason：命中依据（关键词/触点/页面/控件/用例标题等）
• feature_scope：功能域（例如：提现/签约/加号/就诊人/问诊状态流转）
• touchpoints[]：触点（例如：医生端-门诊信息页 / 患者端-预约详情 / 医生端-钱包提现）

说明：modules[] 是解决“分类标准不一致”的关键，能保证合并后跨模块检索不丢规则。

5.3.3 AI 如何自动标注模块（推荐策略）

AI 标注遵循“可解释、可回溯”的证据链策略：

• 触点优先：页面/入口归属（钱包提现页 → INCOME；认证流程页 → AUTH；问诊会话/咨询单 → INQUIRY；门诊预约/加号/坐诊 → CLINIC；患者档案/患者列表 → PATIENT）
• 业务实体补强：关键词与实体（提现/税源地/签约/银行卡/余额 → INCOME/AUTH；就诊人/档案 → PATIENT；主诉/咨询单/会话 → INQUIRY；加号/坐诊/预约/挂号费 → CLINIC）
• 动作与结果补强：如果触点不明确，用 A/R（动作/反馈）去判断（例如“提交提现/到账失败”强指向 INCOME）

5.3.4 冲突与仲裁（跨模块如何定主模块）

当一条规则同时命中多个模块时，按以下优先级仲裁 primary_module： 1) 规则最终生效处/校验处 属于哪个模块（例如提现金额校验在提现流程内 → INCOME） 2) 用户主要操作入口 属于哪个模块（例如从问诊页触发，但实际改变的是患者档案 → primary 可能是 PATIENT，modules 同时包含 INQUIRY） 3) 若仍不确定：选择“更有利于检索的模块”为主（通常是用户提问最可能落点的模块），并保留 modules[] 全量

5.3.5 置信度阈值与人工兜底（最小可执行）

• module_confidence >= 0.80：自动通过（默认不需要人工确认）
• 0.50 ~ 0.80：进入“待确认列表”（你批量确认；不要求逐条手改）
• < 0.50：必须人工确认（通常是触点缺失/证据不足/跨模块强耦合）

graph TB; X["AI 输出：modules + confidence + reason"] --> Y["confidence >= 0.8 ?"]; Y --> A["自动落库"]; Y --> Z["confidence >= 0.5 ?"]; Z --> B["待确认列表（你批量确认/抽检）"]; Z --> C["必须人工确认（补充触点/规则拆分/同义词表）"]; B --> A; C --> A;

5.3.6 协同建议（你 vs 黑豆）

• 黑豆交付侧：可以“可选”提供 module_hint（基于用例所在测试集/目录），但不作为强约束
• 你交付侧：你维护模块字典与仲裁规则；最终落库的 primary_module/modules[] 以你侧为准
• 版本同步表建议增加（可选字段）：
  • module_hints[]：该版本涉及的模块范围（便于预评审/验收）
  • module_review_status：pending | partial | done（模块标注是否已人工兜底）

---

6. 版本同步表（推荐模板）

建议每个版本一条记录，维护在仓库（或飞书表格也行，但建议落地成文件便于自动化）。

字段建议：

• app_version
• status：collecting | ready_to_merge | merged | ingested | done
• figma_links_file
• figma_file_keys（可选）
• test_suite_files[]
• case_atoms_file（可选，但强烈推荐）
• owners：{figma: 你, test: 黑豆, merge: 你}
• last_sync_at
• notes

模板文件见：docs/rag/version_sync_template.yaml

---

7. 质量与验收（必须写清楚的“协同接口”）

7.1 黑豆交付验收（你拿到后自动校验）

• XML 可解析（结构完整）
• external_id 存在（截图里你们已勾选导出 external id，则非常好）
• 若交付 case_atoms.jsonl：
  • 每条 atom 都有 canon_text 与 merge_fingerprint
  • A/R 至少一个包含“强规则信号”（toast/弹窗/禁用/默认选中…）

7.2 你侧验收（输出报表）

• 命中率：matched_clusters / total_case_atoms
• 未命中分类：
  • Figma 缺少文案/流程（只写了背景）
  • XML 缺少期望（只有截图 base64，无法抽取）
  • 语义不一致（需要同义词表/占位符增强）

---

8. 附：v4.57.3 的“真实命中”样例（证明方案可跑通）

在 t1NWQ5VaeWAY1Dnnd6Z7sF 的 node-id=397-922 中，Figma 文本包含：

• 发送给患者
• 请选择坐诊时间段
• 您当天坐诊时间已结束
• 您当天没有坐诊排班
• 患者加号发送成功

与 XML 用例（如 externalid=24256/24254/24255/24257）能够通过 merge_key = v4.57.3:<fingerprint12> 自动对齐合并。