refactor: UDE 诊断整合向量聚类方案（DashScope + DBSCAN）

agent/skills/ude_diagnosis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: UDE 诊断
-description: 基于 TOC 约束理论，从 VOC 消费者数据中提取并校验 UDE（不良效果），通过因果推导收敛到核心问题
+description: 基于 TOC 约束理论，从 VOC 消费者数据中提取 UDE（不良效果），通过向量聚类发现核心问题
 ---
 
 # UDE 诊断（Undesirable Effects Diagnosis）
@@ -13,173 +13,153 @@ UDE 是**症状**，不是病因，也不是解决方案。多个 UDE 之间的
 
 ---
 
-## 第一步：从 VOC 数据提取 UDE 候选
+## 整体流程
 
-如果已有 VOC 研究数据（通过 `voc_research` 技能采集并标注），优先从标注数据中提取 UDE 候选：
+```
-
+VOC 评论 ──LLM转写──→ UDE 格式句 ──向量化──→ 语义聚类 ──覆盖扫描──→ 核心 UDE 清单
-### 数据来源映射
+                ↑                    ↑           ↑                    ↑
-
+           格式转换（低幻觉）   DashScope v4   DBSCAN（确定性）    因果链验收
-| VOC 标注维度 | 对应 UDE 线索 |
-|-------------|-------------|
-| `tonbs_barrier`（消费障碍） | 🔴 **最直接的 UDE 来源** — 消费者正在经历的阻碍 |
-| `compensatory`（代偿行为） | 🟡 UDE 的佐证 — 消费者"不得不"的替代方案说明需求未被满足 |
-| `sentiment = negative` | 🟡 负面情绪集中的领域可能隐藏 UDE |
-| `tonbs_need`（未满足需求） | 🟢 辅助验证 — 需求与障碍的对应关系 |
-
-### 操作方法
-
-如果有 VOC 研究 ID，通过 API 查询 Barrier 排名：
-
-```bash
-source ~/.copaw/workspaces/mafia-expert/.env
-curl -sS "https://brand.brainwork.club/voc/api/research/${RESEARCH_ID}/chat" \
-  -H "Content-Type: application/json" \
-  -H "X-TikHub-Key: $TIKHUB_API_KEY" \
-  -d '{"message": "请列出 tonbs_barrier 的 Top 10 分布及每个值的典型原声"}'
 ```
 
-将返回的高频 Barrier 转写为 UDE 候选句。
+**LLM 只出场一次（转写），相似性判断和频次统计全部交给向量空间。**
-
-### 无 VOC 数据时
-
-直接引导用户从自身经验出发列举。**不要用预设框架**（如"战略/业绩/营销"等维度），而是问：
-
-> "站在你的客户/消费者的角度，他们**当前持续承受**着哪些让他们不满意、阻碍他们更好地完成任务的问题？尽可能多地列出来。"
 
 ---
 
-## 第二步：UDE 陈述规范校验
+## 第一步：VOC → UDE 转写
 
-每条 UDE 候选必须通过以下 **7 条规范**。不合格的退回修改，不能凑合使用。
+### 有 VOC 研究数据时
 
-| # | 规范 | 检查问题 | 常见错误 → 正确写法 |
+对 Agent 说：
-|---|------|---------|-------------------|
+> "请对研究 [research_id] 的 VOC 评论进行 UDE 转写"
-| 1 | **完整陈述句** | 是否是完整的句子？ | ❌ "响应慢" → ✅ "客户投诉响应时间持续超过48小时" |
+
-| 2 | **现在时态** | 是否描述当前正在发生的事？ | ❌ "去年产能曾经不足" → ✅ "当前产能利用率低于70%" |
+Agent 会调用 `voc_to_ude` 工具，将每条消费者评论转写为一条 UDE 格式句。
-| 3 | **只描述效果，不含原因** | 是否混入了因果分析？ | ❌ "因为人手不足所以发货延迟" → ✅ "发货持续延迟" |
+
-| 4 | **不是伪装的解决方案** | 是否暗藏了"应该做X"？ | ❌ "我们需要更多员工" → ✅ "生产产能不足以满足当前需求" |
+转写规则（LLM 的任务是"格式转换"，不是"分析"）：
-| 5 | **单一实体** | 一条只描述一个问题？ | ❌ "利润下降，而且客户流失" → 拆为两条 |
+- 输入："一瓶三百多，吃一个月，真的吃不起"
-| 6 | **客观可验证** | 利益相关方能否达成共识？ | ❌ "我觉得客户不够忠诚" → ✅ "回头客比例同比下降15%" |
+- 输出："该品类产品月均消费成本持续超出目标消费者的可接受范围"
-| 7 | **在影响范围内** | 组织/团队可以采取行动改善？ | ❌ "全球经济下行" → 删除（不可控） |
+
+### UDE 格式规范（7 条硬约束）
+
+| # | 规范 | 检查要点 |
+|---|------|---------|
+| 1 | **完整陈述句** | 不是"响应慢"，而是"客户投诉响应时间持续超过48小时" |
+| 2 | **现在时态** | 描述当前正在发生的事，不是过去或未来 |
+| 3 | **只描述效果，不含原因** | 不能包含"因为…所以…" |
+| 4 | **不是伪装的解决方案** | 不能说"需要X"、"应该做Y" |
+| 5 | **单一实体** | 一条 UDE 只描述一个问题 |
+| 6 | **客观可验证** | 利益相关方能达成共识的事实 |
+| 7 | **在影响范围内** | 品牌/企业可以采取行动改善的 |
 
 ### 「伪装的解决方案」速查表
 
-这是最常犯的错误——以下都是**不合格的 UDE**：
-
 | ❌ 伪装的解决方案 | ✅ 正确的 UDE |
 |-----------------|-------------|
 | "需要新的 ERP 系统" | "关键数据难以检索，决策持续滞后" |
 | "应该增加广告预算" | "品牌知名度持续低于主要竞品" |
 | "需要引进高端人才" | "核心技术岗位长期空缺，项目交付延期" |
 | "应该做消费者调研" | "产品开发决策缺乏消费者需求依据" |
-| "需要开拓线上渠道" | "线下渠道增速放缓，新客获取成本持续攀升" |
 
-### 输出格式
+### 无 VOC 数据时
 
-对每条 UDE 输出校验结果：
+引导用户从自身经验出发。**不要用预设框架**，直接问：
 
-```markdown
+> "站在你的客户/消费者的角度，他们**当前持续承受**着哪些让他们不满意、阻碍他们更好地完成任务的问题？"
-#### UDE-[编号]：[UDE 描述]
 
