当用户标记口感为"难喝"时，基于 badReasons（太苦/太酸/自定义）和冲煮参数， 诊断萃取问题并提供优先级排序的调参建议。 触发场景：用户标记 taste=bad 后自动触发、用户主动要求分析上一次冲煮、用户描述口感问题。
当用户标记口感为"难喝"时，基于 badReasons（太苦/太酸/自定义）和冲煮参数， 诊断萃取问题并提供优先级排序的调参建议。 触发场景：用户标记 taste=bad 后自动触发、用户主动要求分析上一次冲煮、用户描述口感问题。
npx skills add https://github.com/dengyanbo/CoffeeKnowledgeBase --skill brew-diagnosisこのコマンドをClaude Codeにコピー＆ペーストしてスキルをインストール
为用户推荐个性化冲煮参数。根据豆子烘焙度、冲煮方式、手法、器具和口味偏好， 结合知识库权威数据和用户历史成功记录，生成完整的冲煮参数组。 触发场景：用户请求推荐冲煮参数、引导冲煮的"配置参数"阶段、用户拿到新豆子不知道用什么参数。
为用户推荐完整的冲煮方案：冲煮方式 + 手法 + 配方 + 参数。 适用于用户拿到新豆子不知道怎么冲、想尝试不同方案、或在引导冲煮前选择手法时。 综合考虑烘焙度、口味偏好、可用器具和历史成功经验。
| name | brew-diagnosis |
| description | 当用户标记口感为"难喝"时，基于 badReasons（太苦/太酸/自定义）和冲煮参数， 诊断萃取问题并提供优先级排序的调参建议。 触发场景：用户标记 taste=bad 后自动触发、用户主动要求分析上一次冲煮、用户描述口感问题。 |
| metadata | {"author":"MCGA Team","version":"1.0.0","category":"diagnosis"} |
分析用户"难喝"的冲煮记录，根据 badReasons 和实际参数与推荐范围的偏差，诊断萃取问题（过萃/欠萃/浓度/不均匀萃取），并提供优先级排序的具体调参建议。
核心原则: 一次只建议改一个变量，便于用户理解因果关系。
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格。"
}
}
输入:
bad, badReasons: ['too_bitter']medium, brewMethod: pourover, brewTechnique: sanduanshi诊断:
建议:
输入:
bad, badReasons: ['too_sour']light, brewMethod: coldbrew诊断:
建议:
输入:
bad, badReasons: ['too_bitter', 'too_sour']medium_light, brewMethod: pourover诊断:
建议:
| 优先级 | 文档 | 用途 |
|---|---|---|
| 必需 | 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 | 研磨均匀度问题 |