INTERNAL · 战略研究部 · 工具文档

# game-analyst-agent 工具说明书

通用产品分析自动化工具 — 自动探索游戏/网页界面、提取机制与数值、多游戏对比、活动追踪、市场数据采集、决策报告生成
1.7.0 2026-05-22 游戏分析师、制作人、策划、市场研究员、产品经理 Windows / macOS + Python 3.10+
核心能力
自动探索界面
机制规则提取
数值事实采集
多游戏横向对比
活动变化追踪
决策报告生成
覆盖范围
Android 游戏（模拟器）
H5 / 网页游戏
竞品官网
市场数据页面
使用方式
命令行启动
挂机无人值守
定期查看增量报告
按需生成决策报告
运行成本
探索阶段：免费
分析阶段：国产模型
24h 连续运行 < 1 元

## 一、工具定位与设计理念

为什么需要这个工具，它解决什么问题，不做什么。

### 1.1 解决的核心问题

游戏分析师在做竞品深拆、项目选型调研时，需要大量时间手动体验游戏、截图记录、整理机制规则、采集市场数据、横向对比。一款中度游戏的完整系统拆解通常需要 3-5 天人工投入，多游戏对比更是倍数级工作量。

game-analyst-agent 将整条分析链路自动化：

- 自动探索游戏界面（Android 模拟器）或网页（浏览器模式）
- 自动截图、去重、提取机制规则和数值事实
- 多游戏横向对比，生成结构化对比报告
- 定时重跑追踪竞品活动变化
- 采集市场数据页面信息
- 生成面向管理层的决策报告

设计理念
工具定位是产品分析自动化辅助，不替代人工判断。它负责把信息「采集、结构化、对比、呈现」，分析师负责基于这些信息做商业判断和策略建议。

### 1.2 核心设计原则

- 不依赖手动截图 — 工具自动完成所有界面采集，人工不参与运行期操作
- 不针对特定产品 — 不硬编码任何游戏/网站的坐标或导航路径，对任意目标零配置启动
- 可长时间无人值守 — 支持 24h+ 连续运行，用时间换覆盖率，按固定频率输出进度报告
- 双模式覆盖 — Android 模拟器（手游）+ Playwright 浏览器（网页/H5/市场数据）
- 从采集到决策的完整链路 — 探索 → 提取 → 对比 → 追踪 → 报告，一条工具链闭环

### 1.3 不做什么

- 不直接输出体验评价结论或商业化建议（这是分析师的工作）
- 不做外挂式自动操作（不刷资源、不代打）
- 不需要逆向游戏协议或破解 APK

## 二、核心能力总览

工具当前已具备的全部能力，分为六大模块。

自主界面探索
Android 模拟器 + 浏览器双模式
感知哈希去重，不重复探索
BFS 导航 + 自动回退
长按 / 悬停 / 边缘抽屉发现
弹窗自动关闭 + Cookie 处理
自适应无限滚动 + 暗色主题适配
机制规则 + 数值提取
AI 视觉模型分析截图
提取规则并按系统模块分类
提取数值事实（定价/时间/消耗量）
资源流转拓扑自动推断
多游戏横向对比
跨游戏规则按 module 对齐
自动标注差异点
生成 HTML 对比矩阵报告
活动追踪与时间线
定时重跑检测界面变化
追踪限时活动上下线
输出变化时间线
市场数据采集
浏览器模式采集数据页面
七麦 / SensorTower / 榜单
补充市场表现维度
决策报告生成
多游戏数据 + AI 综合分析
面向管理层的推荐格式
可直接用于项目评审会

### 2.1 探索智能（v1.7）

探索引擎内置 9 级优先级决策链，模拟真实用户的全部交互行为：

