内容
# 麦麦种草落地
**把小红书的“想吃”，变成当前麦当劳门店里一份可以照着点的完整餐单。**
面向普通麦当劳消费者：先选口味偏好和整餐预算，再参考真实笔记，从本店菜单搭配主食、小食和饮料，最后用官方整单试算选出 **一份推荐**。预算不足时，最多保留一份完整超预算参考，并显示差额。
当前功能版本：**v0.5.0 · 完整一餐**。项目包含 Skill、本机运行的移动端网页，以及不需要账号的合成数据演示。
> 准备参赛请先看 [提交指南](SUBMISSION.md)：包含干净打包、GitHub 上传、可直接填写的报名 Issue 和演示建议。项目源码与文档已整理；仓库发布和报名需由参赛者本人完成。
## 目标用户与使用场景
- 想试小红书推荐，但不知道自己的门店有没有、今天多少钱的消费者。
- 希望按一餐预算搭配，不想逐个翻菜单和计算优惠的人。
- 有“薯条星人”“低预算”“早餐不纠结”等口味或场景偏好的人。
例如：
> 我想吃薯条，整餐预算35元，在附近麦当劳自取。参考小红书灵感，帮我搭好主食、小食和饮料，只推荐一份，并按本店实际可用优惠核价。
## 能做什么
| 能力 | 当前实现 |
|---|---|
| 个性化灵感 | 六个词条与自定义搜索；读取小红书搜索结果和少量正文 |
| 当前门店菜单 | 使用麦当劳官方 MCP 查询门店、餐品、套餐组成和合法规格 |
| 完整一餐 | 根据实际选项核对主食、小食、饮料，补齐缺少的部分；套餐子项不重复收费 |
| 预算与优惠 | 比较有限候选的官方应付；查询本人在本店已有的可用券，保留用券与规格关联 |
| 一份结果 | 后台比较，前台仅给一份完整配餐；区分笔记灵感与系统补齐 |
| 到店取餐 | 高德解析地点，查询真实步行距离、时间和分段指引，提供导航入口 |
| 手机布局 | 单列卡片、顶部预算、大触控区域、底部餐篮与复制清单 |
| 来源核验 | Skill 与 Python 比较引擎保留独立来源、购买条件和餐篮报价关联 |
网页的主要链路：
```text
偏好 + 预算 + 地点
→ 小红书正文灵感
→ 当前麦当劳门店菜单 / 实际规格 / 本人可用券
→ 搭齐主食、小食、饮料
→ 官方整餐核价
→ 一份完整餐单 + 来源说明 + 到店步行指引
```
小红书暂时不可用时，网页仍可依据真实门店菜单配餐，并说明灵感缺失。菜单或官方核价失败时，不使用演示数据冒充实时结果。
## 先体验：无需账号的离线演示
需要 **Python 3.10+**，只使用标准库。在项目根目录执行：
```powershell
python scripts/run_demo.py --budget-yuan 35
```
然后用浏览器打开 `demo/index.html`，体验点法比较、明确的套餐选项、预算提示与清单复制。目录中的门店、笔记、餐品和金额全部是合成案例。
离线演示保留逐篇点法对照；实时网页提供按偏好补齐一餐的流程。`demo/index.html` 是静态演示，实时入口是下文的本机 HTTP 地址。
## 使用 Skill 与真实服务
### 在支持 MCP 的宿主中使用 Skill
1. 将本项目公开源码放入宿主支持的技能目录，保留 `SKILL.md` 及其引用的子目录。
2. 阅读 [麦当劳官方 MCP 指南](https://github.com/M-China/mcd-mcp-server)，使用本人的 Token 配置官方服务。
3. 按 [第三方小红书 MCP 文档](https://github.com/xpzouying/xiaohongshu-mcp) 安装本机服务，由本人完成扫码登录；也可先提供笔记文字或截图。
4. 参考 [mcp-config.example.json](mcp-config.example.json) 配置连接。环境变量占位符的替换方式由宿主决定，示例不能保证直接兼容所有客户端。
5. 让宿主读取 `SKILL.md`，再输入上面的使用示例。需要地图能力时，另行配置高德 MCP。
实际工具、调用参数与使用范围见 [MCP 集成说明](MCP_INTEGRATION.md)，凭证与结果处理见 [真实接入](references/live-integration.md)。
### 运行本机真实数据网页
需要 **Node.js 22+**。当前开发机已完成三方联调，但公开源码没有附带本人凭证、登录状态或私有启动组件。新机器需先完成下表配置。
| 服务 | 网页适配器当前接法 |
|---|---|
| 麦当劳 | 优先读取 `MCD_MCP_TOKEN`；未设置时使用本机私有凭证助手 |
| 小红书 | 连接固定的 `http://127.0.0.1:18060/mcp`；需本人登录，并配置匹配的 `XHS_MCP_AUTH_TOKEN` 或私有鉴权助手 |
| 高德 | 目前依赖本机 `private/Start-AmapMcp.cjs` 与 `private/amap-runtime/` 中的 MCP/SDK 配置，公开包不包含这些组件 |
**公开包可以直接复现离线演示；真实网页的三方连接仍有本机配置依赖。** 当前没有项目根级 `package.json`，无需在根目录执行 `npm install`。小红书无鉴权的默认安装也不能直接视为已满足网页适配器的配置要求。配置细节和现有限制见 [真实接入](references/live-integration.md)。
在已配置的电脑上运行：
```powershell
node scripts/live_server.mjs
```
Windows 也可运行：
```powershell
.\scripts\start_live.ps1 -Port 8787
```
浏览器打开 `http://127.0.0.1:8787`，按以下顺序体验：
1. 设置整餐预算、城市和出发地点，选择取餐门店。
2. 点选“薯条星人”“低预算”等词条，或输入关键词。
3. 点击“按预算，搭配完整一餐”，查看组成、官方试算和来源。
4. 采用后确认餐品规格，可调整、重新核价并复制清单。
5. 查询到店步行路线，在麦当劳官方渠道自行确认下单。
服务仅接受本机回环访问。`127.0.0.1` 不是可以分享给手机或评委的线上网址；移动端在这里指界面布局。当前未提供局域网访问、公网部署或嵌入式高德地图底图。
## 计价与能力边界
- **完整与单份**：必须包含主食、小食、饮料，不能只以一份薯条充当一餐。后台最多读取2篇正文、查询15份详情、生成8个候选、进行6次官方核价，最终只展示一份；不承诺搜索全店所有组合。
- **真实价格**：预算以当前具体餐篮的官方最终应付为依据，菜单展示价和原帖价格仅作参考。更换门店、规格或份数后重新核价。
- **会员与券**：麦金卡资格仍为 `unverified`，不能凭菜单金卡标签认定本人享有权益。优惠取官方实际核价，不自动购卡、领券或重复减价。
- **时效**：报价复核窗口最多300秒，优惠到期可能更早；重读结果不能延长。任务结果最多保留15分钟，运行任务最多120秒，尚未退出的调用不会叠加新任务。
- **灵感与营养**：网页采用菜单约束的文字规则，无 OCR 或独立 LLM 接口。系统补齐会标明；“低卡”是方向性偏好，未完成官方营养核验；“低预算”不代表全店最低价。
- **操作范围**：网页仅查询、搭配与复制清单，不执行下单、支付、领券、购卡或社交发布。小红书接入为第三方本机工具，并非平台官方 API。
## 验证与目录
在项目根目录运行：
```powershell
python -m unittest discover -s tests -p "test_*.py"
node --test tests/live_providers.test.mjs tests/meal_planner.test.mjs tests/meal_composer.test.mjs tests/meal_plan_service.test.mjs
```
公开测试主要使用合成数据和假提供方，验证完整配餐、规格/优惠绑定、预算、过期处理与本机接口边界，不访问消费者账号或产生订单。Python 的部分测试需检测到 Node.js 才执行；公开包还会跳过一项依赖本机私有真实笔记的回归。这些测试不能证明运行时第三方服务一定可用。
```text
README.md 项目介绍与运行方法
SUBMISSION.md 参赛提交流程与报名正文
CONTEST_DECLARATION.md 官方原样参赛声明
MCP_INTEGRATION.md 实际 MCP、工具和调用链
mcp-config.example.json 仅含占位符的连接示例
SKILL.md 宿主技能说明
web/ 本机移动端网页
scripts/ 适配器、配餐器、比较引擎与打包工具
tests/ 自动化回归
fixtures/、demo/ 合成案例与离线演示
references/ 数据约定和详细接入说明
submission-files.txt 公开提交文件白名单
```
## 打包与参赛
在项目根目录执行以下命令，生成只含公开清单的干净目录和 ZIP：
```powershell
python scripts/package_submission.py --output-dir ../dist
```
上传干净目录中的文件到你自己的 **Public GitHub 仓库根目录**，再按 [提交指南](SUBMISSION.md) 中的模板前往大赛仓库发布报名 Issue。ZIP 是传输副本，不能仅把 ZIP 上传仓库代替可读取的源码文件。
规则核对日期：2026-10-15；当前报名截止为 **2026-10-25 23:59（北京时间）**，以 [官方活动仓库](https://github.com/M-China/mcd-developer-innovation-challenge) 和 [活动规则](https://github.com/M-China/mcd-developer-innovation-challenge/blob/main/activityGuidelines.md) 的后续公告为准。
`private/`、`artifacts/`、`.env*`、Cookie、账号配置和真实调用快照不进入公开包。最近生成的长截图与高清 HTML 位于 `artifacts/`，请在核对第三方内容和隐私后单独决定展示素材。需要公开界面示例时，可先使用 `demo/` 的合成演示。
## 许可与第三方
项目自有代码采用 [MIT License](LICENSE)。麦当劳 MCP、小红书第三方工具、高德服务和运行时取得的内容，各自遵循其所属方的规则与权利。项目为独立参赛作品，不代表麦当劳、小红书或高德官方。
MCP 市场