

Sunshine 远程串流 · 功能说明
目标体验仍很直白:在家用物理屏,主屏确实离线时才让 VDD 兜底,主屏回来后把普通窗口拉回;现在已经有实现和测试,但还不能把这段目标场景说成真机成功。
当前情况:11 月 6 日 13:58:58 只读体检:结论是主机这边正常,没有列出要留意的原因;守护在跑、心跳新鲜,跑的程序和当前源码一致(任务 11 月 6 日 01:21 随开机启动);捕获模式在虚拟屏上,这一轮决定“留在虚拟屏”,Sunshine 配置要抓的那块屏在线,没有报任何阻断原因,显卡安全闸放行;已搬到虚拟屏的窗口是 0 个。11 月 4 日报过的“要留意”(运行的程序比源码旧)已不是现状:10 月 21—25 日源码里的改动(搬窗来源收紧、启动器日志、心跳发布和换屏判断分开)、11 月 2 日的“重启时等旧进程真正退出”和 11 月 3 日写进源码的换屏日志、TCP 分表判断现在都已加载,但加载不等于在真实换屏里验过。10 月 11 日 13:33 体检报过的“阻塞”(配置要抓的屏在当时活动的屏里找不到对应的一个,守护在等串流空闲)也已不是现状。这次没有改显示,也没有主动发起真实串流。手机画面与真实主屏故障转移仍未验收;普通联网串流 10 月 8 日有本人实用结果。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。

Sunshine 远程串流 · 功能说明
目标体验仍很直白:在家用物理屏,主屏确实离线时才让 VDD 兜底,主屏回来后把普通窗口拉回;现在已经有实现和测试,但还不能把这段目标场景说成真机成功。
当前情况:11 月 6 日 13:58:58 只读体检:结论是主机这边正常,没有列出要留意的原因;守护在跑、心跳新鲜,跑的程序和当前源码一致(任务 11 月 6 日 01:21 随开机启动);捕获模式在虚拟屏上,这一轮决定“留在虚拟屏”,Sunshine 配置要抓的那块屏在线,没有报任何阻断原因,显卡安全闸放行;已搬到虚拟屏的窗口是 0 个。11 月 4 日报过的“要留意”(运行的程序比源码旧)已不是现状:10 月 21—25 日源码里的改动(搬窗来源收紧、启动器日志、心跳发布和换屏判断分开)、11 月 2 日的“重启时等旧进程真正退出”和 11 月 3 日写进源码的换屏日志、TCP 分表判断现在都已加载,但加载不等于在真实换屏里验过。10 月 11 日 13:33 体检报过的“阻塞”(配置要抓的屏在当时活动的屏里找不到对应的一个,守护在等串流空闲)也已不是现状。这次没有改显示,也没有主动发起真实串流。手机画面与真实主屏故障转移仍未验收;普通联网串流 10 月 8 日有本人实用结果。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。


用途与实际影响
多屏扩展下,Windows 可能把新开或失去焦点的窗口放到看不见的扩展屏;如果盲目开启“系统镜像”,又可能打乱物理屏高刷与 HDR(高动态范围)。另外,正在用的人不能被突然切屏踢掉,坏掉的窗口记录也不能拿来乱搬窗。因此需要一套先核对身份、再决定是否动作的窗口与捕获目标守护器。
“家里的主屏真的不在线了,我想从手机继续看电脑。”守护器先确认屏幕已稳定离线、真的没人在串流(不光看建连通道,还看画面和声音的 UDP 通道还在不在)、近期显卡没出过故障,才切到已认准的虚拟屏;主屏回来还要实际看窗口有没有回去。
已经有屏幕识别、等待、空闲检查、窗口回迁和损坏记录保护的实现与测试;还没有真实证明拔线后手机画面不中断或所有窗口都能回到原处。

用途与实际影响
多屏扩展下,Windows 可能把新开或失去焦点的窗口放到看不见的扩展屏;如果盲目开启“系统镜像”,又可能打乱物理屏高刷与 HDR(高动态范围)。另外,正在用的人不能被突然切屏踢掉,坏掉的窗口记录也不能拿来乱搬窗。因此需要一套先核对身份、再决定是否动作的窗口与捕获目标守护器。
“家里的主屏真的不在线了,我想从手机继续看电脑。”守护器先确认屏幕已稳定离线、真的没人在串流(不光看建连通道,还看画面和声音的 UDP 通道还在不在)、近期显卡没出过故障,才切到已认准的虚拟屏;主屏回来还要实际看窗口有没有回去。
已经有屏幕识别、等待、空闲检查、窗口回迁和损坏记录保护的实现与测试;还没有真实证明拔线后手机画面不中断或所有窗口都能回到原处。

