wecom_it_smart_desk/docs/02-技术文档/实现配置/Dify_App改造与AI供给链路修复方案-v1.0.md

Dify App 改造与 AI 供给链路修复方案

版本: v1.0 日期: 2026-07-13 涵盖任务: P1-4（App精简）、P1-5（Prompt部署）、P1-6（知识库优化） 前置条件: P0 代码改造已完成（_call_dify_native() + DIFY_NATIVE_* 环境变量）

---

一、当前阻塞点（P0-3 验证结果）

1.1 Dify 应用状态

应用	API Key	状态	说明
智能IT支持-员工咨询	app-7jkRkAzvX4QM9v9SM3P8mMEO	❌ 400	"Workflow not published"（工作流未发布）
老线上应用	app-UaTWYdBSwN6VktKQlbh5YN5H	✅ 200	返回纯文本Markdown（非JSON），已标记禁用
分诊应用	app-z3S9AEUUAVPbtR2rioxpiIvp	✅ 200	返回结构化JSON，正常工作
自建应用	app-J3s8sHarZQ2SCaNF3xCppliL	❌ 400	"Model credentials not initialized"

1.2 根因分析

Dify 应用 app-7jkRkAzvX4QM9v9SM3P8mMEO 是一个 advanced-chat（聊天流） 类型的应用，包含 85 个节点。该应用的工作流 尚未发布，导致 API 调用返回 "Workflow not published" 错误。

影响：

• 后端 _call_dify_native() 调用 Dify 原生 API → 返回 400 → 降级到代理路径
• 代理路径（dify2openai）返回 [object Object] → JSON 解析失败 → 降级为纯文本
• 最终结果：所有 Phase 1-6 前端改造的结构化功能（卡片渲染、选项按钮、诊断阶段）均无法触发

1.3 修复路径

用户在 Dify 平台发布工作流
    ↓
Dify API 返回 200 + JSON answer
    ↓
后端 _call_dify_native() 解析 JSON
    ↓
双 WS 推送（ai_reply + dynamic_recommend）
    ↓
前端渲染结构化消息（文字气泡 + 卡片 + 选项按钮）

---

二、P1-4：Dify App 精简方案（85 → ~35 节点）

2.1 精简原则

1. 后端已接管的功能：审批意图分类、关键词预过滤、BYOD 拦截、图片增强 → Dify 中对应节点可删除
2. Prompt 已覆盖的功能：JSON 输出格式、诊断阶段标注、审批卡片推送规则 → Dify 中的格式化/路由节点可删除
3. 保留核心能力：RAGFlow 知识检索、LLM 推理、多轮对话上下文 → 这三块是 Dify 的核心价值
4. Vision 节点：后端 VisionService 已独立接入，但 Dify 内的图片理解节点暂保留（双路径冗余）

2.2 节点分类与精简计划

可删除节点（50个）

类别	节点类型	数量	删除原因
审批意图路由	if-else + answer	12	后端 _check_approval_intent() 已接管，关键词收窄至~25个
BYOD 拦截	if-else + code + assigner	8	后端 h5_ai_task.py 已实现 BYOD 拦截逻辑
格式化输出	code + template-transform	10	Prompt v1.1 已要求 LLM 直接输出 JSON，无需后处理
变量中转	assigner	12	精简后不再需要多步变量传递
打招呼/人工判断	if-else + answer	4	后端 h5_ai_task.py 已实现打招呼和人工坐席判断
保底机制	code + if-else + assigner	4	后端有 30s 超时降级 + 15s still_thinking 推送

保留节点（~35个）

类别	节点类型	数量	保留原因
核心	start + answer	3	工作流入口和最终输出
知识检索	knowledge-retrieval	3	RAGFlow 检索（IT知识库 + 审批流程库 + FAQ库）
LLM 推理	llm	4	主对话 LLM + 意图理解 + 上下文总结 + 图片描述
条件路由	if-else	5	图片/文本分流 + 知识库命中/未命中分流 + 上下文长度判断
变量管理	assigner	6	对话变量（servyou_query, memory_query, memory_ans, mmq）
代码处理	code	6	查询预处理 + 结果后处理 + 上下文拼接 + 图片URL提取
HTTP 请求	http-request	4	RAGFlow API 调用 + 图片理解 API + 外部知识源
模板转换	template-transform	2	上下文模板 + 答案模板
列表操作	list-operator	1	历史消息列表处理
其他	1	保底 answer 节点

2.3 精简后的工作流结构