交互覆盖
点击（tap）+ 长按（long press）
垂直/水平滚动 + 自适应无限滚动
边缘抽屉滑动（侧边栏/下拉面板）
浏览器悬停（hover）展开子菜单
干扰处理
弹窗自动检测 + 关闭（签到/活动/礼包）
Cookie/隐私同意弹窗自动关闭
加载动画等待（画面稳定再操作）
暗色主题自适应检测阈值
覆盖率保障
角落小图标检测（?/!/设置）
Tab 栏等距按钮检测
DOM 元素精确识别（浏览器模式）
pHash 变化驱动的自适应决策

### 2.2 基础支撑能力

多模型后端
Claude / 通义千问 / GLM-4V / 豆包
按需切换成本与精度
规则去重与分类
自动去除重复规则
按 module 分组归档
置信度分层标注
容错与恢复
ADB 断连自动重连
API 失败重试后跳过
探索引擎自动回退不卡死

### 2.3 完整工作流程

┌──────────────────────────────────────────────────────────────┐ │ 单游戏深拆链路 │ ├──────────────────────────────────────────────────────────────┤ │ │ │ explore（Android / 浏览器） │ │ │ │ │ ├─ 探索阶段（本地，成本 = 0） │ │ │ 截图 → pHash 去重 → 9 级智能决策： │ │ │ 弹窗关闭 → 边缘抽屉 → tap → 滚动 → 自适应滚动 │ │ │ → 长按 → 悬停(浏览器) → 回退 │ │ │ │ │ ├─ 分析阶段（定时，可控成本） │ │ │ 批量截图 → AI 视觉模型 → 规则 + 数值事实 → DB │ │ │ → 资源流转推断 │ │ │ │ │ └─ 报告阶段（自动） │ │ 每 30min → 进度报告 ｜ 探索结束 → 最终报告 │ │ │ └──────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────┐ │ 多游戏对比 + 决策链路 │ ├─────────────────────────────────────────────────────────┤ │ │ │ compare → 跨游戏规则对齐 → 差异标注 → 对比报告 HTML │ │ timeline → 定时重跑 → 活动上下线检测 → 变化时间线 │ │ market → 浏览器采集数据页 → 市场数据补充 │ │ decision-report → 多游戏数据 + AI 综合推断 → 决策报告 │ │ │ └─────────────────────────────────────────────────────────┘

## 三、技术架构

工具的内部结构，供技术背景的使用者了解运行原理。非技术用户可跳过本节，不影响正常使用。

### 3.1 模块架构

模块 | 文件 | 职责
--- | --- | ---
设备驱动 | `core/adb_device_driver.py` | 通过 ADB 控制模拟器：截图、点击、长按、滑动、返回
探索引擎 | `core/explorer.py` | 9 级优先级决策引擎：弹窗→抽屉→tap→滚动→自适应滚动→长按→回退
画面去重 | `core/screen_dedup.py` | 感知哈希（pHash）计算、Screen 库持久化、重复判定
本地检测 | `core/local_detector.py` | 视觉检测按钮/色块/Tab 栏/角落图标/弹窗覆盖层，暗色主题自适应
模型后端 | `core/llm_backend.py` | 统一接口调用多种视觉 AI 模型（OpenAI 兼容 + Anthropic）
批量分析 | `core/batch_analyzer.py` | 定时收集新截图、调用模型提取规则、写入数据库
报告生成 | `core/reporter.py` | 增量进度报告 + 最终完整报告生成
数据存储 | `core/db_client.py` | SQLite 数据库：screens / rules / facts / sessions 表
浏览器驱动 | `core/browser_driver.py` | Playwright 驱动：截图、点击、滚动、长按、悬停、DOM 感知、Cookie 弹窗处理
数值提取 | `core/fact_extractor.py` | 从 AI 分析结果中解析结构化数值事实
资源流转 | `core/flow_inferrer.py` | 从 rules + facts 推断资源流转拓扑关系
CLI 入口 | `tools/cli.py` | 命令行路由：explore / compare / timeline / market / decision-report / report / doctor / init

### 3.2 两阶段成本分离

