pokemon-player

Pokemon 玩家

使用 pokemon-agent 软件包，通过无头模拟游玩 Pokemon 游戏。

适用场景

• 用户说“玩 Pokemon”“开始 Pokemon”“Pokemon 游戏”
• 用户询问 Pokemon Red、Blue、Yellow、FireRed 等游戏
• 用户想观看 AI 玩 Pokemon
• 用户提到 ROM 文件（.gb、.gbc、.gba）

启动流程

1. 首次设置（克隆、创建虚拟环境、安装）

该仓库是 GitHub 上的 NousResearch/pokemon-agent。克隆仓库，然后 设置 Python 3.10+ 虚拟环境。优先使用 uv（速度更快） 创建虚拟环境，并通过 pyboy extra 以可编辑模式安装软件包。如果 没有 uv，则改用 python -m venv + pip。

如果已有仓库副本（例如，~/pokemon-agent 中已准备好虚拟环境）， 只需进入该目录并运行 source .venv/bin/activate，无需重新克隆。

你还需要一个 ROM 文件。请向用户索取（之前的设置可能 已在仓库副本内的 roms/pokemon_red.gb 中准备好）。 切勿下载或提供 ROM 文件——务必向用户索取。

2. 启动游戏服务

在已激活虚拟环境的 pokemon-agent 目录中运行 pokemon-agent serve，并使用 --rom 指定 ROM，使用 --port 指定 9876 端口。 使用 & 在后台运行。 若要从已保存的游戏进度继续，添加 --load-state 并指定存档名称。 等待 4 秒让服务启动，然后通过 GET /health 验证。

3. 设置实时仪表板供用户观看

通过 localhost.run 使用 SSH 反向隧道，让用户能在浏览器中查看 仪表板。使用 ssh 连接，将本地端口 9876 转发到 keyless localhost.run 端点的远程端口 80 （ssh -R 80:localhost:9876 ssh://[email protected]）。将输出重定向 到日志文件，等待 10 秒，然后在日志中 grep 出 .lhr.life URL。将末尾附加 /dashboard/ 的 URL 提供给用户。 隧道 URL 每次都会变化——重启后请向用户提供新的 URL。

保存和加载

何时保存

• 每进行 15-20 个回合
• 在道馆战、劲敌遭遇或高风险战斗前，务必保存
• 进入新城镇或地牢前
• 执行任何你不确定的操作前

如何保存

使用描述性名称执行 POST /save。示例：before_brock、route1_start、mt_moon_entrance、got_cut

如何加载

使用存档名称执行 POST /load。

列出可用存档

GET /saves 会返回所有已保存的状态。

服务启动时加载

启动服务时使用 --load-state 标志自动加载存档。 这比启动后通过 API 加载更快。

游戏循环

步骤 1：观察——检查状态并截图

通过 GET /state 获取位置、HP、战斗和对话信息。 通过 GET /screenshot 截图并保存到 ~/.hermes/cache/scratch/pokemon.png，然后使用 vision_analyze。 两者都要执行——RAM 状态提供数值，视觉分析提供空间感知。

步骤 2：确定方位

• 屏幕上有对话/文本 → 推进对话
• 正在战斗 → 战斗或逃跑
• 队伍受伤 → 前往 Pokemon Center
• 接近目标 → 谨慎移动

步骤 3：决策

优先级：对话 > 战斗 > 治疗 > 剧情目标 > 训练 > 探索

步骤 4：行动——最多移动 2-4 步，然后重新检查

使用较短的操作列表执行 POST /action（2-4 个操作，而非 10-15 个）。

步骤 5：验证——每组移动操作后截图

截图并使用 vision_analyze 确认移动到了预期位置。 这是最重要的一步。没有视觉分析，你一定会迷路。

步骤 6：使用 PKM: 前缀将进度记录到记忆中

步骤 7：定期保存

操作参考

• press_a — 确认、交谈、选择
• press_b — 取消、关闭菜单
• press_start — 打开游戏菜单
• walk_up/down/left/right — 移动一格
• hold_b_N — 按住 B 键 N 帧（用于加快文本显示）
• wait_60 — 等待约 1 秒（60 帧）
• a_until_dialog_end — 连续按 A，直到对话结束

实战关键提示

经常使用视觉能力

• 每移动 2-4 步就截一次图
• RAM 状态能告诉你位置和 HP，但看不到周围环境
• 悬崖边、围栏、标牌、建筑入口、NPC——只有通过截图才能看到
• 向视觉模型提出具体问题：“我北边一格是什么？”
• 遇到卡住的情况时，随机尝试方向之前一定要先截图

穿门和楼梯传送后需要额外等待

