FA 一键诊断 - 设计实现偏差问题说明（现状 vs 产品预期）
状态：评审中（v3，已按强哥裁定修正） ｜ 范围：维修工单「一键诊断」排障报告 ｜ 关联：FA 一键诊断 Dify 编排功能设计（v3.0）、FA 一键诊断 总体设计（v1.9）、知识库元数据标签体系设计、Metadata 过滤限制与 Role 方案 ｜ 问题定位：PRD 已于 2026-09-17 对齐生产「现状 + 待开发」（编排 v3.0 / 总体 v1.9）。本文档保留尚未闭环的差异——知识库 Metadata 过滤（待开发）、打标输入面（待补设备实时 IOT）；置信度分支经决策暂不整改（PRD 记录为预留）；「多维数据注入、安全提示、辅助标记」经评审确认已实现或移出范围
0. 问题清单总览
等级说明：P0（阻断/必须本期解决）＞ P1（本期应解决）＞ P2（后续版本/需求点）。已实现 / 已决策移除 / 等价替代项不列入问题清单，仅在 §6 记录决策。
| # | 问题 | 等级 | 定性 | 处理建议 |
|---|---|---|---|---|
| 1 | 知识库 Metadata 过滤未启用（category+tag 精准检索失效） | P0 | 设计实现偏离，检索精度存疑 | 待整改：开发已确认会加；PRD v3.0 §2.5 已标注「待开发」（见 §5） |
| 2 | 打标 LLM 输入面未达目标态（缺设备实时 IOT 信号） | P1 | 输入面待补齐 | 开发侧待补：PRD v3.0 §2.3 已标注「[待开发] 注入设备实时 IOT」（见 §5） |
多维数据注入（5 维交叉）已完全实现、无缺口：后端
/asset-context返回全量 JSON，由诊断 LLM 直接消费做交叉分析（详见 §3.4）。摘要/交叉分析是 AI 侧职责，工程化后端只负责供数据，不承担摘要能力。置信度降级分支（原第 2 条）经决策暂不整改——PRD v3.0 §2.4 已记录为「未实现 · 预留」，后续按需拓展，详见 §3.2 / §6。
1. 问题一句话
FA 一键诊断 Dify 生产编排相对设计文档，在「知识库精准检索（Metadata Filter）」与「打标 LLM 输入面（缺设备实时 IOT）」两个能力点上存在缺失/待补齐——前者影响排障建议的证据精度，后者影响打标准确性；置信度降级分支经决策暂不整改（PRD 记录为预留）；其余差异（多维注入、安全提示、辅助标记）经评审确认已实现或移出范围。
2. 产品预期（PRD 汇总）
按设计文档的原始定义：
- 二级标签 + Metadata 精准检索：知识库采用 L1 诊断语义层二维标签
category（一级过滤维度，默认 7 类）+tag（二级过滤维度，~40 项），值与工单打标输出直接对齐，检索时对文档做 metadata 过滤（标签体系 §1.2）。 - 置信度降级检索：N2 打标输出
confidence（0~1）→ N3 分支：≥0.5走 N4a 精确检索（category+tag双条件，Top-5，阈值 0.3）；<0.5走 N4b 宽检索（仅category单条件 +doc_nature not_in [保修卡,合格证]，Top-3，阈值 0.2），并输出is_low_confidence（编排设计 §2.4/§2.5）。注：该分子当前未实现，PRD v3.0 §2.4 已改记为「未实现 · 预留」，经决策暂不整改（见 §3.2 / §6）。 - 多维数据交叉注入（核心壁垒）：注入 2 类来源 × 5 个维度——IOT ①运行记录+②告警，Asset ③历史报修+④历史巡检+⑤保养/零配件更换（总体设计 §5.1）。
- SSE 流式输出：N7 流式生成 +
workflow_finished全量结构化结果（编排设计 §2.8）。 - 打标输入面：N2 打标在「分类树 + 故障描述」之外，注入 资产摘要（资产档案 + 关联设备）+ 近 N 天告警，并规划追加 设备实时 IOT 信号（编排设计 §2.3）。
3. 现状实现与偏差定性
3.1 知识库检索：Metadata Filter 未启用；打标前置但未用于过滤（P0）
时序确认：生产仍遵循「先打标 → 再检索 → 最后诊断」的主链路——打标 LLM（故障打标）先输出 systemName/componentName/faultSymptom/confidence，再进入「知识检索」。问题不在打标时序，而在打标结果未接入 metadata 过滤：
- 「知识检索」节点
metadata_filtering_mode: disabled，且retrieval_mode: multiple（混合检索）+ rerank（bge-reranker-v2-m3cd）+top_k: 5+score_threshold: 0.3； - 打标输出的
systemName/componentName未被映射为category/tag过滤条件，仅拼进检索query文本（问题现象: {fault_symptom}+打标理由: {reasoning}）与problem_classification_path。
由此：分类结果等于"未参与检索约束"——知识库检索退化为纯向量检索（+rerank），PRD 的"一级/二级过滤维度"与"宽检索剔除保修卡/合格证"均未落地。
案例取证（暖通空调 / 空调机组 / 制冷不足）：本次真实调用中 RAG 命中 [C:1] 空调机组风量不足 / [C:2] 空调机组不制冷常见原因 / [C:3] 冷水阀开度偏低，文档内容均围绕"空调机组"，未观察到明显跨类别噪声。说明纯向量检索在该样本上尚可，但无类别硬约束——当知识库混有"电气/给排水"等多类别且组件语义相近时，TOP5 存在被语义相似但类别不符文档挤占的风险（此样本未能证明，需构造跨类别样本验证）。这正是强哥判断：需恢复"先分类→metadata 精准检索"，以确定性约束兜底，1 秒换取 RAG 精准，值得。
3.2 置信度分支：N3 精确/宽检索合并为一路（已决策：暂不整改）
生产打标 LLM 之后没有 N3 置信度判定节点，所有工单（无论 confidence 高低）统一进入同一「知识检索」节点（Top-5，阈值 0.3）。PRD 的 N4a/N4b 双路（精确 Top-5 / 宽 Top-3 低阈值 + doc_nature 排除）未落地，低置信"纯向量检索并排除非诊断文档"的降级策略一并抹平。is_low_confidence 亦未输出（等价替代见 §6）。
决策（2026-09-17）：暂不整改。维持单路检索；PRD v3.0 §2.4 已把该分支改记为「未实现 · 预留」，后续若低置信工单的检索质量需要单独兜底，再启用 N3 if-else 分路。
3.3 打标输入面：缺设备实时 IOT（P1，待开发补齐）
现状：故障打标 LLM 已注入 分类树（category_tree_text）+ 资产摘要（asset_summary：资产档案名称/编码/类型/位置 + 关联设备 + 数据缺口 + 近 N 天告警 ≤5 条）+ 故障描述——即打标并非"只看工单描述"。
缺口：设备实时 IOT 信号（iotLiveSignals，物模型属性实时值）未进入打标上下文——它目前只随全量 asset_context_json 进入 诊断报告 LLM。打标因此无法在设备工况可见的前提下分类。
判定：待开发补齐（PRD v3.0 §2.3 已标注「[待开发] 注入设备实时 IOT」）。
3.4 多维数据注入：已完全实现（全量透传），无缺口
修正上一版误判：生产将 PRD 的 N5（device_id 解析）+ N6（N5a IOT + N5b Asset 历史）下沉合并为一个 Hub 聚合接口 POST /internal/fa-diagnosis/asset-context，Dify 通过 asset_context_json 把后端全量返回透传给诊断 LLM。
实测确认（来自诊断 LLM 实际 input）：asset_context_json 完整包含 —— assetProfile、inspectionHistory（巡检）、maintenanceHistory（保养）、repairHistory（报修）、sparePartReplacements（零配件）、inventoryCheckHistory（盘点）、iotLiveSignals（IOT 实时信号）、deviceAlarmHistory（告警）、contextMeta（lookbackDaysByType/dataGaps）。5 维交叉数据均已进入 LLM 上下文，符合总体设计 §5.1。
判定：已完全实现、无缺口。 工程化后端（Hub）只负责按 assetItemId + lookbackDays + maxRecords 供全量数据，不做摘要——摘要与交叉分析本就是 AI 侧（诊断 LLM）的职责，全量 JSON 透传即可，无需 Dify 层再造摘要节点。
3.5 输出形态：SSE 流式 → 单次 diagnosis_json（P2）
PRD 为 SSE 流式（text_chunk 逐字渲染 + workflow_finished 全量）；生产为单 LLM 节点 + 代码节点组装，End 仅输出一个 diagnosis_json。前端改为一次取出 JSON 渲染 Markdown。meta 信息量高于 PRD（含 contextMode / errors / tagReasoning / lookbackDaysByType 等），但无 has_iot_data / has_asset_history 布尔（可由 contextMode 推断）。属前端渲染方式差异，不阻断。
3.6 生产新增增强项（非偏差，建议认可）
| 增强项 | 说明 |
|---|---|
| 百度 Web 搜索补充 | qianfan/baidu_ai_search 插件，RAG 后追加 Web 引用（[C:N] 续编 id），FA_WEB_SEARCH_ENABLED 开关控制（默认 true）。PRD 未规划 |
| 引用真实性校验 | 组装诊断结果 _strip_invalid_citations + _filter_cited：移除正文中未在真实检索结果内的 [C:ID]，且只保留正文引用到的条目，防 LLM 幻觉引用（证据链溯源）。PRD v3.0 §2.9 已改为「正文引用才算证据」 |
| 精细化报告 Prompt | 含结构化章节（故障概述/工况与指标/告警/可能原因/排查步骤/安全提示/需现场核实）+ 归因铁律 5 条 + 禁则，质量高于 PRD 草案；已反向回填 PRD v3.0 §2.8 |
| rerank 二次精排 | bge-reranker-v2-m3cd，PRD 未规划 |
| 工单结构解耦 | 入参仅 repair_work_order_id + user_token，由 Hub 后端拉取工单实体，Dify 不暴露非结构化字段。属合理演进 |
3.7 其他差异（待确认/简化）
- 模型：PRD 用 DeepSeek-V3 / Qwen-Max；生产统一
Qwen/qwen3-14B-awq（打标 temp 0.2、报告 temp 0.3）。 - 回溯窗口（已实现，运营期调优）：生产为每类数据源独立配置回溯天数（非统一）——
LOOKBACK_DAYS_INSPECTION=30 / MAINTENANCE=30 / REPAIR=90 / SPARE_PART=30 / INVENTORY_CHECK=30 / ALARM=30，参数已暴露、可按类型分别调整。天数具体取值（如保养周期长短）属运营期调优，不构成本期缺陷。注意项：组装资产上下文请求代码节点_days()有 365 天硬封顶（min(365, …)），若未来需超过 365 天的长周期（如保养 2 年）需放开封顶。 - 分类候选注入：生产打标依赖后端
/internal/fa-diagnosis/category-tree提供的分类树文本（category_tree_text），约束"systemName/componentName 与分类树原文一致"，与 PRD{% for %}动态渲染思路一致，候选来源不同。 - 异常处理：PRD 有显式异常矩阵（N1 标签回退、LLM 打标重试）；生产在代码节点内嵌 try/except 收集
hub_error/check_error/kb_error至meta.errors，无"标签回退默认列表"与"打标重试"，依赖 Dify 重试配置。
4. 测试用例（实测清单）
4.1 知识库 Metadata 过滤有效性（P0，先实测后定）
| ID | 输入 | 设计预期 | 现状预期 | 判定 | 验证方式 |
|---|---|---|---|---|---|
| T-KB-01 | 暖通「空调机组制冷不足」工单 | metadata:category=暖通,tag=空调 精确命中暖通文档 | 向量检索 top5；本样本命中 [C:1][C:2][C:3] 均围绕空调机组（未见跨类别） | 基线观察 | 构造跨类别语义相近样本验证是否上榜 |
| T-KB-02 | 低置信工单（描述模糊） | 走宽检索，仅 category 过滤 + 排除保修卡 | 与高置信同路，无 doc_nature 排除 | 功能缺失 | 观察是否命中"保修卡/合格证"类文档 |
| T-KB-03 | 闸机「无法升降」工单 | category=弱电智能化, tag=闸机 过滤 | 向量检索，可能命中其他弱电设备（道闸/门禁） | 设计差异 | 核对引用文档 tag 是否全为闸机 |
4.2 置信度降级分支（已决策：暂不整改，本期不测）
| ID | 输入 | 设计预期 | 现状预期 | 判定 |
|---|---|---|---|---|
| T-CONF-01 | 高置信工单（≥0.5） | N4a 精确检索 Top-5 | 同单一路检索 Top-5 | 基线一致 |
| T-CONF-02 | 低置信工单（<0.5） | N4b 宽检索 Top-3 + doc_nature 排除 | 同单一路检索，无区分 | 功能缺失 |
4.3 多维数据交叉注入（已实现，验证通过）
| ID | 输入 | 设计预期 | 现状预期 | 判定 |
|---|---|---|---|---|
| T-MULTI-01 | 冷却阀执行器间歇故障 | 交叉「15 月前更换零件 + 3 月前保养正常 + 当前阀位 18.5%」浮出根因 | 后端 /asset-context 已返回 full 5 维 + IOT + 告警（实测含 inspection/maintenance/repair/sparePart/inventory/iotLiveSignals/deviceAlarmHistory），全量透传 LLM | 已通过 |
5. 整改方向（供评审）
- 启用 Metadata 过滤（P0，核心，待开发）：恢复「知识检索」metadata 过滤——打标后将
systemName/componentName解析为category/tag接入检索条件：高置信走category+tag双条件，低置信走category单条件 +doc_nature not_in [保修卡,合格证]。若 Dify UI 层 metadata 过滤不可用，参考 Metadata 方案 §4.3 用「Build Filter Node(Python) + Dataset Retrieve(HTTP)」落地。开发侧已确认会实现，PRD v3.0 §2.5 已标注「待开发」。 - 打标输入面补齐设备实时 IOT（P1，待开发）：当前打标已注入 分类树 + 资产摘要（资产档案 + 关联设备）+ 近 N 天告警 + 故障描述；按 PRD v3.0 §2.3 追加 设备实时 IOT 信号（物模型属性实时值），使打标在设备工况可见的前提下完成分类。
- 置信度分支（暂不整改）：维持单路检索；PRD v3.0 §2.4 已记录为「未实现 · 预留」，后续若低置信工单检索质量需单独兜底，再启用 N3 if-else 分路精确/宽检索。
6. 已决策 / 不纳入项（评审确认后冻结）
| 项 | 决策 | 依据 |
|---|---|---|
工单入参简化 repair_work_order_id + user_token | 认可，保持现状 | 由 Hub 后端拉取工单实体，解耦非结构化字段 |
| 百度 Web 搜索 + rerank + 引用真实性校验 | 认可，保持现状 | 相对 PRD 的新增增强项，提升证据质量；PRD v3.0 §2.9 已把引用口径改为「正文引用才算证据」 |
| 精细化报告 Prompt（告警/需现场核实章节 + 归因铁律） | 认可，保持现状，已反向回填 PRD | 生产质量高于 PRD 草案；PRD v3.0 §2.8 已回填 |
| 置信度降级分支（N3 精确/宽检索） | 已决策：暂不整改 | 维持单路检索；PRD v3.0 §2.4 已记录为「未实现 · 预留」，后续按需拓展 |
| 多维数据注入（全量透传 JSON） | 认可，保持现状 | 后端已返回 5 维 + IOT + 告警；摘要/交叉分析为 AI 侧职责，工程化后端只供数据，无需摘要节点 |
is_low_confidence / citation_hint | 等价替代 | 生产已有 tagConfidence / kb_hit_count 覆盖 |
| 历史回溯窗口 | 认可，保持现状 | 已按类型独立配置（LOOKBACK_DAYS_*）、参数可分别调整；天数取值运营期调优。注意 _days() 有 365 天硬封顶，未来超长周期需放开 |
7. 例外说明
- 本问题不影响正向主链路闭环：
kb_only/asset/device_signals_only三条降级路径均可产出diagnosis_json。 - 引用真实性校验（
_strip_invalid_citations+_filter_cited）已落地，避免幻觉引用；仅需恢复 Metadata 过滤以保检索精度，并把设备实时 IOT 补入打标输入。 - 多轮/批处理不适用：FA 一键诊断以
repair_work_order_id单次拉起，无对话多轮；user_token（Hub JWT）透传保证鉴权链路完整。
说明：本文档基于
dify/20260917export/FA一键诊断.yml（生产）与 FA 一键诊断 PRD 逐项比对（PRD 已于 2026-09-17 更新至「现状 + 待开发」，编排 v3.0 / 总体 v1.9）。评审裁定：多维注入改判为"已实现"、安全提示改判为"已决策移除"、辅助标记改判为"等价替代"、置信度分支改判为"暂不整改（预留）"。逻辑推断涉及后端/asset-context返回结构之处，均以实测 LLM input 佐证。