brew-plan-recommender

name	brew-plan-recommender
description	为用户推荐完整的冲煮方案：冲煮方式 + 手法 + 配方 + 参数。 适用于用户拿到新豆子不知道怎么冲、想尝试不同方案、或在引导冲煮前选择手法时。 综合考虑烘焙度、口味偏好、可用器具和历史成功经验。
metadata	{"author":"MCGA Team","version":"1.0.0","category":"recommendation"}

Skill: 冲煮方案推荐 / Brew Plan Recommender

功能描述

为用户推荐一个完整的冲煮方案，从"用什么方式冲"到"用什么手法和配方"到"具体参数是多少"一站式解决。相比 brew-parameter-recommender（已确定方式和手法后推荐参数），本 Skill 从更高层级帮用户做决策。

触发条件

• 用户拿到新豆子："这个豆子怎么冲最好？"
• 用户想换方案："上次手冲不好喝，有没有其他建议？"
• 用户在引导冲煮前选择冲煮方式和手法
• 用户问比较类问题："这个豆子手冲好还是冷萃好？"

输入参数

必需输入

参数	App 字段	类型	说明
烘焙度	roastLevel	string	light / medium_light / medium / medium_dark / dark

可选输入

参数	来源	类型	说明
咖啡豆名称	beanName / 用户输入	string	查询豆子历史
口味偏好	用户描述	string	偏酸/偏甜/偏浓/均衡/追求干净/追求醇厚
可用器具	users.grinders / users.filterCups	string[]	限制推荐范围
场景	用户描述	string	日常/待客/实验/快速
上次冲煮方式	最近记录	string	如果上次不好喝，推荐替换方案

上下文数据

数据	来源	用途
用户各方式的 goodRate	coffee_logs 统计	推荐成功率高的方式
同烘焙度各手法的 goodRate	coffee_logs 统计	推荐成功率高的手法
用户器具列表	users 集合	确认可用器具，影响方案可行性
可用配方列表	brew_recipes 集合	匹配推荐配方

处理流程

Step 1: 确定推荐冲煮方式（brewMethod）
   ├── 加载 06-roast-level-guide.md（烘焙度 × 方式适配表）
   ├── 评分：
   │   ├── 浅烘 → 手冲 5★ / 冷萃 3★
   │   ├── 中浅 → 手冲 5★ / 冷萃 4★
   │   ├── 中度 → 手冲 5★ / 冷萃 4★
   │   ├── 中深 → 手冲 4★ / 冷萃 5★
   │   └── 深烘 → 手冲 3★ / 冷萃 5★
   ├── 历史修正：
   │   ├── 查询用户各方式的 goodRate
   │   └── goodRate 差异 > 20% → 优先推荐高 goodRate 方式
   ├── 场景修正：
   │   ├── "快速" → 优先手冲（冷萃需 12h+）
   │   └── "提前准备" → 冷萃可行
   └── 如上次方式 taste=bad → 推荐替换方式

Step 2: 确定推荐手法（brewTechnique，仅手冲）
   ├── 加载 08-brew-techniques.md（烘焙度 × 手法适配表）
   ├── 默认推荐：
   │   ├── 浅烘/中浅 → 一刀流
   │   ├── 中度/中深/深烘 → 三段式
   ├── 口味偏好修正：
   │   ├── 干净/明亮 → 一刀流
   │   ├── 醇厚/层次 → 三段式
   │   └── 简单/快速 → 一刀流
   ├── 历史修正：
   │   └── 同烘焙度各手法 goodRate → 优先推荐高 goodRate 手法
   └── 如上次手法 taste=bad → 建议尝试另一手法

Step 3: 匹配推荐配方（recipeName）
   ├── 根据 brewTechnique 查询 brew_recipes 集合
   ├── 可用配方列表中选择：
   │   ├── 新手用户 → 推荐"标准"/"经典"配方
   │   ├── 进阶用户（冲煮次数 > 20）→ 可推荐变体配方
   │   └── 如用户指定配方 → 尊重选择
   └── 输出配方名 + 步骤概述

Step 4: 生成推荐参数（委托 brew-parameter-recommender）
   ├── 将确定的 brewMethod + brewTechnique + roastLevel 传入
   ├── 加上用户的器具和偏好信息
   └── 获取完整参数组

Step 5: 组装完整方案
   └── 冲煮方式 + 手法 + 配方 + 参数 + 理由

输出格式