代码已覆盖应当保持主屏、何时尝试虚拟屏与如何计划窗口回迁;真实手机画面和拔线前后对照仍未验收。往虚拟屏搬窗时,新源码只认当前证明在线的主屏区域或上次记下的主屏区域;两样都没有,就不再计划新搬窗、原有搬窗记录照样保留,捕获照样在虚拟屏,不是停止捕获。11 月 4 日运行的守护包含这条。
近 15 分钟内有显卡故障就停止捕获切换和往虚拟屏搬窗,过了这段再重新核对;窗口恢复记录损坏时停下自动切换,不拿空白记录覆盖。10 月 11 日卡住的是配置要抓的屏对不上,守护在等串流空闲,手机此刻画面未知。
虚拟屏不唯一或驱动身份不清时停止切换,不把画面送到猜测的屏幕。

代码已覆盖应当保持主屏、何时尝试虚拟屏与如何计划窗口回迁;真实手机画面和拔线前后对照仍未验收。往虚拟屏搬窗时,新源码只认当前证明在线的主屏区域或上次记下的主屏区域;两样都没有,就不再计划新搬窗、原有搬窗记录照样保留,捕获照样在虚拟屏,不是停止捕获。11 月 4 日运行的守护包含这条。
近 15 分钟内有显卡故障就停止捕获切换和往虚拟屏搬窗,过了这段再重新核对;窗口恢复记录损坏时停下自动切换,不拿空白记录覆盖。10 月 11 日卡住的是配置要抓的屏对不上,守护在等串流空闲,手机此刻画面未知。
虚拟屏不唯一或驱动身份不清时停止切换,不把画面送到猜测的屏幕。

在已配置的 Sunshine 守护环境中运行零写入体检 Get-SunshineHealth.ps1 -Json 查看当前捕获目标;实际切换由守护器在主屏确实离线且串流空闲时进行,本页不能代替真实画面验收。
- 要远程看的主机与屏幕
- 是否希望主屏离线时使用专用虚拟屏
- 窗口位置异常时指出现象


在已配置的 Sunshine 守护环境中运行零写入体检 Get-SunshineHealth.ps1 -Json 查看当前捕获目标;实际切换由守护器在主屏确实离线且串流空闲时进行,本页不能代替真实画面验收。
- 要远程看的主机与屏幕
- 是否希望主屏离线时使用专用虚拟屏
- 窗口位置异常时指出现象


10 月 22 日 07:22:22 守护回执(历史):当时运行中的 WorkerSha256=2EA6698B… 与当时源码 967F366D… 不一致,c09364f(10 月 22 日 06:39)和 6cfbfde(10 月 21 日 06:38)尚未加载;10 月 20 日 07:38:27 那份回执四个组件与当时源码一致。10 月 30 日 11:10:14 读到的守护回执(历史):进程 ProcessStartUtc 2026-10-26T02:30:32Z(北京时间 10 月 26 日 10:30),回执里四个 ComponentSha256(Invoke-SunshineCaptureFailover.ps1、sunshine-capture-failover.psm1、sunshine-safety.psm1、sunshine-headless-config.psm1)当时与源码逐项相等,c09364f、6cfbfde 和 8de3dcf(健康回执发布与捕获周期失败分开)都已加载,是守护自然重启后加载的。现在:11 月 6 日 13:58:58 零写入体检(Get-SunshineHealth.ps1 -Json)Status=host-observed-healthy,Reasons 为空;任务 SunshineCaptureFailover-Interactive 11 月 6 日 01:21:26 启动,Worker.Fresh=true、SourceCurrent=true,Mode/CaptureKind=Vdd、Action=StayVdd、ConfiguredTargetOnline=true、BlockedReason=null、ClientAcceptance=unknown;GPU Allowed=true(current-boot-clean);Active / verified-stream-udp-endpoint、0 条 RTSP 连接、3 个媒体端点(不是客户端数);MigratedWindowCount=0。这只证明主机观察,不证明客户端画面。之前:11 月 4 日 13:03 零写入体检(进程退出 0)Status=attention,唯一 Reasons 为 worker-source-bundle-not-current;ProcessStartUtc 2026-11-03T08:01:19Z(北京时间 11 月 3 日 16:01:19),心跳新鲜,Mode/CaptureKind=Vdd、Action=StayVdd、ConfiguredTargetOnline=true、BlockedReason=null、ClientAcceptance=unknown;GPU Allowed=true(current-boot-clean)。这个新开的体检进程加载的是当前模块,报 Active / verified-stream-udp-endpoint、0 条 RTSP 连接、3 个媒体端点(不是客户端数)。四个文件逐项比较(09:10:45):sunshine-capture-failover.psm1、sunshine-headless-config.psm1 相同,Invoke-SunshineCaptureFailover.ps1、sunshine-safety.psm1 不同。把回执指纹和提交历史对照:运行的主脚本等于 f2e238f(11 月 2 日 09:22),安全模块等于 23fa6d2(10 月 19 日 13:06),所以 c09364f、8de3dcf 和 f2e238f 都在运行版本里,5b04f67(11 月 3 日 16:58)和 27af2fa(11 月 3 日 17:58)当时还没加载;不是旧修复失效。同一天的守护回执 MigratedWindowCount=0、AppliedWindowActionCount=0、FailedWindowActionCount=0。核对时没有重启或部署。历史:10 月 11 日 13:33 零写入体检曾是 blocked(capture-output-offline-or-ambiguous),当时会话 Active(0 个 TCP、3 个 UDP 串流端点)、动作为“等待串流空闲”。客户端画面 Unknown(未验证),真实切换和手机验收仍未完成


