better-genshin-impact Documentation

Technical Documentation: babalae/better-genshin-impact

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

English | 中文 | 繁體中文 | 日本語
BetterGI · 更好的原神， 一个基于计算机视觉技术，意图让原神变的更好的项目。

功能 Copy Chapter

• 实时任务
  • 自动拾取：遇到可交互/拾取内容时自动按 F，支持黑白名单配置
  • 自动剧情：快速点击过剧情、自动选择选项、自动提交物品、关闭弹出书页等
    • 与凯瑟琳对话时有橙色选项会 自动领取「每日委托」奖励、自动重新派遣
  • 自动邀约：自动剧情开启的情况下此功能才会生效，自动选择邀约选项
  • 快速传送：在地图上点击传送点，或者点击后出现的列表中存在传送点，会自动点击传送点并传送
  • 半自动钓鱼：AI 识别自动抛竿，鱼上钩时自动收杆，并自动完成钓鱼进度
• 独立任务
  • 全自动七圣召唤：帮助你轻松完成七圣召唤角色邀请、每周来客挑战等 PVE 内容
  • 自动伐木：自动 Z 键使用「王树瑞佑」，利用上下线可以刷新木材的原理，挂机刷满一背包的木材
  • 自动秘境：全自动秘境挂机刷体力，自动循环进入秘境开启钥匙、战斗、走到古树并领取奖励
  • 自动幽境危战：自动传送并前往幽境危战，主要用于难度三刷圣遗物
  • 全自动钓鱼：在出现钓鱼 F 按钮的位置面向鱼塘，然后启动全自动钓鱼，启动后程序会自动完成钓鱼，并切换白天和晚上
  • 自动地脉花：自动连续刷地脉花，支持绝大部分地脉花位置。
  • 自动音游：一键自动完成千音雅集的专辑，快速获取成就
  • 自动烹饪：自动在完美区域完成食物烹饪
  • 自动分解圣遗物：支持 快速分解 和 按匹配规则的圣遗物分解
• 全自动
  • 一条龙：一键完成日常（使用历练点），并领取奖励
  • 自动采集/挖矿/锄地：通过左上角小地图的识别，完成自动采集、挖矿、锄地等功能
  • 键鼠录制：可以录制回放当前的键鼠操作，建议配合调度器使用
• 操控辅助
  • 那维莱特转圈：设置快捷键后，长按可以不断水平旋转视角（当然你也可以用来转草神）
  • 快速圣遗物强化：通过快速切换“详情”、“强化”页跳过圣遗物强化结果展示，快速+20
  • 商店一键购买：可以快速以满数量购买商店中的物品，适合快速清空活动兑换，尘歌壶商店兑换等
• ……

截图 Copy Chapter

下载 Copy Chapter

[!NOTE]
下载地址：⚡Github 下载

不知道下载哪个？第一次使用？请看：快速上手 ， 遇到问题请先看：常见问题

最新测试版本可以从自动构建中获取：
或者从CNB上直接下载（速度快）：CNB Releases

使用方法 Copy Chapter

由于图像识别比较吃性能，低配置电脑可能无法正常使用部分功能。

推荐的电脑配置至少能够中画质60帧流畅游玩原神，否则部分功能的使用体验会较差。

你的系统需要满足以下条件：

• Windows 10 或更高版本的64位系统
• .NET 8 运行时 （没有的话，启动程序，系统会提示下载安装）

⚠️注意：

1. 窗口大小变化、切换游戏分辨率、切换显示器的时候请重启本软件。
2. 不支持任何画面滤镜（HDR、N卡滤镜等）。游戏亮度请保持默认。
3. 当前只支持 16:9 的分辨率，推荐在 1920x1080 窗口化游戏下使用。
4. 模拟操作部分可能被部分安全软件拦截，请加入白名单。已知360或者自定义规则WD会拦截部分类型的模拟点击

打开软件以后，在“启动”页选择好截图方式，点击启动按钮就可以享受 BetterGI 带来的便利了！

详细使用指南请看：快速上手

具体功能效果与使用方式见：文档

FAQ Copy Chapter

• 为什么需要管理员权限？
  • 因为游戏是以管理员权限启动的，软件不以管理员权限启动的话没有权限模拟鼠标点击。
• 会不会封号？
  • 理论上不会被封。 BetterGI 不会做出任何修改游戏文件、读写游戏内存等任何危害游戏本体的行为，单纯依靠视觉算法和模拟操作实现。 但是mhy是自由的，用户条款上明确说明第三方软件/模拟操作是封号理由之一。当前方案还是存在被检测的可能。只能说请低调使用，请不要跳脸官方。
• 更多常见问题...

致谢 Copy Chapter

本项目的完成离不开以下项目：

• Yap
• genshin-woodmen
• Fischless
• MicaSetup
• cvAutoTrack
• genshin_impact_assistant
• HutaoFisher
• minimap
• kachina-installer

另外特别感谢 @Lightczx 和 @emako 对本项目的指导与贡献

开发者 Copy Chapter

格式化：CodeMaid.config、Settings.XamlStyler；

如何编译项目？

许可证 Copy Chapter

问题反馈 Copy Chapter

提 Issue 或 QQ群761949201

Overview (`BetterGenshinImpact/README.md`) Copy Section

如何编译并运行整个工程？ Copy Chapter

Rider (推荐) Copy Section

1. git clone https://github.com/babalae/better-genshin-impact.git
2. 推荐使用 Rider 打开本项目。速度快且免费！

Visual Studio 2022 Copy Section

1. git clone https://github.com/babalae/better-genshin-impact.git
2. 需要使用 Visual Studio 2022 打开本项目。

请注意当前 /Asset 目录下的部分文件过大，比如地图特征数据（300M+），需要手动从 Release 包中获取并拷贝至对应的编译目录下，软件才能够正常运行对应的功能。（当前仅影响地图追踪、自动传送相关功能） 现在已经丢到 nuget 上可以直接编译构建了

如何通过 Github Action 直接构建完整包？ Copy Chapter

首先 fork 这个项目并启用 GitHub Actions。然后提交 <commit> 并且推送到 `` 。

最后前往这里 https://github.com/<your-user-name>/better-genshin-impact/actions/workflows/publish.yml 并点击 Run workflow:

• Use workflow from 选择 ``
• BetterGI Version 填写 <current-version>+<commit hash>
• Kachina Installer Channel 选择 release （无需修改）
• 不要勾选 创建 GitHub Release 草稿

点击绿色按钮 Run workflow，等待约10分钟。

刷新当前页面，点击最新的 Run，Artifacts 中的 BetterGI_7z 就是构建的完整包。

运行项目闪退？ Copy Chapter

可能是 Windows SDK 版本不够。使用 Visual Studio Installer 安装 10.0.22621.0 及以上版本的 Windows SDK，或者编辑项目文件的 TargetFramework 降低版本。

识别用的模板资源 Recognition.json 如何编写 Copy Chapter

参考：RecognitionJson编写说明

Overview (`Docs/README.md`) Copy Section

文档

仓库文档按主题分类存放。

Docs/
├─ architecture/       # 架构设计
├─ development/        # 开发者文档
├─ technical/          # 具体技术实现
├─ api/                # API / SDK
├─ design/             # 设计文档 / ADR
├─ images/             # 文档图片
├─ archive/            # 废弃/历史方案
├─ tmp/                # AI 临时设计文件（git 忽略）
└─ i18n/               # README 多语言文本

Overview (`Fischless.WindowsInput/README.md`) Copy Section

Fischless.WindowsInput

Modify version implement https://www.nuget.org/packages/InputSimulator 1.0.4.

Get legacy version:

<PackageReference Include="InputSimulator" Version="1.0.4" />

Overview (`Build/BetterGenshinImpact.I18nSync/README.md`) Copy Section

BetterGenshinImpact.I18nSync

BetterGenshinImpact.I18nSync 用于扫描主项目 XAML 中的 {i18n:T 中文原文} 以及少量明确标记的 C# UI 文案，并自动同步 BetterGenshinImpact/User/I18n/*.json 中的多语言 Key。

中文原文同时作为 i18n Key 和默认文案，因此 XAML 设计器可以直接显示中文；当目标语言没有对应翻译，或翻译值为空时，程序运行时也会回退显示这个中文 Key。

快速开始 Copy Chapter

请在仓库根目录运行：

# 默认模式：补充缺少的 Key，并删除已经废弃的 Key
.\Build\Scripts\i18n-sync.ps1

# 只补充缺少的 Key，不删除废弃 Key
.\Build\Scripts\i18n-sync.ps1 -AddOnly

# 只检查默认同步模式是否会产生变更，不修改文件
.\Build\Scripts\i18n-sync.ps1 -Check

# 只检查“只补充”模式是否会产生变更，不修改文件
.\Build\Scripts\i18n-sync.ps1 -AddOnly -Check

脚本会自动把 BetterGenshinImpact 主项目目录传给同步工具，日常开发优先使用该脚本即可。

XAML 写法 Copy Chapter

直接将中文界面文本作为 Key：

<TextBlock Text="{i18n:T 用户设置}" />
<Button Content="{i18n:T 保存}" />
<GroupBox Header="{i18n:T 自动战斗}" />

同步后，语言文件中会生成相同的 Key：

{
  "保存": "",
  "用户设置": "",
  "自动战斗": ""
}

新增 Key 的值会故意留空，方便搜索和判断哪些翻译尚未补充。空字符串不会让界面显示为空，I18nService 会回退显示中文 Key。

同步模式 Copy Chapter

“废弃 Key”是指语言 JSON 中存在、但当前项目 XAML 或明确标记的 C# UI 文案已经不再引用的 Key。默认模式会删除它们；如果正在重构界面、暂时不希望清理旧 Key，请使用 -AddOnly。

Check 模式不仅检查缺失或废弃 Key，也会检查文件的排序、缩进、换行等是否符合工具的规范化输出。发现任何需要同步的内容时，工具不会修改文件，但会返回退出码 1。

直接运行工具 Copy Chapter

需要指定其他项目目录，或者不经过 PowerShell 脚本时，可以直接运行：

dotnet run --project .\Build\BetterGenshinImpact.I18nSync\BetterGenshinImpact.I18nSync.csproj -- --project .\BetterGenshinImpact

可用参数：

未传入 --project 时，工具会按以下顺序定位主项目：

1. 当前目录包含 BetterGenshinImpact.csproj 时，使用当前目录。
2. 否则尝试使用当前目录下的 BetterGenshinImpact 子目录。

语言文件约定 Copy Chapter

语言文件位于：

BetterGenshinImpact/User/I18n/

例如：

en-US.json
it-IT.json
ja-JP.json
ru-RU.json

同步规则如下：

• 处理该目录下所有 *.json 文件。
• 文件名以 _ 开头的 JSON 会被忽略，可用于保存不参与同步的辅助文件。
• 已有 Key 的翻译值会原样保留。
• 新增 Key 的翻译值固定写为空字符串 ""。
• 默认模式会删除 XAML 中已经不存在的 Key；AddOnly 模式会保留它们。
• 每次写入前都会使用 StringComparer.Ordinal 对全部 Key 排序。
• 输出格式为两空格缩进、LF 换行、UTF-8 无 BOM。
• 只有内容确实发生变化的语言文件才会被写入。

Key 提取规则 Copy Chapter

工具会递归扫描项目中的 *.xaml 和 *.cs 文件，并遵循以下规则：

• 提取 XML 属性值中的 {i18n:T ...}。
• 提取 I18nService.Instance.Translate("...") 和 new HotKeySettingModel("...") / new StatusItem("...") 中明确作为 UI 文案 Key 的字符串，并还原 C# 字符串转义。
• 忽略 bin 和 obj 目录。
• XAML 注释中的文本不会被提取。
• C# 的行注释和块注释中的文本不会被提取。
• 相同 Key 只保留一份。
• JSON 格式错误、重复 Key 或非字符串翻译值都会使同步失败，避免覆盖异常数据。
• 先验证并生成全部文件的同步计划，确认无错误后才开始写入，避免只更新一部分语言文件。

推荐工作流 Copy Chapter

1. 在 XAML 中新增、修改或删除 {i18n:T 中文原文}。
2. 运行 .\Build\Scripts\i18n-sync.ps1 同步所有语言文件。
3. 在各语言 JSON 中搜索值为 "" 的项目并补充翻译。
4. 提交前运行 .\Build\Scripts\i18n-sync.ps1 -Check。
5. 检查 Git 差异，确认删除的废弃 Key 符合预期。

如果界面重构尚未完成，建议第 2 步临时使用 -AddOnly，等 XAML 调整完成后再运行默认模式统一清理废弃 Key。

CI 检查 Copy Chapter

可以在持续集成环境中运行：

pwsh .\Build\Scripts\i18n-sync.ps1 -Check

退出码约定：

常见问题 Copy Chapter

新增 Key 后为什么翻译值是空字符串？ Copy Section

这是预期行为。空字符串用于标记待翻译内容，运行时会回退显示中文 Key，不会显示空白。

为什么 `Check` 模式返回失败，但没有缺少的 Key？ Copy Section

文件中可能存在废弃 Key，或者排序、缩进、换行等格式与工具的规范化输出不一致。先运行一次对应的同步模式，再检查 Git 差异。

默认同步删除了某个 Key，应该怎么办？ Copy Section

确认该 Key 是否仍在真实的 XAML 属性中使用。注释中的引用不会被视为有效引用。重构期间需要暂时保留旧 Key 时，请使用 -AddOnly。

修改了 JSON，但界面仍显示中文 Key Copy Section

请确认当前语言文件中的 Key 与 XAML 中文原文完全一致，并且翻译值不是空字符串或纯空白。Key 比较区分大小写，也不会自动忽略前后空格。

Overview (`Docs/api/README.md`) Copy Section

API / SDK

本目录存放对内或对外的 API、SDK 与接口约定说明。

文档列表 Copy Chapter

暂无。

Overview (`Docs/architecture/README.md`) Copy Section

架构设计

本目录存放 BetterGI 的架构设计文档，包括整体分层、模块边界、依赖关系与演进方案。

文档列表 Copy Chapter

暂无。

Overview (`Docs/archive/README.md`) Copy Section

废弃 / 历史方案

本目录存放已废弃、未采纳或仅作历史参考的方案，避免与现行文档混淆。

迁入时请在原文开头注明废弃原因和替代文档（如有）。

文档列表 Copy Chapter

暂无。

Overview (`Docs/design/README.md`) Copy Section

设计文档 / ADR

本目录存放设计文档与架构决策记录（Architecture Decision Record）。

每份 ADR 建议记录：背景、备选方案、决策结果，以及取舍原因。

文档列表 Copy Chapter

• Pulonia 任务系统设计总览与开发计划
• BetterGI 多实例命名管道协议
• BetterGI 输入层 InputHub 设计
• 遮罩窗口（MaskWindow）统一设计
• 配置持久化链路（AllConfig 保存）优化
• 实时触发器生命周期与启停设计
• TaskTriggerDispatcher 依赖注入改造设计

Overview (`Docs/development/README.md`) Copy Section

开发者文档

本目录存放面向贡献者的开发文档，包括编译、调试、代码规范与协作流程。

文档列表 Copy Chapter

暂无。

Overview (`Docs/images/README.md`) Copy Section

文档图片

本目录存放文档引用的图片资源。正文中请使用相对路径引用，例如 ../images/example.png。

Overview (`Docs/technical/README.md`) Copy Section

技术实现

本目录存放具体功能或子系统的技术实现说明，例如截图、识别、任务调度、输入模拟等。

文档列表 Copy Chapter

• Recognition.json 编写说明

Overview (`Docs/tmp/README.md`) Copy Section

AI 临时设计文件

本目录用于存放 AI 生成的临时设计稿、分析笔记和未定稿方案，不纳入版本库。

正式文档请整理后移到 architecture/、design/、technical/ 等对应目录。历史方案请移到 archive/。

Overview (`Test/BetterGenshinImpact.UnitTest/README.md`) Copy Section

使用单元测试前准备 Copy Chapter

准备Assets Copy Section

Assets目录下面是一个子模块（submodule）
为了避免不关注测试的用户下载不必要的数据，子模块没有保持最新，因此为了进行测试，要手动下载Assets目录下的最新数据资源：
git submodule update --remote
可能需要先init：
git submodule init

子模块被定义在 .gitmodules 文件中，因此上述git命令也应在该文件所在目录执行

Assets项目地址：https://github.com/huiyadanli/BetterGI.UnitTest.Assets

准备配置文件 Copy Section

有的单元测试要读取配置，目前采取读取主项目BetterGenshinImpact编译环境相同配置的方式
因此须要编译运行一次主项目BetterGenshinImpact，使得User/config.json被创建出来

Overview (`BetterGenshinImpact/GameTask/Common/StateMachine/README.md`) Copy Section

StateMachineBase 状态机框架

StateMachineBase<TState, TContext> 是给游戏自动化任务使用的有限状态机基类。它把 UI 场景识别、场景处理、状态转移、重试和超时兜底放到统一框架里，避免任务里堆一长串 switch、while 和零散的超时判断。

推荐写法是：

1. 用枚举定义所有 UI 状态。
2. 用 [StateDetector] 标记状态检测方法。
3. 用 [StateHandler] 标记状态处理方法，并在节点上声明重试策略。
4. 在一个地方集中注册状态转移图。
5. 调用 RunStateMachineUntil 运行到目标状态。

核心概念 Copy Chapter

TState 必须是枚举。建议第一个枚举值是 Unknown，因为 default(TState) 会被框架当作“未识别到状态”使用。

基本模板 Copy Chapter

public enum MyState
{
    Unknown,
    MainWorld,
    EventMenu,
    TargetPage,
}

public class MyTask : StateMachineBase<MyState, BvPage>, ISoloTask
{
    protected override ILogger Logger => TaskControl.Logger;

    public MyTask()
    {
        RegisterAllStateHandlers();
    }

    private void RegisterAllStateHandlers()
    {
        RegisterStateMethodsByAttribute();

        RegisterStateTransitions(
            (MyState.MainWorld, [MyState.EventMenu]),
            (MyState.EventMenu, [MyState.TargetPage])
        );
    }

    public async Task Start(CancellationToken ct)
    {
        Initialize(ct, MyState.Unknown);
        var page = new BvPage(ct);

        await RunStateMachineUntil(page, MyState.TargetPage);
    }
}

Detector Copy Chapter

Detector 只负责“当前截图是不是这个状态”，不要在里面点击、等待或修改状态。

[StateDetector(MyState.MainWorld, Order = 10)]
private bool DetectMainWorld(ImageRegion ra)
{
    return ra.Find(ElementAssets.Instance.PaimonMenuRo).IsExist();
}

[StateDetector(MyState.EventMenu, Order = 20)]
private bool DetectEventMenu(ImageRegion ra)
{
    return ra.FindMulti(RecognitionObject.Ocr(125, 142, 113, 28))
             .Any(o => o.Text.Contains("活动一览"));
}

Order 表示全量检测时的检测顺序，数值越小越先检测。建议把快且稳定的模板匹配放前面，把大范围 OCR 放后面。

状态机每轮只截图一次并复用给多个检测器。若当前状态注册了邻接状态，则只检测邻接状态；若当前状态没有注册转移关系，则回退到全量检测。

Handler Copy Chapter

Handler 只负责“在当前状态做一步动作”，动作结果用 StateHandlerResult 表达。除 Success 外，还可以用 SuccessTo(...) 将本次动作的等待目标收窄到当前状态图中的一个或多个合法邻接状态。

[StateHandler(MyState.MainWorld)]
private async Task<StateHandlerResult> HandleMainWorld(BvPage page)
{
    Simulation.SendInput.SimulateAction(GIActions.OpenTheEventsMenu);
    await Delay(500, _ct);
    return StateHandlerResult.Success;
}

[StateHandler(MyState.EventMenu, RetryTimeout = 30000)]
private async Task<StateHandlerResult> HandleEventMenu(BvPage page)
{
    var target = page.GetByText("目标活动").FindAll().FirstOrDefault();
    if (target == null)
    {
        return StateHandlerResult.Retry;
    }

    target.Click();
    await Delay(300, _ct);
    return StateHandlerResult.Success;
}

[StateHandler(MyState.TargetPage)]
private async Task<StateHandlerResult> HandleTargetPage(BvPage page)
{
    if (/* 当前页面业务条件成立 */)
    {
        Simulation.SendInput.SimulateAction(GIActions.OpenPaimonMenu);
        return StateHandlerResult.SuccessTo(MyState.MainWorld);
    }

    page.GetByText("前往").FindAll().First().Click();
    return StateHandlerResult.SuccessTo(MyState.TeleportMap, MyState.DomainEntrance);
}

SuccessTo(...) 的目标只表示真实的屏幕状态。当前屏幕中的业务条件不能伪造成一个新的状态；应先执行动作，再等待动作后的真实目标状态。

目标状态通常不会执行 Handler。RunStateMachineUntil 每轮会先检测当前状态，发现已到达目标状态就直接返回。

Unknown Handler Copy Chapter

未知状态处理器用于兜底恢复，例如回主界面后重新识别。

[UnknownStateHandler]
private async Task<StateHandlerResult> HandleUnknownState(BvPage page)
{
    await new ReturnMainUiTask().Start(_ct);
    return StateHandlerResult.Wait;
}

未知状态处理器最多只能注册一个。它适合做“恢复到已知入口”的动作，不适合吞掉真正的业务错误。

状态转移图 Copy Chapter

状态转移关系必须集中注册，保持流程可读。

RegisterStateTransitions(
    (MyState.MainWorld, [MyState.EventMenu]),
    (MyState.EventMenu, [MyState.TargetPage])
);

状态图是严格的：

• 当前状态有邻接关系时，框架只检测邻接状态。
• 每个注册的状态转移必须至少有一个邻接状态；结束节点不要注册状态转移。
• 邻接状态不能包含自身，注册时会直接抛异常。
• 如果需要在同一页面重试，不要写自环，应该让 Handler 返回 Retry，或让 Success 后的源状态保持超时触发 retry。
• Success 状态必须有合理的下一跳，否则等待邻接状态会失败并消耗 retry。

候选状态顺序会影响检测优先级。更具体、更不容易误判的状态应放在前面。

结束节点 Copy Chapter

结束节点用 RunStateMachineUntil 的目标状态表达，不需要也不应该注册空邻接。

RegisterStateTransitions(
    (MyState.MainWorld, [MyState.EventMenu]),
    (MyState.EventMenu, [MyState.TargetPage])
);

await RunStateMachineUntil(page, MyState.TargetPage);

