game-analyst-agent 工具说明书

一、工具定位与设计理念

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

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 小时以获得足够覆盖率
多游戏对比时，各游戏的探索时长应尽量一致，保证数据可比性