- sunshine-capture-failover.psm1 实现活动显示快照采集、EDID 校验、Sunshine 配置 CAS(比较并交换)原子更新与 Win32 窗口位置控制。
- Invoke-SunshineCaptureFailover.ps1 作为常驻轮询工作器(3 秒稳态轮询,等待期 250ms 快速复核),用全局互斥锁避免重复实例,并让隐藏父启动器监视生命周期。

10 月 22 日 07:22:22 守护回执(历史):当时运行中的 WorkerSha256=2EA6698B… 与当时源码 967F366D… 不一致,c09364f(10 月 22 日 06:39)和 6cfbfde(10 月 21 日 06:38)尚未加载;10 月 20 日 07:38:27 那份回执四个组件与当时源码一致。10 月 30 日 11:10:14 读到的守护回执(历史):进程 ProcessStartUtc 2026-10-26T02:30:32Z(北京时间 10 月 26 日 10:30),回执里四个 ComponentSha256(Invoke-SunshineCaptureFailover.ps1、sunshine-capture-failover.psm1、sunshine-safety.psm1、sunshine-headless-config.psm1)当时与源码逐项相等,c09364f、6cfbfde 和 8de3dcf(健康回执发布与捕获周期失败分开)都已加载,是守护自然重启后加载的。现在:11 月 6 日 13:58:58 零写入体检(Get-SunshineHealth.ps1 -Json)Status=host-observed-healthy,Reasons 为空;任务 SunshineCaptureFailover-Interactive 11 月 6 日 01:21:26 启动,Worker.Fresh=true、SourceCurrent=true,Mode/CaptureKind=Vdd、Action=StayVdd、ConfiguredTargetOnline=true、BlockedReason=null、ClientAcceptance=unknown;GPU Allowed=true(current-boot-clean);Active / verified-stream-udp-endpoint、0 条 RTSP 连接、3 个媒体端点(不是客户端数);MigratedWindowCount=0。这只证明主机观察,不证明客户端画面。之前:11 月 4 日 13:03 零写入体检(进程退出 0)Status=attention,唯一 Reasons 为 worker-source-bundle-not-current;ProcessStartUtc 2026-11-03T08:01:19Z(北京时间 11 月 3 日 16:01:19),心跳新鲜,Mode/CaptureKind=Vdd、Action=StayVdd、ConfiguredTargetOnline=true、BlockedReason=null、ClientAcceptance=unknown;GPU Allowed=true(current-boot-clean)。这个新开的体检进程加载的是当前模块,报 Active / verified-stream-udp-endpoint、0 条 RTSP 连接、3 个媒体端点(不是客户端数)。四个文件逐项比较(09:10:45):sunshine-capture-failover.psm1、sunshine-headless-config.psm1 相同,Invoke-SunshineCaptureFailover.ps1、sunshine-safety.psm1 不同。把回执指纹和提交历史对照:运行的主脚本等于 f2e238f(11 月 2 日 09:22),安全模块等于 23fa6d2(10 月 19 日 13:06),所以 c09364f、8de3dcf 和 f2e238f 都在运行版本里,5b04f67(11 月 3 日 16:58)和 27af2fa(11 月 3 日 17:58)当时还没加载;不是旧修复失效。同一天的守护回执 MigratedWindowCount=0、AppliedWindowActionCount=0、FailedWindowActionCount=0。核对时没有重启或部署。历史:10 月 11 日 13:33 零写入体检曾是 blocked(capture-output-offline-or-ambiguous),当时会话 Active(0 个 TCP、3 个 UDP 串流端点)、动作为“等待串流空闲”。客户端画面 Unknown(未验证),真实切换和手机验收仍未完成


- sunshine-capture-failover.psm1 实现活动显示快照采集、EDID 校验、Sunshine 配置 CAS(比较并交换)原子更新与 Win32 窗口位置控制。
- Invoke-SunshineCaptureFailover.ps1 作为常驻轮询工作器(3 秒稳态轮询,等待期 250ms 快速复核),用全局互斥锁避免重复实例,并让隐藏父启动器监视生命周期。
数字截至 2026 年 11 月 6 日

