paulthemagno/pokemon-emulator-tracker

GitHub: paulthemagno/pokemon-emulator-tracker

宝可梦模拟器存档与实时内存追踪仪表盘，提供队伍、物品栏、地图等数据的可视化展示及可选的AI问答助手。

Stars: 0 | Forks: 0

# Pokemon 模拟器追踪器

Pokemon Emulator Tracker logo

检查 Pokemon 存档文件，实时监控 mGBA 内存，并使用基于工具的 LLM 查询当前游戏进度。

Pokemon Emulator Tracker battle demo

Pokemon Emulator Tracker 是一个本地优先的 Pokemon 模拟器运行仪表盘。它将存档文件和实时 mGBA 内存数据转化为可读的训练师仪表盘：队伍、HP、箱子、物品栏、徽章、Pokedex、地图位置、剧情标志以及当前进度。它支持两个主要工作流程： - **存档文件：** 上传 `.sav`、`.srm`、`.sa1`、`.sa2`、`.sn1` 或 `.sn2` 文件并检查运行情况。 - **实时模拟器追踪：** 通过本地 Lua 适配器连接 mGBA，并在游戏运行时实时观察仪表盘的更新。可选的 Ollama、OpenRouter 或 BYOK 助手可以回答有关当前加载的存档或实时会话的问题。 ## 目录 - [仪表盘概述](#dashboard-overview) - [快速开始](#quick-start) - [支持的游戏](#supported-games) - [存档文件工作流](#save-file-workflow) - [实时模拟器工作流](#live-emulator-workflow) - [本地 LLM 助手](#local-llm-assistant) - [测试与审计](#test-and-audit) - [数据来源](#data-sources) - [项目文档](#project-docs) ## 仪表盘概述

Pokemon Emulator Tracker dashboard overview

## 快速开始需要 Node.js 和 Corepack。 ``` corepack enable corepack pnpm install corepack pnpm dev ``` 打开： ``` http://localhost:3000 ``` 你也可以尝试托管的 UI：[pokemon-emulator-tracker.vercel.app](https://pokemon-emulator-tracker.vercel.app/)。托管演示支持上传存档和 UI 浏览。实时 mGBA 模式和本地 Ollama 仅限本地运行，因为 Vercel 无法访问你机器上运行的服务。当配置或输入了 API key 后，托管聊天可以使用 OpenRouter 或 AI SDK BYOK。

安装和局域网说明

如果 `pnpm install` 因构建脚本被阻止而失败： ``` corepack pnpm approve-builds --all corepack pnpm install ``` 要在局域网中暴露 UI： ``` corepack pnpm dev --hostname 0.0.0.0 ``` 然后打开主机 IP，例如： ``` http://192.168.1.83:3000 ```

## 支持的游戏 | 世代 | 游戏 | 存档上传 | mGBA 实时 | | --- | --- | --- | --- | | 第 1 世代 | Red, Blue, Yellow | 支持 | 支持 | | 第 2 世代 | Gold, Silver, Crystal | 支持 | 支持 | | 第 3 世代 | Ruby, Sapphire, Emerald | 完全支持 | 完全支持 | | 第 3 世代 | FireRed, LeafGreen | 完全支持 | 完全支持 | 有关详细的支持列表和当前注意事项，请参阅 [docs/game-support-matrix.md](docs/game-support-matrix.md)。 ## 存档文件工作流 1. 在本地启动应用程序或打开托管演示。 2. 将 `.sav`、`.srm`、`.sa1`、`.sa2`、`.sn1` 或 `.sn2` 文件拖到上传区域。 3. 检查训练师数据、队伍、Pokedex、PC 箱子、物品栏、徽章和地图。 4. 在游戏中保存后重新上传存档，以刷新仪表盘。当原始存档布局无法唯一识别游戏时，文件名提示非常重要： - 第 1 世代：在通用文件名中包含 `red`、`blue` 或 `yellow`。 - 第 3 世代：在通用文件名中包含 `ruby`、`sapphire`、emerald`、`firered` 或 `leafgreen`。解析器将上传的存档规范化为与实时模式相同的模型，因此 UI 在上传或实时轮询后的行为表现是一致的。 ## 实时模拟器工作流实时模式要求应用程序在本地运行。 1. 使用 `corepack pnpm dev` 启动应用程序。 2. 在 mGBA 中打开游戏。 3. 在 mGBA 中，打开 `Tools -> Scripting...`。 4. 为你的游戏加载 Lua 适配器。 5. 保持脚本运行。 6. 在 Web 应用程序中，按 **Start Live**。 | 游戏 | Lua 适配器 | | --- | --- | | Red, Blue, Yellow | `live-adapters/mgba-gen1-live.lua` | | Gold, Silver, Crystal | `live-adapters/mgba-gen2-live.lua` | | Ruby, Sapphire, Emerald, FireRed, LeafGreen | `live-adapters/mgba-gen3-live.lua` | Lua 适配器提供： ``` http://127.0.0.1:8080/snapshot ``` Web 应用程序调用： ``` GET /api/live ``` 这将代理到本地 Lua 服务器。如果更改了 Lua 脚本或 `live-adapters/generated/` 下的任何文件，请在 mGBA 中重新加载脚本。如果实时轮询停止，仪表盘将回退到上传的存档文件。更多详细信息和调试端点：[live-adapters/README.md](live-adapters/README.md)。 ## LLM 助手聊天助手是可选的。它可以使用本地 Ollama、OpenRouter 或 AI SDK BYOK，并从当前存档/实时会话中接收精简的上下文：训练师、队伍、物品栏、徽章、位置、Pokedex 进度以及相关的本地知识。

