BetterGI 原神自动化全解：计算机视觉驱动的 UI 自动化工具深度解析-平芜编程栈

BetterGI 原神自动化全解：计算机视觉驱动的 UI 自动化工具深度解析

BetterGI（BetterGenshinImpact，简称 BGI）是一个基于计算机视觉的原神 UI 自动化工具。它不改游戏文件、不读写内存，只靠"实时截图 → 图像/文字识别 → 模拟键鼠"这条链路，把自动拾取、自动剧情、自动钓鱼、自动刷秘境、一条龙日常等重活接管下来。全文按"原理 → 跑通 → 细用 → 深入"展开：先看它的识别-决策-操作闭环怎么运转，再给出环境要求与启动步骤，然后按使用场景拆解功能与源码级参数，最后整理避坑要点和开发者入口，读完你能对每个功能的默认值、文件路径逐项核对。

一、先看闭环：一帧画面如何变成一次按键

整个程序围绕一个约 20fps 的循环运转，任何功能最终都落在这条流水线上：

捕获。Fischless.GameCapture持续抓取游戏窗口，共 5 种模式（CaptureModes枚举）：BitBlt（默认）、WindowsGraphicsCapture、WindowsGraphicsCaptureHdr、WindowsGraphicsCaptureV2、DwmGetDxSharedSurface，由 AllConfig.cs 的CaptureMode字段决定。
识别。Core/Recognition 下按能力分三个子层：OpenCv/（模板匹配、颜色范围）、OCR/（Paddle、Yap 两套引擎）、ONNX/（模型推理，用于图标匹配等）；任务侧统一通过 RecognitionAssets.cs 的Get(...)按名字取识别对象，具体区域和模板写在各任务的Assets/Recognition.json里。
调度。TaskTriggerDispatcher.cs 用一个System.Timers.Timer按TriggerInterval（默认50ms，见 AllConfig.cs）驱动Tick。每帧的规则很明确：
- 上一帧没处理完 → 跳过本帧并计入"跳过次数"指标，不排队等待；
- 游戏窗口最小化 / 已退出 → 不截图，退出时自动停止截图器；
- 窗口不在前台 → 只有声明IsBackgroundRunning的触发器继续跑；
- 存在独占触发器（IsExclusive，如剧情播放中）→ 本帧只执行它；
- 每帧先用Bv.WhichGameUiForTriggers判定当前游戏 UI 类别（如BigMap），UI 类别切换后的 30 秒内所有触发器都会执行一遍，之后只执行SupportedGameUiCategory匹配当前 UI 的触发器。
操作。各触发器/任务通过 TaskControl.cs 与运行环境扩展执行点击、按键；TaskControl.TaskSemaphore（容量 1 的SemaphoreSlim）保证同一时刻只有一个独立任务在跑。截图失败时CaptureGameImage会以 30ms 间隔重试 3 次，仍失败才抛异常。

触发器本身的生命周期由 ITaskTrigger.cs 定义：实例在启动截图器时由 GameTaskManager.cs 统一创建并按Priority降序排列，停止截图器时销毁；不在任务中时看IsEnabledByConfig（直接读用户配置），独立任务执行期间只看任务/脚本通过AddTrigger注入的启用名单（目前支持AutoPick、AutoSkip、AutoEat三种）。所有回调都在Tick里串行执行，触发器内部无需自己加锁。

识别素材按分辨率目录加载：优先GameTask/<任务>/Assets/<宽x高>/，缺失时回退1920x1080/再按缩放比Resize（GameTaskManager.LoadAssetImage），这也是"分辨率变了要重启"的根源。

二、环境与启动：三步跑起来

硬性要求

项目	要求	来源
操作系统	Windows 10 或更高版本的 64 位系统	根 README.md
运行时	.NET 10，发布包已自带，无需另装	根 README.md
分辨率	仅支持 16:9，推荐 1920x1080 窗口化	根 README.md
硬件基线	至少能中画质 60 帧流畅游玩原神	根 README.md

下载渠道：