- 提交时把 pending(待处理)与 applied(已应用)状态分开:配置 CAS 后在同一期限内(f2e238f 起默认 60 秒)重启并检查服务:Restart-SunshineCaptureService 等旧服务宿主和归属已核实的 Sunshine 子进程退出,宿主退出后补查晚生子进程,再启动并等会话可判定 Idle 或 Active;SCM 显示 Stopped/Running 不够,Unknown 继续等,只等待、不强杀,读不到残留归属即失败(运行版本已包含,11 月 4 日核对时没有执行这条路径)。失败时只有当前文件仍是这次写入的版本才回滚到变更前内容,缺这次的指纹或已被别处改过就拒绝覆盖并报告未恢复。窗口逐个复核身份、来源区域与写后位置,单个失败不阻塞其余窗口。
- 状态文件损坏时(空、全零、非对象、格式或时间坏)停在 capture-state-invalid;持久记录用候选文件刷新、原子替换并回读,保留一份有效的 .previous 作恢复点。
- Install-SunshineCaptureFailoverTask.ps1 将其注册为当前交互用户登录时触发的 Highest(最高权限)任务,配合 VBS(Visual Basic 脚本)启动器无窗运行并监视父进程。6cfbfde 起 Invoke-SunshineCaptureFailover-Hidden.vbs 写正式日志 runtime/capture-launcher.log(UTF-16,约 1 MB 轮转),分开记 start、worker_exit 和 launcher_error,启动异常返回 1;这份日志不能倒推查清它出现前的历史故障(docs/operations.md)。
- Set-SunshineHeadlessConfig.ps1 提供独立的人工应急固定 VDD 路径:默认预览、显式 Apply 才写,只改受管配置键,保留原文件备份,同样要过显卡、会话、唯一 VDD 身份和 CAS 这几关,不冒充已重载或已显示。
- tests/Test-SunshineCaptureFailover.ps1 现定义 78 个测试(11 月 4 日 09:18 静态计数,没有运行;9 月 18 日有回执时是 67 个,后来新增 3 个损坏状态场景等),覆盖已建模的身份、去抖、会话、窗口与故障分支。
- 会话检测 Active/Idle/Unknown 三态,端口随 Sunshine 当前 base-port 解析;缺监听、失败或进程身份不符为 Unknown(未验证)。当前源码(5b04f67、27af2fa,11 月 4 日运行的守护未加载)完整读取 IPv4/IPv6 的 OWNER_PID_LISTENER、OWNER_PID_CONNECTIONS 四张表,保留 RawState/Family/EvidenceKind,按来源表区分监听和连接;任一表失败、截断或越界都不能证明 Idle,缓冲增长有限重试,系统同步调用没有单次硬超时。连接表里任何 RTSP 行都阻止 Idle,TIME_WAIT 收尾行也可能保守延后换屏,不能说这些行都证明有已建立串流;异常 TCP 状态仍可由已核实唯一 Sunshine UDP 媒体端点证明 Active;没有媒体端点时,须真实 RTSP 监听且没有连接或未知 RTSP 行才是 Idle。短写操作共用互斥,runtime(运行环境)/worker-health.json 绑定 PID、创建时间、源码 SHA 和上次完整循环,旧心跳不能续成健康。健康回执写失败单独记为 health-publication-failure:不清除已经累计的串流空闲时间,也不把成功的捕获结果改成阻断;真正的捕获周期失败仍记 cycle-transient-failure 并清除空闲计时;写不出回执时不更新成功心跳,持续失败会在体检里显示过期(8de3dcf)。体检读这份回执时允许守护同时整份原子替换它,两边不再互相卡住(174286d)。
- 5b04f67 增加 cycle-transition 语义变化日志:只有确实重载并回读成功才记 CaptureCommitted=true;Applied 可以只是普通周期,不能当作一次换屏,更不能当作客户端验收;稳定轮询不每秒写日志。11 月 4 日运行的守护未加载。
- 1 常驻守护器每 3 秒获取一次系统显示快照与串流会话状态(RTSP、TCP 和 UDP 端点)。
- 2 若物理主屏正常在线,将任何意外漂入或新建在 VDD 区域的普通窗口持续拉回主屏。