上面这个例子里，TargetPage 没有出边，所以不注册 (MyState.TargetPage, [])。状态机每轮会先检测是否到达目标状态，命中后直接退出，不会执行目标状态的 Handler。

如果一个状态在某个阶段是结束节点，在另一个阶段还要继续流转，也可以注册它的出边。是否结束由本次 RunStateMachineUntil 的目标状态决定，不由状态本身永久决定。

Retry 策略 Copy Chapter

节点可以在 [StateHandler] 上声明 retry 策略：

[StateHandler(MyState.EventMenu, RetryTimeout = 30000, RetryInterval = 500)]
private async Task<StateHandlerResult> HandleEventMenu(BvPage page)
{
    ...
}

[StateHandler(MyState.TargetPage, RetryTimes = 10)]
private async Task<StateHandlerResult> HandleTargetPage(BvPage page)
{
    ...
}

RetryTimes 和 RetryTimeout 互斥，不能同时设置。

retry 预算会被两类事件消耗：

• Handler 返回 Retry。
• Handler 返回 Success 后，源状态持续可见并达到动作生效窗口上限。

状态变化后 retry 计数和 retry 计时都会重置。

什么时候用次数，什么时候用时间 Copy Chapter

用 RetryTimes：

• Handler 能明确判断本次动作失败。
• 每次 retry 的成本相近。
• 失败次数比耗时更能表达问题。

用 RetryTimeout：

• Handler 动作是幂等的。
• 没法确认本次动作是否已经触发转场。
• 可能卡在加载、动画、弹窗等中间态，按次数容易误杀。

例如“找不到活动入口”和“交互秘境入口后没法确认是否已经选中”属于同一类问题：动作可重复，但最终只能靠后续状态检测确认。这类节点更适合设置 RetryTimeout。

转场等待 Copy Chapter

DefaultTransitionTimeout 表示：Handler 返回 Success 后，源状态持续可见多久才认为本次动作没有生效。默认是 3000ms。达到这个窗口上限后，状态机会触发当前状态 retry。

DefaultIntermediateTransitionTimeout 表示：如果界面已经离开源状态，但还没到任何邻接目标，最多允许中间态持续多久。默认是 120000ms。这个设计是为了避免游戏加载、传送、黑屏等中间态被短动作窗口误判成当前状态 retry。

转场等待会按 DefaultDetectionInterval 持续轮询“邻接目标状态 + 源状态”，不会做全量状态检测。这样可以避免 MainWorld 这类宽泛状态在秘境入口、地图等场景误命中，导致当前节点本该 retry 的动作被误判成中间态。

等待期间按下面的规则计时：

• 检测到邻接目标状态：立即转换成功。
• 检测到源状态：说明动作还没有触发转场，动作生效窗口继续计时，中间态长超时重置。
• 源状态和邻接目标都没检测到：说明可能处于加载、黑屏、动画等中间态，动作生效窗口重置，中间态长超时继续计时。
• 中间态长超时：直接抛出中间态转换超时异常，不计入当前源状态的 retry 预算。

SuccessTo(targetStates...) 使用同一套转场等待机制，但将“邻接目标状态”收窄为 Handler 指定的目标集合。状态机在运行时校验每个目标确实是当前状态的合法邻接状态，并且已注册 Detector；校验失败属于状态图或 Handler 契约错误，不会静默回退到全部邻接状态。

例如同一个活动页可以按业务条件走不同真实屏幕节点：

return StateHandlerResult.SuccessTo(StygianState.MainWorld);

// 或
return StateHandlerResult.SuccessTo(
    StygianState.TeleportMap,
    StygianState.DomainEntrance);

前者适用于执行 Esc 后返回主界面，后者适用于点击“前往挑战”后可能进入传送地图或秘境入口。业务条件本身不需要注册为状态，只负责决定本次动作及其目标集合。

可以在节点上覆盖动作生效窗口：

[StateHandler(MyState.TeleportMap, TransitionTimeout = 10000)]
private async Task<StateHandlerResult> HandleTeleportMap(BvPage page)
{
    ...
}

Handler 内可读状态 Copy Chapter

Handler 内可以读取当前 retry 信息，用于调整动作强度或打印日志：

if (CurrentStateRetryCount > 3)
{
    Logger.LogWarning("当前状态已重试 {Count} 次", CurrentStateRetryCount);
}

可读属性：

这些属性都是只读保护属性，节点不能直接改框架内部计数。

完整示例 Copy Chapter

自动幽境危战任务是当前状态机的完整示例：

GameTask/AutoStygianOnslaught/AutoStygianOnslaughtTask.cs

简化状态图：

flowchart LR
    Unknown --> MainWorld
    MainWorld --> EventMenu
    MainWorld --> StygianOnslaughtPage
    EventMenu --> StygianOnslaughtPage
    StygianOnslaughtPage --> MainWorld
    StygianOnslaughtPage --> TeleportMap
    StygianOnslaughtPage --> DomainEntrance
    TeleportMap --> DomainEntrance
    DomainEntrance --> DifficultySelect
    DifficultySelect --> DomainLobby
    DomainLobby --> BossSelect
    DomainLobby --> LeylineFlowerPrompt
    BossSelect --> BattleArena
    BattleArena --> BattleResultWin
    BattleArena --> BattleResultLose
    BattleResultWin --> DomainLobby
    BattleResultLose --> BossSelect
    LeylineFlowerPrompt --> ResinSelect
    ResinSelect --> ContinueOrExit
    ResinSelect --> DomainLobby
    ContinueOrExit --> BattleArena
    ContinueOrExit --> MainWorld

幽境危战里的两个典型兜底：

[StateHandler(StygianState.EventMenu, RetryTimeout = 30000)]
private async Task<StateHandlerResult> HandleEventMenuState(BvPage page)
{
    ...
}

[StateHandler(StygianState.StygianOnslaughtPage, RetryTimes = 10)]
private async Task<StateHandlerResult> HandleStygianOnslaughtPageState(BvPage page)
{
    ...
}

EventMenu 使用时间预算，因为找不到活动入口时无法确认是否已经进入右侧详情页，只能交给后续状态检测兜底。StygianOnslaughtPage 使用次数预算，因为找不到“前往挑战”按钮是当前页内的明确失败。

常见坑 Copy Chapter

• 不要把自身放到邻接状态里。需要重复当前页面动作时，使用 Retry 或节点 retry 策略。
• 不要在 Detector 里点击或等待。Detector 只做识别。
• 不要让 Handler 自己写无限循环。循环、retry、超时交给状态机。
• 不要把所有状态都塞进邻接状态。邻接表越精确，误判越少。
• Wait 不消耗 retry。只在确实可预期等待时使用，否则可能靠 maxIterations 兜底才退出。
• Success 表示“动作已发出”，不是“已经到达下一页”。下一页确认由状态机的邻接状态检测完成。
• 如果节点动作可重复但无法确认效果，优先考虑 RetryTimeout。
• 如果节点失败很明确，优先考虑 RetryTimes。

迁移旧任务 Copy Chapter

旧代码如果手动调用 RegisterStateHandlers 和 RegisterStateDetectors，可以按下面步骤迁移：

1. 保留原来的状态枚举。
2. 在检测方法上加 [StateDetector(State, Order = n)]。
3. 在处理方法上加 [StateHandler(State)]。
4. 未知状态处理方法加 [UnknownStateHandler]。
5. 注册入口改成先调用 RegisterStateMethodsByAttribute()。
6. 保留并整理 RegisterStateTransitions(...)。
7. 把节点级 retry 策略从集中注册迁到对应 [StateHandler] 上。

迁移后，状态的检测逻辑、处理逻辑和节点策略都贴在方法声明处；状态图仍集中维护。

Docs Design Automation System (`Docs/design/automation-system.md`) Copy Section

Pulonia 任务系统设计总览

状态：讨论稿，尚未实施。2026-10-02 按主题拆分；当前进入开发计划的步骤 0：设计验收。

目标：普通玩家选择要培养的角色、要采集的物品并一键托管；高级玩家使用任务树组合能力；开发者使用同一个 C#/JS 执行入口。新菜单和页面最终替代配置组、一条龙、地图追踪与 JS 管理的旧实现，复用可靠的底层能力。

从哪里开始 Copy Chapter

先读用户故事与边界，再看开发与逐步验收计划。只讨论某个功能时，直接打开对应专题；原来的大文档内容已经移入下列文件。

核心决策 Copy Chapter

1. 使用 BetterGenshinImpact.Pulonia 命名空间和 PuloniaTask 相关实体；保留 d-v3 的 root_task / children 树格式。
2. 一条龙是同一份任务计划的简洁视图；托管生成计划，树编辑器手工编辑计划，所有入口复用同一执行语义。
3. 主链保持“入口 → 任务服务 → 类型执行器”，文件存储旁路提供支持。允许集中构建只读执行树；具体形式在模型阶段用样例验收，不再禁止第二种运行时表示，也不照搬层层转发的转换/调度链。
4. 触发、空闲准入与资源 CD 分开；开始执行前固定版本、解析有效配置，运行状态与编辑模型分开。
5. 游戏会话与截图按需获取，Shell 和纯计算任务不强制启动截图器；首版串行执行，共同管理输入所有权。
6. 完成结果必须附带证据，执行结束不自动等于采集或领奖成功；支持节点级续跑和有限异常恢复。
7. 不引入 Quartz、SQLite、ORM 或通用工作流框架。使用 .NET 调度循环、现有热键和 JSON 文件；当前不要求新增第三方库。

开发约定 Copy Chapter

每一步完成实现与自查后，提交给用户验收并停止；收到明确通过后才能开始下一步。 子步骤遵守同样规则。编译成功不能代替用户验收；当前整理文档不代表开始实施。

基础任务系统先可用，再补可靠调度、迁移、多账号和目标托管。完整 box、库存与圣遗物识别按能力分步验收，缺失能力明确标记。具体步骤与验收记录只维护在开发计划，其他文档不另存一套进度。

依据与维护方式 Copy Chapter

代码依据：本体 893777b4a、本地 d-v3@b7aa7fc66；脚本依据固定到远端提交 6be613e7dbb3debf7b242146fbee43ddd8a1b4a1。调研采用静态源码和文档阅读，未切换分支或运行游戏；issue 状态为核查当日状态，详见调研依据。

新增需求先更新用户故事与来源，再修改所属专题；涉及已验收合同或开发范围变化时同步更新计划并重新提交相关部分验收。本轮只整理 Markdown，不修改业务代码。

Docs Design Config Persistence (`Docs/design/config-persistence.md`) Copy Section

配置持久化链路（AllConfig 保存）优化

状态：已实施（第 1~3 项） · 2026-09-30

1. 背景 Copy Chapter

AllConfig 是全局唯一的配置对象，保存在 User/config.json 中。读取入口有两个，拿到的是同一个实例：

• 静态入口 TaskContext.Instance().Config，转发到 ConfigService.Config。有 296 处调用，分布在 120 个文件。
• DI 入口 IConfigService.Get()，约 27 个文件使用。

"全局静态、任何地方都能读写"这种用法本身不变。本次只改写入之后的链路：变更感知、触发器刷新和落盘。

2. 现状问题 Copy Chapter

2.1 每次属性变更的代价过高 Copy Section

AllConfig.OnAnyPropertyChanged 会在"调用方线程"上同步执行下面两步：

1. GameTaskManager.RefreshTriggerConfigs()：
   • 重新 Init() 7 个触发器。其中 AutoPick 会重读 3~4 个名单文件，AutoSkip 会重读 3 个 JSON。
   • SkillCd 的 Init() 会清空所有 CD 计时，所以改任何一个无关配置都会让 CD 提示归零。
   • 最后调用 DrawContent.ClearAll()，同步 Dispatcher.Invoke 到 UI 线程。
2. ConfigService.Save()：全量序列化后执行 File.WriteAllText。

XAML 里约有 44 处配置绑定使用了 UpdateSourceTrigger=PropertyChanged，每输入一个字符就会把上面两步完整走一遍。

File.WriteAllText 采用截断后覆盖写入。如果写到一半进程退出，文件就会损坏。现在的 BackupConfigFile 就是为这种情况兜底的。

2.2 自动保存的订阅不完整 Copy Section

InitEvent() 手写了 32 行 PropertyChanged +=，存在以下遗漏：

• 未订阅的一级配置：OtherConfig、RecordConfig、AutoComboBuildConfig、AutoGeniusInvokationConfig、GetGridIconsConfig。
• 所有嵌套对象，例如 OtherConfig.AutoRestartConfig、AutoFightConfig.FinishDetectConfig、PathingConditionConfig 中的 Condition、SkillCdConfig.CustomCdList 中的规则。
• 所有 ObservableCollection 的增删。

这些改动只有在托盘退出时由 NotifyIconViewModel.Exit() 顺带保存。进程被杀、崩溃，或者走 Environment.Exit 的重启路径时，改动都会丢失。

2.3 线程模型与注释不一致 Copy Section

ConfigService.Config 的注释写着"写入只有 UI 线程会调用"，但下面这些地方都会在非 UI 线程写配置：

• 任务线程：AutoFishingTask、AutoWoodTask、AutoLeyLineOutcropTask、TurnAroundMacro。
• 截图线程：SkillCdTrigger 检测到联机时，会在 OnCapture 内部关闭自身。
• 其他：WebView 桥和热键回调。

后果：

• 整份配置会在这些线程上序列化。如果 UI 线程同时在修改 List，就可能抛出 "Collection was modified"，异常最终会变成一个错误弹窗。
• SkillCdTrigger 这条路径会在持有 _triggerListLocker 的情况下同步写盘。

3. 目标与非目标 Copy Chapter

目标：

1. 保存做防抖和原子写，触发器只按变更来源定向刷新。
2. 自动覆盖整个配置对象图，新增配置类时不需要再去登记。
3. 任何线程都可以写配置，保存侧不再产生竞争。

非目标（留给后续）：

• 不改动 296 处调用点，也不引入新的访问入口。
• 不处理运行时状态混在配置中的问题：NextScriptGroupName、AutoLeyLineOutcropTask 临时替换 AutoFightConfig、临时打开 DisplayRecognitionResultsOnMask。
• 不处理多个实例（主实例与桌面分身）同时写同一个 config.json 时"后写者覆盖"的问题。

4. 设计 Copy Chapter

4.1 变更追踪：`ConfigChangeTracker` Copy Section

新增 Core/Config/ConfigChangeTracker.cs。它从 AllConfig 根节点开始，递归订阅：

遍历属性时，跳过以下几类：有索引参数的属性、没有公开 getter 的属性、标注 [JsonIgnore]（Condition = Always）的属性、值类型、string 和委托。每个 getter 都包在 try/catch 中。

订阅是增量且幂等的：

• 已访问的对象记录在 ConditionalWeakTable 中。同一对象只订阅一次，环也不会导致无限递归。弱引用不会阻止对象被 GC。
• 某个属性变更时，如果新值是可追踪对象（例如子配置被整体替换），就补订阅这个新值。PropertyName 为空时，重新遍历该对象的所有子节点。
• 集合发生 Add/Replace 时，补订阅新元素；发生 Reset 时，重新遍历整个集合。
• 被替换掉的旧对象不主动退订。它们以后如果再触发事件，只会多产生一次保存请求，没有副作用。

不做全量重扫，原因是 AutoLeyLineOutcropTask 会在战斗期间把 AllConfig.AutoFightConfig 临时换成另一个实例。如果此时全量重扫，追踪就会挂到这个临时对象上，而原对象丢失订阅。增量订阅不会去读根节点上没有通知能力的自动属性，所以不受这次临时替换的影响。

每次变更都会回调 onChanged(sender)，回调在触发事件的线程上同步执行。

4.2 触发器定向刷新 Copy Section

已被 实时触发器生命周期与启停设计 取代：RefreshTriggerConfigs 已删除，tracker 回调只负责保存（sender 为 MaskWindowConfig 时额外清画布），触发器改为每帧读取配置。下文保留为历史记录。

AllConfig.InitEvent() 改为创建 tracker，回调中做两件事：

1. GameTaskManager.RefreshTriggerConfigs(sender)（新增重载）。
2. OnAnyChangedAction?.Invoke()，也就是 ConfigService.RequestSave。

NotificationConfig 仍然单独订阅，用来调用 NotificationService.RefreshNotifiers()。

各触发器的 Init() 只依赖自身对应的那份子配置（已逐一核对），映射如下：

当有触发器被刷新，或者 sender 是 MaskWindowConfig 时，额外执行一次 DrawContent.ClearAll()。这样可以保留两种原有行为：关闭触发器时擦掉它的残留绘制，以及切换识别结果显示开关时清掉过期的图形。其他配置变更不再刷新触发器，也不再清空画布。

刷新仍然是同步执行的，不做防抖，因此"改开关后触发器立即生效"的语义保持不变。

显式调用无参 RefreshTriggerConfigs() 的地方保持全量刷新，比如 AutoPick 名单编辑窗口：它只改了文件，配置里的 bool 值可能没有变化。

4.3 保存调度 Copy Section

ConfigService 内部维护两个版本号：

• _changeSeq：每次保存请求时加 1。
• _persistedSeq：已经落盘的快照对应的 _changeSeq。

两者不相等时，表示有未保存的改动。

防抖（RequestSave，任意线程可调用）：

1. _changeSeq++。如果当前没有待执行的保存，就启动一个 500ms 的定时器。窗口内的多次请求合并为一次，最大延迟有上限。
2. 定时器触发后，在 UI 线程上以 DispatcherPriority.Background 生成快照：先读取 _changeSeq，再序列化得到 JSON。
3. 回到线程池执行原子写。写入前检查：如果快照的版本号不大于 _persistedSeq，说明已经有更新的内容落盘，本次直接跳过。

快照放在 UI 线程生成，是因为绝大多数集合（包括所有 WPF 绑定的 ObservableCollection）都只在 UI 线程修改，在这里序列化就不会与它们竞争。任务线程改的是标量或引用，读取本身是安全的。

兜底策略：

• UI 线程 3 秒内没有执行，或者 Dispatcher 已经开始关闭时，改在当前线程生成快照。
• 快照生成抛异常（多半是其他线程正在改集合）时，稍后重试。连续失败 3 次后弹窗提示，并停止自动重试，等到下一次改动或退出时再尝试。

读写互不阻塞：

• 代码中读写配置（Config.Xxx）操作的是内存对象，全程不加锁，写完立即可读。保存链路只登记改动，不拦截任何读写。
• 生成快照时持有的锁只在快照之间互斥，不影响属性读写。其他线程在快照期间照常读写；期间发生的改动版本号更大，会进入下一次保存。
• 读文件（Read()）不加锁。原子替换保证读取方只会看到完整的旧文件或新文件。文件内容比内存最多落后一个防抖窗口，需要最新文件内容的地方先调用 Flush()。
• 反过来，如果读取方打开文件时没有开放删除共享，替换会短暂失败。这时由写入方重试，读取方不受影响。

原子写：

1. 写入临时文件 config.json..<guid>.tmp，内容为 UTF-8 无 BOM，然后 Flush(true)。
2. 用 File.Move(tmp, config.json, overwrite: true) 替换正式文件。这是同卷 rename，读取方只会看到旧文件或新文件，不会看到写了一半的文件。
3. 替换时如果遇到共享冲突，最多重试 5 次，每次间隔 50ms，最后仍失败则弹窗，与现有行为一致。
4. 临时文件名带上进程号和 GUID，避免主实例和桌面分身互相踩到同一个临时文件。
5. 启动时清理 1 分钟前残留的临时文件。

4.4 立即保存与退出落盘 Copy Section

• Save()：先执行 _changeSeq++，再同步生成快照并写盘，语义与现在一致（立即写）。不在 UI 线程时，用 Dispatcher.Invoke 生成快照，超时后退回当前线程。
• Flush()（IConfigService 新增）：只在有未保存改动时执行 Save()。

调用点：

Process.Kill 和崩溃时，最多丢失最近约 500ms 内的改动。

5. 行为变化 Copy Chapter

6. 改动清单 Copy Chapter

• 新增 Core/Config/ConfigChangeTracker.cs。
• Core/Config/AllConfig.cs：InitEvent() 改用 tracker，删除 OnAnyPropertyChanged。
• GameTask/GameTaskManager.cs：新增 RefreshTriggerConfigs(object? changedConfig)。
• Service/ConfigService.cs、Service/Interface/IConfigService.cs：实现保存调度、原子写和 Flush()。
• App.xaml.cs、GameTask/SystemControl.cs、Service/ChildSession/ChildSessionProcessLauncher.cs、Core/Script/WebView/RepoWebBridge.cs：在对应位置调用 Flush()。

Docs Design Game Runtime (`Docs/design/game-runtime.md`) Copy Section

BetterGI 游戏运行环境 GameRuntime 设计

状态：P1、P2 已实现（第 6 版） · 2026-09-30 · 前置：InputHub 设计

第 6 版变更（维护者要求与 feat/yys 的目标对齐，正文已同步，汇总见第 11 节）：

• 实例名参数改为 --instance-name，并登记到根实例的端点。
• 数据目录改为 WebView2Data/CloudGame/<实例名>。
• 页面地址固定为 https://ys.mihoyo.com/cloud/?autobegin=1，删除 CloudWebConfig。
• WebView2 禁止缩放、关闭状态栏，开发者工具只在 Debug 下可用。
• 页面固定按 100% 渲染，不跟随系统缩放；宿主改为直接托管 CoreWebView2Controller，不再使用 WPF WebView2 控件（7.2）。
• 宏回放改走 InputHub；网页版跳过本地原神设置检查。

第 5 版变更（维护者要求，正文已同步）：

• 网页版截图改用 WGC（GraphicsCapture），不再用 GraphicsCaptureV2。
• 宿主客户区锁定为 1920×1080 物理像素，不能调整大小或最大化。
• 网页版实例不显示主界面，只显示宿主窗口；关闭宿主即退出实例。原先为网页版准备的主界面改动随之删除。

第 4 版变更：P2 落地，与设计有出入的地方已同步到正文，汇总见第 11 节"P2 实施说明"。

第 3 版变更：落实第 15 节的确认结果。

• 页面默认地址为 https://ys.mihoyo.com/cloud/。
• 网页版实例不响应任何热键。
• 宿主禁用 Chromium 的遮挡与后台降频。
• RTC 断线只停止截图器。
• 文字输入只加注释，不做适配。
• 配置共享问题由维护者另行安排。

第 2 版变更：

• P1 优化：
  • Provider 的两个启动方法合并为 AcquireAsync。
  • WinEventHook 改为只订阅游戏进程，并去掉 SKIPOWN 标志。
  • WebPageGameWindow 改为继承 Win32GameWindow。
  • 启动统一切到 UI 线程执行。
  • 截图参数改为集中构建。
