Pwsh

Overview

以“先兼容、后增强”为原则生成 PowerShell 命令。默认先满足 pwsh5 可运行，再按需启用 pwsh7 专属能力。

Workflow

1. 确认目标解释器：先读取 $PSVersionTable.PSVersion，判断是 5.1 还是 7.x。
2. 选兼容级别：默认按 pwsh5 语法生成；仅在确认 7.x 时使用 7 专属语法。
3. 组装参数：优先用变量或数组传参，避免在命令行内堆叠转义。
4. 处理原生命令：当参数被误解析时，先改写引号；必要时使用 --% 或 pwsh7 参数传递设置。
5. 输出结果：明确命令、兼容前提、以及可能影响行为的版本差异。

Baseline Rules

• 将 pwsh5 视为最低兼容基线。
• 在 PowerShell 中向 --jq 或类似参数传入含 | 的表达式时，必须使用单引号字符串。
• 需要变量拼接时，先构造变量再传参，不在命令行直接拼复杂引号。
• 文件读写显式指定编码，避免依赖不同版本默认值。

pwsh7 Adaptation

• 仅在确认 PowerShell 7.3+ 时考虑 $PSNativeCommandArgumentPassing 影响。
• 旧脚本因参数传递行为变化失败时，按需临时切换 Legacy，任务完成后恢复原值。
• 使用 pwsh7 专属语法（如 ??、||、&&、ForEach-Object -Parallel）前先做版本判断。

Failure Handling

1. 出现 | 被吃掉：检查表达式是否被单引号包裹。
2. 原生命令参数异常：先改为变量传参，再评估 --% 或 $PSNativeCommandArgumentPassing。
3. 跨版本结果不同：回显版本号与关键变量值后，再给出兼容改写命令。

Output Format

1. Plan: 要解决的 PowerShell 兼容问题。
2. Commands: 可直接执行的命令（必要时分 5.1 与 7.x 两套）。
3. Result: 关键输出与版本信息。
4. Compat: 是否依赖 pwsh7 特性，及回退方案。

Reference

按需加载，不要一次性读取全部细节：

• 通用兼容基线：references/pwsh5-baseline.md
• --jq 与引号规则：references/quoting-jq.md
• pwsh7 增量适配：references/pwsh7-adaptation.md