通用手游 Agent

架构和设计详见《通用手游Agent开发文档.md》。第一个落地游戏是无期迷途，资源来自 MBCCtools。

环境准备

python -m venv .venv
./.venv/Scripts/pip install -r requirements.txt   # Windows
# source .venv/bin/activate && pip install -r requirements.txt  # macOS/Linux

复制.env.example为.env并填写LLM相关的key（LLM_MODEL_ID/LLM_API_KEY/LLM_BASE_URL）。

模拟器/真机需开启adb调试，且games/无期迷途/profile.yaml里的adb.address要能连上； 如果本机装了多个adb，建议在profile里显式填adb.adb_path，否则会用 maa.toolkit.Toolkit.find_adb_devices()自动探测。

单独测试MAA-MCP-Server

不经过LLM，先验证MaaFramework这一层能不能跑通：

./.venv/Scripts/python core/maa_mcp_server.py games/无期迷途/profile.yaml

进程会常驻并通过stdio等待MCP客户端连接（比如用MCP Inspector连上去手动调用 screenshot/click/swipe/list_known_tasks/run_known_task）。

跑自由探索Agent

./.venv/Scripts/python core/agent_runner.py games/无期迷途/profile.yaml

agent_runner.py会自动拉起maa_mcp_server.py子进程（通过stdio），把它暴露的工具注册进 HelloAgents的ReActAgent，然后开始自由探索。探索记忆存在exploration_logs/<game_id>.json里， 按game_id分文件，重复运行不会互相污染。

运行时终端会打印一个本地网页地址（默认http://127.0.0.1:8765），浏览器打开就能实时看到 LLM调用/工具调用/敏感界面拦截等日志（core/log_broadcaster.py，给ReActAgent自带的 TraceLogger包了一层SSE推送，不影响原有的memory/traces/落盘）。端口可以在profile.yaml里加 dashboard: {host: ..., port: ...}覆盖。

接入新游戏

复制games/_template/，按里面的README checklist填。验证标准：接入过程中core/目录 不应该有任何改动。