• P2 补充：
  • 网页版实例改为"命名多实例"，WebView 数据按实例名存放。
  • 补充宿主窗口、截图、输入精简与接入的设计。

1. 背景 Copy Chapter

BetterGI 目前只支持一种运行环境：本机上的一个 Win32 游戏窗口（本地原神或 Windows 云原神客户端）。代码里没有"运行环境"类型，整个程序用一个 IntPtr GameHandle 表示它，相关职责分散在四处：

云原神网页版运行在 WebView2 中，和 Win32 窗口有四点不同，现有的 hWnd 模型接不进去：

1. 游戏"进程"就是 BetterGI 自己。GameProcess.HasExited 永远为 false；按进程名判断前台时，BetterGI 主窗口也会被当成游戏。
2. 输入经 RTC 数据通道发往云端，不需要前台。但 TaskControl 的每次 Sleep / Delay 都会检查前台并抢焦点。
3. 宿主窗口和调度器在同一进程。Dispatcher 的 WinEventHook 带 WINEVENT_SKIPOWNPROCESS，收不到宿主窗口的事件。
4. 截图方式应该由运行环境决定，但现在只能来自用户配置。

启动链路上还有几处反 DI 的写法：

• ScriptService.StartGameTask 通过 App.GetService<HomePageViewModel>() 反向调用 ViewModel；
• TaskTriggerDispatcher 自己创建截图器；
• TaskContext 可以在任何地方被写入。

2. 目标与非目标 Copy Chapter

目标：

• 把"窗口 + 截图 + 输入"收成一个可替换的单元 GameRuntime，由各环境的 Provider 产出。
• 实现两种运行环境：Win32Window（现有行为）和 WebPage（云原神网页版）。
• 网页版以命名实例运行，可以同时开多个，每个实例使用独立的 WebView 数据目录。
• 运行环境由 DI 管理。TaskContext、SystemControl、InputHub 保留为静态入口并改为转发，500+ 调用点不改。
• 精简 TaskContext 与现有的 WebSdk 输入实现。

非目标：

• 一个进程同时驱动多个游戏。一个进程同一时刻只有一个运行环境，多开靠多进程。
• 主实例与网页版实例之间的任务下发和状态回传（task.* IPC）。
• 按实例拆分 User/config.json。由维护者另行安排，见第 15 节。
• 网页版的文字输入适配，见 7.5。
• 游戏画面没有铺满 WebView 时的子区域裁剪。
• 静态调用点改为构造注入（P3 渐进进行）。

3. 术语 Copy Chapter

实例类型与运行环境一一对应，不需要配置项：

Wine 不算运行环境：它仍然是 Win32 窗口，保留现有的 WinePlatformAddon 分支。

4. 实例拓扑 Copy Chapter

Primary（BetterGI.exe）
├─ GameRuntimeService ─ Win32RuntimeProvider
├─ 调度器 / 任务 / 脚本 / 遮罩
└─ 首页「云原神网页版」卡片 ─ WebViewInstanceStore（实例名列表）
      │ WebViewInstanceLauncher.Launch("小号A")
      ▼
网页版实例「小号A」（BetterGI.exe --instance webview --instance-name 小号A start）
├─ GameRuntimeService ─ WebPageRuntimeProvider
├─ 调度器 / 任务 / 脚本 / 遮罩（功能完整，由命令行驱动）
├─ 不创建 MainWindow
└─ CloudWebHostWindow ─ WebView2（唯一界面，即 Application.MainWindow；数据目录 WebView2Data/CloudGame/小号A）

网页版实例「小号B」……（结构相同，与「小号A」互不影响）

• 每个进程各有一套运行环境、调度器和任务。TaskContext、InputHub、TaskTriggerDispatcher 都是进程级单例，天然隔离。
• 网页版实例通过已有的根管道登记到 Primary（WebViewConnectionsByProcessId），本期不新增 IPC 操作。
• 同名实例同一时刻只能运行一个，靠实例名互斥体保证（7.1）。

5. 运行环境抽象（L2） Copy Chapter

5.1 层级与依赖规则 Copy Section

L4 使用方    Task / Trigger / JS 脚本 / Region / 遮罩 / HomePageViewModel / ScriptService
               │ 只依赖 L3 和 L2
L3 编排层    GameRuntimeService（DI 单例）；TaskContext（静态入口，只读转发）
L2 抽象层    GameRuntime = IGameWindow + IGameCapture + IInputBackend；IGameRuntimeProvider
L1 实现层    Win32   ：Win32GameWindow、Win32RuntimeProvider
             WebPage ：WebPageGameWindow（继承 Win32GameWindow）、WebPageRuntimeProvider、CloudWebHostWindow
L0 原始层    SystemControl 的 Win32 函数 / Fischless.GameCapture / InputHub 各后端 / WebView2

• 只允许上层依赖下层。L4 唯一可以直接用 L1 的地方是手动选窗：Win32RuntimeProvider.AttachTo(hWnd)，而且这个入口只在 Win32 实例中显示。
• IGameCapture 和 IInputBackend 直接复用，不再包一层。
• 目录：
  • 抽象与实现放在 GameTask/Runtime/{Win32,WebPage}，命名空间为 BetterGenshinImpact.GameTask.Runtime；
  • 宿主窗口放在 View/Windows/CloudWebHostWindow.xaml；
  • 实例名存储与启动器放在 Service/Instance/。

5.2 类图 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

5.3 接口定义 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

GameRuntimeService 的公开成员：

6. Win32 实现（P1） Copy Chapter

6.1 Win32GameWindow Copy Section

/// <summary>在 UI 线程创建（WinEventHook 需要消息循环）</summary>
public class Win32GameWindow : IGameWindow
{
    public Win32GameWindow(nint hWnd);

    public nint Handle { get; }
    public int ProcessId { get; }                       // GetWindowThreadProcessId(Handle)
    public GameViewport Viewport =>                     // 沿用现有算法
        new(SystemControl.GetCaptureRect(Handle), DpiHelper.GetScale(Handle).Y);
    public virtual bool IsAlive => !_process.HasExited;
    public bool IsForeground => User32.GetForegroundWindow() == Handle;
    public bool IsMinimized => User32.IsIconic(Handle);
    public virtual bool RequiresForeground => true;
    public virtual void Activate();                     // 原 SystemControl.ActivateWindow(hWnd)
    public event EventHandler? ViewportChanged;
    public virtual void Dispose();                      // 解除钩子，释放 Process
}

WinEventHook 从 Dispatcher 搬进这里，同时做两处调整：

• idProcess 传 ProcessId，不再订阅全系统。现在的钩子会收到所有进程的 LOCATIONCHANGE 事件（光标、插入符移动也算），全部在 UI 线程上过滤。
• 去掉 WINEVENT_SKIPOWNPROCESS | WINEVENT_SKIPOWNTHREAD。钩子已经限定到游戏进程，不再需要这两个标志；网页版宿主和 BetterGI 同进程，也因此能收到事件。回调仍然按 hwnd == Handle && idObject == 0 过滤。

6.2 Win32RuntimeProvider Copy Section

截图参数由 GameCaptureSettings.From(AllConfig) 集中构建，生成的就是现在 Dispatcher 里那个字典：autoFixWin11BitBlt、MinUpdateIntervalMs、UseCpuConvert。两个 Provider 都用它。

原 TaskContext.GetGenshinGameProcessNameList 移到 SystemControl.GetGenshinGameProcessNameList()，因为找窗函数 FindGenshinImpactHandle 仍在那里，DialogueOptionVoiceDiagnosticService 也直接使用它：

• 已绑定 Win32 窗口时，返回 Win32GameWindow.ProcessName；
• 否则返回候选进程名。

StartFromLocalAsync 同样留在 SystemControl，作为 L0 函数由 Provider 调用。

7. 网页版实现（P2） Copy Chapter

7.1 命名实例 Copy Section

实例名规则由 WebViewInstanceStore 统一校验：

• 去掉首尾空白后长度为 1~32；
• 不含 \ / : * ? " < > | 和控制字符，不以 . 结尾（因此也排除了 . 和 ..）；
• 不能是 Windows 保留名（CON、PRN、AUX、NUL、COM19、LPT19），按第一个 . 之前的部分判断，CON.txt 同样被拒绝；
• 不区分大小写，不能重名。

这套规则与 feat/yys 的 WebViewInstanceName 等价，唯一的区别是末尾空格：feat/yys 直接拒绝，这里去掉后接受。

WebViewInstanceStore 同时负责存储：

启动参数与实例身份：

• WebViewInstanceLauncher.Launch(name) 的参数为 --instance webview --instance-name <name> start，路径取 Environment.ProcessPath。以 dotnet dll 方式运行时，参考 ChildSessionProcessLauncher.CreateBetterGiStartInfo。参数名与 feat/yys 一致。
• CommandLineOptions 像处理 --instance 那样剥离 --instance-name，存为 InstanceName。InstanceContext 增加 InstanceName，只有 WebView 实例有值。
• InstanceBootstrap 对 WebView 实例额外做两件事：
  • 没有 --instance-name 或名称不合法时提示并退出；
  • 获取实例名互斥体（进程内一直持有），已被占用时提示"实例「name」已在运行"并退出。带 --restart-from-pid 时最多等待 15 秒，让应用内重启的旧进程先退出；旧进程未释放就退出时按已获取处理（AbandonedMutexException）。
  • 提示使用 WinForms MessageBox，和 App 启动失败时的兜底方式一样。
• WebViewInstanceLauncher.Launch 只启动已存在的实例（目录存在）且未在运行的实例，启动前先 IConfigService.Flush()，与桌面分身一致。
• SystemControl.RestartApplication 对 WebView 实例追加 --instance-name。
• 日志标识 BgiInstance 带上实例名，例如 WebView(小号A):S1:P1234:T…。
• 实例名随 connection.open（ConnectionOpenRequest.InstanceName）登记到根实例，写入 InstanceEndpoint.InstanceName，webview.list 按实例名排序。Primary 和其他实例因此能按名称识别网页版实例。
  • 根实例不按名称判重，同名互斥只由互斥体保证。应用内重启时，旧进程的连接可能还没被根清理，在根上判重会误拒新进程。

网页版实例不创建 MainWindow，ApplicationHostService 改走 HandleWebViewActivation：

• 总是调用 HomePageViewModel.HandleActivation → GameRuntimeService.StartAsync，与有没有 start 参数无关（例如应用内重启）。宿主窗口在 StartAsync 的同步阶段创建，并设为 Application.MainWindow，之后等待绑定。
• 一条龙：依次调用 OneDragonFlowViewModel.OnNavigatedTo()（加载配置列表）和 LoadedCommand（读取命令行后执行），与页面被导航到时的顺序一致。
• 配置组 / 任务进度：直接调用 ScriptControlViewModel 的对应方法。
• 这些命令都由 StartGameTask 自行启动截图器，与上面的自动启动走同一个串行的 StartAsync，不会重复绑定。

7.2 宿主窗口 CloudWebHostWindow Copy Section

约束：

• 使用系统标题栏的普通 WPF Window，不用自绘标题栏（例如 FluentWindow + ExtendsContentIntoTitleBar）。自绘标题栏属于 Win32 客户区，会被截进画面，坐标也会偏。
• WebView2 铺满客户区，不留边距，也不放工具栏。
• 页面固定按 100% 渲染，不跟随系统缩放：
  • WebView2 默认按显示器 DPI 设置 RasterizationScale。150% 缩放时页面视口只有 1280×720 CSS 像素，页面自己的悬浮菜单、登录框等都会跟着放大，不同机器上的页面布局也不一样。
  • 宿主关闭 ShouldDetectMonitorScaleChanges，把 RasterizationScale 固定为 1，BoundsMode = UseRawPixels、Bounds 为客户区物理像素。页面视口因此始终是 1920×1080 CSS 像素，devicePixelRatio 为 1。
  • WPF 的 WebView2 控件不公开 CoreWebView2Controller，做不到这一点，所以宿主不用该控件，而是用 CoreWebView2Environment.CreateCoreWebView2ControllerAsync(Handle) 直接托管在窗口句柄上。宿主自己负责：客户区尺寸变化时更新 Bounds、窗口移动时 NotifyParentWindowPositionChanged、窗口激活时 MoveFocus（否则登录时键盘输入不进页面）、关闭时 Close。
  • 标题栏和边框属于非客户区，仍由系统按 DPI 绘制，不影响截图。
• 客户区锁定为 1920×1080 物理像素，不随 DPI 缩放，截图和识图直接工作在 1080P 下：
  • ResizeMode="CanMinimize"：不能拖动调整大小，也不能最大化；
  • SourceInitialized 中用 SetWindowPos 设置外框尺寸（当前边框 + 1920×1080），不走 DIP 换算，避免舍入误差；首次设置时按 Screen.FromHandle 的物理像素工作区居中，工作区放不下时记 warn，窗口会超出屏幕；
  • OnDpiChanged（拖到 DPI 不同的显示器）中重新锁定，因为 WPF 会按 DIP 缩放窗口。
• 不设 Topmost。现有 WGC 对 Topmost 窗口不做客户区裁剪。
• 网页版实例没有主界面，宿主就是唯一的窗口：由 WebPageRuntimeProvider 设为 Application.MainWindow，供对话框 Owner、UIDispatcherHelper.MainWindow 等使用。
• 标题为"云原神 · {实例名}"。关闭宿主窗口即退出实例（Closed 中 BeginInvoke(Application.Shutdown)），CloseGame 也会走到这里。

初始化：

1. 创建 CoreWebView2Environment，用户数据目录为 WebViewInstanceStore.GetDataFolder(实例名)，并通过 AdditionalBrowserArguments 禁用遮挡与后台降频：
   text Copy

   --disable-features=CalculateNativeWinOcclusion
   --disable-backgrounding-occluded-windows
   --disable-renderer-backgrounding
   --disable-background-timer-throttling

   • 前两项让宿主在被遮挡时照常渲染，否则 WGC 会一直拿到旧帧（7.4）。
   • 后两项让页面在后台不降低优先级，也不限流定时器。SDK 的 tapKey / click 用 setTimeout 控制按住时长，限流后按键时序会被拉长。
   • 每个实例的数据目录都是独立的，这些参数不会和 HtmlMask 等功能的 WebView2 环境冲突。
2. controller = await environment.CreateCoreWebView2ControllerAsync(Handle)，然后设置（ConfigureController）。页面必须按 1:1 铺满 1920×1080 客户区，截图与输入坐标才一致：
   • ShouldDetectMonitorScaleChanges = false，RasterizationScale = 1，BoundsMode = UseRawPixels：不跟随系统缩放（见上）；
   • IsZoomControlEnabled = false，ZoomFactor = 1：禁止 Ctrl + 滚轮 / Ctrl + +/- 缩放（与 feat/yys 一致，下同）；
   • IsStatusBarEnabled = false：左下角的链接状态栏会被截进画面；
   • AreDevToolsEnabled = RuntimeHelper.IsDebug：开发者工具只在 Debug 下可用；
   • IsWebMessageEnabled = true：输入桥依赖 WebMessage，显式开启。
3. bridge = await WebView2InputBridge.InstallAsync(core)：注入 SDK 和分发脚本，然后返回桥（7.5）。
4. 导航到固定地址 https://ys.mihoyo.com/cloud/?autobegin=1（常量 CloudGameUrl，与 feat/yys 一致）。autobegin=1 让页面加载后自动开始游戏，不需要手动点"开始游戏"。不提供配置项：config.json 由所有实例共享，没法按实例区分。

就绪检测：

• 用 DispatcherTimer 每秒调用一次 bridge.GetStatusAsync()。rtcDataChannelState == "open" 且 gameDataStarted == true 时，IsGameReady 为 true。
• 已就绪之后，连续 3 次未就绪（约 3 秒）才判定为断开，避免单次查询失败就停掉任务。
• 断开后只让截图器停止（Tick 发现 IsAlive == false），不自动刷新页面，也不自动重新绑定。网页版实例没有主界面、不响应热键，无法手动重新启动截图器，需要关闭宿主窗口（即退出实例）后从 Primary 重新启动。这条限制写在 CloudWebHostWindow 和 WebPageGameWindow.IsAlive 的代码注释里，避免以后有人误以为这里会自动重连。
• IsGameReady 用 volatile 字段保存。Tick 线程通过 WebPageGameWindow.IsAlive 读取它。
• WaitGameReadyAsync(ct) 等到就绪为止，不设短超时，因为登录和排队可能要几分钟。就绪返回 true，宿主被关闭返回 false，取消时抛 OperationCanceledException。未就绪的原因（例如页面更新导致 ClientCore 模块找不到）只在变化时记一条 Debug 日志。
• 初始化失败（例如未安装 WebView2 Runtime）时弹出错误提示并关闭窗口，等待中的启动随之返回。

7.3 运行环境：WebPageGameWindow 与 WebPageRuntimeProvider Copy Section

宿主是一个真实的顶层 Win32 窗口，而且 WebView 铺满客户区，所以 WebPageGameWindow 继承 Win32GameWindow，只覆写三个成员：

public sealed class WebPageGameWindow(CloudWebHostWindow host) : Win32GameWindow(host.Handle)
{
    /// <summary>宿主关闭后 IsGameReady 为 false</summary>
    public override bool IsAlive => host.IsGameReady;

    public override bool RequiresForeground => false;

    /// <summary>只从最小化还原，不抢前台</summary>
    public override void Activate()
    {
        if (IsMinimized)
        {
            User32.ShowWindow(Handle, ShowWindowCommand.SW_RESTORE);
        }
    }
}

以下成员直接继承，不需要单独实现：

• Viewport、IsForeground、IsMinimized、ProcessId（即当前进程）；
• ViewportChanged：钩子限定到当前进程即可收到宿主事件。

WebPageGameWindow 还订阅宿主的 Closing 事件，在其中调用 InputHub.ReleaseAll()（input-hub.md 5.7.5 第 5 步）。Closing 在 UI 线程上触发，桥会直接投递 releaseAll（7.5），能在页面销毁前送达。

AcquireAsync 在就绪后先调用一次 window.Activate()：宿主最小化时 WGC 拿不到帧，画面尺寸也不满足 SystemInfo 的要求。

WebPageRuntimeProvider.AcquireAsync：

1. host = 已有宿主 ?? 新建 CloudWebHostWindow，设为 Application.MainWindow 并 Show()   Provider 持有宿主
2. await host.WaitGameReadyAsync(ct)                           日志：等待云原神就绪（登录 / 排队）
3. window  = new WebPageGameWindow(host)
   capture = new GraphicsCapture(); capture.Start(host.Handle, GameCaptureSettings.From(config))
             与 Win32 路径一样在 UI 线程上创建（帧池用 Direct3D11CaptureFramePool.Create）
   input   = new WebSdkInputBackend(host.Bridge, () => window.Viewport.ScreenRect)
4. return new GameRuntime(GameRuntimeKind.WebPage, window, capture, input)

CloseGame 关闭宿主窗口（经 Dispatcher 切到 UI 线程），宿主关闭即退出实例。GameRuntime.Dispose 不关闭宿主，和"停止截图器不关闭本地游戏"一致。

7.4 截图 Copy Section

• 固定使用 WGC（GraphicsCapture，不是 GraphicsCaptureV2），对宿主窗口句柄截图，参数取 GameCaptureSettings.From(config)，不读 CaptureMode。
  • 不读 CaptureMode 是因为 config.json 由所有实例共享，网页版实例改了它会影响 Primary。
  • 网页版实例没有主界面，截图模式等 Win32 专属设置本来就看不到。
• Fischless.GameCapture 不改。现有 WGC 已经会从窗口裁出客户区，而 7.2 的约束保证客户区就是 1920×1080 的游戏画面。
• 宿主和 BetterGI 同进程，WGC 可以用 CreateForWindow 截取本进程的窗口。WebView2 的内容在宿主的子 HWND 中渲染，由 DWM 合成到宿主窗口，需要实测确认能截到（13.2 #3）。
• WGC 在没有新帧时会返回缓存帧。如果 Chromium 在宿主被遮挡时停止渲染，任务会拿到旧画面而不自知。因此宿主通过浏览器参数禁用了遮挡降帧（7.2），测试见 13.2 #5。
• 扩展方式：以后如果需要其他截图方式（例如 CoreWebView2.CapturePreviewAsync），新增一个 IGameCapture 实现，由 WebPageRuntimeProvider 选择，上层不受影响。

7.5 输入：接入与精简 Copy Section

Resources/JavaScript/ys-input-inject.js 与 E:\HuiTask\云原神\_analysis\ys-input-inject.js 的内容一致，只是换行符不同。但 csproj 里没有任何打包项，发布后找不到这个脚本。

现有 Core/Input/Backends/WebSdk/ 有 5 个文件，精简为 4 个：

桥的实现要点：

• 注入：ys-input-inject.js 设为 EmbeddedResource（LogicalName BetterGenshinImpact.Resources.JavaScript.ys-input-inject.js），InstallAsync 用 AddScriptToExecuteOnDocumentCreatedAsync 注入它和 BootstrapScript。宿主只需要调用这一个方法，构造函数和 BootstrapScript 改为私有。
  • 注入脚本也会在子 frame 中执行，而子 frame 没有 chrome.webview：SDK 原文不改，外面包一层 if (window.top === window)；分发脚本同样只在顶层文档生效。
• 调用：其他线程由 Dispatcher.Invoke 改为 Dispatcher.BeginInvoke，UI 线程上直接投递。
  • 同优先级的调用按 FIFO 执行，同一线程内顺序不变；
  • 任务线程不再阻塞，也不会在 UI 线程同步等待任务时死锁；
  • UI 线程直接投递，保证宿主 Closing 中发出的 releaseAll 能在页面销毁前送达；
  • 投递失败（例如页面已关闭）在 UI 线程内捕获并限频打 warn；桥已释放时 Invoke 同步抛 InvalidOperationException，与原契约一致。
• 状态：GetStatusAsync() 执行 ExecuteScriptAsync，在页面内用 try/catch 包住 window.__ysInputInject?.status()，返回 WebSdkStatus(RtcDataChannelState, GameDataStarted, Error)，其中 IsReady => RtcDataChannelState == "open" && GameDataStarted == true。
• 错误：删除 InvokeFailed 事件。它现在没有订阅者，页面断开改由状态轮询发现。页面回报的调用错误限频打 warn。

扩展方式：