- 提交时把 pending(待处理)与 applied(已应用)状态分开:配置 CAS 后在同一期限内(f2e238f 起默认 60 秒)重启并检查服务:Restart-SunshineCaptureService 等旧服务宿主和归属已核实的 Sunshine 子进程退出,宿主退出后补查晚生子进程,再启动并等会话可判定 Idle 或 Active;SCM 显示 Stopped/Running 不够,Unknown 继续等,只等待、不强杀,读不到残留归属即失败(运行版本已包含,11 月 4 日核对时没有执行这条路径)。失败时只有当前文件仍是这次写入的版本才回滚到变更前内容,缺这次的指纹或已被别处改过就拒绝覆盖并报告未恢复。窗口逐个复核身份、来源区域与写后位置,单个失败不阻塞其余窗口。
- 状态文件损坏时(空、全零、非对象、格式或时间坏)停在 capture-state-invalid;持久记录用候选文件刷新、原子替换并回读,保留一份有效的 .previous 作恢复点。
- Install-SunshineCaptureFailoverTask.ps1 将其注册为当前交互用户登录时触发的 Highest(最高权限)任务,配合 VBS(Visual Basic 脚本)启动器无窗运行并监视父进程。6cfbfde 起 Invoke-SunshineCaptureFailover-Hidden.vbs 写正式日志 runtime/capture-launcher.log(UTF-16,约 1 MB 轮转),分开记 start、worker_exit 和 launcher_error,启动异常返回 1;这份日志不能倒推查清它出现前的历史故障(docs/operations.md)。
- Set-SunshineHeadlessConfig.ps1 提供独立的人工应急固定 VDD 路径:默认预览、显式 Apply 才写,只改受管配置键,保留原文件备份,同样要过显卡、会话、唯一 VDD 身份和 CAS 这几关,不冒充已重载或已显示。
- tests/Test-SunshineCaptureFailover.ps1 现定义 78 个测试(11 月 4 日 09:18 静态计数,没有运行;9 月 18 日有回执时是 67 个,后来新增 3 个损坏状态场景等),覆盖已建模的身份、去抖、会话、窗口与故障分支。
- 会话检测 Active/Idle/Unknown 三态,端口随 Sunshine 当前 base-port 解析;缺监听、失败或进程身份不符为 Unknown(未验证)。当前源码(5b04f67、27af2fa,11 月 4 日运行的守护未加载)完整读取 IPv4/IPv6 的 OWNER_PID_LISTENER、OWNER_PID_CONNECTIONS 四张表,保留 RawState/Family/EvidenceKind,按来源表区分监听和连接;任一表失败、截断或越界都不能证明 Idle,缓冲增长有限重试,系统同步调用没有单次硬超时。连接表里任何 RTSP 行都阻止 Idle,TIME_WAIT 收尾行也可能保守延后换屏,不能说这些行都证明有已建立串流;异常 TCP 状态仍可由已核实唯一 Sunshine UDP 媒体端点证明 Active;没有媒体端点时,须真实 RTSP 监听且没有连接或未知 RTSP 行才是 Idle。短写操作共用互斥,runtime(运行环境)/worker-health.json 绑定 PID、创建时间、源码 SHA 和上次完整循环,旧心跳不能续成健康。健康回执写失败单独记为 health-publication-failure:不清除已经累计的串流空闲时间,也不把成功的捕获结果改成阻断;真正的捕获周期失败仍记 cycle-transient-failure 并清除空闲计时;写不出回执时不更新成功心跳,持续失败会在体检里显示过期(8de3dcf)。体检读这份回执时允许守护同时整份原子替换它,两边不再互相卡住(174286d)。
- 5b04f67 增加 cycle-transition 语义变化日志:只有确实重载并回读成功才记 CaptureCommitted=true;Applied 可以只是普通周期,不能当作一次换屏,更不能当作客户端验收;稳定轮询不每秒写日志。11 月 4 日运行的守护未加载。
- 1 常驻守护器每 3 秒获取一次系统显示快照与串流会话状态(RTSP、TCP 和 UDP 端点)。
- 2 若物理主屏正常在线,将任何意外漂入或新建在 VDD 区域的普通窗口持续拉回主屏。




| 名词 | 意思 |
|---|---|
| EDID(扩展显示标识数据) | 显示器提供的身份信息;项目把它与同一次 PnP/活动输出证据组合为稳定标识,并在每次操作前重新核对。 |
| CAS(Compare-And-Swap) | 原子替换机制;写入配置文件前先校验原有内容是否被修改,防止多进程并发冲突覆写。回滚时也要先确认文件仍是这次写的版本。 |
| 串流空闲判断 | 先看 RTSP(建连通道)监听、进程和 TCP 会话;TCP 没有会话时,再看同一个 Sunshine 的视频、控制、音频 UDP 端点。UDP 还在就算“进行中”,查询失败或归属冲突算 Unknown(未验证);只有明确空闲并连续 5 秒才累计。实际端口来自当前 base-port,不固定猜默认值。 |

它处理“远程端只剩壁纸、窗口落在看不见的虚拟屏”这类事故:先确认物理主屏真的离线、串流真的空闲、近期显卡安静、窗口记录完好,再决定是否允许 failover(故障转移)。
解决什么
防止多屏混用与关屏串流时,failover(故障转移)状态机出现画面丢失、窗口错位、副屏被夺取、正在串流的人被踢掉、拿损坏记录乱搬窗,或显卡驱动连锁崩溃。



它处理“远程端只剩壁纸、窗口落在看不见的虚拟屏”这类事故:先确认物理主屏真的离线、串流真的空闲、近期显卡安静、窗口记录完好,再决定是否允许 failover(故障转移)。
解决什么
防止多屏混用与关屏串流时,failover(故障转移)状态机出现画面丢失、窗口错位、副屏被夺取、正在串流的人被踢掉、拿损坏记录乱搬窗,或显卡驱动连锁崩溃。

解决什么
防止多屏混用与关屏串流时,failover(故障转移)状态机出现画面丢失、窗口错位、副屏被夺取或显卡驱动连锁崩溃。