探索阶段
纯本地运算：OpenCV 视觉检测 + pHash 去重 + 9 级智能决策 + 设备操作。成本 = 0，可无限运行。
分析阶段
定时批量调用视觉模型。使用国产模型（通义千问）时，24 小时连续分析成本 < 1 元人民币。

### 3.3 数据存储结构

SQLite 数据库（games/{game_id}/db/mechanics.db） ├── screens 界面库：phash、访问次数、深度、分析状态 ├── rules 机制规则：规则文本、module 分类、置信度、来源截图 ├── facts 数值事实：属性名、数值、单位、关联系统 ├── resource_flows 资源流转：source → target、消耗量、触发条件 └── sessions 运行记录：时长、发现界面数、规则数、成本

## 四、安装与环境配置

从零开始，3 分钟完成安装。

### 4.1 前提条件

依赖 | 要求 | 说明
--- | --- | ---
操作系统 | Windows 10/11（推荐） | Windows 推荐；macOS 需额外配置模拟器
Python | 3.10 或更高 | 推荐使用 uv 安装管理
Android 模拟器 | MuMu Player 12（推荐） | 需开启 ADB 调试，默认端口 16384
模型 API Key | 至少一个 | 推荐阿里通义千问（性价比）或 Anthropic Claude（精度）

### 4.2 安装步骤

安装流程
1
获取代码：`git clone <repo_url>` 然后 `cd game-analyst-agent`
2
安装依赖：`pip install -e .`（基础安装）或 `pip install -e ".[all]"`（含浏览器模式 + 定时任务）
3
配置 API Key：`cp .env.example .env`，用文本编辑器打开 `.env`，填入你的 Key
4
环境自检：`game-analyst doctor`，全部 ✓ 表示就绪
可选依赖说明

- `pip install -e ".[browser]"` — 安装 Playwright，启用浏览器模式和市场数据采集
- `pip install -e ".[schedule]"` — 安装 croniter，启用定时重跑功能
- `pip install -e ".[all]"` — 安装全部可选依赖

### 4.3 API Key 获取方式

模型供应商 | 环境变量名 | 获取地址 | 参考价格
--- | --- | --- | ---
阿里通义千问-VL | `DASHSCOPE_API_KEY` | dashscope.aliyun.com | 约 0.003 元/张
字节豆包 Vision | `ARK_API_KEY` | volcengine.com/product/ark | 约 0.002 元/张
智谱 GLM-4V | `ZHIPU_API_KEY` | open.bigmodel.cn | 约 0.005 元/张
Anthropic Claude | `ANTHROPIC_API_KEY` | console.anthropic.com | 约 0.02 元/张

推荐配置
日常使用选阿里通义千问，成本极低且精度满足规则提取需求。需要高精度推断（如商业化结构分析）时切换 Claude。

## 五、使用指南

从启动到查看报告的完整操作流程。

### 5.1 初始化游戏

game-analyst init --game my_garden # 输出： # 已创建游戏配置：games/my_garden/ # 请编辑 games/my_garden/game.yaml 填写游戏名称和设备信息

打开 `games/my_garden/game.yaml`，只需修改游戏名称：

game: name: "我的花园世界" id: my_garden device: serial: "127.0.0.1:16384" # MuMu 默认端口

### 5.2 启动探索

# 确保模拟器已打开，游戏已进入主界面 # 启动（默认 24h 运行，每 30min 输出报告） game-analyst explore --game my_garden # 自定义参数 game-analyst explore --game my_garden \ --max-runtime 4 \ --analysis-interval 15 \ --max-depth 8

参数 | 说明 | 默认值
--- | --- | ---
`--game` | 游戏 ID（对应 games/ 下的目录名） | 必填
`--device` | ADB 设备地址 | 127.0.0.1:16384
`--max-runtime` | 最大运行时长（小时） | 24
`--analysis-interval` | AI 分析触发频率（分钟） | 30
`--max-depth` | 探索最大深度（从主界面算起的层级数） | 6
`--analyze-only` | 只对已有截图重新分析，不启动探索 | 关闭

