用途与实际影响
这项功能怎样使用
为什么需要它
公开源码能下载，不等于这台电脑已接上两块屏。厂商程序、串口、网卡、天气位置和显示器身份要在本机合法取得并重新确认；照搬旧编号可能把画面送错。
举个实际例子
我说“这台新电脑也要用上两块副屏”。安装过程会重新识别当前串口、网卡、天气位置和显示器，不照抄旧机器编号；最后我会亲眼看到机箱屏在更新、水冷屏落在正确位置，确认后它们才随登录自动启动。
最后我会得到什么
得到在这台电脑上安装的两块副屏和自动启动设置；源码、程序运行、机箱屏实体更新、水冷屏实际落点分别验收，缺一项只说明缺一项。
正常时
厂商文件、私有配置和两块真实设备都确认后，安装启动任务，再分别看两块实体屏。
发现问题时
端口、显示器或旧绑定不对时停在那一层修正，不靠整机重启碰运气。
入口不可用或证据不足时
合法厂商文件或唯一设备身份缺失时不能完成本机安装；软件演示仍只算演示。
从哪里开始
在已接入项目的本机 AI 对话中说要在这台新电脑安装双副屏，并准备合法取得的厂商程序和两块实体设备。
需要准备什么
- 本机串口、物理网口和天气位置
- 合法取得的厂商运行文件
- HS2 显示器和背景选择
从开始到拿到结果
- 1
从干净源码准备
补齐厂商文件，把示例配置复制为本机私有配置，重新发现端口和显示器。
- 2
先查环境再安装
runtime（运行环境） check 有缺项就停；确认设备身份、渲染发送和 HS2 唯一落点后才装登录任务。
- 3
本人看两块实体屏
分别确认机箱屏更新和 HS2 背景与浮层位置，再验证自然登录启动；旧机器编号不当新机事实。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
9月7日公开ZIP和本机既有任务重新启动已验证；clean clone（干净克隆）、换机、系统重装和新硬件双屏验收仍未执行关键规则与设计选择
clean clone 只带公开源码、文档、脚本、测试和无真实值示例；厂商 EXE/DLL、私有 JSON、out/bin/obj、日志和设备绑定不属于 Git 交付。
RJCP.SerialPortStream.dll 与 TURZX.exe 或 TURZX.weatherfix.metrics.exe 必须由安装者从有权使用的来源取得，并放在仓库根；项目不代为分发。
config.example.json 只能作为模板；复制成 ignored（已被版本控制忽略） config.json 后再填写当前 serial.port、network.publicInterface 与 weather 经纬度，换机不沿用旧值。
check-runtime 只读检查 Python、按需 psutil/asyncpg、csc.exe、RJCP、TURZX 运行文件和 StartSideScreenStack；任一必需项缺失时安装器拒绝注册任务。
TURZX 绑定当前真实串口并在实机写入前确认唯一健康设备；COM7 只是本机默认，不是迁移常量。
HS2 重新发现唯一健康 8091 Hub、port 2 控制器、port 3 LED、AD23 与 MI_00 显示接口；只有连续两次健康才保存新的 ignored（已被版本控制忽略） 拓扑绑定并启用浮层。
启动任务属于当前交互用户，以 Highest 在登录时由 wscript 无窗口启动唯一长期 watchdog；旧 stock 任务被禁用而非删除，旧 Resume Owner 不得与新 watchdog 并存。
验收顺序固定为源码/公开包、runtime（运行环境） check、配置与绑定、任务/进程/heartbeat、TURZX 实体像素、HS2 实体背景与浮层、睡眠恢复和异常断电后的自然启动；前一层不能替后一层。
本模块用到的名词
- source package（源码包）
- 能公开克隆、构建和检查的代码/文档集合，不包含一台机器的可执行依赖、配置、绑定或运行输出。
- private config（私有配置）
- 由 config.example.json 派生、被 Git 忽略的当前机串口、物理网卡和天气等值；可备份但不能公开提交。
- machine binding（机器绑定）
- 当前电脑上 TURZX 串口与 HS2 Hub/controller/LED/display 的实际身份关系；换机或重接后必须重新发现。
- runtime gate（运行依赖门）
- check-runtime 返回 ready 前不允许安装启动任务，避免把缺依赖的路径变成开机故障。
- layered acceptance（分层验收）
- 源码、测试、安装、进程/heartbeat、实体像素、睡眠恢复和自然启动分别给结论，不能互相替代。
专业定义
把 clean clone（干净克隆）、合法取得的厂商运行文件、每台机器自己的串口/物理网卡/天气配置和双屏绑定按顺序组装；依赖未齐时不装启动任务，主机通过后仍单独看实体像素。
解决什么
解决公开源码缺少本机私有运行态、换机误复制硬件身份、厂商文件误入 Git、依赖未齐先装任务、旧路径残留、双屏只验进程不验像素，以及安装失败后没有清晰回退的问题。
当前怎样实现
- build-release.ps1 从源码构建 ZIP，只纳入 README、AGENTS、LICENSE、docs、scripts 与三套 tool source；测试会解包核对 HS2 源码和公开清单。
- 发布规则只允许 tools/turzx_side_screen/config.example.json 这一份配置示例；真实 config.json、weather local JSON、out、bin、obj、AppPackages、厂商 EXE/DLL 和生成预览全部排除。
- config.json 保存当前机 serial、480×1920 刷新、loopback metrics、天气、时区、物理公网接口与 UI 选项；天气也可从显式私有路径或成对环境变量注入，未填坐标时失败关闭。
- check-runtime.ps1 发现合适 Python 与 C# 编译器，核对 RJCP/TURZX 文件和 stack 入口，并返回 ready/missing；TimeAudit 凭据存在时才要求 Python 同时具备 psutil 与 asyncpg。
- StartSideScreenWatchdog.ps1 在 ignored（已被版本控制忽略） out 中维护 hs2-usb-topology-binding.json；新机器或改线后由健康拓扑生成，旧绑定不作为跨机事实。
- install-startup-admin.ps1 先调用 runtime（运行环境） check，再把已解析 Root、Port、Interval 与 Hybrid 模式写进计划任务动作；wscript 父适配器保持无窗口长期运行。
- uninstall-startup-admin.ps1 可移除主任务与旧 Resume task；安装器只禁用旧 stock 任务而不删除，Hybrid 不兼容时另有显式 command-200 三秒兼容模式。
- 验收记录把当前主机运行证据和新机/重装 E2E（端到端验证） 分开；没有摄像头或设备 ACK 时，以人工观察两块实体屏和自然启动作为最后一层。
执行流程
- 1
从 PUBLIC（公开） main 或公开源码 ZIP 建立 clean clone。
- 2
从合法来源把 RJCP 串口库与 TURZX 运行程序放到仓库根。
- 3
复制 config.example.json 为 ignored（已被版本控制忽略） config.json，填写当前串口、物理公网接口和天气；不改公开模板。
- 4
运行 check-runtime，缺项时停止且不注册启动任务。
- 5
确认 TURZX 当前实际串口与唯一设备身份，再做主机侧渲染/发送检查。
- 6
让 HS2 进入当前可用模式，核对唯一 8091、port 2 controller、port 3 LED、AD23/MI_00 与非主 2288×1048 显示器；连续两次健康后保存绑定。
- 7
在 HS2 目标显示器选择 Wallpaper Engine 背景或 Windows 静态背景；浮层本身不复制或修改壁纸资产。
- 8
以管理员 PowerShell 安装当前交互用户的登录任务，并回读任务动作、Root、Highest 与唯一 watchdog。
- 9
检查 runtime（运行环境）、唯一进程、heartbeat、HS2 落点和公开安全边界。
- 10
分别观察 TURZX 实体时钟/像素、HS2 背景/透明浮层，再按需要验睡眠恢复与异常断电后的自然启动。
边界
- 厂商 TURZX 程序、RJCP 二进制和 Wallpaper Engine 场景必须从安装者有权使用的来源取得；PUBLIC（公开） 仓库与源码 ZIP 不重新分发。
- config.json、天气坐标、物理网卡名、TIMEAUDIT 凭据、设备拓扑绑定、日志和生成输出保持在 Git 外；公开示例继续为空值。
- 旧机器的 COM7、DISPLAY 编号、8091/AD23/LED 实例号和任务 Root 都不是新机器事实；迁移必须重新发现并回读。
- 内部 USB 排针改线属于实体操作，必须关机并断开整机电源；安装页面不会把源码接线说明写成已完成实测。
- 安装启动任务需要管理员 PowerShell，会改变当前用户的 Task Scheduler；网站刷新和本模块证据采集保持只读。
- 当前主机健康、公开 ZIP 回归或 source contract 都不能证明另一台机器、重装系统、睡眠或异常断电后的真实 E2E（端到端验证）。
失败与恢复
- Python、csc、RJCP、TURZX 运行文件或 stack 入口缺失
- check-runtime 返回具体 missing 且非零退出；安装器立即停止，不留下半注册启动任务。
- 私有串口、物理网卡或天气值仍是旧机器内容
- 保留公开示例不动，在 ignored（已被版本控制忽略） config.json 中重新发现并填写；天气坐标缺失时 shim（受保护入口垫片） 失败关闭，不回落作者位置。
- TURZX 串口不唯一或旧 writer 仍占用
- 不启动第二个 writer，不把 COM7 当常量；先确认当前设备身份和旧 Owner 退出。
- HS2 绑定缺失、歧义或只出现 A108 Boot ROM
- 不复制旧绑定、不发送模式命令；等待唯一完整拓扑，并在 AD23/MI_00 与 LED 连续两次健康后再保存。
- 启动任务 Root、参数或安装结果错误
- 运行 uninstall-startup-admin.ps1 撤销本项目任务，修正路径/配置并重新通过 runtime（运行环境） check 后再安装；不并行启用旧 Resume Owner。
- 1 Hz Hybrid 在目标 TURZX 上不兼容
- 显式使用 `-HybridRefresh:$false` 回到已验证 command 200 三秒兼容模式；不把自动降频当修复成功。
- 主机检查通过但实体画面未更新
- 把问题留在实体/设备层，不升级 PASS；观察真实 TURZX 时钟和 HS2 背景/浮层，必要时交给串口或电源恢复模块。
真实入口
E:\Projects\Tools\TURZX-SideScreen\README.mdclean clone、本机配置、厂商运行文件、启动任务与实体验收总入口
E:\Projects\Tools\TURZX-SideScreen\docs\release.md公开源码包包含/排除与合法本地 runtime（运行环境） 边界
E:\Projects\Tools\TURZX-SideScreen\tools\turzx_side_screen\config.example.json无真实值的 serial/network/weather 安装模板
E:\Projects\Tools\TURZX-SideScreen\scripts\check-runtime.ps1Python、csc、RJCP、TURZX 与 stack 的只读 ready/missing 门
E:\Projects\Tools\TURZX-SideScreen\scripts\install-startup-admin.ps1Highest 登录任务、Root/Port/Hybrid 参数与旧任务收口
E:\Projects\Tools\TURZX-SideScreen\scripts\uninstall-startup-admin.ps1启动任务撤销与重装前回退入口
E:\Projects\Tools\TURZX-SideScreen\docs\startup.md双屏启动、HS2 绑定、任务动作、模式回退与分层验收合同
E:\Projects\Tools\TURZX-SideScreen\tools\turzx_side_screen\HS2ActiveRecoveryPolicy.ps1唯一 8091/AD23/MI_00/LED 拓扑发现、读取与原子绑定规则
E:\Projects\Tools\TURZX-SideScreen\scripts\test-public-release.ps1fresh ZIP 解包、缺厂商 runtime（运行环境） 失败和私有/二进制排除回归
如何验证
- 8 月 31 日 2026-08-31 旧验收记录：PUBLIC（公开） main=8c217eadf76e6849c382c909b407d9dc436f9005，本地 HEAD、origin/main 与实时远端 main 当时一致且源工作树干净；该次公开发布测试构建并解包 ZIP，确认 config.example、双屏源码和安装脚本存在，厂商二进制、本机 JSON 与生成目录不存在。
- 9月7日现有主机依赖ready、missing=0；既有TURZX任务已重新启动，新隐藏入口的异常退出恢复实际执行，唯一stream与新鲜Hybrid心跳存在。a4d8e22公开ZIP构建并解包通过；这些只证明现有机器与源码包。
- 当前源码的 runtime（运行环境） checker 回归同时验证：缺 RJCP/TURZX 时失败，补齐要求的 runtime（运行环境） 与 stack 后才 ready；安装器自身也会在注册任务前调用该门。
- 本轮没有在clean clone、另一台电脑或重装后的Windows上重建private（私有） config、重新绑定两块屏、安装任务并完成自然启动。本机TURZX刷新已有9月7日本人确认；换机、HS2当前实体画面、睡眠和异常断电仍未验收。
与其他模块的关系
本模块把公开源码变成当前机器可运行的前置安装态，为指标、渲染、串口和 HS2 浮层提供私有配置与双屏绑定；安装完成后的睡眠、冻结、端点消失和运行期自愈仍由电源恢复模块负责。