Pokemon Emulator Tracker AI SDK BYOK assistant demo

助手支持三种提供者模式： | 模式 | 连接方式 | 最低设置要求 | | --- | --- | --- | | **Ollama** | 完全本地的 Ollama 端点 | 运行 Ollama，拉取模型，并使用 `CHAT_PROVIDER=ollama` | | **OpenRouter** | 通过 OpenRouter 网关的托管模型 | 设置 `OPENROUTER_API_KEY`、`OPENROUTER_MODEL` 和 `CHAT_PROVIDER=openrouter` | | **AI SDK / BYOK** | 通过 Vercel AI SDK 的原生 Anthropic、OpenAI 或 Google API | 设置 `AI_SDK_MODEL=provider/model`，提供匹配的供应商密钥，并使用 `CHAT_PROVIDER=ai-sdk` | 上面的演示使用带有 Google Gemini 的 **AI SDK / BYOK**。通过 `CHAT_PROVIDER` 设置默认提供者，或者在当前页面会话的 **Chat AI → Settings** 中切换提供者、模型并请求 API key。对于每种模式，启动应用程序，加载存档或启动实时模式，然后打开 **Chat AI**。助手在桌面端会作为右侧抽屉打开，在其可见时会调整仪表盘的大小；在较小的屏幕上，它的表现类似于底部表单。

本地 Ollama 设置

1. 安装 Ollama 并拉取默认模型： ``` ollama pull gemma4:latest ``` 2. 启动 Ollama： ``` ollama serve ``` 3. 启动应用程序： ``` corepack pnpm dev ```

如果选择的 Ollama 模型不支持工具调用，应用程序将回退到 prompt/context 模式。OpenRouter 和 AI SDK BYOK 通过提供者的工具调用 API 使用相同的工具注册表。

LLM 配置

