brew-diagnosis

name	brew-diagnosis
description	当用户标记口感为"难喝"时，基于 badReasons（太苦/太酸/自定义）和冲煮参数， 诊断萃取问题并提供优先级排序的调参建议。 触发场景：用户标记 taste=bad 后自动触发、用户主动要求分析上一次冲煮、用户描述口感问题。
metadata	{"author":"MCGA Team","version":"1.0.0","category":"diagnosis"}

Skill: 冲煮诊断调参 / Brew Diagnosis

功能描述

分析用户"难喝"的冲煮记录，根据 badReasons 和实际参数与推荐范围的偏差，诊断萃取问题（过萃/欠萃/浓度/不均匀萃取），并提供优先级排序的具体调参建议。

核心原则: 一次只建议改一个变量，便于用户理解因果关系。

触发条件

• 用户标记 taste = 'bad' 后（可自动触发或用户选择"分析"）
• 用户主动要求诊断："上一次不好喝，帮我看看怎么调"
• 用户连续多次 taste=bad，系统主动建议诊断

输入参数

必需输入

参数	App 字段	类型	说明
口感	taste	string	固定为 'bad'
难喝原因	badReasons	string[]	['too_bitter'], ['too_sour'], ['other:自定义'] 等，可多选
烘焙度	roastLevel	string	当前冲煮的烘焙度
冲煮方式	brewMethod	string	pourover / coldbrew
研磨度	grindSize	number	当前使用的研磨度
水温	waterTemp	number	当前使用的水温
粉量	coffeeDose	number	当前粉量
水量	waterAmount	number	当前水量

可选输入

参数	App 字段	类型	说明
萃取时间	brewTime	number	实际萃取时间
手法	brewTechnique	string	yidaoliu / sanduanshi
滤杯	filterCup	string	滤杯型号
磨豆机	grinderModel	string	磨豆机型号
品鉴笔记	notes	string	用户自由描述的补充信息
豆名	beanName	string	用于查询历史记录

上下文数据

数据	来源	用途
推荐参数范围	09-parameter-reference.md	对比偏差
同豆子的 taste=good 历史记录	coffee_logs	提供目标参数参考
同问题的过往诊断记录	coffee_logs	避免重复建议无效调整

处理流程

Step 1: 解析 badReasons → 确定主要诊断方向
   ├── 'too_bitter' → 过萃路径
   ├── 'too_sour' → 欠萃路径
   ├── 'too_bitter' + 'too_sour' → 不均匀萃取
   ├── 'other:太淡' → 浓度不足路径
   ├── 'other:涩' → 过萃 + 细粉路径
   ├── 'other:发酵味' / 'other:异味' → 非参数问题（豆子/器具）
   └── 其他 'other:xxx' → 分析 notes，尝试匹配已知模式

Step 2: 获取推荐参数范围
   ├── 从 09-parameter-reference.md 查表
   ├── 按 brewMethod × roastLevel × brewTechnique
   └── 应用 filterCup 修正

Step 3: 参数偏差分析
   for each param in [grindSize, waterTemp, brewTime, brewRatio]:
     偏差 = 实际值 - 推荐范围中心值
     偏差级别 = 正常 / 轻微 / 明显 / 严重（见 09 的判定标准）
     偏差方向 = 偏向过萃 or 偏向欠萃
   
   生成偏差报告: [{参数, 实际值, 推荐范围, 偏差级别, 偏差方向}]

Step 4: 匹配诊断路径（参考 07-taste-diagnosis.md）
   ├── too_bitter:
   │   ├── 找偏差最大且方向为"过萃"的参数 → 首选调整项
   │   ├── 如无明显偏差 → 建议磨粗1格（最安全的调整）
   │   └── 如 roastLevel='dark' 且参数正常 → 可能是豆子特征，建议换烘焙度或冷萃
   │
   ├── too_sour:
   │   ├── 找偏差最大且方向为"欠萃"的参数 → 首选调整项
   │   ├── 如无明显偏差 → 建议磨细1格
   │   └── 如 roastLevel='light' 且参数正常 → 浅烘天然酸，建议尝试中度烘焙
   │
   ├── too_bitter + too_sour (不均匀萃取):
   │   ├── 检查研磨均匀度（建议检查磨豆机）
   │   ├── 检查注水手法（建议换用容错性高的滤杯如Kalita）
   │   └── 建议筛除细粉
   │
   └── other 类型:
       ├── 太淡 → 粉水比分析
       ├── 涩 → 过萃 + 磨豆机检查
       └── 异味 → 非参数建议（检查豆子/器具清洁）

Step 5: 查询用户历史
   ├── 同豆子 taste=good 记录 → 提取成功参数作为调参目标
   ├── 同问题过往记录 → 检查上次建议是否已执行
   │   ├── 如已执行但仍有问题 → 换下一优先级的调整项
   │   └── 如未执行 → 重复建议
   └── 统计该豆子的 goodRate → 如果极低可能是豆子不适合当前方式