### 5.3 查看进度

# 命令行查看状态 game-analyst status --game my_garden # 直接读报告文件 cat reports/my_garden/latest_progress.md

### 5.4 生成最终报告

# Markdown 格式（按系统模块分章节） game-analyst report --game my_garden # HTML 格式（可直接发给非技术用户浏览） game-analyst report --game my_garden --format html --standalone

### 5.5 完整 CLI 命令一览

命令 | 用途 | 使用场景
--- | --- | ---
`game-analyst explore` | 启动自主探索 | 挂机跑游戏/网页深拆
`game-analyst status` | 查看当前探索状态 | 中途了解进度
`game-analyst report` | 生成/重新生成分析报告 | 探索结束后导出最终报告
`game-analyst compare` | 多游戏横向对比报告 | 对比多款游戏的机制/商业化结构
`game-analyst timeline` | 活动追踪与变化时间线 | 定时重跑后查看竞品活动上下线
`game-analyst market` | 市场数据采集 | 通过浏览器采集七麦/SensorTower 等页面数据
`game-analyst decision-report` | 决策报告生成 | 基于多游戏数据生成面向管理层的推荐报告
`game-analyst doctor` | 环境自检 | 首次安装或排查问题
`game-analyst init` | 初始化新游戏配置 | 分析一款新游戏/网站前

### 5.6 多游戏对比

当你已对多款游戏完成探索后，可以生成横向对比报告：

# 对比 3 款游戏的商业化和核心循环 game-analyst compare --games my_garden,merge_mansion,gardenscapes \ --dimensions monetization,core_loop,progression # 只对比商业化维度 game-analyst compare --games my_garden,merge_mansion --dimensions monetization

输出为 HTML 格式对比报告，包含：各游戏按 module 对齐的规则矩阵、差异点标注（"A 有但 B 无"）、各维度优劣小结。可直接发送给同事在浏览器中查看。

### 5.7 浏览器模式探索

对网页游戏、竞品官网或市场数据页面进行探索分析：

# 探索 H5 网页游戏 game-analyst explore --game h5_game --driver browser --url "https://game.example.com" # 采集市场数据页面 game-analyst market --game my_garden --url "https://www.qimai.cn/app/..." --headless

浏览器模式自动利用 DOM 结构精确识别可交互元素，覆盖率高于纯视觉检测。需安装可选依赖：`pip install game-analyst-agent[browser]`

### 5.8 活动追踪与时间线

# 查看最近 7 天的变化记录 game-analyst timeline --game my_garden --last 7 # 输出为 HTML 格式 game-analyst timeline --game my_garden --last 30 --format html

需先对同一游戏进行过多次探索（不同日期），工具会自动对比各次结果，标注新增/消失的界面和规则。

### 5.9 决策报告

# 生成面向管理层的项目选型支撑报告 game-analyst decision-report \ --games my_garden,merge_mansion,gardenscapes \ --question "花园经营赛道哪款产品的商业化结构最适合小团队复制"

输出 HTML 格式决策报告：结论先行 + 对比矩阵 + 数据支撑 + 风险提示 + 建议。可直接用于项目评审会。

## 六、输出产物说明

工具运行后产出哪些文件，各自的用途和阅读方式。

### 6.1 目录结构

game-analyst-agent/ ├── games/ │ └── my_garden/ │ ├── game.yaml 游戏配置 │ ├── db/mechanics.db SQLite 数据库（规则、截图索引、运行记录） │ ├── screenshots/explore/ 探索模式截图（按 pHash 命名） │ └── logs/ 运行日志 ├── reports/ │ └── my_garden/ │ ├── latest_progress.md 最新增量进度报告（每 30min 更新） │ └── final_20260522.md 最终完整报告 └── .env API Key 配置（不分享）

