play-any-game（玩任何游戏）

Play Any Game - AI游戏伴侣助手

项目定位

不是游戏代肝助手，而是游戏伴侣助手。

当你玩游戏时遇到困难：

• 🤔 不知道这个机关怎么解？
• 😵 卡在这个Boss打不过？
• 🤷 找不到NPC在哪？
• 😕 不知道这个界面怎么操作？

AI可以：

1. 截图分析 - 看到你的游戏画面，理解当前状态
2. 解答问题 - 告诉你该怎么解决
3. 简单操作 - 帮你点击界面、解决问题

核心设计理念

每次操作都有截图，让 AI 能看到操作后的效果，然后继续下一步操作。

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   AI 分析截图 ──→ 执行操作 ──→ 自动截图 ──→ 返回给 AI      │
│        ↑                                           │        │
│        └───────────────────────────────────────────┘        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

按钮识别方案

使用多模态大模型直接识别界面元素，通过自然语言描述定位按钮：

# 通过文字描述点击按钮
python main.py click_text "地图按钮" "原神"
python main.py click_text "快速编队按钮" "原神"
python main.py click_text "确认按钮" "原神"

优点：

• 无需预设按钮模板
• 支持动态界面
• 自然语言描述，灵活直观
• 适用于各种游戏

支持的游戏

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

依赖说明：

如果安装速度慢，使用国内镜像：

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：

1. 前往 阿里云百炼平台
2. 注册/登录账号
3. 在 "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 命令

基础命令

AI 识图命令

配置命令

游戏会话命令

游戏会话命令用于 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"
}

点击模式

1. 前台点击模式（默认）

- 使用 mouse_event API 模拟真实鼠标 - 需要窗口在前台 - 会移动真实鼠标光标

1. 后台点击模式（--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)

添加新游戏支持

1. 在 games/ 目录下创建游戏文件夹
2. 创建 SOUL.md - AI 角色设定
3. 创建 SKILL.md - 游戏子技能说明

SOUL.md 模板

# 角色名 - 游戏名助手

## 基本信息

- **名称**: 角色名
- **身份**: 角色身份
- **性格**: 角色性格
- **口头禅**: "口头禅"

## 核心能力

- 游戏画面实时分析
- 游戏知识问答
- 自动化操作

注意事项

• 游戏窗口可见：AI 需要游戏窗口在可见状态才能分析画面
• 辅助性质：AI 只是辅助玩家解决问题，不是全自动挂机
• 策略判断：需要真正策略判断的高难度内容仍需玩家自己操作
• API Key 保护：不要将 API Key 提交到 git 仓库

参考资料

📖 详细的安装说明、模型信息、使用示例请查阅 README.md

• README.md - 项目介绍、安装指南、使用截图
• AGENTS.md - 项目规则
• games/genshin-impact/SOUL.md - 派蒙角色设定
• games/honkai-starrail/SOUL.md - 三月七角色设定
• 阿里云 GUI-Plus 文档

🌐 开源仓库

• play-any-game：https://github.com/CGandGameEngineLearner/play-any-game.git
• 派蒙.skill：https://github.com/CGandGameEngineLearner/paimon-skill.git