金谷园饺子馆 Skill（jinguyuan-dumpling-skill）是一个帮用户查排队状态、排队取号的 AI 助手技能。它最有趣的设计之一，是明确要求 AI "不能想当然"：回答"现在排队吗"之前，必须先查最新数据，过期快照不许冒充实时事实。

为什么 AI 回答排队问题最容易"翻车"？

对新手来说，AI 助手回答排队问题有三类典型错误：

jinguyuan-dumpling-skill 的解法很干脆：把"什么能答、什么不能答"写成合同，让 AI 照着执行。这套合同就写在 references/queue-reply-contract.md 里，是理解整个项目设计的关键文件。

排队回答合同：AI 先读"合同"再开口

当用户问"金谷园现在排队吗"，AI 并不会直接猜，而是调用金谷园官方 API 拿到一份结构化返回体，然后优先读其中的合同字段：

简单理解：API 返回的不只是数据，还有一份"答题规则"。AI 先定骨架（mainScenario），再决定说什么（requiredPoints）和不许说什么（forbiddenPoints），最后才组织语言。

💡 这套设计的好处是：AI 的回答不再是"自由发挥"，而是有据可查、可复现的。你问两次同类问题，它不会这次严谨、下次放飞。

数据新鲜度设计：数据是否新鲜是唯一通行证

排队状态是最容易过期的数据。金谷园 API 的返回体里，每家门店都带一个关键字段——当前排队状态.门店[].数据是否新鲜，规则只有一条：

• ✅ 只有值为true，才能把等待桌数说成当前状态
• ⚠️ 值为false时，只能说明"最近采集时间"和"当前无法确认"，最后一次记录仅供回看，不能冒充实时事实

这条规则在 SKILL.md 的"Agent 硬约束"中被反复强调，并在"通用禁令"里补了一句：不要把数据是否新鲜不为true的最后一次记录说成当前排队状态。

再叠加几条配套禁令，AI 的"想当然"空间就被彻底封死了：

1. ❌ 不把等待桌数换算成具体分钟
2. ❌ 不把前一天和上周同日加权平均后说成唯一结论
3. ❌ 不把历史参考说成目标日期的事实
4. ❌ 不用门店当前总等待冒充用户个人排队进度
5. ❌ 不声称查询接口已经帮用户取号或查到个人进度

分层回答：事实是事实，建议是建议

除了"当前排队"，项目把其他排队问题也分了层，避免混淆口径（详见 references/queue-reply-contract.md 的"餐段口径"）：

• 事实层queue/period-facts：已发生餐段的实际观测——"今天中午几点开始排"，必须说清是实际观测
• 策略层queue/period-advice：未来餐段的参考建议——"明天中午几点去比较稳"，必须说清是参考建议，默认参考前一天 + 上周同日

所有公开查询统一走随包 CLI（入口是 scripts/jgy.cjs），能力清单与调用方式见 references/api-reference.md；真实的取号、查进度、取消排队则走独立的queue命令并需用户明确确认，规则在 references/queue-actions.md 中定义。

小结：把"严谨"写进设计

jinguyuan-dumpling-skill 给 AI 排队问答划了一条清晰的底线：没查到就说没查到，查到了先验新鲜度，再按合同回答。这种"回答合同 + 数据新鲜度"的设计，对任何想让 AI 可靠回答实时信息的开发者，都值得借鉴。技能的整体能力描述可参考 skill.json 与 README.md。