[Start] 
  → [Code: 预处理用户输入]
  → [IF-ELSE: 图片消息?]
      ├─ Yes → [HTTP: 调用图片理解API] → [LLM: 图片描述生成]
      └─ No  → 直接继续
  → [Code: 拼接上下文(memory_query + memory_ans + servyou_query)]
  → [IF-ELSE: 上下文长度 > 阈值?]
      ├─ Yes → [LLM: 上下文压缩总结]
      └─ No  → 直接继续
  → [Knowledge-Retrieval: RAGFlow 检索]
  → [IF-ELSE: 检索结果命中?]
      ├─ Yes → [LLM: 基于知识库回答(JSON格式)] → [Answer]
      └─ No  → [LLM: 通用回答(JSON格式)] → [Answer]
  → [Code: 更新对话变量]

2.4 精简操作步骤

1. 导出当前 DSL：在 Dify 后台导出 app-7jkRkAzvX4QM9v9SM3P8mMEO 的完整 YAML（已导出，见 scripts/dify_export_clean.yaml）
2. 在 Dify 后台编辑工作流：
   • 删除审批意图路由相关节点（12个 if-else + answer）
   • 删除 BYOD 拦截相关节点（8个）
   • 删除格式化输出节点（10个 code + template-transform）
   • 删除冗余变量中转节点（12个 assigner）
   • 删除打招呼/人工判断节点（4个）
   • 删除保底机制节点（4个）
3. 更新 LLM 节点的 System Prompt：将 dify_main_chat_prompt_v1.md 的完整 Prompt 粘贴到主 LLM 节点
4. 重新连接节点：确保工作流从 Start 到 Answer 的路径完整
5. 测试工作流：在 Dify 后台的调试面板中测试以下场景：
   • "密码忘记了怎么办" → 应返回 JSON with options
   • "我要申请VPN" → 应返回 JSON with action
   • "你好" → 应返回 JSON 纯文字
6. 发布工作流：点击「发布」按钮，使工作流生效

---

三、P1-5：Dify Prompt v1.1 部署内容

3.1 Prompt 文件位置

完整 Prompt 已准备好，位于：

docs/02-产品需求/dify_main_chat_prompt_v1.md

3.2 部署步骤

