Guardian Engine

Guardian Engine — API 与 MCP 集成指南

在 Agent 的生成→验证循环中充当确定性判定器。 你的 LLM 编写食谱；Guardian 负责判定。Guardian Engine 能在食谱进入锅中之前，发现虚构的温度、遗漏的技巧、错误的食材和不可能的烹饪步骤，并返回可供机器执行的修补方案，让你的 Agent 精确修正问题。食谱是第一个垂直领域——同样的确定性方法也适用于任何需要确保正确性的流程性领域。

为什么要用判定器，而不是再加一个 LLM 批评环节？ LLM 的批评结果只是一个样本——每次运行都会以不同方式遗漏问题。Guardian 的符号引擎能够提供生成式模型在结构上无法做到的保证：

• 穷尽式检查——每次调用都会评估所有规则，而不是抽样评估部分规则。
• 可认证的否定结论——“未检测到欧盟附件 II 过敏原来源”是 LLM 无法做出的缺失声明。
• 可重放的判定结果——相同输入 + 相同规范 + 相同知识库版本 → 输出逐字节一致。每个响应都会固定 kb_version_hash 和 master_hash，因此任何判定结果都可作为审计记录复现。
• 可供机器执行的修复——发现的问题附带结构化的 patches（而且 fix_recipe 可以确定性地应用这些修补方案）；其余部分由你的 Agent 编写，再重新验证。
• 使用你自己的规范——通过 master_json，根据你自己的家用食谱或 SOP 进行验证，而不只是使用内置目录。

端点：https://api.kaimeilabs.dev/mcp
传输方式：Streamable HTTP（MCP）
身份验证：无——早期访问期间免费（适用合理使用政策）

---

⚠️ 安全与责任声明

Guardian Engine 是一款自动化的信息类食谱验证工具。它不是食品安全、医疗、营养或法规合规领域的权威机构，其输出不构成专业建议。

• 不保证过敏原信息准确。 过敏原警告（包括 check_safety、check_allergens，以及每条验证响应中的 allergens 字段）来自自动化知识库，可能不完整或有误。PASSED 判定或空的过敏原列表不代表食谱不含任何过敏原，也不代表任何个人食用后都安全。切勿依赖 Guardian 判断某种食物对食物过敏或不耐受者是否安全——务必对照实际食材／产品标签进行核实，并咨询合格的专业人士。
• 饮食及宗教相关声明不等同于认证。 verify_dietary_claim 的结果（纯素、素食、无麸质、无乳制品、无坚果、清真、犹太洁食）是自动进行的食材级检查，不能替代公认的饮食或宗教权威机构认证。
• 修复后的食谱并未获得安全认证。 在烹饪、供应或发布前，必须由人工审核 fix_recipe 的输出；过敏原检查结果绝不会自动修复，修复后的食谱仍可能无法通过验证。
• 烹饪安全检查结果仅供参考，不得替代权威指导（例如 USDA、EU FIC 或当地食品安全主管部门的指导）。
• 不提供保证。 本服务按“现状”提供，不附带任何形式的保证。在法律允许的最大范围内，对于因使用 Guardian 输出或依赖其输出而导致的任何损失、伤害或损害，Kaimei Labs 不承担任何责任。

使用 API 即表示接受完整的服务条款（免责声明、责任限制、赔偿条款）。

---

连接你的 Agent