可选的环境变量： ``` CHAT_PROVIDER=ollama CHAT_MAX_TOKENS=-1 CHAT_TEMPERATURE=0 CHAT_THINKING=true CHAT_ENABLE_TOOLS=true OLLAMA_ENDPOINT=http://127.0.0.1:11434 OLLAMA_MODEL=gemma4:latest OLLAMA_EMBEDDING_MODEL=embeddinggemma:latest OLLAMA_API_KEY= OLLAMA_ALLOW_RUNTIME_ENDPOINT=false OPENROUTER_API_KEY= OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 OPENROUTER_MODEL=google/gemini-2.5-flash-lite AI_SDK_API_KEY= AI_SDK_MODEL=anthropic/claude-sonnet-4-5 ``` `CHAT_PROVIDER` 选择服务器的默认提供者。聊天设置面板可以为当前页面会话覆盖提供者、模型、Ollama 端点，并请求 API key。空白字段使用服务器环境变量值，并且请求的 API key 不会存储在对话历史记录中。远程 Ollama 端点覆盖需要 `OLLAMA_ALLOW_RUNTIME_ENDPOINT=true`。 `CHAT_MAX_TOKENS` 和 `CHAT_TEMPERATURE` 是所有聊天提供者共享的默认值。对于公开兼容控件的提供者，`CHAT_THINKING` 是共享的思考/推理默认值。设置 `CHAT_ENABLE_TOOLS=false` 以禁用每个提供者的工具调用并使用 prompt/context 模式。当你需要时，仍然支持特定于提供者的覆盖：`OLLAMA_MAX_TOKENS`、`OPENROUTER_MAX_TOKENS`、`AI_SDK_MAX_TOKENS`、`OLLAMA_TEMPERATURE`、`OPENROUTER_TEMPERATURE`、`AI_SDK_TEMPERATURE`、`OLLAMA_THINKING` 和 `AI_SDK_REASONING`。 `CHAT_PROVIDER=ai-sdk` 启用通过 Vercel AI SDK 的 BYOK 路由。输入模型格式为 `provider/model`，例如 `anthropic/claude-sonnet-4-5`、`openai/gpt-4.1` 或 `google/gemini-2.5-flash`。API key 必须与提供者前缀匹配。 `OLLAMA_EMBEDDING_MODEL` 选择用于指南 RAG 生成和运行时向量检索的 Ollama embedding 模型。它没有隐藏的默认值；请在生成 embedding 之前进行设置。如果更改此项，请重新生成静态指南 embedding，以便文档和查询向量由同一个模型生成： ``` corepack pnpm generate:pokemon-guide-embeddings ``` JPEG、PNG 和 WebP 附件支持具有视觉能力的 Ollama、OpenRouter 或 AI SDK 模型。通过图片按钮添加它们，或将图片直接粘贴到聊天输入框中。语音备忘录需要单独的 speech-to-text 步骤，目前尚不支持。附件图片将在聊天中呈现，并与客户端的对话一起存储。公开 Ollama 思考或 AI SDK 推理的模型可以将其流式传输到可折叠面板中。在聊天设置中禁用 **Model thinking**，设置 `CHAT_THINKING=false`、`OLLAMA_THINKING=false` 或 `AI_SDK_REASONING=false`，以在所选提供者支持禁用推理的情况下，仅请求最终答案。

详细信息：[docs/llm-pokemon-agent.md](docs/llm-pokemon-agent.md)。 ## 测试与审计 ``` corepack pnpm test corepack pnpm audit:pokemon-data ``` 在将新游戏提升为完全支持之前，请更新支持列表并添加 fixtures/tests。 ## 数据来源 Pokemon 数据在运行时应保留在本地，并具有可追溯的来源。`lib/pokemon/knowledge/` 和 `live-adapters/generated/` 下的生成文件不应手动编辑。源清单： ``` lib/pokemon/knowledge/sources/ ``` 生成的输出： ``` lib/pokemon/knowledge/ live-adapters/generated/gen1-live-offsets.lua live-adapters/generated/gen2-live-offsets.lua live-adapters/generated/gen3-live-offsets.lua ``` 重新生成： ``` corepack pnpm generate:pokemon-knowledge ``` 源策略与固定版本： - [docs/pokemon-source-policy.md](docs/pokemon-source-policy.md) - [docs/source-lockfile.md](docs/source-lockfile.md) 事件描述将固定的 PRET 源事件与来自 `lib/pokemon/knowledge/sources/game-guide-sources.json` 的经过审查的攻略参考结合在一起。 ## 项目文档 - [live-adapters/README.md](live-adapters/README.md)：使用和调试 mGBA 脚本。 - [docs/architecture.md](docs/architecture.md)：稳定的技术数据流。 - [docs/game-support-matrix.md](docs/game-support-matrix.md)：各游戏的支持状态。 - [docs/known-issues.md](docs/known-issues.md)：已知的限制。 - [docs/llm-pokemon-agent.md](docs/llm-pokemon-agent.md)：本地助手工具、检索和提供者行为。 - [docs/pokemon-source-policy.md](docs/pokemon-source-policy.md)：Pokemon 数据的来源标准。 - [docs/source-lockfile.md](docs/source-lockfile.md)：来源、固定版本与偏移量说明。 - [docs/progress-facts-prototype.md](docs/progress-facts-prototype.md)：已审查进度事实的生成审计报告。 - [AGENTS.md](AGENTS.md)：Codex/agents 的操作说明。

标签：AI风险缓解, LLM集成, rizin, 仪表盘, 内存读取, 宝可梦, 自动化攻击