1. 登录 Dify 平台：http://yw-dify.dc.servyou-it.com
2. 打开应用：找到「智能IT支持-员工咨询」（API Key: app-7jkRkAzvX4QM9v9SM3P8mMEO）
3. 进入编排页面：点击「编排」→ 进入工作流编辑器
4. 找到主 LLM 节点：在精简后的工作流中，主 LLM 节点（用于生成最终回复的节点）
5. 替换 System Prompt：
   • 将 dify_main_chat_prompt_v1.md 中「## System Prompt 正文」以下的所有内容复制
   • 粘贴到 LLM 节点的「SYSTEM」输入框中
   • 确保 USER 输入框设置为 {{#sys.query#}}（用户原始输入）
6. 配置模型参数：
   • 模型：gpt-3.5-turbo（或可用的 OpenAI 兼容模型）
   • Temperature：0.3（低温度保证 JSON 格式稳定）
   • Max Tokens：500（JSON 输出不需要太长）
7. 测试验证：
   • 在调试面板输入 "密码忘了" → 验证返回 JSON 包含 text + options + diagnosis_stage
   • 在调试面板输入 "我要申请VPN" → 验证返回 JSON 包含 action
   • 在调试面板输入 "谢谢" → 验证返回 JSON 纯文字
8. 发布：确认无误后点击「发布」

3.3 Prompt 核心要点

Prompt v1.1 的关键设计：

要点	说明
JSON 强制输出	4个字段：text、action、options、diagnosis_stage
文字简短	text 字段 ≤50字，口语化
诊断阶段	6种值：initial/gathering_info/diagnosing/recommending/resolved/escalating
审批卡片	action.type = "approval_card"，8种审批类型
交互选项	options 最多4个，label ≤8字
无 markdown	直接输出 JSON 原文，不用代码块包裹

3.4 后端适配确认

后端 _call_dify_native() 和 _parse_structured_response() 已完成适配：

• _call_dify_native()：直连 Dify /v1/chat-messages，blocking 模式，返回 answer 字段
• _parse_structured_response()：解析 answer 字段为 JSON，提取 text/action/options/diagnosis_stage
• 失败降级：JSON 解析失败 → 纯文本回复（不中断用户体验）

---

四、P1-6：知识库内容优化计划

4.1 当前知识库状态

RAGFlow 生产环境：http://10.80.0.85:8080/（API: :9380）

Dify 中引用的知识库：

1. IT知识库：日常IT问题解答（密码重置、VPN连接、打印机等）
2. 审批流程库：12种审批类型的操作流程
3. FAQ库：高频问题快速回答

4.2 优化目标

指标	当前	目标
检索准确率	~60%（粗估）	≥85%
知识库文档数	~200篇	~150篇（精简+补充）
平均检索时间	~3s	≤2s
无效检索率	~25%	≤10%

4.3 优化策略

策略1：知识库结构化重构

IT知识库/
├── 01-账号密码/          # 密码重置、账号解锁、二次验证
│   ├── 企微密码重置.md
│   ├── 邮箱密码重置.md
│   ├── aTrust密码重置.md
│   └── GitLab密码重置.md
├── 02-网络VPN/           # VPN连接、网络故障、WiFi
│   ├── 零信任aTrust连接.md
│   ├── 传统VPN配置.md
│   └── 网络不通排查.md
├── 03-设备硬件/          # 电脑、显示器、打印机
│   ├── 打印机连接.md
│   ├── 蓝屏排查.md
│   └── 设备报修流程.md
├── 04-软件安装/          # 软件安装、授权、更新
│   ├── 软件安装指南.md
│   └── 软件授权申请.md
├── 05-审批流程/          # 12种审批类型
│   ├── 设备申请流程.md
│   ├── VPN账号申请.md
│   └── ...
└── 06-常见FAQ/           # 高频问题
    ├── 电脑卡顿.md
    └── 邮件配置.md

策略2：文档内容标准化

每篇知识库文档统一格式：

# [问题标题]

## 问题描述
[1-2句话描述问题场景]

## 解决方案
### 步骤1：[操作名称]
[具体操作步骤]

### 步骤2：[操作名称]
[具体操作步骤]

## 相关链接
- [操作入口URL]
- [相关文档]

## 关键词
密码、重置、企微、登录

策略3：RAGFlow 检索优化

1. Chunk 策略调整：

   • 将大文档拆分为 ≤500 token 的 chunk
   • 每个 chunk 包含完整的「问题描述 + 解决方案」
   • 避免跨 chunk 的信息断裂

2. Embedding 模型：

   • 确认使用中文优化的 embedding 模型（如 bge-large-zh）
   • 如果当前用的是英文模型，切换后检索准确率可提升 15-20%

3. 检索参数调优：

   • Top-K：5→3（减少噪音）
   • 相似度阈值：0.5→0.65（提高精度）
   • Rerank：启用 rerank 模型（如 bge-reranker-base）

策略4：知识库内容补充

基于员工咨询高频场景，需补充以下内容：

场景	当前状态	补充内容
企微使用问题	缺失	企微登录/消息/审批/会议常见问题
税友安全助手	缺失	安装/认证失败/网络断开排查
域控账号	部分	域控密码同步机制 + 常见故障
云桌面	缺失	云桌面连接/卡顿/文件传输
视频会议	部分	腾讯会议/企微会议常见问题

4.4 实施时间线

阶段	内容	预计工作量
第1周	知识库结构化重构 + 文档标准化	2天
第1周	RAGFlow 检索参数调优	0.5天
第2周	高频场景内容补充（20篇）	2天
第2周	Embedding 模型评估 + 切换	1天
第3周	端到端测试 + 效果评估	1天

---

五、完整执行清单

5.1 用户需在 Dify 平台操作（阻塞项）

• D-1：登录 http://yw-dify.dc.servyou-it.com
• D-2：打开「智能IT支持-员工咨询」应用（app-7jkRkAzvX4QM9v9SM3P8mMEO）
• D-3：精简工作流（按 P1-4 方案，85→~35节点）
• D-4：更新主 LLM 节点的 System Prompt（按 P1-5 部署步骤）
• D-5：在调试面板测试3个场景（密码/VPN/打招呼）
• D-6：点击「发布」按钮
• D-7：发布后通知我验证 API 连通性

5.2 我来完成（Dify 发布后）

• M-1：验证 Dify 原生 API 返回 JSON 格式（复用 test_dify_native.py）
• M-2：请用户在企微内发消息测试端到端链路
• M-3：检查后端日志确认 调用 Dify 原生 API + JSON 解析成功
• M-4：验证前端结构化消息渲染（文字气泡 + 卡片 + 选项按钮）
• M-5：开始知识库优化（P1-6）

5.3 临时方案（如需立即可用）

如果用户暂时无法在 Dify 平台操作，可临时切换到旧 Key（需用户授权）：

# 临时切换 .env 中的 DIFY_NATIVE_API_KEY
DIFY_NATIVE_API_KEY=app-UaTWYdBSwN6VktKQlbh5YN5H

注意：旧 Key 返回纯文本（非JSON），后端会降级为纯文字回复。结构化功能（卡片/选项）不可用，但至少 AI 对话能正常工作。

---

六、风险评估

风险	等级	缓解措施
Dify 工作流精简后遗漏关键路径	中	精简前已导出完整 DSL YAML 备份
Prompt v1.1 在 Dify 中 JSON 输出不稳定	中	Temperature=0.3 + 后端有 JSON 解析降级
RAGFlow 检索准确率不达标	低	可通过调整检索参数 + 补充内容逐步优化
知识库内容过时	中	建立月度知识库审查机制