稳定版 / 测试版：项目 Release 页面；
最新自动构建产物：publish.yml工作流，产物为完整发布包；
国内可用 CNB Releases 渠道，速度更快。

三步启动

打开软件，进入"启动"页选择截图方式（对应CaptureMode，默认BitBlt；Windows 11 下若 BitBlt 不可用，AutoFixWin11BitBlt默认开启会自动修复）；
确认游戏以 16:9 窗口化运行且分辨率未变过；
点击启动，TaskTriggerDispatcher随即以 50ms 周期开始派发画面，遮罩窗口会同步显示日志和识别结果。

窗口大小变化、切换游戏分辨率、切换显示器时，请重启本软件，否则识别区域错位。模拟操作可能被部分安全软件拦截（已知 360、自定义规则 Windows Defender 会拦截部分模拟点击），请加入白名单。

三、功能地图：按使用场景归类

仓库里功能模块集中在 GameTask 目录，一个功能一个子目录，配置类与识别素材Assets/并存。下表按"你想用它干什么"重新归类，路径均可直接打开核对。

3.1 挂在旁边的"陪玩"：边玩边开

功能	作用	源码位置
自动拾取	遇到可交互内容自动按`F`，支持黑白名单	GameTask/AutoPick
自动剧情 / 自动邀约	跳过对话、按策略选选项、领每日委托、重新派遣	GameTask/AutoSkip
快速传送	地图界面识别传送点并代点	GameTask/QuickTeleport
自动吃药	战斗中识别血量自动嗑药	GameTask/AutoEat
半自动钓鱼	AI 识别抛竿、上钩收杆、拉满进度条	GameTask/AutoFishing
技能 CD 提示	遮罩上叠加技能冷却	GameTask/SkillCd
地图遮罩	游戏画面上叠加地图/标记层	GameTask/MapMask

3.2 体力消耗：挂机等奖励

功能	作用	源码位置
自动秘境	循环进秘境、开钥匙、战斗、走古树领奖励	GameTask/AutoDomain
自动幽境危战	自动传送并前往，主打难度三刷圣遗物	GameTask/AutoStygianOnslaught
自动首领讨伐	按策略自动挑战世界首领	GameTask/AutoBoss
自动地脉花	连续刷地脉花，支持绝大部分点位	GameTask/AutoLeyLineOutcrop
一条龙	一键日常编排（历练点、副本、地脉花、首领等按序执行）	Core/Config/OneDragonFlowConfig.cs、GameTask/OneDragon

一条龙本质是任务编排器：OneDragonFlowConfig里TaskOrder保存任务顺序、TaskEnabledList保存每个任务的开关、TaskDefinitions支持同名任务重复添加，用户可在界面上按需增删和排序；树脂相关的刷取预算、周本开关（WeeklyDomainEnabled）、自动首领选择（默认"根据队伍自动选择"）都挂在同一份配置上。

3.3 材料搬运：采集、挖矿、锄地、伐木

功能	作用	源码位置
自动采集/挖矿/锄地	识别左上角小地图定位，沿路径点行走	GameTask/AutoPathing
自动伐木	自动按`Z`释放「王树瑞佑」，利用上下线刷新木材刷满背包	GameTask/AutoWood
自动地脉花	同 3.2，也可归入材料类	GameTask/AutoLeyLineOutcrop

路径导航的核心在 Navigation.cs：WarmUp预热地图特征匹配（MapManager.GetMap(...).WarmUp()），GetPosition/GetPositionStable分别用于高效定位与高精度定位，再用GetTargetOrientation/GetDistance结合路径点（Waypoint）算出朝向与距离，驱动行走。执行链路见 PathExecutor.cs 与 NavigationInstance.cs。

自动伐木的参数很简单（AutoWoodConfig.cs）：AfterZSleepDelay（默认 0，用道具后额外延迟）、WoodCountOcrEnabled（默认 false，OCR 读取木材数量）、UseWonderlandRefresh（默认 true，通过进出千星奇域刷新 CD）。

3.4 手速外挂：单点提效