穿过门或楼梯时，地图切换期间屏幕会淡出至黑屏。你必须等待切换完成。每次通过门或楼梯传送后，都要额外执行 2-3 次 wait_60 操作。如果不等待，读到的位置会过时，让你误以为自己还在旧地图中。

离开建筑时的陷阱

离开建筑时，你会直接出现在门前。如果向北走，就会直接回到建筑内。务必先向左或向右移动 2 格，再朝预定方向前进。

对话处理

第 1 世代的文本逐字缓慢滚动。若要加快对话，按住 B 120 帧，然后按 A。根据需要重复。按住 B 会让文本以最快速度显示。然后按 A 前进到下一行。a_until_dialog_end 操作会检查 RAM 中的对话标志，但该标志无法捕捉所有文本状态。如果对话似乎卡住了，请改用手动按住 B + 按 A 的方式，并通过截图确认。

悬崖边只能单向通过

悬崖边（小型峭壁）只能向下跳（向南），不能向上爬（向北）。如果向北走时被悬崖边挡住，就必须向左或向右寻找绕过它的缺口。使用视觉能力判断缺口在哪个方向，并明确询问视觉模型。

导航策略

• 每次移动 2-4 步，然后截图检查位置
• 进入新区域时，立即截图确认方位
• 询问视觉模型：“往哪个方向去 [目的地]？”
• 如果尝试 3 次以上仍然卡住，就截图并重新全面评估
• 不要连续乱走 10-15 步——你会走过头或卡住

从野生战斗中逃跑

在战斗菜单中，RUN 位于右下角。要从默认光标位置（左上角的 FIGHT）移动到 RUN：先按下，再按右，然后按 A。使用 hold_b 加快文本和动画的播放速度。

战斗（FIGHT）

在战斗菜单中，FIGHT 位于左上角（默认光标位置）。按 A 进入招式选择，再按一次 A 使用第一个招式。然后按住 B，加快攻击动画和文本的播放速度。

战斗策略

决策树

1. 想要捕捉？→ 先削弱，再扔 Poke Ball
2. 不需要的野生宝可梦？→ RUN
3. 属性占优？→ 使用效果拔群的招式
4. 没有属性优势？→ 使用威力最强的本系招式
5. HP 低？→ 换人或使用 Potion

第 1 世代属性相克表（关键对局）

• 水克火、地面、岩石
• 火克草、虫、冰
• 草克水、地面、岩石
• 电克水、飞行
• 地面克火、电、岩石、毒
• 超能力克格斗、毒（在第 1 世代中非常强！）

第 1 世代的特殊机制

• 特殊能力值同时决定特殊招式的攻击和防御
• 超能力属性过于强势（幽灵招式存在错误）
• 暴击取决于速度属性值
• 缠绕/绑紧会让对手无法行动
• 聚气存在错误：会降低暴击率，而不是提高

记忆约定

前缀	用途	示例
PKM:OBJECTIVE	当前目标	从常青市友好商店领取包裹
PKM:MAP	导航信息	常青市：友好商店在东北方
PKM:STRATEGY	战斗/队伍计划	在挑战小霞之前需要草属性宝可梦
PKM:PROGRESS	里程碑追踪	击败劲敌，正前往常青市
PKM:STUCK	卡住的情况	y=28 处有悬崖边，向右走绕过去
PKM:TEAM	队伍备注	杰尼龟 Lv6，撞击 + 摇尾巴

进度里程碑

• 选择初始宝可梦
• 从 Viridian Mart 送包裹，领取图鉴
• Boulder Badge — Brock（岩石）→ 使用水系／草系
• Cascade Badge — Misty（水）→ 使用草系／电系
• Thunder Badge — Lt. Surge（电）→ 使用地面系
• Rainbow Badge — Erika（草）→ 使用火系／冰系／飞行系
• Soul Badge — Koga（毒）→ 使用地面系／超能力系
• Marsh Badge — Sabrina（超能力）→ 最难的道馆
• Volcano Badge — Blaine（火）→ 使用水系／地面系
• Earth Badge — Giovanni（地面）→ 使用水系／草系／冰系
• 四天王 → 冠军！

停止游戏

1. 通过 POST /save 并使用描述性名称保存游戏
2. 使用 PKM:PROGRESS 更新记忆
3. 告诉用户：“游戏已保存为 [name]！说‘play pokemon’即可继续。”
4. 终止服务和隧道后台进程

注意事项

• 绝不要下载或提供 ROM 文件
• 检查视觉画面前，操作不要超过 4–5 次
• 离开建筑后务必先侧移，再向北走
• 通过门或楼梯传送后，务必添加 wait_60 x2-3
• 通过 RAM 检测对话并不可靠——请通过截图确认
• 在高风险遭遇前保存
• 每次重启隧道后，URL 都会变化