• 键鼠接口表达不了的能力，直接调用 WebSdkInputBackend.Sdk.Invoke(方法名, 参数)，不用改接口。
• 文字输入本期不适配，只在 GlobalMethod.InputText 上加注释。注释写明三点：
  • 网页版下，写本机剪贴板对云端无效；
  • 需要时可以把"写本机剪贴板"换成 Sdk.Invoke("sendClipboard", text)，或者直接调用 Sdk.Invoke("sendIme", text)；
  • 两种方式都没有实测过。
• WebSdkInputBackend 里相对移动和滚轮的系数 TODO 保留，P2 测试时一起标定。

接入：由 WebPageRuntimeProvider 创建后端，GameRuntimeService 负责 InputHub.Attach。落地后同步更新 input-hub.md 的 5.7.5 和 5.9。

7.6 界面 Copy Section

Primary 的首页新增「云原神网页版」卡片，只在 IsRoot 时显示：

• 实例名下拉框，数据来自 WebViewInstanceStore.List()，并用 IsRunning 标出运行中的实例（"名称（运行中）"）；
• 刷新、启动、新建（PromptDialog 输入名称并校验）、删除（ThemedMessageBox.QuestionAsync 二次确认）四个按钮。
• 实例正在运行时禁用启动和删除。运行状态在进入首页、启动实例 3 秒后、点击刷新时更新。

Primary 的首页：截图器启动过程中（GameRuntimeService.IsStarting），启动按钮显示为"停止"；停止按钮提交停止请求，在本次启动结束后解绑（获取完成后直接放弃，不再绑定）。

网页版实例：

• 不显示主界面，只显示宿主窗口（7.1、7.2）。任务由启动参数决定：默认只启动截图器（实时触发器照常工作），一条龙、配置组、任务进度由对应的命令行参数触发。
• 因为没有主界面，原先为网页版准备的界面改动都已去掉：标题栏徽章、首页隐藏 Win32 专属设置、"等待云原神就绪"提示、热键页 InfoBar。
  • "同时启动原神"卡片里的配置仍按共享配置生效，例如"自动进入游戏"对网页版同样有效。
• 要结束等待或结束实例，关闭云原神窗口即可。
• 不响应任何热键，全局热键和键鼠监听都算在内：
  • HotKeyPageViewModel.IsHotKeyEnabled 在网页版实例中为 false，跳过全部 RegisterHotKey。热键原本在 HomePage 构造时初始化，网页版实例不创建页面，所以这里只是兜底；
  • 热键配置由所有实例共享，只能在 Primary 中编辑；
  • 这样也避开了同一 Session 中全局热键只能被先启动的实例注册的问题。

8. 生命周期、所有权与 DI Copy Chapter

启动（首页按钮 / ScriptService.StartGameTask / 命令行 start）
  GameRuntimeService.StartAsync(ct)             切到 UI 线程；串行；已在运行时返回 true
    1. runtime = await provider.AcquireAsync(ct)    期间 IsStarting = true；返回 null 时整体返回 false
       获取期间收到停止请求（stopVersion 变化）：释放 runtime，返回 false，不绑定
    2. TaskContext.Instance().Bind(runtime)         由 Viewport 构建 SystemInfo，记录 DpiScale 快照
    3. InputHub.Attach(runtime.Input)
    4. dispatcher.Start(runtime, interval)          加载触发器，订阅 ViewportChanged，启动定时器
    5. 触发 Started                                  HomePageViewModel 显示遮罩；Win32 实例订阅 MouseKeyMonitor
    第 2~4 步任一步抛异常：回滚已完成的步骤，然后 runtime.Dispose()

停止（按钮 / Tick 发现 !IsAlive 或截图器停止 / 切换截图模式）
  GameRuntimeService.StopAsync()
    0. 等待 _startLock；停止请求之前排队的 StartAsync 跳过绑定
    1. CancellationContext.Instance.Cancel()
    2. dispatcher.Stop()
    3. InputHub.ReleaseAll()，然后 Attach 未绑定后端     显式释放旧后端输入，再切换
    4. TaskContext.Instance().Bind(null)
    5. runtime.Dispose()
    6. 触发 Stopped                                  HomePageViewModel 隐藏遮罩，取消订阅

services.AddSingleton<Win32RuntimeProvider>();
services.AddSingleton<IGameRuntimeProvider>(sp => sp.GetRequiredService<Win32RuntimeProvider>());
services.AddSingleton<IGameRuntimeProvider, WebPageRuntimeProvider>();
services.AddTransient<CloudWebHostWindow>();
services.AddSingleton<Func<CloudWebHostWindow>>(sp => () => sp.GetRequiredService<CloudWebHostWindow>());
services.AddSingleton<GameRuntimeService>();
services.AddSingleton<WebViewInstanceStore>();
services.AddSingleton<WebViewInstanceLauncher>();

GameRuntimeService 通过构造函数注入：

• IEnumerable，按 InstanceType == WebView ? WebPage : Win32Window 从中选定；
• InstanceBootstrap、TaskTriggerDispatcher、IConfigService、ILogger<GameRuntimeService>。

HomePageViewModel 在启动时一定会被创建：Primary 中 ApplicationHostService 总是先导航到首页；网页版实例没有页面，由 HandleWebViewActivation 直接从 DI 取出它。所以遮罩交给它管理，GameRuntimeService 不依赖任何 View。

9. TaskContext 拆分 Copy Chapter

使用次数按 TaskContext.Instance().成员 统计。

public class TaskContext
{
    public static TaskContext Instance() { /* 不变 */ }

    /// <summary>当前运行环境。截图器未启动时为 null</summary>
    public GameRuntime? Runtime { get; private set; }

    public bool IsInitialized => Runtime is not null;

    /// <summary>最近一次绑定的窗口句柄，解绑后保留。兼容旧调用点，新代码请使用 Runtime.Window</summary>
    public IntPtr GameHandle { get; private set; }

    /// <summary>绑定时的快照。解绑后保留最后一次的值，与现状一致</summary>
    public float DpiScale { get; private set; }

    /// <summary>绑定时由 Viewport 构建。解绑后保留最后一次的值，与现状一致</summary>
    public ISystemInfo SystemInfo { get; private set; }

    /// <summary>只是转发 ConfigService.Config。新代码请注入 IConfigService</summary>
    public AllConfig Config => /* 不变 */;

    internal void Bind(GameRuntime? runtime)
    {
        if (runtime is not null)
        {
            var viewport = runtime.Window.Viewport;
            SystemInfo = new SystemInfo(viewport); // 分辨率不合规时抛异常，Runtime 保持不变
            DpiScale = viewport.DpiScale;
            GameHandle = runtime.Window.Handle;
        }

        Runtime = runtime;
    }
}

ISystemInfo 同步删除 GameProcess、GameProcessName、GameProcessId。这三个成员共有 5 处使用，分别改为 Window.IsAlive、Win32GameWindow 和 Window.ProcessId。SystemInfo 的构造函数改为 SystemInfo(GameViewport)，原来的最小化检查移到 AttachTo。

10. 调用点改造 Copy Chapter

以下调用点不用改：

• MaskWindow / HtmlMaskWindow 定位；
• DpiHelper、AssertUtils.CheckGameResolution、各任务的 LogScreenResolution；
• KeyMouseHook；
• GameCaptureRegion → DesktopRegion 点击链路；
• 画中画定位。

它们只用 GameHandle 做几何计算。网页版的 Handle 也是真实的顶层窗口，并且 WebView 铺满客户区，所以算出来的结果与 Viewport 一致。网页版的坐标换算只是 0~65535 与屏幕像素之间的算术往返，不受多显示器影响。

11. 迁移步骤 Copy Chapter

P1：纯重构，只有 Win32 实现，除 12.1 所列差异外行为不变。

1. 新增 L2 类型：GameRuntimeKind、GameViewport、IGameWindow、GameRuntime、IGameRuntimeProvider。
2. 新增 Win32GameWindow（包含 6.1 的钩子调整）、Win32RuntimeProvider、GameCaptureSettings。
3. 新增 GameRuntimeService 并完成 DI 注册。首页、ScriptService、OneDragonFlowViewModel 改为调用它。
4. 按第 9 节收缩 TaskContext 和 ISystemInfo。
5. 按第 10 节改造 Dispatcher、SystemControl、TaskControl。
6. 编译，然后按 13.1 回归。

P1 实施说明：

• 已完成步骤 1~5，解决方案编译通过。13.1 的手动回归尚未进行。
• P1 只注册了 Win32RuntimeProvider。GameRuntimeService 找不到 WebView 实例对应的 WebPage Provider 时，会记录警告并回退到 Win32，行为与改造前相同。这个回退标了 TODO(P2)，P2 注册 WebPageRuntimeProvider 后删除。

P2：网页版。

1. 实例命名：--instance-name 参数、InstanceName、互斥体、重启参数、日志标识。
2. WebViewInstanceStore、WebViewInstanceLauncher，以及 Primary 首页卡片。
3. 按 7.5 精简输入，并把脚本改为嵌入资源。
4. CloudWebHostWindow：初始化、注入、就绪检测。
5. WebPageGameWindow、WebPageRuntimeProvider，并完成 DI 注册。
6. 网页版实例界面（7.6）。
7. 按 13.2 测试，并标定相对移动和滚轮系数。

P2 实施说明：

• 已完成步骤 1~6，解决方案编译通过，命令行解析的单元测试（InstanceIpcProtocolTests）通过。步骤 7 的手动测试与系数标定尚未进行。
• P1 的 Win32 回退已删除：找不到对应的 Provider 时 GameRuntimeService 直接抛异常。
• 与设计的出入（正文已同步）：
  • 获取期间收到停止请求时，获取完成后直接放弃，不绑定（原设计是绑定后再解绑，效果相同，但不会闪一下遮罩、也不会加载触发器）。网页版要立即结束等待，关闭宿主窗口即可。
  • 桥在 UI 线程上直接投递，其他线程才用 BeginInvoke（7.5），否则 Closing 里的 releaseAll 送不到页面。
  • SDK 注入外包 if (window.top === window)，分发脚本也只在顶层文档生效（7.5）。
  • 网页版实例没有 start 参数也会自动打开宿主（7.1）。
• 第 5 版调整（正文已同步）：
  • 截图由 GraphicsCaptureV2 改为 GraphicsCapture（7.3、7.4）。
  • 宿主由"锁定 16:9、最小 1280×720"改为客户区固定 1920×1080 物理像素，ResizeMode="CanMinimize"，DPI 变化后重新锁定（7.2）。删除了 WindowAspectRatioBehavior 的使用、WS_MAXIMIZEBOX 处理和 StateChanged 兜底。
  • 网页版实例不创建 MainWindow，宿主成为 Application.MainWindow，关闭即退出实例；命令行任务由 ApplicationHostService.HandleWebViewActivation 驱动（7.1、7.2）。原来的"随主窗口关闭"逻辑删除。
  • 删除了看不到的网页版界面改动：MainWindow 徽章（MainWindowViewModel.IsWebViewInstance / InstanceName）、首页隐藏 Win32 设置和"等待云原神就绪"提示、热键页 InfoBar。
  • RTC 断开后没有界面可以重新启动截图器，需要关闭宿主后从 Primary 重新启动（7.2）。
• 新增文件：
  • GameTask/Runtime/WebPage/{WebPageGameWindow,WebPageRuntimeProvider}.cs
  • View/Windows/CloudWebHostWindow.xaml(.cs)
  • Service/Instance/{WebViewInstanceStore,WebViewInstanceLauncher}.cs
  • Model/CloudWebInstanceItem.cs
• 删除文件：Core/Input/Backends/WebSdk/WebSdkChannel.cs。
• 第 6 版调整（与 feat/yys 的目标对齐，正文已同步）：
  • 启动参数 --name 改为 --instance-name；实例名登记到根实例的端点（7.1）。
  • 数据目录由 WebView2Instances/<name> 改为 WebView2Data/CloudGame/<name>（7.1）。旧目录不迁移，里面的登录态需要重新登录。
  • 地址改为固定的 https://ys.mihoyo.com/cloud/?autobegin=1，删除 CloudWebConfig（7.2）。已保存到 config.json 的 CloudWebConfig 字段在读取时被忽略。
  • 补上 WebView2 设置：禁止缩放、关闭状态栏、开发者工具只在 Debug 下可用（7.2）。
  • 宏回放改走 InputHub；网页版跳过本地原神设置检查（第 10 节）。

P3：渐进收敛。

• 新代码改为注入 GameRuntimeService 并从 GameRuntime 取依赖；GlobalGameCapture 和 TaskContext.GameHandle 逐步下线。
• TaskContext.Config 的调用点改为注入 IConfigService。
• CurrentScriptProject 改为在 EngineExtend.InitHost 创建 Http / Notification / HtmlMask 时传入所属项目的权限。

12. 行为变化 Copy Chapter

12.1 Win32（P1 之后） Copy Section

• 触发频率的检查（必须大于 0）提前到获取运行环境之前，配置不合法时不会先去启动游戏。
• （P2）获取运行环境期间（例如关联启动游戏时）首页启动按钮显示为"停止"。点击后提交停止请求，游戏仍会启动，但截图器不会绑定。原来这段时间按钮显示为"启动"，也无法中止。
• 停止后，InputHub 换回一个未绑定窗口的 Win32 后端：前台输入照常可用，后台输入只打 warn。
• 前台是另一个 BetterGI 实例时，本实例的遮罩会隐藏。原来按进程名 "BetterGI" 放行，多个实例的置顶遮罩会叠在一起。
• WinEventHook 只接收游戏进程的事件，UI 线程上的回调次数明显减少。
• Tick 每帧检查 IsAlive（原来只在失焦或截图器停止时才检查）。
• DPI 取值不变，仍然是绑定时的快照。

12.2 网页版与 Win32 的差异 Copy Section

13. 手动测试 Copy Chapter

13.1 Win32 回归（P1） Copy Section

13.2 网页版（P2） Copy Section

14. 决策记录 Copy Chapter

15. 遗留事项 Copy Chapter

第 2 版的待确认事项都已落实，结论见第 14 节。剩下一项由维护者另行安排，本设计不处理：

• 配置共享：所有实例读写同一个 User/config.json，没有跨进程锁，后写入的会覆盖先写入的。多个网页版实例同时运行时，这种情况更容易发生。

Docs Design Input Hub (`Docs/design/input-hub.md`) Copy Section

BetterGI 输入层 InputHub 设计

状态：已实现（第 6 版，Win32 + WebSdk 输入层；手柄未实现） · 2026-09-30

第 6 版变更：宏回放（KeyMouseMacroPlayer）移出 L0 白名单，改走 InputHub.Foreground，网页版实例中也能回放。见 5.1 和第 8 节。

第 5 版变更：网页版宿主已由 GameRuntime 设计 实现，WebSdk 后端随之精简。

• WebSdkChannel 并入 WebSdkInputBackend，后端兼任通道。
• WebView2InputBridge 只保留 InstallAsync 入口，新增 GetStatusAsync，删除 InvokeFailed。
• SDK 改为嵌入资源。
• 后端改由 GameRuntimeService 在绑定运行环境时 Attach，不再经过 TaskContext.Init。
• 相关段落（3、5.1、5.2、5.7、5.9、9.3）已同步。

1. 背景 Copy Chapter

BetterGI 需要在三个平台上模拟操作：

Windows 平台上前台和后台总是同时使用，不存在整体从前台切到后台的场景。需要整体切换的是 (a,b)、c、d 三组输出。

现状（main）：业务代码直接调用 Simulation.SendInput 和 TaskContext.PostMessageSimulator，没有统一入口，因此无法整体切换到手柄或网页。

本设计基于 main。从 feat/yys 分支只取一样东西：页面注入脚本 ys-input-inject.js，也就是 d 的 JS SDK。C# 侧对 SDK 的调用按本设计重新实现。

2. 目标与非目标 Copy Chapter

目标：

• 以 Windows 原神键鼠操作为基准，定义统一的输入接口。
• 支持 (a,b) / c / d 三组输出整体切换。
• 保留“同一任务里前台、后台混用”的写法。
• 层级彻底分开：新增入口 InputHub，Simulation 降为原始层，业务代码不再直接引用。
• 本期实现 Win32 和 WebSdk 两个后端；Gamepad 只预留类和接口，不实现。

非目标：

• 网页版宿主：承载云原神页面的 WebView2 窗口、页面生命周期、截图。本设计只约定宿主接入输入层的方式（5.7.5）。
• 游戏运行环境的整体抽象。TaskContext 保持 main 的形态，输入层只依赖窗口句柄。
• 手柄的全部实现：驱动、映射表、视角标定。
• 1080P 和游戏区域的坐标换算。这部分留在 Region 体系，不进入输入层。
• ys-input-inject.js 本身的改造。

3. 术语 Copy Chapter

平台与后端的对应关系：

4. 改造前 Copy Chapter

4.1 层级 Copy Section

业务调用   Task / Trigger / JS 脚本 / Region 点击 / BvPage / Music / AutoFishing
             │                                  │
             │  每个调用点自己选择走哪条路，也常绕过映射层直接调用原始实现
             ├──────────────────────────────────┐
动作映射   InputSimulatorExtension            PostMessageSimulatorExtension
             │                                  │
原始实现   Simulation.SendInput               TaskContext.PostMessageSimulator
           Fischless.InputSimulator           PostMessageSimulator
             │                                  │
系统接口   SendInput                          PostMessage(hWnd)

4.2 类图 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

注：ScriptPostMessage 即 Core.Script.Dependence.Simulator.PostMessage，也就是 JS 里的 new PostMessage()。

4.3 问题 Copy Section

1. 没有统一入口。前台还是后台由调用点直接选原始类，无法整体切换到手柄或网页。
2. 动作映射写了两份，行为不一致：前台支持中键和侧键，后台静默忽略；前台 SimulateAction 返回 void，后台返回自身。
3. Win32 细节外泄：扩展键判断散落在扩展方法、GlobalMethod、Music 和宏回放里；是否发送 WM_ACTIVATE 要由调用方选择 *Background 变体。
4. ReleaseAllKey 依赖 GetAsyncKeyState，只能覆盖 SendInput，经 PostMessage 按下的键释放不了。
5. DesktopRegion、AutoSkipTrigger、JS PostMessage 都在字段里缓存了输入实例，一旦后端可以切换，这些引用就会过期。
6. 已知缺陷：MouseSideButton2 和 JS 的 VK_XBUTTON2 发的都是 XButton(0x0001)；PostMessageSimulator 的 lParam 扫描码写死为 0x1E。

5. 改造后 Copy Chapter

5.1 层级与依赖规则 Copy Section

L4 业务层    Task / Trigger / JS 脚本 / Region / BvPage / Music / AutoFishing
               │ 只依赖 L3 InputHub 和 L2 接口
L3 入口层    InputHub
               │ Backend / Foreground / Background / Attach / ReleaseAll
L2 抽象层    IInputBackend -> IInputChannel -> IKeyboardInput / IMouseInput
               │ InputChannelBase：按下状态、默认动作映射、warn 限频
L1 后端层    Win32InputBackend     Foreground: SendInputChannel   Background: PostMessageChannel
             WebSdkInputBackend    Foreground = Background = 自身（后端兼任通道）
             GamepadInputBackend   Foreground = Background: GamepadChannel（预留）
               │
L0 原始层    Simulation / Fischless.WindowsInput / PostMessageSimulator
             IWebInputBridge <- WebView2InputBridge -> ys-input-inject.js（页面内）
             手柄驱动（预留，本期不定义）

接入         IGameRuntimeProvider 创建后端 -> GameRuntimeService 绑定时 InputHub.Attach(runtime.Input)
             停止时 InputHub.Attach(new Win32InputBackend(IntPtr.Zero))

规则：

• 只允许上层依赖下层。L4 只能看到 L3 和 L2。
• L0 只被 L1 引用。白名单：
  • RelativeMouseMessageHandler：把根实例上用户的真实鼠标位移转发到桌面分身的桌面，不是对游戏的模拟操作，不应跟随后端切换。
• 宏回放（KeyMouseMacroPlayer）是对游戏的模拟操作，和其他业务代码一样走 InputHub.Foreground，不区分后端。原来它作为"Win32 键鼠回放"在白名单里，网页版实例中会把按键发到桌面前台，第 6 版移出白名单。
• 命名空间：BetterGenshinImpact.Core.Input，后端放在 Core/Input/Backends/{Win32,WebSdk,Gamepad}。

5.2 类图 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

注：

• IMouseInput 里的 XxxButtonDownUpClick 是类图里的简写，实际是 Down / Up / Click 三个方法，名字与 Fischless 相同。
• <<reserved>> 表示本期只有预留实现，见 5.8。
• YsInputInject 即 ys-input-inject.js 暴露在页面上的 window.__ysInputInject，图中只列出本设计用到的函数。

5.3 接口定义 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

接口方法名沿用 Fischless 和现有扩展方法。迁移时只需要换调用对象，方法名不用改。

以下 Fischless 成员不收进新接口，C# 侧已检索确认没有业务调用：扩展键重载 KeyDown(bool?, VK) 等（改由通道内部处理）、TextEntry、ModifiedKeyStroke、*DoubleClick、HorizontalScroll、MoveMouseToPositionOnVirtualDesktop，以及 Keyboard 与 Mouse 之间的互相跳转。

5.4 InputChannelBase Copy Section

• 一个类同时实现 IInputChannel、IKeyboardInput、IMouseInput，Keyboard 和 Mouse 都返回 this。三个接口里的 Sleep 用显式接口实现。
• 按下状态：加锁维护 HashSet<VK>，鼠标键记为 VK_LBUTTON 等。ReleaseAll 按这份记录逐个抬起（单个按键失败不影响其余按键），IsKeyDown 默认也查这份记录。
• 鼠标键 VK：Keyboard.KeyDown/KeyUp/KeyPress 收到 VK_LBUTTON、VK_RBUTTON、VK_MBUTTON、VK_XBUTTON1、VK_XBUTTON2 时按对应鼠标键处理。GlobalMethod 和 Avatar 的字符串按键因此不再各自判断鼠标键。
• 默认 SimulateAction：GIActions 经 SimulateKeyHelper.ToActionKey 得到 KeyId，再落到键盘或鼠标的原子操作。现有两套扩展方法的逻辑合并到这里，侧键 2 改为 XButton2。
• OnKeyPress / OnMouseClick 默认实现为 Down + Up。子类可以覆写，保持各自的时序：SendInput 在一次调用里发送按下和抬起；PostMessage 发送 WM_CHAR，点击间隔 100 ms；WebSdk 交给页面按住。
• KeyType.Hold 为按下、等待 1000 ms、抬起，与现有一致。
• 遇到不支持的操作时调用 WarnUnsupported(operation)，然后直接返回 this。同一种操作 10 秒内只打一次 warn。
• 鼠标键枚举命名为 InputMouseButton { Left, Right, Middle, X1, X2 }，避免和 WPF 的 System.Windows.Input.MouseButton、Fischless 的 MouseButton 重名。

