| 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（明显偏差）
- 诊断: 过萃——研磨过细 + 水温过高
建议:
- (首选) 研磨度从 16 调至 22 格 — "远低于推荐范围，苦味主因"
- (次选) 水温从 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 上限
- 诊断: 萃取不足——时间不够 + 研磨偏粗
建议:
- (首选) 浸泡时间延长至 20-22 小时
- (次选) 研磨度从 36 调至 32 格
- (备选) "浅烘天然酸质较高。如果调参后仍觉得酸，可以尝试中度烘焙的冷萃。"
场景 3: 又酸又苦
输入:
- taste:
bad, badReasons: ['too_bitter', 'too_sour']
- roastLevel:
medium_light, brewMethod: pourover
- grindSize: 18, waterTemp: 93, coffeeDose: 15, waterAmount: 240
诊断:
- 参数均在推荐范围内
- 同时酸和苦 → 不均匀萃取信号
- 诊断: 研磨均匀度问题或注水手法问题
建议:
- "检查磨豆机是否需要校准——同时出现酸味和苦味通常是颗粒分布不均匀导致的"
- "尝试换用 Kalita Wave 平底滤杯——比 V60 更容错，萃取更均匀"
- "如使用三段式手法，确保每段注水均匀覆盖粉层"
知识库依赖
| 优先级 | 文档 | 用途 |
|---|
| 必需 | 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，建议用户提供更多描述