功能	作用	源码位置
那维莱特转圈	长按快捷键持续水平转视角（也可转草神）	GameTask/Macro/TurnAroundMacro.cs
快速圣遗物强化	快切"详情/强化"页跳过结算，快速 +20	GameTask/Macro/QuickEnhanceArtifactMacro.cs
商店一键购买	满数量快速购买，适合活动兑换/尘歌壶商店	GameTask/QuickBuy
键鼠录制回放	录制回放当前键鼠操作，建议配合调度器	Core/Recorder
自动音游	一键通关千音雅集专辑	GameTask/AutoMusicGame
自动烹饪	在完美区域完成烹饪	GameTask/AutoCook
自动分解圣遗物	快速分解 / 按规则匹配分解	GameTask/AutoArtifactSalvage
全自动七圣召唤	七圣召唤 PVE 角色邀请、来客挑战	GameTask/AutoGeniusInvokation
全自动钓鱼	面向鱼塘启动后自动完成钓鱼并切换昼夜	GameTask/AutoFishing
自动使用兑换码	自动领取/兑换	GameTask/UseRedeemCode
原琴演奏	自动演奏乐曲	GameTask/Music

七圣召唤与音游的定位参数见下文"参数详解"。音游配置（AutoMusicGameConfig.cs）里有MustCanorusLevel（默认 false，是否强制大音天籁）、MusicLevel（乐曲级别）、UseCapturePipeline（默认 false，改用截图管线检测音符，替代 GDIGetPixel，兼容 WGC V2 等全部捕获模式）。

四、源码级参数详解

以下四个功能是日常使用频率最高的，参数按"参数名（默认值）：作用"列出，全部可在对应文件中逐项核对。

4.1 自动拾取：三个偏移量划出的 OCR 窗口

文件：AutoPickConfig.cs。

Mode（Whitelist）：名单模式，Whitelist/Blacklist二选一；
WhitelistModeDoNotPickEnabled（true）：白名单模式下"不拾取规则"默认开启，即命中不拾取词条的物品跳过；
BlacklistModePickEnabled（false）：黑名单模式下的拾取规则开关；
OcrEngine（Paddle）：文字识别引擎，可选Paddle或Yap；
FastModeEnabled（false）：急速模式，无视文字识别结果直接按拾取键，响应更快但对场景有要求；
PickKey（F）：自定义拾取按键；
ItemIconLeftOffset（60）/ItemTextLeftOffset（115）/ItemTextRightOffset（400）：1080p 下拾取文字左侧图标、文字起始、文字终止的像素偏移，三者共同圈定 OCR 区域；
LegacyWhiteListEnabled：旧版白名单开关，读取后由MigrateLegacyConfig()迁移为黑名单模式的拾取规则。

文件顶部注释明确提示：非 16:9 分辨率下可能无法正常工作——因为上述偏移量全部按 1080p 设计。

4.2 自动剧情：选项策略 + 人声等待 + 后台画中画

文件：AutoSkipConfig.cs。

Enabled（true）：总开关，启用后覆盖快速跳过对话、自动点击选项、黑屏过长自动跳过三类行为；
QuicklySkipConversationsEnabled（true）：快速点击跳过剧情对话；
ClickChatOption（优先选择第一个选项）：选项策略，另支持"随机选择选项""不选择选项"；
CustomPriorityOptionsEnabled（false）+CustomPriorityOptions（空）：按文本自定义优先选项，每行一个或用分号分隔；
AutoWaitDialogueOptionVoiceEnabled（false）+DialogueOptionVoiceMaxWaitSeconds（30）：通过游戏进程音频的人声检测等待语音结束后再点选项，最长 30 秒；
AutoGetDailyRewardsEnabled（true）/AutoReExploreEnabled（true）：凯瑟琳对话出现橙色选项时自动领取每日委托、自动重新派遣；
AutoHangoutEventEnabled（false）：自动邀约，依赖自动剧情开启；AutoHangoutPressSkipEnabled（true）控制邀约中自动点击跳过；
SubmitGoodsEnabled（true）/ClosePopupPagedEnabled（true）：自动提交物品、关闭弹出书页；
RunBackgroundEnabled（false）：剧情后台运行；PictureInPictureEnabled（false）开启画中画，PictureInPictureSourceType默认CaptureLoop（主动获取 60 帧），可切TriggerDispatcher（跟随截图器 50ms 一帧）。

