Game Assistant Walkthrough
提示:游戏助手服务在后台运行,不使用时可说"关闭服务"或"关掉服务"来停止(会连同攻略助手客户端一起关闭)。
使用时机
- 用户表达要开始玩游戏并打开攻略助手,或明确要求下载/更新攻略。
- 常见触发语:
- 我要玩游戏了
- 打开攻略
- 开始游戏
- 启动攻略助手
- 下载攻略
- 下载XXX攻略
- 更新攻略
- 打开XXX攻略
- 我要玩XXX游戏了
- 关闭服务 / 停止服务 / 关掉服务
已支持游戏列表(不断完善中,欢迎玩家贡献)
- 识质存在
- 艾尔登法环
- 黑神话:悟空
- 只狼:影逝二度
- 生化危机4重制版
- 明末:渊虚之羽
- 007初露锋芒
列表之外,还有无限可能!欢迎通过 Vibe Coding 亲自尝试,解锁属于你的专属游戏体验。
用户询问"支持某游戏吗 / 某游戏能不能用"时,可直接据此回答,无需运行任何命令。
v2 客户端会自动做什么(理解它,才能把结果讲对)
GameWalkthroughV2/run_app.py 是攻略助手客户端,有两种工作模式:
- 自动检测模式(
launch不带游戏名):持续按 GPU 占用检测正在运行的游戏。只认GameWalkthroughV2/config/game_processes.json里登记过的进程,新游戏必须先补映射(见下文"游戏名解析"),否则永远不会被识别。 - 指定游戏名模式(
launch "<游戏名>"直启):跳过检测,直接把该游戏设为当前游戏并自动下载+导入攻略;截图改为识别全屏画面。不依赖进程映射,也不要求游戏已启动——游戏还没开也能先启动助手,游戏画面出现后自动定位攻略。
两种模式共同的行为:
- 内嵌 webserver(端口 22818):浏览器访问
http://127.0.0.1:22818看攻略;鼠标移到屏幕右上角滑出二维码面板,手机/平板扫码即可。 - 进入游戏后:左上角滑入"检测到游戏"提示;随后 10 FPS 截图做 vision 匹配,自动打开并定位匹配的攻略页面。攻略的下载/插入/build 未完成前不做识别(不对着建到一半的索引发查询),完成后才恢复。
- 屏幕左上角有可拖动的攻略浮窗(📌图钉可切自动隐藏),事件提示均为左上角滑入弹窗。
- 攻略下载/导入进行中:攻略页面顶部显示进度条(搜索→逐页下载→插入图片→build 索引,阶段/百分比实时刷新,完成或失败后短暂提示自动收起);客户端自动准备(直启模式)、skill 的
download后台下载、服务端实例被删后的重新导入,都会体现在页面上。 - 攻略准备完成(build 结束)后自动把页面定位到位:首次准备跳到攻略第一页;之前展示过该游戏的恢复上次浏览的页面(该页在新攻略里已不存在时回退第一页)。
- 二维码面板点「⛶ 全屏」可整屏放大(白底黑码、左侧大码 + 右侧地址,适合电视/会场大荧幕远距离扫码;还原按钮/Esc/点二维码退出)。
因此:"打开攻略"只需确保服务可用 + 启动客户端,其余交给客户端;skill 不需要替它下载导入。
前提步骤(每次执行 skill 时必须最先执行)
1. 环境依赖
必须一次性安装全部依赖(使用国内镜像源加速;镜像不可用时切换其它镜像或回退官方 PyPI 重试),本步骤未完成禁止进入下载/启动等任何后续步骤:
pip install -r GameWalkthroughV2/requirements.txt py7zr modelscope -i https://mirrors.aliyun.com/pypi/simple/
(requirements.txt 含 requests / beautifulsoup4 / pillow / qrcode / pywebview;py7zr、modelscope 是服务部署脚本需要的。)
下文命令里的 python 还必须带 tkinter(下载进度弹窗、客户端提示弹窗、扫码面板与攻略浮窗都依赖它)。默认 python 不满足时(如精简发行版缺 tkinter、或依赖没装齐),换用本机另一个装有 tkinter 的解释器,并在命令里写明它的绝对路径。
若报"找不到 python / pip"或类似错误,说明这台机器没装 Python:告诉用户先安装 Python 3.9 以上版本(安装时勾选 Add to PATH),不要继续后面的步骤。
2. 服务健康检查与部署(全自动,无需你操心)
download 和 launch 会自己检查服务。服务没起来时,它们会在后台先部署服务,部署完成后自动继续原来的任务(继续下载攻略 / 继续启动客户端)——你不需要在部署完成后重新下一遍命令,只要照下面的表轮询 status 即可。
「游戏助手服务」需要在用户整个游戏过程中后台常驻。脚本拉起的后台进程在某些 Agent 沙盒里会随前台命令结束被回收——部署/启动完成后必须确认服务能跨命令存活,见下节第 3 条(不确认就宣告完成,服务可能在用户手里立刻失效)。
模型下载策略与预装目录不用传参:脚本每次执行时自己读本文件 frontmatter 的 models 和 install_dir,所有命令直接执行即可。install_dir 是预装目录。服务端目录按以下优先级确定,命中即用、绝不重新下载解压:①上次用户选择并记住的目录(记在 %LOCALAPPDATA%\GameAssistant\chosen_server_dir.txt)→ ②预装目录 install_dir → ③默认目录 %LOCALAPPDATA%\GameAssistant;三处都没有解压好的服务端(以目录内含服务端 exe 为准)时才弹窗问用户——「自动下载并安装(默认)」把安装包下载到默认目录并解压到那里,「选择已解压的服务端目录」直接使用用户指定的目录,10 秒无操作自动选自动下载。日志、状态文件与模型下载缓存跟随实际使用的服务端目录。
独立使用场景(如纯部署):
python ./scripts/service_manager.py health # 仅检查
python ./scripts/service_manager.py deploy # 后台部署
python ./scripts/service_manager.py status # 轮询进度
python ./scripts/service_manager.py ensure # 检查+按需部署
版本更新与确认弹窗(脚本自动处理,你要知道怎么向用户解释):deploy 启动时会联网检测服务端与模型更新(约几秒)。服务端更新的判定:默认双条件同时满足才更新——①本地服务端 exe 的修改时间早于 ModelScope 上压缩包的修改时间(files API 的 CommittedDate);②SHA256 与本地记录不一致(防止本地已从 GitHub 装了更新版本被误降级)。若压缩包修改时间的所有来源都拿不到(API 无字段且响应头无 Last-Modified),则退化为仅按 SHA256 不一致判定(日志会写明降级原因)。模型更新按仓库内容指纹与清单变化判定。检测到更新会弹窗询问「立即更新 / 暂不更新」(弹窗里每个选择都会写入日志,倒计时自动选择与用户主动点击可区分),10 秒无操作自动选"暂不更新"——暂不更新属正常路径,服务用当前版本继续启动(status 最终仍是 done),且该版本之后不再询问,直到出现更新的版本才再次弹窗。status 长时间停在「等待用户确认 (10%)」即是在等用户点弹窗(install_dir 配置了但还没装服务端时,也会弹安装方式确认窗,10 秒无操作自动开始下载)。更新规则:只更新已安装过的模型(未装过的模型不会被主动下载);服务端与模型作为一个事务更新——全部下载成功才会停服覆盖安装,任一下载失败自动继续使用当前版本;覆盖安装保留用户数据:saves/(存档数据库)与 models/(未更新的模型)原样保留、包内骨架不落地,旧版 caches/ 目录自动清理;更新期间服务会短暂关闭。ModelScope 下载失败时才会转 GitHub 源,转用前弹窗会明示"国内直连速度有较大概率很慢、耗时较久"。无网络时直接跳过检测照常启动。
3. Agent 环境适配(沙盒代理 / DLL 注入 / 后台进程回收 / 文件删除限制——命令执行前先读)
通过 Agent 启动本助手时,四类沙盒机制会造成故障,症状与对策如下(客户端与脚本进程内部已自动处理大半,这里是你需要做的部分和排障知识)。其中第 1 条(回环免代理)和第 4 条(删除权限放行)是启动脚本前就要主动做的,第 2、3 条是出问题时的排障知识:
- 沙盒代理:Agent 沙盒/企业网络常注入
http_proxy/https_proxy,会把发往127.0.0.1的本机请求也送进代理——症状是 webserver 页面打不开、部署/健康检查失败、浮窗白屏。每次执行本 skill 的命令前,先在当前 shell 设置回环免代理(幂等,已含回环条目则跳过):$env:NO_PROXY="127.0.0.1,localhost"; $env:no_proxy="127.0.0.1,localhost"service_manager拉起的所有子进程(部署/下载/客户端/浮窗)会自动合并该变量,无需你传递;这一步覆盖的是你自己直接执行的命令。用户反馈"页面打不开/一直转圈/健康检查失败"时,先检查这个变量再排查其它原因。不管沙盒里还是宿主机上,这个变量都必须有——不能假设环境里没有代理。 - DLL 注入:会往进程注入 DLL 的沙盒环境会让浮窗的 WebView2 白屏崩溃。浮窗进程导入时已自动设置
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--disable-features=ThirdPartyDllBlocking --no-sandbox规避(--no-sandbox是关键,单加 feature 参数无效;页面仅来自本机 webserver,风险可控)。不要清除或覆盖该环境变量;若用户仍反馈浮窗白屏,确认该变量存在后,shutdown再重新launch。 - 后台进程常驻:
deploy/download/launch都是脚本用 Popen 拉起后台进程后立即返回,而「游戏助手服务」要在用户整个游戏过程中长期存活——某些 Agent 沙盒会在前台命令结束时把脚本拉起的后台进程整树回收(SIGTERM/杀进程树)。症状:status刚到done、健康检查刚通过,下一条命令再查服务就没了;或status长时间停在running且毫无进展。因此宣告完成前必须确认服务能跨命令存活:- 部署/启动完成后等 30 秒,用一条新命令执行:
python ./scripts/service_manager.py healthhealthy→ 后台进程未被回收,正常继续;unhealthy(或status卡在running超过 5 分钟无进展且health失败)→ 该沙盒会回收后台进程,改用下面的常驻方式重做(优先你的后台任务能力,其次 CIM)。 - 常驻方式一(优先):用你的后台任务能力启动脚本:若你具备后台执行任务/后台进程的能力(如后台任务、后台 shell),优先把
service_manager命令(deploy/download/launch)放到后台任务里运行——沙盒回收的是「前台命令结束时拉起的后台进程」,挂在你的后台任务下的服务进程不会随后台任务结束而消失(任务本身很快返回也没关系,服务进程已经常驻),之后照常每 30 秒轮询status。这比下面任何兜底手段都可靠,能用就用。 - 常驻方式二(无后台任务能力时的兜底):CIM 拉起脱离进程树:用 CIM 创建进程,新进程挂在系统 WmiPrvSE 之下、不属于你的命令进程树,前台命令结束时不会被连带回收(
<python绝对路径>、<项目根绝对路径>替换为实际值,路径含空格也不影响;CIM 创建的进程不继承你 shell 的工作目录和临时环境变量——所以必须用绝对路径,$env:NO_PROXY也不用传,脚本子进程会自行合并回环免代理):powershell -NoProfile -Command "Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = '<python绝对路径> <项目根绝对路径>\scripts\service_manager.py ensure'; CurrentDirectory = '<项目根绝对路径>' } | Select-Object ReturnValue, ProcessId"ReturnValue = 0表示创建成功。之后照常每 30 秒轮询status到done,再用一条新命令health复核。download、launch(含直启,游戏名照常加双引号写在子命令后)同样适用——把命令里的ensure换成对应子命令即可;攻略客户端(webserver 22818 页面 / 左上角浮窗)也是脚本拉起的后台进程,在会回收的沙盒里launch也要走上述常驻方式,否则客户端会随后台回收一起消失。shutdown不受影响:按 PID/端口停止,常驻方式拉起的进程一样能正常关闭。 - 向用户说明:在此类沙盒里服务可能随 Agent 会话结束而停止,下次要玩时说一声"打开攻略"即可重新拉起。
- 部署/启动完成后等 30 秒,用一条新命令执行:
- 文件删除限制(启动脚本前先放行删除权限):Agent 沙盒常禁止脚本删除文件,而部署/启动流程里到处是删除与改名操作——覆盖安装要清掉旧内容、解压要在安装目录父级建/清
_extract_*/_unwrap_*临时目录、模型要从下载缓存移动落位到服务端模型目录、状态文件要原子替换。删除权限没放行时,后续任何一处删除被拦都会让脚本卡住(退化成整目录复制或反复重试,耗时数分钟到数十分钟毫无进展)甚至报错中断、模型全部留在下载缓存目录(<服务根目录>/_modelscope_download_cache/),助手等于没装成。因此第一次执行deploy/download/launch/ensure前,先主动请求放行对安装目录的删除/写入权限(默认%LOCALAPPDATA%\GameAssistant,frontmatterinstall_dir非空时为该路径;连同其父目录下的_extract_*/_unwrap_*临时目录一并放行,或临时关闭对应的文件防护)——向用户说明这是部署必需的文件操作、征得同意后在沙盒权限里批准,不要等脚本失败后再补。补救与判据:- 已中招时:
status返回error且detail/日志里有「无法把模型 XXX 安装到 …(移动/复制均被拒绝…请放行后重试)」,说明连复制写入都被拦截:按上面放行后重新执行原来的deploy/download命令——已下载的模型缓存在重跑时会复用,不会重新下载。 - 脚本内置回退:仅移动被拒时会自动改为复制安装(复制是纯写入,沙盒不拦),日志出现「移动/删除被沙盒拒绝,已改为覆盖复制安装」即说明模型已就位,无需你处理;仅下载缓存会残留在原处多占一份磁盘,之后放行删除重新部署即可清掉。
- 落位成功的判据:部署日志出现逐条的「安装完成: <模型名> → <目标目录>」,且服务端模型目录里能看到模型文件。模型只躺在
_modelscope_download_cache/而模型目录为空 = 落位失败,按上一条放行后重跑。
- 已中招时:
返回值怎么读(所有命令都只输出一行 JSON)
| status | 含义 | 你要做的 |
|---|---|---|
| started | 任务已在后台开始 | 告诉用户已开始,然后每 30 秒轮询一次 status |
| already_running | 攻略助手客户端已经开着 | 转达给用户,不要重复启动 |
| busy | 已有别的后台任务在跑 | 告诉用户稍等,每 30 秒轮询 status,完成后再重试本命令 |
| error | 失败 | 把 message 原样转达给用户,结束 |
status 命令返回 {task, status, stage, progress, detail}:
running→ 把stage和progress讲给用户听,30 秒后再查一次done→ 先按「Agent 环境适配」第 3 条确认服务能跨命令存活(新命令health),确认后再通知用户任务完成error→ 把detail转达给用户idle→ 还没有任务记录,等 30 秒再查一次;连续两次都是idle就当作没有任务在跑
shutdown 自带端口检测,无需前置步骤;返回 {status: done|error, client_stopped, message},client_stopped=true 表示攻略助手客户端也被一并关闭。
意图分流规则
- 若用户原话包含
关闭服务、停止服务、关掉服务等,判定为关闭服务。执行:
该命令的关闭范围是全部:攻略助手客户端主进程 → 客户端的全部子进程(左上角攻略浮窗、浮窗的 WebView2、ssh 反向隧道,python ./scripts/service_manager.py shutdowntaskkill /T连树结束;浮窗与 ssh 另有 Job Object 兜底)→ 残留浮窗与残留 ssh 隧道自动清扫(幂等兜底;ssh 孤儿会一直占着云端转发端口导致后续启动失败,必须清)→ 后台服务端(/server/shutdown优雅关,失败转/server/shutdown_kill强杀)。客户端没开就只停服务;客户端即使不是本 skill 拉起的(用户手动启动、PID 文件丢失),也会按命令行扫描找到并关闭。返回值client_stopped=false仅表示"客户端本来就没在运行"。关闭完成后无需任何手动清理命令。 - 若用户原话包含
下载攻略、下载XXX攻略、更新攻略等下载/更新诉求,判定为下载攻略。 - 若用户原话包含
打开攻略、我要玩游戏了、开始游戏、启动攻略助手等开启助手诉求,判定为打开攻略。 - 当同一句里同时出现下载与打开含义时,优先按用户的下载诉求执行,即先判定为
下载攻略。 - 若用户原话属于
打开XXX攻略、我要玩XXX游戏了这类"打开攻略 + 明确游戏名"表达,进入"打开攻略-直启分支"。
游戏名解析(仅在需要游戏名而没有时)
适用时机:
- 意图为
下载攻略/更新攻略,但原话没有明确游戏名; - 意图为
打开攻略且未命中直启分支,用户玩的游戏不在已支持列表、客户端一直不识别时——补上映射即可,无需重启客户端,下一轮检测自动生效(指定游戏名模式不依赖映射,不要为直启补映射)。
1. 从原话提取游戏名
- 优先读取 skill 参数里的用户原话。
- 如果原话清楚表达了目标游戏名,则直接使用,不运行检测。
- 可接受的明确表达包括但不限于:
下载黑神话悟空攻略帮我下载黑神话悟空的攻略更新一下黑神话悟空攻略- 仅移除动作词和尾部的
攻略、的攻略、图文攻略等固定修饰,不要擅自改写游戏名。 - 如果原话里没有明确游戏名,或游戏名提取后仍明显为空,再进入下一步"检测游戏进程"。
2. 检测正在运行的游戏进程
单次检测命令(脚本一次执行即返回;连续 5 次都拿不到结果才判定"没检测到",每次间隔 1 秒,重试由你控制):
python ./GameWalkthroughV2/app/game_detection.py
解析标准输出 JSON(一个对象),重点读取 process;name 字段来自旧版映射文件,忽略它,游戏名一律按下一步的映射规则确定。
分支规则:
process连续 5 次为 null:没检测到 GPU 高占用的游戏进程。问用户"没有检测到正在运行的游戏,请告诉我游戏名";用户给了就用它继续,用户不想说就结束 skill。不要静默结束。process非 null:进入下一步"进程 → 游戏名映射"。
3. 进程 → 游戏名映射(本地优先,联网兜底)
- 先读本地映射:打开
GameWalkthroughV2/config/game_processes.json,把process去掉.exe、忽略大小写后与 key 比对:- 查到 → 直接用该 value 作为
game_name,不要联网,进入下方"写入映射"。 - 没查到 → 进入第 2 步联网补全。
- 查到 → 直接用该 value 作为
- 联网补全游戏名(必须由 agent 完成):
- 使用 agent 的联网能力(如网页检索/浏览)搜索:
<process> 对应的游戏名。 - 禁止写脚本调用搜索引擎 API。
- 选择最可信的中文游戏名(优先官方名称或高可信来源交叉验证)。
- 若没有联网能力,或无法可靠确定游戏名:直接问用户"检测到
<process>,请确认游戏名",不要猜测写入。 - 联网补全得到
game_name后,进入下方"写入映射"。
- 使用 agent 的联网能力(如网页检索/浏览)搜索:
- 写入映射(
process与最终game_name都非空时必须执行):把"进程名": "游戏名"直接写入GameWalkthroughV2/config/game_processes.json(保持 JSON 合法、保留已有条目;key 用检测到的进程名去掉.exe,大小写随意,匹配时不区分)。写完客户端即可识别该游戏。旧版append_detected_process.py已删除,不要再找这个脚本。
打开攻略-直启分支
触发条件:
- 意图已判定为
打开攻略。 - 能从用户原话稳定提取出明确
game_name,典型如:打开XXX攻略、我要玩XXX游戏了。
执行规则:
- 命中该分支时,不运行游戏检测,也不需要该游戏在已支持列表或进程映射里——指定游戏名模式下客户端不依赖
config/game_processes.json。 - 通过 service_manager 直启客户端:
python ./scripts/service_manager.py launch "XXX"
其中 XXX 必须替换为从用户原话提取到的 game_name。
3. 若提取失败或结果为空,则回退到普通分支(不带游戏名启动,见"动作执行")。
动作执行
当你已经得到最终 game_name(或意图无需游戏名)后,按意图执行:
- 当意图为
下载攻略:后台下载+导入,不启动客户端。 即使本地攻略文件已存在,也必须调用service_manager.py download <游戏名>,不得直接回复"已下载"。下载期间会自动弹出 tkinter 进度窗口;若攻略助手客户端已开着(页面http://127.0.0.1:22818可访问),页面顶部还会同步显示下载进度条,可直接让用户去页面看进度:
python ./scripts/service_manager.py download "<game_name>"
返回 started 后提示用户"攻略下载正在后台运行"(若消息里说明了正在自动部署服务,一并告诉用户首次准备会比较久),然后每 30 秒轮询一次状态,按上面"返回值怎么读"处理:
python ./scripts/service_manager.py status
补充约定(脚本已负责,无需手动做):只下载图片并生成 images.json,再以 --images-json 模式导入 vision 服务;下载目录为 GameWalkthroughV2/walkthrough/<游戏名>/,导入 instance_id 使用最终 game_name,与 v2 客户端的自动下载/导入共用同一份攻略数据。
- 当意图为
打开攻略且命中"打开攻略-直启分支":
python ./scripts/service_manager.py launch "<game_name>"
客户端跳过检测,自动下载/导入该游戏攻略并识别全屏画面。游戏还没启动也可以先启动助手,游戏画面出现后会自动定位攻略——这句话要讲给用户。
- 当意图为
打开攻略且未命中直启分支:
python ./scripts/service_manager.py launch
客户端自动检测正在运行的游戏(新游戏须已在 config/game_processes.json 登记,否则不会被识别;不识别时按"游戏名解析"补映射即可,无需重启)。
两种分支共通的 launch 返回处理(含 PID 防重复;服务没起时后台自动部署,部署完自动启动):
already_running→ 转达用户,不要重复启动。started且 message 带"正在自动部署" → 每 30 秒轮询status,直到done(客户端会自动打开)或error。- 普通
started→ 直启分支告诉用户"正在为你准备《XXX》的攻略,准备期间网页会显示进度,完成后攻略页面会自动打开(首次到第一页,之前看过则回到上次的位置),进入游戏后还会随画面自动定位章节";普通分支告诉用户"攻略助手已启动,检测到游戏后会自动打开对应攻略"。两种情况都可以补充:网页版可访问http://127.0.0.1:22818;手机/平板在同一局域网时把鼠标移到屏幕右上角扫码访问,演示场合可点二维码面板的「⛶ 全屏」整屏展示;屏幕左上角还有常驻攻略浮窗。
完成条件
前置:达成下列条件前,先按「Agent 环境适配」第 3 条用新命令确认服务常驻——沙盒会回收后台进程时,done/started 不等于用户手里可用。
- 当意图为
下载攻略:status返回done(下载并导入完成);或 - 当意图为
打开攻略:攻略助手客户端启动成功(started/already_running);或 process连续 5 次检测为空、且用户也没有提供游戏名;或- 当意图为
关闭服务:shutdown返回done并结束。
模糊退出意图的处理
当用户表达模糊的退出意图(如"不玩了""退出""关掉""结束"等,但不包含"服务"关键词)→ 不命中任何意图分支,此时提示用户:"如果需要关闭后台服务,请说'关闭服务'或'关掉服务'"。
Scan to join WeChat group