- 不通过系统级复制/镜像显示器实现画面同步,杜绝模式冲突;守护本身也不改 Windows 显示拓扑。
- 不触碰 Shell 桌面底栏、输入法、全屏独占游戏或无法证明归属的未知句柄窗口;其他程序或 Windows 自己怎么摆窗口,不在本项目保证内。
- 近 15 分钟内有显卡故障时,停止切换捕获目标和往虚拟屏搬窗;只有从虚拟屏回到健康物理主屏的窄范围窗口恢复,可以另行核对放行。
- 只调虚拟屏参数修不了 10 月 11 日那种阻塞:配置里记的输出在当前活动屏里找不到对应,参数入口不写 output_name。
- 检测到多于一个同名 VDD 或存在未知虚拟驱动 拒绝推断目标,执行失败关闭,保持当前配置不动并记录错误日志。
- 配置要抓的屏在活动屏里找不到唯一对应 体检报 blocked(capture-output-offline-or-ambiguous),守护等待串流空闲后再处理;这只说明配置和当前活动屏对不上,不等于虚拟屏坏了,也不推断手机一定黑屏。10 月 11 日就是这种情况;10 月 20 日早上、10 月 22 日 07:22、10 月 30 日 11:10 和 11 月 4 日 09:10 的记录里都没有这一阻塞。
- 近 15 分钟内有 BugCheck、显示内核错误或匹配的 WER 图形故障 保持 BlockedByGpuStability,不切捕获或往虚拟屏搬窗;只有空闲且证明来自 VDD、目标是健康物理主屏的普通窗口单向回迁可独立处理。单独一次 Kernel-Power 41(非正常关机)只记诊断,不挡整次开机;WER 按类型参数和报告编号去重,虚拟驱动自检报告不算显卡崩溃;事件查询本身出错仍挡。
- 要往虚拟屏搬窗,却证明不了主屏区域 当前源码不计划新搬窗、保留已有迁移记录,捕获切换照常判断;不用虚拟屏区域冒充来源。11 月 4 日运行的守护包含此修复。
- 窗口恢复记录损坏 停在 capture-state-invalid,不自动切换、不用空白记录覆盖;核对有效的上一份记录和当前现场后再恢复。

解决什么
防止多屏混用与关屏串流时,failover(故障转移)状态机出现画面丢失、窗口错位、副屏被夺取或显卡驱动连锁崩溃。

- 不通过系统级复制/镜像显示器实现画面同步,杜绝模式冲突;守护本身也不改 Windows 显示拓扑。
- 不触碰 Shell 桌面底栏、输入法、全屏独占游戏或无法证明归属的未知句柄窗口;其他程序或 Windows 自己怎么摆窗口,不在本项目保证内。
- 近 15 分钟内有显卡故障时,停止切换捕获目标和往虚拟屏搬窗;只有从虚拟屏回到健康物理主屏的窄范围窗口恢复,可以另行核对放行。
- 只调虚拟屏参数修不了 10 月 11 日那种阻塞:配置里记的输出在当前活动屏里找不到对应,参数入口不写 output_name。
- 检测到多于一个同名 VDD 或存在未知虚拟驱动 拒绝推断目标,执行失败关闭,保持当前配置不动并记录错误日志。
- 配置要抓的屏在活动屏里找不到唯一对应 体检报 blocked(capture-output-offline-or-ambiguous),守护等待串流空闲后再处理;这只说明配置和当前活动屏对不上,不等于虚拟屏坏了,也不推断手机一定黑屏。10 月 11 日就是这种情况;10 月 20 日早上、10 月 22 日 07:22、10 月 30 日 11:10 和 11 月 4 日 09:10 的记录里都没有这一阻塞。
- 近 15 分钟内有 BugCheck、显示内核错误或匹配的 WER 图形故障 保持 BlockedByGpuStability,不切捕获或往虚拟屏搬窗;只有空闲且证明来自 VDD、目标是健康物理主屏的普通窗口单向回迁可独立处理。单独一次 Kernel-Power 41(非正常关机)只记诊断,不挡整次开机;WER 按类型参数和报告编号去重,虚拟驱动自检报告不算显卡崩溃;事件查询本身出错仍挡。
- 要往虚拟屏搬窗,却证明不了主屏区域 当前源码不计划新搬窗、保留已有迁移记录,捕获切换照常判断;不用虚拟屏区域冒充来源。11 月 4 日运行的守护包含此修复。
- 窗口恢复记录损坏 停在 capture-state-invalid,不自动切换、不用空白记录覆盖;核对有效的上一份记录和当前现场后再恢复。

- 单轮显示枚举瞬时失败(如驱动重置) 代码把它记为 cycle-transient-failure 并留待下一轮;自动化测试覆盖了不让该异常直接终止守护器的分支。
- 人工无头写入前 VDD 身份或原配置变化 拒绝覆盖;若已写入,仅在当前仍匹配这次写入的结果且 GPU、会话、身份门允许时回滚,未恢复项单独报告。工具本身不自动重启 Sunshine,也不把备份冒充恢复成功。
- 隐藏启动器起不来 新版把 launcher_error 记进 runtime/capture-launcher.log(UTF-16、约 1 MB 轮转)并返回 1,不再悄悄失败;日志只从新版开始有。
- 健康回执写不出去 单独记 health-publication-failure,不清除已累计的空闲时间,也不把这一轮成功的捕获结果改成失败;成功心跳不更新,持续写不出去时体检和驾驶舱看到的是心跳过期,不会把守护当成正常。

