| name | brew-parameter-recommender |
| description | 为用户推荐个性化冲煮参数。根据豆子烘焙度、冲煮方式、手法、器具和口味偏好，
结合知识库权威数据和用户历史成功记录，生成完整的冲煮参数组。
触发场景：用户请求推荐冲煮参数、引导冲煮的"配置参数"阶段、用户拿到新豆子不知道用什么参数。
|
| metadata | {"author":"MCGA Team","version":"1.0.0","category":"recommendation"} |
Skill: 冲煮参数推荐 / Brew Parameter Recommender
功能描述
根据用户提供的豆子信息、器具和偏好，推荐一组完整的冲煮参数（研磨度/粉量/水量/水温/萃取时间），并附上推荐理由。
触发条件
当以下任一条件满足时触发:
- 用户主动请求推荐冲煮参数
- 用户在引导冲煮的"配置参数"阶段需要参数建议
- 用户选择了豆子和冲煮方式但不确定具体参数
- 用户问"这个豆子怎么冲"（结合 brew-plan-recommender 使用）
输入参数
必需输入
| 参数 | App 字段 | 类型 | 说明 |
|---|
| 烘焙度 | roastLevel | string | light / medium_light / medium / medium_dark / dark |
| 冲煮方式 | brewMethod | string | pourover / coldbrew |
可选输入（用于精细化推荐）
| 参数 | App 字段 | 类型 | 说明 |
|---|
| 冲煮手法 | brewTechnique | string | yidaoliu / sanduanshi（仅手冲） |
| 咖啡豆名称 | beanName | string | 用于查询历史记录 |
| 磨豆机型号 | grinderModel | string | 用于研磨度校准 |
| 滤杯型号 | filterCup | string | 用于研磨度修正 |
| 口味偏好 | — | string | 偏酸 / 偏甜 / 均衡 / 偏浓 / 偏淡 |
| 粉量 | coffeeDose | number | 用户指定粉量时按比例计算水量 |
| 环境温度 | ambientTemp | number | 环境温度修正 |
| 湿度 | humidity | number | 湿度修正 |
上下文数据（系统自动获取）
| 数据 | 来源 | 用途 |
|---|
| 用户历史中同类 taste=good 记录 | coffee_logs 集合 | 提取成功参数模式 |
| 用户历史中同类 taste=bad + badReasons 记录 | coffee_logs 集合 | 避免已知失败参数 |
| 用户器具列表 | users 集合 | 确认可用器具 |
处理流程
Step 1: 加载知识库
├── brewMethod='pourover' → 加载 04-pourover-guide.md + 09-parameter-reference.md
├── brewMethod='coldbrew' → 加载 05-coldbrew-guide.md + 09-parameter-reference.md
└── 加载 06-roast-level-guide.md（始终）
Step 2: 查表获取基准参数
├── 从 09-parameter-reference.md 中按 brewMethod × roastLevel × brewTechnique 查表
└── 获取: grindSize范围, waterTemp范围, coffeeDose, waterAmount, brewTime范围
Step 3: 器具修正
├── filterCup 修正研磨度（04 中滤杯差异表）
│ ├── V60: ±0
│ ├── Kalita: +1~2格（三孔限流滞留时间长，略粗防过萃）
│ ├── Origami (V60滤纸): ±0; Origami (Wave滤纸): +1格
│ ├── Chemex: +1~2格
│ └── 其他: 按流速特性推断
└── grinderModel: 如有历史成功值，以历史值为锚
Step 4: 口味偏好修正
├── 偏酸/偏明亮 → grindSize +1, waterTemp -1°C
├── 偏甜/偏均衡 → 基准值不变
├── 偏浓 → 粉水比调浓（coffeeDose +1g 或 waterAmount -15ml）
└── 偏淡 → 粉水比调淡
Step 5: 历史数据个性化
├── 查询: 同 roastLevel + 同 brewMethod + taste='good' 的最近 5 条记录
├── 如有: 计算历史成功参数的中位数
│ └── 推荐值 = 加权平均(知识库基准 × 0.4, 历史中位数 × 0.6)
├── 如无: 使用知识库基准值
└── 额外检查: 同类 taste='bad' 记录的参数 → 标记为"避免区间"
Step 6: 环境修正
├── ambientTemp < 15°C → waterTemp +1~2°C
├── ambientTemp > 30°C → waterTemp -0.5~1°C; 冷萃 steepTime -1~2h
└── humidity > 70% → grindSize +0.5~1格
Step 7: 生成输出
└── 推荐参数组 + 每个参数的推荐理由
输出格式
{
"recommendation": {
"grindSize": 20,
"coffeeDose": 15,
"waterAmount": 240,
"waterTemp": 93,
"brewTime": "约 2:30",
"brewRatio": "1:16"
},
"explanation": {
"summary": "中浅烘豆手冲一刀流，推荐中细研磨、93°C水温，突出明亮酸质和甜感。",
"grindSize": "中浅烘V60基准18格，您历史成功值集中在20格，综合推荐20格。",
"waterTemp": "中浅烘推荐92-94°C，取中间值93°C。",
"coffeeDose": "标准15g单杯粉量。",
"waterAmount": "1:16粉水比，15g × 16 = 240ml。",
"brewTime": "一刀流V60预期约2:00-3:00，中间值约2:30。"
},
"confidence": "high",
"basedOn": {
"knowledgeBase": ["04-pourover-guide", "06-roast-level-guide", "09-parameter-reference"],
"historicalRecords": 3,
"historicalGoodRate": "75%"
}
}
示例场景
场景 1: 新手浅烘手冲
输入:
- roastLevel:
light
- brewMethod:
pourover
- brewTechnique:
yidaoliu
- filterCup:
V60
- 无历史记录
推荐输出:
- grindSize: 16, coffeeDose: 15g, waterAmount: 250ml, waterTemp: 94°C, brewTime: ~2:30
- 理由: "浅烘豆密度高，需要较细的研磨(16格)和较高的水温(94°C)来充分萃取。V60基准值无需修正。建议闷蒸30秒后一次注完。"
场景 2: 有历史的中度三段式
输入:
- roastLevel:
medium
- brewMethod:
pourover
- brewTechnique:
sanduanshi
- filterCup:
Kalita Wave
- grinderModel:
Comandante C40
- 历史: 3条taste=good记录，grindSize中位数=22
推荐输出:
- grindSize: 22, coffeeDose: 15g, waterAmount: 240ml, waterTemp: 92°C, brewTime: ~3:00
- 理由: "中度烘焙三段式基准研磨度19-25格。Kalita修正-1格=18-24格。您历史成功值集中在22格(Comandante C40)，综合推荐22格。三段式每段约70ml。"
场景 3: 深烘冷萃
输入:
- roastLevel:
dark
- brewMethod:
coldbrew
- 口味偏好: 偏浓
推荐输出:
- grindSize: 36, coffeeDose: 50g, waterAmount: 300ml (1:6 浓缩), waterTemp: 4°C, steepTime: 12-14h
- 理由: "深烘冷萃溶解度高，推荐浓缩型(1:6)。粗研磨36格防止过萃。冷藏浸泡12-14小时。饮用时兑水/奶1:1稀释。"
知识库依赖
| 优先级 | 文档 | 加载条件 |
|---|
| 必需 | 09-parameter-reference.md | 始终 |
| 必需 | 06-roast-level-guide.md | 始终 |
| 条件 | 04-pourover-guide.md | brewMethod='pourover' |
| 条件 | 05-coldbrew-guide.md | brewMethod='coldbrew' |
| 条件 | 08-brew-techniques.md | 需要手法推荐时 |
| 辅助 | 02-water-chemistry.md | 有环境数据时 |
| 辅助 | 03-grind-science.md | 需要磨豆机知识时 |
| 辅助 | 10-bean-freshness.md | 有烘焙日期时，调整闷蒸和研磨度 |
| 参考 | 08-brew-techniques.md (WBrC冠军配方) | 提供竞技级参考基准 |
| 辅助 | 11-origin-processing.md | 有产地/处理法信息时，调整研磨度和水温 |