### 6.2 增量进度报告（每 30 分钟）

自动生成于 `reports/{game}/latest_progress.md`，包含：

- 已探索的唯一界面数量
- 本轮新发现的规则列表
- 按 module 分类的规则统计
- 新发现率（判断是否接近探索饱和）
- 累计 AI 调用次数和估算成本

### 6.3 最终报告（按系统分模块）

探索结束后生成，结构示例：

## core_loop（核心循环） - 主循环为：种植鲜花 → 收获 → 完成订单 → 获取金币/经验 - 鲜花种植需要种子 + 花盆，花盆数量限制同时种植上限 ... ## resource（资源系统） - 金币：完成订单获得，用于购买种子和扩展花盆 - 元宝：付费货币，用于加速和抽奖 ... ## monetization（商业化） - 主要付费点：加速道具、稀有种子抽奖、礼包直售 - 公会竞赛推动竞争消费 ...

### 6.4 数据库直查（高级用法）

有 SQL 基础的用户可以直接查询数据库获取结构化数据：

# 查看各模块规则数量 sqlite3 games/my_garden/db/mechanics.db \ "SELECT module, COUNT(*) FROM rules GROUP BY module ORDER BY COUNT(*) DESC" # 导出所有高置信度规则 sqlite3 games/my_garden/db/mechanics.db \ "SELECT module, rule_text FROM rules WHERE confidence >= 0.8 ORDER BY module"

## 七、支持的模型与成本估算

工具的分析阶段支持多种视觉 AI 模型，可按需在成本和精度之间取舍。

### 7.1 成本模型

成本分离设计
探索阶段完全在本地运行（OpenCV + 感知哈希），成本为零。只有分析阶段（AI 模型看图提取规则）产生费用。分析频率可配置：降低频率 = 降低成本。

### 7.2 24 小时运行成本估算

模型 | 分析频率 | 24h 估算张数 | 24h 估算成本 | 精度评级
--- | --- | --- | --- | ---
通义千问-VL | 每 30min | ~200 张 | 约 0.6 元 | 够用
字节豆包 Vision | 每 30min | ~200 张 | 约 0.4 元 | 够用
智谱 GLM-4V | 每 30min | ~200 张 | 约 1.0 元 | 够用
Claude Sonnet | 每 30min | ~200 张 | 约 4.0 元 | 高精度

推荐策略
日常深拆用通义千问（成本最低，精度满足规则提取）。需要精细分析商业化结构或复杂系统时，对特定截图切换 Claude 做二次分析。

## 八、迭代路线图

工具的版本演进历程，全部功能已交付。

版本 | 能力 | 业务价值 | 状态
--- | --- | --- | ---
MVP | 自主探索 + 规则提取 + 增量报告 | 单游戏自动深拆 | 已完成
v1.1 | 多游戏对比报告 | 横向对比 3-5 款参照游戏，支撑项目选型 | 已完成
v1.2 | 数值事实提取 | 提取具体数值（定价/时间/消耗量），不止文字描述 | 已完成
v1.3 | 定时重跑 + 活动追踪 | 跟踪竞品运营节奏：限时活动、礼包更替、版本更新 | 已完成
v1.4 | 浏览器模式 + 市场数据采集 | 补充七麦/SensorTower 数据，形成完整视角 | 已完成
v1.5 | 决策报告模板 | 自动生成面向管理层的对比+推荐格式报告 | 已完成
v1.6 | 资源流转建模 + 探索策略优化 | 经济系统拓扑自动推断 + 界面覆盖率提升 | 已完成
v1.7 | 探索智能增强（8 项） | 模拟真实用户全部交互行为，消除覆盖盲区 | 已完成

### 8.1 各版本核心交付

