用途：指导在 Windows 上安全地编写和运行 PowerShell，尤其是调用原生程序、处理带引号的路径、转义、pwsh、Start-Process、文件操作与 shell 交互等易错场景。
主要能力与要点：
- 版本区分：优先使用 PowerShell 7（pwsh.exe），除非明确需要 Windows PowerShell 5.1。注意 pwsh.exe 是 PowerShell 7，powershell.exe 是 5.1，安装 7 不会改变 powershell.exe。可用 $PSVersionTable.PSVersion 和 $PSNativeCommandArgumentPassing 确认当前环境。
- 原生程序调用：不要把参数拼成一个大命令字符串，应把每个参数作为数组项，用 & $exe @argList 调用，并立即捕获 $LASTEXITCODE 检查退出码。避免使用 $args 作为自定义参数数组名（它是自动变量），改用 $argList 或 $nativeArgs。不要用 Invoke-Expression，不要为启动可执行文件额外加 cmd.exe /c，不要用 Bash 风格的反斜杠转义。
- Cmdlet 调用：使用哈希表 splatting；对具体路径优先用 -LiteralPath；仅暴露 -Path 的 cmdlet（如 New-Item）用 -Path，不确定时用 Get-Command <cmdlet> -Syntax 查看。不要用 $LASTEXITCODE 判断 cmdlet 成败，应使用终止性错误（如 $ErrorActionPreference = 'Stop'）。参数值中的表达式需加括号或先赋值。
- 复杂命令：避免深层嵌套引号（如 cmd.exe /c pwsh.exe -Command "..."）。多行代码、嵌套引号、JSON、XML、正则、管道、重定向或非 ASCII 路径时，写入临时 .ps1 文件并用 pwsh.exe -NoLogo -NoProfile -NonInteractive -File script.ps1 执行。除非执行策略确实阻止可信脚本，否则不要加 -ExecutionPolicy Bypass。从外层 PowerShell 通过 -Command 传脚本时，外层会先展开 $变量，需用外层单引号字符串。
- 字符串与多行：字面字符串和路径用单引号，需要展开时才用双引号；避免反引号续行，改用数组、哈希表、splatting、括号或脚本块；不要用 Bash heredoc；JSON 用 ConvertTo-Json 生成，不要手工转义；字面多行文本用单引号 here-string。
- 编码：PowerShell 7 文本输出默认 UTF-8 无 BOM，5.1 因 cmdlet 而异。新文本文件按下游工具要求显式指定编码；修改已有文件前先识别并保留原编码，不要静默转换 GBK、UTF-16 或对 BOM 敏感的文件。默认不要设置 Console.InputEncoding/OutputEncoding，仅在确认终端或原生程序编码不匹配时设置；$OutputEncoding 控制发给原生程序的文本。二进制文件不要套用文本编码选项，应使用字节 API。
- Start-Process：普通前台执行用 & $exe @argList；仅在需要提权、新窗口/隐藏窗口、分离启动或 shell 行为时用 Start-Process。其 -ArgumentList 会把值拼成命令行字符串，不是可靠的结构化参数 API；参数边界重要时优先用 ProcessStartInfo.ArgumentList。
- 文件操作：递归删除、移动或覆盖前，解析绝对根路径与目标路径，确认目标位于预期根内，拒绝空路径、根级路径或意外路径；文件系统修改尽量留在 PowerShell 内完成。映射驱动器按用户/会话区分，自动化账户下 Test-Path 失败时可检查 whoami 与 Get-PSDrive，或向用户索取 UNC 路径。
- 版本与模块差异：5.1 与 7 可能同名命令参数不同，使用前用 Get-Command <cmdlet> -Syntax 验证。例如 Format-Hex -Count 仅 PowerShell 7 支持，5.1 可用管道 Select-Object -First 2 替代。命令发现异常时检查 $env:PSModulePath 与 Get-Module -ListAvailable。
决策顺序：优先 PowerShell cmdlet，其次 & $exe @argList，再是临时 .ps1 文件配合 pwsh.exe -File，然后 ProcessStartInfo.ArgumentList，需要特殊行为时才用 Start-Process，仅在需要 cmd 语义时用 cmd.exe /c，Invoke-Expression 仅作严格受控的最后手段。
限制：资料未提供具体安装命令、收费信息或平台支持范围；更多罕见情况与完整示例需查阅其 reference.md。