---
name: UDE 诊断
description: 基于 TOC 约束理论，从 VOC 消费者数据中提取 UDE（不良效果），通过向量聚类发现核心问题
---

# UDE 诊断（Undesirable Effects Diagnosis）

## 什么是 UDE

**UDE（Undesirable Effect）= 系统中当前正在发生的、阻碍系统实现目标的、可观测的负面现象。**

UDE 是**症状**，不是病因，也不是解决方案。多个 UDE 之间的因果关系指向隐藏的**核心问题**——通常是一条不被质疑的政策或假设。

---

## 整体流程

```
VOC 评论 ──LLM转写──→ UDE 格式句 ──向量化──→ 语义聚类 ──覆盖扫描──→ 核心 UDE 清单
                ↑                    ↑           ↑                    ↑
           格式转换（低幻觉）   DashScope v4   DBSCAN（确定性）    因果链验收
```

**LLM 只出场一次（转写），相似性判断和频次统计全部交给向量空间。**

---

## 第一步：VOC → UDE 转写

### 有 VOC 研究数据时

对 Agent 说：
> "请对研究 [research_id] 的 VOC 评论进行 UDE 转写"

Agent 会调用 `voc_to_ude` 工具，将每条消费者评论转写为一条 UDE 格式句。

转写规则（LLM 的任务是"格式转换"，不是"分析"）：
- 输入："一瓶三百多，吃一个月，真的吃不起"
- 输出："该品类产品月均消费成本持续超出目标消费者的可接受范围"

### UDE 格式规范（7 条硬约束）

| # | 规范 | 检查要点 |
|---|------|---------|
| 1 | **完整陈述句** | 不是"响应慢"，而是"客户投诉响应时间持续超过48小时" |
| 2 | **现在时态** | 描述当前正在发生的事，不是过去或未来 |
| 3 | **只描述效果，不含原因** | 不能包含"因为…所以…" |
| 4 | **不是伪装的解决方案** | 不能说"需要X"、"应该做Y" |
| 5 | **单一实体** | 一条 UDE 只描述一个问题 |
| 6 | **客观可验证** | 利益相关方能达成共识的事实 |
| 7 | **在影响范围内** | 品牌/企业可以采取行动改善的 |

### 「伪装的解决方案」速查表

| ❌ 伪装的解决方案 | ✅ 正确的 UDE |
|-----------------|-------------|
| "需要新的 ERP 系统" | "关键数据难以检索，决策持续滞后" |
| "应该增加广告预算" | "品牌知名度持续低于主要竞品" |
| "需要引进高端人才" | "核心技术岗位长期空缺，项目交付延期" |
| "应该做消费者调研" | "产品开发决策缺乏消费者需求依据" |

### 无 VOC 数据时

引导用户从自身经验出发。**不要用预设框架**，直接问：

> "站在你的客户/消费者的角度，他们**当前持续承受**着哪些让他们不满意、阻碍他们更好地完成任务的问题？"

---

## 第二步：向量聚类

### 前置条件
用户需配置 DashScope API Key（阿里云百炼控制台获取）。对 Agent 说「我的 DashScope Key 是 xxx」即可。

### 执行
对 Agent 说：
> "请对研究 [research_id] 的 UDE 进行聚类分析"

Agent 会调用 `cluster_udes` 工具：
1. 使用 DashScope text-embedding-v4 将所有 UDE 句向量化（1024 维）
2. 使用 DBSCAN 算法进行语义聚类
3. 返回按覆盖量排序的聚类列表

### 为什么用向量聚类而非标签统计

| | 标签统计（旧方案） | 向量聚类（当前方案） |
|---|---|---|
| 问题 | LLM 标签碎片化（1020 条产出 1003 个标签）| 向量空间天然处理近义表述 |
| 频次 | GROUP BY 结果无意义（每标签=1次） | **簇大小 = 真实覆盖量** |
| 全局视野 | ❌ LLM 逐条处理 | ✅ 向量空间容纳全部 UDE |

### 输出示例

```
簇 1（覆盖 80 条）
  代表 UDE：该品类产品月均消费成本持续超出目标消费者的可接受范围
  原声：["一瓶三百多真的吃不起", "不是不想买太贵了", ...]

簇 2（覆盖 27 条）
  代表 UDE：产品冷藏存储要求与消费者日常场景持续冲突
  原声：["需要冷藏但办公室没冰箱", "忘了放冰箱担心失效", ...]

噪声：45 条（4.4%）— 不属于任何主要 UDE 簇
```

---

## 第三步：覆盖扫描

对 Agent 说：
> "请扫描 UDE 聚类的覆盖情况"

Agent 会调用 `scan_coverage` 工具，返回：
- 覆盖率：多少 VOC 评论被 UDE 簇覆盖
- 噪声占比：未被覆盖的 UDE（可能遗漏的线索）
- 噪声样本：供人工检查

判断标准：
- 噪声 < 10%：覆盖充分
- 噪声 10-20%：查看样本，可能遗漏某类 UDE
- 噪声 > 20%：需要调整聚类参数

---

## 第四步：构建因果链

取聚类产生的 Top 5-10 个代表性 UDE，用「因为…所以…」链接，寻找因果关系：

1. 取任意两条 UDE，问："A 是否会导致 B？"
2. 用箭头标注因果方向
3. **发出最多箭头的 UDE** = 候选核心问题（根因方向）

### 朗读测试

- 从下到上：「**因为** [原因 UDE]，**所以** [效果 UDE]」
- 从上到下：「[效果 UDE] **是因为** [原因 UDE]」

听着不合逻辑 → 检查是否缺少中间环节。

---

## 第五步：核心问题验收（CLR 检验）

对核心问题候选进行 3 项验收：

| 检验项 | 问题 |
|--------|------|
| **充分性** | 该原因单独足够导致那些效果吗？还需要什么其他条件？ |
| **预测效果** | 如果核心问题存在，还应该产生什么其他效果？那些效果存在吗？ |
| **同义反复** | 核心问题是不是在用不同的话重复某个 UDE？ |

---

## 完成标志

- [ ] VOC 评论已转写为 UDE 格式句
- [ ] UDE 已通过向量聚类，产出按覆盖量排序的簇
- [ ] 覆盖扫描通过（噪声 < 10%）
- [ ] 构建了因果链，识别出核心问题候选
- [ ] 核心问题通过 CLR 三项验收
- [ ] 用户确认核心问题

完成后，将核心问题和 UDE 清单传递给下一步：**冲突图构建**。

> **关键提醒**：核心问题 = 导致最多 UDE 的根因，不是"跟我们的产品最相关的"。产品/方案如何注入到核心问题上，是冲突图和惯例打破要解决的事。