Step 6: 生成调参建议
   ├── 排序：按"与badReasons的关联度"×"偏差大小"
   ├── 每条建议包含：调什么、怎么调、调多少、为什么
   └── 限制最多 3 条建议（一次改一个，但给出备选）

输出格式

{
  "diagnosis": {
    "primaryIssue": "过萃 (Over-extracted)",
    "summary": "研磨度偏细且水温偏高，导致萃取过度产生苦味。",
    "confidence": "high"
  },
  "parameterAnalysis": [
    {
      "param": "grindSize",
      "actual": 14,
      "recommended": "18–24",
      "deviation": "严重偏差（偏向过萃）",
      "isLikelyCause": true
    },
    {
      "param": "waterTemp",
      "actual": 96,
      "recommended": "91–93",
      "deviation": "明显偏差（偏向过萃）",
      "isLikelyCause": true
    },
    {
      "param": "brewRatio",
      "actual": "1:16",
      "recommended": "1:16",
      "deviation": "正常",
      "isLikelyCause": false
    }
  ],
  "adjustments": [
    {
      "priority": 1,
      "param": "grindSize",
      "action": "磨粗",
      "from": 14,
      "to": 20,
      "reason": "当前14格远低于中度烘焙推荐的18-24格，是苦味的最可能原因。建议先调至20格。"
    },
    {
      "priority": 2,
      "param": "waterTemp",
      "action": "降温",
      "from": 96,
      "to": 92,
      "reason": "96°C高于推荐上限93°C。如果磨粗后仍偏苦，下次降至92°C。"
    }
  ],
  "additionalNotes": "建议先只调整研磨度（优先级1），下次冲煮后再评估是否需要调温度。",
  "historicalContext": {
    "sameBeanGoodRecords": 2,
    "sameBeanGoodGrindSize": 22,
    "suggestion": "您之前用22格冲同款豆子评价为好喝，可直接尝试22格。"
  }
}

示例场景

场景 1: 中度烘焙手冲太苦

输入:

• taste: bad, badReasons: ['too_bitter']
• roastLevel: medium, brewMethod: pourover, brewTechnique: sanduanshi
• grindSize: 16, waterTemp: 95, coffeeDose: 15, waterAmount: 240, brewTime: 210

诊断:

• 研磨度 16 < 推荐 19-25（严重偏差）
• 水温 95 > 推荐 91-93（明显偏差）
• 诊断: 过萃——研磨过细 + 水温过高

建议:

1. (首选) 研磨度从 16 调至 22 格 — "远低于推荐范围，苦味主因"
2. (次选) 水温从 95 降至 92°C — "如果磨粗后仍苦，再降温"

场景 2: 浅烘冷萃太酸

输入:

• taste: bad, badReasons: ['too_sour']
• roastLevel: light, brewMethod: coldbrew
• grindSize: 36, coffeeDose: 30, waterAmount: 390, brewTime: 43200 (12h)

诊断:

• 浸泡时间 12h 偏短（浅烘冷藏推荐 20-24h）
• 研磨度 36 在推荐范围 30-36 上限
• 诊断: 萃取不足——时间不够 + 研磨偏粗

建议:

1. (首选) 浸泡时间延长至 20-22 小时
2. (次选) 研磨度从 36 调至 32 格
3. (备选) "浅烘天然酸质较高。如果调参后仍觉得酸，可以尝试中度烘焙的冷萃。"

场景 3: 又酸又苦

输入:

• taste: bad, badReasons: ['too_bitter', 'too_sour']
• roastLevel: medium_light, brewMethod: pourover
• grindSize: 18, waterTemp: 93, coffeeDose: 15, waterAmount: 240

诊断:

• 参数均在推荐范围内
• 同时酸和苦 → 不均匀萃取信号
• 诊断: 研磨均匀度问题或注水手法问题

建议:

1. "检查磨豆机是否需要校准——同时出现酸味和苦味通常是颗粒分布不均匀导致的"
2. "尝试换用 Kalita Wave 平底滤杯——比 V60 更容错，萃取更均匀"
3. "如使用三段式手法，确保每段注水均匀覆盖粉层"

知识库依赖

优先级	文档	用途
必需	07-taste-diagnosis.md	诊断决策树和调参规则
必需	09-parameter-reference.md	推荐参数范围对比
必需	01-extraction-science.md	萃取原理支撑诊断
条件	08-brew-techniques.md	手法可能是原因时
条件	04-pourover-guide.md	手冲特定问题诊断
条件	05-coldbrew-guide.md	冷萃特定问题诊断
辅助	03-grind-science.md	研磨均匀度问题

边界与限制

• 非参数问题: 发酵味/异味等可能是豆子品质或器具清洁问题，诊断应明确告知"非冲煮参数问题"
• 数据不足: 当用户只有 1-2 条记录时，诊断主要依赖知识库规则；当有 5+ 条记录时可做更个性化分析
• 置信度: 当 badReasons 与参数偏差方向一致时 confidence=high；方向不一致时 confidence=medium，建议用户提供更多描述