Guardian 是托管式 MCP 服务。无需安装、无需 API 密钥、无需 Docker。选择你的客户端并粘贴配置。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "guardian": {
      "url": "https://api.kaimeilabs.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

重启 Claude Desktop。提问：“列出 Guardian Engine 中可用的菜品”，以确认连接。

Cursor

打开设置 → MCP 服务 → 添加新的 MCP 服务，然后粘贴：

{
  "guardian": {
    "url": "https://api.kaimeilabs.dev/mcp",
    "transport": "streamable-http"
  }
}

VS Code（GitHub Copilot）

将以下内容添加到你的 .vscode/mcp.json（或用户 settings.json 中的 "mcp" 下）：

{
  "servers": {
    "guardian": {
      "type": "http",
      "url": "https://api.kaimeilabs.dev/mcp"
    }
  }
}

Windsurf

将以下内容添加到你的 Windsurf MCP 配置中：

{
  "mcpServers": {
    "guardian": {
      "serverUrl": "https://api.kaimeilabs.dev/mcp"
    }
  }
}

Smithery（一键安装）

— 自动配置 Claude Desktop、Cursor 等客户端。

警告

Smithery 代理的限制： 默认的 Smithery 代理 URL（guardian-engine--kaimeilabs.run.tools）不支持 Streaming HTTP，且会静默失败。安装后必须编辑 MCP 配置，改用直连端点：https://api.kaimeilabs.dev/mcp。

Glama.ai

Guardian Engine 也已列入 Glama.ai — 可从 Glama 目录发现并连接 MCP 服务。

任意 MCP 客户端（Python SDK）

import asyncio
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamable_http_client
from httpx import AsyncClient

async def main():
    async with AsyncClient(timeout=30.0) as http:
        async with streamable_http_client("https://api.kaimeilabs.dev/mcp", http_client=http) as streams:
            read_stream, write_stream, _ = streams
            async with ClientSession(read_stream, write_stream) as session:
                await session.initialize()
                result = await session.call_tool("list_dishes", arguments={"cuisine_filter": "french"})
                print(result)

asyncio.run(main())

pip install mcp>=1.2.1 httpx>=0.27.0

---

工具

MCP 服务提供七种工具。verify_recipe 是核心流程；其余工具支持“比较 → 验证 → 修复”循环，以及不依赖主配方的安全检查。

verify_recipe

根据 Guardian 主规范验证候选食谱。返回一份结构化报告，给出严格的 PASSED／FAILED 判定（不含分数）和详细的问题发现，每项均注明违反的规则。判定由策略驱动：任何 CRITICAL 级问题都会导致食谱未通过；WARNING 超过 5 项也会导致未通过。

参数	类型	必填	描述
dish_name	string	是*	菜肴名称或别名（例如 "carbonara"、"rendang"、"kung-pao"、"bourguignon"）。dish 可作为向后兼容的别名使用。*提供 master_json 时可选
candidate_json	string | object	是	完整食谱的 JSON 格式——参见 schema.md。最大 500 KB
master_json	string | object	否	使用你自己的主规范——用于验证的自家食谱／SOP，采用与目录主规范相同的架构。此项会绕过内置目录；响应会通过 master_hash（sha256）和 master_source: "user" 标明你的规范
original_prompt	string	否	生成该食谱的用户原始请求
response_format	string	否	"text"（默认）或 "json"。在 Agent 自我修正循环中使用 "json"，以获取可供机器处理的修补项
session_id	string	否	跟踪 Agent 在多次尝试中的改进循环
operator_id	string	否	写入验证日志和合规记录的审计标识符（字母、数字、连字符；最长 64 个字符）

提示 — 提供原始提示词以获取个性化反馈： 提供 original_prompt（例如 "制作一道辛辣的纯素 rendang"）后，Guardian 会根据用户声明的饮食需求和口味偏好匹配问题发现，并启用针对受众的安全检查（例如，标记婴儿食谱中的蜂蜜、孕妇食谱中的生鸡蛋）。不提供时，Guardian 仍会返回完整判定和所有问题发现。

菜肴未知？ 如果目录中没有该菜肴，UNKNOWN_DISH 错误会包含一个 safety_fallback 判定——独立于主规范的安全层（禽肉温度检查 + 过敏原扫描）仍会运行，因此你的 Agent 始终能获得确定的结果。

字段用途： issue 是供程序处理的机器可读代码——不要向最终用户展示。面向用户的字段请使用 title 和 suggested_correction。

fix_recipe

根据主规范确定性地修复候选食谱。该工具会先进行验证，再应用符号引擎生成的所有可由机器执行的修补项（缺失食材、用量、温度、时长、烹饪介质、替换项），然后重新验证。不会使用 LLM——修复是根据候选内容和规则集确定性执行的。

参数	类型	必填	描述
dish_name	string	是*	要依据其主规范进行修复的菜肴（接受 dish 别名）。*提供 master_json 时可选
candidate_json	string | object	是	与 verify_recipe 使用相同的架构
master_json	string | object	否	用于修复的自备主规范；修补项（包括 suggested_step 模板）依据你的规范生成
original_prompt	string	否	仅用于验证期间识别安全上下文
response_format	string	否	"text"（默认）或 "json"——使用 "json" 可获取完整的 fixed_recipe 对象

响应会报告 verdict_before → verdict_after、fully_fixed、patches_applied、patches_skipped、unresolved_findings 和 fixed_recipe。需要食谱撰写判断的更改（添加完整烹饪阶段、改写说明、重新平衡比例）不会自动应用——这些更改会列在 patches_skipped 下；其中的 add_step 修补项会附带来自主规范的 suggested_step 模板，供你的 Agent 用食谱本身的风格撰写并重新验证。**过敏原问题永远不会自动修复。**不要假定修复后的食谱一定能通过——请检查 verdict_after。

list_dishes

列出 Guardian 可供核验的所有主配方，并提供丰富的元数据（slug、标题、菜系、地区、别名、复杂度）。

参数	类型	必填	描述
cuisine_filter	string	否	不区分大小写的菜系筛选条件（例如 "french"、"chinese"、"thai"）

get_master

返回某道菜的规范主配方——纯知识库查询，不使用 LLM。支持先比较再核验的工作流：获取主配方，将其与您的配方进行差异比较，然后调用 verify_recipe，而不是盲目核验。默认情况下，主配方内容完全透明：精确的温度、时间以及 EU FIC 1169/2011 过敏原代码均按原样返回。自带主配方时，它也可作为 master_json 架构的实时参考。

参数	类型	必填	描述
dish_name	string	是	菜品名称或别名
response_format	string	否	"json"（默认）或 "text"

check_safety

适用于任意配方、独立于主配方的安全检查——无需解析菜品或提供主配方规范。检查禽肉内部温度是否安全（≥ 74 °C），并扫描所有食材是否属于 14 类 EU FIC 1169/2011 附录 II 过敏原。verify_recipe 没有匹配的主配方时可使用此工具。

参数	类型	必填	描述
candidate_json	string	是	完整的候选配方 JSON 字符串

check_allergens

检查食材列表中是否含有 EU FIC 1169/2011 过敏原，并提供详细的审计追踪，将每种食材映射到其附录 II 过敏原组（包含条目编号和标签）。

参数	类型	必填	描述
ingredients	list[string]	是	食材名称，可为自由形式或规范名称（例如 ["butter", "wheat_flour", "peanut_butter"]）
restrictions	list[string]	否	根据用户限制进行检查的过敏原组 ID：gluten、crustaceans、eggs、fish、peanuts、soy、dairy、tree_nuts、celery、mustard、sesame、sulphites、lupin、molluscs
dish_name	string	否	报告上下文
check_all_eu_allergens	boolean	否	true 会扫描全部 14 类附录 II 过敏原，不受 restrictions 限制——适用于标签式的“申报所有检出的过敏原”检查
response_format	string	否	"text"（默认）或 "json"

verify_dietary_claim

核验配方是否符合某项饮食声明，并返回结构化判定结果，指出具体不符合要求的食材——绝不使用含糊的转述。

参数	类型	必填	描述
candidate_json	string	是	配方 JSON（仅需包含食材列表）
claim	string	是	可选值：vegan、vegetarian、gluten_free、dairy_free、nut_free、halal、kosher
response_format	string	否	"text"（默认）或 "json"

---

自带主版本（master_json）

内置目录是一份参考库——生产环境的主要模式是根据你自己的规范进行验证：家常食谱、连锁品牌的 SOP 或测试厨房的标准版本。将 master_json 传给 verify_recipe 或 fix_recipe（架构与目录中的主版本相同——调用 get_master 获取实时示例：title、serves、ingredients[]、包含替代品等级的 required_ingredients[]，以及包含技法／温度／时长／介质的 steps[]）。

• 提供 master_json 时，可以省略 dish_name，并且会完全绕过目录——候选食谱将根据你的规范进行检查。
• 响应会固定该规范：master_source: "user" 和 master_hash（对规范化后的主版本计算 sha256）。结合 kb_version_hash，可使每个判定都可重现：任何持有相同候选食谱、规范和知识库版本的人，都能复现逐字节相同的结果。
• 格式错误的主版本会返回结构化的 INVALID_MASTER 错误，而非服务端错误。最大 500 KB。

---

可用食谱（161 道菜，5 个地区）

地区	菜品
欧洲	巴斯克芝士蛋糕 · 勃艮第炖牛肉 · 惠灵顿牛排 · 奶油南瓜汤 · 奶酪胡椒意面 · 卡普雷塞沙拉 · 法式豆焖肉 · 奶酪舒芙蕾 · 意式猎人鸡 · 马沙拉鸡 · 柠檬酸豆鸡 · 巧克力舒芙蕾 · 油封鸭 · 莱茵白葡萄酒炖公鸡 · 红酒炖公鸡 · 焦糖布丁 · 可丽饼 · 阿尔弗雷多宽面 · 炸鱼薯条 · 佛罗伦萨饼干 · 巴里佛卡夏 · 法式煎蛋卷 · 法式洋葱汤 · 意式煎蛋饼 · 西班牙冷汤 · 土豆团子 · 匈牙利炖牛肉 · 希腊沙拉 · 瑞典肉丸 · 千层酥 · 意式蔬菜汤 · 尼斯沙拉 · 意式炖小牛膝 · 诺玛意面 · 卡邦尼意面 · 番茄意面 · 西班牙辣味土豆 · 伏特加笔管面 · 热那亚青酱 · 波兰饺子 · 洋葱鳀鱼挞 · 土豆韭葱汤 · 普罗旺斯炖菜 · 米兰藏红花烩饭 · 烤鸡 · 德式酸味炖牛肉 · 牧羊人派 · 希腊菠菜奶酪派 · 蒜油意面 · 阿马特里恰纳意面 · 博洛尼亚肉酱意面 · 西班牙海鲜饭 · 牛排薯条 · 德式水果蛋糕 · 苹果挞 · 提拉米苏 · 番茄汤 · 西班牙土豆蛋饼
亚洲与东南亚	越南法棍三明治 · 仁当牛肉 · 印度香饭 · 韩式烤牛肉 · 黄油鸡 · 广式清蒸鱼 · 炒粿条 · 印度奶油鸡咖喱 · 炒面 · 担担面 · 煎饼果子 · 泰北咖喱面 · 泡菜炒饭 · 宫保鸡丁 · 叻沙 · 捞面 · 马萨曼咖喱 · 印尼炒饭 · 椰浆饭 · 大阪烧 · 泰式炒宽粉 · 泰式炒河粉 · 印度菠菜奶酪咖喱 · 罗根乔什咖喱 · 泰式青木瓜沙拉 · 寿司饭 · 糖醋鸡 · 照烧鸡 · 泰式绿咖喱 · 日式炸猪排 · 豚骨拉面 · 日式炒面
中东与北非	法拉费尔 · 鹰嘴豆泥 · 埃及通心粉杂烩 · 扁豆汤 · 摩洛哥羊肉塔吉锅 · 烤茄子泥 · 皮塔饼 · 北非番茄辣椒炖蛋 · 黎凡特烤鸡肉串 · 塔布勒沙拉
美洲	天使蛋糕 · 烤土豆 · 烤三文鱼 · 烤通心粉 · 香蕉面包 · 烧烤排骨 · 饼干配肉汁 · 酪乳松饼 · 凯撒沙拉 · 墨西哥手撕猪肉 · 酸橘汁腌鱼 · 奶酪玉米饼 · 墨西哥鸡肉法士达 · 鸡肉面汤 · 帕尔马干酪鸡排 · 辣椒炖肉 · 巧克力豆曲奇 · 经典巧克力蛋糕 · 科布沙拉 · 蟹饼 · 奶油菠菜 · 班尼迪克蛋 · 鱼肉塔可 · 法式蘸汁三明治 · 法式吐司 · 软糖布朗尼 · 蒜香黄油虾 · 牛肉塔可 · 意裔美式肉丸 · 牙买加香辣烤鸡 · 基韦斯特青柠派 · 龙虾卷 · 秘鲁炒牛肉 · 奶酪通心粉 · 土豆泥 · 普埃布拉摩尔酱 · 香煎猪排 · 香煎扇贝 · 巴西奶酪面包 · 玉米糕 · 山核桃派 · 费城芝士牛肉三明治 · 炖牛肉 · 波索莱汤 · 手撕猪肉 · 烤球芽甘蓝 · 烤花椰菜 · 炒蘑菇 · 香蒜柠檬虾 · 南方炸鸡 · 玉米粽 · 德州烟熏牛胸肉 · 火鸡肉丸 · 香草纸杯蛋糕 · 蔬菜炒饭 · 华尔道夫沙拉
非洲	兔肉杂烩面包 · 尼日利亚菠菜炖菜 · 南非奶挞 · 安哥拉炖鸡 · 苏亚烤肉串

所有食谱都接受多个别名（例如 "rendang"、"tikka-masala"、"risotto"、"bourguignon"、"carbonara"）。使用 list_dishes 查看完整的实时目录。

没找到想要的菜品？

目录会定期扩充。如果你的 Agent 需要核实目前尚未支持的菜品，请**在 GitHub 上提交问题**申请添加。我们会根据开发者的需求优先安排新增菜品。

---

示例验证输出

Guardian 验证报告实际是什么样的？以下是 Agent 提交一份用培根、奶油和过热的锅制作的 carbonara 时，response_format: "json" 结构的（节选）：

{
  "api_version": "0.7.1",
  "schema_version": "1.0",
  "response_format_version": "v3",
  "kb_version_hash": "7dda40a3b646",
  "verdict": "FAILED",
  "matched_against": "Pasta alla Carbonara (Master)",
  "master_source": "catalog",
  "master_hash": "3357e0929021c0003fea0b79015e2c53cf9ef50d70f0d507605788ad9741fd29",
  "coverage_percentage": 100.0,
  "summary": {"CRITICAL": 4, "WARNING": 0, "INFO": 3},
  "findings": [
    {
      "step_index": 2,
      "issue": "TEMPERATURE_MISMATCH",
      "severity": "critical",
      "justification": "Temperature is significantly outside the required range.",
      "title": "rendering",
      "details": {"expected": "100.0-130.0", "observed": "180"},
      "dimension": "temperature"
    },
    {
      "step_index": null,
      "issue": "INGREDIENT_SUBSTITUTED",
      "severity": "critical",
      "justification": "'bacon' is in the same group ('cured_pork') as 'guanciale' but is not the canonical ingredient for this recipe.",
      "title": "You used bacon, expected guanciale",
      "details": {"expected": "guanciale", "observed": "bacon"},
      "dimension": "ingredients"
    }
  ],
  "allergens": [
    "Allergen detected: Pork-derived ingredients (halal/kosher compliance)",
    "Allergen detected: Milk and products thereof (including lactose)",
    "Allergen detected: Cereals containing gluten (wheat, rye, barley, oats, spelt, kamut)"
  ],
  "patches": [
    {"action": "set_temperature", "step_index": 2, "value": "100.0-130.0"},
    {"action": "replace_ingredient", "remove": "bacon", "add": "guanciale"}
  ]
}

每条发现都包含 severity、基于烹饪科学的 justification，以及机器可读的 details；patches 数组则会准确告知你的 Agent 应进行哪些更改来解决每条可修复的发现，让它只修复问题所在，而不是重新生成并猜测。kb_version_hash + master_hash 会锁定计算判定所依据的确切知识库和规范版本，让结果可作为审计记录重放。

补丁操作：add_ingredient、replace_ingredient、set_quantity、adjust_quantity、set_temperature、set_duration、set_medium 和 add_step（其中包含一个 suggested_step 模板，供你的 Agent 编写，然后重新验证）。

---

本仓库中的文件

文件	用途
schema.md	verify_recipe 所需的完整 candidate_json 结构
client.py	Python 示例：提交食谱进行验证
test_integration.py	针对公共 API 的实时连接测试
smithery.yaml	Smithery MCP 注册表配置
glama.json	Glama.ai MCP 服务声明配置

---

数据与隐私

• 不收集个人身份信息——我们不会存储用户名、电子邮件地址或 API 密钥。底层云基础设施可能会为了路由而暂时处理 IP 地址。
• 用于计算交换的数据——这项免费服务以使用数据作为交换条件。提交的食谱会用于提高验证准确性并创建匿名化衍生数据集。请参阅我们的服务条款。
• 请勿在食谱负载中包含个人身份信息。
• 通过计算限制执行合理使用配额。

注意

不能替代食品安全知识
Guardian Engine 虽然能捕捉明确危险的 AI 幻觉（例如将低于安全温度的禽肉端上桌），但无法保证食谱 100% 安全可食用。病原体灭活取决于文本型 AI 模型无法完全控制的变量（时间、质量、设备）。验证结果仅供参考，必须始终结合人的常识和标准厨房安全实践。

---

支持与联系

正在开发 AI 烹饪助手、智能厨房平台或 Agentic 食品科技产品？我们很乐意听取你的想法。

• 电子邮件：[email protected]
• 网站：kaimeilabs.dev
• GitHub：github.com/kaimeilabs

许可证

本仓库中的客户端代码（client.py、test_integration.py）根据 MIT License 发布。Guardian Engine 验证逻辑和主食谱数据集为专有内容。