版本 | 关键命令/能力
--- | ---
MVP | `explore` + `report` + `doctor` + `init` — 单游戏自动深拆闭环
v1.1 | `compare` — 跨游戏规则对齐 + 差异标注 + HTML 对比矩阵
v1.2 | facts 表 — 结构化数值事实提取（定价/时间/消耗量）
v1.3 | `timeline` — 定时重跑 + 活动上下线检测 + 变化时间线
v1.4 | `market` + BrowserDriver — 浏览器模式探索 + 市场数据页采集
v1.5 | `decision-report` — 多游戏综合分析 + 面向管理层的决策报告
v1.6 | resource_flows 表 + Tab 扫描 + 滚动探索 — 资源拓扑 + 覆盖率提升
v1.7 | 长按 / 弹窗关闭 / 边缘抽屉 / 悬停 / 加载等待 / 暗色适配 / 自适应滚动 / Cookie 处理

## 九、常见问题

使用中可能遇到的问题和解决方式。

Q: ADB 连接失败怎么办？
确认模拟器已启动且开启 ADB 调试。在终端运行 `adb connect 127.0.0.1:16384`，然后运行 `game-analyst doctor` 查看状态。MuMu 12 默认端口为 16384，如有多个模拟器实例端口会递增。
Q: 探索一直在同一个界面打转？
v1.7 起工具会自动检测并关闭弹窗（签到、活动、Cookie 同意等）。若仍出现打转，可能是非标准弹窗。检查日志 `games/{game}/logs/` 中的回退记录，或手动关闭后探索会自动继续。
Q: 分析结果中 "other" 分类太多怎么办？
这通常意味着模型对该游戏界面的理解不够精确。可以尝试：1) 切换到更强的模型（如 Claude）；2) 让工具运行更长时间积累更多界面，后续分析会利用上下文自动修正。
Q: 如何同时分析多款游戏？
开多个模拟器实例，每个实例打开不同游戏，分别启动：
game-analyst explore --game game_a --device 127.0.0.1:16384 game-analyst explore --game game_b --device 127.0.0.1:16416 # 第二个实例端口
Q: 如何把报告分享给不装工具的同事？
使用 `game-analyst report --game my_garden --format html --standalone` 生成单文件 HTML，用浏览器直接打开，无需任何安装。可以通过飞书/微信直接发送文件。
Q: 运行中电脑休眠或网络断了怎么办？
工具具备断线恢复机制：ADB 断连后会自动重试连接；API 调用失败会重试后跳过。已探索的数据不会丢失，重新启动后会从中断点继续。

## 十、适用场景与边界

工具擅长什么，不擅长什么，使用者需要明确的期望。

### 10.1 适合的场景

竞品机制拆解
对目标竞品的系统规则、数值、资源结构、商业化节点进行系统性采集
项目选型调研
横向对比多款同赛道产品，生成对比矩阵和决策报告
运营活动监控
定期重跑检测竞品活动上下线、礼包更替、版本变化
市场数据采集
浏览器模式采集七麦/SensorTower 等数据页面信息
H5/网页游戏分析
对浏览器中运行的 H5 游戏或网页应用进行界面探索和结构分析
新手流程评估
自动走完新手引导，记录每一步操作和界面变化

### 10.2 不适合的场景

以下场景超出工具能力范围

- 深层付费体验 — 工具不会付费，无法探索付费墙后的内容
- 实时 PvP / 高操作玩法 — 动作游戏/射击游戏的核心体验无法通过静态截图分析
- 社交互动系统 — 公会、好友、聊天等需要多账号交互的系统，单设备无法覆盖
- 直接生成商业结论 — 工具提取事实和规则，商业判断由分析师完成
- 反作弊规避 — 部分游戏可能检测模拟器环境，导致体验受限

### 10.3 使用建议

最佳实践

- 先手动体验 15-30 分钟，了解游戏基本结构，再挂机让工具补充覆盖
- 工具产出的规则报告是初稿，需结合截图核实低置信度规则
- 对重点分析对象，建议跑 4-8 小时以获得足够覆盖率
- 多游戏对比时，各游戏的探索时长应尽量一致，保证数据可比性