- 单轮显示枚举瞬时失败(如驱动重置) 代码把它记为 cycle-transient-failure 并留待下一轮;自动化测试覆盖了不让该异常直接终止守护器的分支。
- 人工无头写入前 VDD 身份或原配置变化 拒绝覆盖;若已写入,仅在当前仍匹配这次写入的结果且 GPU、会话、身份门允许时回滚,未恢复项单独报告。工具本身不自动重启 Sunshine,也不把备份冒充恢复成功。
- 隐藏启动器起不来 新版把 launcher_error 记进 runtime/capture-launcher.log(UTF-16、约 1 MB 轮转)并返回 1,不再悄悄失败;日志只从新版开始有。
- 健康回执写不出去 单独记 health-publication-failure,不清除已累计的空闲时间,也不把这一轮成功的捕获结果改成失败;成功心跳不更新,持续写不出去时体检和驾驶舱看到的是心跳过期,不会把守护当成正常。

- 9 月 18 日 14:07 有原始回执:当时 67/67 通过(涵盖设备快照、GUID 绑定、去抖、CAS 写入、BugCheck/WER/GPU 事件门和窗口计划);现定义 78 个(11 月 4 日 09:18 静态计数),没有运行。它们是合成分支,不是物理串流。
- 11 月 4 日 11:40 零写入体检(历史):attention(worker-source-bundle-not-current),ConfiguredTargetOnline=true、BlockedReason 为空、Action=StayVdd、ClientAcceptance=unknown;它只说明当时运行程序落后于源码,没有看客户端画面。
- 11 月 6 日 13:58:58 零写入体检:host-observed-healthy,Reasons 为空,Worker.Fresh=true、SourceCurrent=true,ConfiguredTargetOnline=true、BlockedReason 为空、Action=StayVdd、ClientAcceptance=unknown;它只证明主机观察,没有看客户端画面,也不是一次换屏验收。
- 11 月 4 日 09:12 只读核对音频源地址修补(native-patches/source-address-ready.json,docs/native-source-address-ready.md):音频 UDP PING 可能先到,旧源码此时开始采集,媒体发送可能读到默认 0.0.0.0 源地址;修补让音视频先等本会话源地址就绪,沿原握手绝对期限等待并支持停止取消,不改显示、音频配置、路由或防火墙。这份清单写明 full_sunshine_build_passed=false、deployed=false、original_sunshine_trigger_passed=false,其中构建这一项是后来那次构建之前的记录,没有再改。后来提交的 docs/native-source-address-ready.md(e466c8a,11 月 5 日 01:39)记明:11 月 4 日完整构建过一次、从未运行,成品和构建缓存已删;本人 11 月 5 日决定继续用官方版、不部署修补,只在串流空闲时真实画面切不过来或“串流画面切换”任务再报错时重新评估;真实客户端初始化和原换屏回归都没有通过。隔离 C++ 回归有记录,核对时没有复跑。历史初始化错误与此缺陷高度吻合,但缺原失败调用参数,不能写成已找到全部历史发送错误根因或已修好。
- 10 月 30 日 11:10:14 守护回执:ConfiguredTargetOnline=true、BlockedReason=null、Action=StayVdd、ClientAcceptance=unknown;它是守护自己的周期记录,不是体检,也不看客户端画面。10 月 20 日 07:38:27、10 月 22 日 07:22:22 回执结论相同,留作历史。历史:10 月 11 日 13:33 截止前体检:blocked,配置要抓的屏不在线或认不唯一(ConfiguredTargetOnline=false),捕获模式和待切目标都是虚拟屏;体检按配置的输出编号在活动屏里严格匹配,它没有看客户端画面,也不能证明虚拟屏驱动坏了。客户端画面和输入未知。
- 历史记录:2026年9月4日曾发现 output_name 与活动输出不匹配,并被当次 GPU 稳定门阻断;9 月 18 日那次开机又因显卡故障记录停止切换。这些是带日期的旧情况,现在的显卡门只看近 15 分钟,10 月 11 日显卡这关是放行的。
- 窗口恢复状态 9 月 14 日的记录(Mode=Vdd、PendingTargetKind=Physical)保留为历史;10 月 11 日 13:33 体检时为 Mode=Vdd、PendingTargetKind=Vdd;10 月 20 日 07:35:51 更新的状态仍为 Mode=Vdd。状态里记的上次目标不能代替配置里当前要抓的屏,状态新鲜也不证明捕获选择或窗口迁移已通过。
- 系统计划任务 SunshineCaptureFailover-Interactive 随 10 月 10 日 11:06 登录启动并常驻;10 月 11 日 13:33 体检时守护心跳新鲜、源码一致;10 月 20 日 07:38 守护回执的四个组件 SHA-256 当时与源码一致;10 月 22 日 07:22 读到当时运行中的守护(10 月 20 日 22:16 启动)脚本指纹 2EA6698B… 与当时源码 967F366D… 不一致,那时 c09364f、6cfbfde 两项修复还没加载;10 月 30 日 11:10 读到的守护 10 月 26 日 10:30 启动,四个组件 SHA-256 当时与源码逐项相等,这两项和 8de3dcf 当时都已加载;11 月 4 日读到的任务上次启动 11 月 3 日 16:01:18(状态码 267009 表示仍在运行),守护主脚本和 sunshine-safety.psm1 当时落后于源码,另两项相同;11 月 6 日 05:29 读到任务上次启动 11 月 6 日 01:21:26(状态码 267009 表示仍在运行),SourceCurrent=true,已和源码一致。
为整个远程串流系统提供坚固的显示可用性基石;与 VDD 独立显示参数管理及传输层紧密协作。