5.5 Win32 通道行为 Copy Section

hWnd 为 IntPtr.Zero（未 Attach）时，后台通道的所有操作都 warn。

Region.BackgroundClick 需要借用真实光标，这类组合操作由外部组合两个通道完成（前台移动光标，后台点击），不进入 PostMessageChannel。

5.6 PostMessage 键盘 lParam 修正 Copy Section

现状：所有按键的 lParam 都写死为 0x1E0001（按下）和 0xC01E0001（抬起），也就是扫描码固定为 0x1E（A 键）。

修正后：

scan       = MapVirtualKey(vk, MAPVK_VK_TO_VSC) & 0xFF
WM_KEYDOWN = 1 | (scan << 16)                           // 重复次数 1
WM_CHAR    = 1 | (scan << 16)
WM_KEYUP   = 1 | (scan << 16) | (1 << 30) | (1 << 31)   // 之前为按下 + 状态转换

• 改在 L0：PostMessageSimulator 新增 MakeKeyLParam(VK vk, bool keyUp)，替换所有写死的常量。
• 扩展键位（bit 24）按 ExtendedKeys 设置，与前台通道的扩展标志规则相同：WM_KEYDOWN = ... | (1 << 24)（扩展键时）。
• 只改 lParam。WM_CHAR 的 wParam 仍是 VK 值而不是字符码，本次不动。鼠标消息不受影响。

5.7 WebSdk 后端 Copy Section

5.7.1 组成

SDK 的工作方式：脚本通过 webpack 拿到云原神页面内部的 ClientCore 模块，直接调用它的键鼠方法，经 RTC 数据通道发给云端。它不派发 DOM 事件，也不需要 Pointer Lock。SDK 自己保存指针位置（setAbsPosition），鼠标按键和相对移动默认使用这个位置。

5.7.2 调用协议

C# 侧只有一个通用方法：按函数名调用 window.__ysInputInject 上的任意函数。

public interface IWebInputBridge
{
    /// <summary>
    /// 调用页面 SDK window.__ysInputInject[method](...args)。
    /// 不等待执行结果，页面侧按到达顺序串行执行；失败通过实现类的事件回报。
    /// 可选参数请直接省略，不要传 null：JSON 的 null 不会触发 JS 的参数默认值。
    /// </summary>
    void Invoke(string method, params object[] args);
}

消息格式：

C# -> 页面   { "channel": "bgi.input", "method": "tapKey", "args": ["KeyF"] }
页面 -> C#   { "channel": "bgi.input.error", "method": "tapKey", "error": "rtc data channel is not open: closed" }   // 只在失败时发送

页面侧分发脚本（WebView2InputBridge.BootstrapScript）：

(() => {
  if (window.__bgiInputBridge) return;
  window.__bgiInputBridge = true;
  let queue = Promise.resolve();
  window.chrome.webview.addEventListener("message", ({ data }) => {
    if (!data || data.channel !== "bgi.input") return;
    const { method, args = [] } = data;
    // 串行执行：tapKey、click 等是异步函数，并发执行会打乱按键顺序
    queue = queue
      .then(() => {
        const sdk = window.__ysInputInject;
        if (!sdk || !Object.hasOwn(sdk, method) || typeof sdk[method] !== "function") {
          throw new Error(`unknown sdk method: ${method}`);
        }
        return sdk[method](...args);
      })
      .catch(e => window.chrome.webview.postMessage({
        channel: "bgi.input.error", method, error: String(e?.message ?? e)
      }));
  });
})();

WebView2InputBridge：

• 入口：static Task<WebView2InputBridge> InstallAsync(CoreWebView2 core)，在 UI 线程、首次导航前调用。它注入嵌入资源中的 SDK（外包 if (window.top === window)，只在顶层文档执行）和分发脚本，然后返回桥。构造函数与分发脚本都是私有的。
• Invoke：序列化成上面的 JSON，调用 PostWebMessageAsJson，不等页面执行。UI 线程上直接投递，其他线程用 Dispatcher.BeginInvoke（同优先级 FIFO，任务线程不阻塞）。投递失败限频打 warn；桥已释放时同步抛 InvalidOperationException。
• GetStatusAsync()：在页面内执行 window.__ysInputInject?.status()（异常转成 error 字段），返回 WebSdkStatus(RtcDataChannelState, GameDataStarted, Error)，IsReady 表示 RTC 为 open 且已进入游戏。宿主每秒轮询一次，用来判断就绪和断开。
• 收到 bgi.input.error 时限频打 warn 日志。原来的 InvokeFailed 事件没有订阅者，已删除，页面断开改由状态轮询发现。

灵活性：

• 新增或调整 SDK 函数时，C# 桥接和分发脚本都不用改。

• WebSdkInputBackend.Sdk 对外暴露桥接。遇到键鼠接口表达不了的需求，可以直接调用 SDK 的其他函数，例如 sendIme（文字输入）、setDefaults（调整按住时长）、look：

  csharp Copy

  if (InputHub.Backend is WebSdkInputBackend web)
  {
      web.Sdk.Invoke("setDefaults", new { keyHoldMs = 80 });
  }

5.7.3 操作映射

5.7.4 实现要点

/* Detailed source-code truncated for AI context efficiency. */

• 坐标：MoveMouseTo 收到的是桌面 065535 坐标。先按 PrimaryScreen.WorkingArea 换算成物理像素（与 DesktopRegion 的归一化方式一致），再相对 canvasRect() 归一化，截断到 01。canvasRect 由宿主提供，是游戏画面在屏幕上的物理像素矩形，应与截图区域一致。1080P 换算仍由 Region 体系完成，和桌面端一样。
• 时序：Invoke 返回时页面还没执行。页面串行执行，tapKey / click 会在页面内按住一段时间，后续指令排队等待。按键后接识图时，延时要把页面内的按住时长算进去。
• 异常：映射表以外的按键、侧键 warn 后忽略。SDK 执行失败（如 RTC 数据通道未打开）由页面回报，桥接限频打 warn。桥已释放时 Invoke 直接抛 InvalidOperationException，ReleaseAll 会吞掉这个异常。

5.7.5 宿主接入（已由 GameRuntime 实现）

宿主即 CloudWebHostWindow，接入由 game-runtime.md 第 7 节实现，输入层不依赖宿主的其他实现：

1. CloudWebHostWindow 在 CoreWebView2 初始化后、首次导航前调用 bridge = await WebView2InputBridge.InstallAsync(core)。
2. WebPageRuntimeProvider 在游戏就绪后创建 new WebSdkInputBackend(host.Bridge, () => window.Viewport.ScreenRect)，画面区域与截图区域一致。
3. GameRuntimeService 绑定时调用 InputHub.Attach(runtime.Input)。
4. 页面断开由宿主轮询 GetStatusAsync() 发现，截图器随之停止，不自动重连。
5. WebPageGameWindow 在宿主 Closing 时调用 InputHub.ReleaseAll()；Closing 在 UI 线程上触发，releaseAll 会被直接投递。

5.7.6 SDK 已知问题

ys-input-inject.js 的 getLocationFromCode 把所有以 Left / Right 结尾的 code 都当作左右修饰键，ArrowLeft、ArrowRight、BracketLeft、BracketRight 的 location 会是 1 或 2，而不是 0。按非目标约定本次不改脚本，是否影响云端识别需要实测。

5.8 预留后端：Gamepad Copy Section

GamepadInputBackend + GamepadChannel 本期只建类，不实现：

• 实现 L2 接口，Foreground 和 Background 返回同一个通道实例。
• 所有操作都走 WarnUnsupported("手柄后端未实现")，然后返回 this。ReleaseAll 和 Dispose 为空实现。
• 本期没有任何地方创建它，也不加配置项。

实现时要遵守的约定（接口层面已经留好位置，本期不做）：覆写 SimulateAction，把 GIActions 直接映射成手柄输入；键盘按键按键位配置反查成 GIActions 再映射；MoveMouseBy 映射到右摇杆，是阻塞调用；原始鼠标按键和 MoveMouseTo 都 warn 后忽略。最后一条的原因是坐标点击由“移动 + 左键”两步组成，只忽略移动的话，左键会被映射成普攻。

5.9 生命周期与切换 Copy Section

进程启动
   └─ InputHub 持有 Win32InputBackend(IntPtr.Zero)      // 前台可用，后台 warn

GameRuntimeService 绑定运行环境（见 game-runtime.md 第 8 节）
   ├─ Win32：   InputHub.Attach(new Win32InputBackend(hWnd))
   └─ 网页版：  InputHub.Attach(new WebSdkInputBackend(bridge, () => window.Viewport.ScreenRect))

GameRuntimeService 解绑运行环境
   ├─ InputHub.ReleaseAll()
   └─ InputHub.Attach(new Win32InputBackend(IntPtr.Zero))

InputHub.Attach(backend)
   1. 替换当前后端
   2. 旧后端 Dispose()

• 切换：(a,b)、c、d 之间的切换就是 Attach 一个新后端，不另设 Switch。只在没有任务运行时调用。
• 所有权：InputHub 持有当前后端，替换时释放旧后端。桥接等外部资源由创建者（宿主）持有，后端的 Dispose 不释放它们。
• 未 Attach 时：与现状对应。现在 Simulation.SendInput 随时可用，而 PostMessageSimulator 在 Init 之前为 null；改造后前台照常可用，后台 warn，不再抛空引用异常。
• 引用规则：单个任务内可以持有通道引用。跨任务存活的对象不能缓存，必须每次从 InputHub 取，包括静态字段、DI 单例、Region 树、Trigger。
• 线程：后端引用用 volatile 加 Interlocked.Exchange，按下状态加锁。
• 多实例：每个 BetterGI 进程各有一份 InputHub 状态，互不影响。

6. 调用方式对照 Copy Chapter

网页版下 Foreground 和 Background 是同一个通道，上表的写法不用改，后台调用会自动落到 SDK。

7. 迁移步骤 Copy Chapter

基于 main，直接替换入口，不保留转发。

1. 新增 Core/Input：L3、L2、Win32 后端、WebSdk 后端（5.7.1 的全部文件），以及 Gamepad 的预留类。从 feat/yys 复制 ys-input-inject.js，在 csproj 中设为 PreserveNewest。Microsoft.Web.WebView2 在 main 上已经引用，不新增依赖。

2. 从下往上改基础设施：

   位置	改法
   PostMessageSimulator	按 5.6 修正键盘 lParam
   TaskContext	Init(hWnd) 中把 PostMessageSimulator = Simulation.PostMessage(GameHandle) 改为 InputHub.Attach(new Win32InputBackend(hWnd))，删除 PostMessageSimulator 属性。签名不变
   DesktopRegion	去掉 IMouseSimulator 字段和构造参数，静态和实例方法都改走 InputHub.Foreground.Mouse
   Region.BackgroundClick	前台移动真实光标，后台点击，再移回原位
   GlobalMethod	走 InputHub.Foreground，去掉扩展键分支，修正 VK_XBUTTON2。InputText 加注释，内容见下方
   JS PostMessage 宿主	每次调用时取 InputHub.Background，去掉构造时的缓存
   BvFlow 服务、BvPage	走 InputHub.Foreground；BvPage.Keyboard / Mouse 直接换成新接口类型
   Music	两个 transport 分别包装 InputHub.Foreground / Background，每次调用时取
   AutoFishing	构造注入从 IInputSimulator 改为 IInputChannel；单测里的 FakeInputSimulator 改为 FakeInputChannel
   AutoSkipTrigger	去掉 _postMessageSimulator 字段，每次调用时取 InputHub.Background
   MouseKeyMonitor	长按空格 / F 连发的定时器从 Simulation.PostMessage(_hWnd) 改为 InputHub.Background
   ClickExtension、BvSimpleOperation.FindFAndPress、GridScroller、AutoArtifactSalvageTask.OpenInventory	参数与返回值类型换成 IInputChannel / IKeyboardInput / IMouseInput
   缓存 Simulation.SendInput 的字段	private readonly InputSimulator input = Simulation.SendInput; 改为属性 private IInputChannel input => InputHub.Foreground;，每次访问都取当前通道

   InputText 的注释：

   csharp Copy

   // 通过剪贴板 + Ctrl+V 输入文字，只面向键鼠后端。
   // 手柄场景用不到文字输入，这里不做手柄适配；将来如果需要，请单独实现，不要依赖 Ctrl 的映射。

