StellarX-kaifa/开发记录/BUG/BUG-20261005-0001-WindowsPowerShell5无法解析UI测试脚本.md

BUG-20261005-0001

适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。

基本信息

• ID: BUG-20261005-0001
• 标题: Windows PowerShell 5.1 无法解析 UI 测试脚本
• 状态：已验证
• 严重性：S3
• 优先级：P1
• 模块: 自动化测试 / PowerShell / UI 回归
• 版本 / 分支: master，发现基线 3d08bac
• 环境: Windows PowerShell 5.1 / 系统活动代码页 CP936
• 发现人: Codex 提交前兼容性复验
• 关联 Fix ID: Fix-BUG-20261005-0001

问题描述

• 现象: 使用 powershell.exe 启动 scripts/run-ui-tests.ps1 时，解析器把 Add-Type 的 C# here-string 内容当成 PowerShell 语句，连续报告 Missing using directive、Unexpected attribute 'StructLayout' 等错误。
• 影响范围: Windows PowerShell 5.1 下不能直接运行 UI 测试脚本；经 scripts/test.ps1 进入的 UI、Render 和 All 套件同样受影响。
• 期望结果: Windows PowerShell 5.1 与 PowerShell 7 都能解析并执行同一份 UI 测试脚本。
• 实际结果: PowerShell 7 可正常执行，Windows PowerShell 5.1 在脚本解析阶段终止，尚未进入 UI fixture。

复现信息

• 前置条件: scripts/run-ui-tests.ps1 以 UTF-8 无 BOM 保存，文件中包含中文注释和 Add-Type @' ... '@ C# here-string。
• 复现步骤:

1. 在仓库根目录运行 powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-ui-tests.ps1 -Repeat 0。
2. 观察解析器在 C# using 与 StructLayout 行报错。
3. 检查文件首字节为 23 20 E5 A4，确认缺少 UTF-8 BOM EF BB BF。

• 复现概率：必现
• 最小复现 Demo：powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-ui-tests.ps1 -Repeat 0
• 证据：Windows PowerShell 5.1 解析错误输出；修复前文件首字节检查。

初步分析

• 疑似位置: scripts/run-ui-tests.ps1 文件编码。
• 触发条件: Windows PowerShell 5.1 按系统 ANSI 代码页解释 UTF-8 无 BOM 脚本，中文字节流干扰后续 here-string 解析。
• 相关线索:
  • scripts/test.ps1 已使用 UTF-8 BOM，并在 Windows PowerShell 5.1 下通过完整 NonUI 验证。
  • 开发记录/TESTING.md 已明确记录测试入口脚本的 BOM 兼容性要求，但此前只覆盖 test.ps1。
• 最近相关改动: c0eca1d 扩展了 run-ui-tests.ps1 的原生关闭回归，但该问题本质是脚本既有编码与 Windows PowerShell 5.1 的兼容边界。

跟踪信息

• 首次发现时间: 2026-10-05
• 最后更新时间: 2026-10-05
• 修复版本: 本次修复提交
• 验证版本: Windows PowerShell 5.1 完整 UI 回归 1 轮通过；PowerShell 7 AST 解析零错误
• 备注: 修复只应增加 UTF-8 BOM，不改动 UI 测试逻辑、参数或场景。