mihoyo-mcp: Instructions file for Codex

AGENTS.md

给在本仓库工作的 coding agent 的指令。改代码前先读完本文。

项目是什么

mihoyo-mcp 是一个独立的 MCP Server，统一封装米哈游账号能力，同时面向米游社（国服） 与 HoYoLAB（国际服）。底层 API 封装直接依赖 genshin.py （MIT，PyPI 包名 genshin），不要自己手写米哈游 endpoint / DS / cookie 处理。

主要消费方是 nahida-bot（通过 MCP client 调用），但服务本身不绑定任何 bot。

不可违反的边界（改设计前先想清楚）

1. 凭据永不出服务边界。 Cookie/token 只存在 accounts/vault.py 的 Fernet 加密库里， 只交给 genshin.py 客户端。工具结果、日志、异常消息里绝不能出现 cookie 字段值； Agent 能看到的只有 account_id（形如 miyoushe:123456）和公开的游戏角色信息。 新增任何工具时自查一遍返回结构。
2. 本服务不管调度和推送。 "什么时候轮询、问完告诉谁"是客户端（nahida-bot 的 cron/channel）的事。这里只提供"怎么和米哈游说话"。不要往里加定时器、webhook、消息推送。
3. stdout 属于 MCP 协议。 任何日志/打印一律走 stderr（server.py 的 logging 配置已处理， 新代码用 logging，不要 print）。

关键技术决定（有背景，别随手推翻）

• 工具名必须扁平蛇形（starrail_daily_note，不用 starrail.daily_note）：MCP 规范 SEP-986 要求工具名匹配 ^[a-zA-Z0-9_-]{1,64}$，点号会被部分客户端拒绝。用前缀当命名空间。
• mcp SDK 是 2.0：高层 API 是 from mcp.server.mcpserver import MCPServer（装饰器风格）。 老代码里的 mcp.server.fastmcp.FastMCP 在 2.0 已不存在，抄旧示例代码时注意。
• 米游社扫码登录复用 genshin.py 内部方法 Client._create_qrcode() / _check_qrcode(ticket) （passport-api.miyoushe.com，确认后 Set-Cookie 给 v2 cookies：account_id_v2 / account_mid_v2 / ltoken_v2 / cookie_token_v2）。genshin.py 自带的 login_with_qrcode() 是阻塞交互式的，所以才在 auth/qr.py 拆成 start/poll。
• HoYoLAB 登录尚未接入：genshin.py 没有 OS 扫码流程，mihoyo-api-collect 对 OS 扫码 endpoint 标注"未知"。在验证过真实流量之前，不要凭记忆写死 OS 登录 endpoint。
• 告警去重状态属于本服务（alerts/state.py 的 armed/re-arm 机制）：目的是让客户端 cron 轮询 starrail_check_alerts 时空列表可以直接静默，不重复推送也不烧 LLM token。
• 返回结构防御式归一化：米哈游 API 字段会变，games/notes.py 里用 getattr + 默认值， 上游加/删字段不应炸掉工具，未知字段变 None。

分层约定

tools/      薄封装：解析参数 → 调服务层 → 返回 dict。不写业务逻辑
auth/ games/ alerts/ accounts/   服务层，可单测
context.py  AppContext 单例（settings/registry/vault/sessions/alerts）

新增一个游戏能力的套路：accounts/models.py 的 Game 枚举确认有值 → games/notes.py 加 fetch + normalize → tools/note_tools.py 注册工具 → tests/test_server.py 的 EXPECTED_TOOLS 加名字 → 告警类逻辑进 alerts/ 并配纯逻辑测试。