MenuPilot 0.1.0__py3-none-any.whl

menupilot/agent/workflow.py

@@ -0,0 +1,1072 @@
+"""
+LangGraph 工作流定义 — 编排完整 POS 模板映射管线。
+
+节点顺序:
+  load_data → preprocess → analyze_schema → classify_tokens → normalize → validate → match → write_output
+
+每个节点读取上一个节点的输出，写入本节点的结果。任一步骤失败可捕获并进入错误处理。
+兼容无 langgraph 安装环境，提供 run_pipeline() 作为纯顺序回退方案。
+"""
+
+from typing import Any, Dict, List, Optional
+
+try:
+    from typing import NotRequired  # Python >= 3.11
+except ImportError:
+    from typing_extensions import NotRequired  # Python < 3.11
+
+import pandas as pd
+
+from menupilot.agent.matching_engine import generate_console_summary, generate_report as me_generate_report
+from menupilot.agent.matching_engine import match
+from menupilot.agent.rule_engine import (
+    check_row_completeness,
+    master_to_canonical,
+    template_to_canonical,
+    validate_tokens,
+)
+from menupilot.agent.schema_analyzer import analyze_from_dataframe
+from menupilot.agent.token_classifier import classify_from_dataframe, reset_cache as tc_reset_cache
+from menupilot.excel_io.excel_reader import read_master, read_template
+from menupilot.excel_io.excel_writer import write_result
+
+# ── 工作流状态键 ────────────────────────────────────────────────
+
+try:
+    from typing import TypedDict  # Python >= 3.8
+except ImportError:
+    from typing_extensions import TypedDict
+
+
+class PipelineState(TypedDict, total=False):
+    """TypedDict 版本的管线状态（所有字段可选，支持增量更新）。
+
+    total=False: 节点只需返回变化的字段，其余字段由 LangGraph 自动合并。
+    """
+
+    # ── 输入参数 ──
+    master_path: str
+    template_path: str
+    output_path: str
+    report_path: str
+    target_col: str
+    master_sheet: int
+    template_sheet: int
+
+    # ── 中间数据 ──
+    master_df: "pd.DataFrame"
+    template_df: "pd.DataFrame"
+    template_type: str
+    chowbus_rows: List[Dict[str, Any]]
+    schema_result: Dict[str, Any]
+    token_results: List[Dict[str, Any]]
+    master_canonical: List[Dict[str, Any]]
+    template_canonical: List[Dict[str, Any]]
+    validated_tokens: List[Dict[str, Any]]
+    match_results: List[Dict[str, Any]]
+    report: str
+    console_summary: str
+
+    # ── Human Review（用户审核介入）──
+    low_conf_rows: List[Dict[str, Any]]
+    human_review_result: Dict[str, Any]
+
+    # ── 错误信息 ──
+    error: str
+    error_step: str
+
+    # ── 统计 ──
+    api_call_count: int
+
+
+def make_pipeline_state(
+    master_path: str = "",
+    template_path: str = "",
+    output_path: str = "",
+    report_path: str = "",
+    target_col: str = "配料",
+    master_sheet: int = 0,
+    template_sheet: int = 0,
+) -> PipelineState:
+    """创建 PipelineState 并填充默认值。
+
+    Args:
+        master_path: 主数据表 Excel 路径。
+        template_path: POS 模板 Excel 路径。
+        output_path: 输出 Excel 路径。
+        report_path: 校验报告路径。
+        target_col: 目标列名。
+        master_sheet: 主数据表 Sheet 序号。
+        template_sheet: 模板表 Sheet 序号。
+
+    Returns:
+        初始化好的 PipelineState。
+    """
+    return PipelineState(
+        master_path=master_path,
+        template_path=template_path,
+        output_path=output_path,
+        report_path=report_path or output_path.replace(".xlsx", "_report.txt") if output_path else "",
+        target_col=target_col,
+        master_sheet=master_sheet,
+        template_sheet=template_sheet,
+        # 中间数据
+        master_df=None,
+        template_df=None,
+        template_type="standard",
+        chowbus_rows=None,
+        schema_result=None,
+        token_results=None,
+        master_canonical=None,
+        template_canonical=None,
+        validated_tokens=None,
+        match_results=None,
+        report="",
+        console_summary="",
+        # 错误信息
+        error=None,
+        error_step=None,
+        # 统计
+        api_call_count=0,
+    )
+
+
+# ── 管线节点 ────────────────────────────────────────────────────
+
+
+def step_load_data(state: PipelineState) -> PipelineState:
+    """Step 1: 读取主数据表和模板表 + 模板类型检测。"""
+    if state.get("error") is not None:
+        return state
+    try:
+        from menupilot.agent.template_preprocessor import detect_template_type, collect_chowbus_rows
+
+        state["master_df"] = read_master(state["master_path"], sheet_name=state["master_sheet"])
+
+        # 先以 header=None 读取模板原始数据，用于类型检测
+        from menupilot.excel_io.excel_reader import read_template_raw
+        raw_df = read_template_raw(state["template_path"], sheet_name=state["template_sheet"])
+        state["template_type"] = detect_template_type(raw_df)
+
+        if state["template_type"] == "chowbus":
+            # chowbus 类型：收集散列字段，跳过 Schema Analyzer
+            state["chowbus_rows"] = collect_chowbus_rows(raw_df)
+            state["template_df"] = None  # chowbus 不使用标准 template_df
+            # 目标列：chowbus 模板固定为 sop_code
+            if state["target_col"] == "配料":
+                state["target_col"] = "sop_code"
+        else:
+            # standard 类型：正常读取
+            state["template_df"] = read_template(
+                state["template_path"], sheet_name=state["template_sheet"]
+            )
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "load_data"
+    return state
+
+
+def step_preprocess(state: PipelineState) -> PipelineState:
+    """Step 1.5: chowbus 预处理 — 收集散列字段 → Token 分类 → 标准化为 Canonical。
+
+    对 standard 类型透明跳过。
+    """
+    if state.get("error") is not None or state["template_type"] != "chowbus":
+        return state
+    try:
+        from menupilot.agent.token_classifier import (
+            classify_single,
+            set_prompt_hook as tc_set_prompt_hook,
+        )
+        from menupilot.agent.rule_engine import master_to_canonical
+
+        # 注入静默钩子：UNKNOWN 不触发询问
+        tc_set_prompt_hook(lambda word, ctx, llm: {"action": "skip"})
+
+        # 对每行 composite_info 做 Token 分类
+        for row in state["chowbus_rows"]:
+            composite_str = row.get("composite_info", "")
+            if composite_str:
+                result = classify_single(composite_str)
+                row["_tokens"] = result.get("tokens", [])
+                row["_missing"] = result.get("missing", [])
+            else:
+                row["_tokens"] = []
+                row["_missing"] = []
+
+        # 还原静默钩子
+        tc_set_prompt_hook(None)
+
+        # 转换为 Canonical Schema 行
+        from menupilot.data.canonical_schema import CANONICAL_FIELDS
+        from menupilot.data.token_dict import normalize_token
+
+        canonical_rows = []
+        for row in state["chowbus_rows"]:
+            cr = {f: None for f in CANONICAL_FIELDS}
+            cr["product_name"] = str(row.get("product_name", "") or "").strip()
+            for token in row.get("_tokens", []):
+                ttype = token.get("type", "")
+                tvalue = token.get("value", "")
+                # 将 token 类型映射到 canonical 字段
+                type_map = {
+                    "茶底": "tea_base",
+                    "奶底": "milk_base",
+                    "糖度": "sugar",
+                    "温度": "temperature",
+                    "规格": "size",
+                }
+                cfield = type_map.get(ttype)
+                if cfield and cfield in cr:
+                    cr[cfield] = tvalue
+            # 补充：直接收集的中文值可能未被 token 词典识别，
+            # 但标准化层接受部分缺失，匹配引擎会处理通配
+            canonical_rows.append(cr)
+
+        state["template_canonical"] = canonical_rows
+
+        # 主数据标准化（复用现有逻辑）
+        state["master_canonical"] = master_to_canonical(state["master_df"])
+
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "preprocess"
+    return state
+
+
+def step_analyze_schema(state: PipelineState) -> PipelineState:
+    """Step 2: Schema Analyzer 分析模板字段语义。"""
+    if state.get("error") is not None:
+        return state
+    # chowbus 类型跳过
+    if state["template_type"] == "chowbus":
+        return state
+    try:
+        state["schema_result"] = analyze_from_dataframe(state["template_df"])
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "analyze_schema"
+    return state
+
+
+def step_classify_tokens(state: PipelineState) -> PipelineState:
+    """Step 3: Token Classifier 解析组合字段。"""
+    if state.get("error") is not None:
+        return state
+    if state["template_type"] == "chowbus":
+        return state
+    try:
+        composite_col = state["schema_result"].get("composite_col")
+        if composite_col and composite_col in state["template_df"].columns:
+            state["token_results"] = classify_from_dataframe(
+                state["template_df"], composite_col
+            )
+        else:
+            # 无组合字段，提供空 token 结果
+            state["token_results"] = [
+                {"tokens": [], "missing": []}
+                for _ in range(len(state["template_df"]))
+            ]
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "classify_tokens"
+    return state
+
+
+def step_normalize(state: PipelineState) -> PipelineState:
+    """Step 4: Rule Engine — 主数据 + 模板标准化为 Canonical Schema。"""
+    if state.get("error") is not None:
+        return state
+    if state["template_type"] == "chowbus":
+        return state  # chowbus 已在 preprocess 中完成标准化
+    try:
+        fm = state["schema_result"].get("field_mapping", {})
+        composite_col = state["schema_result"].get("composite_col", "")
+        state["master_canonical"] = master_to_canonical(state["master_df"])
+        state["template_canonical"] = template_to_canonical(
+            state["template_df"], fm, composite_col, state["token_results"]
+        )
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "normalize"
+    return state
+
+
+def step_validate(state: PipelineState) -> PipelineState:
+    """Step 5: Rule Engine — Token 验证 + 必要维度检查。"""
+    if state.get("error") is not None:
+        return state
+    if state["template_type"] == "chowbus":
+        return state  # chowbus 已在 preprocess 中完成验证
+    try:
+        state["validated_tokens"] = validate_tokens(state["token_results"])
+
+        # 检查每行完整度，在 canonical 行上标记
+        for i, trow in enumerate(state["template_canonical"]):
+            missing = check_row_completeness(trow)
+            if missing:
+                trow["_completeness_issues"] = missing
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "validate"
+    return state
+
+
+def step_match(state: PipelineState) -> PipelineState:
+    """Step 6: Matching Engine — 模板行 → 主数据行匹配。"""
+    if state.get("error") is not None:
+        return state
+    try:
+        # ── 断言：验证商品名称在管线各阶段未被改写 ──
+        _assert_product_name_integrity(state)
+        state["match_results"] = match(state["template_canonical"], state["master_canonical"])
+        # 提取低置信度行，供 human_review 审核
+        state["low_conf_rows"] = [
+            r for r in state["match_results"]
+            if r.get("confidence") == "LOW_CONFIDENCE"
+        ]
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "match"
+    return state
+
+
+def _assert_product_name_integrity(state: PipelineState) -> None:
+    """验证模板商品名称从原始读取到匹配前保持一致。
+
+    对比 state["template_df"]（原始 Excel 读取值）与
+    state["template_canonical"]（经 Schema Analyzer → Token Classifier → Rule Engine 处理后）
+    中的 product_name 字段。任何不一致都立即报错，防止 LLM 静默改写数据。
+    """
+    # chowbus 类型跳过（template_df 为 None，产品名来自预处理层）
+    if state["template_type"] == "chowbus" or state["template_df"] is None:
+        return
+
+    # 找到模板中映射为 product_name 的列
+    fm = state["schema_result"].get("field_mapping", {})
+    src_col = None
+    for tcol, cfield in fm.items():
+        if cfield == "product_name":
+            src_col = tcol
+            break
+
+    if src_col is None or src_col not in state["template_df"].columns:
+        return  # 无法验证，跳过
+
+    raw_names = state["template_df"][src_col].astype(str).str.strip().tolist()
+    canonical_names = [
+        str(r.get("product_name", "")).strip()
+        for r in state["template_canonical"]
+    ]
+
+    mismatches = []
+    for i, (raw, canonical) in enumerate(zip(raw_names, canonical_names)):
+        if raw != canonical:
+            mismatches.append(
+                f"  行 {i+1}: 原始='{raw}' -> 改写为='{canonical}'"
+            )
+
+    if mismatches:
+        raise ValueError(
+            f"商品名称在管线中被意外改写！{len(mismatches)} 行不一致:\n"
+            + "\n".join(mismatches[:10])
+            + ("\n  ..." if len(mismatches) > 10 else "")
+        )
+
+
+def step_write_output(state: PipelineState) -> PipelineState:
+    """Step 7: 写入结果 Excel + 校验报告。"""
+    if state.get("error") is not None:
+        return state
+    try:
+        # 构建结果 DataFrame
+        sops = [r.get("sop", "") for r in state["match_results"]]
+        confidences = [r.get("confidence", "") for r in state["match_results"]]
+
+        result_df = pd.DataFrame({
+            state["target_col"]: sops,
+            "匹配置信度": confidences,
+        })
+
+        write_result(
+            state["template_path"],
+            state["output_path"],
+            result_df,
+            target_col=state["target_col"],
+            header_row=1,
+            data_start_row=3 if state["template_type"] == "chowbus" else None,
+        )
+
+        # 生成用户友好摘要报告（文件 = 完整日志）
+        state["report"] = me_generate_report(state["match_results"])
+        state["console_summary"] = generate_console_summary(
+            state["match_results"], report_path=state["report_path"]
+        )
+
+        # 写入报告文件（完整日志）
+        from pathlib import Path
+        Path(state["report_path"]).write_text(state["report"], encoding="utf-8")
+    except Exception as e:
+        state["error"] = str(e)
+        state["error_step"] = "write_output"
+    return state
+
+
+# ── 路由函数 ────────────────────────────────────────────────────
+
+
+def route_after_load(state: PipelineState) -> str:
+    """load_data 之后的条件路由。
+
+    - 有错误 → 直接跳到 write_output
+    - chowbus 模板 → preprocess
+    - standard 模板 → analyze_schema
+    """
+    if state.get("error") is not None:
+        return "write_output"
+    if state.get("template_type") == "chowbus":
+        return "preprocess"
+    return "analyze_schema"
+
+
+def route_after_match(state: PipelineState) -> str:
+    """match 之后的条件路由。
+
+    - 有错误 → 直接跳到 write_output
+    - 有 LOW_CONFIDENCE 行 → human_review
+    - 全部 HIGH → write_output
+    """
+    if state.get("error") is not None:
+        return "write_output"
+    low_conf = state.get("low_conf_rows", [])
+    if low_conf:
+        return "human_review"
+    return "write_output"
+
+
+# ── Human Review 节点 ────────────────────────────────────────────
+
+
+def _compute_master_fingerprint(path: str) -> str:
+    """计算主数据文件的内容指纹（MD5 前 8 位）。"""
+    if not path:
+        return ""
+    import hashlib
+    with open(path, "rb") as f:
+        return hashlib.md5(f.read()).hexdigest()[:8]
+
+
+def step_human_review(state: PipelineState) -> PipelineState:
+    """Human Review 节点：应用用户审核决策。
+
+    前提：interrupt_before 挂起后，外部通过 update_state 注入
+    human_review_result。本节点读取该字段并应用到 match_results。
+
+    逻辑：
+      - accept/manual → 升级对应行为 HIGH，写入长期记忆
+      - permanent_skip → 写入 __SKIP__ 到长期记忆，保持 LOW_CONFIDENCE
+      - skip → 不写记忆，保持 LOW_CONFIDENCE
+    """
+    review_result = state.get("human_review_result", {})
+    if not review_result:
+        return state
+
+    decisions = review_result.get("decisions", [])
+    if not decisions:
+        return state
+
+    match_results = state.get("match_results", [])
+    template_canonical = state.get("template_canonical", [])
+    master_fingerprint = _compute_master_fingerprint(
+        str(state.get("master_path", ""))
+    )
+
+    from menupilot.data.memory import add_confirmed_mapping, build_confirmed_key
+    from menupilot.data.memory import get_confirmed_mapping
+
+    for decision in decisions:
+        idx = decision["row_index"]
+        action = decision["action"]
+
+        if idx < 0 or idx >= len(match_results):
+            continue
+
+        if action in ("accept", "manual"):
+            sop = decision.get("sop", "")
+            match_results[idx]["sop"] = sop
+            match_results[idx]["confidence"] = "HIGH"
+            # 写入长期记忆
+            if idx < len(template_canonical):
+                key = build_confirmed_key(master_fingerprint, template_canonical[idx])
+                add_confirmed_mapping(key, sop)
+
+        elif action == "permanent_skip":
+            if idx < len(template_canonical):
+                key = build_confirmed_key(master_fingerprint, template_canonical[idx])
+                add_confirmed_mapping(key, "__SKIP__")
+
+        # action == "skip"：不写记忆，保持 LOW_CONFIDENCE
+
+    state["match_results"] = match_results
+    # 清除 human_review_result，防止重复应用
+    state["human_review_result"] = {}
+    return state
+
+
+# ── DataFrame 序列化适配器 ────────────────────────────────────────
+
+
+class _DataFrameSerde:
+    """包装默认 serde，处理 DataFrame 的 msgpack 序列化。
+
+    将 DataFrame 转为 records 格式序列化，反序列化时还原。
+    保证 checkpointer 可以在 interrupt 后正确恢复状态。
+    """
+
+    def __init__(self):
+        from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+        self._inner = JsonPlusSerializer()
+
+    def dumps_typed(self, obj):
+        import pandas as pd
+        if isinstance(obj, pd.DataFrame):
+            wrapped = {"__dataframe__": obj.to_dict(orient="records")}
+            # 也保存列名（空 DataFrame 的 records 为空列表）
+            wrapped["__columns__"] = list(obj.columns)
+            return self._inner.dumps_typed(wrapped)
+        return self._inner.dumps_typed(obj)
+
+    def loads_typed(self, data):
+        import pandas as pd
+        result = self._inner.loads_typed(data)
+        if isinstance(result, dict) and "__dataframe__" in result:
+            return pd.DataFrame(
+                result["__dataframe__"],
+                columns=result.get("__columns__"),
+            )
+        return result
+
+
+# ── LangGraph 工作流 ─────────────────────────────────────────────
+
+
+def build_graph():
+    """构建 LangGraph StateGraph（条件路由 + checkpoint + interrupt）。
+
+    需要 langgraph 已安装。返回编译后的 app 对象。
+
+    Raises:
+        ImportError: langgraph 未安装。
+    """
+    from langgraph.checkpoint.memory import MemorySaver
+    from langgraph.graph import END, StateGraph
+
+    graph = StateGraph(PipelineState)
+
+    # 注册所有节点
+    graph.add_node("load_data", step_load_data)
+    graph.add_node("preprocess", step_preprocess)
+    graph.add_node("analyze_schema", step_analyze_schema)
+    graph.add_node("classify_tokens", step_classify_tokens)
+    graph.add_node("normalize", step_normalize)
+    graph.add_node("validate", step_validate)
+    graph.add_node("match", step_match)
+    graph.add_node("human_review", step_human_review)
+    graph.add_node("write_output", step_write_output)
+
+    graph.set_entry_point("load_data")
+
+    # ── 条件边：load_data 之后根据模板类型 + 错误状态分流 ──
+    graph.add_conditional_edges(
+        "load_data",
+        route_after_load,
+        {
+            "preprocess": "preprocess",
+            "analyze_schema": "analyze_schema",
+            "write_output": "write_output",
+        },
+    )
+
+    # ── chowbus：preprocess → 直接 match ──
+    graph.add_edge("preprocess", "match")
+
+    # ── standard：标准管线链 ──
+    graph.add_edge("analyze_schema", "classify_tokens")
+    graph.add_edge("classify_tokens", "normalize")
+    graph.add_edge("normalize", "validate")
+    graph.add_edge("validate", "match")
+
+    # ── 条件边：match 之后根据低置信度行数分流 ──
+    graph.add_conditional_edges(
+        "match",
+        route_after_match,
+        {
+            "human_review": "human_review",
+            "write_output": "write_output",
+        },
+    )
+
+    # ── human_review 后直接输出 ──
+    graph.add_edge("human_review", "write_output")
+    graph.add_edge("write_output", END)
+
+    # ── 编译 + checkpoint + interrupt ──
+    checkpointer = MemorySaver(serde=_DataFrameSerde())
+    return graph.compile(checkpointer=checkpointer)
+
+
+# ── 公开 API ────────────────────────────────────────────────────
+
+
+def run_pipeline(
+    master_path: str,
+    template_path: str,
+    output_path: str,
+    report_path: Optional[str] = None,
+    target_col: str = "配料",
+    master_sheet: int = 0,
+    template_sheet: int = 0,
+    use_langgraph: bool = True,
+) -> PipelineState:
+    """运行完整的 POS 模板映射管线。
+
+    这是工作流的主入口。默认使用纯顺序执行（不依赖 langgraph）。
+    传入 use_langgraph=True 可启用 LangGraph 编排。
+
+    Args:
+        master_path: 主数据表 Excel 路径。
+        template_path: POS 模板 Excel 路径。
+        output_path: 输出 Excel 路径。
+        report_path: 校验报告路径（默认 output_path 同目录 + _report.txt）。
+        target_col: 需要填充的目标列名，默认 "配料"。
+        master_sheet: 主数据表 Sheet 序号（从 0 开始），默认 0。
+        template_sheet: 模板表 Sheet 序号（从 0 开始），默认 0。
+        use_langgraph: 是否使用 LangGraph 编排（需安装 langgraph）。
+
+    Returns:
+        PipelineState，包含所有中间数据和最终结果。
+        检查 state.get("error") is not None 判断是否成功。
+
+    Raises:
+        ImportError: use_langgraph=True 但 langgraph 未安装。
+    """
+    state = make_pipeline_state(
+        master_path=master_path,
+        template_path=template_path,
+        output_path=output_path,
+        report_path=report_path,
+        target_col=target_col,
+        master_sheet=master_sheet,
+        template_sheet=template_sheet,
+    )
+
+    # 重置 API 调用计数器 + 会话新增 token 追踪
+    from menupilot.agent.schema_analyzer import reset_api_call_count as _sa_reset
+    from menupilot.agent.token_classifier import reset_api_call_count as _tc_reset
+    from menupilot.data.memory import reset_new_tokens as _reset_new_tokens
+    _sa_reset()
+    _tc_reset()
+    _reset_new_tokens()
+
+    if use_langgraph:
+        import uuid
+        app = build_graph()
+        config = {"configurable": {"thread_id": str(uuid.uuid4())}}
+        result = app.invoke(state, config)
+
+        # Human Review 已禁用：输出报告后直接结束
+        # （保留 interrupt/resume 代码，需要时取消注释即可恢复）
+        #
+        # snapshot = app.get_state(config)
+        # if snapshot.next and "human_review" in snapshot.next:
+        #     snap_state = snapshot.values
+        #     low_conf = snap_state.get("low_conf_rows", [])
+        #     master_fp = _compute_master_fingerprint(
+        #         str(snap_state.get("master_path", ""))
+        #     )
+        #     from menupilot.cli.human_review import run_review
+        #     review_result = run_review(low_conf, master_fp)
+        #     app.update_state(config, {"human_review_result": review_result})
+        #     result = app.invoke(None, config)
+
+        # 收集 API 调用统计
+        from menupilot.agent.schema_analyzer import get_api_call_count as _sa_count
+        from menupilot.agent.token_classifier import get_api_call_count as _tc_count
+        result["api_call_count"] = _sa_count() + _tc_count()
+        return result
+
+    # 纯顺序执行
+    steps = [
+        ("load_data", step_load_data),
+        ("preprocess", step_preprocess),
+        ("analyze_schema", step_analyze_schema),
+        ("classify_tokens", step_classify_tokens),
+        ("normalize", step_normalize),
+        ("validate", step_validate),
+        ("match", step_match),
+    ]
+
+    for step_name, step_fn in steps:
+        step_fn(state)
+        if state.get("error") is not None:
+            break
+
+    # Human Review 已禁用：输出报告后直接结束
+    # （保留代码，需要时取消注释即可恢复）
+    #
+    # if not state.get("error"):
+    #     low_conf_rows = [
+    #         r for r in state.get("match_results", [])
+    #         if r.get("confidence") == "LOW_CONFIDENCE"
+    #     ]
+    #     if low_conf_rows:
+    #         from menupilot.cli.human_review import run_review
+    #         master_fp = _compute_master_fingerprint(
+    #             str(state.get("master_path", ""))
+    #         )
+    #         review_result = run_review(low_conf_rows, master_fp)
+    #         state["human_review_result"] = review_result
+    #         step_human_review(state)
+
+    # 输出
+    if not state.get("error"):
+        step_write_output(state)
+
+    # 收集 API 调用统计
+    from menupilot.agent.schema_analyzer import get_api_call_count as _sa_count
+    from menupilot.agent.token_classifier import get_api_call_count as _tc_count
+    state["api_call_count"] = _sa_count() + _tc_count()
+
+    return state
+
+
+# ── 自测 ────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import os
+    import tempfile
+
+    os.environ["USE_MOCK_LLM"] = "1"
+    import importlib
+
+    importlib.reload(__import__("config"))
+
+    passed = 0
+    failed = 0
+
+    def check(condition, msg):
+        global passed, failed
+        if condition:
+            passed += 1
+            print(f"  PASS  {msg}")
+        else:
+            failed += 1
+            print(f"  FAIL  {msg}")
+
+    print("=== Workflow 自测（Mock LLM 模式）===\n")
+
+    tmpdir = tempfile.mkdtemp()
+    master_path = os.path.join(tmpdir, "master.xlsx")
+    template_path = os.path.join(tmpdir, "template.xlsx")
+    output_path = os.path.join(tmpdir, "output.xlsx")
+
+    # ── 覆盖 Mock 响应以匹配测试数据 ──
+    from menupilot import config as cfg
+
+    original_mock_schema = dict(cfg.MOCK_SCHEMA_RESPONSE)
+    tc_reset_cache()
+
+    # ── 准备测试用主数据表和模板表 ──
+    pd.DataFrame({
+        "品名": ["浅浅清茶", "浅浅清茶", "黑糖波波牛乳", "珍珠奶茶"],
+        "杯型": ["中杯", "中杯", "大杯", "中杯"],
+        "奶底": ["牛奶", "牛奶", "", "椰乳"],
+        "做法": ["少冰", "去冰", "正常冰", "热"],
+        "糖": ["七分糖", "标准糖", "标准糖", "无糖"],
+        "SOP": [
+            "T240、B30/80、S4",
+            "T265、B30/105、S5",
+            "T200、B50/100、S5",
+            "T180、B40/80、S2",
+        ],
+    }).to_excel(master_path, index=False)
+
+    pd.DataFrame({
+        "菜品名称": ["浅浅清茶", "浅浅清茶", "黑糖波波牛乳"],
+        "规格": ["中杯", "中杯", "大杯"],
+        "口味做法组合": [
+            "牛奶, 少冰, 七分糖",
+            "牛奶, 去冰, 标准糖",
+            "正常冰, 标准糖",
+        ],
+        "配料": ["", "", ""],
+    }).to_excel(template_path, index=False)
+
+    try:
+        # ── 1. 完整管线运行 ──
+        print("1. 完整管线 run_pipeline()")
+        state = run_pipeline(master_path, template_path, output_path)
+
+        check(not state.get("error") is not None, f"管线无错误（错误: {state["error"]}）")
+        check(state["master_df"] is not None, "master_df 已加载")
+        check(state["template_df"] is not None, "template_df 已加载")
+        check(state["schema_result"] is not None, "schema_result 已生成")
+        check(state["token_results"] is not None, "token_results 已生成")
+        check(state["master_canonical"] is not None, "master_canonical 已转换")
+        check(state["template_canonical"] is not None, "template_canonical 已转换")
+        check(state["validated_tokens"] is not None, "validated_tokens 已验证")
+        check(state["match_results"] is not None, "match_results 已生成")
+        check(len(state["match_results"]) == 3, f"3 条匹配结果（实际 {len(state["match_results"])}）")
+        print()
+
+        # ── 2. 匹配结果验证 ──
+        print("2. 匹配结果验证")
+        check(
+            state["match_results"][0]["confidence"] == "HIGH",
+            f"第 1 行 HIGH（实际 {state["match_results"][0]['confidence']}）",
+        )
+        check(
+            state["match_results"][1]["confidence"] == "HIGH",
+            f"第 2 行 HIGH（实际 {state["match_results"][1]['confidence']}）",
+        )
+        check(
+            state["match_results"][2]["product_score"] >= 90,
+            f"第 3 行商品名分数 ≥ 90（实际 {state["match_results"][2]['product_score']}）",
+        )
+        print()
+
+        # ── 3. 输出文件验证 ──
+        print("3. 输出文件验证")
+        check(os.path.exists(output_path), "输出 Excel 文件已生成")
+        report_path = output_path.replace(".xlsx", "_report.txt")
+        check(os.path.exists(report_path), "校验报告已生成")
+
+        # 读取输出 Excel 验证内容
+        df_out = pd.read_excel(output_path)
+        check("配料" in df_out.columns, "输出包含 '配料' 列")
+        check("匹配置信度" in df_out.columns, "输出包含 '匹配置信度' 列")
+        check(
+            df_out.iloc[0]["配料"] == "T240、B30/80、S4",
+            f"第 1 行 SOP 正确（实际 {df_out.iloc[0]['配料']}）",
+        )
+
+        # 读取报告验证
+        report_text = open(report_path, encoding="utf-8").read()
+        check("本次映射完成" in report_text, "报告包含标题")
+        print()
+
+        # ── 4. 多候选精确匹配 ──
+        print("4. 多候选精确属性选择")
+        tc_reset_cache()
+
+        # 同产品名三个主数据行（不同属性），应精确选择对的属性
+        pd.DataFrame({
+            "品名": ["测试茶", "测试茶", "测试茶"],
+            "杯型": ["大杯", "中杯", "小杯"],
+            "奶底": ["牛奶", "燕麦奶", ""],
+            "做法": ["正常冰", "少冰", "去冰"],
+            "糖": ["全糖", "七分糖", "三分糖"],
+            "SOP": ["SOP-A", "SOP-B", "SOP-C"],
+        }).to_excel(master_path, index=False)
+
+        pd.DataFrame({
+            "菜品名称": ["测试茶"],
+            "规格": ["中杯"],
+            "口味做法组合": ["燕麦奶, 少冰, 七分糖"],
+            "配料": [""],
+        }).to_excel(template_path, index=False)
+
+        state2 = run_pipeline(master_path, template_path, output_path)
+        check(not state2.get("error") is not None, "二次运行无错误")
+        check(len(state2["match_results"]) == 1, "1 条匹配")
+        check(
+            state2["match_results"][0]["sop"] == "SOP-B",
+            f"选中 SOP-B（中杯/燕麦奶/少冰/七分糖）（实际 {state2["match_results"][0]['sop']}）",
+        )
+        check(state2["match_results"][0]["confidence"] == "HIGH", "置信度 HIGH")
+        print()
+
+        # ── 5. 错误处理：文件不存在 ──
+        print("5. 错误处理：文件不存在")
+        state_err = run_pipeline(
+            "不存在的文件.xlsx", template_path, output_path
+        )
+        check(state_err.get("error") is not None, "文件不存在 → has_error=True")
+        check(state_err["error_step"] == "load_data", "错误发生在 load_data 步骤")
+        print()
+
+        # ── 6. 报告内容验证 ──
+        print("6. 报告内容")
+        check(
+            "高置信匹配" in state["report"],
+            "报告包含高置信匹配统计",
+        )
+        check(
+            "需要确认" in state["report"] or "高置信匹配" in state["report"],
+            "报告包含置信度分级",
+        )
+        print()
+
+        # ── 7. 无匹配商品 → LOW_CONFIDENCE ──
+        print("7. 无匹配商品 → LOW_CONFIDENCE")
+        tc_reset_cache()
+        pd.DataFrame({
+            "品名": ["产品A"],
+            "杯型": ["中杯"],
+            "奶底": [""],
+            "做法": ["正常冰"],
+            "糖": ["标准糖"],
+            "SOP": ["SOP-X"],
+        }).to_excel(master_path, index=False)
+
+        pd.DataFrame({
+            "菜品名称": ["完全不存在的商品"],
+            "规格": ["中杯"],
+            "口味做法组合": ["正常冰, 标准糖"],
+            "配料": [""],
+        }).to_excel(template_path, index=False)
+
+        state3 = run_pipeline(master_path, template_path, output_path)
+        check(not state3.get("error") is not None, "无错误")
+        check(len(state3["match_results"]) == 1, "1 条结果")
+        check(
+            state3["match_results"][0]["confidence"] == "LOW_CONFIDENCE",
+            f"无匹配 → LOW_CONFIDENCE（实际 {state3["match_results"][0]['confidence']}）",
+        )
+        check(
+            state3["match_results"][0]["match_type"] == "best_guess",
+            f"匹配类型 best_guess（实际 {state3["match_results"][0]['match_type']}）",
+        )
+        print()
+
+        # ── 8. LangGraph 路径和顺序路径结果一致 ──
+        print("8. LangGraph 路径和顺序路径结果一致")
+        # 重新写入最初的标准测试数据
+        pd.DataFrame({
+            "品名": ["浅浅清茶", "浅浅清茶", "黑糖波波牛乳", "珍珠奶茶"],
+            "杯型": ["中杯", "中杯", "大杯", "中杯"],
+            "奶底": ["牛奶", "牛奶", "", "椰乳"],
+            "做法": ["少冰", "去冰", "正常冰", "热"],
+            "糖": ["七分糖", "标准糖", "标准糖", "无糖"],
+            "SOP": [
+                "T240、B30/80、S4", "T265、B30/105、S5",
+                "T200、B50/100、S5", "T180、B40/80、S2",
+            ],
+        }).to_excel(master_path, index=False)
+
+        pd.DataFrame({
+            "菜品名称": ["浅浅清茶", "浅浅清茶", "黑糖波波牛乳"],
+            "规格": ["中杯", "中杯", "大杯"],
+            "口味做法组合": [
+                "牛奶, 少冰, 七分糖",
+                "牛奶, 去冰, 标准糖",
+                "正常冰, 标准糖",
+            ],
+            "配料": ["", "", ""],
+        }).to_excel(template_path, index=False)
+        tc_reset_cache()
+
+        # 顺序执行
+        state_seq = run_pipeline(master_path, template_path, output_path, use_langgraph=False)
+        check(state_seq.get("error") is None, "顺序执行无错误")
+        seq_sops = [r.get("sop", "") for r in state_seq["match_results"]]
+
+        # LangGraph 执行
+        state_lg = run_pipeline(master_path, template_path, output_path, use_langgraph=True)
+        check(state_lg.get("error") is None, "LangGraph 执行无错误")
+
+        if state_lg.get("error") is None:
+            lg_sops = [r.get("sop", "") for r in state_lg["match_results"]]
+            lg_confs = [r.get("confidence", "") for r in state_lg["match_results"]]
+            seq_confs = [r.get("confidence", "") for r in state_seq["match_results"]]
+            check(seq_sops == lg_sops, f"SOP 结果一致（顺序={len(seq_sops)}, LG={len(lg_sops)}）")
+            check(seq_confs == lg_confs, "置信度结果一致")
+            check(len(state_seq["match_results"]) == len(state_lg["match_results"]),
+                  f"匹配行数一致（{len(state_seq['match_results'])}）")
+        print()
+
+        # ── 9. 路由函数单元测试 ──
+        print("9. 路由函数单元测试")
+        check(route_after_load({"error": "test error"}) == "write_output",
+              "有 error → write_output")
+        check(route_after_load({"template_type": "chowbus"}) == "preprocess",
+              "chowbus → preprocess")
+        check(route_after_load({"template_type": "standard"}) == "analyze_schema",
+              "standard → analyze_schema")
+        check(route_after_load({}) == "analyze_schema",
+              "无 template_type 默认 → analyze_schema")
+
+        check(route_after_match({"error": "test"}) == "write_output",
+              "match 有 error → write_output")
+        check(route_after_match({"low_conf_rows": [{"confidence": "LOW_CONFIDENCE"}]}) == "human_review",
+              "有低置信度行 → human_review")
+        check(route_after_match({"low_conf_rows": []}) == "write_output",
+              "无低置信度行 → write_output")
+        check(route_after_match({}) == "write_output",
+              "low_conf_rows 不存在 → write_output")
+        print()
+
+        # ── 10. step_human_review 单元测试 ──
+        print("10. step_human_review 单元测试")
+        # 10a: 空 review_result → 无操作
+        s10a = {"human_review_result": {}, "match_results": [{"sop": "OLD", "confidence": "LOW_CONFIDENCE"}]}
+        step_human_review(s10a)
+        check(s10a["match_results"][0]["sop"] == "OLD", "空 review → 不变")
+
+        # 10b: accept 升级为 HIGH
+        s10b = {
+            "human_review_result": {"decisions": [{"row_index": 0, "action": "accept", "sop": "NEW"}]},
+            "match_results": [{"sop": "OLD", "confidence": "LOW_CONFIDENCE"}],
+            "template_canonical": [{"product_name": "测试"}],
+            "master_path": master_path,
+        }
+        step_human_review(s10b)
+        check(s10b["match_results"][0]["confidence"] == "HIGH", "accept → HIGH")
+        check(s10b["match_results"][0]["sop"] == "NEW", "accept → sop=NEW")
+
+        # 10c: manual 手动输入
+        s10c = {
+            "human_review_result": {"decisions": [{"row_index": 0, "action": "manual", "sop": "手动SOP"}]},
+            "match_results": [{"sop": "OLD", "confidence": "LOW_CONFIDENCE"}],
+            "template_canonical": [{"product_name": "测试"}],
+            "master_path": master_path,
+        }
+        step_human_review(s10c)
+        check(s10c["match_results"][0]["confidence"] == "HIGH", "manual → HIGH")
+        check(s10c["match_results"][0]["sop"] == "手动SOP", "manual → sop=手动SOP")
+
+        # 10d: skip 保持 LOW_CONFIDENCE
+        s10d = {
+            "human_review_result": {"decisions": [{"row_index": 0, "action": "skip"}]},
+            "match_results": [{"sop": "OLD", "confidence": "LOW_CONFIDENCE"}],
+            "template_canonical": [],
+            "master_path": "",
+        }
+        step_human_review(s10d)
+        check(s10d["match_results"][0]["confidence"] == "LOW_CONFIDENCE", "skip → 保持 LOW_CONFIDENCE")
+
+        # 10e: permanent_skip 写入 __SKIP__
+        s10e = {
+            "human_review_result": {"decisions": [{"row_index": 0, "action": "permanent_skip"}]},
+            "match_results": [{"sop": "OLD", "confidence": "LOW_CONFIDENCE"}],
+            "template_canonical": [{"product_name": "永久跳过商品"}],
+            "master_path": master_path,
+        }
+        step_human_review(s10e)
+        check(s10e["match_results"][0]["confidence"] == "LOW_CONFIDENCE",
+              "permanent_skip → 保持 LOW_CONFIDENCE（标记在 memory 中）")
+        print()
+
+    finally:
+        # 清理临时文件
+        for f in [master_path, template_path, output_path,
+                  output_path.replace(".xlsx", "_report.txt")]:
+            if os.path.exists(f):
+                os.remove(f)
+        os.rmdir(tmpdir)
+
+    # 还原 Mock 设置
+    cfg.MOCK_SCHEMA_RESPONSE = original_mock_schema
+    tc_reset_cache()
+
+    print(f"=== 结果: {passed} passed, {failed} failed ===")