-| 规范 | 通过？ | 备注 |
+---
-|------|-------|------|
-| 1. 完整陈述句 | ✅/❌ | [如不通过，说明原因和修改建议] |
-| 2. 现在时态 | ✅/❌ | |
-| 3. 不含原因 | ✅/❌ | |
-| 4. 不是方案 | ✅/❌ | |
-| 5. 单一实体 | ✅/❌ | |
-| 6. 客观可验证 | ✅/❌ | |
-| 7. 影响范围内 | ✅/❌ | |
 
-**结论**：✅ 合格 / ❌ 需修改：[修改建议]
+## 第二步：向量聚类
+
+### 前置条件
+用户需配置 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 簇
 ```
 
 ---
 
-## 第三步：构建因果链（简版 CRT）
+## 第三步：覆盖扫描
 
-将校验合格的 UDE（建议精简到 **5-10 条**）用「因为…所以…」链接，寻找因果关系。
+对 Agent 说：
+> "请扫描 UDE 聚类的覆盖情况"
 
-### 方法
+Agent 会调用 `scan_coverage` 工具，返回：
+- 覆盖率：多少 VOC 评论被 UDE 簇覆盖
+- 噪声占比：未被覆盖的 UDE（可能遗漏的线索）
+- 噪声样本：供人工检查
 
-1. 取任意两条 UDE，问：「A 是否会导致 B？B 是否会导致 A？还是两者没有直接关系？」
+判断标准：
-2. 用箭头标注因果方向：A → B 表示"因为 A，所以 B"
+- 噪声 < 10%：覆盖充分
-3. 找到被最多箭头指向的 UDE = 上层效果（症状）
+- 噪声 10-20%：查看样本，可能遗漏某类 UDE
-4. 找到**发出最多箭头**的 UDE = 候选核心问题（根因方向）
+- 噪声 > 20%：需要调整聚类参数
+
+---
+
+## 第四步：构建因果链
+
+取聚类产生的 Top 5-10 个代表性 UDE，用「因为…所以…」链接，寻找因果关系：
+
+1. 取任意两条 UDE，问："A 是否会导致 B？"
+2. 用箭头标注因果方向
+3. **发出最多箭头的 UDE** = 候选核心问题（根因方向）
 
 ### 朗读测试
 
-用以下句式朗读每条因果链：
 - 从下到上：「**因为** [原因 UDE]，**所以** [效果 UDE]」
 - 从上到下：「[效果 UDE] **是因为** [原因 UDE]」
 
-如果听起来不合逻辑，检查是否缺少中间环节或隐含假设。
+听着不合逻辑 → 检查是否缺少中间环节。
-
-### 输出格式
-
-```markdown
-### 因果链
-
-UDE-3（根因方向）
-  → UDE-1
-    → UDE-5
-    → UDE-7（上层症状）
-  → UDE-2
-    → UDE-6（上层症状）
-
-### 核心问题候选
-UDE-3：[描述] — 它直接或间接导致了 [X] 条其他 UDE
-```
 
 ---
 
-## 第四步：核心问题验收（CLR 检验）
+## 第五步：核心问题验收（CLR 检验）
 
-对核心问题候选进行 **3 项严格验收**：
+对核心问题候选进行 3 项验收：
 
-### ① 充分性检验
+| 检验项 | 问题 |
-- 该原因**单独**足够导致那些效果吗？
+|--------|------|
-- 还需要什么其他条件同时成立？
+| **充分性** | 该原因单独足够导致那些效果吗？还需要什么其他条件？ |
-- 如果需要，补充缺失的联合原因
+| **预测效果** | 如果核心问题存在，还应该产生什么其他效果？那些效果存在吗？ |
-
+| **同义反复** | 核心问题是不是在用不同的话重复某个 UDE？ |
-### ② 预测效果检验
-- 如果这个核心问题真的存在，**还应该**产生什么其他效果？
-- 那些预测的效果在现实中存在吗？
-- 存在 → 验证通过；不存在 → 因果关系可能有误
-
-### ③ 同义反复检验
-- 核心问题是不是在用不同的话重复某个 UDE？
-- 如果是 → 不是真正的核心问题，需要继续向下追溯
-
-### 输出格式
-
-```markdown
-### 核心问题验收
-
-**核心问题**：[描述]
-
-| 检验项 | 结果 | 说明 |
-|--------|------|------|
-| 充分性 | ✅/❌ | [该原因是否足够导致那些效果] |
-| 预测效果 | ✅/❌ | [预测的其他效果是否存在] |
-| 同义反复 | ✅/❌ | [是否只是换了说法] |
-
-**验收结论**：✅ 确认为核心问题 / ❌ 需要继续追溯
-```
 
 ---
 
 ## 完成标志
 
-当以下条件全部满足时，此技能完成：
+- [ ] VOC 评论已转写为 UDE 格式句
-
+- [ ] UDE 已通过向量聚类，产出按覆盖量排序的簇
-- [ ] UDE 候选已从 VOC 数据和/或用户经验中收集
+- [ ] 覆盖扫描通过（噪声 < 10%）
-- [ ] 所有 UDE 通过 7 条陈述规范校验
-- [ ] 精简到 5-10 条合格 UDE
 - [ ] 构建了因果链，识别出核心问题候选
 - [ ] 核心问题通过 CLR 三项验收
 - [ ] 用户确认核心问题
 
 完成后，将核心问题和 UDE 清单传递给下一步：**冲突图构建**。
 
-> **关键提醒**：核心问题的筛选标准是「导致最多 UDE 的根因」，不是「跟我们的产品最相关的」。产品/方案如何注入到核心问题上，是后续冲突图和惯例打破要解决的事。
+> **关键提醒**：核心问题 = 导致最多 UDE 的根因，不是"跟我们的产品最相关的"。产品/方案如何注入到核心问题上，是冲突图和惯例打破要解决的事。