{
  "plan": {
    "brewMethod": "pourover",
    "brewMethodReason": "浅烘豆手冲最能展现产地花果酸质",
    "brewTechnique": "yidaoliu",
    "brewTechniqueReason": "一刀流萃取干净均匀，突出浅烘明亮特征",
    "recipeName": "经典一刀流",
    "recipeOverview": "闷蒸30秒 → 一次注完 → 约2:30完成"
  },
  "parameters": {
    "grindSize": 16,
    "coffeeDose": 15,
    "waterAmount": 250,
    "waterTemp": 94,
    "brewTime": "约 2:30"
  },
  "alternatives": [
    {
      "brewMethod": "pourover",
      "brewTechnique": "sanduanshi",
      "reason": "如果想要更多甜感和层次，可以尝试三段式",
      "grindSizeAdjustment": "+1格 (17格)"
    },
    {
      "brewMethod": "coldbrew",
      "reason": "想要柔和低酸的冷饮版本，可以冷萃（需提前20-24小时准备）",
      "parameters": { "grindSize": 32, "coffeeDose": 30, "waterAmount": 390, "steepTime": "20-24h" }
    }
  ],
  "confidence": "high",
  "basedOn": {
    "knowledgeBase": ["06-roast-level-guide", "08-brew-techniques", "04-pourover-guide"],
    "historicalRecords": 5,
    "pouroverGoodRate": "80%",
    "coldbrewGoodRate": "N/A"
  }
}

示例场景

场景 1: 新豆子（浅烘耶加雪菲）

输入:

• beanName: "耶加雪菲 水洗"
• roastLevel: light
• 口味偏好: "喜欢花果香、干净"
• 可用器具: 磨豆机 Comandante C40, 滤杯 V60

推荐:

• 方式: 手冲 — "浅烘耶加雪菲以花果酸质著称，手冲最能展现"
• 手法: 一刀流 — "干净萃取突出柑橘和茉莉花调"
• 配方: 经典一刀流
• 参数: grindSize 16, coffeeDose 15g, waterAmount 250ml, waterTemp 94°C

替代方案:

• 三段式: "如果想多些蜂蜜般的甜感层次"
• 冷萃: "想要柔和冰爽版本（需提前22小时）"

场景 2: 上次不好喝（中深烘一刀流太苦）

输入:

• beanName: "曼特宁"
• roastLevel: medium_dark
• 上次记录: brewMethod=pourover, brewTechnique=yidaoliu, taste=bad, badReasons=['too_bitter']

推荐:

• 方式: 手冲（保持） — "曼特宁中深烘手冲仍可出好味道"
• 手法: 三段式 — "上次一刀流偏苦，三段式分段注水可更好控制萃取深度"
• 配方: 标准三段式
• 参数: grindSize 26(+3), waterTemp 90(-2°C), 其他保持
• 理由: "一刀流一次注完可能对中深烘萃取过深。三段式分段注水，每段间歇让萃取更可控。同时磨粗3格、降温2°C进一步防苦。"

替代方案:

• 冷萃: "中深烘冷萃天然不苦，非常甜润。推荐 1:13 比例冷藏 16 小时"

场景 3: 深烘豆快速选择

输入:

• roastLevel: dark
• 场景: "日常"
• 可用器具: 磨豆机 Timemore C2, 滤杯 Kalita Wave

推荐:

• 方式: 冷萃（首选） — "深烘冷萃天然低苦味，甜润醇厚"
• 参数: grindSize 40, coffeeDose 30g, waterAmount 390ml, steepTime 12-14h

替代方案:

• 手冲三段式: "如果想要热饮，三段式+低温(88°C)+粗研磨(30格)可减少苦味"

知识库依赖

优先级	文档	用途
必需	06-roast-level-guide.md	烘焙度 × 方式/手法适配
必需	08-brew-techniques.md	手法原理与选择策略
必需	09-parameter-reference.md	参数查表
条件	04-pourover-guide.md	手冲方案细节
条件	05-coldbrew-guide.md	冷萃方案细节
辅助	07-taste-diagnosis.md	上次 bad 的诊断信息

与其他 Skills 的协作

Skill	协作方式
brew-parameter-recommender	本 Skill 确定方式和手法后，委托 recommender 生成具体参数
brew-diagnosis	如果上次 taste=bad，先调用 diagnosis 分析原因，再基于诊断结果调整本次推荐

边界与限制

• 冷萃 Coming Soon: 冷萃在引导冲煮中标注为 Coming Soon，但方案推荐仍可推荐冷萃（用户手动记录）
• 配方依赖: 推荐的 recipeName 必须在 brew_recipes 集合中存在
• 器具限制: 如果用户没有某种滤杯，不推荐依赖该滤杯特性的方案
• 新用户冷启动: 无历史数据时完全依赖知识库规则；推荐较保守的"中间参数"