timhengc / mai-shen-zai-ci

# 麦门封神榜
> 你在麦门算老几？领取你的麦门专属身份
麦当劳程序员创意开发大赛独立参赛作品，非麦当劳官方产品。基于 麦当劳中国 MCP，年报与名片用代码生成，并附带18张已生成的男女等级角色图；日常使用无需调用模型生图。
## 三件套，一份身份
| 功能 | 产物 | 视觉 |
| --- | --- | --- |
| 麦门年报 | 动画 HTML + 1080px 宽 PNG 长图 | 消费回顾、口味排行、月份节拍、最终门派身份与角色 |
| 麦门名片 | HTML + PNG | 门派、称号、境界、个人纹章、数据依据 |
| 专属头像 | HTML + PNG 原图 | 直接输出与年报、名片相同的等级人物图，保留原始尺寸 |
| AI 头像扩展 | 可选生图简报 | 仅明确选择后使用 Agent 的生图能力；不影响核心功能 |
项目只做身份视觉创作，不提供餐饮决策或交易功能。版式、汉堡插画、纹章为代码绘制，人物使用已打包的男女等级图，不表示官方餐品图片或会员等级。人物衣服保留小巧的金黄色麦当劳双拱门 M 胸标；后续模型头像沿用简约粗黑线红黄涂鸦风，不做 OK 手势。
## 预置人物图：男女各9个等级
半身版、红黄配色、粗黑线涂鸦风；每个等级男女各一张，不区分门派，衣服保留小号金色麦当劳 M 胸标。低阶朴素，高阶逐步增加发饰、飘带和光轮。
| 男性扫地僧 | 女性扫地侠 |
| --- | --- |
| | |
全部素材：男性9级图鉴 · 女性9级图鉴。每套含独立 PNG、按等级索引的 `manifest.json` 和完整生成提示词。
年报、名片、头像默认根据同一身份的 `level` 与 `gender` 自动选择同一张人物图，无需手动指定。`--portrait-image` 可统一替换为用户指定的人物图。头像直接复制原图，不添加文字、边框或装饰。预置素材已经生成并随项目提供，使用这些图片无需实时生图。原始参考截图、失败草稿、私人名片、预览和 ZIP 打包产物不纳入仓库。
## 如何确定身份
统一实现：identity.py，可调整的预设：identity_rules.json。年报、名片、头像绝不分别猜测称号；`all` 一次查询，共享同一个快照和规则版本。
**阅历 = 完成订单数 × 2 + min(有记录月份,12) + min(餐品种类,12)**。同一天多笔完成订单分别计入，订单贡献不封顶；月份与餐品种类各最多加12分。只使用已完成、去重后的已知数据；金额、性别不参与等级。该分数是虚构世界观的生成规则，不是现实评价，也不提供升级消费建议。
| 最低阅历 | 境界 | 预设身份（男 / 女） |
| --- | --- | --- |
| 0 | 初识 | 麦门新客 |
| 4 | 入门 | 见习小师弟 / 见习小师妹 |
| 12 | 修习 | 藏味扫地僧 / 藏味扫地侠 |
| 50 | 入室 | 关门大弟子 |
| 70 | 宗师 | 一派掌门 |
| 90 | 出尘 | 云游散仙 |
| 110 | 登仙 | 金拱真仙 |
| 135 | 仙境 | 赤金仙君 / 赤金仙姬 |
| 160 | 神境 | 麦门真神 |
扫地僧覆盖12—49分；已移除“入室弟子”。例如9笔订单、6个有记录月份、15种餐品得 `9×2+6+12=36` 分，属于扫地僧。活跃天数仍作为年报展示统计，但不再参与身份评分。达到160分即为最高等级“麦门真神”，男女同名；阅历仍按实际订单累计。
餐品关键词确定门派：薯山剑派、金堡门、麦咖书院、气泡宗、甜心谷、脆羽山庄；未知明细归逍遥门。一个餐品只分配一次，份数同分按预设顺序，口味不作为性别或现实性格的推断。
**官方接口只提供近期订单，不保证全年完整。** 年份只是本地筛选条件；身份和报告明确写“本次可见订单”。金额或餐品明细缺失时不编造数据，真实模式失败也不回退成示例。
## 在 Agent 中使用 Skill
项目入口见 SKILL.md。
1. 首次使用且未配置 Token 时，Agent 先展示官网入口二维码、可点击链接和申请教程图，让用户完成登录并复制 Token；可直接发到对话框，或写入 `.env`。
2. 完成连接后，用户没有明确目标时，Agent 展示：年报 / 名片 / 头像 / 全套，并等待选择。
3. 选定后，再询问可选性别称谓：男（默认）/ 女。跳过时使用男性称谓；已明确提供就不重复询问。
4. 若能从本人账号的明确字段获取性别，直接复用。目前真实 MCP 账户查询不含性别，不能把地址联系人性别当成账号性别。
5. 读取真实订单，统一定身份，再生成所选内容。开发讨论不触发创作问答。
性别仅用于称谓与角色预设，不影响分数、等级、门派，不推断真实长相。
## 安装和直接运行
Python 3.9+；PNG 导出额外需要 Node.js 20+：
 [code] 
在 MCP 开放平台 申请 Token，可发到 Agent 对话框供本次使用，也可以写入已被 Git 忽略的 `.env`：
 [code] 
 [code] 
支持 `--year`（默认当前年）、`--output`（自定义目录）、`--mock-data`（自定义演示 JSON）。CLI 不访问远程生图服务，也不嵌入任何模型密钥。
## 用户名与多账号
年报和名片默认优先使用接口明确返回的本人账号名；如果接口没有账号名，则不显示用户名。不会用账号 ID、手机号或配送联系人冒充用户名，也不会自动补“麦门同学”。用户可用 `--nickname` 明确指定显示名。
 [code] 
输出例如 `annual-report_example.html/.png`、`identity-card_example.html/.png`。`--env-file` 严格隔离账号，不会在指定文件无效时读取其他凭证。省略 `--nickname-fallback` 时，未知账号名保持隐藏。
## 首次登录与 Token
先提供 **官方平台与接入文档**、入口二维码及下方教程。打开官网，按当前页面提示完成登录，进入控制台激活、同意协议后复制 MCP Token。
复制后任选一种方式：
- **发到当前 Agent 对话框**：Agent 不回显完整 Token，默认仅用于本次操作，不自动保存。
- **写入配置文件**：项目根目录 `.env` 添加 `MCD_MCP_TOKEN=你的Token`，以后可直接复用。`.env` 被 Git 忽略。
可直接打开的教程页由标准库生成，内嵌全部图片，无需 Node.js：
 [code] 
教程页也提供本地生成 `mcd-token.env` 下载的选项；输入内容不发往网络，下载后原样放到项目根目录即可自动读取，无需改名；该文件也被 Git 忽略。环境变量优先，其次 `.env`，再其次 `mcd-token.env`。入口二维码打开官网，不包含任何 Token，也不是自动授权回调。截图中的登录二维码是示意，实时登录步骤以官网为准。
 展开 Token 申请图文教程（用户提供的参考截图） 
## 打开作品
全套默认输出在 `ou