4.3 钓鱼：超时兜底 + 昼夜策略

文件：AutoFishingConfig.cs、FishingTimePolicy.cs。

Enabled（false）：半自动钓鱼触发器总开关，启用后自动判断进入钓鱼状态、自动提杆、自动拉条；
AutoThrowRodEnabled（false）：自动抛竿开关；
AutoThrowRodTimeOut（15 秒）：自动抛竿后未上钩的超时；
WholeProcessTimeoutSeconds（300 秒）：整个钓鱼任务的超时；
FishingTimePolicy（All）：昼夜策略，取值All（全天）/Daytime（白天）/Nighttime（夜晚）/DontChange（不调昼夜）。

4.4 自动秘境：树脂统一配置与双路奖励识别

文件：AutoDomainConfig.cs。

ResinUsage（迁移自旧字段）：统一树脂设置，取代旧版"优先级列表 + 分树脂计数"一组字段（ResinPriorityList旧默认["浓缩树脂", "原粹树脂"]、OriginalResin20UseCount等均已标记为迁移专用）；
FightEndDelay（5 秒）：战斗结束后延迟几秒再寻找石化古树；
ShortMovement（false）：寻找古树时改为短距离移动，给识别速度较慢的机器用；
LeftRightMoveTimes（3 次）：寻找古树时左右移动的次数；
ReviveRetryCount（3）：战斗死亡后的重试次数；
PartyName/DomainName（空）：指定刷本队伍与副本名称，SundaySelectedValue指定周日奖励序号；
AutoEat（false）/AutoArtifactSalvage（false）：战斗自动吃药、结束自动分解圣遗物；
RewardRecognitionEnabled（false）：开启后每轮领取奖励用 ONNX 图标匹配 + OCR 材料名双路识别，秘境结束打印汇总；
TargetItems（空列表）：按"物品名 + 数量"达到目标提前停止；
TrainingGuideCalculateRunsEnabled（true）：按提升指南培养计划自动计算今日刷取次数的总开关；TrainingGuideRewardRecognitionEnabled（true）——注意：即使常规奖励识别关闭，培养计划刷取仍会识别奖励；TrainingGuideFallbackDomainName为当天无可刷目标时使用的备选秘境。

4.5 附：快速传送的判定链

QuickTeleportTrigger.cs 是"模板匹配 + OCR"组合技的典型，值得单独看一遍判定顺序：

距上次执行 ≤300ms 直接返回，限制动作频率；
判定是否在大地图：CurrentGameUiCategory == BigMap或Bv.IsInBigMapUi；
找到"传送"按钮模板 → 直接点击，结束；
找不到传送按钮但存在"地图关闭 / 地图选择"按钮 → 说明尚未选中传送点，返回；
否则对传送点列表图标做多模板匹配（阈值 0.8，HDR 捕获降为 0.7），按Y坐标升序取最高一项，对其右侧 200px 宽、上下各扩 8px 的区域做"颜色范围 + OCR"（HLS 色域 L:245~255, S:0~15）识别文字，非空且 >1 个字符即点击该选项，TeleportListClickDelay默认 200ms 的间隔控制连点节奏；
选项点击后等WaitTeleportPanelDelay（默认 50ms，0.24 版本后识别耗时变长可设 0），再回步骤 3 点掉传送按钮。

另支持HotkeyTpEnabled：按住指定快捷键时才触发整套流程（QuickTeleportConfig.cs）。

五、避坑指南：高频问题一次说清

为什么必须管理员权限运行？游戏本身以管理员权限启动，软件权限不够时无法向游戏窗口注入模拟点击，表现为"识别正常但点不动"。

会不会封号？BetterGI 不做任何修改游戏文件、读写内存的行为，纯视觉 + 模拟输入，官方口径是"理论上不会"。但用户条款明确把第三方软件/模拟操作列为封号理由之一，存在被检测的可能。建议低调使用。