- 9 月 18 日 14:07 有原始回执:当时 67/67 通过(涵盖设备快照、GUID 绑定、去抖、CAS 写入、BugCheck/WER/GPU 事件门和窗口计划);现定义 78 个(11 月 4 日 09:18 静态计数),没有运行。它们是合成分支,不是物理串流。
- 11 月 4 日 11:40 零写入体检(历史):attention(worker-source-bundle-not-current),ConfiguredTargetOnline=true、BlockedReason 为空、Action=StayVdd、ClientAcceptance=unknown;它只说明当时运行程序落后于源码,没有看客户端画面。
- 11 月 6 日 13:58:58 零写入体检:host-observed-healthy,Reasons 为空,Worker.Fresh=true、SourceCurrent=true,ConfiguredTargetOnline=true、BlockedReason 为空、Action=StayVdd、ClientAcceptance=unknown;它只证明主机观察,没有看客户端画面,也不是一次换屏验收。
- 11 月 4 日 09:12 只读核对音频源地址修补(native-patches/source-address-ready.json,docs/native-source-address-ready.md):音频 UDP PING 可能先到,旧源码此时开始采集,媒体发送可能读到默认 0.0.0.0 源地址;修补让音视频先等本会话源地址就绪,沿原握手绝对期限等待并支持停止取消,不改显示、音频配置、路由或防火墙。这份清单写明 full_sunshine_build_passed=false、deployed=false、original_sunshine_trigger_passed=false,其中构建这一项是后来那次构建之前的记录,没有再改。后来提交的 docs/native-source-address-ready.md(e466c8a,11 月 5 日 01:39)记明:11 月 4 日完整构建过一次、从未运行,成品和构建缓存已删;本人 11 月 5 日决定继续用官方版、不部署修补,只在串流空闲时真实画面切不过来或“串流画面切换”任务再报错时重新评估;真实客户端初始化和原换屏回归都没有通过。隔离 C++ 回归有记录,核对时没有复跑。历史初始化错误与此缺陷高度吻合,但缺原失败调用参数,不能写成已找到全部历史发送错误根因或已修好。
- 10 月 30 日 11:10:14 守护回执:ConfiguredTargetOnline=true、BlockedReason=null、Action=StayVdd、ClientAcceptance=unknown;它是守护自己的周期记录,不是体检,也不看客户端画面。10 月 20 日 07:38:27、10 月 22 日 07:22:22 回执结论相同,留作历史。历史:10 月 11 日 13:33 截止前体检:blocked,配置要抓的屏不在线或认不唯一(ConfiguredTargetOnline=false),捕获模式和待切目标都是虚拟屏;体检按配置的输出编号在活动屏里严格匹配,它没有看客户端画面,也不能证明虚拟屏驱动坏了。客户端画面和输入未知。
- 历史记录:2026年9月4日曾发现 output_name 与活动输出不匹配,并被当次 GPU 稳定门阻断;9 月 18 日那次开机又因显卡故障记录停止切换。这些是带日期的旧情况,现在的显卡门只看近 15 分钟,10 月 11 日显卡这关是放行的。
- 窗口恢复状态 9 月 14 日的记录(Mode=Vdd、PendingTargetKind=Physical)保留为历史;10 月 11 日 13:33 体检时为 Mode=Vdd、PendingTargetKind=Vdd;10 月 20 日 07:35:51 更新的状态仍为 Mode=Vdd。状态里记的上次目标不能代替配置里当前要抓的屏,状态新鲜也不证明捕获选择或窗口迁移已通过。
- 系统计划任务 SunshineCaptureFailover-Interactive 随 10 月 10 日 11:06 登录启动并常驻;10 月 11 日 13:33 体检时守护心跳新鲜、源码一致;10 月 20 日 07:38 守护回执的四个组件 SHA-256 当时与源码一致;10 月 22 日 07:22 读到当时运行中的守护(10 月 20 日 22:16 启动)脚本指纹 2EA6698B… 与当时源码 967F366D… 不一致,那时 c09364f、6cfbfde 两项修复还没加载;10 月 30 日 11:10 读到的守护 10 月 26 日 10:30 启动,四个组件 SHA-256 当时与源码逐项相等,这两项和 8de3dcf 当时都已加载;11 月 4 日读到的任务上次启动 11 月 3 日 16:01:18(状态码 267009 表示仍在运行),守护主脚本和 sunshine-safety.psm1 当时落后于源码,另两项相同;11 月 6 日 05:29 读到任务上次启动 11 月 6 日 01:21:26(状态码 267009 表示仍在运行),SourceCurrent=true,已和源码一致。
为整个远程串流系统提供坚固的显示可用性基石;与 VDD 独立显示参数管理及传输层紧密协作。
复制 AI 续作说明
项目:物理主屏优先,唯一 MTT1337 VDD(虚拟显示器)兜底并守护应用窗口;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。







