当你想让 AI 真正“上手”玩一款大型 RPG 游戏时最难的不是模型能不能理解对话而是整个链路能否稳定跑通屏幕画面怎么采集、画面怎么变成模型能理解的信号、模型决策之后怎么转成键盘鼠标操作以及最让人头疼的——为什么画面突然黑屏AI 瞬间失去“视力”。这篇文章基于我最近搭建 AI 游戏 Agent 的实战过程整理而成。我会拆解一套可运行的方案重点讲清楚视觉回传链路的设计以及“黑屏”这类高频问题的排查思路。如果你对 AI Agent、多模态模型、游戏自动化感兴趣或者手里正好有一台吃灰的电脑想折腾点新东西这篇文章应该能帮你少走很多弯路。文中示例代码以 Python 为主依赖尽量精简核心逻辑可以直接复制到你的项目里改一改就能用。1. 背景AI Agent 玩游戏到底拆成了哪几步1.1 Neuro 类智能体不只是“外挂”你可能在网上看过一些 AI 实况主播比如用神经网络驱动角色跑图、接任务、甚至和 NPC 对话。这类玩法统称“Neuro 类智能体”核心思路不是用固定脚本模拟按键而是让模型像人一样“看画面、想策略、再操作”。和传统图像识别 键鼠脚本相比Neuro 类智能体的优势在于泛化能力传统脚本遇到画面亮度变化、UI 布局调整就失效基于视觉语言模型VLM的 Agent 能根据当前画面内容动态决策模型甚至能读懂任务日志、物品描述、地图信息然后自行规划下一步。当然缺点也很明显延迟高、推理贵、行为不稳定。所以这类项目更适合做技术验证而不是生产级“外挂”。1.2 为什么选上古卷轴这类 RPG 作为试验场《上古卷轴》这类开放世界 RPG 是非常理想的 AI 试验环境画面元素丰富光照、天气、室内外场景差异大能考验视觉模型的鲁棒性任务链路长AI 需要长期记忆和规划输入自由度大移动、交互、菜单、地图、对话几乎覆盖了游戏 Agent 需要的全部动作原语。如果把 AI 玩游戏的难度分成等级俄罗斯方块算入门格斗游戏算进阶上古卷轴这种开放世界 RPG 就是地狱模式。“黑屏”只是这条路上遇到的第一道坎。1.3 一条完整的控制闭环一个 AI 游戏 Agent 的最小闭环包含五个环节视觉采集从屏幕获取当前游戏画面图像理解把画面“翻译”成文字描述策略决策由 LLM 根据描述和任务目标生成下一步动作动作执行把动作转成键盘鼠标输入状态反馈再次采集画面判断动作是否生效。下面这张 ASCII 图可以帮助理解闭环逻辑屏幕画面 - 视觉采集 - 预处理 - VLM 图像描述 - LLM 决策 - 动作映射 - 键鼠操作 - 屏幕画面 ^ | |____________________ 反馈循环 _______________________|当某个环节断裂整个 Agent 就成了“盲人开车”。最常见的问题就是视觉采集环节出现黑屏导致后续所有逻辑拿不到有效输入。2. 整体架构与模块拆解2.1 架构设计我把项目拆成了四个独立模块模块之间通过队列解耦便于单独调试capture.py负责屏幕采集和图像预处理describer.py负责调用多模态模型生成画面描述brain.py负责接收描述和任务状态输出决策controller.py负责执行键盘鼠标动作。另外有一个main.py负责编排主循环。模块解耦的收益是如果黑屏直接测试capture.py就能定位问题如果想换更强的 VLM只需要改describer.py其他模块不动。2.2 为什么要把画面转成文字而不是直接让模型看图片大型语言模型擅长处理文本但并不是每个模型都具备视觉能力。即使在 2025 年很多推理模型仍然只接受文本输入。所以这里采用“VLM 描述 LLM 决策”的两段式架构VLM视觉语言模型负责把复杂画面压缩成结构化文本LLM大语言模型基于文本描述做策略推理。这种做法的好处降低决策模型的视觉负担便于查看决策日志因为模型是“看着文字”做判断的可以随时替换决策模型比如从 GPT 换成本地开源模型。坏处是丢失了大量视觉细节但作为 MVP 足够。2.3 技术选型参考模块工具说明屏幕采集mss跨平台速度快适合游戏场景图像处理OpenCV缩放、转灰度、画框视觉描述Qwen-VL / 其他 VLM API将截图转成文本决策模型GPT / Claude / 本地 LLM根据描述生成动作键鼠控制pyautogui跨平台模拟键盘鼠标编排Pythonthreading/asyncio异步采集与推理版本不需要过度纠结Python 3.10 即可依赖库使用 pip 安装的最新稳定版。如果使用 API请确认你的模型服务支持“图像输入转文本描述”的能力。3. 环境准备与版本说明3.1 运行环境本文示例在 Windows 11 上验证macOS 和 Linux 也可以运行但需要注意屏幕采集权限和键鼠控制权限的差异。游戏建议在窗口化模式下运行分辨率固定为 1920x1080避免全屏切换带来的采集问题。3.2 Python 环境与依赖建议使用虚拟环境python -m venv venv source venv/bin/activate # Windows 下为 venv\Scripts\activate安装依赖pip install mss opencv-python pyautogui pillow requests如果你的 VLM 和 LLM 使用 OpenAI 兼容接口需要额外安装pip install openai或者直接使用requests调用 HTTP 接口避免引入过多 SDK。3.3 项目目录结构ai_game_agent/ ├── main.py # 主循环 ├── capture.py # 屏幕采集与预处理 ├── describer.py # 图像转描述 ├── brain.py # 决策模块 ├── controller.py # 键鼠控制 ├── prompts.py # 提示词模板 ├── config.py # 配置文件 └── logs/ ├── frames/ # 异常帧截图 └── decisions.log # 决策日志4. 从零搭建一个可运行的 AI 游戏 Agent4.1 视觉采集模块 capture.py核心需求以固定频率抓取游戏窗口区域并对图像做基础预处理。# capture.py import time import mss import cv2 import numpy as np class ScreenCapture: def __init__(self, regionNone): # region: (left, top, width, height)默认全屏 self.region region self.sct mss.mss() def grab(self): monitor self.sct.monitors[1] if self.region: monitor { left: self.region[0], top: self.region[1], width: self.region[2], height: self.region[3], } img self.sct.grab(monitor) frame np.array(img) # mss 返回 BGRA转为 BGR frame cv2.cvtColor(frame, cv2.COLOR_BGRA2BGR) return frame def preprocess(self, frame, resize(512, 512)): # 统一尺寸减少 VLM 传输量 resized cv2.resize(frame, resize) return resized def save_debug_frame(self, frame, path): cv2.imwrite(path, frame) if __name__ __main__: cap ScreenCapture(region(0, 0, 1920, 1080)) frame cap.grab() processed cap.preprocess(frame) cap.save_debug_frame(processed, logs/frames/debug.png) print(capture ok, shape , processed.shape)这段代码的核心是mss它比pyautogui.screenshot()更快适合连续采集。preprocess里统一缩放是为了降低图片体积推理速度会快很多。4.2 视觉描述模块 describer.py这里以 OpenAI 兼容的 VLM 接口为例。假设你有一个支持图像输入的模型服务传入图片 base64 后返回画面描述。# describer.py import base64 import cv2 import requests def encode_frame_to_base64(frame): _, buffer cv2.imencode(.jpg, frame, [cv2.IMWRITE_JPEG_QUALITY, 85]) return base64.b64encode(buffer).decode(utf-8) class VisionDescriber: def __init__(self, api_url, api_key, model): self.api_url api_url self.api_key api_key self.model model def describe(self, frame, task_hint): b64_img encode_frame_to_base64(frame) prompt ( 你是一个游戏画面分析师。请用中文简洁描述当前画面中的以下要素\n 1. 玩家位置若可见\n 2. 场景类型室内/室外/城镇/野外/菜单/黑屏\n 3. 可交互对象NPC、门、物品等\n 4. 当前 UI 状态是否有对话、任务、物品栏\n 5. 是否有异常黑屏、加载中、卡死\n f额外任务提示{task_hint}\n 描述不超过 120 字。 ) payload { model: self.model, messages: [ { role: user, content: [ {type: text, text: prompt}, { type: image_url, image_url: { url: fdata:image/jpeg;base64,{b64_img} }, }, ], } ], } headers {Authorization: fBearer {self.api_key}} resp requests.post(self.api_url, jsonpayload, headersheaders, timeout30) resp.raise_for_status() return resp.json()[choices][0][message][content]注意不同模型服务的请求格式可能存在差异核心是把“图片 base64 文本提示词”一起交出去。生产环境建议增加超时重试。4.3 决策模块 brain.py决策模块负责根据 VLM 描述和当前任务生成下一步动作。动作可以抽象成以下几种原语move direction移动direction 为 forward/back/left/rightinteract交互E 键attack攻击open_menu打开菜单wait等待use_item name使用物品。为了让 LLM 输出稳定我们严格限制输出格式为 JSON。# brain.py import json import re class Brain: def __init__(self, llm_call_func, sys_prompt): self.llm_call_func llm_call_func self.sys_prompt sys_prompt def decide(self, scene_desc, task, memory): user_prompt f 当前任务{task} 画面描述{scene_desc} 记忆{memory[-5:]} 请选择下一步动作并严格输出以下 JSON 格式 {{action: move, parameter: forward, reason: 简短理由}} 可选 actionmove / interact / attack / open_menu / wait / use_item 可选 parameterforward / back / left / right / 物品名 / 空字符串 reply self.llm_call_func(self.sys_prompt, user_prompt) return self._parse_reply(reply) staticmethod def _parse_reply(text): try: return json.loads(text) except json.JSONDecodeError: match re.search(r\{.*\}, text, re.S) if match: return json.loads(match.group()) raise ValueError(f无法解析模型输出: {text})为了让代码可运行llm_call_func是一个你传入的函数。你可以选择调用 OpenAI SDK、本地 vLLM 服务或者随便写一个 mock 函数。4.4 动作执行模块 controller.py控制模块负责把决策结果映射成键盘鼠标操作。这里用pyautogui的按键按下/释放接口。# controller.py import time import pyautogui KEY_MAP { forward: w, back: s, left: a, right: d, } class Controller: def exec_action(self, action, parameter, duration0.3): if action move: key KEY_MAP.get(parameter, w) pyautogui.keyDown(key) time.sleep(duration) pyautogui.keyUp(key) elif action interact: pyautogui.press(e) elif action attack: pyautogui.click(buttonleft) elif action open_menu: pyautogui.press(tab) elif action wait: time.sleep(float(parameter or 1.0)) elif action use_item: # 简化按数字键 1 pyautogui.press(1) time.sleep(0.1)这里有一个很容易忽略的点动作执行后必须给游戏留出反应时间。如果采集频率太高画面还没刷新AI 会重复执行上一个动作导致角色原地抽搐。4.5 主循环 main.py现在把模块串起来。# main.py import time import threading from collections import deque from capture import ScreenCapture from describer import VisionDescriber from brain import Brain from controller import Controller def mock_llm(system, user): # 这里替换成你的真实 LLM 调用 # 为了演示返回固定动作 return {action: move, parameter: forward, reason: demo} def main(): cap ScreenCapture(region(0, 0, 1920, 1080)) describer VisionDescriber( api_urlhttps://your-vlm-endpoint/v1/chat/completions, api_keyYOUR_KEY, modelyour-vlm-model, ) brain Brain(llm_call_funcmock_llm, sys_prompt你是一个游戏策略规划师。) controller Controller() task 前往最近的城镇 memory deque(maxlen10) frame_count 0 while True: frame cap.grab() processed cap.preprocess(frame) frame_count 1 if frame_count % 10 0: try: desc describer.describe(processed, task_hinttask) decision brain.decide(desc, task, memory) controller.exec_action(decision[action], decision[parameter]) memory.append(f{desc} - {decision}) print(f[{time.strftime(%H:%M:%S)}] {desc}) print(f决策: {decision}) except Exception as e: print(f异常: {e}) # 保存异常帧方便排查黑屏 cap.save_debug_frame(processed, flogs/frames/error_{int(time.time())}.png) time.sleep(1) if __name__ __main__: main()这个主循环每 1 秒采集一次每 10 次调用一次 VLM。实际使用时频率要根据机器性能调整。注意这里的mock_llm只是为了让你跑通流程真正决策时必须接真实模型。5. 黑屏问题专题排查5.1 现象描述AI 运行一段时间后describe返回“当前画面为黑色”或者保存的调试帧截图完全是黑色的。此时决策模块拿不到任何有效信息AI 开始随机乱走或者卡住不动。5.2 可能原因黑屏不一定是模型问题更可能是采集链路出了问题。我把常见原因整理成了一张表原因分类具体原因概率采集窗口失效游戏切换到全屏、分辨率变化、窗口被遮挡高采集权限macOS 或 Windows 屏幕录制权限被回收中硬件加速游戏使用硬件加速渲染mss抓不到独显输出中游戏自身状态加载界面、过场动画、休眠高图像压缩异常OpenCV 编码失败base64 为空低5.3 排查步骤我建议按以下顺序排查速度最快人工查看游戏窗口游戏是否正常显示如果游戏本身黑屏问题在游戏不在 Agent。单独运行capture.py观察logs/frames/debug.png是否为黑。如果 debug 图黑说明采集链路有问题。检查游戏显示模式尽量使用“窗口化全屏”或“无边框窗口”不要用独占全屏。检查采集区域坐标如果你写死了region但游戏分辨率变了采集区域会偏掉。检查权限Windows 设置 - 隐私 - 屏幕录制macOS 系统设置 - 隐私与安全性 - 屏幕录制。检查 VLM API把 debug.png 用其他工具打开手动上传给 VLM确认模型能正常描述。5.4 解决方案针对不同原因给出对应解决方案游戏窗口变化每次采集前通过窗口标题获取最新窗口矩形而不是用固定坐标。# 使用 pygetwindow 获取窗口坐标示例 import pygetwindow as gw win gw.getWindowsWithTitle(Skyrim)[0] region (win.left, win.top, win.width, win.height)权限被回收重新授权然后重启 Python 进程。黑屏帧检测在capture.py中增加黑屏检测如果平均亮度低于阈值则跳过本次推理并保存日志。def is_black_frame(frame, threshold10): gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) return gray.mean() threshold使用无边框窗口在游戏设置里把显示模式改为“无边框窗口”或“窗口化”。5.5 如何预防黑屏问题很难完全避免但可以通过以下手段降低出现次数不要独占全屏固定分辨率关闭动态分辨率在 VLM 描述提示词中明确要求识别“黑屏”状态增加黑屏重试机制连续 N 帧黑屏后触发恢复操作比如按 Esc 或等待加载建立异常帧自动保存机制方便事后复盘。6. 与 my_ai_town 开源项目的结合6.1 项目简介输入材料里提到了一个开源项目https://github.com/mewamew/my_ai_town。从名字来看这是一个“AI 小镇”类项目核心思路是让多个 AI 角色在小镇环境中自主生活、交流、协作。这种项目通常包含三类基础能力角色记忆、环境感知、行为决策。虽然它面向的是虚拟小镇而不是 RPG 游戏但底层逻辑和游戏 Agent 高度相似环境感知 - 对应游戏画面采集角色记忆 - 对应游戏任务状态记忆行为决策 - 对应动作生成行为执行 - 对应键盘鼠标操作。6.2 从 AI 小镇到 RPG 游戏的扩展思路如果my_ai_town已经实现了角色决策框架我们可以把它的决策内核抽取出来替换掉本文中的Brain。改造关键点如下将“小镇环境状态”映射为“游戏画面描述”将“角色交流”映射为“与 NPC 对话”将“移动行为”映射为“WASD 按键操作”将“物品管理系统”映射为“游戏物品栏读取”。这种抽象方式让同一个 Agent 框架可以适配不同环境也是当前 AI Agent 工程化的主流做法。6.3 可复用的模块建议无论你是从零开始还是参考开源项目都建议把以下模块独立出来记忆模块保存“历史画面描述 动作 结果”用于避免重复决策任务规划模块把大目标拆成小步骤异常恢复模块统一处理黑屏、卡死、加载中回放模块把截图和决策日志按时间戳组织便于调试。7. 常见问题与应对思路问题现象常见原因解决思路VLM 返回超时网络慢或图片太大压缩图片尺寸、提高超时时间、增加重试LLM 输出格式乱提示词不够严格使用 JSON mode或增加输出格式校验AI 原地打转移动执行后画面更新延迟增加动作后等待时间降低采集频率菜单打开后无法关闭决策模型不理解当前 UI在画面描述中明确 UI 状态加入菜单处理规则长时间无响应VLM 或 LLM 卡住增加看门狗线程超时自动跳过黑屏帧频繁出现游戏切换到全屏强制使用无边框窗口权限弹窗导致断线系统屏幕录制权限手动授权后重启进程8. 最佳实践与工程建议8.1 提示词工程游戏 Agent 的提示词要尽量结构化。不要让模型自由发挥否则输出根本无法执行。我的经验是给出“可选动作列表”给出“动作参数说明”要求输出标准 JSON每轮只做一步决策不要一步规划到底。8.2 日志与回放日志是调试游戏 Agent 最重要的工具。每轮循环至少记录时间戳画面描述模型决策动作执行结果当前任务状态。建议把截图统一保存到logs/frames/按时间戳命名。这样即使 AI 半夜跑崩了第二天也能根据日志和截图还原现场。8.3 性能优化游戏 Agent 的响应速度取决于三个瓶颈屏幕采集耗时VLM 推理耗时LLM 推理耗时。如果觉得太慢可以采用异步流水线采集线程和推理线程分离采集永远不等待推理。# 伪代码展示生产者消费者模式 frame_queue queue.Queue(maxsize3) def capture_worker(): while True: frame cap.grab() frame_queue.put(frame) def inference_worker(): while True: frame frame_queue.get() desc describer.describe(frame) action brain.decide(desc) controller.exec_action(action)这样即使推理耗时 3 秒采集也不会丢帧太多。8.4 安全边界这部分很重要。所有自动化操作只应作用于你自己拥有或明确授权的测试环境不要使用这类技术绕过游戏反作弊机制不要用于线上游戏牟利使用屏幕采集和键鼠控制时注意操作系统权限限制如果项目部署在公共环境确保 API Key 不泄露到代码仓库。9. 总结与下一步到这里一条 AI 游戏 Agent 的完整链路已经跑通了屏幕采集 - 图像描述 - 策略决策 - 动作执行 - 结果反馈。黑屏问题的核心在于采集链路失效排查时先看原始截图再逐步定位是游戏状态、窗口坐标、系统权限还是模型解析的问题。如果你对这类项目感兴趣下一步可以尝试引入长期记忆让 AI 记住上一个城镇的位置用本地 VLM 替换云端 API降低延迟参考my_ai_town的角色决策框架把单一游戏 Agent 扩展成多角色协作系统加入强化学习评价机制让 AI 根据任务完成度自动调整策略。游戏 Agent 离真正的“通用游戏智能”还有很长的路但每一步从黑屏排查开始积累的经验都会成为你理解多模态 AI 工程落地的宝贵素材。动手跑通第一个闭环比看再多的文章都有用。