改过窗口 / 分辨率 / 显示器之后识别全部错位？重启本软件。所有识别区域和素材缩放都按启动时的窗口尺寸计算（见"素材按分辨率目录加载"一节）。

开了功能却没反应？先查三件事：触发器Enabled是否为 true；游戏窗口是否在前台（多数触发器不在前台不跑，只有声明后台运行的例外）；是否正处于独立任务执行中（任务期间只看启用名单，用户开的其他触发器会被暂停）。

配置改了不生效？大部分开关每帧直接读配置、即时生效；少数项（如CaptureMode、DisableInputMonitor、WGC V2 相关转换选项）需要重启截图器或软件后生效，以源码注释标注为准。

低配置机器能跑吗？图像识别吃性能，官方基线是"中画质 60 帧流畅"。达不到时优先调小TriggerInterval之外的开销：关闭不用的触发器、把 OCR 区域类功能（如自动拾取）切到急速模式。

安全软件拦截模拟点击？已知 360 和自定义规则 Windows Defender 会拦截部分类型的模拟点击，把 BetterGI 加入白名单。

六、开发者入口：编译、识别资源与配置体系

编译工程

前置：.NET 10 SDK + Windows SDK10.0.22621.0及以上；运行闪退多半是 SDK 版本不够，装新版或调整TargetFramework降版（见 BetterGenshinImpact/README.md）；
推荐 Rider（速度快且免费）或支持 .NET 10 的 Visual Studio 打开 BetterGenshinImpact.sln；
需要完整发布包时，可 fork 后在publish.yml工作流手动触发，约 10 分钟产出BetterGI_7z；
代码风格由 CodeMaid.config 与 Settings.XamlStyler 统一约束；
源码获取：git clone https://gitcode.com/gh_mirrors/be/better-genshin-impact。

识别资源怎么写

每个任务的识别配置放在BetterGenshinImpact\GameTask\<任务名>\Assets\Recognition.json，完整规范见 Docs/technical/recognition-json.md。要点：

顶层结构：version（固定 1）、vars、regions（公共区域表达式）、templates（公共模板别名）、objects（识别对象集合）；
roi/reference.bbox/vars支持表达式，由 NCalc 解析，可用@别名引用公共区域与模板；
type必须与RecognitionTypes枚举文本完全一致（如TemplateMatch）；模板匹配场景下省略name时运行时默认取模板名；
运行时通过RecognitionAssets.Get("任务名", "对象名", region)加载，加载器为 RecognitionObjectJsonLoader.cs，模板资产由 RecognitionTemplateAssetService.cs 管理。

配置体系

全部用户配置聚合在 AllConfig.cs：一个根对象挂 30 余个子配置块（自动拾取、剧情、钓鱼、打牌、秘境、宏、快捷键、通知、地图追踪、桌面分身、外部访问服务……），子配置各自独立成文件，目录 Core/Config；
InitEvent()里的ConfigChangeTracker对整个对象图做变更追踪，任意嵌套项变更都会回调OnAnyChangedAction（由ConfigService设为防抖保存）；
实时触发器每帧直接读配置，因此大部分开关无需重启即时生效；
旧字段迁移模式值得注意：多个任务用MigrateLegacy...()+Ensure...()一对方法把旧配置一次性迁移到统一结构（如树脂设置统一为ResinUsage），新字段非空时旧字段不再覆盖。

七、结语

BetterGI 把"截图—识别—决策—模拟输入"这条纯视觉闭环工程化到了相当完整的程度：调度器一帧一帧地管住并发与优先级，触发器接口把"实时响应"与"流程化任务"切成两种生命周期，识别逻辑则全部外置成Recognition.json与分辨率素材目录，识别规则可以脱离 C# 代码独立维护。想继续深入，建议从 ITaskTrigger.cs 的接口契约、Docs/technical/recognition-json.md 的表达式系统、Docs/design 下的架构设计文档（任务契约、触发器调度 DI、实时触发等）三个入口读起，再对照 GameTask 里任一任务目录的"配置类 + 触发器 + Assets"三件套，基本就能上手扩展新功能了。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考