Play Any Game - AI游戏伴侣助手
项目定位
不是游戏代肝助手，而是游戏伴侣助手。
当你玩游戏时遇到困难：
- 🤔 不知道这个机关怎么解？
- 😵 卡在这个Boss打不过？
- 🤷 找不到NPC在哪？
- 😕 不知道这个界面怎么操作？
AI可以：
- 截图分析 - 看到你的游戏画面，理解当前状态
- 解答问题 - 告诉你该怎么解决
- 简单操作 - 帮你点击界面、解决问题
核心设计理念
每次操作都有截图，让 AI 能看到操作后的效果，然后继续下一步操作。
┌─────────────────────────────────────────────────────────────┐
│ │
│ AI 分析截图 ──→ 执行操作 ──→ 自动截图 ──→ 返回给 AI │
│ ↑ │ │
│ └───────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
按钮识别方案
使用多模态大模型直接识别界面元素，通过自然语言描述定位按钮：
# 通过文字描述点击按钮
python main.py click_text "地图按钮" "原神"
python main.py click_text "快速编队按钮" "原神"
python main.py click_text "确认按钮" "原神"
优点：
- 无需预设按钮模板
- 支持动态界面
- 自然语言描述，灵活直观
- 适用于各种游戏
支持的游戏
| 游戏 | AI 角色 | 窗口标题 |
|---|
| 原神 | 派蒙 | "原神" |
| 崩坏：星穹铁道 | 三月七 | "崩坏：星穹铁道" |
SOUL 切换机制
OpenClaw 使用此技能时，通过 game 命令切换 SOUL：
用户说：我要玩原神
→ OpenClaw 调用: python main.py game start 原神
→ 返回: { soulPath: "games/genshin-impact/SOUL.md" }
→ OpenClaw 读取 SOUL.md → 替换系统提示
→ AI 化身为派蒙与用户交互
用户说：不玩了
→ OpenClaw 调用: python main.py game end
→ 返回: { soulPath: "games/default/SOUL.md" }
→ OpenClaw 恢复默认 SOUL
目录结构
.trae/skills/play-any-game/
├── scripts/ # Python 核心模块
│ ├── click.py # 点击功能
│ ├── keyboard.py # 键盘功能
│ ├── screenshot.py # 截图功能
│ ├── window.py # 窗口管理
│ ├── config.py # 配置管理
│ └── gui_agent/ # 多模态 AI 识图模块
│ ├── base.py # 抽象基类
│ ├── aliyun.py # 阿里云 GUI-Plus 实现
│ └── factory.py # 工厂模式
├── games/ # 游戏定制目录
│ ├── games.json # 游戏配置
│ ├── default/ # 默认 SOUL
│ │ └── SOUL.md # OpenClaw 默认人设
│ ├── genshin-impact/ # 原神
│ │ └── SOUL.md # 派蒙角色设定
│ └── honkai-starrail/ # 崩坏：星穹铁道
│ └── SOUL.md # 三月七角色设定
├── screenshots/ # 截图存储目录
├── config.json # 配置文件
├── main.py # CLI 入口
└── requirements.txt # Python 依赖
环境要求与安装指南
🤖 Agent 必读：使用此 skill 前，必须确保 Python 3 环境和所有依赖已正确安装。请按照以下步骤逐一执行。
系统要求
- OS: Windows 10/11（使用 Win32 API 控制窗口和鼠标）
- Python: 3.8 或更高版本
- 网络: 需要能访问阿里云 API（用于 AI 识图）
🐍 Step 1：检查并安装 Python 3
首先检查 Python 是否已安装：
python --version
如果命令不存在或版本低于 3.8，按以下方式安装：
# 推荐：使用 winget（Windows 10/11 内置包管理器）
winget install Python.Python.3.12
安装完成后，关闭并重新打开终端，然后验证：
python --version # 应输出 Python 3.12.x（或 3.8+）
pip --version # 应输出 pip 版本信息
⚠️ 若 python 命令仍不可用，请检查安装时是否勾选了 "Add Python to PATH"。可以重新运行安装程序，选择 "Modify" → 勾选 "Add Python to PATH"。
📦 Step 2：安装 Python 依赖
# 进入 skill 目录（根据实际路径调整）
cd skills/play-any-game
# 安装所有依赖
pip install -r requirements.txt
依赖说明：
| 包名 | 版本要求 | 用途 |
|---|
pywin32 | >=306 | Windows 窗口管理、鼠标/键盘控制（Win32 API） |
Pillow | >=10.0.0 | 图像处理、截图保存 |
opencv-python | >=4.8.0 | 图像识别、模板匹配 |
numpy | >=1.24.0 | 数值计算（opencv 依赖） |
openai | >=1.0.0 | 调用阿里云 GUI-Plus AI 模型 API |
如果安装速度慢，使用国内镜像：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
安装后验证依赖：
python -c "import win32api, PIL, cv2, numpy, openai; print('All dependencies OK')"
🔑 Step 3：配置 API Key
此 skill 使用阿里云百炼平台的 GUI-Plus 模型进行 AI 识图。
# 方式1：命令行配置（推荐，持久保存到 config.json）
python main.py config --set-api-key YOUR_DASHSCOPE_API_KEY
# 方式2：环境变量（临时生效，重启终端后失效）
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
获取 API Key：
- 前往 阿里云百炼平台
- 注册/登录账号
- 在 "API-KEY 管理" 页面创建新的 API Key
✅ Step 4：验证安装
# 测试1：列出所有窗口（验证 pywin32 正常）
python main.py windows
# 测试2：截取屏幕（验证 Pillow/截图功能正常）
python main.py screenshot
# 测试3：查看当前配置（验证 API Key 已设置）
python main.py config --show
全部命令正常输出，说明环境安装完成。
CLI 命令
基础命令
| 命令 | 说明 | 示例 |
|---|
screenshot [窗口] | 截取屏幕 | python main.py screenshot |
capture <窗口> | 截取指定窗口 | python main.py capture "原神" |
click <x> <y> [窗口] | 点击坐标 | python main.py click 540 820 "原神" |
key <按键> [窗口] | 按键 | python main.py key Space "原神" |
hold <按键> <毫秒> [窗口] | 按住按键 | python main.py hold W 1000 "原神" |
windows | 列出所有窗口 | python main.py windows |
AI 识图命令
| 命令 | 说明 | 示例 |
|---|
click_text <描述> [窗口] | AI识图点击 | python main.py click_text "地图按钮" "原神" |
click_text <描述> --dry-run | 仅分析不执行 | python main.py click_text "确认" --dry-run |
click_text <描述> --provider <模型> | 指定模型 | python main.py click_text "地图" --provider gui-plus-2026-02-26 |
配置命令
| 命令 | 说明 | 示例 |
|---|
config --set-api-key <KEY> | 设置 API Key | python main.py config --set-api-key sk-xxx |
config --show | 显示当前配置 | python main.py config --show |
config --list-agents | 列出可用模型 | python main.py config --list-agents |
游戏会话命令
| 命令 | 说明 | 示例 |
|---|
game list | 列出支持的游戏 | python main.py game list |
game start <游戏> | 开始游戏会话 | python main.py game start 原神 |
game end | 结束游戏会话 | python main.py game end |
game current | 显示当前游戏 | python main.py game current |
游戏会话命令用于 SOUL 切换：
# 开始玩原神 → AI 化身为派蒙
python main.py game start 原神
# 返回: { soulPath: "games/genshin-impact/SOUL.md", character: "派蒙" }
# 不玩了 → 恢复默认 SOUL
python main.py game end
# 返回: { soulPath: "games/default/SOUL.md", character: "OpenClaw" }
支持的游戏关键词：
- 原神：原神、genshin、派蒙、paimon
- 星铁：星穹铁道、星铁、starrail、崩铁、三月七
命令返回格式
所有命令返回标准 JSON 格式：
{
"action": "click_text",
"text": "地图按钮",
"windowTitle": "原神",
"x": 120,
"y": 90,
"provider": "aliyun",
"model": "gui-plus",
"screenshotPath": "screenshots/原神/screenshot_xxx.png",
"afterScreenshotPath": "screenshots/原神/screenshot_xxx.png",
"timestamp": "2026-04-05T20:00:00.000000"
}
点击模式
-
前台点击模式（默认）
- 使用
mouse_event API 模拟真实鼠标
- 需要窗口在前台
- 会移动真实鼠标光标
-
后台点击模式（--background）
- 使用
PostMessage 发送窗口消息
- 不抢夺鼠标，可在后台运行
- 部分游戏可能拦截
原神特殊处理
原神游戏中所有 UI 点击操作需要同时按住 Alt 键：
- 点击前自动按住 Alt 键
- 点击完成后释放 Alt 键
- 代码已自动处理，无需手动操作
典型工作流
AI 识图点击
# 1. 通过文字描述点击按钮
python main.py click_text "地图按钮" "原神"
# AI 分析截图，找到按钮位置，执行点击，返回点击前后截图
# 2. 仅分析不执行
python main.py click_text "确认按钮" "原神" --dry-run
# 返回识别到的坐标，不执行点击
帮玩家操作界面
# 1. 截图分析当前状态
python main.py capture "原神"
# AI 分析截图，发现需要点击某个按钮
# 2. 点击按钮
python main.py click 540 820 "原神"
# 返回点击后的截图，AI 确认操作成功
扩展新模型
from scripts.gui_agent import register_agent, BaseGUIAgent
class NewGUIAgent(BaseGUIAgent):
@property
def name(self) -> str:
return "new-model"
def analyze(self, screenshot, instruction, **kwargs):
# 实现调用新模型 API
pass
register_agent("new-model", NewGUIAgent)
添加新游戏支持
- 在
games/ 目录下创建游戏文件夹
- 创建
SOUL.md - AI 角色设定
- 创建
SKILL.md - 游戏子技能说明
SOUL.md 模板
# 角色名 - 游戏名助手
## 基本信息
- **名称**: 角色名
- **身份**: 角色身份
- **性格**: 角色性格
- **口头禅**: "口头禅"
## 核心能力
- 游戏画面实时分析
- 游戏知识问答
- 自动化操作
注意事项
- 游戏窗口可见：AI 需要游戏窗口在可见状态才能分析画面
- 辅助性质：AI 只是辅助玩家解决问题，不是全自动挂机
- 策略判断：需要真正策略判断的高难度内容仍需玩家自己操作
- API Key 保护：不要将 API Key 提交到 git 仓库
参考资料
📖 详细的安装说明、模型信息、使用示例请查阅 README.md
🌐 开源仓库