3. 用正则批量替换业务调用点（数量是文本匹配数，包含定义和注释，仅供估算工作量）：

   查找	替换	约数
   Simulation.SendInput.SimulateAction(	InputHub.Foreground.SimulateAction(	318
   Simulation.SendInput.Keyboard.Mouse.	InputHub.Foreground.Mouse.	少量
   Simulation.SendInput.Keyboard.	InputHub.Foreground.Keyboard.	105
   Simulation.SendInput.Mouse.	InputHub.Foreground.Mouse.	208
   Simulation.IsKeyDown(	InputHub.Foreground.IsKeyDown(	3
   TaskContext.Instance().PostMessageSimulator.SimulateAction(	InputHub.Background.SimulateAction(	20
   TaskContext.Instance().PostMessageSimulator.Key(Press|Down|Up)Background(	InputHub.Background.Keyboard.Key$1(	27
   Simulation.ReleaseAllKey()	InputHub.ReleaseAll()	37

   通过局部变量或字段持有 PostMessageSimulator 的调用需要手工修改，比如 AutoSkipTrigger 的大部分调用。扩展键重载 KeyDown(false, vk) 替换后会编译失败，按第 6 节改成单参数即可。

4. 删除 InputSimulatorExtension、PostMessageSimulatorExtension 和 DesktopRegion(IMouseSimulator) 构造函数。Simulation 保留，作为 L0 使用。

5. 守住层级（可选）：加一个源码扫描单测，要求 Simulation、PostMessageSimulator、Fischless.WindowsInput 只出现在 Core/Input/Backends/Win32/** 和白名单文件中。

实施结果：步骤 1~4 已完成，步骤 5 未做。业务代码中 Simulation、PostMessageSimulator、Fischless.WindowsInput 类型已只剩白名单文件和注释。OverrideController、KeyBindingTextBox 里原本就有未使用的 using Fischless.WindowsInput;，与模拟输入无关，未改动。

8. Windows 下的行为变化 Copy Chapter

• 后台通道在游戏不在前台时自动补发 WM_ACTIVATE。之前只有 *Background 变体会发。

• InputHub.ReleaseAll() 会额外释放经 PostMessage 按下的键。

• 后台通道遇到中键、侧键、移动、滚轮时，从静默忽略改为 warn（限频）。

• 前台 SimulateAction 的返回值从 void 改为通道本身，源码兼容。

• 修复侧键 2 实际发送 XButton1 的问题。

• PostMessage 键盘消息的 lParam 扫描码改为按键计算，之前固定为 0x1E。

• DesktopRegion(IMouseSimulator) 构造函数移除。JS 里的无参构造和 (w, h) 构造不受影响。

• JS 可见的 BvPage.Keyboard / Mouse 换成新接口，脚本能用的成员变少：扩展键重载、TextEntry、ModifiedKeyStroke、*DoubleClick、HorizontalScroll，以及键盘和鼠标之间的互相跳转。已确认接受。

• 前台扩展标志改为按真实键盘判断。原来有两套不一致的规则，各错一半：

  • SimulateAction、GlobalMethod、Music 对 IsExtendedKey 列表里的键一律不带扩展标志。左 Alt 因此正确，方向键、Insert 等则可能被识别成小键盘按键。
  • 其他直接发送的调用点（拾取键、秘境移动键、Avatar.KeyDown(string) 等）走 Fischless 自动判断。方向键等因此正确，左 Alt、泛指的 Alt / Ctrl 则会被识别成右 Alt / 右 Ctrl。

  现在两条路径统一使用 ExtendedKeys，行为与真实键盘一致。默认键位中只有“呼出鼠标”的左 Alt 在原列表里，它走 SimulateAction，前后都不带扩展标志，因此默认配置下没有变化；只有改绑到上述按键的用户会受影响。

• 后台 PostMessage 按键消息对扩展键设置 lParam 第 24 位，之前恒为 0。

• 键盘接口收到鼠标键 VK 时按鼠标键处理。TaskControl.TrySuspend 暂停时会释放所有按下的键，用户此时按住的鼠标键现在也会被释放；之前对鼠标键发的是无效的键盘消息。

• InputHub.Attach 不执行全局按键释放；运行环境停止或绑定失败后的回滚会在替换后端前显式 ReleaseAll。

• （第 6 版）宏回放改走 InputHub.Foreground：

  • 扩展标志改用 ExtendedKeys。原来对 IsExtendedKey 列表里的键强制不带扩展标志，其余键也不带，相当于所有键都不带；现在方向键、Insert 等带扩展标志，左 Alt 仍然不带。只有录制里包含这些扩展键的宏受影响。
  • 侧键仍然忽略，与原来一致。

9. 手动测试 Copy Chapter

9.1 PostMessage 扫描码修正 Copy Section

只影响经 PostMessage 发送的键盘消息，鼠标不受影响。以下每项在 Windows 原神和 Windows 云原神上各跑一遍，因为云原神客户端对按键消息的处理方式和本地客户端不同。

9.2 其他行为变化（Windows） Copy Section

9.3 云原神网页版（宿主接入后） Copy Section

10. 决策记录 Copy Chapter

11. 待确认 Copy Chapter

1. 网页版的文字输入。GlobalMethod.InputText 用本机剪贴板加 Ctrl+V 实现，云端能不能拿到本机剪贴板没有验证。SDK 提供了 sendIme，可以通过 WebSdkInputBackend.Sdk.Invoke("sendIme", text) 调用，不需要改接口。是否在 InputText 里对网页版走这条路？

Docs Design Mask Window (`Docs/design/mask-window.md`) Copy Section

遮罩窗口（MaskWindow）统一设计

状态：已实现（分支 refactor/20260930-mask-window，实现与设计的差异见第 11 节） · 2026-09-30

1. 背景 Copy Chapter

遮罩窗口是覆盖在游戏窗口上的透明窗口。外部对它的使用分四类：

前三类绕过了 MVVM 和 DI，直接操作 View。本设计把它们收敛为三个接口。第四类只做 DI 和 MVVM 规范化。

调用规模：VisionContext.Instance() 78 处，分布在 35 个文件；MaskWindow.Instance*() 20 处，分布在 8 个文件。

2. 现状问题 Copy Chapter

2.1 绘制链路 Copy Section

1. 每次绘制都同步切到 UI 线程。DrawContent 的每个 Put*、Remove*、ClearAll 都会调用 MaskWindow.Instance().Refresh()，也就是 Dispatcher.Invoke(InvalidateVisual)。调用方有两类：
   • TaskTriggerDispatcher.Tick 里的触发器。调用时正持有 _locker 和 _triggerListLocker，UI 线程一忙，截图循环就被拖慢；如果 UI 线程上有代码在等这两把锁，就会死锁。
   • 独立任务线程。每画一次框，都要同步等待 UI 线程处理完。
2. 重绘过多：
   • 去重条件写反了。prevRect.Count == 0 && newRect.Equals(prevRect[0]) 永远不成立，Count 为 0 时还会越界。PutOrRemove*List 只要参数非空就判定为有变化。结果是 SkillCdTrigger 在主界面时每帧都触发一次重绘。
   • Equals 不完整。TextDrawable 只比较坐标，RectDrawable 不比较画笔，所以即使修好去重也会漏掉变化。
   • 重绘范围是整个窗口。OnRender 每次都把准星和全部图形重画一遍，并新建 Pen、Brush、FormattedText。而 AllowsTransparency 窗口每次重绘本身开销就大。
   • 还有其他重绘来源。MaskWindowConfig 任意属性变化，以及 VM 的 IsInBigMapUi、IsMapPointPickerOpen 变化，都会执行 Dispatcher.Invoke(InvalidateVisual)。AutoLeyLineOutcropTask 在 Put 之后还会再调用一次 Refresh()。
3. 存在数据竞争。字典里存的就是调用方传入的那个 List<T>。AutoArtifactSalvageTask 把列表放进去以后继续往里 Add，还用 TextList.GetOrAdd 绕过了刷新；与此同时，UI 线程在 OnRender 里枚举这些列表。由此产生的异常被 catch 吞掉，表现为偶发丢帧。
4. 坐标系混用。矩形和直线在生产方就除以了 TaskContext.DpiScale（主屏 DPI），文字则在 OnRender 里除以窗口的 PixelsPerDip。AutoArtifactSalvageTask 用已经换算过的矩形坐标生成文字，高 DPI 下坐标被除了两次。
5. 渲染器要了解业务：
   • OnRender 通过字符串 "SkillCdText" 特判技能 CD 的样式。
   • DisplayRecognitionResultsOnMask 一个开关同时控制调试框和技能 CD。
   • AutoLeyLineOutcropTask 为了显示自己的提示，会临时改写这个用户配置。
6. 静态耦合：
   • VisionContext 是静态单例，里面只有一个可替换的 DrawContent，另一个属性 Drawable 没有任何地方使用。
   • DrawContent 本是业务模型，却直接依赖 View。单测里的 FakeDrawContent 没有覆写 PutOrRemoveTextList，一旦调用就会抛出"MaskWindow 未初始化"。

2.2 窗口访问 Copy Section

7. View 是静态单例。_maskWindow 在构造函数里赋值，窗口关闭后也不清空；窗口创建之前调用 Instance() 会直接抛异常。

8. 显隐策略分散在 5 处：

   • TaskTriggerDispatcher.Tick：每帧 BeginInvoke(Show)。
   • HomePageViewModel：new、Show、Hide、Close。
   • TaskRunner。
   • AutoLeyLineOutcropTask：设置 Topmost、Show、BringToTop。
   • HideSelf：编辑模式守卫。

   HtmlMaskWindow 在同样的位置被平行调用。CustomHtmlMaskService 在计时器线程上读取 IsVisible。

9. 遮罩窗口被当作通用 Dispatcher 使用。maskWindow.Invoke/BeginInvoke 的效果与 UIDispatcherHelper 相同，而且会吞掉取消异常。

10. 越层访问。MapMaskTrigger 和 TaskRunner 把 DataContext 强转成 MaskWindowViewModel 来修改 IsInBigMapUi，还直接调用具名控件的方法 PointsCanvasControl.UpdateViewport。

2.3 MVVM / DI Copy Section

11. VM 是在 XAML 里 new 出来的，不经过 DI，依赖只能通过 App.GetService 获取。配置同时从 Config 和 TaskContext.Instance().Config 两处读取。
12. HomePageViewModel 自己创建并持有 View（new MaskWindow()）。
13. VM 和 View 互相越界：
    • VM 接收 SizeChangedEventArgs，并直接调用 Application.Current.Dispatcher。
    • code-behind 读取 TaskContext、修改 VM 状态、计算点击穿透，还负责打印系统信息和检查游戏设置。

3. 目标与非目标 Copy Chapter

目标：

• 业务代码只依赖接口，不引用 MaskWindow、MaskWindowViewModel、Dispatcher。
• 绘制请求只写数据，不阻塞，也不切线程。UI 侧把多次请求合并，按帧率上限重绘，而且只重绘发生变化的那一层。
• 遮罩窗口的创建、显隐、置顶、跟随只有一个入口。
• MaskWindow 回到标准 MVVM：窗口由 DI 构造，状态放在 VM，交互通过绑定和 Behavior 实现。
• 删除 VisionContext、DrawContent、*Drawable，以及 MaskWindow 的全部静态成员。

非目标：

• HtmlMaskWindow 内部不改，只是改为由宿主统一驱动它的显隐和位置。
• 日志框（已通过 IRichTextBox 解耦）、画中画、点位选择器的业务逻辑都不动。
• 拆分 MaskWindowViewModel，可以留作后续工作。

4. 总体结构 Copy Chapter

4.1 遮罩窗口内的区域 Copy Section

窗口内有多个互相独立的区域，每个区域有自己的名字和数据来源：

窗口本身的生命周期由 IMaskWindowHost 负责。

4.2 分层 Copy Section

业务层   Trigger / Task / Region / BgiYoloPredictor / SkillCd …
           │ 只依赖 Core/Mask 里的接口；可在任意线程调用，立即返回
接口层   IMaskWindowDrawingBoard       IMaskWindowHost            IMaskWindowMapState
         画什么                   窗口怎么显示                地图点位状态
           │                        │                          │
实现层   MaskWindowDrawingBoard        MaskWindowHost             MaskWindowMapState
         不可变快照 + Changed     唯一持有 MaskWindow         不可变快照 + Changed
           │                        │ 内部使用 UiCoalescer      │
VM 层    MaskWindowViewModel（DI 单例）：用 UiCoalescer 拉取快照 → Drawing / IsInBigMapUi / 视口
           │ 绑定
View 层  MaskWindow（DI 构造）
           ├─ MaskWindowCrosshairLayer   只在准星配置变化时重绘
           ├─ MaskWindowDrawingLayer     只在绘制快照变化时重绘
           └─ 现有 XAML（状态、日志、指标、点位…）

依赖规则：

• Core/Mask 不引用 View 或 ViewModel。
• 只有 View 层引用 MaskWindow 类型。MaskWindowHost 放在 View/Mask/ 下，View 层以外的代码只能通过它接触遮罩窗口。
• 遮罩相关的新代码跨线程时只能经过 UiCoalescer，不再调用 Dispatcher.Invoke。

4.3 绘制时序 Copy Section

sequenceDiagram
    participant T as 触发器/任务线程
    participant D as MaskWindowDrawingBoard
    participant C as UiCoalescer
    participant VM as MaskWindowViewModel
    participant L as MaskWindowDrawingLayer
    T->>D: Set(group, shapes)
    D->>D: 与旧内容相同则直接返回
    D-->>C: Changed → Request()（已有待执行则忽略）
    Note over T: 立即返回，不等 UI
    C->>VM: BeginInvoke(Render)，距上次 ≥ 33ms
    VM->>VM: Drawing = source.Current
    VM-->>L: 绑定 → AffectsRender
    L->>L: OnRender（只画这一层）

5. 接口定义 Copy Chapter

命名空间为 BetterGenshinImpact.Core.Mask，目录为 Core/Mask/。不用 Core.MaskWindow 的原因见 10.1。

术语约定：

• Layer：只指 View 中负责渲染的元素。
• Group：一组按名字整体替换的图形，也就是原来 DrawContent 的 key。

5.1 绘制：IMaskWindowDrawingBoard Copy Section

/// 遮罩窗口绘制入口（业务侧）。线程安全，所有方法立即返回，不等待 UI。
public interface IMaskWindowDrawingBoard
{
    /// 整组替换。shapes 为空等价于 Clear；内容与当前相同则不做任何事。
    void Set(MaskWindowDrawingGroup group, IReadOnlyList<MaskWindowDrawingShape>? shapes);
    void Clear(MaskWindowDrawingGroup group);
    void ClearAll();
}

public static class MaskWindowDrawingBoardExtensions
{
    public static void Set(this IMaskWindowDrawingBoard board, MaskWindowDrawingGroup group, MaskWindowDrawingShape shape)
        => board.Set(group, new[] { shape });

    /// Dispose 时清除该组，用于"任务期间显示、结束即清"
    public static IDisposable Scope(this IMaskWindowDrawingBoard board, MaskWindowDrawingGroup group);
}

MaskWindowDrawingBoard 的实现要点：

• 存储：按 group.Name 存进 ImmutableDictionary<string, MaskWindowDrawingEntry>。写入时加锁，锁内只做比较和替换。
• Set：
  • 先把 shapes 拷贝成数组，调用方之后再改原列表也不会影响已存的内容。
  • 再用 SequenceEqual 和旧内容比较（图形是 record，按值相等）。相同就直接返回。
  • 不同则替换内容、版本号加 1、触发 Changed。
• Changed 在写入线程上同步触发，订阅方在回调里只能做 O(1) 的操作，例如 UiCoalescer.Request()。
• NullMaskWindowDrawingBoard.Instance 是空实现，用于单测和没有 DI 的环境。

5.2 分组与图形 Copy Section

public enum MaskWindowDrawingKind
{
    Recognition, // 识别结果（调试可视化）：受「在遮罩上显示识别结果」开关和统一样式控制
    Feature,     // 功能提示（技能 CD、地脉 OCR 区域）：遮罩可见就显示，使用图形自带样式
}

/// 绘制分组。按 Name 存储，Kind 决定显示规则
public readonly record struct MaskWindowDrawingGroup(
    string Name, MaskWindowDrawingKind Kind = MaskWindowDrawingKind.Recognition)
{
    public static implicit operator MaskWindowDrawingGroup(string name) => new(name);
}

public abstract record MaskWindowDrawingShape;
public sealed record MaskWindowDrawingRect(Rect Bounds, MaskWindowDrawingStroke? Stroke = null) : MaskWindowDrawingShape;
public sealed record MaskWindowDrawingLine(Point From, Point To, MaskWindowDrawingStroke? Stroke = null) : MaskWindowDrawingShape;
public sealed record MaskWindowDrawingText(string Text, Point Origin, MaskWindowDrawingTextStyle? Style = null) : MaskWindowDrawingShape;

public readonly record struct MaskWindowDrawingStroke(Color Color, double Thickness = 2);

/// 为 null 的字段使用 MaskWindowConfig 的识别结果样式。
/// FontSize 单位为捕获像素；Background 不为空时绘制圆角底色；Numeric 表示使用数字字体（Fgi）
public sealed record MaskWindowDrawingTextStyle(
    Color? Foreground = null, double? FontSize = null, Color? Background = null, bool Numeric = false);

约定：

• 坐标：统一用游戏捕获区域的物理像素，与截图 Mat 的坐标系相同。换算成 DIP 只在 MaskWindowDrawingLayer 里做一次，使用遮罩窗口自身的 DPI。生产方不再读取 TaskContext.DpiScale。
• 样式：图形没带样式时，使用 MaskWindowConfig 里的识别结果样式。开启"统一样式"后，Recognition 组忽略图形自带的样式，这与现状一致。
• 类型：Point、Rect 来自 System.Windows，Color 是 System.Windows.Media.Color。它们都是值类型，不持有 GDI 资源。

5.3 读端：IMaskWindowSnapshotSource Copy Section

/// 渲染侧读取，仅 MaskWindowViewModel 使用
public interface IMaskWindowSnapshotSource<out T>
{
    T Current { get; }       // 不可变快照，UI 线程直接读取，无需加锁
    event Action? Changed;   // 可在任意线程触发，只表示"有新版本"，由订阅方自行合并
}

public sealed record MaskWindowDrawingSnapshot(long Version, IReadOnlyList<MaskWindowDrawingEntry> Entries);
public sealed record MaskWindowDrawingEntry(MaskWindowDrawingGroup Group, IReadOnlyList<MaskWindowDrawingShape> Shapes);

MaskWindowDrawingBoard 同时实现 IMaskWindowDrawingBoard 和 IMaskWindowSnapshotSource<MaskWindowDrawingSnapshot>，DI 中用同一个单例注册这两个接口。

5.4 窗口：IMaskWindowHost Copy Section

public interface IMaskWindowHost
{
    void Attach(nint gameHandle);                  // UI 线程。首次调用时创建窗口，绑定游戏窗口并显示
    void Detach();                                 // UI 线程。隐藏窗口并解除绑定，窗口实例保留复用
    void Close();                                  // UI 线程。关闭并释放窗口（程序退出时）
    void ReportGameWindow(GameWindowState state);  // 任意线程，每帧可调；宿主去重后决定显隐、置顶、跟随
    MaskWindowState State { get; }                 // 缓存值，任意线程可读
    event EventHandler<MaskWindowState>? StateChanged; // 在 UI 线程触发，附属遮罩订阅
}

/// 描述游戏窗口，不是遮罩窗口，所以不加 MaskWindow 前缀
public readonly record struct GameWindowState(
    bool IsCapturing, bool IsActive, bool IsMinimized, bool IsForegroundOwnedByBetterGiOrGame, RECT Bounds);

public readonly record struct MaskWindowState(bool IsVisible, Rect Bounds);

显隐策略集中在 MaskWindowHost 中，按优先级从高到低判断，命中一条即停止：

Bounds 变化时重新定位遮罩。位置按游戏窗口所在显示器的 DPI 换算，与 HtmlMaskWindow 一样使用 DpiHelper.GetScale(gameHandle)。

实现要点：

• 在调用 ReportGameWindow 的线程上算出期望状态。和上次的期望状态相同就直接返回，不同时才调用 UiCoalescer.Request()。
• 在 UI 线程上应用：窗口由构造注入的 Func<MaskWindow> 工厂创建，然后依次执行 Show/Hide、BringToTop、设置位置，最后触发 StateChanged。
• CustomHtmlMaskService 和 HtmlMaskWindow.ShowAll/HideAll/UpdateAllPositions 改为订阅 StateChanged，TaskTriggerDispatcher 不再平行调用它们。

5.5 地图点位：IMaskWindowMapState Copy Section

public interface IMaskWindowMapState
{
    /// 任意线程调用。字段为 null 表示不修改；多次调用合并为一个快照
    void Update(bool? isInBigMap = null, Rect? bigMapViewport = null, Rect? miniMapViewport = null);

    /// 退出大地图并清空两个视口。在任务开始、地图遮罩关闭时调用
    void Reset();
}

public sealed record MaskWindowMapSnapshot(bool IsInBigMap, Rect BigMapViewport, Rect MiniMapViewport);

• MaskWindowMapState 同时实现 IMaskWindowSnapshotSource<MaskWindowMapSnapshot>。
• MapMaskTrigger 现有的合并逻辑（PendingUiUpdate、TryScheduleUiApply）拆成两部分：字段合并移到 MaskWindowMapState.Update，UI 调度交给 VM 的 UiCoalescer。
• PointsCanvas 和 MiniMapPointsCanvas 新增 Viewport 依赖属性，绑定到 VM。UpdateViewport 改为私有方法，在依赖属性的回调中调用。

5.6 UiCoalescer Copy Section

/// 把任意线程、任意频率的 Request 合并成 UI 线程上的一次 apply
public sealed class UiCoalescer(Action apply, TimeSpan minInterval = default,
                                DispatcherPriority priority = DispatcherPriority.Render)
{
    public void Request();
}

• 单飞：用 Interlocked 保证同一时刻最多只有一个待执行的回调。
• 限频：两次 apply 的间隔不小于 minInterval，不足时推迟到满足间隔再执行。
• 不阻塞：只用 BeginInvoke。标志位在调用 apply 之前复位，apply 执行期间新到的请求不会丢失。
• 没有 Application.Current 时（例如单测）直接同步执行。
• 位置：Helpers/Ui/UiCoalescer.cs。绘制用 33 ms（约 30 fps），地图状态和宿主用 0。

6. View / ViewModel 规则 Copy Chapter

1. 构造方式：
   • DI 注册 services.AddSingleton<MaskWindowViewModel>()、services.AddTransient<MaskWindow>()，另外注册一个 Func<MaskWindow> 工厂供 MaskWindowHost 使用。
   • MaskWindow(MaskWindowViewModel vm) 在构造函数里设置 DataContext，同时删除 XAML 中的 <Window.DataContext>。
   • VM 的依赖全部通过构造函数注入：IConfigService、OverlayMetricsService、IMaskMapPointService、两个 IMaskWindowSnapshotSource<>、ILogger<>。配置统一从 Config 读取。
2. 删除 MaskWindow 的这些成员：_maskWindow、Instance()、InstanceNullable()、IsExist()、Refresh()、Invoke()、BeginInvoke()、HideSelf()、RefreshPosition*()、LogBox、OnRender。
3. 渲染层：
   • MaskWindowDrawingLayer 和 MaskWindowCrosshairLayer 都是 FrameworkElement，依赖属性设为 AffectsRender，并设置 IsHitTestVisible=False。两者放在根 Grid 的最底层，跨满所有行列。
   • Pen 和 Brush 冻结后缓存，缓存键是"颜色 + 粗细"。
   • VM 把 MaskWindowConfig.Recognition* 这组配置合成一个 MaskWindowDrawingStyle 记录，只在这些属性变化时更新。
   • 准星的每个配置项分别绑定到一个依赖属性，其他配置的变化不会触发准星重绘。
4. 点击穿透：
   • VM 提供两个属性：IsClickThrough = !(OverlayLayoutEditEnabled || IsInBigMapUi)，IsCrosshairVisible = CrosshairEnabled && IsClickThrough。
   • WindowClickThroughBehavior 绑定 IsClickThrough，据此设置 WS_EX_TRANSPARENT。
5. 视图事件改为命令。IsVisibleChanged、窗口最小化、PointsCanvas.ViewportChanged 三个事件通过 EventTrigger + InvokeCommandAction 调用 VM 的 CloseTransientPopupsCommand。
6. VM 不接收 WPF 类型。窗口尺寸由 Behavior 以 Size 推送给 VM，布局提交事件经 EventArgsConverter 转换成纯数据。
7. code-behind 只保留纯视图逻辑：日志框裁剪、MapLabelSearchWindow 定位。PrintSystemInfo 和 GameSettingsChecker 移到 HomePageViewModel.Start 中，在 Attach 之后调用。

7. 线程规则 Copy Chapter

• 业务线程调用 IMaskWindowDrawingBoard、IMaskWindowHost.ReportGameWindow、IMaskWindowMapState 时只写数据，调用立即返回，在持锁代码里调用也是安全的。
• 进入 UI 线程只能通过 UiCoalescer（内部使用 BeginInvoke）。遮罩相关代码禁止使用 Dispatcher.Invoke。
• UI 线程只读取不可变快照，不需要加锁。
• MaskWindowViewModel 中还有两处也要改为经 UiCoalescer 进入 UI 线程：
  • OverlayMetricsService.MetricsUpdated 的回调里同步调用了 UIDispatcherHelper.Invoke。
  • FpsInspector 回调直接写 Fps。

8. 归属、获取方式与调用对照 Copy Chapter

8.1 归属 Copy Section

DI 容器
 ├─ MaskWindowDrawingBoard 单例 ··················· 所有者，生命周期 = 进程
 │   ├─ 读端 → MaskWindowViewModel（构造注入）→ MaskWindowDrawingLayer
 │   └─ 写端 → Win32RuntimeProvider（构造注入）
 │        └─ new GameRuntime(..., drawingBoard, mapState) ···· 借用，Dispose 不释放
 │             └─ TaskContext.Bind(runtime) → SystemInfo.DesktopRectArea → 截图区域树继承
 ├─ MaskWindowMapState 单例 ······················ 同上：读端 VM，写端经 Provider 放进 GameRuntime
 └─ IMaskWindowHost 单例 ························· 窗口显示策略，不属于运行环境，只做构造注入

• 绘制内容和地图点位状态以这次运行环境的捕获像素为坐标，放在 GameRuntime 上，与 Capture、Input 并列：没有运行环境就没有可画的地方。
• 实例由 DI 拥有，GameRuntime 只借用。GameRuntimeService.Stop 解绑时 ClearAll 并 Reset，下一次运行环境不会带着旧内容。
• IMaskWindowHost 管的是遮罩窗口本身（创建、显隐、跟随），和运行环境的生命周期无关，不放进 GameRuntime。

8.2 获取方式 Copy Section

规则：

• 业务代码不调用 App.GetService。
• 不把绘制入口缓存到跨运行环境存活的对象里（触发器实例、静态字段）。单次任务内可以在 Start 时取一次；行为树节点在 Terminate 时截图可能已释放，可保存最近一次截图的 DrawingBoard。
• 等 GameRuntime P3 把任务改成由 DI 创建后，TaskContext.Instance().Runtime 换成注入的 GameRuntime，写法不变。

8.3 调用对照 Copy Section

9. 迁移步骤 Copy Chapter

在一个分支里按下面的顺序完成，最后一次性编译通过。与 InputHub 的做法一样，直接替换入口，不保留转发层。

1. 基础设施：
   • 新增 Core/Mask/，包括所有接口、模型，以及 MaskWindowDrawingBoard、NullMaskWindowDrawingBoard、MaskWindowMapState。
   • 新增 Helpers/Ui/UiCoalescer.cs，并完成 DI 注册。
2. View 层：
   • 新增 View/Mask/ 下的 MaskWindowDrawingLayer.cs、MaskWindowCrosshairLayer.cs、MaskWindowHost.cs，以及 View/Behavior/WindowClickThroughBehavior.cs。
   • 按第 6 节改造 MaskWindow 和 MaskWindowViewModel。
3. 窗口调用方：
   • HomePageViewModel：改用 Attach / Detach。
   • TaskTriggerDispatcher：Tick 和 SyncMaskWindowPosition 改用 ReportGameWindow。
   • TaskRunner：删除对遮罩窗口的操作。
   • AutoLeyLineOutcropTask：OCR 区域提示改用 Feature 分组，删除 EnsureMaskOverlayVisible、RestoreMaskOverlayVisible、RefreshMaskWindowForOverlay。
   • CustomHtmlMaskService：改为订阅 StateChanged。
4. 绘制调用方：
   • Region、ImageRegion、GameCaptureRegion 中的 drawContent 换成 IMaskWindowDrawingBoard。
   • ToRectDrawable 改名为 ToMaskWindowDrawingRect，并去掉其中除以 DpiScale 的换算。
   • 其余 78 处 VisionContext.Instance() 按第 8 节替换。
   • SkillCdOverlayRenderer 负责生成带样式的 MaskWindowDrawingText。
   • AutoArtifactSalvageTask 的文字坐标改用捕获像素。
5. 地图：
   • MapMaskTrigger 和 TaskRunner 改为写当前运行环境的 MaskWindowMapState。
   • 两个 Canvas 新增 Viewport 依赖属性。
6. 清理：
   • 删除整个 View/Drawable/ 目录和 FakeDrawContent。
   • 可选：加一个源码扫描单测，确保 MaskWindow 只出现在 View/ 下。

10. 命名（已确认） Copy Chapter

10.1 命名规则 Copy Section

• 业务代码能看到的、用来操作遮罩窗口的类型，一律以 MaskWindow 开头，结构为 MaskWindow + 区域或职责 + 概念：
  • 区域或职责：Drawing、Map、Crosshair、Host。
  • 概念：Group、Rect、Snapshot、Layer 等。
• 这样和窗口里其他区域以及其他遮罩都能区分开。其他区域指状态、日志、指标（AdjustableOverlayItem）；其他遮罩指 HtmlMaskWindow，以及将来可能新增的 Overlay。
• 不加前缀的只有三个：
  • UiCoalescer：通用 UI 调度工具。
  • WindowClickThroughBehavior：HtmlMaskWindow 也能用。
  • GameWindowState：描述的是游戏窗口，不是遮罩窗口。
• 命名空间用 Core.Mask，不用 Core.MaskWindow。原因是 C# 查找简单名称时，会先查外层命名空间的成员，再看文件顶部的 using。如果存在 BetterGenshinImpact.Core.MaskWindow 这个命名空间，那么 BetterGenshinImpact.Core.* 下的代码写 MaskWindow 时会先解析到这个命名空间，报 CS0118。

10.2 命名一览 Copy Section

几个取舍：

• 绘制入口用 DrawingBoard，不用 Canvas。窗口里已经有 PointsCanvas 这个真正的画布控件，Canvas 会和它、以及 WPF 的 Canvas 混淆。
• 分组用 Group，不用 Layer。Layer 留给 View 里的渲染元素，免得 MaskWindowDrawingLayer 里又出现一个"layer"参数。
• 宿主用 Host，不用 Manager 或 Controller。Host 表示拥有这个窗口并决定它怎么显示；Manager 太泛；Controller 听起来像只负责转发指令。

10.3 其他待确认 Copy Section

1. 技能 CD 改为 Feature 分组后，不再受"在遮罩上显示识别结果"开关控制，这是一处行为变化。
2. 绘制重绘上限定为 33 ms（约 30 fps）是否合适，是否需要做成配置项。

11. 实现记录 Copy Chapter

11.1 与设计的差异 Copy Section

11.2 行为变化 Copy Section

• 技能 CD（含 AutoCombo 接管时）改为 Feature 分组，不再受「在遮罩上显示识别结果」开关控制。
• 地脉花任务不再临时改写 DisplayRecognitionResultsOnMask，也不再强制显示遮罩；OCR 区域提示是 Feature 分组，任务期间其他识别框仍按用户开关显示。
• AutoArtifactSalvageTask 的"识别失败 / 套装名"文字改用捕获像素坐标，修复了高 DPI 下位置偏移。
• 系统信息与 MSI Afterburner 检查从遮罩窗口 Loaded 移到 HomePageViewModel.OnRuntimeStarted，每次启动截图器都会输出。
• 截图器停止时清空所有绘制内容并重置地图点位状态。
• HTML 遮罩改为只在主遮罩显隐或移动时同步，不再每帧 ShowAll。

11.3 验证情况 Copy Section

• dotnet build BetterGenshinImpact.sln -c Debug 通过，没有新增警告。
• 没有实际运行程序。以下行为需要手动验证：遮罩显隐与跟随、多显示器 / 非 100% DPI 下识别框和准星位置、布局编辑模式下的点击穿透、大地图点位与小地图、技能 CD 显示。
• 单测依赖的资源子模块在新 worktree 中没有初始化，未运行单测。

Docs Design Multi Instance Ipc (`Docs/design/multi-instance-ipc.md`) Copy Section

BetterGI 多实例命名管道协议

设计目标 Copy Chapter

协议不再使用 InstanceId，也不要求根实例保存“由谁启动了谁”的进程树。实例关系只由
当前 Windows 用户、Windows Session、进程用途和进程 ID 决定。

当前协议版本为 v2，规则如下：

• 每个 Windows 用户最多有一个根 BetterGI；
• 根 BetterGI 是该用户固定根管道的持有者，通常运行在主桌面 Session；
• 与根不在同一个 Session 的 BetterGI 是桌面分身 BetterGI；
• WebView 无论在哪个 Session 启动，都是根 BetterGI 的直接客户端；
• 桌面分身 BetterGI 只能查询和访问相同 Session 中的 WebView；
• 同一个 Session 只允许一个 BetterGI，WebView 则允许多个并通过进程 ID 精确寻址。

独立任务的选择面板、任务下发和状态回传不在当前实现范围内。

管道和 Windows 用户隔离 Copy Chapter

每个 Windows 用户只有一个固定根管道：

BetterGI.v2.user-<Windows用户SID>.root

命名管道名称在整台计算机上可见，而不是按 Windows Session 隔离。因此根 BetterGI、
桌面分身 BetterGI 和 WebView 即使运行在不同 Session，也能连接同一个固定端点。
管道 ACL 只允许当前 Windows 用户 SID 完全控制，并显式拒绝 Network SID，所以
不同 Windows 用户分别拥有自己的根 BetterGI，彼此不会注册到对方的实例组中。

协议内容不敏感，不使用密钥、令牌、InstanceId 或父实例 ID。根端从已连接的命名管道
句柄调用 Windows API 获取客户端真实进程 ID，再由进程 ID取得真实 Windows Session；
客户端提交的用途只用于区分 BetterGI 与 WebView，不能伪造进程或 Session 身份。

启动参数 Copy Chapter

客户端用途仅使用：

--instance <childSession|webview>

• --instance childSession 表示该进程只能作为桌面分身客户端，根暂时不存在时也不会
  自行成为根；
• --instance webview 表示该进程只能作为 WebView 客户端，必须同时用
  --instance-name <实例名> 指定实例名（云原神网页版，见 GameRuntime 设计 7.1）。
  实例名随 connection.open 提交，根把它写入该 WebView 的端点（InstanceEndpoint.InstanceName），
  只用于识别和展示；同名互斥由实例名互斥体保证，根不判重；
• 不带 --instance 的 BetterGI 会先竞争固定根管道。竞争成功即成为根；竞争失败则
  连接已有根，由根根据真实 Session 决定是转发重复启动还是注册为桌面分身。

应用自身重启时额外传递：

--restart-from-pid <旧进程ID>

新进程会等待旧进程退出，再竞争根管道或替换同 Session 中的旧客户端连接。该参数只用于
消除重启交接期间的竞态，不作为长期身份。

连接拓扑和访问规则 Copy Chapter

某个 Windows 用户的根 BetterGI
├─ Session 2 的桌面分身 BetterGI（最多一个）
├─ Session 3 的桌面分身 BetterGI（最多一个）
├─ Session 1 的 WebView（可多个，以进程 ID 区分）
├─ Session 2 的 WebView（可多个，以进程 ID 区分）
└─ Session 3 的 WebView（可多个，以进程 ID 区分）

所有客户端都直接连接根管道，不在桌面分身下面建立二级管道。这样根重启后只需恢复一个
固定端点，客户端也只需重连一个固定名称。

WebView 访问规则：

• 根 BetterGI 可以查询和访问全部 WebView；
• 桌面分身 BetterGI 只能查询与自己 Windows Session 相同的 WebView；
• 单播通过 WebView 进程 ID 精确定位；
• 组播由调用方先查询可见 WebView，再逐个发送，不在协议中维护易失的实例组。

连接建立和重复启动 Copy Chapter

客户端连接固定根管道后，首先发送 connection.open。根根据管道连接的真实进程 ID 和
Session 处理：

1. webview：按进程 ID 注册，可在断线后替换旧连接。
2. BetterGI 与根位于相同 Session：视为重复启动，把业务启动参数转发给根窗口，然后
   新进程退出。
3. BetterGI 与根位于不同 Session：注册为桌面分身。
4. 同一 Session 已有桌面分身：把业务启动参数转发给已有进程，然后新进程退出。
5. 旧连接已经失效，或 --restart-from-pid 指向该 Session 中被替换的进程：接受新连接。

断线、闪退和退出语义 Copy Chapter

桌面分身 BetterGI 与 WebView 在根管道断开后，每秒尝试重新连接固定根管道，且没有总
超时时间。因此根 BetterGI 闪退、被结束进程或隔很久后才重新启动，都不改变客户端的
发现地址；新根取得固定管道后，仍存活的客户端会自动重新注册。

正常关闭根 BetterGI 时，现有 ChildSessionService.Dispose 流程继续主动断开 RDP 并
注销桌面分身 Session。只有未执行正常释放流程的闪退场景，桌面分身才会留存并等待根
恢复。

连接断开即移除对应运行时记录，不把客户端清单持久化。根重启后的关系由仍存活的客户端
重新连接重建，避免把已经退出的 PID 当作在线实例。

帧格式 Copy Chapter

同一条连接同时承载 JSON 控制消息和二进制相对鼠标批次。整数使用小端序。

uint32 payloadLength
byte   payloadType
byte[] payload

payloadLength 最大为 1 MiB。

JSON 信封的主要字段：

{
  "version": 2,
  "requestId": "00000000-0000-0000-0000-000000000000",
  "operation": "ping",
  "success": true,
  "errorCode": null,
  "errorMessage": null,
  "data": {}
}

响应使用相同 requestId，并将 operation 设为 response。信封中不再传输
sourceInstanceId。

当前控制操作：

相对鼠标批次结构：

uint16 sampleCount            // 1..64
uint64 firstSequence
int64  baseUtcTicks
repeat sampleCount:
    int32 deltaX
    int32 deltaY
    int32 timestampOffsetUs

发送端最多等待 5 ms 或累计 64 个样本后发送。队列拥塞时将后续位移合并，避免阻塞
Raw Input 采集线程。根 BetterGI 仅在游戏鼠标模式已启用、桌面分身窗口可见、RDP 已连接且
Input Capture Window 具有键盘焦点时转发。

Docs Design Realtime Trigger (`Docs/design/realtime-trigger.md`) Copy Section

实时触发器生命周期与启停设计

状态：已实施（第 2 版） · 2026-09-30 · 关联：配置持久化链路、GameRuntime、遮罩窗口

0. 一句话说明 Copy Chapter

触发器实例在启动截图器时创建一次，之后不再销毁或重建。原来的"清空 / 重新引入"改成增删一张"任务期间启用名单"，调度器每一帧照着这张名单（不在任务中时照用户配置）决定哪些触发器运行。

• 实例什么时候销毁：只在停止截图器时丢弃，下次启动截图器再新建一套，这一点和现在一样。任务开始和结束、脚本添加和清空触发器、修改配置，都不再销毁或重建实例。上一次会话中仍处于启用状态的实例，在新会话第一帧收到 OnDisabled，清掉留在遮罩上的内容。
• 触发器怎么知道自己被开关：调度器每帧把"本帧该不该运行"和上一帧比较，不同时调用触发器的 OnEnabled 或 OnDisabled。原来散在 Init() 和外部代码里的初始化、收尾逻辑，都搬进这两个方法。
• 对原有功能的影响：用法和效果基本不变，JS 接口不变，暂停、任务期间全停这些规则也保持原样。能感知到的差异见 7.2：任务里临时启用的触发器随任务结束、暂停不再卡住 Tick，其余是 bug 修复和生效时机的细微变化。

1. 背景 Copy Chapter

实时触发器（ITaskTrigger）由 TaskTriggerDispatcher 驱动。每 50ms 执行一次 Tick：截一帧图，然后按优先级依次调用各触发器的 OnCapture。现有 9 个触发器：

2. 现状问题 Copy Chapter

2.1 清空就是销毁，恢复就是全部重建 Copy Section

flowchart TD
    S["启动截图器<br/>Dispatcher.Start"] --> L1["LoadInitialTriggers<br/>new 9 个实例，逐个 Init()"]
    L1 --> IDLE["空闲：按用户配置运行"]
    IDLE --> TI["TaskRunner.Init<br/>ClearTriggers：清空字典和列表"]
    TI --> TASK["任务中：列表为空"]
    TASK --> AT["AddTrigger(name, 参数)<br/>new 一个实例放进字典"]
    AT --> CV["ConvertToTriggerList(true)<br/>字典里全部重新 Init()，再全部强制启用"]
    CV --> TASK
    TASK --> TE["TaskRunner.End<br/>ClearTriggers，然后 SetTriggers(LoadInitialTriggers())"]
    TE --> L2["再 new 9 个实例"]
    L2 --> IDLE

1. 实例的生命周期和"是否启用"绑在一起：要关只能从列表删掉，要恢复只能重新 new。每个任务结束都会重建全部 9 个实例。
2. 重建有副作用：AutoFishingTrigger 在构造函数里按当时的配置建行为树，所以钓鱼配置什么时候生效，取决于之后有没有跑过任务。GameLoadingTrigger.Init() 里的 Starward 通知也随重建反复执行，见 2.4。
3. 收尾逻辑散在外面：TaskRunner.Init 替 MapMask 复位大地图状态，多处调用 DrawContent.ClearAll() 擦掉触发器的残留绘制。
4. 同一份数据有两个来源：静态的 GameTaskManager.TriggerDictionary 和 Dispatcher 的 _triggers。DialogueOptionVoiceDiagnosticService 读的是字典，任务期间字典为空，拿不到 AutoSkip。
5. AddTrigger 会把字典里所有触发器都设成 IsEnabled = true。SkillCdTrigger.IsEnabled 的 setter 会写回用户配置，目前只是因为字典总是先被清空才没有出事。
6. 任务里临时启用的触发器没有撤销入口：自动秘境加入的 AutoEat、地脉花加入的 AutoPick 会一直留到当前项目结束。

2.2 配置一变就调用 `Init()` Copy Section

flowchart LR
    UI["UI 线程<br/>设置页开关"] --> PC["PropertyChanged"]
    TK["任务线程<br/>AutoFishingTask 等"] --> PC
    CAP["截图线程<br/>SkillCd 联机自关"] --> PC
    PC --> TR["ConfigChangeTracker"]
    TR --> SV["防抖保存"]
    TR --> RF["RefreshTriggerConfigs(sender)<br/>按 sender 类型查表"]
    RF --> INIT["对应触发器 Init()<br/>不持有列表锁"]
    RF --> CA["DrawContent.ClearAll()<br/>同步切到 UI 线程"]
    INIT -. 并发 .- OC["Tick 线程上的 OnCapture"]

Init() 同时做了四件事，所以配置只要一变，就只能整个重新调用一遍：

由此带来的问题：

1. 强制启用被覆盖：路径追踪强制启用了 AutoPick，这时 AutoPickConfig 只要有一项变化，Init() 就会把 IsEnabled 改回用户的开关。
2. 无关选项也会重置状态：改 SkillCd 的任意选项，或者编辑 CD 修正规则（这里调用的是全量刷新），CD 计时都会清零。
3. 线程不安全：Init() 在触发变更的线程上同步执行，可能是 UI、任务或截图线程，并且不持有列表锁，和 OnCapture 并发。SkillCd 检测到联机时会执行 IsEnabled = false，这一句会在它自己的 OnCapture 里重入 Init()，然后在持有两把锁的情况下调用 ClearAll()，同步等待 UI 线程。
4. 查表只认子配置对象本身：嵌套对象和集合元素（例如 CustomCdList 里的规则）变化时不会刷新。新增触发器时还要记得去登记映射。
5. 清理范围过大：任一触发器的配置变化，ClearAll() 会连任务画的内容一起清掉。

2.3 暂停拾取会卡住整个 Tick Copy Section

RunnerContext.StopAutoPick() 让计数加 1。AutoPickTrigger.OnCapture 发现计数大于 0 时执行 while (...) Thread.Sleep(1000)，睡眠期间一直持有 _locker 和 _triggerListLocker。

• "暂停拾取时全部触发器都停下"这个效果，其实是阻塞带来的副作用，并且只在 AutoPick 处于启用状态时才会出现。
• 窗口跟随、遮罩显隐、画中画这些 Tick 的基础工作也会一起停。
• 这期间其他线程调用 AddTrigger、ClearTriggers 会一直等锁。

2.4 "记录游戏时长"挂在自动开门触发器上 Copy Section

首页"同时启动原神"里的"使用 Starward 记录游戏时间"，代码写在 GameLoadingTrigger.Init() 中。开关开启、并且已注册 Starward 协议时，调用 starward://playtime/{区服}。Init() 在两个时机执行，所以通知也在这两个时机发出：

• 每次启动截图器：手动启动、调度器或一条龙自动启动、命令行启动、切换截图模式后的自动重启。此时游戏窗口已经存在。
• 每个独立任务结束：TaskRunner.End 重建全部触发器。

问题：

1. 通知次数取决于启动了几次截图器、跑了几个任务，和游戏进程无关。调用不带 pid，Starward 收到后会拉起一个进程，每 2 秒按进程名查找游戏，找不到时最多等十几秒。已经在记录的游戏进程会被跳过，所以时长不会重复计算，但每次调用都会多拉起一个 Starward 进程。
2. 与自动开门无关：关闭"自动进入游戏"也照样通知。
3. 区服只从 InstallPath 判断：没配置安装路径，或者 exe 不是 GenshinImpact.exe、YuanShen.exe 时，不通知。注册表兜底的条件是 GameServer == null，而字段初始值是 ""，所以兜底永远不会执行。

3. 目标与非目标 Copy Chapter

目标：

• 每次截图会话（启动截图器到停止截图器）内，每个触发器只有一个实例。
• 任务期间停止全部用户开启的触发器，只运行任务和脚本显式启用的那些。
• 任务里临时启用的触发器随启用它的任务一起结束。
• 配置变化不再调用触发器，触发器每帧读取实时配置。
• 暂停时全部触发器停止，但不阻塞 Tick。
• JS 接口不变：dispatcher.addTimer、addTrigger、clearAllTriggers 和 RealtimeTimer。

非目标：

• 不改各触发器的识别和操作逻辑。
• 不改 Tick 里截图器、窗口、遮罩的判断，这些分别由 GameRuntime 和 遮罩窗口 负责。
• 不扩大脚本可启用的范围，仍然只有 AutoPick、AutoSkip、AutoEat。
• 不改 RunnerContext 的暂停接口，也不改 SkillCdTrigger.Suspend/Resume：AutoCombo 只在任务里运行，而任务期间 SkillCd 本来就是停用的。
• 不改 ConfigChangeTracker 和保存链路。

4. 设计 Copy Chapter

4.1 规则：每一帧谁在运行 Copy Section

flowchart TD
    A["每帧，对每个触发器"] --> B{"正在执行任务？"}
    B -- 否 --> C{"用户开启了？<br/>IsEnabledByConfig"}
    B -- 是 --> D{"启用名单里有它？"}
    C -- 是 --> ON["启用，没有参数"]
    C -- 否 --> OFF["停用"]
    D -- 有 --> ON2["启用，参数取最后加入的那一条"]
    D -- 没有 --> OFF
    ON --> P{"暂停计数 > 0？"}
    ON2 --> P
    P -- 是 --> SKIP["本帧不运行，状态保留"]
    P -- 否 --> RUN["运行 OnCapture"]

整个设计只有这一条规则，用到三份数据：

租约（lease）就是加入名单时拿到的一个 IDisposable，调用 Dispose 就把自己这一条从名单里删掉。不需要中途撤销的调用方（例如 JS 脚本）可以不管它，名单会在下一次 ClearTriggers 或任务结束时整体清空。

4.2 类图 Copy Section

改造前：

classDiagram
    direction LR
    class ITaskTrigger {
        <<接口>>
        +string Name
        +bool IsEnabled
        +int Priority
        +bool IsExclusive
        +bool IsBackgroundRunning
        +Init()
        +OnCapture(CaptureContent content)
    }
    class TaskTriggerDispatcher {
        -List~ITaskTrigger~ _triggers
        -object _triggerListLocker
        +Start(GameRuntime runtime, int interval)
        +ClearTriggers()
        +SetTriggers(List~ITaskTrigger~ list)
        +AddTrigger(string name, object externalConfig) bool
        -Tick()
    }
    class GameTaskManager {
        <<静态>>
        +ConcurrentDictionary TriggerDictionary
        +LoadInitialTriggers() List~ITaskTrigger~
        +ConvertToTriggerList(bool allEnabled) List~ITaskTrigger~
        +AddTrigger(string name, object externalConfig) bool
        +ClearTriggers()
        +RefreshTriggerConfigs()
        +RefreshTriggerConfigs(object changedConfig)
    }
    class AllConfig {
        -OnConfigChanged(object sender)
    }
    class AutoPickTrigger {
        +Init()
        +OnCapture(CaptureContent content)
    }
    TaskTriggerDispatcher --> GameTaskManager : 取列表
    GameTaskManager --> ITaskTrigger : new、Init、强制启用
    AllConfig ..> GameTaskManager : 配置变化时刷新
    ITaskTrigger <|.. AutoPickTrigger

改造后：

/* Detailed source-code truncated for AI context efficiency. */

触发器部分只新增 TaskTriggerDispatcher 里的两个私有嵌套类。另外从 GameLoadingTrigger 拆出一个静态类，负责 Starward 通知：

4.3 接口 Copy Section

public interface ITaskTrigger
{
    string Name { get; }
    int Priority { get; }
    GameUiCategory SupportedGameUiCategory => GameUiCategory.Unknown;

    /// <summary>用户是否开启。每帧读取，实现里直接读配置，不缓存</summary>
    bool IsEnabledByConfig { get; }

    /// <summary>运行时状态，由触发器自己维护</summary>
    bool IsExclusive { get; }

    /// <summary>实时读取配置</summary>
    bool IsBackgroundRunning => false;

    /// <summary>停用 → 启用。options 是脚本传入的参数，没有则为 null。原 Init() 中的初始化放在这里</summary>
    void OnEnabled(object? options) { }

    /// <summary>启用 → 停用。原 Init() 中关闭时的收尾、以及外部替它做的清理放在这里</summary>
    void OnDisabled() { }

    void OnCapture(CaptureContent content);
}

与现在相比：

• IsEnabled { get; set; } 换成只读的 IsEnabledByConfig。触发器不再自己保存启用状态，是否运行由调度器决定。
• Init() 拆成 OnEnabled 和 OnDisabled，只在状态变化时调用。
• OnCapture 只在启用且未暂停时调用，触发器内部原来那些 if (IsEnabled) 判断可以删掉。

public class TaskTriggerDispatcher
{
    /// <summary>任务开始：进入任务模式，清空启用名单。用户开启的触发器下一帧停用</summary>
    public void BeginTask();

    /// <summary>任务结束：退出任务模式，清空启用名单。下一帧按用户配置恢复。重复调用无副作用</summary>
    public void EndTask();

    /// <summary>
    /// 任务期间启用一个触发器，只接受 "AutoPick"、"AutoSkip"、"AutoEat"。
    /// 返回租约，Dispose 时撤销这一条；名称不支持时返回 null
    /// </summary>
    public IDisposable? AddTrigger(string name, object? options = null);

    /// <summary>清空启用名单。不销毁任何实例</summary>
    public void ClearTriggers();

    /// <summary>取当前截图会话中的触发器实例，供诊断等只读场景使用</summary>
    public T? GetTrigger<T>() where T : class, ITaskTrigger;

    /// <summary>调度器还没创建时返回 null，供 TaskRunner.End、诊断服务等"可能早于截图器"的调用方使用</summary>
    public static TaskTriggerDispatcher? InstanceNullable();
}

• ClearTriggers、AddTrigger 保留原来的名字和调用位置，含义从"删除实例 / 新建实例"变成"清空名单 / 加入名单"。
• TaskRunner.End 第一步就调用 EndTask()，早于"截图器是否已初始化"的判断。任务中途截图器被停止时，也不会停留在任务模式。
• 删除 SetTriggers。
• 任务标记用 bool 即可：TaskControl.TaskSemaphore 已经保证同一时刻只有一个任务。

4.4 触发器状态与 Tick Copy Section

stateDiagram-v2
    state "停用" as Off
    state "启用" as On
    [*] --> Off: 启动截图器，创建实例
    Off --> On: 本帧判定为启用 / OnEnabled(options)
    On --> Off: 本帧判定为停用 / OnDisabled()
    On --> On: 参数变了 / OnDisabled() + OnEnabled(新参数)
    Off --> [*]: 停止截图器，丢弃实例
    On --> [*]: 停止截图器，丢弃实例

暂停不是一个状态：暂停只是本帧不调用 OnCapture，不会触发 OnDisabled，所以触发器的内部状态保留，和现在被阻塞时一样。

sequenceDiagram
    participant Timer as 定时器（50ms）
    participant D as TaskTriggerDispatcher
    participant T as 触发器
    Timer->>D: Tick（持有 _locker，保证串行）
    D->>D: 在 _leaseLock 里拷贝任务标记、启用名单和上一会话留下的实例
    D->>T: 上一会话中仍启用的实例 OnDisabled()
    loop 每个触发器（SyncTriggerStates）
        D->>D: 按 4.1 的规则算出本帧状态和参数
        alt 与上一帧不同
            D->>T: 原来启用则 OnDisabled()
            D->>T: 现在启用则 OnEnabled(options)
        end
    end
    D->>D: 不在任务中且有触发器停用（用户关闭）时，ClearAll() 一次
    D->>D: 截图器、最小化、前台检查，截图（同现在）
    alt 暂停计数 > 0
        D->>D: 不调用任何 OnCapture
    else
        D->>T: OnCapture（按独占、后台、UI 类别过滤，同现在）
    end

规则：

1. OnEnabled、OnDisabled、OnCapture 都只在 Tick 里执行，Tick 由 _locker 保证串行，所以触发器内部不需要为它们加锁。
2. 状态同步放在 Tick 开头，早于"最小化、不在前台"这几处提前返回。游戏在后台时，停用也能及时收尾。
3. 参数按引用比较。
4. 回调抛出的异常只记日志，不影响其他触发器，状态照常迁移。
5. OnCapture 执行期间不持有 _leaseLock，删除 _triggerListLocker。其他线程改名单时只等一次列表增删，不会等 Tick。
6. 停止截图器时不处理触发器（Stop 可能在退出流程中调用，此时不适合切 UI 线程）。下次 Start 新建一套实例，初始全部为停用；旧实例放进 _retiredSlots，新会话第一帧对其中仍启用的调用 OnDisabled，清掉 SkillCd 文字、MapMask 点位等残留，再按规则启用新实例。
7. ClearAll() 只在"不在任务中、有触发器从启用变为停用"时执行，对应原来"改触发器配置就清画布"。任务开始、结束时的清理仍由 TaskRunner 负责，撤销租约时不清画布，避免擦掉任务或脚本自己画的内容。

4.5 暂停 Copy Section

暂停计数和 5 个调用点都不改，只改检查的位置：从 AutoPickTrigger.OnCapture 里的 Sleep 循环挪到 Tick。计数大于 0 时，本帧不调用任何触发器的 OnCapture。

效果与原来一致，都是全部触发器停止，区别只有两点：不管 AutoPick 是否启用都会生效；Tick 的基础工作照常运行。AutoPickTriggerStopCount 的名字保留，注释改为"暂停全部实时触发器的计数"。RunnerContext.Clear() 在任务开始和结束时把计数清零，这一点也不变。

4.6 配置变更 Copy Section

配置变化不再调用任何触发器。Init() 的四件事去向如下：

AutoPick 名单缓存直接写在 AutoPickTrigger 里，不新增类：

private static int _listVersion;

/// <summary>名单文件被界面修改后调用，下一次 OnCapture 重读</summary>
public static void ReloadLists() => Interlocked.Increment(ref _listVersion);

/// <summary>在 OnCapture 识别到拾取键之后、用到名单之前调用</summary>
private void EnsureLists(AutoPickConfig config)
{
    var key = (config.Mode, config.BlacklistModePickEnabled, config.WhitelistModeDoNotPickEnabled,
               Volatile.Read(ref _listVersion));
    if (_loadedListKey == key)
    {
        return;
    }

    _loadedListKey = key;
    LoadLists(config); // 与原 Init() 相同：按模式读 5 个文件，整体替换 4 个集合
}

读取失败的弹窗改用 UIDispatcherHelper.BeginInvoke 发出，避免在 Tick 里等用户点确定。失败的结果同样按键缓存，同一个键只弹一次。

调用点：

用户关闭某个触发器后，下一帧它会停用。停用那一帧由调度器 ClearAll() 一次，效果与现在"改配置就清画布"相同。任务期间撤销租约时不清画布，任务或脚本自己画的内容不受影响。

AutoSkip 关键词读取失败的弹窗同样改为 BeginInvoke：关键词在 OnEnabled 里读，也运行在 Tick 中。

4.7 脚本参数（options） Copy Section

options 就是现在 AddTrigger(name, externalConfig) 里的 externalConfig，只有 JS 脚本会传：

现在参数只能通过构造函数传进去，带参数启用就只能 new 一个新实例。改造后参数记在名单里，同一个实例在 OnEnabled(options) 时取用，名单清空后回到全局配置。

同一个触发器在名单里有多条时，用最后加入的那一条。触发器保持启用、但参数变了的时候，按"先 OnDisabled 再 OnEnabled(新参数)"处理，运行状态随之重置，与现在"替换成新实例"的效果相同。这只会在脚本内部出现，例如脚本对同一个触发器先后调用两次 addTrigger 并传了不同参数。

脚本传入的 AutoSkipConfig.Enabled 不参与判断，与现在强制启用的效果一致。

4.8 记录游戏时长（Starward） Copy Section

这个功能记录的是游戏进程的时长，和触发器无关。通知从 GameLoadingTrigger 移到绑定游戏进程的位置，每个游戏进程只通知一次：

flowchart LR
    A["Win32RuntimeProvider.AttachTo<br/>绑定游戏窗口"] --> B{"开启了记录游戏时间<br/>且已注册 Starward 协议？"}
    B -- 否 --> X["不通知"]
    B -- 是 --> C{"这个游戏进程<br/>已经通知过？"}
    C -- 是 --> X
    C -- 否 --> D["按游戏 exe 识别区服"]
    D --> E["starward://playtime/区服?pid=进程ID"]

StarwardPlaytime 放在 GameTask/Runtime/Win32/。GameLoadingTrigger 中的 StartStarward、GetGameServerRegistry、IsStarwardProtocolRegistered，以及区服识别代码和相关字段，全部移入这个类。

5. 各触发器改造 Copy Chapter

原来有些运行字段是靠"任务结束重建实例"清零的。实例不再重建后，改造时逐个核对这些字段，需要清零的放进 OnEnabled。OnEnabled 的调用时机与原来重建的时机一致：任务结束后按用户配置重新启用时。

6. 调用点对照 Copy Chapter

7. 变更前后对比 Copy Chapter

7.1 一次调度器执行（JS 项目，脚本里调用了自动秘境） Copy Section

改造前：

sequenceDiagram
    participant TR as TaskRunner
    participant SS as ScriptService
    participant D as TaskTriggerDispatcher
    participant GM as GameTaskManager
    participant JS as JS 脚本
    TR->>D: Init：ClearTriggers()
    D->>GM: 清空字典，列表清空
    SS->>D: 每个项目 ClearTriggers()
    JS->>D: addTimer(AutoPick, 参数)
    D->>GM: AddTrigger：new AutoPickTrigger(参数)
    GM-->>D: 字典全部 Init 并强制启用
    JS->>D: runAutoDomainTask 内部 AddTrigger(AutoEat)
    GM-->>D: 再次全部 Init，AutoPick 也被重新 Init
    Note over D: AutoEat 一直留到项目结束
    TR->>D: End：ClearTriggers + SetTriggers(LoadInitialTriggers())
    GM-->>D: new 9 个实例

改造后：

sequenceDiagram
    participant TR as TaskRunner
    participant SS as ScriptService
    participant D as TaskTriggerDispatcher
    participant JS as JS 脚本
    participant AD as 自动秘境
    TR->>D: BeginTask()：进入任务模式，清空名单
    Note over D: 下一帧用户开启的触发器 OnDisabled
    SS->>D: 每个项目 ClearTriggers()：清空名单
    JS->>D: addTimer(AutoPick, 参数)：清空名单，加入 AutoPick
    Note over D: 下一帧 AutoPick.OnEnabled(参数)
    JS->>AD: runAutoDomainTask
    AD->>D: using AddTrigger("AutoEat")
    AD-->>D: 秘境返回，撤销 AutoEat
    Note over D: 下一帧 AutoEat.OnDisabled，AutoPick 不受影响
    TR->>D: EndTask()：退出任务模式，清空名单
    Note over D: 下一帧按用户配置 OnEnabled

7.2 行为变化 Copy Section

其余行为不变：任务期间用户开启的触发器全部停止，任务结束后恢复；脚本的 addTimer、addTrigger、clearAllTriggers 用法和效果相同；路径追踪自动拾取、钓鱼独占、后台运行、UI 类别过滤都不变。

7.3 代码层面 Copy Section

8. 改动清单 Copy Chapter

已在一个分支中完成，编译通过，尚未运行第 9 节的手动测试。

9. 手动测试 Copy Chapter

10. 决策记录 Copy Chapter

Docs Design Task Trigger Dispatcher Di (`Docs/design/task-trigger-dispatcher-di.md`) Copy Section

TaskTriggerDispatcher 依赖注入改造设计

状态：精简版已实施，编译通过 · 2026-10-01 · 关联：GameRuntime 设计、实时触发器生命周期与启停设计

1. 现状与决策 Copy Chapter

改造前，TaskTriggerDispatcher 已注册为 DI 单例，GameRuntimeService 和部分 ViewModel 也已注入它。但调度器仍在构造时写入静态 _instance，其他代码通过 Instance()、InstanceNullable() 和 GlobalGameCapture 访问。这使创建顺序隐含在全局状态里，依赖关系也无法从构造函数看出来。

建议：先做局部收敛，预计修改 9 个现有类，新增 0 个类 / 接口。 保留进程级 DI 单例，移除调度器自己维护的 _instance；已有 DI 调用方改为注入，旧任务暂留兼容入口，截图访问回到 GameRuntime。

上一版将 TaskRunner、录制器、脚本宿主的整条创建链都纳入 DI，范围偏大。改造前有 14 个文件直接使用调度器静态入口；仅 new TaskRunner() 就分布在 8 个文件（均不计注释）。彻底删除静态 API 会继续牵动上层调用链，不能只按直接调用点估算成本。

本次优先解决实例来源不统一、截图依赖调度器这两个问题，接受旧代码仍存在隐式依赖。没有必要为了调用方式一致而改造所有对象的创建方式。

当前代码已实现截图器归属：Win32RuntimeProvider.AttachTo() 创建并启动截图器，GameRuntime.Capture 持有它，GameRuntime.Dispose() 释放它。本次沿用这个结构，重点收敛访问路径。

这里的会话是 BetterGI 从绑定游戏到解绑的一段时间。同一个游戏进程中停止、重新启动截图器，会产生新的 GameRuntime 和截图器；一次脚本或独立任务结束不会结束会话。

直接注入现有具体类即可；复用 IGameCapture。不新增 ScreenshotService、CaptureSession、调度器接口或 DI Scope。TakeScreenshot() 本次保留在调度器中，截图器的所有权仍属于 GameRuntime。

2. 改造前后 Copy Chapter

改动前 Copy Section

classDiagram
    direction LR
    class TaskTriggerDispatcher {
        -TaskTriggerDispatcher _instance$
        +Instance() TaskTriggerDispatcher$
        +InstanceNullable() TaskTriggerDispatcher$
        +IGameCapture GlobalGameCapture$
        -GameRuntime _runtime
    }
    class GameRuntimeService {
        +GameRuntime Current
    }
    class GameRuntime {
        +IGameCapture Capture
    }
    class TaskRunner
    class Dispatcher
    class NotificationService

    GameRuntimeService --> TaskTriggerDispatcher : DI 注入
    GameRuntimeService --> GameRuntime : 持有
    GameRuntime *-- IGameCapture
    TaskRunner ..> TaskTriggerDispatcher : Instance()
    Dispatcher ..> TaskTriggerDispatcher : Instance()
    NotificationService ..> TaskTriggerDispatcher : GlobalGameCapture

本次改动后 Copy Section

classDiagram
    direction LR
    class TaskTriggerDispatcher {
        -GameRuntime _runtime
        +Instance() TaskTriggerDispatcher$
        +InstanceNullable() TaskTriggerDispatcher$
        +Start(runtime, interval)
        +Stop()
        +BeginTask()
        +EndTask()
        +AddTrigger(name, options)
        +ClearTriggers()
    }
    class GameRuntimeService {
        +GameRuntime Current
    }
    class GameRuntime {
        +IGameCapture Capture
    }
    class ScriptService
    class TaskRunner
    class NotificationService
    class ServiceProvider

    GameRuntimeService --> TaskTriggerDispatcher : DI 注入并启停
    GameRuntimeService --> GameRuntime : 持有当前会话
    GameRuntime *-- IGameCapture : 拥有并释放
    TaskTriggerDispatcher --> GameRuntime : 运行期间引用
    ServiceProvider --> TaskTriggerDispatcher : DI 创建唯一实例
    ScriptService --> TaskTriggerDispatcher : 构造注入
    TaskRunner ..> TaskTriggerDispatcher : 暂用兼容入口
    TaskTriggerDispatcher ..> ServiceProvider : 仅静态兼容入口查询
    NotificationService --> GameRuntimeService : 构造注入

调度器只在 Start(GameRuntime, ...) 到 Stop() 之间使用会话引用，不反向注入 GameRuntimeService，避免两者形成 DI 循环。GameRuntime 只组合窗口、截图和输入，不负责查询容器，也不充当调度器入口。

3. 预期改动的类 Copy Chapter

已修改：9 个类 / 9 个文件 Copy Section

前 4 个类调整调度依赖，后 5 个类调整截图来源。已有 DI 注册不变，构造参数由容器补齐；不要求新增工厂或修改所有上层构造函数。

本次不改 / 暂缓 Copy Section

取舍：这是局部 DI 改造，不是全量清除静态访问。 兼容查询仅保留在调度器的两个旧入口中，不将 App.GetService 散布到业务代码。旧截图路径复用已有 TaskContext；新代码使用构造注入或显式参数，不新增静态调用点。

4. 使用示例 Copy Chapter

以下示例表达依赖方向，省略原有业务逻辑。

已有 DI 调用方直接注入 Copy Section

// App.xaml.cs：保持唯一注册
services.AddSingleton<TaskTriggerDispatcher>();

// GameRuntimeService / Provider 沿用已有注册。
// GameRuntime 和 IGameCapture 由 Provider 按会话创建，不在根容器注册。

public partial class ScriptService
{
    private readonly TaskTriggerDispatcher _triggers;

    public ScriptService(TaskTriggerDispatcher triggers)
    {
        _triggers = triggers;
    }

    // 每个脚本项目执行前，原来的静态调用改用 _triggers.ClearTriggers()。
}

调度器自身的 ILogger<TaskTriggerDispatcher>、OverlayMetricsService、CustomHtmlMaskService 也改为构造注入。构造函数只装配依赖和定时器，不启动会话；调度器不反向注入 GameRuntimeService。

旧调用方保留兼容入口 Copy Section

// 以下方法位于 TaskTriggerDispatcher；删除 _instance 及构造时的静态赋值。
// 仅供旧调用方兼容，返回 DI 容器中的同一个实例，不自行创建或缓存。
public static TaskTriggerDispatcher Instance() =>
    App.GetService<TaskTriggerDispatcher>()
    ?? throw new InvalidOperationException("调度器未注册");

public static TaskTriggerDispatcher? InstanceNullable() =>
    App.GetService<TaskTriggerDispatcher>();

// TaskRunner、JS Dispatcher、录制器等旧调用点暂时保持原样。
TaskTriggerDispatcher.Instance().BeginTask();

这种转发仍属于服务定位（Service Locator），只是把实例来源统一交给 DI，不能称为调用方已完成注入。容器初始化后才允许访问；InstanceNullable() 可能触发容器首次创建实例，不再表示“截图器是否启动”。EndTask() 保持未启动时可调用，GetTrigger<T>() 在尚无触发器时返回 null。

读取本次会话的截图器 Copy Section

public sealed class CaptureCaller(GameRuntimeService runtimes)
{
    public bool TryCapture()
    {
        var runtime = runtimes.Current;
        if (runtime is null) return false;

        using var frame = runtime.Capture.Capture();
        if (frame is null) return false;

        // 使用本次会话的画面；frame.Frame 随 frame 一起释放。
        return true;
    }
}

长期存在的服务每次操作读取 Current，不能在构造时缓存 Current.Capture。属于某次会话的任务可接收固定的 GameRuntime，并随该会话取消，避免重启后转而操作新游戏会话。调用方释放截图帧，不释放借用的截图器。

以上截图示例只展示依赖与帧所有权；与停止并发时，还需满足下面的生命周期约束，判空本身不能防止对象被释放。

5. 生命周期与实施边界 Copy Chapter

会话边界 Copy Section

• 启动：Provider 创建并启动截图器 → 组装 GameRuntime → Service 绑定上下文和输入 → dispatcher.Start(runtime)。失败时由创建方或已接管的 Service 回滚，避免遗漏或重复释放。
• 停止：由 GameRuntimeService 取消任务、停止调度并释放 GameRuntime。调度器只解绑，不释放截图器。
• 暂停调度：录制期间的 StopTimer() 只暂停 Tick；截图会话仍然有效。独立任务的 EndTask() 也不释放会话。

现有 Stop() 发出取消请求、停止定时器后立即释放会话，尚未等待在途任务 / Tick 完成。这是既有的释放竞态，不纳入本次 9 个类的 DI 调整，也不能宣称已解决。后续应单独设计停止协调：拒绝新工作，异步等待会话使用者退出后再释放，避免 UI 同步等待或 Tick 等待自身造成死锁。

实施与验证 Copy Section

1. 修改 TaskTriggerDispatcher 的构造依赖与静态兼容实现，保留现有注册。
2. 修改表中的 3 个调度调用方与 5 个截图调用方，删除公共截图器入口。
3. 检查只保留表中 6 个旧类的静态调度调用，未增加分散的容器查询、重复实例或循环依赖。
4. dotnet build BetterGenshinImpact.sln -c Debug 已通过：0 个错误，628 个警告。按项目要求无需实际运行程序。

未来修改某个旧任务时，再顺手将其依赖改为参数传入；等兼容调用自然收敛后删除静态入口，不为清零调用数量单开一轮全量重构。

触发器的启停名单、租约和每帧调度规则沿用现有设计。本次保留已有注释，修改过的 C# 文件均为 UTF-8 无 BOM。

Docs Technical Recognition Json (`Docs/technical/recognition-json.md`) Copy Section

Recognition.json 编写说明

本文档说明各任务目录下 Assets\Recognition.json 的写法，用于将普通静态 RecognitionObject 配置化，并通过 RecognitionAssets.Get(...) 动态加载。

1. 文件位置 Copy Chapter

每个任务自己的识别配置文件放在：

BetterGenshinImpact\GameTask\<任务名>\Assets\Recognition.json

例如：

BetterGenshinImpact\GameTask\AutoSkip\Assets\Recognition.json
BetterGenshinImpact\GameTask\Common\Element\Assets\Recognition.json

调用方式通常是：

RecognitionAssets.Get("AutoSkip", "Collect", region);
RecognitionAssets.Get("AutoFight", "Confirm", width, height);
ElementRecognition.Get("PaimonMenu", region);

其中第二个参数就是 objects 下的对象名。

2. 基本结构 Copy Chapter

{
  "version": 1,
  "vars": {},
  "regions": {},
  "templates": {},
  "objects": {}
}

各字段含义：

• version：配置版本号，目前固定写 1
• vars：公共变量，供表达式复用
• regions：公共区域表达式，供 roi / reference.bbox 通过 @别名 引用
• templates：公共模板别名，供 template 通过 @别名 引用
• objects：识别对象定义集合

3. 一个最小示例 Copy Chapter

{
  "version": 1,
  "regions": {
    "topLeftQuarter": "rect(0, 0, cw / 4, ch / 4)"
  },
  "objects": {
    "PaimonMenu": {
      "type": "TemplateMatch",
      "template": "paimon_menu.png",
      "roi": "@topLeftQuarter",
      "draw": false
    }
  }
}

说明：

• PaimonMenu 是对象名，也是调用时的 objectName
• type 必须与 RecognitionTypes 枚举文本完全一致
• template 是模板文件名
• roi 可以直接写表达式，也可以引用 regions 中的别名
• 模板匹配场景下如果不写 name，运行时名称默认使用模板名，因此通常可以省略

4. 表达式系统 Copy Chapter

roi、reference.bbox、vars 中的值都支持表达式，底层由 NCalc 解析。

4.1 内置变量 Copy Section

• cw：当前截图宽度
• ch：当前截图高度
• cx：当前截图区域左上角 X
• cy：当前截图区域左上角 Y
• s：资源缩放系数
  • 当截图宽度小于 1920 时，s = cw / 1920
  • 其他情况 s = 1

4.2 支持的函数 Copy Section

• rect(x, y, w, h)：创建矩形
• cutLeft(percent)：截取左侧比例区域
• cutRight(percent)：截取右侧比例区域
• cutTop(percent)：截取上侧比例区域
• cutBottom(percent)：截取下侧比例区域
• cutLeftTop(widthPercent, heightPercent)：截取左上区域
• cutRightTop(widthPercent, heightPercent)：截取右上区域
• cutLeftBottom(widthPercent, heightPercent)：截取左下区域
• cutRightBottom(widthPercent, heightPercent)：截取右下区域

4.3 示例 Copy Section

{
  "vars": {
    "topBarHeight": "100 * s"
  },
  "regions": {
    "inventoryTopRight": "rect(cw * 3 / 4, 0, cw / 4, topBarHeight)",
    "pageCloseWhite": "rect(cw - cw / 8, 0, cw / 8, ch / 8)",
    "leftBottom": "cutLeftBottom(0.2, 0.2)"
  }
}

5. 模板别名和区域别名 Copy Chapter

5.1 区域别名 Copy Section

在 regions 中先定义：

"regions": {
  "option": "rect(cw / 2, ch / 12, cw - cw / 2 - cw / 6, ch - ch / 12 - 10)"
}

再在对象里引用：

"roi": "@option"

5.2 模板别名 Copy Section

在 templates 中先定义：

"templates": {
  "pageClose": "page_close.png"
}

再在对象里引用：

"template": "@pageClose"

适合多个对象共用同一模板，或者模板文件名比较长的时候。

6. objects 常用字段 Copy Chapter

下面只列常用和当前加载器支持的字段。

6.1 通用字段 Copy Section

• name

  • 可选
  • 运行时名称
  • 模板匹配通常可以省略

• type

  • 必填
  • 必须与 RecognitionTypes 一致
  • 常见值：
    • TemplateMatch
    • ColorMatch
    • OcrMatch
    • Ocr
    • ColorRangeAndOcr

• roi

  • 可选
  • 返回 Rect 的表达式，或 @区域别名

• draw

  • 可选
  • 是否绘制调试框

• drawColor

  • 可选
  • 调试框颜色，HTML 颜色格式，例如 #FF0000

• drawWidth

  • 可选
  • 调试框线宽

7. TemplateMatch 字段 Copy Chapter

适用于 type = "TemplateMatch"。

• template

  • 必填
  • 模板文件名、相对路径或 @模板别名

• templateMode

  • 可选
  • 对应 OpenCV ImreadModes
  • 默认 Color

• threshold

  • 可选
  • 匹配阈值
  • 默认通常为 0.8

• use3Channels

  • 可选
  • 是否使用三通道匹配

• templateMatchMode

  • 可选
  • 对应 OpenCV TemplateMatchModes
  • 常见值：
    • CCoeffNormed
    • CCorrNormed
    • SqDiff

• useMask

  • 可选
  • 是否启用遮罩

• maskColor

  • 可选
  • 遮罩颜色，HTML 颜色格式

• maxMatchCount

  • 可选
  • 最大匹配数量
  • 不限制时可不填

• useBinaryMatch

  • 可选
  • 是否先二值化再匹配

• binaryThreshold

  • 可选
  • 二值化阈值